diff --git a/.release-please-manifest.json b/.release-please-manifest.json index b9e06599..bef741c4 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "4.21.0" + ".": "4.21.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 43e23949..97af43da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 4.21.1 (2026-07-25) + +Full Changelog: [v4.21.0...v4.21.1](https://github.com/trycourier/courier-ruby/compare/v4.21.0...v4.21.1) + +### Documentation + +* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-ruby/issues/172)) ([c540bdb](https://github.com/trycourier/courier-ruby/commit/c540bdb855f180d850feeabf1a30ed4394092b50)) +* **openapi:** rewrite operation descriptions for agents and SEO ([#174](https://github.com/trycourier/courier-ruby/issues/174)) ([8a8c25b](https://github.com/trycourier/courier-ruby/commit/8a8c25b54b9a8db2cd906ab09ac8729423fa35b8)) + ## 4.21.0 (2026-07-23) Full Changelog: [v4.20.0...v4.21.0](https://github.com/trycourier/courier-ruby/compare/v4.20.0...v4.21.0) diff --git a/Gemfile.lock b/Gemfile.lock index ed874bea..54e83dda 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -11,7 +11,7 @@ GIT PATH remote: . specs: - trycourier (4.21.0) + trycourier (4.21.1) cgi connection_pool diff --git a/lib/courier/models/users/preference_update_or_create_topic_params.rb b/lib/courier/models/users/preference_update_or_create_topic_params.rb index 4b1a26e5..c8ef9c49 100644 --- a/lib/courier/models/users/preference_update_or_create_topic_params.rb +++ b/lib/courier/models/users/preference_update_or_create_topic_params.rb @@ -42,12 +42,16 @@ class PreferenceUpdateOrCreateTopicParams < Courier::Internal::Type::BaseModel class Topic < Courier::Internal::Type::BaseModel # @!attribute 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. # # @return [Symbol, Courier::Models::PreferenceStatus] required :status, enum: -> { Courier::PreferenceStatus } # @!attribute custom_routing - # 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. # # @return [Array, nil] optional :custom_routing, @@ -55,16 +59,22 @@ class Topic < Courier::Internal::Type::BaseModel nil?: true # @!attribute has_custom_routing + # Set to true to route this topic to the channels in custom_routing instead of the + # topic's default routing. # # @return [Boolean, nil] optional :has_custom_routing, Courier::Internal::Type::Boolean, nil?: true # @!method initialize(status:, custom_routing: nil, has_custom_routing: nil) - # @param status [Symbol, Courier::Models::PreferenceStatus] + # Some parameter documentations has been truncated, see + # {Courier::Models::Users::PreferenceUpdateOrCreateTopicParams::Topic} for more + # details. # - # @param custom_routing [Array, nil] The Channels a user has chosen to receive notifications through for this topic + # @param status [Symbol, Courier::Models::PreferenceStatus] The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level # - # @param has_custom_routing [Boolean, nil] + # @param custom_routing [Array, nil] The channels to deliver this topic on when has_custom_routing is true. One or mo + # + # @param has_custom_routing [Boolean, nil] Set to true to route this topic to the channels in custom_routing instead of the end end end diff --git a/lib/courier/models/users/topic_preference.rb b/lib/courier/models/users/topic_preference.rb index 6035e8f9..15873002 100644 --- a/lib/courier/models/users/topic_preference.rb +++ b/lib/courier/models/users/topic_preference.rb @@ -5,27 +5,36 @@ module Models module Users class TopicPreference < Courier::Internal::Type::BaseModel # @!attribute default_status + # The topic's default status, returned on reads. It applies whenever the user has + # no override of their own (status equals this value). # # @return [Symbol, Courier::Models::PreferenceStatus] required :default_status, enum: -> { Courier::PreferenceStatus } # @!attribute 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. # # @return [Symbol, Courier::Models::PreferenceStatus] required :status, enum: -> { Courier::PreferenceStatus } # @!attribute topic_id + # The unique identifier of the subscription topic this preference applies to. # # @return [String] required :topic_id, String # @!attribute topic_name + # The display name of the subscription topic, returned on reads. # # @return [String] required :topic_name, String # @!attribute custom_routing - # 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. # # @return [Array, nil] optional :custom_routing, @@ -33,22 +42,27 @@ class TopicPreference < Courier::Internal::Type::BaseModel nil?: true # @!attribute has_custom_routing + # Whether the user has chosen specific delivery channels for this topic (listed in + # custom_routing) rather than the topic's default routing. # # @return [Boolean, nil] optional :has_custom_routing, Courier::Internal::Type::Boolean, nil?: true # @!method initialize(default_status:, status:, topic_id:, topic_name:, custom_routing: nil, has_custom_routing: nil) - # @param default_status [Symbol, Courier::Models::PreferenceStatus] + # Some parameter documentations has been truncated, see + # {Courier::Models::Users::TopicPreference} for more details. # - # @param status [Symbol, Courier::Models::PreferenceStatus] + # @param default_status [Symbol, Courier::Models::PreferenceStatus] The topic's default status, returned on reads. It applies whenever the user has # - # @param topic_id [String] + # @param status [Symbol, Courier::Models::PreferenceStatus] The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the # - # @param topic_name [String] + # @param topic_id [String] The unique identifier of the subscription topic this preference applies to. # - # @param custom_routing [Array, nil] The Channels a user has chosen to receive notifications through for this topic + # @param topic_name [String] The display name of the subscription topic, returned on reads. # - # @param has_custom_routing [Boolean, nil] + # @param custom_routing [Array, nil] The channels the user has chosen to receive this topic on, present only when has + # + # @param has_custom_routing [Boolean, nil] Whether the user has chosen specific delivery channels for this topic (listed in end end end diff --git a/lib/courier/resources/audiences.rb b/lib/courier/resources/audiences.rb index d406a3d6..ba71e57b 100644 --- a/lib/courier/resources/audiences.rb +++ b/lib/courier/resources/audiences.rb @@ -3,7 +3,8 @@ module Courier module Resources class Audiences - # 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. # # @overload retrieve(audience_id, request_options: {}) # @@ -26,7 +27,8 @@ def retrieve(audience_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::AudienceUpdateParams} for more details. # - # Creates or updates audience. + # Creates or replaces an audience from a filter and an AND or OR operator. + # Membership recalculates automatically as profiles change. # # @overload update(audience_id, description: nil, filter: nil, name: nil, operator: nil, request_options: {}) # @@ -56,7 +58,8 @@ def update(audience_id, params = {}) ) end - # 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. # # @overload list(cursor: nil, request_options: {}) # @@ -79,7 +82,8 @@ def list(params = {}) ) end - # 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. # # @overload delete(audience_id, request_options: {}) # @@ -99,7 +103,8 @@ def delete(audience_id, params = {}) ) end - # 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. # # @overload list_members(audience_id, cursor: nil, request_options: {}) # diff --git a/lib/courier/resources/audit_events.rb b/lib/courier/resources/audit_events.rb index 1fcb8c85..8d95714c 100644 --- a/lib/courier/resources/audit_events.rb +++ b/lib/courier/resources/audit_events.rb @@ -3,7 +3,8 @@ module Courier module Resources class AuditEvents - # 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. # # @overload retrieve(audit_event_id, request_options: {}) # @@ -23,7 +24,8 @@ def retrieve(audit_event_id, params = {}) ) end - # 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. # # @overload list(cursor: nil, request_options: {}) # diff --git a/lib/courier/resources/auth.rb b/lib/courier/resources/auth.rb index b9f9aac9..756e7588 100644 --- a/lib/courier/resources/auth.rb +++ b/lib/courier/resources/auth.rb @@ -6,7 +6,8 @@ class Auth # Some parameter documentations has been truncated, see # {Courier::Models::AuthIssueTokenParams} for more details. # - # 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. # # @overload issue_token(expires_in:, scope:, request_options: {}) # diff --git a/lib/courier/resources/automations.rb b/lib/courier/resources/automations.rb index 738c4ac4..71ddaeea 100644 --- a/lib/courier/resources/automations.rb +++ b/lib/courier/resources/automations.rb @@ -9,7 +9,8 @@ class Automations # Some parameter documentations has been truncated, see # {Courier::Models::AutomationListParams} for more details. # - # 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. # # @overload list(cursor: nil, version: nil, request_options: {}) # diff --git a/lib/courier/resources/automations/invoke.rb b/lib/courier/resources/automations/invoke.rb index 9a5fc62f..1d7b2a2d 100644 --- a/lib/courier/resources/automations/invoke.rb +++ b/lib/courier/resources/automations/invoke.rb @@ -4,10 +4,8 @@ module Courier module Resources class Automations class Invoke - # 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. # # @overload invoke_ad_hoc(automation:, brand: nil, data: nil, profile: nil, recipient: nil, template: nil, request_options: {}) # @@ -36,7 +34,8 @@ def invoke_ad_hoc(params) # Some parameter documentations has been truncated, see # {Courier::Models::Automations::InvokeInvokeByTemplateParams} for more details. # - # 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. # # @overload invoke_by_template(template_id, recipient:, brand: nil, data: nil, profile: nil, template: nil, request_options: {}) # diff --git a/lib/courier/resources/brands.rb b/lib/courier/resources/brands.rb index 19e56383..9f4ce739 100644 --- a/lib/courier/resources/brands.rb +++ b/lib/courier/resources/brands.rb @@ -3,8 +3,8 @@ module Courier module Resources class Brands - # 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. # # @overload create(name:, settings:, id: nil, snippets: nil, request_options: {}) # @@ -22,7 +22,8 @@ def create(params) @client.request(method: :post, path: "brands", body: parsed, model: Courier::Brand, options: options) end - # Fetch a specific brand by brand ID. + # Returns one brand by id, including its colors, logo and styling settings, + # Handlebars snippets, and published version. # # @overload retrieve(brand_id, request_options: {}) # @@ -42,7 +43,8 @@ def retrieve(brand_id, params = {}) ) end - # 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. # # @overload update(brand_id, name:, settings: nil, snippets: nil, request_options: {}) # @@ -70,7 +72,8 @@ def update(brand_id, params) ) end - # Get the list of brands. + # Lists the workspace's brands. Every entry carries its name, styling settings, + # snippets, and published version. # # @overload list(cursor: nil, request_options: {}) # @@ -93,7 +96,8 @@ def list(params = {}) ) end - # 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. # # @overload delete(brand_id, request_options: {}) # diff --git a/lib/courier/resources/digests/schedules.rb b/lib/courier/resources/digests/schedules.rb index decde45f..d976d4f8 100644 --- a/lib/courier/resources/digests/schedules.rb +++ b/lib/courier/resources/digests/schedules.rb @@ -7,9 +7,8 @@ class Schedules # Some parameter documentations has been truncated, see # {Courier::Models::Digests::ScheduleListInstancesParams} for more details. # - # 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. # # @overload list_instances(schedule_id, cursor: nil, limit: nil, request_options: {}) # diff --git a/lib/courier/resources/inbound.rb b/lib/courier/resources/inbound.rb index 59c070bd..868240f1 100644 --- a/lib/courier/resources/inbound.rb +++ b/lib/courier/resources/inbound.rb @@ -6,7 +6,8 @@ class Inbound # Some parameter documentations has been truncated, see # {Courier::Models::InboundTrackEventParams} for more details. # - # 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. # # @overload track_event(event:, message_id:, properties:, type:, user_id: nil, request_options: {}) # diff --git a/lib/courier/resources/journeys.rb b/lib/courier/resources/journeys.rb index 298afc57..78d590fc 100644 --- a/lib/courier/resources/journeys.rb +++ b/lib/courier/resources/journeys.rb @@ -6,12 +6,8 @@ class Journeys # @return [Courier::Resources::Journeys::Templates] attr_reader :templates - # 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. # # @overload create(name:, nodes:, enabled: nil, state: nil, request_options: {}) # @@ -68,7 +64,8 @@ def retrieve(template_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::JourneyListParams} for more details. # - # Get the list of journeys. + # Lists the workspace's journeys, each carrying a name, state, and enabled flag. + # Paged by cursor. # # @overload list(cursor: nil, version: nil, request_options: {}) # @@ -93,8 +90,8 @@ def list(params = {}) ) end - # 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. # # @overload archive(template_id, request_options: {}) # @@ -117,12 +114,8 @@ def archive(template_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::JourneyCancelParams} for more details. # - # 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. # # @overload cancel(cancel_journey_request:, request_options: {}) # @@ -147,8 +140,8 @@ def cancel(params) # Some parameter documentations has been truncated, see # {Courier::Models::JourneyInvokeParams} for more details. # - # 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. # # @overload invoke(template_id, data: nil, profile: nil, user_id: nil, request_options: {}) # @@ -176,7 +169,8 @@ def invoke(template_id, params = {}) ) end - # 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. # # @overload list_versions(template_id, request_options: {}) # @@ -196,9 +190,8 @@ def list_versions(template_id, params = {}) ) end - # 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. # # @overload publish(template_id, version: nil, request_options: {}) # @@ -222,11 +215,8 @@ def publish(template_id, params = {}) ) end - # 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. # # @overload replace(template_id, name:, nodes:, enabled: nil, state: nil, request_options: {}) # diff --git a/lib/courier/resources/journeys/templates.rb b/lib/courier/resources/journeys/templates.rb index 8ce57501..d1cbf627 100644 --- a/lib/courier/resources/journeys/templates.rb +++ b/lib/courier/resources/journeys/templates.rb @@ -35,9 +35,8 @@ def create(template_id, params) ) end - # 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. # # @overload retrieve(notification_id, template_id:, request_options: {}) # @@ -92,8 +91,8 @@ def list(template_id, params = {}) ) end - # 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. # # @overload archive(notification_id, template_id:, request_options: {}) # @@ -120,8 +119,8 @@ def archive(notification_id, params) ) end - # 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. # # @overload list_versions(notification_id, template_id:, request_options: {}) # @@ -148,9 +147,8 @@ def list_versions(notification_id, params) ) end - # 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. # # @overload publish(notification_id, template_id:, version: nil, request_options: {}) # @@ -255,7 +253,8 @@ def put_locale(locale_id, params) ) end - # 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. # # @overload replace(notification_id, template_id:, notification:, state: nil, request_options: {}) # @@ -290,11 +289,8 @@ def replace(notification_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Journeys::TemplateRetrieveContentParams} for more details. # - # 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. # # @overload retrieve_content(notification_id, template_id:, version: nil, request_options: {}) # diff --git a/lib/courier/resources/lists.rb b/lib/courier/resources/lists.rb index 81c52668..487b1c3e 100644 --- a/lib/courier/resources/lists.rb +++ b/lib/courier/resources/lists.rb @@ -6,7 +6,8 @@ class Lists # @return [Courier::Resources::Lists::Subscriptions] attr_reader :subscriptions - # 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. # # @overload retrieve(list_id, request_options: {}) # @@ -26,7 +27,8 @@ def retrieve(list_id, params = {}) ) end - # 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. # # @overload update(list_id, name:, preferences: nil, request_options: {}) # @@ -55,7 +57,8 @@ def update(list_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::ListListParams} for more details. # - # 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. # # @overload list(cursor: nil, pattern: nil, request_options: {}) # @@ -80,7 +83,8 @@ def list(params = {}) ) end - # 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. # # @overload delete(list_id, request_options: {}) # @@ -100,7 +104,8 @@ def delete(list_id, params = {}) ) end - # 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. # # @overload restore(list_id, request_options: {}) # diff --git a/lib/courier/resources/lists/subscriptions.rb b/lib/courier/resources/lists/subscriptions.rb index c99377a9..aea20ca5 100644 --- a/lib/courier/resources/lists/subscriptions.rb +++ b/lib/courier/resources/lists/subscriptions.rb @@ -4,7 +4,8 @@ module Courier module Resources class Lists class Subscriptions - # Get the list's subscriptions. + # Returns the users subscribed to a list with paging, each with the preferences + # recorded for that subscription. # # @overload list(list_id, cursor: nil, request_options: {}) # @@ -82,8 +83,8 @@ def subscribe(list_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Lists::SubscriptionSubscribeUserParams} for more details. # - # 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. # # @overload subscribe_user(user_id, list_id:, preferences: nil, request_options: {}) # @@ -113,7 +114,8 @@ def subscribe_user(user_id, params) ) end - # 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. # # @overload unsubscribe_user(user_id, list_id:, request_options: {}) # diff --git a/lib/courier/resources/messages.rb b/lib/courier/resources/messages.rb index 504a57ab..a07ed48e 100644 --- a/lib/courier/resources/messages.rb +++ b/lib/courier/resources/messages.rb @@ -6,7 +6,8 @@ class Messages # Some parameter documentations has been truncated, see # {Courier::Models::MessageRetrieveParams} for more details. # - # 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. # # @overload retrieve(message_id, request_options: {}) # @@ -29,7 +30,8 @@ def retrieve(message_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::MessageListParams} for more details. # - # 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. # # @overload list(archived: nil, cursor: nil, enqueued_after: nil, event: nil, list: nil, message_id: nil, notification: nil, provider: nil, recipient: nil, status: nil, tag: nil, tags: nil, tenant_id: nil, trace_id: nil, request_options: {}) # @@ -78,11 +80,8 @@ def list(params = {}) ) end - # 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. # # @overload cancel(message_id, request_options: {}) # @@ -105,7 +104,8 @@ def cancel(message_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::MessageContentParams} for more details. # - # Get message content + # Returns the rendered content Courier delivered for a message, broken out per + # channel, to confirm what the recipient received. # # @overload content(message_id, request_options: {}) # @@ -125,7 +125,8 @@ def content(message_id, params = {}) ) end - # 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. # # @overload history(message_id, type: nil, request_options: {}) # @@ -153,11 +154,8 @@ def history(message_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::MessageResendParams} for more details. # - # 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. # # @overload resend(message_id, request_options: {}) # diff --git a/lib/courier/resources/notifications.rb b/lib/courier/resources/notifications.rb index 410d855e..11ff6195 100644 --- a/lib/courier/resources/notifications.rb +++ b/lib/courier/resources/notifications.rb @@ -63,7 +63,8 @@ def retrieve(id, params = {}) ) end - # 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. # # @overload list(cursor: nil, event_id: nil, notes: nil, request_options: {}) # @@ -90,7 +91,8 @@ def list(params = {}) ) end - # Archive a notification template. + # Archives a notification template, preventing new sends from referencing it. The + # template stays retrievable for its version history. # # @overload archive(id, request_options: {}) # @@ -110,12 +112,9 @@ def archive(id, params = {}) ) end - # 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. # # @overload duplicate(id, request_options: {}) # @@ -135,7 +134,8 @@ def duplicate(id, params = {}) ) end - # List versions of a notification template. + # Returns a notification template's published versions, most recent first, for + # comparison or rollback. Paged. # # @overload list_versions(id, cursor: nil, limit: nil, request_options: {}) # @@ -187,9 +187,8 @@ def publish(id, params = {}) ) end - # 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. # # @overload put_content(id, content:, state: nil, request_options: {}) # @@ -215,8 +214,8 @@ def put_content(id, params) ) end - # 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. # # @overload put_element(element_id, id:, type:, channels: nil, data: nil, if_: nil, loop_: nil, ref: nil, state: nil, request_options: {}) # @@ -258,9 +257,8 @@ def put_element(element_id, params) ) end - # 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. # # @overload put_locale(locale_id, id:, elements:, state: nil, request_options: {}) # @@ -295,7 +293,8 @@ def put_locale(locale_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::NotificationReplaceParams} for more details. # - # 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. # # @overload replace(id, notification:, state: nil, request_options: {}) # @@ -324,10 +323,8 @@ def replace(id, params) # Some parameter documentations has been truncated, see # {Courier::Models::NotificationRetrieveContentParams} for more details. # - # 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. # # @overload retrieve_content(id, version: nil, request_options: {}) # diff --git a/lib/courier/resources/notifications/checks.rb b/lib/courier/resources/notifications/checks.rb index f9a2524c..fc2df7d5 100644 --- a/lib/courier/resources/notifications/checks.rb +++ b/lib/courier/resources/notifications/checks.rb @@ -4,7 +4,8 @@ module Courier module Resources class Notifications class Checks - # 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. # # @overload update(submission_id, id:, checks:, request_options: {}) # @@ -34,7 +35,8 @@ def update(submission_id, params) ) end - # Retrieve the submission checks for a notification template. + # Returns the approval checks recorded for a template submission, each with its + # pass or fail result. # # @overload list(submission_id, id:, request_options: {}) # @@ -61,7 +63,8 @@ def list(submission_id, params) ) end - # 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. # # @overload delete(submission_id, id:, request_options: {}) # diff --git a/lib/courier/resources/profiles.rb b/lib/courier/resources/profiles.rb index d0d7fd32..e8687d31 100644 --- a/lib/courier/resources/profiles.rb +++ b/lib/courier/resources/profiles.rb @@ -9,8 +9,8 @@ class Profiles # Some parameter documentations has been truncated, see # {Courier::Models::ProfileCreateParams} for more details. # - # 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. # # @overload create(user_id, profile:, request_options: {}) # @@ -37,7 +37,8 @@ def create(user_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::ProfileRetrieveParams} for more details. # - # 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. # # @overload retrieve(user_id, request_options: {}) # @@ -60,7 +61,8 @@ def retrieve(user_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::ProfileUpdateParams} for more details. # - # Update a profile + # Applies a JSON Patch to a user profile, adding, removing, or replacing + # individual fields without sending the whole object. # # @overload update(user_id, patch:, request_options: {}) # @@ -87,7 +89,8 @@ def update(user_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::ProfileDeleteParams} for more details. # - # 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. # # @overload delete(user_id, request_options: {}) # @@ -110,11 +113,8 @@ def delete(user_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::ProfileReplaceParams} for more details. # - # 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. # # @overload replace(user_id, profile:, request_options: {}) # diff --git a/lib/courier/resources/profiles/lists.rb b/lib/courier/resources/profiles/lists.rb index ea96c78b..dec8cee0 100644 --- a/lib/courier/resources/profiles/lists.rb +++ b/lib/courier/resources/profiles/lists.rb @@ -7,7 +7,8 @@ class Lists # Some parameter documentations has been truncated, see # {Courier::Models::Profiles::ListRetrieveParams} for more details. # - # 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. # # @overload retrieve(user_id, cursor: nil, request_options: {}) # @@ -35,7 +36,8 @@ def retrieve(user_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::Profiles::ListDeleteParams} for more details. # - # 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. # # @overload delete(user_id, request_options: {}) # @@ -58,8 +60,8 @@ def delete(user_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::Profiles::ListSubscribeParams} for more details. # - # 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. # # @overload subscribe(user_id, lists:, request_options: {}) # diff --git a/lib/courier/resources/providers.rb b/lib/courier/resources/providers.rb index 3fca502e..6fe51b28 100644 --- a/lib/courier/resources/providers.rb +++ b/lib/courier/resources/providers.rb @@ -9,8 +9,8 @@ class Providers # Some parameter documentations has been truncated, see # {Courier::Models::ProviderCreateParams} for more details. # - # 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. # # @overload create(provider:, alias_: nil, settings: nil, title: nil, request_options: {}) # @@ -38,7 +38,8 @@ def create(params) ) end - # Fetch a single provider configuration by ID. + # Returns one configured provider by id, including its channel, provider key, + # alias, title, and current settings. # # @overload retrieve(id, request_options: {}) # @@ -61,11 +62,8 @@ def retrieve(id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::ProviderUpdateParams} for more details. # - # 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. # # @overload update(id, provider:, alias_: nil, settings: nil, title: nil, request_options: {}) # @@ -95,8 +93,8 @@ def update(id, params) ) end - # 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. # # @overload list(cursor: nil, request_options: {}) # @@ -119,8 +117,8 @@ def list(params = {}) ) end - # 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. # # @overload delete(id, request_options: {}) # diff --git a/lib/courier/resources/providers/catalog.rb b/lib/courier/resources/providers/catalog.rb index e5611c84..f298f891 100644 --- a/lib/courier/resources/providers/catalog.rb +++ b/lib/courier/resources/providers/catalog.rb @@ -7,10 +7,8 @@ class Catalog # Some parameter documentations has been truncated, see # {Courier::Models::Providers::CatalogListParams} for more details. # - # 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. # # @overload list(channel: nil, keys: nil, name: nil, request_options: {}) # diff --git a/lib/courier/resources/requests.rb b/lib/courier/resources/requests.rb index 6d848dfd..4f665343 100644 --- a/lib/courier/resources/requests.rb +++ b/lib/courier/resources/requests.rb @@ -3,7 +3,8 @@ module Courier module Resources class Requests - # 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. # # @overload archive(request_id, request_options: {}) # diff --git a/lib/courier/resources/routing_strategies.rb b/lib/courier/resources/routing_strategies.rb index 2121c931..770a3aea 100644 --- a/lib/courier/resources/routing_strategies.rb +++ b/lib/courier/resources/routing_strategies.rb @@ -36,8 +36,8 @@ def create(params) ) end - # 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. # # @overload retrieve(id, request_options: {}) # @@ -105,8 +105,8 @@ def archive(id, params = {}) ) end - # 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. # # @overload list_notifications(id, cursor: nil, limit: nil, request_options: {}) # diff --git a/lib/courier/resources/send.rb b/lib/courier/resources/send.rb index 43c50dbc..663a97e9 100644 --- a/lib/courier/resources/send.rb +++ b/lib/courier/resources/send.rb @@ -6,7 +6,8 @@ class Send # Some parameter documentations has been truncated, see # {Courier::Models::SendMessageParams} for more details. # - # 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. # # @overload message(message:, request_options: {}) # diff --git a/lib/courier/resources/tenants.rb b/lib/courier/resources/tenants.rb index 52be0202..9bb7dbfd 100644 --- a/lib/courier/resources/tenants.rb +++ b/lib/courier/resources/tenants.rb @@ -9,7 +9,8 @@ class Tenants # @return [Courier::Resources::Tenants::Templates] attr_reader :templates - # Get a Tenant + # Returns one tenant with its name, parent tenant id, default preferences, + # properties, and the user profile applied to its members. # # @overload retrieve(tenant_id, request_options: {}) # @@ -32,7 +33,8 @@ def retrieve(tenant_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::TenantUpdateParams} for more details. # - # Create or Replace a Tenant + # Creates or replaces a tenant from a name, parent, brand, properties, and default + # preferences supplied in the request body. # # @overload update(tenant_id, name:, brand_id: nil, default_preferences: nil, parent_tenant_id: nil, properties: nil, user_profile: nil, request_options: {}) # @@ -69,7 +71,8 @@ def update(tenant_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::TenantListParams} for more details. # - # Get a List of Tenants + # Lists the workspace's tenants, each carrying a name, parent tenant, properties, + # and default preferences. Paged. # # @overload list(cursor: nil, limit: nil, parent_tenant_id: nil, request_options: {}) # @@ -96,7 +99,8 @@ def list(params = {}) ) end - # Delete a Tenant + # Deletes a tenant. Its members' workspace-level profiles and preferences live + # outside the tenant and are managed separately. # # @overload delete(tenant_id, request_options: {}) # @@ -119,7 +123,8 @@ def delete(tenant_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::TenantListUsersParams} for more details. # - # 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. # # @overload list_users(tenant_id, cursor: nil, limit: nil, request_options: {}) # diff --git a/lib/courier/resources/tenants/preferences/items.rb b/lib/courier/resources/tenants/preferences/items.rb index 7e2f0e8b..7e67ce83 100644 --- a/lib/courier/resources/tenants/preferences/items.rb +++ b/lib/courier/resources/tenants/preferences/items.rb @@ -8,7 +8,8 @@ class Items # Some parameter documentations has been truncated, see # {Courier::Models::Tenants::Preferences::ItemUpdateParams} for more details. # - # 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. # # @overload update(topic_id, tenant_id:, status:, custom_routing: nil, has_custom_routing: nil, request_options: {}) # @@ -42,7 +43,8 @@ def update(topic_id, params) ) end - # Remove Default Preferences For Topic + # Removes a tenant's default preference for one subscription topic, addressed by + # tenant id and topic id. # # @overload delete(topic_id, tenant_id:, request_options: {}) # diff --git a/lib/courier/resources/tenants/templates.rb b/lib/courier/resources/tenants/templates.rb index 4816549d..d1beb190 100644 --- a/lib/courier/resources/tenants/templates.rb +++ b/lib/courier/resources/tenants/templates.rb @@ -7,7 +7,8 @@ class Templates # @return [Courier::Resources::Tenants::Templates::Versions] attr_reader :versions - # Get a Template in Tenant + # Returns a tenant's notification template with its content, version, and created, + # updated, and published timestamps. # # @overload retrieve(template_id, tenant_id:, request_options: {}) # @@ -34,7 +35,8 @@ def retrieve(template_id, params) ) end - # List Templates in Tenant + # Lists a tenant's notification templates, each carrying its version and published + # timestamp. Paged. # # @overload list(tenant_id, cursor: nil, limit: nil, request_options: {}) # @@ -61,12 +63,8 @@ def list(tenant_id, params = {}) ) end - # 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. # # @overload delete(template_id, tenant_id:, request_options: {}) # @@ -96,10 +94,8 @@ def delete(template_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Tenants::TemplatePublishParams} for more details. # - # 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. # # @overload publish(template_id, tenant_id:, version: nil, request_options: {}) # @@ -132,13 +128,8 @@ def publish(template_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Tenants::TemplateReplaceParams} for more details. # - # 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. # # @overload replace(template_id, tenant_id:, template:, published: nil, request_options: {}) # diff --git a/lib/courier/resources/tenants/templates/versions.rb b/lib/courier/resources/tenants/templates/versions.rb index 628c2864..57dce05b 100644 --- a/lib/courier/resources/tenants/templates/versions.rb +++ b/lib/courier/resources/tenants/templates/versions.rb @@ -8,13 +8,8 @@ class Versions # Some parameter documentations has been truncated, see # {Courier::Models::Tenants::Templates::VersionRetrieveParams} for more details. # - # 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. # # @overload retrieve(version, tenant_id:, template_id:, request_options: {}) # diff --git a/lib/courier/resources/translations.rb b/lib/courier/resources/translations.rb index 3be02c21..3b58dd9d 100644 --- a/lib/courier/resources/translations.rb +++ b/lib/courier/resources/translations.rb @@ -6,7 +6,8 @@ class Translations # Some parameter documentations has been truncated, see # {Courier::Models::TranslationRetrieveParams} for more details. # - # Get translations by locale + # Returns the translation strings stored for one domain and locale, for use in + # localized notification content. # # @overload retrieve(locale, domain:, request_options: {}) # @@ -36,7 +37,8 @@ def retrieve(locale, params) # Some parameter documentations has been truncated, see # {Courier::Models::TranslationUpdateParams} for more details. # - # Update a translation + # Uploads the translation strings for one domain and locale. Courier uses them to + # render localized content for recipients in that locale. # # @overload update(locale, domain:, body:, request_options: {}) # diff --git a/lib/courier/resources/users/preferences.rb b/lib/courier/resources/users/preferences.rb index c2f7693a..d66c20d9 100644 --- a/lib/courier/resources/users/preferences.rb +++ b/lib/courier/resources/users/preferences.rb @@ -7,7 +7,8 @@ class Preferences # Some parameter documentations has been truncated, see # {Courier::Models::Users::PreferenceRetrieveParams} for more details. # - # Fetch all user preferences. + # Returns a user's preference overrides with paging, one entry per subscription + # topic they have set a choice for. # # @overload retrieve(user_id, tenant_id: nil, request_options: {}) # @@ -35,23 +36,8 @@ def retrieve(user_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::Users::PreferenceBulkReplaceParams} for more details. # - # 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. # # @overload bulk_replace(user_id, topics:, tenant_id: nil, request_options: {}) # @@ -83,23 +69,8 @@ def bulk_replace(user_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Users::PreferenceBulkUpdateParams} for more details. # - # 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. # # @overload bulk_update(user_id, topics:, tenant_id: nil, request_options: {}) # @@ -131,9 +102,8 @@ def bulk_update(user_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Users::PreferenceDeleteTopicParams} for more details. # - # 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. # # @overload delete_topic(topic_id, user_id:, tenant_id: nil, request_options: {}) # @@ -167,7 +137,8 @@ def delete_topic(topic_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Users::PreferenceRetrieveTopicParams} for more details. # - # 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. # # @overload retrieve_topic(topic_id, user_id:, tenant_id: nil, request_options: {}) # @@ -201,7 +172,8 @@ def retrieve_topic(topic_id, params) # Some parameter documentations has been truncated, see # {Courier::Models::Users::PreferenceUpdateOrCreateTopicParams} for more details. # - # 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. # # @overload update_or_create_topic(topic_id, user_id:, topic:, tenant_id: nil, request_options: {}) # diff --git a/lib/courier/resources/users/tenants.rb b/lib/courier/resources/users/tenants.rb index 5ea9251e..e21010dc 100644 --- a/lib/courier/resources/users/tenants.rb +++ b/lib/courier/resources/users/tenants.rb @@ -7,7 +7,8 @@ class Tenants # Some parameter documentations has been truncated, see # {Courier::Models::Users::TenantListParams} for more details. # - # 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. # # @overload list(user_id, cursor: nil, limit: nil, request_options: {}) # @@ -34,9 +35,8 @@ def list(user_id, params = {}) ) end - # 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. # # @overload add_multiple(user_id, tenants:, request_options: {}) # @@ -60,10 +60,8 @@ def add_multiple(user_id, params) ) end - # 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. # # @overload add_single(tenant_id, user_id:, profile: nil, request_options: {}) # @@ -93,7 +91,8 @@ def add_single(tenant_id, params) ) end - # 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. # # @overload remove_all(user_id, request_options: {}) # @@ -113,7 +112,8 @@ def remove_all(user_id, params = {}) ) end - # 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. # # @overload remove_single(tenant_id, user_id:, request_options: {}) # diff --git a/lib/courier/resources/users/tokens.rb b/lib/courier/resources/users/tokens.rb index 61bf81a8..81e19671 100644 --- a/lib/courier/resources/users/tokens.rb +++ b/lib/courier/resources/users/tokens.rb @@ -4,7 +4,8 @@ module Courier module Resources class Users class Tokens - # 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. # # @overload retrieve(token, user_id:, request_options: {}) # @@ -31,7 +32,8 @@ def retrieve(token, params) ) end - # 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. # # @overload update(token, user_id:, patch:, request_options: {}) # @@ -61,7 +63,8 @@ def update(token, params) ) end - # 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. # # @overload list(user_id, request_options: {}) # @@ -81,7 +84,8 @@ def list(user_id, params = {}) ) end - # Delete User Token + # Deletes one device token for a user, addressed by the token value, so push sends + # no longer target that device. # # @overload delete(token, user_id:, request_options: {}) # @@ -108,7 +112,8 @@ def delete(token, params) ) end - # 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. # # @overload add_multiple(user_id, request_options: {}) # @@ -131,7 +136,8 @@ def add_multiple(user_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::Users::TokenAddSingleParams} for more details. # - # 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. # # @overload add_single(token, user_id:, provider_key:, device: nil, expiry_date: nil, properties: nil, tracking: nil, request_options: {}) # diff --git a/lib/courier/resources/workspace_preferences.rb b/lib/courier/resources/workspace_preferences.rb index 1204552d..e4b4775f 100644 --- a/lib/courier/resources/workspace_preferences.rb +++ b/lib/courier/resources/workspace_preferences.rb @@ -6,9 +6,8 @@ class WorkspacePreferences # @return [Courier::Resources::WorkspacePreferences::Topics] attr_reader :topics - # 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. # # @overload create(name:, description: nil, has_custom_routing: nil, routing_options: nil, request_options: {}) # @@ -36,7 +35,8 @@ def create(params) ) end - # 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. # # @overload retrieve(section_id, request_options: {}) # @@ -56,8 +56,8 @@ def retrieve(section_id, params = {}) ) end - # 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. # # @overload list(request_options: {}) # @@ -99,9 +99,8 @@ def archive(section_id, params = {}) # Some parameter documentations has been truncated, see # {Courier::Models::WorkspacePreferencePublishParams} for more details. # - # 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. # # @overload publish(brand_id: nil, description: nil, heading: nil, request_options: {}) # diff --git a/lib/courier/resources/workspace_preferences/topics.rb b/lib/courier/resources/workspace_preferences/topics.rb index cdc53bd1..97b95efc 100644 --- a/lib/courier/resources/workspace_preferences/topics.rb +++ b/lib/courier/resources/workspace_preferences/topics.rb @@ -7,9 +7,8 @@ class Topics # Some parameter documentations has been truncated, see # {Courier::Models::WorkspacePreferences::TopicCreateParams} for more details. # - # 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. # # @overload create(section_id, default_status:, name:, allowed_preferences: nil, description: nil, include_unsubscribe_header: nil, routing_options: nil, topic_data: nil, request_options: {}) # @@ -45,9 +44,8 @@ def create(section_id, params) ) end - # 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. # # @overload retrieve(topic_id, section_id:, request_options: {}) # @@ -74,7 +72,8 @@ def retrieve(topic_id, params) ) end - # List the topics in a workspace preference. + # Returns the subscription topics inside a workspace preference, each with its + # default status and routing options. # # @overload list(section_id, request_options: {}) # @@ -94,8 +93,8 @@ def list(section_id, params = {}) ) end - # 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. # # @overload archive(topic_id, section_id:, request_options: {}) # diff --git a/lib/courier/version.rb b/lib/courier/version.rb index f25582f1..2e55560e 100644 --- a/lib/courier/version.rb +++ b/lib/courier/version.rb @@ -1,5 +1,5 @@ # frozen_string_literal: true module Courier - VERSION = "4.21.0" + VERSION = "4.21.1" end diff --git a/rbi/courier/models/users/preference_update_or_create_topic_params.rbi b/rbi/courier/models/users/preference_update_or_create_topic_params.rbi index 7f7e3c51..8aa2256f 100644 --- a/rbi/courier/models/users/preference_update_or_create_topic_params.rbi +++ b/rbi/courier/models/users/preference_update_or_create_topic_params.rbi @@ -81,10 +81,14 @@ module Courier ) end + # 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. sig { returns(Courier::PreferenceStatus::OrSymbol) } attr_accessor :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. sig do returns( T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]) @@ -92,6 +96,8 @@ module Courier end attr_accessor :custom_routing + # Set to true to route this topic to the channels in custom_routing instead of the + # topic's default routing. sig { returns(T.nilable(T::Boolean)) } attr_accessor :has_custom_routing @@ -104,9 +110,15 @@ module Courier ).returns(T.attached_class) end def self.new( + # 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. 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. custom_routing: nil, + # Set to true to route this topic to the channels in custom_routing instead of the + # topic's default routing. has_custom_routing: nil ) end diff --git a/rbi/courier/models/users/topic_preference.rbi b/rbi/courier/models/users/topic_preference.rbi index caef61b9..6c7c9e0b 100644 --- a/rbi/courier/models/users/topic_preference.rbi +++ b/rbi/courier/models/users/topic_preference.rbi @@ -9,19 +9,28 @@ module Courier T.any(Courier::Users::TopicPreference, Courier::Internal::AnyHash) end + # The topic's default status, returned on reads. It applies whenever the user has + # no override of their own (status equals this value). sig { returns(Courier::PreferenceStatus::TaggedSymbol) } attr_accessor :default_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. sig { returns(Courier::PreferenceStatus::TaggedSymbol) } attr_accessor :status + # The unique identifier of the subscription topic this preference applies to. sig { returns(String) } attr_accessor :topic_id + # The display name of the subscription topic, returned on reads. sig { returns(String) } attr_accessor :topic_name - # 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. sig do returns( T.nilable(T::Array[Courier::ChannelClassification::TaggedSymbol]) @@ -29,6 +38,8 @@ module Courier end attr_accessor :custom_routing + # Whether the user has chosen specific delivery channels for this topic (listed in + # custom_routing) rather than the topic's default routing. sig { returns(T.nilable(T::Boolean)) } attr_accessor :has_custom_routing @@ -44,12 +55,23 @@ module Courier ).returns(T.attached_class) end def self.new( + # The topic's default status, returned on reads. It applies whenever the user has + # no override of their own (status equals this value). default_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. status:, + # The unique identifier of the subscription topic this preference applies to. topic_id:, + # The display name of the subscription topic, returned on reads. topic_name:, - # 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. custom_routing: nil, + # Whether the user has chosen specific delivery channels for this topic (listed in + # custom_routing) rather than the topic's default routing. has_custom_routing: nil ) end diff --git a/rbi/courier/resources/audiences.rbi b/rbi/courier/resources/audiences.rbi index ff070bf3..d14694ef 100644 --- a/rbi/courier/resources/audiences.rbi +++ b/rbi/courier/resources/audiences.rbi @@ -3,7 +3,8 @@ module Courier module Resources class Audiences - # 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. sig do params( audience_id: String, @@ -17,7 +18,8 @@ module Courier ) end - # Creates or updates audience. + # Creates or replaces an audience from a filter and an AND or OR operator. + # Membership recalculates automatically as profiles change. sig do params( audience_id: String, @@ -46,7 +48,8 @@ module Courier ) end - # 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. sig do params( cursor: T.nilable(String), @@ -60,7 +63,8 @@ module Courier ) end - # 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. sig do params( audience_id: String, @@ -74,7 +78,8 @@ module Courier ) end - # 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. sig do params( audience_id: String, diff --git a/rbi/courier/resources/audit_events.rbi b/rbi/courier/resources/audit_events.rbi index 215f6a6a..6debbd55 100644 --- a/rbi/courier/resources/audit_events.rbi +++ b/rbi/courier/resources/audit_events.rbi @@ -3,7 +3,8 @@ module Courier module Resources class AuditEvents - # 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. sig do params( audit_event_id: String, @@ -17,7 +18,8 @@ module Courier ) end - # 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. sig do params( cursor: T.nilable(String), diff --git a/rbi/courier/resources/auth.rbi b/rbi/courier/resources/auth.rbi index 9895f00e..deea43a9 100644 --- a/rbi/courier/resources/auth.rbi +++ b/rbi/courier/resources/auth.rbi @@ -3,7 +3,8 @@ module Courier module Resources class Auth - # 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. sig do params( expires_in: String, diff --git a/rbi/courier/resources/automations.rbi b/rbi/courier/resources/automations.rbi index 3cbd6111..58f56a65 100644 --- a/rbi/courier/resources/automations.rbi +++ b/rbi/courier/resources/automations.rbi @@ -6,7 +6,8 @@ module Courier sig { returns(Courier::Resources::Automations::Invoke) } attr_reader :invoke - # 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. sig do params( cursor: String, diff --git a/rbi/courier/resources/automations/invoke.rbi b/rbi/courier/resources/automations/invoke.rbi index 2e583c26..7589ce59 100644 --- a/rbi/courier/resources/automations/invoke.rbi +++ b/rbi/courier/resources/automations/invoke.rbi @@ -4,10 +4,8 @@ module Courier module Resources class Automations class Invoke - # 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. sig do params( automation: @@ -31,7 +29,8 @@ module Courier ) end - # 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. sig do params( template_id: String, diff --git a/rbi/courier/resources/brands.rbi b/rbi/courier/resources/brands.rbi index afb3d19f..92973b92 100644 --- a/rbi/courier/resources/brands.rbi +++ b/rbi/courier/resources/brands.rbi @@ -3,8 +3,8 @@ module Courier module Resources class Brands - # 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. sig do params( name: String, @@ -17,7 +17,8 @@ module Courier def create(name:, settings:, id: nil, snippets: nil, request_options: {}) end - # Fetch a specific brand by brand ID. + # Returns one brand by id, including its colors, logo and styling settings, + # Handlebars snippets, and published version. sig do params( brand_id: String, @@ -31,7 +32,8 @@ module Courier ) end - # 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. sig do params( brand_id: String, @@ -52,7 +54,8 @@ module Courier ) end - # Get the list of brands. + # Lists the workspace's brands. Every entry carries its name, styling settings, + # snippets, and published version. sig do params( cursor: T.nilable(String), @@ -66,7 +69,8 @@ module Courier ) end - # 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. sig do params( brand_id: String, diff --git a/rbi/courier/resources/digests/schedules.rbi b/rbi/courier/resources/digests/schedules.rbi index 3b8acbbd..72b60a76 100644 --- a/rbi/courier/resources/digests/schedules.rbi +++ b/rbi/courier/resources/digests/schedules.rbi @@ -4,9 +4,8 @@ module Courier module Resources class Digests class Schedules - # 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. sig do params( schedule_id: String, diff --git a/rbi/courier/resources/inbound.rbi b/rbi/courier/resources/inbound.rbi index 4ebfdf65..64c703be 100644 --- a/rbi/courier/resources/inbound.rbi +++ b/rbi/courier/resources/inbound.rbi @@ -3,7 +3,8 @@ module Courier module Resources class Inbound - # 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. sig do params( event: String, diff --git a/rbi/courier/resources/journeys.rbi b/rbi/courier/resources/journeys.rbi index ca7a28a7..deacb652 100644 --- a/rbi/courier/resources/journeys.rbi +++ b/rbi/courier/resources/journeys.rbi @@ -6,12 +6,8 @@ module Courier sig { returns(Courier::Resources::Journeys::Templates) } attr_reader :templates - # 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. sig do params( name: String, @@ -67,7 +63,8 @@ module Courier ) end - # Get the list of journeys. + # Lists the workspace's journeys, each carrying a name, state, and enabled flag. + # Paged by cursor. sig do params( cursor: String, @@ -86,8 +83,8 @@ module Courier ) end - # 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. sig do params( template_id: String, @@ -101,12 +98,8 @@ module Courier ) end - # 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. sig do params( cancel_journey_request: @@ -126,8 +119,8 @@ module Courier ) end - # 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. sig do params( template_id: String, @@ -160,7 +153,8 @@ module Courier ) end - # 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. sig do params( template_id: String, @@ -174,9 +168,8 @@ module Courier ) end - # 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. sig do params( template_id: String, @@ -192,11 +185,8 @@ module Courier ) end - # 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. sig do params( template_id: String, diff --git a/rbi/courier/resources/journeys/templates.rbi b/rbi/courier/resources/journeys/templates.rbi index 3477413a..7ce36980 100644 --- a/rbi/courier/resources/journeys/templates.rbi +++ b/rbi/courier/resources/journeys/templates.rbi @@ -28,9 +28,8 @@ module Courier ) end - # 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. sig do params( notification_id: String, @@ -68,8 +67,8 @@ module Courier ) end - # 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. sig do params( notification_id: String, @@ -86,8 +85,8 @@ module Courier ) end - # 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. sig do params( notification_id: String, @@ -104,9 +103,8 @@ module Courier ) end - # 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. sig do params( notification_id: String, @@ -179,7 +177,8 @@ module Courier ) end - # 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. sig do params( notification_id: String, @@ -203,11 +202,8 @@ module Courier ) end - # 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. sig do params( notification_id: String, diff --git a/rbi/courier/resources/lists.rbi b/rbi/courier/resources/lists.rbi index 9afb8d45..45101763 100644 --- a/rbi/courier/resources/lists.rbi +++ b/rbi/courier/resources/lists.rbi @@ -6,7 +6,8 @@ module Courier sig { returns(Courier::Resources::Lists::Subscriptions) } attr_reader :subscriptions - # 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. sig do params( list_id: String, @@ -20,7 +21,8 @@ module Courier ) end - # 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. sig do params( list_id: String, @@ -38,7 +40,8 @@ module Courier ) end - # 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. sig do params( cursor: T.nilable(String), @@ -58,7 +61,8 @@ module Courier ) end - # 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. sig do params( list_id: String, @@ -72,7 +76,8 @@ module Courier ) end - # 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. sig do params( list_id: String, diff --git a/rbi/courier/resources/lists/subscriptions.rbi b/rbi/courier/resources/lists/subscriptions.rbi index 85db5ed2..594eaabe 100644 --- a/rbi/courier/resources/lists/subscriptions.rbi +++ b/rbi/courier/resources/lists/subscriptions.rbi @@ -4,7 +4,8 @@ module Courier module Resources class Lists class Subscriptions - # Get the list's subscriptions. + # Returns the users subscribed to a list with paging, each with the preferences + # recorded for that subscription. sig do params( list_id: String, @@ -55,8 +56,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -77,7 +78,8 @@ module Courier ) end - # 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. sig do params( user_id: String, diff --git a/rbi/courier/resources/messages.rbi b/rbi/courier/resources/messages.rbi index acf25449..c5906ab4 100644 --- a/rbi/courier/resources/messages.rbi +++ b/rbi/courier/resources/messages.rbi @@ -3,7 +3,8 @@ module Courier module Resources class Messages - # 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. sig do params( message_id: String, @@ -18,7 +19,8 @@ module Courier ) end - # 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. sig do params( archived: T.nilable(T::Boolean), @@ -80,11 +82,8 @@ module Courier ) end - # 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. sig do params( message_id: String, @@ -98,7 +97,8 @@ module Courier ) end - # Get message content + # Returns the rendered content Courier delivered for a message, broken out per + # channel, to confirm what the recipient received. sig do params( message_id: String, @@ -113,7 +113,8 @@ module Courier ) end - # 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. sig do params( message_id: String, @@ -130,11 +131,8 @@ module Courier ) end - # 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. sig do params( message_id: String, diff --git a/rbi/courier/resources/notifications.rbi b/rbi/courier/resources/notifications.rbi index bdb459a6..7c80098a 100644 --- a/rbi/courier/resources/notifications.rbi +++ b/rbi/courier/resources/notifications.rbi @@ -45,7 +45,8 @@ module Courier ) end - # 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. sig do params( cursor: T.nilable(String), @@ -65,7 +66,8 @@ module Courier ) end - # Archive a notification template. + # Archives a notification template, preventing new sends from referencing it. The + # template stays retrievable for its version history. sig do params( id: String, @@ -79,12 +81,9 @@ module Courier ) end - # 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. sig do params( id: String, @@ -98,7 +97,8 @@ module Courier ) end - # List versions of a notification template. + # Returns a notification template's published versions, most recent first, for + # comparison or rollback. Paged. sig do params( id: String, @@ -136,9 +136,8 @@ module Courier ) end - # 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. sig do params( id: String, @@ -158,8 +157,8 @@ module Courier ) end - # 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. sig do params( element_id: String, @@ -197,9 +196,8 @@ module Courier ) end - # 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. sig do params( locale_id: String, @@ -223,7 +221,8 @@ module Courier ) end - # 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. sig do params( id: String, @@ -245,10 +244,8 @@ module Courier ) end - # 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. sig do params( id: String, diff --git a/rbi/courier/resources/notifications/checks.rbi b/rbi/courier/resources/notifications/checks.rbi index 2b6ed984..2bd63c3e 100644 --- a/rbi/courier/resources/notifications/checks.rbi +++ b/rbi/courier/resources/notifications/checks.rbi @@ -4,7 +4,8 @@ module Courier module Resources class Notifications class Checks - # 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. sig do params( submission_id: String, @@ -24,7 +25,8 @@ module Courier ) end - # Retrieve the submission checks for a notification template. + # Returns the approval checks recorded for a template submission, each with its + # pass or fail result. sig do params( submission_id: String, @@ -41,7 +43,8 @@ module Courier ) end - # 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. sig do params( submission_id: String, diff --git a/rbi/courier/resources/profiles.rbi b/rbi/courier/resources/profiles.rbi index 418d0b6b..0b00e6a7 100644 --- a/rbi/courier/resources/profiles.rbi +++ b/rbi/courier/resources/profiles.rbi @@ -6,8 +6,8 @@ module Courier sig { returns(Courier::Resources::Profiles::Lists) } attr_reader :lists - # 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. sig do params( user_id: String, @@ -23,7 +23,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -37,7 +38,8 @@ module Courier ) end - # Update a profile + # Applies a JSON Patch to a user profile, adding, removing, or replacing + # individual fields without sending the whole object. sig do params( user_id: String, @@ -55,7 +57,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -70,11 +73,8 @@ module Courier ) end - # 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. sig do params( user_id: String, diff --git a/rbi/courier/resources/profiles/lists.rbi b/rbi/courier/resources/profiles/lists.rbi index 8a2fd818..9e4d600d 100644 --- a/rbi/courier/resources/profiles/lists.rbi +++ b/rbi/courier/resources/profiles/lists.rbi @@ -4,7 +4,8 @@ module Courier module Resources class Profiles class Lists - # 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. sig do params( user_id: String, @@ -22,7 +23,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -36,8 +38,8 @@ module Courier ) end - # 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. sig do params( user_id: String, diff --git a/rbi/courier/resources/providers.rbi b/rbi/courier/resources/providers.rbi index 3b06b579..28fe7a4d 100644 --- a/rbi/courier/resources/providers.rbi +++ b/rbi/courier/resources/providers.rbi @@ -6,8 +6,8 @@ module Courier sig { returns(Courier::Resources::Providers::Catalog) } attr_reader :catalog - # 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. sig do params( provider: String, @@ -33,7 +33,8 @@ module Courier ) end - # Fetch a single provider configuration by ID. + # Returns one configured provider by id, including its channel, provider key, + # alias, title, and current settings. sig do params( id: String, @@ -47,11 +48,8 @@ module Courier ) end - # 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. sig do params( id: String, @@ -80,8 +78,8 @@ module Courier ) end - # 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. sig do params( cursor: String, @@ -95,8 +93,8 @@ module Courier ) end - # 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. sig do params( id: String, diff --git a/rbi/courier/resources/providers/catalog.rbi b/rbi/courier/resources/providers/catalog.rbi index 7c663abf..05c49c5a 100644 --- a/rbi/courier/resources/providers/catalog.rbi +++ b/rbi/courier/resources/providers/catalog.rbi @@ -4,10 +4,8 @@ module Courier module Resources class Providers class Catalog - # 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. sig do params( channel: String, diff --git a/rbi/courier/resources/requests.rbi b/rbi/courier/resources/requests.rbi index 3e31f83a..bcfe1b5d 100644 --- a/rbi/courier/resources/requests.rbi +++ b/rbi/courier/resources/requests.rbi @@ -3,7 +3,8 @@ module Courier module Resources class Requests - # 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. sig do params( request_id: String, diff --git a/rbi/courier/resources/routing_strategies.rbi b/rbi/courier/resources/routing_strategies.rbi index ecba72a7..4c41c59c 100644 --- a/rbi/courier/resources/routing_strategies.rbi +++ b/rbi/courier/resources/routing_strategies.rbi @@ -34,8 +34,8 @@ module Courier ) end - # 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. sig do params( id: String, @@ -83,8 +83,8 @@ module Courier ) end - # 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. sig do params( id: String, diff --git a/rbi/courier/resources/send.rbi b/rbi/courier/resources/send.rbi index b7d36c2c..ecff9450 100644 --- a/rbi/courier/resources/send.rbi +++ b/rbi/courier/resources/send.rbi @@ -3,7 +3,8 @@ module Courier module Resources class Send - # 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. sig do params( message: Courier::SendMessageParams::Message::OrHash, diff --git a/rbi/courier/resources/tenants.rbi b/rbi/courier/resources/tenants.rbi index eebe3f6d..714106c8 100644 --- a/rbi/courier/resources/tenants.rbi +++ b/rbi/courier/resources/tenants.rbi @@ -9,7 +9,8 @@ module Courier sig { returns(Courier::Resources::Tenants::Templates) } attr_reader :templates - # Get a Tenant + # Returns one tenant with its name, parent tenant id, default preferences, + # properties, and the user profile applied to its members. sig do params( tenant_id: String, @@ -23,7 +24,8 @@ module Courier ) end - # Create or Replace a Tenant + # Creates or replaces a tenant from a name, parent, brand, properties, and default + # preferences supplied in the request body. sig do params( tenant_id: String, @@ -56,7 +58,8 @@ module Courier ) end - # Get a List of Tenants + # Lists the workspace's tenants, each carrying a name, parent tenant, properties, + # and default preferences. Paged. sig do params( cursor: T.nilable(String), @@ -76,7 +79,8 @@ module Courier ) end - # Delete a Tenant + # Deletes a tenant. Its members' workspace-level profiles and preferences live + # outside the tenant and are managed separately. sig do params( tenant_id: String, @@ -90,7 +94,8 @@ module Courier ) end - # 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. sig do params( tenant_id: String, diff --git a/rbi/courier/resources/tenants/preferences/items.rbi b/rbi/courier/resources/tenants/preferences/items.rbi index 9aee21a4..7bc774ae 100644 --- a/rbi/courier/resources/tenants/preferences/items.rbi +++ b/rbi/courier/resources/tenants/preferences/items.rbi @@ -5,7 +5,8 @@ module Courier class Tenants class Preferences class Items - # 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. sig do params( topic_id: String, @@ -36,7 +37,8 @@ module Courier ) end - # Remove Default Preferences For Topic + # Removes a tenant's default preference for one subscription topic, addressed by + # tenant id and topic id. sig do params( topic_id: String, diff --git a/rbi/courier/resources/tenants/templates.rbi b/rbi/courier/resources/tenants/templates.rbi index 2e40d7e1..9126980a 100644 --- a/rbi/courier/resources/tenants/templates.rbi +++ b/rbi/courier/resources/tenants/templates.rbi @@ -7,7 +7,8 @@ module Courier sig { returns(Courier::Resources::Tenants::Templates::Versions) } attr_reader :versions - # Get a Template in Tenant + # Returns a tenant's notification template with its content, version, and created, + # updated, and published timestamps. sig do params( template_id: String, @@ -24,7 +25,8 @@ module Courier ) end - # List Templates in Tenant + # Lists a tenant's notification templates, each carrying its version and published + # timestamp. Paged. sig do params( tenant_id: String, @@ -44,12 +46,8 @@ module Courier ) end - # 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. sig do params( template_id: String, @@ -66,10 +64,8 @@ module Courier ) end - # 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. sig do params( template_id: String, @@ -90,13 +86,8 @@ module Courier ) end - # 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. sig do params( template_id: String, diff --git a/rbi/courier/resources/tenants/templates/versions.rbi b/rbi/courier/resources/tenants/templates/versions.rbi index 2c27af33..fd3ed46c 100644 --- a/rbi/courier/resources/tenants/templates/versions.rbi +++ b/rbi/courier/resources/tenants/templates/versions.rbi @@ -5,13 +5,8 @@ module Courier class Tenants class Templates class Versions - # 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. sig do params( version: String, diff --git a/rbi/courier/resources/translations.rbi b/rbi/courier/resources/translations.rbi index 4f74baca..37310d57 100644 --- a/rbi/courier/resources/translations.rbi +++ b/rbi/courier/resources/translations.rbi @@ -3,7 +3,8 @@ module Courier module Resources class Translations - # Get translations by locale + # Returns the translation strings stored for one domain and locale, for use in + # localized notification content. sig do params( locale: String, @@ -21,7 +22,8 @@ module Courier ) end - # Update a translation + # Uploads the translation strings for one domain and locale. Courier uses them to + # render localized content for recipients in that locale. sig do params( locale: String, diff --git a/rbi/courier/resources/users/preferences.rbi b/rbi/courier/resources/users/preferences.rbi index e33a7622..e324d3a8 100644 --- a/rbi/courier/resources/users/preferences.rbi +++ b/rbi/courier/resources/users/preferences.rbi @@ -4,7 +4,8 @@ module Courier module Resources class Users class Preferences - # Fetch all user preferences. + # Returns a user's preference overrides with paging, one entry per subscription + # topic they have set a choice for. sig do params( user_id: String, @@ -22,23 +23,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -64,23 +50,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -105,9 +76,8 @@ module Courier ) end - # 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. sig do params( topic_id: String, @@ -128,7 +98,8 @@ module Courier ) end - # 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. sig do params( topic_id: String, @@ -149,7 +120,8 @@ module Courier ) end - # 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. sig do params( topic_id: String, diff --git a/rbi/courier/resources/users/tenants.rbi b/rbi/courier/resources/users/tenants.rbi index 6eb7592c..16d6d008 100644 --- a/rbi/courier/resources/users/tenants.rbi +++ b/rbi/courier/resources/users/tenants.rbi @@ -4,7 +4,8 @@ module Courier module Resources class Users class Tenants - # 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. sig do params( user_id: String, @@ -24,9 +25,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -42,10 +42,8 @@ module Courier ) end - # 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. sig do params( tenant_id: String, @@ -65,7 +63,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -79,7 +78,8 @@ module Courier ) end - # 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. sig do params( tenant_id: String, diff --git a/rbi/courier/resources/users/tokens.rbi b/rbi/courier/resources/users/tokens.rbi index ef582fd7..b3453627 100644 --- a/rbi/courier/resources/users/tokens.rbi +++ b/rbi/courier/resources/users/tokens.rbi @@ -4,7 +4,8 @@ module Courier module Resources class Users class Tokens - # 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. sig do params( token: String, @@ -21,7 +22,8 @@ module Courier ) end - # 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. sig do params( token: String, @@ -41,7 +43,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -55,7 +58,8 @@ module Courier ) end - # Delete User Token + # Deletes one device token for a user, addressed by the token value, so push sends + # no longer target that device. sig do params( token: String, @@ -72,7 +76,8 @@ module Courier ) end - # 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. sig do params( user_id: String, @@ -86,7 +91,8 @@ module Courier ) end - # 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. sig do params( token: String, diff --git a/rbi/courier/resources/workspace_preferences.rbi b/rbi/courier/resources/workspace_preferences.rbi index b6d3dfb7..4e29dbad 100644 --- a/rbi/courier/resources/workspace_preferences.rbi +++ b/rbi/courier/resources/workspace_preferences.rbi @@ -6,9 +6,8 @@ module Courier sig { returns(Courier::Resources::WorkspacePreferences::Topics) } attr_reader :topics - # 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. sig do params( name: String, @@ -32,7 +31,8 @@ module Courier ) end - # 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. sig do params( section_id: String, @@ -46,8 +46,8 @@ module Courier ) end - # 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. sig do params(request_options: Courier::RequestOptions::OrHash).returns( Courier::WorkspacePreferenceListResponse @@ -71,9 +71,8 @@ module Courier ) end - # 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. sig do params( brand_id: T.nilable(String), diff --git a/rbi/courier/resources/workspace_preferences/topics.rbi b/rbi/courier/resources/workspace_preferences/topics.rbi index c39b18ab..3b9eb4bc 100644 --- a/rbi/courier/resources/workspace_preferences/topics.rbi +++ b/rbi/courier/resources/workspace_preferences/topics.rbi @@ -4,9 +4,8 @@ module Courier module Resources class WorkspacePreferences class Topics - # 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. sig do params( section_id: String, @@ -49,9 +48,8 @@ module Courier ) end - # 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. sig do params( topic_id: String, @@ -68,7 +66,8 @@ module Courier ) end - # List the topics in a workspace preference. + # Returns the subscription topics inside a workspace preference, each with its + # default status and routing options. sig do params( section_id: String, @@ -82,8 +81,8 @@ module Courier ) end - # 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. sig do params( topic_id: String,