feat(notifications): document the required provider integration id on campaigns and triggers

The gateway now requires the provider integrationId when an Email, Push or
SMS campaign is created (Email/Push: campaign.integrationId; SMS: a new
top-level integrationId, distinct from databaseIntegrationId) and on every
trigger action, which also takes the optional language and initiatorId.
The SDK methods pass the request through, so no signature changes; the
README and the SMS / Push pages now show the id, and tests pin that it
reaches the wire for each case.

Breaking: the server now requires the provider integration id. Calls that
create a campaign or save a trigger without integrationId are refused;
pass the id from get_email_integrations / get_push_integrations /
get_sms_integrations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: Domantas

README.md

@@ -169,6 +169,44 @@ user key: `create_ai_service_user`, `list_ai_service_users`,
 Full tables and an MCP example: [docs/hub/account.md](./docs/hub/account.md),
 [docs/api/public.md](./docs/api/public.md).
 
+## Campaigns and triggers: the provider integration id
+
+The server now **requires the provider integration id** when you create an
+Email, Push or SMS campaign, and on every trigger action. Pick it from
+`get_email_integrations` / `get_push_integrations` / `get_sms_integrations`.
+Email and Push put it inside `campaign`; SMS sends it at the top level, next to
+(and different from) `databaseIntegrationId`:
+
+```python
+norbix.hub.notifications.create_email_campaign(
+    campaign={"templateId": "tpl_123", "integrationId": "int_email", "source": "allUsers"}
+)
+norbix.hub.notifications.create_push_campaign(
+    campaign={"source": "allUsers", "templateId": "tpl_456", "integrationId": "int_push"}
+)
+norbix.hub.notifications.create_sms_campaign(
+    templateId="tpl_789",
+    integrationId="int_sms",
+    deliveryType="PhoneNumbers",
+    phoneNumbers={"recipientsSourceType": "PhoneNumbers", "phoneNumbers": ["+37060000000"]},
+)
+```
+
+A trigger action (`save_schema_trigger`, `save_files_trigger`,
+`save_membership_trigger`, `save_payments_trigger`) takes the same required
+`integrationId`, plus the optional `language` (template language) and
+`initiatorId` (who the send is attributed to) on Email, Push and SMS actions.
+Two related calls:
+
+- `norbix.hub.triggers.get_triggers_needing_attention(triggerType="Schema")` —
+  triggers that need a fix (for example, their provider is gone); `{"items": [...]}`.
+- `norbix.hub.account.check_project_languages(project_id, languages=["en", "de"])` —
+  a dry run before `update_project_languages`: which templates miss a language;
+  `{"templates": [...]}`. Account scope.
+
+Details: [docs/hub/triggers.md](./docs/hub/triggers.md),
+[docs/hub/sms.md](./docs/hub/sms.md), [docs/hub/push.md](./docs/hub/push.md).
+
 ## Errors
 
 ```python
@@ -365,6 +403,10 @@ uv run python scripts/generate_endpoints.py
 
 This refreshes `src/norbix_python/api/`, `hub/`, matching tests under `tests/api` and `tests/hub`, and docs under `docs/`.
 
+Some methods are **hand-written** and marked `HAND-WRITTEN` in the source
+(`hub/triggers.py`, its registration in `hub/__init__.py`, and
+`account.check_project_languages`). Keep them when you regenerate.
+
 ## Development
 
 ```bash

docs/hub/push.md

@@ -21,8 +21,9 @@ field plus the audience's own fields:
 | rows of a database collection | `collection` | `schemaName`, `fields` (the record fields that hold the recipient), `fieldType` (`User` or `Email`), optional `roleNames`, `languages` |
 | raw device tokens | `devices` | `devices`: a list of `{ token, deliveryFamily }`, `deliveryFamily` one of `Ios`, `Android`, `Chrome`, `Safari`, `Expo` |
 
-Every target also takes `templateId` (required) and the optional `integrationId`,
-`language`, `notes`, `campaignTime` (Unix seconds) and `mappedTokens`. Note the
+Every target also takes `templateId` and `integrationId` (both required —
+`integrationId` is the push provider, from `get_push_integrations`), and the
+optional `language`, `notes`, `campaignTime` (Unix seconds) and `mappedTokens`. Note the
 spelling: `rolesNames` on `allUsers`, but `roleNames` on `collection` — the
 gateway names them differently.
 
@@ -31,6 +32,7 @@ client.hub.notifications.create_push_campaign(
     campaign={
         "source": "allUsers",
         "templateId": "tpl_123",
+        "integrationId": "int_push",
         "userTags": ["beta"],
     }
 )

docs/hub/sms.md

@@ -25,13 +25,17 @@ and the settings object repeats the audience name in `recipientsSourceType`:
 Every settings object also takes `campaignTime` (Unix seconds, UTC — set a
 future time so the campaign can be reviewed in the dashboard first), and the
 optional `mappedTokens` and `respectTimeZoneSettings`. The request itself takes
-`templateId` (required), and the optional `language` and `databaseIntegrationId`.
+`templateId` and `integrationId` (both required — `integrationId` is the SMS
+provider, from `get_sms_integrations`), and the optional `language` and
+`databaseIntegrationId` (the database behind a `Collection` audience — a
+different id from `integrationId`).
 Note the spelling: `rolesNames` on `allUsers`, but `roleNames` on `collection` —
 the gateway names them differently.
 
 ```python
 client.hub.notifications.create_sms_campaign(
     templateId="tpl_123",
+    integrationId="int_sms",
     deliveryType="PhoneNumbers",
     phoneNumbers={
         "recipientsSourceType": "PhoneNumbers",

tests/hub/test_email_routes.py

@@ -478,3 +478,20 @@ async def run() -> None:
 
     assert len(seen) == 1
     assert seen[0].headers.get("Authorization") is None
+
+
+def test_create_email_campaign_sends_the_provider_integration_id_nested() -> None:
+    # The gateway requires the email provider id inside `campaign`.
+    import json
+
+    client, transport = make_client()
+    client.hub.notifications.create_email_campaign(
+        campaign={"templateId": "tpl_1", "integrationId": "int_1", "source": "allUsers"}
+    )
+
+    assert transport.last_request is not None
+    assert transport.last_request["method"] == "POST"
+    assert urlparse(transport.last_request["url"]).path == "/v2/notifications/email/campaigns"
+    assert json.loads(transport.last_request["body"]) == {
+        "campaign": {"templateId": "tpl_1", "integrationId": "int_1", "source": "allUsers"}
+    }

tests/hub/test_push.py

@@ -270,6 +270,18 @@ def test_create_push_campaign_sends_the_target_shape(source: str, fields: dict[s
     assert campaign == {"source": source, "templateId": TEMPLATE_ID, **fields}
 
 
+def test_create_push_campaign_sends_the_provider_integration_id_nested() -> None:
+    # The gateway requires the push provider id inside `campaign`.
+    client, transport = make_client()
+    client.hub.notifications.create_push_campaign(
+        campaign={"source": "allUsers", "templateId": TEMPLATE_ID, "integrationId": "int_1"}
+    )
+
+    assert transport.last_request is not None
+    body = json.loads(transport.last_request["body"])
+    assert body == {"campaign": {"source": "allUsers", "templateId": TEMPLATE_ID, "integrationId": "int_1"}}
+
+
 def test_campaign_targets_match_the_gateway() -> None:
     assert {source.lower() for source, _ in CAMPAIGN_TARGETS} == GATEWAY_TARGETS
     assert len(CAMPAIGN_TARGETS) == len(GATEWAY_TARGETS)

tests/hub/test_sms.py

@@ -318,6 +318,32 @@ def test_campaign_audiences_match_the_gateway() -> None:
     assert len(CAMPAIGN_AUDIENCES) == len(GATEWAY_AUDIENCES)
 
 
+def test_create_sms_campaign_sends_the_provider_integration_id_top_level() -> None:
+    # The gateway requires the SMS provider id as a top-level `integrationId`.
+    # It is a different field from `databaseIntegrationId` (the database that
+    # holds a `Collection` audience), so both must reach the wire side by side.
+    client, transport = make_client()
+    client.hub.notifications.create_sms_campaign(
+        templateId=TEMPLATE_ID,
+        integrationId=INTEGRATION_ID,
+        databaseIntegrationId="db_1",
+        deliveryType="Collection",
+        collectionSettings={"schemaName": "subscribers", "fields": ["phone"], "campaignTime": CAMPAIGN_TIME},
+    )
+
+    assert transport.last_request is not None
+    assert transport.last_request["method"] == "POST"
+    assert urlparse(transport.last_request["url"]).path == f"{BASE}/campaigns"
+    body = json.loads(transport.last_request["body"])
+    assert body == {
+        "templateId": TEMPLATE_ID,
+        "integrationId": INTEGRATION_ID,
+        "databaseIntegrationId": "db_1",
+        "deliveryType": "Collection",
+        "collectionSettings": {"schemaName": "subscribers", "fields": ["phone"], "campaignTime": CAMPAIGN_TIME},
+    }
+
+
 # The eight providers the gateway's save converter accepts, with the fields
 # each one validates. Source of truth: gateway Hub.Sms/Integrations/Save_.cs
 # (the switch arms of the converter, read from `provider`) and