diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 242d5048..2a8a14d0 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "5.13.0" + ".": "5.13.1" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index e2794c72..48e48092 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 134 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-b053468fefe6d757f86f3233ebbc52d80329ed2a6e7a6740fee01e4028a4c3b9.yml -openapi_spec_hash: 416835e693de0fe19945be90a787d3f3 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-5c878919b3df530781ebcd4ab1cda83606304da75c53fe0817d4c725d5bbbe73.yml +openapi_spec_hash: dd37022222543ff064200e65e4b82f59 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7 diff --git a/CHANGELOG.md b/CHANGELOG.md index 5148519a..da97cd75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 5.13.1 (2026-07-25) + +Full Changelog: [v5.13.0...v5.13.1](https://github.com/trycourier/courier-php/compare/v5.13.0...v5.13.1) + +### Documentation + +* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-php/issues/172)) ([118ad39](https://github.com/trycourier/courier-php/commit/118ad3932b1feb9950ee303995db021ff183bc29)) +* **openapi:** rewrite operation descriptions for agents and SEO ([#174](https://github.com/trycourier/courier-php/issues/174)) ([4cadcbf](https://github.com/trycourier/courier-php/commit/4cadcbf051dd0e32c9b1427073adf33619b70cbf)) + ## 5.13.0 (2026-07-23) Full Changelog: [v5.12.0...v5.13.0](https://github.com/trycourier/courier-php/compare/v5.12.0...v5.13.0) diff --git a/src/Audiences/AudienceListMembersParams.php b/src/Audiences/AudienceListMembersParams.php index 06584259..fdb37256 100644 --- a/src/Audiences/AudienceListMembersParams.php +++ b/src/Audiences/AudienceListMembersParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get list of members of an audience. + * Returns the users currently matching an audience filter, with paging. Membership is recalculated, so results shift as profiles change. * * @see Courier\Services\AudiencesService::listMembers() * diff --git a/src/Audiences/AudienceListParams.php b/src/Audiences/AudienceListParams.php index 02da8063..898d4bdc 100644 --- a/src/Audiences/AudienceListParams.php +++ b/src/Audiences/AudienceListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get the audiences associated with the authorization token. + * Returns the audiences in the workspace with paging. Audiences are filter-based groups that recalculate as user profiles change. * * @see Courier\Services\AudiencesService::list() * diff --git a/src/Audiences/AudienceUpdateParams.php b/src/Audiences/AudienceUpdateParams.php index a4fad7e7..d1a76cc8 100644 --- a/src/Audiences/AudienceUpdateParams.php +++ b/src/Audiences/AudienceUpdateParams.php @@ -12,7 +12,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Creates or updates audience. + * Creates or replaces an audience from a filter and an AND or OR operator. Membership recalculates automatically as profiles change. * * @see Courier\Services\AudiencesService::update() * diff --git a/src/AuditEvents/AuditEventListParams.php b/src/AuditEvents/AuditEventListParams.php index dcbdccf9..7db32db4 100644 --- a/src/AuditEvents/AuditEventListParams.php +++ b/src/AuditEvents/AuditEventListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Fetch the list of audit events. + * Returns the workspace's audit event log with cursor paging. Each event records the actor, target, source, type, and timestamp of a change. * * @see Courier\Services\AuditEventsService::list() * diff --git a/src/Auth/AuthIssueTokenParams.php b/src/Auth/AuthIssueTokenParams.php index a6a70c7d..4a465dbe 100644 --- a/src/Auth/AuthIssueTokenParams.php +++ b/src/Auth/AuthIssueTokenParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Returns a new access token. + * Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply the scope and an expires_in duration, both required. * * @see Courier\Services\AuthService::issueToken() * diff --git a/src/Automations/AutomationListParams.php b/src/Automations/AutomationListParams.php index 547fff21..5a545cc4 100644 --- a/src/Automations/AutomationListParams.php +++ b/src/Automations/AutomationListParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get the list of automations. + * Lists the workspace's saved automation templates, each with its id and a cursor for paging to the next page of results. * * @see Courier\Services\AutomationsService::list() * diff --git a/src/Automations/Invoke/InvokeInvokeAdHocParams.php b/src/Automations/Invoke/InvokeInvokeAdHocParams.php index 7cff56c0..aedff762 100644 --- a/src/Automations/Invoke/InvokeInvokeAdHocParams.php +++ b/src/Automations/Invoke/InvokeInvokeAdHocParams.php @@ -12,7 +12,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a series of automation steps. For information about what steps are available, checkout the ad hoc automation guide [here](https://www.courier.com/docs/automations/steps/). + * Runs a series of automation steps supplied inline, without a saved template, and returns a runId. * * @see Courier\Services\Automations\InvokeService::invokeAdHoc() * diff --git a/src/Automations/Invoke/InvokeInvokeByTemplateParams.php b/src/Automations/Invoke/InvokeInvokeByTemplateParams.php index 17233715..8c556be4 100644 --- a/src/Automations/Invoke/InvokeInvokeByTemplateParams.php +++ b/src/Automations/Invoke/InvokeInvokeByTemplateParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Invoke an automation run from an automation template. + * Starts an automation run from a saved template for one recipient, with optional data and profile, and returns a runId. * * @see Courier\Services\Automations\InvokeService::invokeByTemplate() * diff --git a/src/Brands/BrandCreateParams.php b/src/Brands/BrandCreateParams.php index 4d242531..4edda096 100644 --- a/src/Brands/BrandCreateParams.php +++ b/src/Brands/BrandCreateParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Create a new brand. Requires `name` and `settings` (with at least `colors.primary` and `colors.secondary`). + * Creates a brand from a name and settings, including primary and secondary colors. Brands supply the logo, colors, and styling that templates render with. * * @see Courier\Services\BrandsService::create() * diff --git a/src/Brands/BrandListParams.php b/src/Brands/BrandListParams.php index d691e02a..df65baba 100644 --- a/src/Brands/BrandListParams.php +++ b/src/Brands/BrandListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get the list of brands. + * Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and published version. * * @see Courier\Services\BrandsService::list() * diff --git a/src/Brands/BrandUpdateParams.php b/src/Brands/BrandUpdateParams.php index ae5a1985..951fc999 100644 --- a/src/Brands/BrandUpdateParams.php +++ b/src/Brands/BrandUpdateParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Replace an existing brand with the supplied values. + * Replaces a brand with the values you supply, so send the complete settings and snippets rather than only the fields you want changed. * * @see Courier\Services\BrandsService::update() * diff --git a/src/Digests/Schedules/ScheduleListInstancesParams.php b/src/Digests/Schedules/ScheduleListInstancesParams.php index 1bf1267d..7775b08b 100644 --- a/src/Digests/Schedules/ScheduleListInstancesParams.php +++ b/src/Digests/Schedules/ScheduleListInstancesParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * List the digest instances for a schedule. Each instance represents the events accumulated for a single user against the schedule, and can be used to monitor digest accumulation before the digest is released. + * Returns the digest instances for a schedule, one per user, with cursor paging. Use it to see what has accumulated before a digest releases. * * @see Courier\Services\Digests\SchedulesService::listInstances() * diff --git a/src/Inbound/InboundTrackEventParams.php b/src/Inbound/InboundTrackEventParams.php index a9828988..d05afb3d 100644 --- a/src/Inbound/InboundTrackEventParams.php +++ b/src/Inbound/InboundTrackEventParams.php @@ -12,7 +12,7 @@ use Courier\Inbound\InboundTrackEventParams\Type; /** - * Courier Track Event. + * Records an inbound event that can trigger a journey. Requires an event name, a messageId you generate, a type, and a properties object. * * @see Courier\Services\InboundService::trackEvent() * diff --git a/src/Journeys/JourneyCancelParams.php b/src/Journeys/JourneyCancelParams.php index a84d6891..181cc3a9 100644 --- a/src/Journeys/JourneyCancelParams.php +++ b/src/Journeys/JourneyCancelParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Cancel journey runs. The request body must include EXACTLY ONE of `cancelation_token` (cancels every run associated with the token) or `run_id` (cancels a single tenant-scoped run). Supplying both or neither returns a `400`. A `run_id` that does not match a run for the tenant returns `404`. Cancelation is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was already `CANCELED` is left unchanged and its current status is returned. + * Cancels in-flight journey runs, either every run sharing a cancelation token or one run by id. Use it to stop a sequence when the event resolves. * * @see Courier\Services\JourneysService::cancel() * diff --git a/src/Journeys/JourneyCreateParams.php b/src/Journeys/JourneyCreateParams.php index d5d719ba..f4a972f7 100644 --- a/src/Journeys/JourneyCreateParams.php +++ b/src/Journeys/JourneyCreateParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to publish on create. Send nodes are not allowed on `POST`. The standard flow is: create the journey shell here, add notification templates with `POST /journeys/{templateId}/templates`, then wire them into the journey with `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to publish a draft after the fact. + * Creates a journey from a set of nodes, in draft state unless you pass a published state. Send nodes cannot be included until their templates exist. * * @see Courier\Services\JourneysService::create() * diff --git a/src/Journeys/JourneyInvokeParams.php b/src/Journeys/JourneyInvokeParams.php index 85023742..63ef62f3 100644 --- a/src/Journeys/JourneyInvokeParams.php +++ b/src/Journeys/JourneyInvokeParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Invoke a journey by id or alias to start a new run. The response includes a `runId` identifying the run. + * Starts a journey run for one user and returns a runId. Runs execute asynchronously, so the response arrives before any message is sent. * * @see Courier\Services\JourneysService::invoke() * diff --git a/src/Journeys/JourneyListParams.php b/src/Journeys/JourneyListParams.php index fa9156ed..09d48882 100644 --- a/src/Journeys/JourneyListParams.php +++ b/src/Journeys/JourneyListParams.php @@ -11,7 +11,7 @@ use Courier\Journeys\JourneyListParams\Version; /** - * Get the list of journeys. + * Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by cursor. * * @see Courier\Services\JourneysService::list() * diff --git a/src/Journeys/JourneyPublishParams.php b/src/Journeys/JourneyPublishParams.php index 5104acb7..b21e5d63 100644 --- a/src/Journeys/JourneyPublishParams.php +++ b/src/Journeys/JourneyPublishParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Publish the current draft as a new version. Body is optional; pass `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if the journey has no draft to publish. + * Publishes a journey's current draft as a new version, making it live for new runs. Pass a version instead to roll back to an earlier one. * * @see Courier\Services\JourneysService::publish() * diff --git a/src/Journeys/JourneyReplaceParams.php b/src/Journeys/JourneyReplaceParams.php index 8b647094..cf6b0a99 100644 --- a/src/Journeys/JourneyReplaceParams.php +++ b/src/Journeys/JourneyReplaceParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Replace the journey draft. Updates the working draft only; call `POST /journeys/{templateId}/publish` to make it live, or pass `state: "PUBLISHED"` in this request to publish immediately. Send-node `template` ids must already exist and be scoped to this journey, and node ids must not be claimed by another journey. + * Replaces a journey's working draft, leaving the published version live until you publish. Reach for this when editing a journey already running. * * @see Courier\Services\JourneysService::replace() * diff --git a/src/Journeys/Templates/TemplateArchiveParams.php b/src/Journeys/Templates/TemplateArchiveParams.php index c2ebc643..bf3a0db8 100644 --- a/src/Journeys/Templates/TemplateArchiveParams.php +++ b/src/Journeys/Templates/TemplateArchiveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Archive the journey-scoped notification template. Archived templates cannot be sent. + * Archives one journey's notification template, preventing further sends. Detach any send node referencing it beforehand. * * @see Courier\Services\Journeys\TemplatesService::archive() * diff --git a/src/Journeys/Templates/TemplateListVersionsParams.php b/src/Journeys/Templates/TemplateListVersionsParams.php index 578e743b..f1c7ab77 100644 --- a/src/Journeys/Templates/TemplateListVersionsParams.php +++ b/src/Journeys/Templates/TemplateListVersionsParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * List published versions of the journey-scoped notification template, ordered most recent first. + * Lists the published versions of a template that belongs to a journey, most recent first. Paged by cursor. * * @see Courier\Services\Journeys\TemplatesService::listVersions() * diff --git a/src/Journeys/Templates/TemplatePublishParams.php b/src/Journeys/Templates/TemplatePublishParams.php index 2fb27b01..6baeabdf 100644 --- a/src/Journeys/Templates/TemplatePublishParams.php +++ b/src/Journeys/Templates/TemplatePublishParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Publish the current draft of the journey-scoped notification template as a new version. Optionally roll back to a prior version by passing `{ "version": "vN" }`. + * Publishes a journey-scoped template's draft as a new version. Pass a version instead to roll back the template to an earlier publish. * * @see Courier\Services\Journeys\TemplatesService::publish() * diff --git a/src/Journeys/Templates/TemplateReplaceParams.php b/src/Journeys/Templates/TemplateReplaceParams.php index fc6ebe59..5887a524 100644 --- a/src/Journeys/Templates/TemplateReplaceParams.php +++ b/src/Journeys/Templates/TemplateReplaceParams.php @@ -12,7 +12,7 @@ use Courier\Journeys\Templates\TemplateReplaceParams\Notification; /** - * Replace the journey-scoped notification template draft. + * Replaces the draft content of one journey's notification template. Publish it before send nodes referencing it render the change. * * @see Courier\Services\Journeys\TemplatesService::replace() * diff --git a/src/Journeys/Templates/TemplateRetrieveContentParams.php b/src/Journeys/Templates/TemplateRetrieveContentParams.php index 3d12baef..6cd382b8 100644 --- a/src/Journeys/Templates/TemplateRetrieveContentParams.php +++ b/src/Journeys/Templates/TemplateRetrieveContentParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Retrieve the elemental content of a journey-scoped notification template. The response contains the versioned elements along with their content checksums, which can be used to detect changes between versions. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. + * Returns the Elemental elements and version of a journey-scoped template's content. Compare versions to see what changed between publishes. * * @see Courier\Services\Journeys\TemplatesService::retrieveContent() * diff --git a/src/Journeys/Templates/TemplateRetrieveParams.php b/src/Journeys/Templates/TemplateRetrieveParams.php index 5158fcee..b19da6d4 100644 --- a/src/Journeys/Templates/TemplateRetrieveParams.php +++ b/src/Journeys/Templates/TemplateRetrieveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Fetch a journey-scoped notification template by id. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. + * Returns a journey's own notification template with its name, brand, subscription topic, and content. Defaults to the published version. * * @see Courier\Services\Journeys\TemplatesService::retrieve() * diff --git a/src/Lists/ListListParams.php b/src/Lists/ListListParams.php index 8e9f0093..99f74c04 100644 --- a/src/Lists/ListListParams.php +++ b/src/Lists/ListListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Returns all of the lists, with the ability to filter based on a pattern. + * Returns the workspace's lists, filterable by a pattern to fetch a subset such as every regional list. Paged by cursor. * * @see Courier\Services\ListsService::list() * diff --git a/src/Lists/ListUpdateParams.php b/src/Lists/ListUpdateParams.php index 732527bd..669316ac 100644 --- a/src/Lists/ListUpdateParams.php +++ b/src/Lists/ListUpdateParams.php @@ -12,7 +12,7 @@ use Courier\RecipientPreferences; /** - * Create or replace an existing list with the supplied values. + * Creates or replaces a list from a name and preferences. Subscribers are managed through the separate subscriptions endpoints. * * @see Courier\Services\ListsService::update() * diff --git a/src/Lists/Subscriptions/SubscriptionListParams.php b/src/Lists/Subscriptions/SubscriptionListParams.php index c63e2e38..9150fa32 100644 --- a/src/Lists/Subscriptions/SubscriptionListParams.php +++ b/src/Lists/Subscriptions/SubscriptionListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get the list's subscriptions. + * Returns the users subscribed to a list with paging, each with the preferences recorded for that subscription. * * @see Courier\Services\Lists\SubscriptionsService::list() * diff --git a/src/Lists/Subscriptions/SubscriptionSubscribeUserParams.php b/src/Lists/Subscriptions/SubscriptionSubscribeUserParams.php index 03462539..9180439c 100644 --- a/src/Lists/Subscriptions/SubscriptionSubscribeUserParams.php +++ b/src/Lists/Subscriptions/SubscriptionSubscribeUserParams.php @@ -12,7 +12,7 @@ use Courier\RecipientPreferences; /** - * Subscribe a user to an existing list (note: if the List does not exist, it will be automatically created). + * Subscribes one user to a list, creating the list if it does not yet exist. Optional preferences apply to this subscription only. * * @see Courier\Services\Lists\SubscriptionsService::subscribeUser() * diff --git a/src/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.php b/src/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.php index aef46695..9f76bf53 100644 --- a/src/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.php +++ b/src/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Delete a subscription to a list by list ID and user ID. + * Removes one user's subscription to a list, addressed by list id and user id. The user's profile and other subscriptions are separate resources. * * @see Courier\Services\Lists\SubscriptionsService::unsubscribeUser() * diff --git a/src/Messages/MessageHistoryParams.php b/src/Messages/MessageHistoryParams.php index 3c6fe8ec..857bf3cf 100644 --- a/src/Messages/MessageHistoryParams.php +++ b/src/Messages/MessageHistoryParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Fetch the array of events of a message you've previously sent. + * Returns the ordered event history for a sent message, one entry per status transition with its timestamp. * * @see Courier\Services\MessagesService::history() * diff --git a/src/Messages/MessageListParams.php b/src/Messages/MessageListParams.php index 909a967b..3df37d5f 100644 --- a/src/Messages/MessageListParams.php +++ b/src/Messages/MessageListParams.php @@ -11,7 +11,7 @@ use Courier\Core\Conversion\ListOf; /** - * Fetch the statuses of messages you've previously sent. + * Returns previously sent messages, most recent first, each carrying its status, recipient, channel, and provider. Paged by cursor. * * @see Courier\Services\MessagesService::list() * diff --git a/src/Notifications/Checks/CheckDeleteParams.php b/src/Notifications/Checks/CheckDeleteParams.php index 79d55984..e2d3f0f4 100644 --- a/src/Notifications/Checks/CheckDeleteParams.php +++ b/src/Notifications/Checks/CheckDeleteParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Cancel a submission for a notification template. + * Cancels a pending template submission, withdrawing it from the approval workflow. The template stays in draft and can be resubmitted later. * * @see Courier\Services\Notifications\ChecksService::delete() * diff --git a/src/Notifications/Checks/CheckListParams.php b/src/Notifications/Checks/CheckListParams.php index 6402e338..2f79e19f 100644 --- a/src/Notifications/Checks/CheckListParams.php +++ b/src/Notifications/Checks/CheckListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Retrieve the submission checks for a notification template. + * Returns the approval checks recorded for a template submission, each with its pass or fail result. * * @see Courier\Services\Notifications\ChecksService::list() * diff --git a/src/Notifications/Checks/CheckUpdateParams.php b/src/Notifications/Checks/CheckUpdateParams.php index 0ba5ffdd..ef1be724 100644 --- a/src/Notifications/Checks/CheckUpdateParams.php +++ b/src/Notifications/Checks/CheckUpdateParams.php @@ -11,7 +11,7 @@ use Courier\Notifications\BaseCheck; /** - * Replace the submission checks for a notification template. + * Replaces the approval checks on a template submission with the complete set supplied in the request body. * * @see Courier\Services\Notifications\ChecksService::update() * diff --git a/src/Notifications/NotificationListParams.php b/src/Notifications/NotificationListParams.php index 01c3f57a..19446b48 100644 --- a/src/Notifications/NotificationListParams.php +++ b/src/Notifications/NotificationListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * List notification templates in your workspace. + * Lists the workspace's notification templates. Each carries a name, tags, brand, routing, and its draft or published state. * * @see Courier\Services\NotificationsService::list() * diff --git a/src/Notifications/NotificationListVersionsParams.php b/src/Notifications/NotificationListVersionsParams.php index 02ca0fbc..89e49e68 100644 --- a/src/Notifications/NotificationListVersionsParams.php +++ b/src/Notifications/NotificationListVersionsParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * List versions of a notification template. + * Returns a notification template's published versions, most recent first, for comparison or rollback. Paged. * * @see Courier\Services\NotificationsService::listVersions() * diff --git a/src/Notifications/NotificationPutContentParams.php b/src/Notifications/NotificationPutContentParams.php index 4c401aaa..58fee677 100644 --- a/src/Notifications/NotificationPutContentParams.php +++ b/src/Notifications/NotificationPutContentParams.php @@ -12,7 +12,7 @@ use Courier\Notifications\NotificationPutContentParams\Content; /** - * Replace the elemental content of a notification template. Overwrites all elements in the template with the provided content. Only supported for V2 (elemental) templates. + * Replaces all Elemental content in a template, overwriting every existing element. Supported for V2 templates only, not V1 blocks and channels. * * @see Courier\Services\NotificationsService::putContent() * diff --git a/src/Notifications/NotificationPutElementParams.php b/src/Notifications/NotificationPutElementParams.php index fc06db8c..3cbb8fbb 100644 --- a/src/Notifications/NotificationPutElementParams.php +++ b/src/Notifications/NotificationPutElementParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Update a single element within a notification template. Only supported for V2 (elemental) templates. + * Replaces one Elemental element in a template, addressed by its element id. Supported for V2 templates only, not V1 blocks and channels. * * @see Courier\Services\NotificationsService::putElement() * diff --git a/src/Notifications/NotificationPutLocaleParams.php b/src/Notifications/NotificationPutLocaleParams.php index 25a2dea7..203ce5b4 100644 --- a/src/Notifications/NotificationPutLocaleParams.php +++ b/src/Notifications/NotificationPutLocaleParams.php @@ -12,7 +12,7 @@ use Courier\Notifications\NotificationPutLocaleParams\Element; /** - * Set locale-specific content overrides for a notification template. Each element override must reference an existing element by ID. Only supported for V2 (elemental) templates. + * Sets locale-specific content overrides for a template. Each override must reference an element that already exists in the default content. * * @see Courier\Services\NotificationsService::putLocale() * diff --git a/src/Notifications/NotificationReplaceParams.php b/src/Notifications/NotificationReplaceParams.php index df1ab13e..071265c5 100644 --- a/src/Notifications/NotificationReplaceParams.php +++ b/src/Notifications/NotificationReplaceParams.php @@ -12,7 +12,7 @@ use Courier\Notifications\NotificationReplaceParams\State; /** - * Replace a notification template. All fields are required. + * Replaces a notification template in full, so send every field rather than only the ones you want changed. Publish separately to make it live. * * @see Courier\Services\NotificationsService::replace() * diff --git a/src/Notifications/NotificationRetrieveContentParams.php b/src/Notifications/NotificationRetrieveContentParams.php index 11698414..3faf2f33 100644 --- a/src/Notifications/NotificationRetrieveContentParams.php +++ b/src/Notifications/NotificationRetrieveContentParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Retrieve the content of a notification template. The response shape depends on whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use the `version` query parameter to select draft, published, or a specific historical version. + * Returns a template's content and checksum. V2 templates return Elemental elements, while V1 templates return blocks and channels instead. * * @see Courier\Services\NotificationsService::retrieveContent() * diff --git a/src/Profiles/Lists/ListRetrieveParams.php b/src/Profiles/Lists/ListRetrieveParams.php index 405830f3..4a04b1d3 100644 --- a/src/Profiles/Lists/ListRetrieveParams.php +++ b/src/Profiles/Lists/ListRetrieveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Returns the subscribed lists for a specified user. + * Returns the lists a user is subscribed to, with paging. Use it to check what a recipient will receive before sending to a list. * * @see Courier\Services\Profiles\ListsService::retrieve() * diff --git a/src/Profiles/Lists/ListSubscribeParams.php b/src/Profiles/Lists/ListSubscribeParams.php index 9f127942..6aafe487 100644 --- a/src/Profiles/Lists/ListSubscribeParams.php +++ b/src/Profiles/Lists/ListSubscribeParams.php @@ -11,7 +11,7 @@ use Courier\Profiles\SubscribeToListsRequestItem; /** - * Subscribes the given user to one or more lists. If the list does not exist, it will be created. + * Subscribes a user to one or more lists, creating any list that does not yet exist. Optional preferences apply to each subscription. * * @see Courier\Services\Profiles\ListsService::subscribe() * diff --git a/src/Profiles/ProfileCreateParams.php b/src/Profiles/ProfileCreateParams.php index 4f828e90..42f45a96 100644 --- a/src/Profiles/ProfileCreateParams.php +++ b/src/Profiles/ProfileCreateParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Merge the supplied values with an existing profile or create a new profile if one doesn't already exist. + * Merges the supplied values into a user's profile, creating it if absent and leaving any key you omit untouched. Prefer this for everyday writes. * * @see Courier\Services\ProfilesService::create() * diff --git a/src/Profiles/ProfileReplaceParams.php b/src/Profiles/ProfileReplaceParams.php index f76525b6..c10dcf49 100644 --- a/src/Profiles/ProfileReplaceParams.php +++ b/src/Profiles/ProfileReplaceParams.php @@ -10,10 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * When using `PUT`, be sure to include all the key-value pairs required by the recipient's profile. - * Any key-value pairs that exist in the profile but fail to be included in the `PUT` request will be - * removed from the profile. Remember, a `PUT` update is a full replacement of the data. For partial updates, - * use the [Patch](https://www.courier.com/docs/reference/profiles/patch/) request. + * Overwrites a user profile in full, removing any key absent from the request body. Use the patch endpoint when changing a single field. * * @see Courier\Services\ProfilesService::replace() * diff --git a/src/Profiles/ProfileUpdateParams.php b/src/Profiles/ProfileUpdateParams.php index 946a7818..90ab141a 100644 --- a/src/Profiles/ProfileUpdateParams.php +++ b/src/Profiles/ProfileUpdateParams.php @@ -11,7 +11,7 @@ use Courier\Profiles\ProfileUpdateParams\Patch; /** - * Update a profile. + * Applies a JSON Patch to a user profile, adding, removing, or replacing individual fields without sending the whole object. * * @see Courier\Services\ProfilesService::update() * diff --git a/src/Providers/Catalog/CatalogListParams.php b/src/Providers/Catalog/CatalogListParams.php index 97519231..2850d27e 100644 --- a/src/Providers/Catalog/CatalogListParams.php +++ b/src/Providers/Catalog/CatalogListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Returns the catalog of available provider types with their display names, descriptions, and configuration schema fields (snake_case, with `type` and `required`). Providers with no configurable schema return only `provider`, `name`, and `description`. + * Returns the provider types Courier supports, each with a display name, description, and the configuration fields it requires. * * @see Courier\Services\Providers\CatalogService::list() * diff --git a/src/Providers/ProviderCreateParams.php b/src/Providers/ProviderCreateParams.php index d2515a19..0f73ac32 100644 --- a/src/Providers/ProviderCreateParams.php +++ b/src/Providers/ProviderCreateParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Create a new provider configuration. The `provider` field must be a known Courier provider key (see catalog). + * Configures a provider integration from a Courier provider key and its settings. Check the catalog endpoint for the schema each provider expects. * * @see Courier\Services\ProvidersService::create() * diff --git a/src/Providers/ProviderListParams.php b/src/Providers/ProviderListParams.php index ca638ed8..ebadaf47 100644 --- a/src/Providers/ProviderListParams.php +++ b/src/Providers/ProviderListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * List configured provider integrations for the current workspace. Supports cursor-based pagination. + * Lists the provider integrations configured in the workspace, one entry per channel and provider key with its alias and settings. * * @see Courier\Services\ProvidersService::list() * diff --git a/src/Providers/ProviderUpdateParams.php b/src/Providers/ProviderUpdateParams.php index 41a4c321..79b4683f 100644 --- a/src/Providers/ProviderUpdateParams.php +++ b/src/Providers/ProviderUpdateParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Replace an existing provider configuration. The `provider` key is required and determines which provider-specific settings schema is applied. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge). Changing the provider type for an existing configuration is not supported. + * Replaces a provider's configuration in full, clearing any field you omit rather than merging it. Send the complete settings object. * * @see Courier\Services\ProvidersService::update() * diff --git a/src/RoutingStrategies/RoutingStrategyListNotificationsParams.php b/src/RoutingStrategies/RoutingStrategyListNotificationsParams.php index 4bf18cc9..75adffcb 100644 --- a/src/RoutingStrategies/RoutingStrategyListNotificationsParams.php +++ b/src/RoutingStrategies/RoutingStrategyListNotificationsParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * List notification templates associated with a routing strategy. Includes template metadata only, not full content. + * Returns the notification templates using a routing strategy, with paging. Check this before changing a strategy that templates depend on. * * @see Courier\Services\RoutingStrategiesService::listNotifications() * diff --git a/src/Send/SendMessageParams.php b/src/Send/SendMessageParams.php index fd17bc4b..dd2a5676 100644 --- a/src/Send/SendMessageParams.php +++ b/src/Send/SendMessageParams.php @@ -11,7 +11,7 @@ use Courier\Send\SendMessageParams\Message; /** - * Send a message to one or more recipients. + * Sends a message to one or more recipients and returns a requestId. Courier routes it to email, SMS, push, chat, or in-app based on your rules. * * @see Courier\Services\SendService::message() * diff --git a/src/Services/AudiencesRawService.php b/src/Services/AudiencesRawService.php index c3901b2e..b0a49e10 100644 --- a/src/Services/AudiencesRawService.php +++ b/src/Services/AudiencesRawService.php @@ -34,7 +34,7 @@ public function __construct(private Client $client) {} /** * @api * - * Returns the specified audience by id. + * Returns one audience with its name, description, and the filter and AND or OR operator that decide which users belong to it. * * @param string $audienceID A unique identifier representing the audience_id * @param RequestOpts|null $requestOptions @@ -59,7 +59,7 @@ public function retrieve( /** * @api * - * Creates or updates audience. + * Creates or replaces an audience from a filter and an AND or OR operator. Membership recalculates automatically as profiles change. * * @param string $audienceID A unique identifier representing the audience id * @param array{ @@ -97,7 +97,7 @@ public function update( /** * @api * - * Get the audiences associated with the authorization token. + * Returns the audiences in the workspace with paging. Audiences are filter-based groups that recalculate as user profiles change. * * @param array{cursor?: string|null}|AudienceListParams $params * @param RequestOpts|null $requestOptions @@ -128,7 +128,7 @@ public function list( /** * @api * - * Deletes the specified audience. + * Deletes an audience permanently, so update any caller sending to it by audience id first. Those sends fail once the audience is gone. * * @param string $audienceID A unique identifier representing the audience id * @param RequestOpts|null $requestOptions @@ -153,7 +153,7 @@ public function delete( /** * @api * - * Get list of members of an audience. + * Returns the users currently matching an audience filter, with paging. Membership is recalculated, so results shift as profiles change. * * @param string $audienceID A unique identifier representing the audience id * @param array{cursor?: string|null}|AudienceListMembersParams $params diff --git a/src/Services/AudiencesService.php b/src/Services/AudiencesService.php index 59d13044..125e4d7c 100644 --- a/src/Services/AudiencesService.php +++ b/src/Services/AudiencesService.php @@ -38,7 +38,7 @@ public function __construct(private Client $client) /** * @api * - * Returns the specified audience by id. + * Returns one audience with its name, description, and the filter and AND or OR operator that decide which users belong to it. * * @param string $audienceID A unique identifier representing the audience_id * @param RequestOpts|null $requestOptions @@ -58,7 +58,7 @@ public function retrieve( /** * @api * - * Creates or updates audience. + * Creates or replaces an audience from a filter and an AND or OR operator. Membership recalculates automatically as profiles change. * * @param string $audienceID A unique identifier representing the audience id * @param string|null $description A description of the audience @@ -95,7 +95,7 @@ public function update( /** * @api * - * Get the audiences associated with the authorization token. + * Returns the audiences in the workspace with paging. Audiences are filter-based groups that recalculate as user profiles change. * * @param string|null $cursor A unique identifier that allows for fetching the next set of audiences * @param RequestOpts|null $requestOptions @@ -117,7 +117,7 @@ public function list( /** * @api * - * Deletes the specified audience. + * Deletes an audience permanently, so update any caller sending to it by audience id first. Those sends fail once the audience is gone. * * @param string $audienceID A unique identifier representing the audience id * @param RequestOpts|null $requestOptions @@ -137,7 +137,7 @@ public function delete( /** * @api * - * Get list of members of an audience. + * Returns the users currently matching an audience filter, with paging. Membership is recalculated, so results shift as profiles change. * * @param string $audienceID A unique identifier representing the audience id * @param string|null $cursor A unique identifier that allows for fetching the next set of members diff --git a/src/Services/AuditEventsRawService.php b/src/Services/AuditEventsRawService.php index 10be9ac1..a0dc7b62 100644 --- a/src/Services/AuditEventsRawService.php +++ b/src/Services/AuditEventsRawService.php @@ -27,7 +27,7 @@ public function __construct(private Client $client) {} /** * @api * - * Fetch a specific audit event by ID. + * Returns one audit event by id, including the actor who performed it, the target they changed, the source, the event type, and a timestamp. * * @param string $auditEventID A unique identifier associated with the audit event you wish to retrieve * @param RequestOpts|null $requestOptions @@ -52,7 +52,7 @@ public function retrieve( /** * @api * - * Fetch the list of audit events + * Returns the workspace's audit event log with cursor paging. Each event records the actor, target, source, type, and timestamp of a change. * * @param array{cursor?: string|null}|AuditEventListParams $params * @param RequestOpts|null $requestOptions diff --git a/src/Services/AuditEventsService.php b/src/Services/AuditEventsService.php index a207f38c..78aab5f9 100644 --- a/src/Services/AuditEventsService.php +++ b/src/Services/AuditEventsService.php @@ -33,7 +33,7 @@ public function __construct(private Client $client) /** * @api * - * Fetch a specific audit event by ID. + * Returns one audit event by id, including the actor who performed it, the target they changed, the source, the event type, and a timestamp. * * @param string $auditEventID A unique identifier associated with the audit event you wish to retrieve * @param RequestOpts|null $requestOptions @@ -53,7 +53,7 @@ public function retrieve( /** * @api * - * Fetch the list of audit events + * Returns the workspace's audit event log with cursor paging. Each event records the actor, target, source, type, and timestamp of a change. * * @param string|null $cursor a unique identifier that allows for fetching the next set of audit events * @param RequestOpts|null $requestOptions diff --git a/src/Services/AuthRawService.php b/src/Services/AuthRawService.php index 0981911c..3e9f417a 100644 --- a/src/Services/AuthRawService.php +++ b/src/Services/AuthRawService.php @@ -26,7 +26,7 @@ public function __construct(private Client $client) {} /** * @api * - * Returns a new access token. + * Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply the scope and an expires_in duration, both required. * * @param array{expiresIn: string, scope: string}|AuthIssueTokenParams $params * @param RequestOpts|null $requestOptions diff --git a/src/Services/AuthService.php b/src/Services/AuthService.php index 07f0d268..1f07bc32 100644 --- a/src/Services/AuthService.php +++ b/src/Services/AuthService.php @@ -32,7 +32,7 @@ public function __construct(private Client $client) /** * @api * - * Returns a new access token. + * Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply the scope and an expires_in duration, both required. * * @param string $expiresIn Duration for token expiration. Accepts various time formats: * - "2 hours" - 2 hours from now diff --git a/src/Services/Automations/InvokeRawService.php b/src/Services/Automations/InvokeRawService.php index 1b429723..5ee6f941 100644 --- a/src/Services/Automations/InvokeRawService.php +++ b/src/Services/Automations/InvokeRawService.php @@ -29,7 +29,7 @@ public function __construct(private Client $client) {} /** * @api * - * Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a series of automation steps. For information about what steps are available, checkout the ad hoc automation guide [here](https://www.courier.com/docs/automations/steps/). + * Runs a series of automation steps supplied inline, without a saved template, and returns a runId. * * @param array{ * automation: Automation|AutomationShape, @@ -67,7 +67,7 @@ public function invokeAdHoc( /** * @api * - * Invoke an automation run from an automation template. + * Starts an automation run from a saved template for one recipient, with optional data and profile, and returns a runId. * * @param string $templateID A unique identifier representing the automation template to be invoked. This could be the Automation Template ID or the Automation Template Alias. * @param array{ diff --git a/src/Services/Automations/InvokeService.php b/src/Services/Automations/InvokeService.php index 19940fcf..bcc0d683 100644 --- a/src/Services/Automations/InvokeService.php +++ b/src/Services/Automations/InvokeService.php @@ -34,7 +34,7 @@ public function __construct(private Client $client) /** * @api * - * Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a series of automation steps. For information about what steps are available, checkout the ad hoc automation guide [here](https://www.courier.com/docs/automations/steps/). + * Runs a series of automation steps supplied inline, without a saved template, and returns a runId. * * @param Automation|AutomationShape $automation * @param array|null $data @@ -72,7 +72,7 @@ public function invokeAdHoc( /** * @api * - * Invoke an automation run from an automation template. + * Starts an automation run from a saved template for one recipient, with optional data and profile, and returns a runId. * * @param string $templateID A unique identifier representing the automation template to be invoked. This could be the Automation Template ID or the Automation Template Alias. * @param array|null $data diff --git a/src/Services/AutomationsRawService.php b/src/Services/AutomationsRawService.php index 2eeb31b9..9c637cfa 100644 --- a/src/Services/AutomationsRawService.php +++ b/src/Services/AutomationsRawService.php @@ -27,7 +27,7 @@ public function __construct(private Client $client) {} /** * @api * - * Get the list of automations. + * Lists the workspace's saved automation templates, each with its id and a cursor for paging to the next page of results. * * @param array{ * cursor?: string, version?: Version|value-of diff --git a/src/Services/AutomationsService.php b/src/Services/AutomationsService.php index a2f7039d..2f9db5c4 100644 --- a/src/Services/AutomationsService.php +++ b/src/Services/AutomationsService.php @@ -40,7 +40,7 @@ public function __construct(private Client $client) /** * @api * - * Get the list of automations. + * Lists the workspace's saved automation templates, each with its id and a cursor for paging to the next page of results. * * @param string $cursor A cursor token for pagination. Use the cursor from the previous response to fetch the next page of results. * @param Version|value-of $version The version of templates to retrieve. Accepted values are published (for published templates) or draft (for draft templates). Defaults to published. diff --git a/src/Services/BrandsRawService.php b/src/Services/BrandsRawService.php index fdeea584..4d2463ff 100644 --- a/src/Services/BrandsRawService.php +++ b/src/Services/BrandsRawService.php @@ -33,7 +33,7 @@ public function __construct(private Client $client) {} /** * @api * - * Create a new brand. Requires `name` and `settings` (with at least `colors.primary` and `colors.secondary`). + * Creates a brand from a name and settings, including primary and secondary colors. Brands supply the logo, colors, and styling that templates render with. * * @param array{ * name: string, @@ -69,7 +69,7 @@ public function create( /** * @api * - * Fetch a specific brand by brand ID. + * Returns one brand by id, including its colors, logo and styling settings, Handlebars snippets, and published version. * * @param string $brandID a unique identifier associated with the brand you wish to retrieve * @param RequestOpts|null $requestOptions @@ -94,7 +94,7 @@ public function retrieve( /** * @api * - * Replace an existing brand with the supplied values. + * Replaces a brand with the values you supply, so send the complete settings and snippets rather than only the fields you want changed. * * @param string $brandID a unique identifier associated with the brand you wish to update * @param array{ @@ -131,7 +131,7 @@ public function update( /** * @api * - * Get the list of brands. + * Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and published version. * * @param array{cursor?: string|null}|BrandListParams $params * @param RequestOpts|null $requestOptions @@ -162,7 +162,7 @@ public function list( /** * @api * - * Delete a brand by brand ID. + * Deletes a brand by id. Reassign any template or tenant that references it before deleting to keep their styling intact. * * @param string $brandID a unique identifier associated with the brand you wish to retrieve * @param RequestOpts|null $requestOptions diff --git a/src/Services/BrandsService.php b/src/Services/BrandsService.php index ac4fcab9..2faa6118 100644 --- a/src/Services/BrandsService.php +++ b/src/Services/BrandsService.php @@ -37,7 +37,7 @@ public function __construct(private Client $client) /** * @api * - * Create a new brand. Requires `name` and `settings` (with at least `colors.primary` and `colors.secondary`). + * Creates a brand from a name and settings, including primary and secondary colors. Brands supply the logo, colors, and styling that templates render with. * * @param BrandSettings|BrandSettingsShape $settings * @param BrandSnippets|BrandSnippetsShape|null $snippets @@ -70,7 +70,7 @@ public function create( /** * @api * - * Fetch a specific brand by brand ID. + * Returns one brand by id, including its colors, logo and styling settings, Handlebars snippets, and published version. * * @param string $brandID a unique identifier associated with the brand you wish to retrieve * @param RequestOpts|null $requestOptions @@ -90,7 +90,7 @@ public function retrieve( /** * @api * - * Replace an existing brand with the supplied values. + * Replaces a brand with the values you supply, so send the complete settings and snippets rather than only the fields you want changed. * * @param string $brandID a unique identifier associated with the brand you wish to update * @param string $name the name of the brand @@ -120,7 +120,7 @@ public function update( /** * @api * - * Get the list of brands. + * Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and published version. * * @param string|null $cursor a unique identifier that allows for fetching the next set of brands * @param RequestOpts|null $requestOptions @@ -142,7 +142,7 @@ public function list( /** * @api * - * Delete a brand by brand ID. + * Deletes a brand by id. Reassign any template or tenant that references it before deleting to keep their styling intact. * * @param string $brandID a unique identifier associated with the brand you wish to retrieve * @param RequestOpts|null $requestOptions diff --git a/src/Services/Digests/SchedulesRawService.php b/src/Services/Digests/SchedulesRawService.php index 3c71a169..629165cb 100644 --- a/src/Services/Digests/SchedulesRawService.php +++ b/src/Services/Digests/SchedulesRawService.php @@ -26,7 +26,7 @@ public function __construct(private Client $client) {} /** * @api * - * List the digest instances for a schedule. Each instance represents the events accumulated for a single user against the schedule, and can be used to monitor digest accumulation before the digest is released. + * Returns the digest instances for a schedule, one per user, with cursor paging. Use it to see what has accumulated before a digest releases. * * @param string $scheduleID The ID of the digest schedule, in the form `sch/{uuid}`. The value must be URL-encoded (e.g. `sch%2F00000000-0000-0000-0000-000000000000`). * @param array{cursor?: string, limit?: int}|ScheduleListInstancesParams $params diff --git a/src/Services/Digests/SchedulesService.php b/src/Services/Digests/SchedulesService.php index eb504268..00fdc152 100644 --- a/src/Services/Digests/SchedulesService.php +++ b/src/Services/Digests/SchedulesService.php @@ -32,7 +32,7 @@ public function __construct(private Client $client) /** * @api * - * List the digest instances for a schedule. Each instance represents the events accumulated for a single user against the schedule, and can be used to monitor digest accumulation before the digest is released. + * Returns the digest instances for a schedule, one per user, with cursor paging. Use it to see what has accumulated before a digest releases. * * @param string $scheduleID The ID of the digest schedule, in the form `sch/{uuid}`. The value must be URL-encoded (e.g. `sch%2F00000000-0000-0000-0000-000000000000`). * @param string $cursor a cursor token from a previous response, used to fetch the next page of results diff --git a/src/Services/InboundRawService.php b/src/Services/InboundRawService.php index 9015c7d5..9fee0700 100644 --- a/src/Services/InboundRawService.php +++ b/src/Services/InboundRawService.php @@ -27,7 +27,7 @@ public function __construct(private Client $client) {} /** * @api * - * Courier Track Event + * Records an inbound event that can trigger a journey. Requires an event name, a messageId you generate, a type, and a properties object. * * @param array{ * event: string, diff --git a/src/Services/InboundService.php b/src/Services/InboundService.php index 1faa85d5..d59278ea 100644 --- a/src/Services/InboundService.php +++ b/src/Services/InboundService.php @@ -33,7 +33,7 @@ public function __construct(private Client $client) /** * @api * - * Courier Track Event + * Records an inbound event that can trigger a journey. Requires an event name, a messageId you generate, a type, and a properties object. * * @param string $event A descriptive name of the event. This name will appear as a trigger in the Courier Automation Trigger node. * @param string $messageID A required unique identifier that will be used to de-duplicate requests. If not unique, will respond with 409 Conflict status diff --git a/src/Services/Journeys/TemplatesRawService.php b/src/Services/Journeys/TemplatesRawService.php index 59910075..cb203f8e 100644 --- a/src/Services/Journeys/TemplatesRawService.php +++ b/src/Services/Journeys/TemplatesRawService.php @@ -85,7 +85,7 @@ public function create( /** * @api * - * Fetch a journey-scoped notification template by id. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. + * Returns a journey's own notification template with its name, brand, subscription topic, and content. Defaults to the published version. * * @param string $notificationID Notification template id * @param array{templateID: string}|TemplateRetrieveParams $params @@ -152,7 +152,7 @@ public function list( /** * @api * - * Archive the journey-scoped notification template. Archived templates cannot be sent. + * Archives one journey's notification template, preventing further sends. Detach any send node referencing it beforehand. * * @param string $notificationID Notification template id * @param array{templateID: string}|TemplateArchiveParams $params @@ -186,7 +186,7 @@ public function archive( /** * @api * - * List published versions of the journey-scoped notification template, ordered most recent first. + * Lists the published versions of a template that belongs to a journey, most recent first. Paged by cursor. * * @param string $notificationID Notification template id * @param array{templateID: string}|TemplateListVersionsParams $params @@ -222,7 +222,7 @@ public function listVersions( /** * @api * - * Publish the current draft of the journey-scoped notification template as a new version. Optionally roll back to a prior version by passing `{ "version": "vN" }`. + * Publishes a journey-scoped template's draft as a new version. Pass a version instead to roll back the template to an earlier publish. * * @param string $notificationID Path param: Notification template id * @param array{templateID: string, version?: string}|TemplatePublishParams $params @@ -350,7 +350,7 @@ public function putLocale( /** * @api * - * Replace the journey-scoped notification template draft. + * Replaces the draft content of one journey's notification template. Publish it before send nodes referencing it render the change. * * @param string $notificationID Path param: Notification template id * @param array{ @@ -389,7 +389,7 @@ public function replace( /** * @api * - * Retrieve the elemental content of a journey-scoped notification template. The response contains the versioned elements along with their content checksums, which can be used to detect changes between versions. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. + * Returns the Elemental elements and version of a journey-scoped template's content. Compare versions to see what changed between publishes. * * @param string $notificationID Path param: Notification template id * @param array{ diff --git a/src/Services/Journeys/TemplatesService.php b/src/Services/Journeys/TemplatesService.php index ef7c7ba8..1cb3add4 100644 --- a/src/Services/Journeys/TemplatesService.php +++ b/src/Services/Journeys/TemplatesService.php @@ -78,7 +78,7 @@ public function create( /** * @api * - * Fetch a journey-scoped notification template by id. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. + * Returns a journey's own notification template with its name, brand, subscription topic, and content. Defaults to the published version. * * @param string $notificationID Notification template id * @param string $templateID Journey id @@ -128,7 +128,7 @@ public function list( /** * @api * - * Archive the journey-scoped notification template. Archived templates cannot be sent. + * Archives one journey's notification template, preventing further sends. Detach any send node referencing it beforehand. * * @param string $notificationID Notification template id * @param string $templateID Journey id @@ -152,7 +152,7 @@ public function archive( /** * @api * - * List published versions of the journey-scoped notification template, ordered most recent first. + * Lists the published versions of a template that belongs to a journey, most recent first. Paged by cursor. * * @param string $notificationID Notification template id * @param string $templateID Journey id @@ -176,7 +176,7 @@ public function listVersions( /** * @api * - * Publish the current draft of the journey-scoped notification template as a new version. Optionally roll back to a prior version by passing `{ "version": "vN" }`. + * Publishes a journey-scoped template's draft as a new version. Pass a version instead to roll back the template to an earlier publish. * * @param string $notificationID Path param: Notification template id * @param string $templateID Path param: Journey id @@ -271,7 +271,7 @@ public function putLocale( /** * @api * - * Replace the journey-scoped notification template draft. + * Replaces the draft content of one journey's notification template. Publish it before send nodes referencing it render the change. * * @param string $notificationID Path param: Notification template id * @param string $templateID Path param: Journey id @@ -305,7 +305,7 @@ public function replace( /** * @api * - * Retrieve the elemental content of a journey-scoped notification template. The response contains the versioned elements along with their content checksums, which can be used to detect changes between versions. Pass `?version=draft` (default `published`) to retrieve the working draft, or `?version=vN` for a historical version. + * Returns the Elemental elements and version of a journey-scoped template's content. Compare versions to see what changed between publishes. * * @param string $notificationID Path param: Notification template id * @param string $templateID Path param: Journey id diff --git a/src/Services/JourneysRawService.php b/src/Services/JourneysRawService.php index 4da9f165..8066d3d9 100644 --- a/src/Services/JourneysRawService.php +++ b/src/Services/JourneysRawService.php @@ -40,7 +40,7 @@ public function __construct(private Client $client) {} /** * @api * - * Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to publish on create. Send nodes are not allowed on `POST`. The standard flow is: create the journey shell here, add notification templates with `POST /journeys/{templateId}/templates`, then wire them into the journey with `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to publish a draft after the fact. + * Creates a journey from a set of nodes, in draft state unless you pass a published state. Send nodes cannot be included until their templates exist. * * @param array{ * name: string, @@ -109,7 +109,7 @@ public function retrieve( /** * @api * - * Get the list of journeys. + * Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by cursor. * * @param array{ * cursor?: string, version?: Version|value-of @@ -142,7 +142,7 @@ public function list( /** * @api * - * Archive a journey. Archived journeys cannot be invoked. Existing journey runs continue to completion. + * Archives a journey so it can no longer be invoked. Runs already in flight continue to completion, so archiving never strands a user mid-sequence. * * @param string $templateID Journey id * @param RequestOpts|null $requestOptions @@ -167,7 +167,7 @@ public function archive( /** * @api * - * Cancel journey runs. The request body must include EXACTLY ONE of `cancelation_token` (cancels every run associated with the token) or `run_id` (cancels a single tenant-scoped run). Supplying both or neither returns a `400`. A `run_id` that does not match a run for the tenant returns `404`. Cancelation is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was already `CANCELED` is left unchanged and its current status is returned. + * Cancels in-flight journey runs, either every run sharing a cancelation token or one run by id. Use it to stop a sequence when the event resolves. * * @param array{ * cancelationToken: string, runID: string @@ -200,7 +200,7 @@ public function cancel( /** * @api * - * Invoke a journey by id or alias to start a new run. The response includes a `runId` identifying the run. + * Starts a journey run for one user and returns a runId. Runs execute asynchronously, so the response arrives before any message is sent. * * @param string $templateID A unique identifier representing the journey to be invoked. Accepts a Journey ID or Journey Alias. * @param array{ @@ -235,7 +235,7 @@ public function invoke( /** * @api * - * List published versions of a journey, ordered most recent first. + * Lists a journey's published versions, most recent first, so you have a version id to roll back to. Paged by cursor. * * @param string $templateID Journey id * @param RequestOpts|null $requestOptions @@ -260,7 +260,7 @@ public function listVersions( /** * @api * - * Publish the current draft as a new version. Body is optional; pass `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if the journey has no draft to publish. + * Publishes a journey's current draft as a new version, making it live for new runs. Pass a version instead to roll back to an earlier one. * * @param string $templateID Journey id * @param array{version?: string}|JourneyPublishParams $params @@ -293,7 +293,7 @@ public function publish( /** * @api * - * Replace the journey draft. Updates the working draft only; call `POST /journeys/{templateId}/publish` to make it live, or pass `state: "PUBLISHED"` in this request to publish immediately. Send-node `template` ids must already exist and be scoped to this journey, and node ids must not be claimed by another journey. + * Replaces a journey's working draft, leaving the published version live until you publish. Reach for this when editing a journey already running. * * @param string $templateID Journey id * @param array{ diff --git a/src/Services/JourneysService.php b/src/Services/JourneysService.php index 11c602a6..3ba69519 100644 --- a/src/Services/JourneysService.php +++ b/src/Services/JourneysService.php @@ -46,7 +46,7 @@ public function __construct(private Client $client) /** * @api * - * Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to publish on create. Send nodes are not allowed on `POST`. The standard flow is: create the journey shell here, add notification templates with `POST /journeys/{templateId}/templates`, then wire them into the journey with `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to publish a draft after the fact. + * Creates a journey from a set of nodes, in draft state unless you pass a published state. Send nodes cannot be included until their templates exist. * * @param list $nodes * @param JourneyState|value-of $state lifecycle state of a journey @@ -103,7 +103,7 @@ public function retrieve( /** * @api * - * Get the list of journeys. + * Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by cursor. * * @param string $cursor A cursor token for pagination. Use the cursor from the previous response to fetch the next page of results. * @param Version|value-of $version The version of journeys to retrieve. Accepted values are published (for published journeys) or draft (for draft journeys). Defaults to published. @@ -127,7 +127,7 @@ public function list( /** * @api * - * Archive a journey. Archived journeys cannot be invoked. Existing journey runs continue to completion. + * Archives a journey so it can no longer be invoked. Runs already in flight continue to completion, so archiving never strands a user mid-sequence. * * @param string $templateID Journey id * @param RequestOpts|null $requestOptions @@ -147,7 +147,7 @@ public function archive( /** * @api * - * Cancel journey runs. The request body must include EXACTLY ONE of `cancelation_token` (cancels every run associated with the token) or `run_id` (cancels a single tenant-scoped run). Supplying both or neither returns a `400`. A `run_id` that does not match a run for the tenant returns `404`. Cancelation is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was already `CANCELED` is left unchanged and its current status is returned. + * Cancels in-flight journey runs, either every run sharing a cancelation token or one run by id. Use it to stop a sequence when the event resolves. * * @param RequestOpts|null $requestOptions * @@ -171,7 +171,7 @@ public function cancel( /** * @api * - * Invoke a journey by id or alias to start a new run. The response includes a `runId` identifying the run. + * Starts a journey run for one user and returns a runId. Runs execute asynchronously, so the response arrives before any message is sent. * * @param string $templateID A unique identifier representing the journey to be invoked. Accepts a Journey ID or Journey Alias. * @param array $data Data payload passed to the journey. The expected shape can be predefined using the schema builder in the journey editor. This data is available in journey steps for condition evaluation and template variable interpolation. Can also contain user identifiers (user_id, userId, anonymousId) if not provided elsewhere. @@ -201,7 +201,7 @@ public function invoke( /** * @api * - * List published versions of a journey, ordered most recent first. + * Lists a journey's published versions, most recent first, so you have a version id to roll back to. Paged by cursor. * * @param string $templateID Journey id * @param RequestOpts|null $requestOptions @@ -221,7 +221,7 @@ public function listVersions( /** * @api * - * Publish the current draft as a new version. Body is optional; pass `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if the journey has no draft to publish. + * Publishes a journey's current draft as a new version, making it live for new runs. Pass a version instead to roll back to an earlier one. * * @param string $templateID Journey id * @param RequestOpts|null $requestOptions @@ -244,7 +244,7 @@ public function publish( /** * @api * - * Replace the journey draft. Updates the working draft only; call `POST /journeys/{templateId}/publish` to make it live, or pass `state: "PUBLISHED"` in this request to publish immediately. Send-node `template` ids must already exist and be scoped to this journey, and node ids must not be claimed by another journey. + * Replaces a journey's working draft, leaving the published version live until you publish. Reach for this when editing a journey already running. * * @param string $templateID Journey id * @param list $nodes diff --git a/src/Services/Lists/SubscriptionsRawService.php b/src/Services/Lists/SubscriptionsRawService.php index 22d12b67..a8ea2b55 100644 --- a/src/Services/Lists/SubscriptionsRawService.php +++ b/src/Services/Lists/SubscriptionsRawService.php @@ -34,7 +34,7 @@ public function __construct(private Client $client) {} /** * @api * - * Get the list's subscriptions. + * Returns the users subscribed to a list with paging, each with the preferences recorded for that subscription. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param array{cursor?: string|null}|SubscriptionListParams $params @@ -137,7 +137,7 @@ public function subscribe( /** * @api * - * Subscribe a user to an existing list (note: if the List does not exist, it will be automatically created). + * Subscribes one user to a list, creating the list if it does not yet exist. Optional preferences apply to this subscription only. * * @param string $userID Path param: A unique identifier representing the recipient associated with the list * @param array{ @@ -175,7 +175,7 @@ public function subscribeUser( /** * @api * - * Delete a subscription to a list by list ID and user ID. + * Removes one user's subscription to a list, addressed by list id and user id. The user's profile and other subscriptions are separate resources. * * @param string $userID A unique identifier representing the recipient associated with the list * @param array{listID: string}|SubscriptionUnsubscribeUserParams $params diff --git a/src/Services/Lists/SubscriptionsService.php b/src/Services/Lists/SubscriptionsService.php index 7346a6a9..d392888a 100644 --- a/src/Services/Lists/SubscriptionsService.php +++ b/src/Services/Lists/SubscriptionsService.php @@ -36,7 +36,7 @@ public function __construct(private Client $client) /** * @api * - * Get the list's subscriptions. + * Returns the users subscribed to a list with paging, each with the preferences recorded for that subscription. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param string|null $cursor A unique identifier that allows for fetching the next set of list subscriptions @@ -108,7 +108,7 @@ public function subscribe( /** * @api * - * Subscribe a user to an existing list (note: if the List does not exist, it will be automatically created). + * Subscribes one user to a list, creating the list if it does not yet exist. Optional preferences apply to this subscription only. * * @param string $userID Path param: A unique identifier representing the recipient associated with the list * @param string $listID path param: A unique identifier representing the list you wish to retrieve @@ -136,7 +136,7 @@ public function subscribeUser( /** * @api * - * Delete a subscription to a list by list ID and user ID. + * Removes one user's subscription to a list, addressed by list id and user id. The user's profile and other subscriptions are separate resources. * * @param string $userID A unique identifier representing the recipient associated with the list * @param string $listID a unique identifier representing the list you wish to retrieve diff --git a/src/Services/ListsRawService.php b/src/Services/ListsRawService.php index f0c802c3..a8e05597 100644 --- a/src/Services/ListsRawService.php +++ b/src/Services/ListsRawService.php @@ -30,7 +30,7 @@ public function __construct(private Client $client) {} /** * @api * - * Returns a list based on the list ID provided. + * Returns one list by id with its name and created and updated timestamps. Fetch its subscribers separately with the subscriptions endpoint. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param RequestOpts|null $requestOptions @@ -55,7 +55,7 @@ public function retrieve( /** * @api * - * Create or replace an existing list with the supplied values. + * Creates or replaces a list from a name and preferences. Subscribers are managed through the separate subscriptions endpoints. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param array{ @@ -91,7 +91,7 @@ public function update( /** * @api * - * Returns all of the lists, with the ability to filter based on a pattern. + * Returns the workspace's lists, filterable by a pattern to fetch a subset such as every regional list. Paged by cursor. * * @param array{cursor?: string|null, pattern?: string|null}|ListListParams $params * @param RequestOpts|null $requestOptions @@ -122,7 +122,7 @@ public function list( /** * @api * - * Delete a list by list ID. + * Deletes a list, halting sends that target it. A previously deleted list can be brought back with the companion restore endpoint. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param RequestOpts|null $requestOptions @@ -147,7 +147,7 @@ public function delete( /** * @api * - * Restore a previously deleted list. + * Restores a previously deleted list along with its subscribers, so a list removed by mistake can be brought back rather than rebuilt. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param RequestOpts|null $requestOptions diff --git a/src/Services/ListsService.php b/src/Services/ListsService.php index db96dc1a..9488cdbb 100644 --- a/src/Services/ListsService.php +++ b/src/Services/ListsService.php @@ -42,7 +42,7 @@ public function __construct(private Client $client) /** * @api * - * Returns a list based on the list ID provided. + * Returns one list by id with its name and created and updated timestamps. Fetch its subscribers separately with the subscriptions endpoint. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param RequestOpts|null $requestOptions @@ -62,7 +62,7 @@ public function retrieve( /** * @api * - * Create or replace an existing list with the supplied values. + * Creates or replaces a list from a name and preferences. Subscribers are managed through the separate subscriptions endpoints. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param RecipientPreferences|RecipientPreferencesShape|null $preferences @@ -89,7 +89,7 @@ public function update( /** * @api * - * Returns all of the lists, with the ability to filter based on a pattern. + * Returns the workspace's lists, filterable by a pattern to fetch a subset such as every regional list. Paged by cursor. * * @param string|null $cursor a unique identifier that allows for fetching the next page of lists * @param string|null $pattern "A pattern used to filter the list items returned. Pattern types supported: exact match on `list_id` or a pattern of one or more pattern parts. you may replace a part with either: `*` to match all parts in that position, or `**` to signify a wildcard `endsWith` pattern match." @@ -113,7 +113,7 @@ public function list( /** * @api * - * Delete a list by list ID. + * Deletes a list, halting sends that target it. A previously deleted list can be brought back with the companion restore endpoint. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param RequestOpts|null $requestOptions @@ -133,7 +133,7 @@ public function delete( /** * @api * - * Restore a previously deleted list. + * Restores a previously deleted list along with its subscribers, so a list removed by mistake can be brought back rather than rebuilt. * * @param string $listID a unique identifier representing the list you wish to retrieve * @param RequestOpts|null $requestOptions diff --git a/src/Services/MessagesRawService.php b/src/Services/MessagesRawService.php index 85e4ee1e..e30de117 100644 --- a/src/Services/MessagesRawService.php +++ b/src/Services/MessagesRawService.php @@ -33,7 +33,7 @@ public function __construct(private Client $client) {} /** * @api * - * Fetch the status of a message you've previously sent. + * Returns a sent message's status, recipient, event, and per-provider delivery detail, with timestamps for enqueued, sent, delivered, opened, and clicked. * * @param string $messageID a unique identifier associated with the message you wish to retrieve (results from a send) * @param RequestOpts|null $requestOptions @@ -58,7 +58,7 @@ public function retrieve( /** * @api * - * Fetch the statuses of messages you've previously sent. + * Returns previously sent messages, most recent first, each carrying its status, recipient, channel, and provider. Paged by cursor. * * @param array{ * archived?: bool|null, @@ -112,7 +112,7 @@ public function list( /** * @api * - * Cancel a message that is currently in the process of being delivered. A well-formatted API call to the cancel message API will return either `200` status code for a successful cancellation or `409` status code for an unsuccessful cancellation. Both cases will include the actual message record in the response body (see details below). + * Cancels a message that is still in the delivery pipeline and returns the message record with its resulting canceled or failed status. * * @param string $messageID A unique identifier representing the message ID * @param RequestOpts|null $requestOptions @@ -137,7 +137,7 @@ public function cancel( /** * @api * - * Get message content + * Returns the rendered content Courier delivered for a message, broken out per channel, to confirm what the recipient received. * * @param string $messageID a unique identifier associated with the message you wish to retrieve (results from a send) * @param RequestOpts|null $requestOptions @@ -162,7 +162,7 @@ public function content( /** * @api * - * Fetch the array of events of a message you've previously sent. + * Returns the ordered event history for a sent message, one entry per status transition with its timestamp. * * @param string $messageID A unique identifier representing the message ID * @param array{type?: string|null}|MessageHistoryParams $params @@ -195,8 +195,7 @@ public function history( /** * @api * - * Resend a previously sent message. The original send request is loaded from storage and a brand-new send is enqueued for the same recipient and content, producing a **new** `messageId` — the original message is not modified. - * Throttled by a per-message rate limit; a repeat inside the limit window returns `429 Too Many Requests`. + * Resends a previously sent message to the same recipient and content, returning a new messageId. The original send request is not modified. * * @param string $messageID a unique identifier representing the message ID of the original message to resend * @param RequestOpts|null $requestOptions diff --git a/src/Services/MessagesService.php b/src/Services/MessagesService.php index 92d2feca..cf7babd3 100644 --- a/src/Services/MessagesService.php +++ b/src/Services/MessagesService.php @@ -37,7 +37,7 @@ public function __construct(private Client $client) /** * @api * - * Fetch the status of a message you've previously sent. + * Returns a sent message's status, recipient, event, and per-provider delivery detail, with timestamps for enqueued, sent, delivered, opened, and clicked. * * @param string $messageID a unique identifier associated with the message you wish to retrieve (results from a send) * @param RequestOpts|null $requestOptions @@ -57,7 +57,7 @@ public function retrieve( /** * @api * - * Fetch the statuses of messages you've previously sent. + * Returns previously sent messages, most recent first, each carrying its status, recipient, channel, and provider. Paged by cursor. * * @param bool|null $archived a boolean value that indicates whether archived messages should be included in the response * @param string|null $cursor a unique identifier that allows for fetching the next set of messages @@ -122,7 +122,7 @@ public function list( /** * @api * - * Cancel a message that is currently in the process of being delivered. A well-formatted API call to the cancel message API will return either `200` status code for a successful cancellation or `409` status code for an unsuccessful cancellation. Both cases will include the actual message record in the response body (see details below). + * Cancels a message that is still in the delivery pipeline and returns the message record with its resulting canceled or failed status. * * @param string $messageID A unique identifier representing the message ID * @param RequestOpts|null $requestOptions @@ -142,7 +142,7 @@ public function cancel( /** * @api * - * Get message content + * Returns the rendered content Courier delivered for a message, broken out per channel, to confirm what the recipient received. * * @param string $messageID a unique identifier associated with the message you wish to retrieve (results from a send) * @param RequestOpts|null $requestOptions @@ -162,7 +162,7 @@ public function content( /** * @api * - * Fetch the array of events of a message you've previously sent. + * Returns the ordered event history for a sent message, one entry per status transition with its timestamp. * * @param string $messageID A unique identifier representing the message ID * @param string|null $type a supported Message History type that will filter the events returned @@ -186,8 +186,7 @@ public function history( /** * @api * - * Resend a previously sent message. The original send request is loaded from storage and a brand-new send is enqueued for the same recipient and content, producing a **new** `messageId` — the original message is not modified. - * Throttled by a per-message rate limit; a repeat inside the limit window returns `429 Too Many Requests`. + * Resends a previously sent message to the same recipient and content, returning a new messageId. The original send request is not modified. * * @param string $messageID a unique identifier representing the message ID of the original message to resend * @param RequestOpts|null $requestOptions diff --git a/src/Services/Notifications/ChecksRawService.php b/src/Services/Notifications/ChecksRawService.php index 69145436..d6193c92 100644 --- a/src/Services/Notifications/ChecksRawService.php +++ b/src/Services/Notifications/ChecksRawService.php @@ -31,7 +31,7 @@ public function __construct(private Client $client) {} /** * @api * - * Replace the submission checks for a notification template. + * Replaces the approval checks on a template submission with the complete set supplied in the request body. * * @param string $submissionID path param: Submission ID * @param array{ @@ -68,7 +68,7 @@ public function update( /** * @api * - * Retrieve the submission checks for a notification template. + * Returns the approval checks recorded for a template submission, each with its pass or fail result. * * @param string $submissionID submission ID * @param array{id: string}|CheckListParams $params @@ -102,7 +102,7 @@ public function list( /** * @api * - * Cancel a submission for a notification template. + * Cancels a pending template submission, withdrawing it from the approval workflow. The template stays in draft and can be resubmitted later. * * @param string $submissionID submission ID * @param array{id: string}|CheckDeleteParams $params diff --git a/src/Services/Notifications/ChecksService.php b/src/Services/Notifications/ChecksService.php index a9b7a3df..c2e1e9b8 100644 --- a/src/Services/Notifications/ChecksService.php +++ b/src/Services/Notifications/ChecksService.php @@ -35,7 +35,7 @@ public function __construct(private Client $client) /** * @api * - * Replace the submission checks for a notification template. + * Replaces the approval checks on a template submission with the complete set supplied in the request body. * * @param string $submissionID path param: Submission ID * @param string $id path param: Notification template ID @@ -61,7 +61,7 @@ public function update( /** * @api * - * Retrieve the submission checks for a notification template. + * Returns the approval checks recorded for a template submission, each with its pass or fail result. * * @param string $submissionID submission ID * @param string $id notification template ID @@ -85,7 +85,7 @@ public function list( /** * @api * - * Cancel a submission for a notification template. + * Cancels a pending template submission, withdrawing it from the approval workflow. The template stays in draft and can be resubmitted later. * * @param string $submissionID submission ID * @param string $id notification template ID diff --git a/src/Services/NotificationsRawService.php b/src/Services/NotificationsRawService.php index 1eed20cb..e893373f 100644 --- a/src/Services/NotificationsRawService.php +++ b/src/Services/NotificationsRawService.php @@ -117,7 +117,7 @@ public function retrieve( /** * @api * - * List notification templates in your workspace. + * Lists the workspace's notification templates. Each carries a name, tags, brand, routing, and its draft or published state. * * @param array{ * cursor?: string|null, eventID?: string, notes?: bool|null @@ -150,7 +150,7 @@ public function list( /** * @api * - * Archive a notification template. + * Archives a notification template, preventing new sends from referencing it. The template stays retrievable for its version history. * * @param string $id template ID (nt_ prefix) * @param RequestOpts|null $requestOptions @@ -175,7 +175,7 @@ public function archive( /** * @api * - * Duplicate a notification template. Creates a standalone copy within the same workspace and environment, with " COPY" appended to the title. The copy clones the source draft's tags, brand, subscription topic, routing strategy, channels, and content, and is always created as a standalone template (it is not linked to any journey or broadcast, even if the source was). Templates that are scoped to a journey or a broadcast cannot be duplicated through this endpoint. + * Copies a notification template within the same workspace and environment, appending " COPY" to the title. The copy is standalone and independently editable. * * @param string $id template ID (nt_ prefix) * @param RequestOpts|null $requestOptions @@ -200,7 +200,7 @@ public function duplicate( /** * @api * - * List versions of a notification template. + * Returns a notification template's published versions, most recent first, for comparison or rollback. Paged. * * @param string $id template ID (nt_ prefix) * @param array{ @@ -268,7 +268,7 @@ public function publish( /** * @api * - * Replace the elemental content of a notification template. Overwrites all elements in the template with the provided content. Only supported for V2 (elemental) templates. + * Replaces all Elemental content in a template, overwriting every existing element. Supported for V2 templates only, not V1 blocks and channels. * * @param string $id notification template ID (`nt_` prefix) * @param array{ @@ -304,7 +304,7 @@ public function putContent( /** * @api * - * Update a single element within a notification template. Only supported for V2 (elemental) templates. + * Replaces one Elemental element in a template, addressed by its element id. Supported for V2 templates only, not V1 blocks and channels. * * @param string $elementID path param: Element ID within the template * @param array{ @@ -348,7 +348,7 @@ public function putElement( /** * @api * - * Set locale-specific content overrides for a notification template. Each element override must reference an existing element by ID. Only supported for V2 (elemental) templates. + * Sets locale-specific content overrides for a template. Each override must reference an element that already exists in the default content. * * @param string $localeID Path param: Locale code (e.g., `es`, `fr`, `pt-BR`). * @param array{ @@ -387,7 +387,7 @@ public function putLocale( /** * @api * - * Replace a notification template. All fields are required. + * Replaces a notification template in full, so send every field rather than only the ones you want changed. Publish separately to make it live. * * @param string $id template ID (nt_ prefix) * @param array{ @@ -423,7 +423,7 @@ public function replace( /** * @api * - * Retrieve the content of a notification template. The response shape depends on whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use the `version` query parameter to select draft, published, or a specific historical version. + * Returns a template's content and checksum. V2 templates return Elemental elements, while V1 templates return blocks and channels instead. * * @param string $id notification template ID (`nt_` prefix) * @param array{version?: string}|NotificationRetrieveContentParams $params diff --git a/src/Services/NotificationsService.php b/src/Services/NotificationsService.php index 36d1d733..6efc8145 100644 --- a/src/Services/NotificationsService.php +++ b/src/Services/NotificationsService.php @@ -102,7 +102,7 @@ public function retrieve( /** * @api * - * List notification templates in your workspace. + * Lists the workspace's notification templates. Each carries a name, tags, brand, routing, and its draft or published state. * * @param string|null $cursor Opaque pagination cursor from a previous response. Omit for the first page. * @param string $eventID filter to templates linked to this event map ID @@ -130,7 +130,7 @@ public function list( /** * @api * - * Archive a notification template. + * Archives a notification template, preventing new sends from referencing it. The template stays retrievable for its version history. * * @param string $id template ID (nt_ prefix) * @param RequestOpts|null $requestOptions @@ -150,7 +150,7 @@ public function archive( /** * @api * - * Duplicate a notification template. Creates a standalone copy within the same workspace and environment, with " COPY" appended to the title. The copy clones the source draft's tags, brand, subscription topic, routing strategy, channels, and content, and is always created as a standalone template (it is not linked to any journey or broadcast, even if the source was). Templates that are scoped to a journey or a broadcast cannot be duplicated through this endpoint. + * Copies a notification template within the same workspace and environment, appending " COPY" to the title. The copy is standalone and independently editable. * * @param string $id template ID (nt_ prefix) * @param RequestOpts|null $requestOptions @@ -170,7 +170,7 @@ public function duplicate( /** * @api * - * List versions of a notification template. + * Returns a notification template's published versions, most recent first, for comparison or rollback. Paged. * * @param string $id template ID (nt_ prefix) * @param string $cursor Opaque pagination cursor from a previous response. Omit for the first page. @@ -220,7 +220,7 @@ public function publish( /** * @api * - * Replace the elemental content of a notification template. Overwrites all elements in the template with the provided content. Only supported for V2 (elemental) templates. + * Replaces all Elemental content in a template, overwriting every existing element. Supported for V2 templates only, not V1 blocks and channels. * * @param string $id notification template ID (`nt_` prefix) * @param Content|ContentShape $content Elemental content payload. The server defaults `version` when omitted. @@ -246,7 +246,7 @@ public function putContent( /** * @api * - * Update a single element within a notification template. Only supported for V2 (elemental) templates. + * Replaces one Elemental element in a template, addressed by its element id. Supported for V2 templates only, not V1 blocks and channels. * * @param string $elementID path param: Element ID within the template * @param string $id path param: Notification template ID (`nt_` prefix) @@ -295,7 +295,7 @@ public function putElement( /** * @api * - * Set locale-specific content overrides for a notification template. Each element override must reference an existing element by ID. Only supported for V2 (elemental) templates. + * Sets locale-specific content overrides for a template. Each override must reference an element that already exists in the default content. * * @param string $localeID Path param: Locale code (e.g., `es`, `fr`, `pt-BR`). * @param string $id path param: Notification template ID (`nt_` prefix) @@ -325,7 +325,7 @@ public function putLocale( /** * @api * - * Replace a notification template. All fields are required. + * Replaces a notification template in full, so send every field rather than only the ones you want changed. Publish separately to make it live. * * @param string $id template ID (nt_ prefix) * @param NotificationTemplatePayload|NotificationTemplatePayloadShape $notification core template fields used in POST and PUT request bodies (nested under a `notification` key) and returned at the top level in responses @@ -353,7 +353,7 @@ public function replace( /** * @api * - * Retrieve the content of a notification template. The response shape depends on whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use the `version` query parameter to select draft, published, or a specific historical version. + * Returns a template's content and checksum. V2 templates return Elemental elements, while V1 templates return blocks and channels instead. * * @param string $id notification template ID (`nt_` prefix) * @param string $version Accepts `draft`, `published`, or a version string (e.g., `v001`). Defaults to `published`. diff --git a/src/Services/Profiles/ListsRawService.php b/src/Services/Profiles/ListsRawService.php index 6dd6ef8b..99da717a 100644 --- a/src/Services/Profiles/ListsRawService.php +++ b/src/Services/Profiles/ListsRawService.php @@ -31,7 +31,7 @@ public function __construct(private Client $client) {} /** * @api * - * Returns the subscribed lists for a specified user. + * Returns the lists a user is subscribed to, with paging. Use it to check what a recipient will receive before sending to a list. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param array{cursor?: string|null}|ListRetrieveParams $params @@ -64,7 +64,7 @@ public function retrieve( /** * @api * - * Removes all list subscriptions for given user. + * Removes every list subscription for a user at once. Their profile and preferences are untouched, so this only affects list-targeted sends. * * @param string $userID a unique identifier representing the user associated with the requested profile * @param RequestOpts|null $requestOptions @@ -89,7 +89,7 @@ public function delete( /** * @api * - * Subscribes the given user to one or more lists. If the list does not exist, it will be created. + * Subscribes a user to one or more lists, creating any list that does not yet exist. Optional preferences apply to each subscription. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param array{ diff --git a/src/Services/Profiles/ListsService.php b/src/Services/Profiles/ListsService.php index a44851ea..36926fc2 100644 --- a/src/Services/Profiles/ListsService.php +++ b/src/Services/Profiles/ListsService.php @@ -36,7 +36,7 @@ public function __construct(private Client $client) /** * @api * - * Returns the subscribed lists for a specified user. + * Returns the lists a user is subscribed to, with paging. Use it to check what a recipient will receive before sending to a list. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param string|null $cursor a unique identifier that allows for fetching the next set of message statuses @@ -60,7 +60,7 @@ public function retrieve( /** * @api * - * Removes all list subscriptions for given user. + * Removes every list subscription for a user at once. Their profile and preferences are untouched, so this only affects list-targeted sends. * * @param string $userID a unique identifier representing the user associated with the requested profile * @param RequestOpts|null $requestOptions @@ -80,7 +80,7 @@ public function delete( /** * @api * - * Subscribes the given user to one or more lists. If the list does not exist, it will be created. + * Subscribes a user to one or more lists, creating any list that does not yet exist. Optional preferences apply to each subscription. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param list $lists diff --git a/src/Services/ProfilesRawService.php b/src/Services/ProfilesRawService.php index 6719cf05..8b56f22e 100644 --- a/src/Services/ProfilesRawService.php +++ b/src/Services/ProfilesRawService.php @@ -32,7 +32,7 @@ public function __construct(private Client $client) {} /** * @api * - * Merge the supplied values with an existing profile or create a new profile if one doesn't already exist. + * Merges the supplied values into a user's profile, creating it if absent and leaving any key you omit untouched. Prefer this for everyday writes. * * @param string $userID a unique identifier representing the user associated with the requested profile * @param array{profile: array}|ProfileCreateParams $params @@ -65,7 +65,7 @@ public function create( /** * @api * - * Returns the specified user profile. + * Returns a user's stored profile and preferences, including the email address, phone number, and push tokens Courier can reach them on. * * @param string $userID a unique identifier representing the user associated with the requested profile * @param RequestOpts|null $requestOptions @@ -90,7 +90,7 @@ public function retrieve( /** * @api * - * Update a profile + * Applies a JSON Patch to a user profile, adding, removing, or replacing individual fields without sending the whole object. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param array{patch: list}|ProfileUpdateParams $params @@ -123,7 +123,7 @@ public function update( /** * @api * - * Deletes the specified user profile. + * Deletes a user's profile and stored contact details. List subscriptions and preferences are separate resources, so remove those too if required. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param RequestOpts|null $requestOptions @@ -148,10 +148,7 @@ public function delete( /** * @api * - * When using `PUT`, be sure to include all the key-value pairs required by the recipient's profile. - * Any key-value pairs that exist in the profile but fail to be included in the `PUT` request will be - * removed from the profile. Remember, a `PUT` update is a full replacement of the data. For partial updates, - * use the [Patch](https://www.courier.com/docs/reference/profiles/patch/) request. + * Overwrites a user profile in full, removing any key absent from the request body. Use the patch endpoint when changing a single field. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param array{profile: array}|ProfileReplaceParams $params diff --git a/src/Services/ProfilesService.php b/src/Services/ProfilesService.php index 86f7a124..186cc8bf 100644 --- a/src/Services/ProfilesService.php +++ b/src/Services/ProfilesService.php @@ -43,7 +43,7 @@ public function __construct(private Client $client) /** * @api * - * Merge the supplied values with an existing profile or create a new profile if one doesn't already exist. + * Merges the supplied values into a user's profile, creating it if absent and leaving any key you omit untouched. Prefer this for everyday writes. * * @param string $userID a unique identifier representing the user associated with the requested profile * @param array $profile @@ -67,7 +67,7 @@ public function create( /** * @api * - * Returns the specified user profile. + * Returns a user's stored profile and preferences, including the email address, phone number, and push tokens Courier can reach them on. * * @param string $userID a unique identifier representing the user associated with the requested profile * @param RequestOpts|null $requestOptions @@ -87,7 +87,7 @@ public function retrieve( /** * @api * - * Update a profile + * Applies a JSON Patch to a user profile, adding, removing, or replacing individual fields without sending the whole object. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param list $patch list of patch operations to apply to the profile @@ -111,7 +111,7 @@ public function update( /** * @api * - * Deletes the specified user profile. + * Deletes a user's profile and stored contact details. List subscriptions and preferences are separate resources, so remove those too if required. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param RequestOpts|null $requestOptions @@ -131,10 +131,7 @@ public function delete( /** * @api * - * When using `PUT`, be sure to include all the key-value pairs required by the recipient's profile. - * Any key-value pairs that exist in the profile but fail to be included in the `PUT` request will be - * removed from the profile. Remember, a `PUT` update is a full replacement of the data. For partial updates, - * use the [Patch](https://www.courier.com/docs/reference/profiles/patch/) request. + * Overwrites a user profile in full, removing any key absent from the request body. Use the patch endpoint when changing a single field. * * @param string $userID a unique identifier representing the user associated with the requested user profile * @param array $profile diff --git a/src/Services/Providers/CatalogRawService.php b/src/Services/Providers/CatalogRawService.php index 1db120ef..73029352 100644 --- a/src/Services/Providers/CatalogRawService.php +++ b/src/Services/Providers/CatalogRawService.php @@ -26,7 +26,7 @@ public function __construct(private Client $client) {} /** * @api * - * Returns the catalog of available provider types with their display names, descriptions, and configuration schema fields (snake_case, with `type` and `required`). Providers with no configurable schema return only `provider`, `name`, and `description`. + * Returns the provider types Courier supports, each with a display name, description, and the configuration fields it requires. * * @param array{ * channel?: string, keys?: string, name?: string diff --git a/src/Services/Providers/CatalogService.php b/src/Services/Providers/CatalogService.php index d61ef96f..b8e253f6 100644 --- a/src/Services/Providers/CatalogService.php +++ b/src/Services/Providers/CatalogService.php @@ -32,7 +32,7 @@ public function __construct(private Client $client) /** * @api * - * Returns the catalog of available provider types with their display names, descriptions, and configuration schema fields (snake_case, with `type` and `required`). Providers with no configurable schema return only `provider`, `name`, and `description`. + * Returns the provider types Courier supports, each with a display name, description, and the configuration fields it requires. * * @param string $channel Exact match (case-insensitive) against the provider channel taxonomy (e.g. `email`, `sms`, `push`). * @param string $keys Comma-separated provider keys to filter by (e.g. `sendgrid,twilio`). diff --git a/src/Services/ProvidersRawService.php b/src/Services/ProvidersRawService.php index cb08d702..973b7530 100644 --- a/src/Services/ProvidersRawService.php +++ b/src/Services/ProvidersRawService.php @@ -29,7 +29,7 @@ public function __construct(private Client $client) {} /** * @api * - * Create a new provider configuration. The `provider` field must be a known Courier provider key (see catalog). + * Configures a provider integration from a Courier provider key and its settings. Check the catalog endpoint for the schema each provider expects. * * @param array{ * provider: string, @@ -65,7 +65,7 @@ public function create( /** * @api * - * Fetch a single provider configuration by ID. + * Returns one configured provider by id, including its channel, provider key, alias, title, and current settings. * * @param string $id a unique identifier of the provider configuration * @param RequestOpts|null $requestOptions @@ -90,7 +90,7 @@ public function retrieve( /** * @api * - * Replace an existing provider configuration. The `provider` key is required and determines which provider-specific settings schema is applied. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge). Changing the provider type for an existing configuration is not supported. + * Replaces a provider's configuration in full, clearing any field you omit rather than merging it. Send the complete settings object. * * @param string $id a unique identifier of the provider configuration to update * @param array{ @@ -128,7 +128,7 @@ public function update( /** * @api * - * List configured provider integrations for the current workspace. Supports cursor-based pagination. + * Lists the provider integrations configured in the workspace, one entry per channel and provider key with its alias and settings. * * @param array{cursor?: string}|ProviderListParams $params * @param RequestOpts|null $requestOptions @@ -159,7 +159,7 @@ public function list( /** * @api * - * Delete a provider configuration. Returns 409 if the provider is still referenced by routing or notifications. + * Deletes a provider configuration, which fails while routing strategies or templates still reference it. Update those references first. * * @param string $id a unique identifier of the provider configuration to delete * @param RequestOpts|null $requestOptions diff --git a/src/Services/ProvidersService.php b/src/Services/ProvidersService.php index 653213a2..9448bd56 100644 --- a/src/Services/ProvidersService.php +++ b/src/Services/ProvidersService.php @@ -40,7 +40,7 @@ public function __construct(private Client $client) /** * @api * - * Create a new provider configuration. The `provider` field must be a known Courier provider key (see catalog). + * Configures a provider integration from a Courier provider key and its settings. Check the catalog endpoint for the schema each provider expects. * * @param string $provider The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a known Courier provider — see the catalog endpoint for valid keys. * @param string $alias optional alias for this configuration @@ -75,7 +75,7 @@ public function create( /** * @api * - * Fetch a single provider configuration by ID. + * Returns one configured provider by id, including its channel, provider key, alias, title, and current settings. * * @param string $id a unique identifier of the provider configuration * @param RequestOpts|null $requestOptions @@ -95,7 +95,7 @@ public function retrieve( /** * @api * - * Replace an existing provider configuration. The `provider` key is required and determines which provider-specific settings schema is applied. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge). Changing the provider type for an existing configuration is not supported. + * Replaces a provider's configuration in full, clearing any field you omit rather than merging it. Send the complete settings object. * * @param string $id a unique identifier of the provider configuration to update * @param string $provider The provider key identifying the type. Required on every request because it selects the provider-specific settings schema for validation. @@ -132,7 +132,7 @@ public function update( /** * @api * - * List configured provider integrations for the current workspace. Supports cursor-based pagination. + * Lists the provider integrations configured in the workspace, one entry per channel and provider key with its alias and settings. * * @param string $cursor opaque cursor for fetching the next page * @param RequestOpts|null $requestOptions @@ -154,7 +154,7 @@ public function list( /** * @api * - * Delete a provider configuration. Returns 409 if the provider is still referenced by routing or notifications. + * Deletes a provider configuration, which fails while routing strategies or templates still reference it. Update those references first. * * @param string $id a unique identifier of the provider configuration to delete * @param RequestOpts|null $requestOptions diff --git a/src/Services/RequestsRawService.php b/src/Services/RequestsRawService.php index eb61c132..0c3db12a 100644 --- a/src/Services/RequestsRawService.php +++ b/src/Services/RequestsRawService.php @@ -24,7 +24,7 @@ public function __construct(private Client $client) {} /** * @api * - * Archive message + * Archives a send request by its request id. Use it to remove test sends or superseded requests from the message list without deleting them. * * @param string $requestID A unique identifier representing the request ID * @param RequestOpts|null $requestOptions diff --git a/src/Services/RequestsService.php b/src/Services/RequestsService.php index 98dede69..80c81b9f 100644 --- a/src/Services/RequestsService.php +++ b/src/Services/RequestsService.php @@ -30,7 +30,7 @@ public function __construct(private Client $client) /** * @api * - * Archive message + * Archives a send request by its request id. Use it to remove test sends or superseded requests from the message list without deleting them. * * @param string $requestID A unique identifier representing the request ID * @param RequestOpts|null $requestOptions diff --git a/src/Services/RoutingStrategiesRawService.php b/src/Services/RoutingStrategiesRawService.php index d8a1ab6b..5eb5dcd6 100644 --- a/src/Services/RoutingStrategiesRawService.php +++ b/src/Services/RoutingStrategiesRawService.php @@ -75,7 +75,7 @@ public function create( /** * @api * - * Retrieve a routing strategy by ID. Returns the full entity including routing content and metadata. + * Returns one routing strategy by id with its name, tags, channels, and the routing rules that decide provider order and fallback. * * @param string $id routing strategy ID (rs_ prefix) * @param RequestOpts|null $requestOptions @@ -158,7 +158,7 @@ public function archive( /** * @api * - * List notification templates associated with a routing strategy. Includes template metadata only, not full content. + * Returns the notification templates using a routing strategy, with paging. Check this before changing a strategy that templates depend on. * * @param string $id routing strategy ID (`rs_` prefix) * @param array{ diff --git a/src/Services/RoutingStrategiesService.php b/src/Services/RoutingStrategiesService.php index 7dd63e73..739c4266 100644 --- a/src/Services/RoutingStrategiesService.php +++ b/src/Services/RoutingStrategiesService.php @@ -81,7 +81,7 @@ public function create( /** * @api * - * Retrieve a routing strategy by ID. Returns the full entity including routing content and metadata. + * Returns one routing strategy by id with its name, tags, channels, and the routing rules that decide provider order and fallback. * * @param string $id routing strategy ID (rs_ prefix) * @param RequestOpts|null $requestOptions @@ -145,7 +145,7 @@ public function archive( /** * @api * - * List notification templates associated with a routing strategy. Includes template metadata only, not full content. + * Returns the notification templates using a routing strategy, with paging. Check this before changing a strategy that templates depend on. * * @param string $id routing strategy ID (`rs_` prefix) * @param string|null $cursor Opaque pagination cursor from a previous response. Omit for the first page. diff --git a/src/Services/SendRawService.php b/src/Services/SendRawService.php index a50e4628..d54da37a 100644 --- a/src/Services/SendRawService.php +++ b/src/Services/SendRawService.php @@ -28,7 +28,7 @@ public function __construct(private Client $client) {} /** * @api * - * Send a message to one or more recipients. + * Sends a message to one or more recipients and returns a requestId. Courier routes it to email, SMS, push, chat, or in-app based on your rules. * * @param array{message: Message|MessageShape}|SendMessageParams $params * @param RequestOpts|null $requestOptions diff --git a/src/Services/SendService.php b/src/Services/SendService.php index 21189de4..3f86153f 100644 --- a/src/Services/SendService.php +++ b/src/Services/SendService.php @@ -34,7 +34,7 @@ public function __construct(private Client $client) /** * @api * - * Send a message to one or more recipients. + * Sends a message to one or more recipients and returns a requestId. Courier routes it to email, SMS, push, chat, or in-app based on your rules. * * @param Message|MessageShape $message The message property has the following primary top-level properties. They define the destination and content of the message. * @param RequestOpts|null $requestOptions diff --git a/src/Services/Tenants/Preferences/ItemsRawService.php b/src/Services/Tenants/Preferences/ItemsRawService.php index aba75fa1..245009c0 100644 --- a/src/Services/Tenants/Preferences/ItemsRawService.php +++ b/src/Services/Tenants/Preferences/ItemsRawService.php @@ -28,7 +28,7 @@ public function __construct(private Client $client) {} /** * @api * - * Create or Replace Default Preferences For Topic + * Sets a tenant's default opt-in status for one subscription topic, which applies to every member unless a user sets their own override. * * @param string $topicID path param: Id of the subscription topic you want to have a default preference for * @param array{ @@ -70,7 +70,7 @@ public function update( /** * @api * - * Remove Default Preferences For Topic + * Removes a tenant's default preference for one subscription topic, addressed by tenant id and topic id. * * @param string $topicID id of the subscription topic you want to have a default preference for * @param array{tenantID: string}|ItemDeleteParams $params diff --git a/src/Services/Tenants/Preferences/ItemsService.php b/src/Services/Tenants/Preferences/ItemsService.php index efa6bf05..99330ac7 100644 --- a/src/Services/Tenants/Preferences/ItemsService.php +++ b/src/Services/Tenants/Preferences/ItemsService.php @@ -33,7 +33,7 @@ public function __construct(private Client $client) /** * @api * - * Create or Replace Default Preferences For Topic + * Sets a tenant's default opt-in status for one subscription topic, which applies to every member unless a user sets their own override. * * @param string $topicID path param: Id of the subscription topic you want to have a default preference for * @param string $tenantID path param: Id of the tenant to update the default preferences for @@ -70,7 +70,7 @@ public function update( /** * @api * - * Remove Default Preferences For Topic + * Removes a tenant's default preference for one subscription topic, addressed by tenant id and topic id. * * @param string $topicID id of the subscription topic you want to have a default preference for * @param string $tenantID id of the tenant to update the default preferences for diff --git a/src/Services/Tenants/Templates/VersionsRawService.php b/src/Services/Tenants/Templates/VersionsRawService.php index fc28aaae..56369394 100644 --- a/src/Services/Tenants/Templates/VersionsRawService.php +++ b/src/Services/Tenants/Templates/VersionsRawService.php @@ -26,12 +26,7 @@ public function __construct(private Client $client) {} /** * @api * - * Fetches a specific version of a tenant template. - * - * Supports the following version formats: - * - `latest` - The most recent version of the template - * - `published` - The currently published version - * - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0") + * Returns one version of a tenant template, addressed by version number or by latest, with its content and publish timestamp. * * @param string $version Version of the template to retrieve. Accepts "latest", "published", or a specific version string (e.g., "v1", "v2"). * @param array{tenantID: string, templateID: string}|VersionRetrieveParams $params diff --git a/src/Services/Tenants/Templates/VersionsService.php b/src/Services/Tenants/Templates/VersionsService.php index 6a828f0c..9b1e7bd9 100644 --- a/src/Services/Tenants/Templates/VersionsService.php +++ b/src/Services/Tenants/Templates/VersionsService.php @@ -32,12 +32,7 @@ public function __construct(private Client $client) /** * @api * - * Fetches a specific version of a tenant template. - * - * Supports the following version formats: - * - `latest` - The most recent version of the template - * - `published` - The currently published version - * - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0") + * Returns one version of a tenant template, addressed by version number or by latest, with its content and publish timestamp. * * @param string $version Version of the template to retrieve. Accepts "latest", "published", or a specific version string (e.g., "v1", "v2"). * @param string $tenantID id of the tenant for which to retrieve the template diff --git a/src/Services/Tenants/TemplatesRawService.php b/src/Services/Tenants/TemplatesRawService.php index addbded2..fee86fdf 100644 --- a/src/Services/Tenants/TemplatesRawService.php +++ b/src/Services/Tenants/TemplatesRawService.php @@ -35,7 +35,7 @@ public function __construct(private Client $client) {} /** * @api * - * Get a Template in Tenant + * Returns a tenant's notification template with its content, version, and created, updated, and published timestamps. * * @param string $templateID id of the template to be retrieved * @param array{tenantID: string}|TemplateRetrieveParams $params @@ -69,7 +69,7 @@ public function retrieve( /** * @api * - * List Templates in Tenant + * Lists a tenant's notification templates, each carrying its version and published timestamp. Paged. * * @param string $tenantID id of the tenant for which to retrieve the templates * @param array{cursor?: string|null, limit?: int|null}|TemplateListParams $params @@ -102,12 +102,7 @@ public function list( /** * @api * - * Deletes the tenant's notification template with the given `template_id`. - * - * Returns **204 No Content** with an empty body on success. - * - * Returns **404** if there is no template with this ID for the tenant, - * including a second `DELETE` after a successful removal. + * Deletes a tenant's notification template by id. Sends for that tenant then use the workspace template registered under the same id. * * @param string $templateID id of the template to remove from the tenant * @param array{tenantID: string}|TemplateDeleteParams $params @@ -141,10 +136,7 @@ public function delete( /** * @api * - * Publishes a specific version of a notification template for a tenant. - * - * The template must already exist in the tenant's notification map. - * If no version is specified, defaults to publishing the "latest" version. + * Publishes a version of a tenant's notification template, making it the content that tenant's sends render from until you publish another. * * @param string $templateID path param: Id of the template to be published * @param array{tenantID: string, version?: string}|TemplatePublishParams $params @@ -179,12 +171,7 @@ public function publish( /** * @api * - * Creates or updates a notification template for a tenant. - * - * If the template already exists for the tenant, it will be updated (200). - * Otherwise, a new template is created (201). - * - * Optionally publishes the template immediately if the `published` flag is set to true. + * Creates or updates a notification template scoped to one tenant, letting a tenant override the content the workspace template would send. * * @param string $templateID path param: Id of the template to be created or updated * @param array{ diff --git a/src/Services/Tenants/TemplatesService.php b/src/Services/Tenants/TemplatesService.php index 697b0a30..bdc34f45 100644 --- a/src/Services/Tenants/TemplatesService.php +++ b/src/Services/Tenants/TemplatesService.php @@ -44,7 +44,7 @@ public function __construct(private Client $client) /** * @api * - * Get a Template in Tenant + * Returns a tenant's notification template with its content, version, and created, updated, and published timestamps. * * @param string $templateID id of the template to be retrieved * @param string $tenantID id of the tenant for which to retrieve the template @@ -68,7 +68,7 @@ public function retrieve( /** * @api * - * List Templates in Tenant + * Lists a tenant's notification templates, each carrying its version and published timestamp. Paged. * * @param string $tenantID id of the tenant for which to retrieve the templates * @param string|null $cursor Continue the pagination with the next cursor @@ -94,12 +94,7 @@ public function list( /** * @api * - * Deletes the tenant's notification template with the given `template_id`. - * - * Returns **204 No Content** with an empty body on success. - * - * Returns **404** if there is no template with this ID for the tenant, - * including a second `DELETE` after a successful removal. + * Deletes a tenant's notification template by id. Sends for that tenant then use the workspace template registered under the same id. * * @param string $templateID id of the template to remove from the tenant * @param string $tenantID id of the tenant that owns the template @@ -123,10 +118,7 @@ public function delete( /** * @api * - * Publishes a specific version of a notification template for a tenant. - * - * The template must already exist in the tenant's notification map. - * If no version is specified, defaults to publishing the "latest" version. + * Publishes a version of a tenant's notification template, making it the content that tenant's sends render from until you publish another. * * @param string $templateID path param: Id of the template to be published * @param string $tenantID path param: Id of the tenant that owns the template @@ -154,12 +146,7 @@ public function publish( /** * @api * - * Creates or updates a notification template for a tenant. - * - * If the template already exists for the tenant, it will be updated (200). - * Otherwise, a new template is created (201). - * - * Optionally publishes the template immediately if the `published` flag is set to true. + * Creates or updates a notification template scoped to one tenant, letting a tenant override the content the workspace template would send. * * @param string $templateID path param: Id of the template to be created or updated * @param string $tenantID path param: Id of the tenant for which to create or update the template diff --git a/src/Services/TenantsRawService.php b/src/Services/TenantsRawService.php index 960693e6..06e38481 100644 --- a/src/Services/TenantsRawService.php +++ b/src/Services/TenantsRawService.php @@ -33,7 +33,7 @@ public function __construct(private Client $client) {} /** * @api * - * Get a Tenant + * Returns one tenant with its name, parent tenant id, default preferences, properties, and the user profile applied to its members. * * @param string $tenantID a unique identifier representing the tenant to be returned * @param RequestOpts|null $requestOptions @@ -58,7 +58,7 @@ public function retrieve( /** * @api * - * Create or Replace a Tenant + * Creates or replaces a tenant from a name, parent, brand, properties, and default preferences supplied in the request body. * * @param string $tenantID a unique identifier representing the tenant to be returned * @param array{ @@ -98,7 +98,7 @@ public function update( /** * @api * - * Get a List of Tenants + * Lists the workspace's tenants, each carrying a name, parent tenant, properties, and default preferences. Paged. * * @param array{ * cursor?: string|null, limit?: int|null, parentTenantID?: string|null @@ -134,7 +134,7 @@ public function list( /** * @api * - * Delete a Tenant + * Deletes a tenant. Its members' workspace-level profiles and preferences live outside the tenant and are managed separately. * * @param string $tenantID id of the tenant to be deleted * @param RequestOpts|null $requestOptions @@ -159,7 +159,7 @@ public function delete( /** * @api * - * Get Users in Tenant + * Returns the users belonging to a tenant with cursor paging. Use it to see who a tenant-scoped send will reach. * * @param string $tenantID id of the tenant for user membership * @param array{ diff --git a/src/Services/TenantsService.php b/src/Services/TenantsService.php index eba0655f..39111ce0 100644 --- a/src/Services/TenantsService.php +++ b/src/Services/TenantsService.php @@ -50,7 +50,7 @@ public function __construct(private Client $client) /** * @api * - * Get a Tenant + * Returns one tenant with its name, parent tenant id, default preferences, properties, and the user profile applied to its members. * * @param string $tenantID a unique identifier representing the tenant to be returned * @param RequestOpts|null $requestOptions @@ -70,7 +70,7 @@ public function retrieve( /** * @api * - * Create or Replace a Tenant + * Creates or replaces a tenant from a name, parent, brand, properties, and default preferences supplied in the request body. * * @param string $tenantID a unique identifier representing the tenant to be returned * @param string $name name of the tenant @@ -113,7 +113,7 @@ public function update( /** * @api * - * Get a List of Tenants + * Lists the workspace's tenants, each carrying a name, parent tenant, properties, and default preferences. Paged. * * @param string|null $cursor Continue the pagination with the next cursor * @param int|null $limit The number of tenants to return @@ -146,7 +146,7 @@ public function list( /** * @api * - * Delete a Tenant + * Deletes a tenant. Its members' workspace-level profiles and preferences live outside the tenant and are managed separately. * * @param string $tenantID id of the tenant to be deleted * @param RequestOpts|null $requestOptions @@ -166,7 +166,7 @@ public function delete( /** * @api * - * Get Users in Tenant + * Returns the users belonging to a tenant with cursor paging. Use it to see who a tenant-scoped send will reach. * * @param string $tenantID id of the tenant for user membership * @param string|null $cursor Continue the pagination with the next cursor diff --git a/src/Services/TranslationsRawService.php b/src/Services/TranslationsRawService.php index 272d1f79..511516ae 100644 --- a/src/Services/TranslationsRawService.php +++ b/src/Services/TranslationsRawService.php @@ -26,7 +26,7 @@ public function __construct(private Client $client) {} /** * @api * - * Get translations by locale + * Returns the translation strings stored for one domain and locale, for use in localized notification content. * * @param string $locale The locale you want to retrieve the translations for * @param array{domain: string}|TranslationRetrieveParams $params @@ -60,7 +60,7 @@ public function retrieve( /** * @api * - * Update a translation + * Uploads the translation strings for one domain and locale. Courier uses them to render localized content for recipients in that locale. * * @param string $locale Path param: The locale you want to retrieve the translations for * @param array{domain: string, body: string}|TranslationUpdateParams $params diff --git a/src/Services/TranslationsService.php b/src/Services/TranslationsService.php index 188a1a02..d421914d 100644 --- a/src/Services/TranslationsService.php +++ b/src/Services/TranslationsService.php @@ -31,7 +31,7 @@ public function __construct(private Client $client) /** * @api * - * Get translations by locale + * Returns the translation strings stored for one domain and locale, for use in localized notification content. * * @param string $locale The locale you want to retrieve the translations for * @param string $domain The domain you want to retrieve translations for. Only `default` is supported at the moment @@ -55,7 +55,7 @@ public function retrieve( /** * @api * - * Update a translation + * Uploads the translation strings for one domain and locale. Courier uses them to render localized content for recipients in that locale. * * @param string $locale Path param: The locale you want to retrieve the translations for * @param string $domain Path param: The domain you want to retrieve translations for. Only `default` is supported at the moment diff --git a/src/Services/Users/PreferencesRawService.php b/src/Services/Users/PreferencesRawService.php index 0405f5e0..d42c06eb 100644 --- a/src/Services/Users/PreferencesRawService.php +++ b/src/Services/Users/PreferencesRawService.php @@ -40,7 +40,7 @@ public function __construct(private Client $client) {} /** * @api * - * Fetch all user preferences. + * Returns a user's preference overrides with paging, one entry per subscription topic they have set a choice for. * * @param string $userID a unique identifier associated with the user whose preferences you wish to retrieve * @param array{tenantID?: string|null}|PreferenceRetrieveParams $params @@ -73,11 +73,7 @@ public function retrieve( /** * @api * - * Replace a user's complete set of preference overrides in a single request. The topics in the request body become the recipient's entire set of overrides: listed topics are created or updated, and every existing override that is not included in the body is reset to its topic default. Submitting an empty `topics` array is a valid clear-all that resets every existing override. - * - * This operation is validation-atomic (all-or-nothing): structural validation fails fast with a single `400`, and if any topic is semantically invalid (an unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing request that is not available on the workspace's plan) the request returns a single `400` aggregating every failure in `errors` and writes nothing. On success it returns `200` with `items` (the complete resulting override set) and `deleted` (the ids of the overrides that were reset to default). - * - * Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. + * Replaces a user's entire set of preference overrides. Any topic you leave out is reset to its default, so send the full set rather than a subset. * * @param string $userID path param: A unique identifier associated with the user whose preferences you wish to update * @param array{ @@ -118,11 +114,7 @@ public function bulkReplace( /** * @api * - * Additively create or update a user's preferences for one or more subscription topics in a single request. Only the topics included in the request body are created or updated; any existing overrides for topics not listed are left untouched. - * - * Structural validation of the request body fails fast with a single `400`. Beyond that, each topic is processed independently (partial-success, not all-or-nothing): valid topics are written and returned in `items`, while topics that cannot be applied are collected in `errors` with a per-topic `reason` (for example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom routing request that is not available on the workspace's plan, or a write failure). The request therefore returns `200` with both lists whenever the body is structurally valid. - * - * Every `topic_id` in the response — in both `items` and `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. + * Adds or updates a user's preferences for several subscription topics at once. Topics you leave out keep whatever they were set to before. * * @param string $userID path param: A unique identifier associated with the user whose preferences you wish to update * @param array{ @@ -163,7 +155,7 @@ public function bulkUpdate( /** * @api * - * Remove a user's preferences for a specific subscription topic, resetting the topic to its effective default. This operation is idempotent: deleting a preference that does not exist succeeds with no error. + * Removes a user's override for one subscription topic, resetting it to the effective default from the tenant or workspace. * * @param string $topicID path param: A unique identifier associated with a subscription topic * @param array{ @@ -200,7 +192,7 @@ public function deleteTopic( /** * @api * - * Fetch user preferences for a specific subscription topic. + * Returns a user's opt-in status and channel choices for one subscription topic, or the effective default if they have set no override. * * @param string $topicID path param: A unique identifier associated with a subscription topic * @param array{ @@ -237,7 +229,7 @@ public function retrieveTopic( /** * @api * - * Update or Create user preferences for a specific subscription topic. + * Sets a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only. * * @param string $topicID path param: A unique identifier associated with a subscription topic * @param array{ diff --git a/src/Services/Users/PreferencesService.php b/src/Services/Users/PreferencesService.php index 5009f9b4..a1a69017 100644 --- a/src/Services/Users/PreferencesService.php +++ b/src/Services/Users/PreferencesService.php @@ -40,7 +40,7 @@ public function __construct(private Client $client) /** * @api * - * Fetch all user preferences. + * Returns a user's preference overrides with paging, one entry per subscription topic they have set a choice for. * * @param string $userID a unique identifier associated with the user whose preferences you wish to retrieve * @param string|null $tenantID query the preferences of a user for this specific tenant context @@ -64,11 +64,7 @@ public function retrieve( /** * @api * - * Replace a user's complete set of preference overrides in a single request. The topics in the request body become the recipient's entire set of overrides: listed topics are created or updated, and every existing override that is not included in the body is reset to its topic default. Submitting an empty `topics` array is a valid clear-all that resets every existing override. - * - * This operation is validation-atomic (all-or-nothing): structural validation fails fast with a single `400`, and if any topic is semantically invalid (an unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing request that is not available on the workspace's plan) the request returns a single `400` aggregating every failure in `errors` and writes nothing. On success it returns `200` with `items` (the complete resulting override set) and `deleted` (the ids of the overrides that were reset to default). - * - * Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. + * Replaces a user's entire set of preference overrides. Any topic you leave out is reset to its default, so send the full set rather than a subset. * * @param string $userID path param: A unique identifier associated with the user whose preferences you wish to update * @param list<\Courier\Users\Preferences\PreferenceBulkReplaceParams\Topic|TopicShape1> $topics Body param: The complete set of topic overrides for the user. Up to 50 topics may be provided. Any existing override not listed here is reset to its topic default; an empty array resets every existing override. @@ -94,11 +90,7 @@ public function bulkReplace( /** * @api * - * Additively create or update a user's preferences for one or more subscription topics in a single request. Only the topics included in the request body are created or updated; any existing overrides for topics not listed are left untouched. - * - * Structural validation of the request body fails fast with a single `400`. Beyond that, each topic is processed independently (partial-success, not all-or-nothing): valid topics are written and returned in `items`, while topics that cannot be applied are collected in `errors` with a per-topic `reason` (for example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom routing request that is not available on the workspace's plan, or a write failure). The request therefore returns `200` with both lists whenever the body is structurally valid. - * - * Every `topic_id` in the response — in both `items` and `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. + * Adds or updates a user's preferences for several subscription topics at once. Topics you leave out keep whatever they were set to before. * * @param string $userID path param: A unique identifier associated with the user whose preferences you wish to update * @param list<\Courier\Users\Preferences\PreferenceBulkUpdateParams\Topic|TopicShape2> $topics Body param: The topics to create or update. Between 1 and 50 topics may be provided in a single request. @@ -124,7 +116,7 @@ public function bulkUpdate( /** * @api * - * Remove a user's preferences for a specific subscription topic, resetting the topic to its effective default. This operation is idempotent: deleting a preference that does not exist succeeds with no error. + * Removes a user's override for one subscription topic, resetting it to the effective default from the tenant or workspace. * * @param string $topicID path param: A unique identifier associated with a subscription topic * @param string $userID path param: A unique identifier associated with the user whose preferences you wish to delete @@ -150,7 +142,7 @@ public function deleteTopic( /** * @api * - * Fetch user preferences for a specific subscription topic. + * Returns a user's opt-in status and channel choices for one subscription topic, or the effective default if they have set no override. * * @param string $topicID path param: A unique identifier associated with a subscription topic * @param string $userID path param: A unique identifier associated with the user whose preferences you wish to retrieve @@ -176,7 +168,7 @@ public function retrieveTopic( /** * @api * - * Update or Create user preferences for a specific subscription topic. + * Sets a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only. * * @param string $topicID path param: A unique identifier associated with a subscription topic * @param string $userID path param: A unique identifier associated with the user whose preferences you wish to retrieve diff --git a/src/Services/Users/TenantsRawService.php b/src/Services/Users/TenantsRawService.php index 5e70cf13..ed3a4b90 100644 --- a/src/Services/Users/TenantsRawService.php +++ b/src/Services/Users/TenantsRawService.php @@ -31,7 +31,7 @@ public function __construct(private Client $client) {} /** * @api * - * Returns a paginated list of user tenant associations. + * Returns the tenants a user belongs to, with cursor paging. A user can belong to many tenants, each with its own profile and preferences. * * @param string $userID id of the user to retrieve all associated tenants for * @param array{cursor?: string|null, limit?: int|null}|TenantListParams $params @@ -64,11 +64,7 @@ public function list( /** * @api * - * This endpoint is used to add a user to - * multiple tenants in one call. - * A custom profile can also be supplied for each tenant. - * This profile will be merged with the user's main - * profile when sending to the user with that tenant. + * Adds a user to several tenants in one call, each optionally with a per-tenant profile that overrides their workspace profile. * * @param string $userID The user's ID. This can be any uniquely identifiable string. * @param array{ @@ -103,11 +99,7 @@ public function addMultiple( /** * @api * - * This endpoint is used to add a single tenant. - * - * A custom profile can also be supplied with the tenant. - * This profile will be merged with the user's main profile - * when sending to the user with that tenant. + * Adds a user to one tenant, optionally with a tenant-specific profile that overrides their workspace profile for sends in that tenant. * * @param string $tenantID path param: Id of the tenant the user should be added to * @param array{ @@ -144,7 +136,7 @@ public function addSingle( /** * @api * - * Removes a user from any tenants they may have been associated with. + * Removes a user from every tenant they belong to in one call. Their workspace-level profile is a separate resource. * * @param string $userID id of the user to be removed from the supplied tenant * @param RequestOpts|null $requestOptions @@ -169,7 +161,7 @@ public function removeAll( /** * @api * - * Removes a user from the supplied tenant. + * Removes a user from one tenant. Their other tenant memberships and workspace profile are managed through separate endpoints. * * @param string $tenantID id of the tenant the user should be removed from * @param array{userID: string}|TenantRemoveSingleParams $params diff --git a/src/Services/Users/TenantsService.php b/src/Services/Users/TenantsService.php index 09d5d8ae..febf3d9a 100644 --- a/src/Services/Users/TenantsService.php +++ b/src/Services/Users/TenantsService.php @@ -34,7 +34,7 @@ public function __construct(private Client $client) /** * @api * - * Returns a paginated list of user tenant associations. + * Returns the tenants a user belongs to, with cursor paging. A user can belong to many tenants, each with its own profile and preferences. * * @param string $userID id of the user to retrieve all associated tenants for * @param string|null $cursor Continue the pagination with the next cursor @@ -61,11 +61,7 @@ public function list( /** * @api * - * This endpoint is used to add a user to - * multiple tenants in one call. - * A custom profile can also be supplied for each tenant. - * This profile will be merged with the user's main - * profile when sending to the user with that tenant. + * Adds a user to several tenants in one call, each optionally with a per-tenant profile that overrides their workspace profile. * * @param string $userID The user's ID. This can be any uniquely identifiable string. * @param list $tenants @@ -89,11 +85,7 @@ public function addMultiple( /** * @api * - * This endpoint is used to add a single tenant. - * - * A custom profile can also be supplied with the tenant. - * This profile will be merged with the user's main profile - * when sending to the user with that tenant. + * Adds a user to one tenant, optionally with a tenant-specific profile that overrides their workspace profile for sends in that tenant. * * @param string $tenantID path param: Id of the tenant the user should be added to * @param string $userID path param: Id of the user to be added to the supplied tenant @@ -119,7 +111,7 @@ public function addSingle( /** * @api * - * Removes a user from any tenants they may have been associated with. + * Removes a user from every tenant they belong to in one call. Their workspace-level profile is a separate resource. * * @param string $userID id of the user to be removed from the supplied tenant * @param RequestOpts|null $requestOptions @@ -139,7 +131,7 @@ public function removeAll( /** * @api * - * Removes a user from the supplied tenant. + * Removes a user from one tenant. Their other tenant memberships and workspace profile are managed through separate endpoints. * * @param string $tenantID id of the tenant the user should be removed from * @param string $userID id of the user to be removed from the supplied tenant diff --git a/src/Services/Users/TokensRawService.php b/src/Services/Users/TokensRawService.php index a5e2fc0e..81c3994a 100644 --- a/src/Services/Users/TokensRawService.php +++ b/src/Services/Users/TokensRawService.php @@ -38,7 +38,7 @@ public function __construct(private Client $client) {} /** * @api * - * Get single token available for a `:token` + * Returns one device token with its provider key, status and status reason, expiry date, and any properties stored alongside it. * * @param string $token the full token string * @param array{userID: string}|TokenRetrieveParams $params @@ -72,7 +72,7 @@ public function retrieve( /** * @api * - * Apply a JSON Patch (RFC 6902) to the specified token. + * Applies a JSON Patch to a device token, changing its status, expiry, or properties without re-registering it. * * @param string $token path param: The full token string * @param array{ @@ -109,7 +109,7 @@ public function update( /** * @api * - * Gets all tokens available for a :user_id + * Returns every device token registered for a user, each with its provider key, status, and expiry date. * * @param string $userID The user's ID. This can be any uniquely identifiable string. * @param RequestOpts|null $requestOptions @@ -134,7 +134,7 @@ public function list( /** * @api * - * Delete User Token + * Deletes one device token for a user, addressed by the token value, so push sends no longer target that device. * * @param string $token the full token string * @param array{userID: string}|TokenDeleteParams $params @@ -168,7 +168,7 @@ public function delete( /** * @api * - * Adds multiple tokens to a user and overwrites matching existing tokens. + * Registers several device tokens for a user in one call, overwriting any stored token with a matching value. * * @param string $userID The user's ID. This can be any uniquely identifiable string. * @param RequestOpts|null $requestOptions @@ -193,7 +193,7 @@ public function addMultiple( /** * @api * - * Adds a single token to a user and overwrites a matching existing token. + * Registers one device token for a user against a provider key, overwriting the token if it already exists. Push sends resolve tokens per user. * * @param string $token path param: The full token string * @param array{ diff --git a/src/Services/Users/TokensService.php b/src/Services/Users/TokensService.php index 41b5a717..5db71ad0 100644 --- a/src/Services/Users/TokensService.php +++ b/src/Services/Users/TokensService.php @@ -41,7 +41,7 @@ public function __construct(private Client $client) /** * @api * - * Get single token available for a `:token` + * Returns one device token with its provider key, status and status reason, expiry date, and any properties stored alongside it. * * @param string $token the full token string * @param string $userID The user's ID. This can be any uniquely identifiable string. @@ -65,7 +65,7 @@ public function retrieve( /** * @api * - * Apply a JSON Patch (RFC 6902) to the specified token. + * Applies a JSON Patch to a device token, changing its status, expiry, or properties without re-registering it. * * @param string $token path param: The full token string * @param string $userID Path param: The user's ID. This can be any uniquely identifiable string. @@ -91,7 +91,7 @@ public function update( /** * @api * - * Gets all tokens available for a :user_id + * Returns every device token registered for a user, each with its provider key, status, and expiry date. * * @param string $userID The user's ID. This can be any uniquely identifiable string. * @param RequestOpts|null $requestOptions @@ -111,7 +111,7 @@ public function list( /** * @api * - * Delete User Token + * Deletes one device token for a user, addressed by the token value, so push sends no longer target that device. * * @param string $token the full token string * @param string $userID The user's ID. This can be any uniquely identifiable string. @@ -135,7 +135,7 @@ public function delete( /** * @api * - * Adds multiple tokens to a user and overwrites matching existing tokens. + * Registers several device tokens for a user in one call, overwriting any stored token with a matching value. * * @param string $userID The user's ID. This can be any uniquely identifiable string. * @param RequestOpts|null $requestOptions @@ -155,7 +155,7 @@ public function addMultiple( /** * @api * - * Adds a single token to a user and overwrites a matching existing token. + * Registers one device token for a user against a provider key, overwriting the token if it already exists. Push sends resolve tokens per user. * * @param string $token path param: The full token string * @param string $userID Path param: The user's ID. This can be any uniquely identifiable string. diff --git a/src/Services/WorkspacePreferences/TopicsRawService.php b/src/Services/WorkspacePreferences/TopicsRawService.php index 8c4f4ba1..2cf47fda 100644 --- a/src/Services/WorkspacePreferences/TopicsRawService.php +++ b/src/Services/WorkspacePreferences/TopicsRawService.php @@ -33,7 +33,7 @@ public function __construct(private Client $client) {} /** * @api * - * Create a subscription preference topic inside a workspace preference. Fails with 404 if the workspace preference does not exist. The topic id is generated and returned. + * Creates a subscription topic inside a workspace preference. The default status sets whether users start opted in, opted out, or required. * * @param string $sectionID id of the workspace preference to create the topic in * @param array{ @@ -74,7 +74,7 @@ public function create( /** * @api * - * Retrieve a topic within a workspace preference. Returns 404 if the workspace preference does not exist, the topic does not exist, or the topic belongs to a different workspace preference. + * Returns one subscription topic with its default status, routing options, allowed preferences, and unsubscribe header setting. * * @param string $topicID id of the subscription preference topic * @param array{sectionID: string}|TopicRetrieveParams $params @@ -108,7 +108,7 @@ public function retrieve( /** * @api * - * List the topics in a workspace preference. + * Returns the subscription topics inside a workspace preference, each with its default status and routing options. * * @param string $sectionID id of the workspace preference * @param RequestOpts|null $requestOptions @@ -133,7 +133,7 @@ public function list( /** * @api * - * Archive a topic and remove it from its workspace preference. Same 404 rules as GET. + * Archives a subscription topic and removes it from its workspace preference, addressed by section id and topic id. * * @param string $topicID id of the subscription preference topic * @param array{sectionID: string}|TopicArchiveParams $params diff --git a/src/Services/WorkspacePreferences/TopicsService.php b/src/Services/WorkspacePreferences/TopicsService.php index b0d35ac5..190cf8df 100644 --- a/src/Services/WorkspacePreferences/TopicsService.php +++ b/src/Services/WorkspacePreferences/TopicsService.php @@ -36,7 +36,7 @@ public function __construct(private Client $client) /** * @api * - * Create a subscription preference topic inside a workspace preference. Fails with 404 if the workspace preference does not exist. The topic id is generated and returned. + * Creates a subscription topic inside a workspace preference. The default status sets whether users start opted in, opted out, or required. * * @param string $sectionID id of the workspace preference to create the topic in * @param DefaultStatus|value-of $defaultStatus the default subscription status applied when a recipient has not set their own @@ -82,7 +82,7 @@ public function create( /** * @api * - * Retrieve a topic within a workspace preference. Returns 404 if the workspace preference does not exist, the topic does not exist, or the topic belongs to a different workspace preference. + * Returns one subscription topic with its default status, routing options, allowed preferences, and unsubscribe header setting. * * @param string $topicID id of the subscription preference topic * @param string $sectionID id of the workspace preference @@ -106,7 +106,7 @@ public function retrieve( /** * @api * - * List the topics in a workspace preference. + * Returns the subscription topics inside a workspace preference, each with its default status and routing options. * * @param string $sectionID id of the workspace preference * @param RequestOpts|null $requestOptions @@ -126,7 +126,7 @@ public function list( /** * @api * - * Archive a topic and remove it from its workspace preference. Same 404 rules as GET. + * Archives a subscription topic and removes it from its workspace preference, addressed by section id and topic id. * * @param string $topicID id of the subscription preference topic * @param string $sectionID id of the workspace preference diff --git a/src/Services/WorkspacePreferencesRawService.php b/src/Services/WorkspacePreferencesRawService.php index e8942902..ce3f0e32 100644 --- a/src/Services/WorkspacePreferencesRawService.php +++ b/src/Services/WorkspacePreferencesRawService.php @@ -31,7 +31,7 @@ public function __construct(private Client $client) {} /** * @api * - * Create a workspace preference. The workspace preference id is generated and returned. Topics are created inside a workspace preference via POST /preferences/sections/{section_id}/topics. + * Creates a workspace preference and returns its generated id. Add subscription topics to it afterwards with the topics endpoint. * * @param array{ * name: string, @@ -67,7 +67,7 @@ public function create( /** * @api * - * Retrieve a workspace preference by id, including its topics. + * Returns one workspace preference by id, including its subscription topics, routing options, and custom routing flag. * * @param string $sectionID id of the workspace preference * @param RequestOpts|null $requestOptions @@ -92,7 +92,7 @@ public function retrieve( /** * @api * - * List the workspace's preferences. Each workspace preference embeds its topics. Scoped to the workspace of the API key. + * Returns the workspace's preferences, each embedding its subscription topics, routing options, and whether custom routing is allowed. * * @param RequestOpts|null $requestOptions * @@ -140,7 +140,7 @@ public function archive( /** * @api * - * Publish the workspace's preferences page. Takes a snapshot of every workspace preference with its topics under a new published version, making the current state visible on the hosted preferences page (non-draft). + * Publishes the workspace preference page, snapshotting every preference and topic, and returns the page id and a preview URL. * * @param array{ * brandID?: string|null, description?: string|null, heading?: string|null diff --git a/src/Services/WorkspacePreferencesService.php b/src/Services/WorkspacePreferencesService.php index 75a91504..d596709e 100644 --- a/src/Services/WorkspacePreferencesService.php +++ b/src/Services/WorkspacePreferencesService.php @@ -42,7 +42,7 @@ public function __construct(private Client $client) /** * @api * - * Create a workspace preference. The workspace preference id is generated and returned. Topics are created inside a workspace preference via POST /preferences/sections/{section_id}/topics. + * Creates a workspace preference and returns its generated id. Add subscription topics to it afterwards with the topics endpoint. * * @param string $name human-readable name for the workspace preference * @param string|null $description optional description shown under the section on the hosted preferences page @@ -77,7 +77,7 @@ public function create( /** * @api * - * Retrieve a workspace preference by id, including its topics. + * Returns one workspace preference by id, including its subscription topics, routing options, and custom routing flag. * * @param string $sectionID id of the workspace preference * @param RequestOpts|null $requestOptions @@ -97,7 +97,7 @@ public function retrieve( /** * @api * - * List the workspace's preferences. Each workspace preference embeds its topics. Scoped to the workspace of the API key. + * Returns the workspace's preferences, each embedding its subscription topics, routing options, and whether custom routing is allowed. * * @param RequestOpts|null $requestOptions * @@ -135,7 +135,7 @@ public function archive( /** * @api * - * Publish the workspace's preferences page. Takes a snapshot of every workspace preference with its topics under a new published version, making the current state visible on the hosted preferences page (non-draft). + * Publishes the workspace preference page, snapshotting every preference and topic, and returns the page id and a preview URL. * * @param string|null $brandID Brand for the hosted page - "default" (workspace default brand), "none" (no brand), or a specific brand id. Defaults to "default". * @param string|null $description description shown under the heading on the hosted preferences page diff --git a/src/Tenants/Preferences/Items/ItemDeleteParams.php b/src/Tenants/Preferences/Items/ItemDeleteParams.php index e045db90..5a6d7430 100644 --- a/src/Tenants/Preferences/Items/ItemDeleteParams.php +++ b/src/Tenants/Preferences/Items/ItemDeleteParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Remove Default Preferences For Topic. + * Removes a tenant's default preference for one subscription topic, addressed by tenant id and topic id. * * @see Courier\Services\Tenants\Preferences\ItemsService::delete() * diff --git a/src/Tenants/Preferences/Items/ItemUpdateParams.php b/src/Tenants/Preferences/Items/ItemUpdateParams.php index 377d82d0..34a157db 100644 --- a/src/Tenants/Preferences/Items/ItemUpdateParams.php +++ b/src/Tenants/Preferences/Items/ItemUpdateParams.php @@ -13,7 +13,7 @@ use Courier\Tenants\Preferences\Items\ItemUpdateParams\Status; /** - * Create or Replace Default Preferences For Topic. + * Sets a tenant's default opt-in status for one subscription topic, which applies to every member unless a user sets their own override. * * @see Courier\Services\Tenants\Preferences\ItemsService::update() * diff --git a/src/Tenants/Templates/TemplateDeleteParams.php b/src/Tenants/Templates/TemplateDeleteParams.php index aff27e36..87d2bdcf 100644 --- a/src/Tenants/Templates/TemplateDeleteParams.php +++ b/src/Tenants/Templates/TemplateDeleteParams.php @@ -10,12 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Deletes the tenant's notification template with the given `template_id`. - * - * Returns **204 No Content** with an empty body on success. - * - * Returns **404** if there is no template with this ID for the tenant, - * including a second `DELETE` after a successful removal. + * Deletes a tenant's notification template by id. Sends for that tenant then use the workspace template registered under the same id. * * @see Courier\Services\Tenants\TemplatesService::delete() * diff --git a/src/Tenants/Templates/TemplateListParams.php b/src/Tenants/Templates/TemplateListParams.php index 55f0d416..ee3207ea 100644 --- a/src/Tenants/Templates/TemplateListParams.php +++ b/src/Tenants/Templates/TemplateListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * List Templates in Tenant. + * Lists a tenant's notification templates, each carrying its version and published timestamp. Paged. * * @see Courier\Services\Tenants\TemplatesService::list() * diff --git a/src/Tenants/Templates/TemplatePublishParams.php b/src/Tenants/Templates/TemplatePublishParams.php index 544e86e3..64c963ca 100644 --- a/src/Tenants/Templates/TemplatePublishParams.php +++ b/src/Tenants/Templates/TemplatePublishParams.php @@ -11,10 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Publishes a specific version of a notification template for a tenant. - * - * The template must already exist in the tenant's notification map. - * If no version is specified, defaults to publishing the "latest" version. + * Publishes a version of a tenant's notification template, making it the content that tenant's sends render from until you publish another. * * @see Courier\Services\Tenants\TemplatesService::publish() * diff --git a/src/Tenants/Templates/TemplateReplaceParams.php b/src/Tenants/Templates/TemplateReplaceParams.php index 8723ee91..a03d6018 100644 --- a/src/Tenants/Templates/TemplateReplaceParams.php +++ b/src/Tenants/Templates/TemplateReplaceParams.php @@ -12,12 +12,7 @@ use Courier\Tenants\TenantTemplateInput; /** - * Creates or updates a notification template for a tenant. - * - * If the template already exists for the tenant, it will be updated (200). - * Otherwise, a new template is created (201). - * - * Optionally publishes the template immediately if the `published` flag is set to true. + * Creates or updates a notification template scoped to one tenant, letting a tenant override the content the workspace template would send. * * @see Courier\Services\Tenants\TemplatesService::replace() * diff --git a/src/Tenants/Templates/TemplateRetrieveParams.php b/src/Tenants/Templates/TemplateRetrieveParams.php index 97b137e1..5c1f4294 100644 --- a/src/Tenants/Templates/TemplateRetrieveParams.php +++ b/src/Tenants/Templates/TemplateRetrieveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get a Template in Tenant. + * Returns a tenant's notification template with its content, version, and created, updated, and published timestamps. * * @see Courier\Services\Tenants\TemplatesService::retrieve() * diff --git a/src/Tenants/Templates/Versions/VersionRetrieveParams.php b/src/Tenants/Templates/Versions/VersionRetrieveParams.php index 6af85009..20414039 100644 --- a/src/Tenants/Templates/Versions/VersionRetrieveParams.php +++ b/src/Tenants/Templates/Versions/VersionRetrieveParams.php @@ -10,12 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Fetches a specific version of a tenant template. - * - * Supports the following version formats: - * - `latest` - The most recent version of the template - * - `published` - The currently published version - * - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0") + * Returns one version of a tenant template, addressed by version number or by latest, with its content and publish timestamp. * * @see Courier\Services\Tenants\Templates\VersionsService::retrieve() * diff --git a/src/Tenants/TenantListParams.php b/src/Tenants/TenantListParams.php index 981fa579..6ef0f308 100644 --- a/src/Tenants/TenantListParams.php +++ b/src/Tenants/TenantListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get a List of Tenants. + * Lists the workspace's tenants, each carrying a name, parent tenant, properties, and default preferences. Paged. * * @see Courier\Services\TenantsService::list() * diff --git a/src/Tenants/TenantListUsersParams.php b/src/Tenants/TenantListUsersParams.php index 7feda665..88e99b2a 100644 --- a/src/Tenants/TenantListUsersParams.php +++ b/src/Tenants/TenantListUsersParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get Users in Tenant. + * Returns the users belonging to a tenant with cursor paging. Use it to see who a tenant-scoped send will reach. * * @see Courier\Services\TenantsService::listUsers() * diff --git a/src/Tenants/TenantUpdateParams.php b/src/Tenants/TenantUpdateParams.php index 91c933e5..2d8a7db4 100644 --- a/src/Tenants/TenantUpdateParams.php +++ b/src/Tenants/TenantUpdateParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Create or Replace a Tenant. + * Creates or replaces a tenant from a name, parent, brand, properties, and default preferences supplied in the request body. * * @see Courier\Services\TenantsService::update() * diff --git a/src/Translations/TranslationRetrieveParams.php b/src/Translations/TranslationRetrieveParams.php index 42ae525d..232cc584 100644 --- a/src/Translations/TranslationRetrieveParams.php +++ b/src/Translations/TranslationRetrieveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get translations by locale. + * Returns the translation strings stored for one domain and locale, for use in localized notification content. * * @see Courier\Services\TranslationsService::retrieve() * diff --git a/src/Translations/TranslationUpdateParams.php b/src/Translations/TranslationUpdateParams.php index 46d1c41c..4fb107c9 100644 --- a/src/Translations/TranslationUpdateParams.php +++ b/src/Translations/TranslationUpdateParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Update a translation. + * Uploads the translation strings for one domain and locale. Courier uses them to render localized content for recipients in that locale. * * @see Courier\Services\TranslationsService::update() * diff --git a/src/Users/Preferences/PreferenceBulkReplaceParams.php b/src/Users/Preferences/PreferenceBulkReplaceParams.php index 542fd82c..81844114 100644 --- a/src/Users/Preferences/PreferenceBulkReplaceParams.php +++ b/src/Users/Preferences/PreferenceBulkReplaceParams.php @@ -12,11 +12,7 @@ use Courier\Users\Preferences\PreferenceBulkReplaceParams\Topic; /** - * Replace a user's complete set of preference overrides in a single request. The topics in the request body become the recipient's entire set of overrides: listed topics are created or updated, and every existing override that is not included in the body is reset to its topic default. Submitting an empty `topics` array is a valid clear-all that resets every existing override. - * - * This operation is validation-atomic (all-or-nothing): structural validation fails fast with a single `400`, and if any topic is semantically invalid (an unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing request that is not available on the workspace's plan) the request returns a single `400` aggregating every failure in `errors` and writes nothing. On success it returns `200` with `items` (the complete resulting override set) and `deleted` (the ids of the overrides that were reset to default). - * - * Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. + * Replaces a user's entire set of preference overrides. Any topic you leave out is reset to its default, so send the full set rather than a subset. * * @see Courier\Services\Users\PreferencesService::bulkReplace() * diff --git a/src/Users/Preferences/PreferenceBulkUpdateParams.php b/src/Users/Preferences/PreferenceBulkUpdateParams.php index 6bef1dfd..919f09c4 100644 --- a/src/Users/Preferences/PreferenceBulkUpdateParams.php +++ b/src/Users/Preferences/PreferenceBulkUpdateParams.php @@ -12,11 +12,7 @@ use Courier\Users\Preferences\PreferenceBulkUpdateParams\Topic; /** - * Additively create or update a user's preferences for one or more subscription topics in a single request. Only the topics included in the request body are created or updated; any existing overrides for topics not listed are left untouched. - * - * Structural validation of the request body fails fast with a single `400`. Beyond that, each topic is processed independently (partial-success, not all-or-nothing): valid topics are written and returned in `items`, while topics that cannot be applied are collected in `errors` with a per-topic `reason` (for example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom routing request that is not available on the workspace's plan, or a write failure). The request therefore returns `200` with both lists whenever the body is structurally valid. - * - * Every `topic_id` in the response — in both `items` and `errors` — is returned in Courier's canonical topic id form, regardless of the form supplied in the request. + * Adds or updates a user's preferences for several subscription topics at once. Topics you leave out keep whatever they were set to before. * * @see Courier\Services\Users\PreferencesService::bulkUpdate() * diff --git a/src/Users/Preferences/PreferenceDeleteTopicParams.php b/src/Users/Preferences/PreferenceDeleteTopicParams.php index 1da1758a..3a928531 100644 --- a/src/Users/Preferences/PreferenceDeleteTopicParams.php +++ b/src/Users/Preferences/PreferenceDeleteTopicParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Remove a user's preferences for a specific subscription topic, resetting the topic to its effective default. This operation is idempotent: deleting a preference that does not exist succeeds with no error. + * Removes a user's override for one subscription topic, resetting it to the effective default from the tenant or workspace. * * @see Courier\Services\Users\PreferencesService::deleteTopic() * diff --git a/src/Users/Preferences/PreferenceRetrieveParams.php b/src/Users/Preferences/PreferenceRetrieveParams.php index 972a450d..3659b393 100644 --- a/src/Users/Preferences/PreferenceRetrieveParams.php +++ b/src/Users/Preferences/PreferenceRetrieveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Fetch all user preferences. + * Returns a user's preference overrides with paging, one entry per subscription topic they have set a choice for. * * @see Courier\Services\Users\PreferencesService::retrieve() * diff --git a/src/Users/Preferences/PreferenceRetrieveTopicParams.php b/src/Users/Preferences/PreferenceRetrieveTopicParams.php index 24735f8c..0488c483 100644 --- a/src/Users/Preferences/PreferenceRetrieveTopicParams.php +++ b/src/Users/Preferences/PreferenceRetrieveTopicParams.php @@ -11,7 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Fetch user preferences for a specific subscription topic. + * Returns a user's opt-in status and channel choices for one subscription topic, or the effective default if they have set no override. * * @see Courier\Services\Users\PreferencesService::retrieveTopic() * diff --git a/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams.php b/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams.php index 35f11dd5..bd88792d 100644 --- a/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams.php +++ b/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams.php @@ -12,7 +12,7 @@ use Courier\Users\Preferences\PreferenceUpdateOrCreateTopicParams\Topic; /** - * Update or Create user preferences for a specific subscription topic. + * Sets a user's opt-in status and channel choices for one subscription topic, overriding the tenant default for that topic only. * * @see Courier\Services\Users\PreferencesService::updateOrCreateTopic() * diff --git a/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams/Topic.php b/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams/Topic.php index 931728af..cc75d8c6 100644 --- a/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams/Topic.php +++ b/src/Users/Preferences/PreferenceUpdateOrCreateTopicParams/Topic.php @@ -23,12 +23,16 @@ final class Topic implements BaseModel /** @use SdkModel */ use SdkModel; - /** @var value-of $status */ + /** + * The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level default, not a user choice; the API rejects opting a user out of a REQUIRED topic. + * + * @var value-of $status + */ #[Required(enum: PreferenceStatus::class)] public string $status; /** - * The Channels a user has chosen to receive notifications through for this topic. + * The channels to deliver this topic on when has_custom_routing is true. One or more of: direct_message, email, push, sms, webhook, inbox. * * @var list>|null $customRouting */ @@ -39,6 +43,9 @@ final class Topic implements BaseModel )] public ?array $customRouting; + /** + * Set to true to route this topic to the channels in custom_routing instead of the topic's default routing. + */ #[Optional('has_custom_routing', nullable: true)] public ?bool $hasCustomRouting; @@ -85,6 +92,8 @@ public static function with( } /** + * The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level default, not a user choice; the API rejects opting a user out of a REQUIRED topic. + * * @param PreferenceStatus|value-of $status */ public function withStatus(PreferenceStatus|string $status): self @@ -96,7 +105,7 @@ public function withStatus(PreferenceStatus|string $status): self } /** - * The Channels a user has chosen to receive notifications through for this topic. + * The channels to deliver this topic on when has_custom_routing is true. One or more of: direct_message, email, push, sms, webhook, inbox. * * @param list>|null $customRouting */ @@ -108,6 +117,9 @@ public function withCustomRouting(?array $customRouting): self return $self; } + /** + * Set to true to route this topic to the channels in custom_routing instead of the topic's default routing. + */ public function withHasCustomRouting(?bool $hasCustomRouting): self { $self = clone $this; diff --git a/src/Users/Preferences/TopicPreference.php b/src/Users/Preferences/TopicPreference.php index 03877e89..0d8b27de 100644 --- a/src/Users/Preferences/TopicPreference.php +++ b/src/Users/Preferences/TopicPreference.php @@ -26,22 +26,36 @@ final class TopicPreference implements BaseModel /** @use SdkModel */ use SdkModel; - /** @var value-of $defaultStatus */ + /** + * The topic's default status, returned on reads. It applies whenever the user has no override of their own (status equals this value). + * + * @var value-of $defaultStatus + */ #[Required('default_status', enum: PreferenceStatus::class)] public string $defaultStatus; - /** @var value-of $status */ + /** + * The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the user's own choice; REQUIRED is a topic-level default set in the preferences editor, not a user choice. + * + * @var value-of $status + */ #[Required(enum: PreferenceStatus::class)] public string $status; + /** + * The unique identifier of the subscription topic this preference applies to. + */ #[Required('topic_id')] public string $topicID; + /** + * The display name of the subscription topic, returned on reads. + */ #[Required('topic_name')] public string $topicName; /** - * The Channels a user has chosen to receive notifications through for this topic. + * The channels the user has chosen to receive this topic on, present only when has_custom_routing is true. One or more of: direct_message, email, push, sms, webhook, inbox. * * @var list>|null $customRouting */ @@ -52,6 +66,9 @@ final class TopicPreference implements BaseModel )] public ?array $customRouting; + /** + * Whether the user has chosen specific delivery channels for this topic (listed in custom_routing) rather than the topic's default routing. + */ #[Optional('has_custom_routing', nullable: true)] public ?bool $hasCustomRouting; @@ -111,6 +128,8 @@ public static function with( } /** + * The topic's default status, returned on reads. It applies whenever the user has no override of their own (status equals this value). + * * @param PreferenceStatus|value-of $defaultStatus */ public function withDefaultStatus( @@ -123,6 +142,8 @@ public function withDefaultStatus( } /** + * The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the user's own choice; REQUIRED is a topic-level default set in the preferences editor, not a user choice. + * * @param PreferenceStatus|value-of $status */ public function withStatus(PreferenceStatus|string $status): self @@ -133,6 +154,9 @@ public function withStatus(PreferenceStatus|string $status): self return $self; } + /** + * The unique identifier of the subscription topic this preference applies to. + */ public function withTopicID(string $topicID): self { $self = clone $this; @@ -141,6 +165,9 @@ public function withTopicID(string $topicID): self return $self; } + /** + * The display name of the subscription topic, returned on reads. + */ public function withTopicName(string $topicName): self { $self = clone $this; @@ -150,7 +177,7 @@ public function withTopicName(string $topicName): self } /** - * The Channels a user has chosen to receive notifications through for this topic. + * The channels the user has chosen to receive this topic on, present only when has_custom_routing is true. One or more of: direct_message, email, push, sms, webhook, inbox. * * @param list>|null $customRouting */ @@ -162,6 +189,9 @@ public function withCustomRouting(?array $customRouting): self return $self; } + /** + * Whether the user has chosen specific delivery channels for this topic (listed in custom_routing) rather than the topic's default routing. + */ public function withHasCustomRouting(?bool $hasCustomRouting): self { $self = clone $this; diff --git a/src/Users/Tenants/TenantAddMultipleParams.php b/src/Users/Tenants/TenantAddMultipleParams.php index 8cb3bffb..17ed44ac 100644 --- a/src/Users/Tenants/TenantAddMultipleParams.php +++ b/src/Users/Tenants/TenantAddMultipleParams.php @@ -11,11 +11,7 @@ use Courier\Tenants\TenantAssociation; /** - * This endpoint is used to add a user to - * multiple tenants in one call. - * A custom profile can also be supplied for each tenant. - * This profile will be merged with the user's main - * profile when sending to the user with that tenant. + * Adds a user to several tenants in one call, each optionally with a per-tenant profile that overrides their workspace profile. * * @see Courier\Services\Users\TenantsService::addMultiple() * diff --git a/src/Users/Tenants/TenantAddSingleParams.php b/src/Users/Tenants/TenantAddSingleParams.php index 93b8ea1d..b8d69e90 100644 --- a/src/Users/Tenants/TenantAddSingleParams.php +++ b/src/Users/Tenants/TenantAddSingleParams.php @@ -11,11 +11,7 @@ use Courier\Core\Contracts\BaseModel; /** - * This endpoint is used to add a single tenant. - * - * A custom profile can also be supplied with the tenant. - * This profile will be merged with the user's main profile - * when sending to the user with that tenant. + * Adds a user to one tenant, optionally with a tenant-specific profile that overrides their workspace profile for sends in that tenant. * * @see Courier\Services\Users\TenantsService::addSingle() * diff --git a/src/Users/Tenants/TenantListParams.php b/src/Users/Tenants/TenantListParams.php index 8f28226b..8e135e94 100644 --- a/src/Users/Tenants/TenantListParams.php +++ b/src/Users/Tenants/TenantListParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Returns a paginated list of user tenant associations. + * Returns the tenants a user belongs to, with cursor paging. A user can belong to many tenants, each with its own profile and preferences. * * @see Courier\Services\Users\TenantsService::list() * diff --git a/src/Users/Tenants/TenantRemoveSingleParams.php b/src/Users/Tenants/TenantRemoveSingleParams.php index 4c4a7e04..3ceaf3bf 100644 --- a/src/Users/Tenants/TenantRemoveSingleParams.php +++ b/src/Users/Tenants/TenantRemoveSingleParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Removes a user from the supplied tenant. + * Removes a user from one tenant. Their other tenant memberships and workspace profile are managed through separate endpoints. * * @see Courier\Services\Users\TenantsService::removeSingle() * diff --git a/src/Users/Tokens/TokenAddSingleParams.php b/src/Users/Tokens/TokenAddSingleParams.php index 6aedf3fd..295255de 100644 --- a/src/Users/Tokens/TokenAddSingleParams.php +++ b/src/Users/Tokens/TokenAddSingleParams.php @@ -14,7 +14,7 @@ use Courier\Users\Tokens\TokenAddSingleParams\Tracking; /** - * Adds a single token to a user and overwrites a matching existing token. + * Registers one device token for a user against a provider key, overwriting the token if it already exists. Push sends resolve tokens per user. * * @see Courier\Services\Users\TokensService::addSingle() * diff --git a/src/Users/Tokens/TokenDeleteParams.php b/src/Users/Tokens/TokenDeleteParams.php index 3e5c0e20..1fdd7d75 100644 --- a/src/Users/Tokens/TokenDeleteParams.php +++ b/src/Users/Tokens/TokenDeleteParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Delete User Token. + * Deletes one device token for a user, addressed by the token value, so push sends no longer target that device. * * @see Courier\Services\Users\TokensService::delete() * diff --git a/src/Users/Tokens/TokenRetrieveParams.php b/src/Users/Tokens/TokenRetrieveParams.php index 67546d0c..abf7b3c3 100644 --- a/src/Users/Tokens/TokenRetrieveParams.php +++ b/src/Users/Tokens/TokenRetrieveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Get single token available for a `:token`. + * Returns one device token with its provider key, status and status reason, expiry date, and any properties stored alongside it. * * @see Courier\Services\Users\TokensService::retrieve() * diff --git a/src/Users/Tokens/TokenUpdateParams.php b/src/Users/Tokens/TokenUpdateParams.php index e71e25f8..7866615c 100644 --- a/src/Users/Tokens/TokenUpdateParams.php +++ b/src/Users/Tokens/TokenUpdateParams.php @@ -11,7 +11,7 @@ use Courier\Users\Tokens\TokenUpdateParams\Patch; /** - * Apply a JSON Patch (RFC 6902) to the specified token. + * Applies a JSON Patch to a device token, changing its status, expiry, or properties without re-registering it. * * @see Courier\Services\Users\TokensService::update() * diff --git a/src/Version.php b/src/Version.php index 6ba3204c..5c69dd7e 100644 --- a/src/Version.php +++ b/src/Version.php @@ -5,5 +5,5 @@ namespace Courier; // x-release-please-start-version -const VERSION = '5.13.0'; +const VERSION = '5.13.1'; // x-release-please-end diff --git a/src/WorkspacePreferences/Topics/TopicArchiveParams.php b/src/WorkspacePreferences/Topics/TopicArchiveParams.php index 7bf33701..4ef5f885 100644 --- a/src/WorkspacePreferences/Topics/TopicArchiveParams.php +++ b/src/WorkspacePreferences/Topics/TopicArchiveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Archive a topic and remove it from its workspace preference. Same 404 rules as GET. + * Archives a subscription topic and removes it from its workspace preference, addressed by section id and topic id. * * @see Courier\Services\WorkspacePreferences\TopicsService::archive() * diff --git a/src/WorkspacePreferences/Topics/TopicCreateParams.php b/src/WorkspacePreferences/Topics/TopicCreateParams.php index 30dbb91e..2a8b9d22 100644 --- a/src/WorkspacePreferences/Topics/TopicCreateParams.php +++ b/src/WorkspacePreferences/Topics/TopicCreateParams.php @@ -14,7 +14,7 @@ use Courier\WorkspacePreferences\Topics\TopicCreateParams\DefaultStatus; /** - * Create a subscription preference topic inside a workspace preference. Fails with 404 if the workspace preference does not exist. The topic id is generated and returned. + * Creates a subscription topic inside a workspace preference. The default status sets whether users start opted in, opted out, or required. * * @see Courier\Services\WorkspacePreferences\TopicsService::create() * diff --git a/src/WorkspacePreferences/Topics/TopicRetrieveParams.php b/src/WorkspacePreferences/Topics/TopicRetrieveParams.php index 36d65f33..3d7ac2e0 100644 --- a/src/WorkspacePreferences/Topics/TopicRetrieveParams.php +++ b/src/WorkspacePreferences/Topics/TopicRetrieveParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Retrieve a topic within a workspace preference. Returns 404 if the workspace preference does not exist, the topic does not exist, or the topic belongs to a different workspace preference. + * Returns one subscription topic with its default status, routing options, allowed preferences, and unsubscribe header setting. * * @see Courier\Services\WorkspacePreferences\TopicsService::retrieve() * diff --git a/src/WorkspacePreferences/WorkspacePreferenceCreateParams.php b/src/WorkspacePreferences/WorkspacePreferenceCreateParams.php index 7ac502bc..a4ebbe8a 100644 --- a/src/WorkspacePreferences/WorkspacePreferenceCreateParams.php +++ b/src/WorkspacePreferences/WorkspacePreferenceCreateParams.php @@ -12,7 +12,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Create a workspace preference. The workspace preference id is generated and returned. Topics are created inside a workspace preference via POST /preferences/sections/{section_id}/topics. + * Creates a workspace preference and returns its generated id. Add subscription topics to it afterwards with the topics endpoint. * * @see Courier\Services\WorkspacePreferencesService::create() * diff --git a/src/WorkspacePreferences/WorkspacePreferencePublishParams.php b/src/WorkspacePreferences/WorkspacePreferencePublishParams.php index b3dd1766..fc1cb79c 100644 --- a/src/WorkspacePreferences/WorkspacePreferencePublishParams.php +++ b/src/WorkspacePreferences/WorkspacePreferencePublishParams.php @@ -10,7 +10,7 @@ use Courier\Core\Contracts\BaseModel; /** - * Publish the workspace's preferences page. Takes a snapshot of every workspace preference with its topics under a new published version, making the current state visible on the hosted preferences page (non-draft). + * Publishes the workspace preference page, snapshotting every preference and topic, and returns the page id and a preview URL. * * @see Courier\Services\WorkspacePreferencesService::publish() *