From c540bdb855f180d850feeabf1a30ed4394092b50 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 23 Jul 2026 23:47:18 +0000 Subject: [PATCH 1/3] docs(openapi): describe user topic-preference fields explicitly (#172) Add field descriptions to UsersTopicPreference and UsersTopicPreferenceUpdate so the generated API reference documents them fully (topic_id, status, default_status, has_custom_routing, custom_routing, topic_name), including the REQUIRED-is-a-topic-default semantics and the custom_routing channel set. Wrap the PreferenceStatus $ref fields in allOf so the description renders under OpenAPI 3.0. Co-authored-by: Claude Opus 4.8 (1M context) --- .stats.yml | 4 +-- ...reference_update_or_create_topic_params.rb | 18 +++++++++--- lib/courier/models/users/topic_preference.rb | 28 ++++++++++++++----- ...eference_update_or_create_topic_params.rbi | 16 +++++++++-- rbi/courier/models/users/topic_preference.rbi | 26 +++++++++++++++-- 5 files changed, 75 insertions(+), 17 deletions(-) diff --git a/.stats.yml b/.stats.yml index e2794c72..e5f81212 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-0630b37ff5ba795185e1e189b0f24d233ecd51681b6ebb7748cad8f0e8c4fcc0.yml +openapi_spec_hash: b9a8c66633e914c9a2f7b3bf275c7349 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7 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/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 From 8a8c25b54b9a8db2cd906ab09ac8729423fa35b8 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Sat, 25 Jul 2026 00:05:46 +0000 Subject: [PATCH 2/3] docs(openapi): rewrite operation descriptions for agents and SEO (#174) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites the `description` on 116 of 134 operations and fills in 14 that had none (GET /tenants, PUT /tenants/{id}, and other tenant/token/message operations). The 18 already-good descriptions are untouched. Why: these descriptions feed the API reference, the generated llms.txt, and the SDK docstrings across all seven languages. Many were either too terse to be useful to a coding agent (e.g. "Returns the specified audience by id") or long enough that Mintlify truncated them mid-sentence in llms.txt (10 sat at 300-301 chars). A prior SEO pass in mintlify-docs (#563) was silently reverted by spec syncs because it edited the generated mirror instead of this source file — this lands the work where it survives. House style, applied uniformly: - Sentence one states what the operation does using concrete nouns — actual response fields, enum values, and id formats, not vague paraphrase. - Sentence two, when present, gives the reason to reach for it or the behavior that surprises people. No status codes, validation rules, em-dashes, or marketing adjectives (those live in the reference body). - 95-160 characters, so they read fully in Google results and don't truncate in llms.txt. Each description was written against the operation's schema (required params, response properties, enums), not from assumption. This caught real errors: the message status enum has 12 values and does not include UNDELIVERABLE; POST /auth/issue-token requires both scope and expires_in (it is not "short-lived"); message content lives at /messages/{id}/output. Please give a domain check to three where behavior was inferred from HTTP semantics rather than stated in the schema: - PUT /users/{user_id}/tenants (users_tenants_addMultiple) — worded to only claim it adds; does it also remove tenants not listed in the body? - PUT /notifications/{id}/{submissionId}/checks (replaceSubmissionChecks) — worded as "the complete set supplied"; are omitted checks dropped? - GET /translations/{domain}/{locale} — says "notification content"; confirm the term. Mechanical: only operation-level `description` lines changed (verified: 0 operationId lines touched, 0 non-description lines added). Multi-line block scalars were collapsed to single quoted lines, which accounts for the deletion count. openapi.yml still parses and all 134 operations are intact. Co-authored-by: Claude --- .stats.yml | 4 +- lib/courier/resources/audiences.rb | 15 ++++-- lib/courier/resources/audit_events.rb | 6 ++- lib/courier/resources/auth.rb | 3 +- lib/courier/resources/automations.rb | 3 +- lib/courier/resources/automations/invoke.rb | 9 ++-- lib/courier/resources/brands.rb | 16 +++--- lib/courier/resources/digests/schedules.rb | 5 +- lib/courier/resources/inbound.rb | 3 +- lib/courier/resources/journeys.rb | 42 ++++++--------- lib/courier/resources/journeys/templates.rb | 28 +++++----- lib/courier/resources/lists.rb | 15 ++++-- lib/courier/resources/lists/subscriptions.rb | 10 ++-- lib/courier/resources/messages.rb | 26 +++++----- lib/courier/resources/notifications.rb | 41 +++++++-------- lib/courier/resources/notifications/checks.rb | 9 ++-- lib/courier/resources/profiles.rb | 20 +++---- lib/courier/resources/profiles/lists.rb | 10 ++-- lib/courier/resources/providers.rb | 22 ++++---- lib/courier/resources/providers/catalog.rb | 6 +-- lib/courier/resources/requests.rb | 3 +- lib/courier/resources/routing_strategies.rb | 8 +-- lib/courier/resources/send.rb | 3 +- lib/courier/resources/tenants.rb | 15 ++++-- .../resources/tenants/preferences/items.rb | 6 ++- lib/courier/resources/tenants/templates.rb | 29 ++++------- .../resources/tenants/templates/versions.rb | 9 +--- lib/courier/resources/translations.rb | 6 ++- lib/courier/resources/users/preferences.rb | 52 +++++-------------- lib/courier/resources/users/tenants.rb | 20 +++---- lib/courier/resources/users/tokens.rb | 18 ++++--- .../resources/workspace_preferences.rb | 17 +++--- .../resources/workspace_preferences/topics.rb | 17 +++--- rbi/courier/resources/audiences.rbi | 15 ++++-- rbi/courier/resources/audit_events.rbi | 6 ++- rbi/courier/resources/auth.rbi | 3 +- rbi/courier/resources/automations.rbi | 3 +- rbi/courier/resources/automations/invoke.rbi | 9 ++-- rbi/courier/resources/brands.rbi | 16 +++--- rbi/courier/resources/digests/schedules.rbi | 5 +- rbi/courier/resources/inbound.rbi | 3 +- rbi/courier/resources/journeys.rbi | 42 ++++++--------- rbi/courier/resources/journeys/templates.rbi | 28 +++++----- rbi/courier/resources/lists.rbi | 15 ++++-- rbi/courier/resources/lists/subscriptions.rbi | 10 ++-- rbi/courier/resources/messages.rbi | 26 +++++----- rbi/courier/resources/notifications.rbi | 41 +++++++-------- .../resources/notifications/checks.rbi | 9 ++-- rbi/courier/resources/profiles.rbi | 20 +++---- rbi/courier/resources/profiles/lists.rbi | 10 ++-- rbi/courier/resources/providers.rbi | 22 ++++---- rbi/courier/resources/providers/catalog.rbi | 6 +-- rbi/courier/resources/requests.rbi | 3 +- rbi/courier/resources/routing_strategies.rbi | 8 +-- rbi/courier/resources/send.rbi | 3 +- rbi/courier/resources/tenants.rbi | 15 ++++-- .../resources/tenants/preferences/items.rbi | 6 ++- rbi/courier/resources/tenants/templates.rbi | 29 ++++------- .../resources/tenants/templates/versions.rbi | 9 +--- rbi/courier/resources/translations.rbi | 6 ++- rbi/courier/resources/users/preferences.rbi | 52 +++++-------------- rbi/courier/resources/users/tenants.rbi | 20 +++---- rbi/courier/resources/users/tokens.rbi | 18 ++++--- .../resources/workspace_preferences.rbi | 17 +++--- .../workspace_preferences/topics.rbi | 17 +++--- 65 files changed, 468 insertions(+), 520 deletions(-) diff --git a/.stats.yml b/.stats.yml index e5f81212..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-0630b37ff5ba795185e1e189b0f24d233ecd51681b6ebb7748cad8f0e8c4fcc0.yml -openapi_spec_hash: b9a8c66633e914c9a2f7b3bf275c7349 +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/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/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, From 936133272f1d6b41dec5a1a32ef58ffc2b88564b Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Sat, 25 Jul 2026 00:06:09 +0000 Subject: [PATCH 3/3] release: 4.21.1 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 9 +++++++++ Gemfile.lock | 2 +- lib/courier/version.rb | 2 +- 4 files changed, 12 insertions(+), 3 deletions(-) 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/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/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