@trycourier/courier 7.20.0 → 7.22.0

package/src/resources/tenants/tenants.ts

@@ -20,12 +20,16 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Manage tenants — the organizations, teams, or accounts your users belong to — along with their users and default preferences.
+ */
 export class Tenants extends APIResource {
   preferences: PreferencesAPI.Preferences = new PreferencesAPI.Preferences(this._client);
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
 
   /**
-   * Get a Tenant
+   * Returns one tenant with its name, parent tenant id, default preferences,
+   * properties, and the user profile applied to its members.
    *
    * @example
    * ```ts
@@ -37,7 +41,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Create or Replace a Tenant
+   * Creates or replaces a tenant from a name, parent, brand, properties, and default
+   * preferences supplied in the request body.
    *
    * @example
    * ```ts
@@ -51,7 +56,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Get a List of Tenants
+   * Lists the workspace's tenants, each carrying a name, parent tenant, properties,
+   * and default preferences. Paged.
    *
    * @example
    * ```ts
@@ -66,7 +72,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * Delete a Tenant
+   * Deletes a tenant. Its members' workspace-level profiles and preferences live
+   * outside the tenant and are managed separately.
    *
    * @example
    * ```ts
@@ -81,7 +88,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts

package/src/resources/translations.ts

@@ -6,9 +6,13 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Store and retrieve the translation strings Courier uses to render localized template content.
+ */
 export class Translations extends APIResource {
   /**
-   * Get translations by locale
+   * Returns the translation strings stored for one domain and locale, for use in
+   * localized notification content.
    */
   retrieve(locale: string, params: TranslationRetrieveParams, options?: RequestOptions): APIPromise<string> {
     const { domain } = params;
@@ -16,7 +20,8 @@ export class Translations extends APIResource {
   }
 
   /**
-   * Update a translation
+   * Uploads the translation strings for one domain and locale. Courier uses them to
+   * render localized content for recipients in that locale.
    */
   update(locale: string, params: TranslationUpdateParams, options?: RequestOptions): APIPromise<void> {
     const { domain, body } = params;

package/src/resources/users/preferences.ts

@@ -7,9 +7,13 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Read and write a single user's notification preferences, per topic and per channel.
+ */
 export class Preferences extends APIResource {
   /**
-   * Fetch all user preferences.
+   * Returns a user's preference overrides with paging, one entry per subscription
+   * topic they have set a choice for.
    *
    * @example
    * ```ts
@@ -27,23 +31,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -72,23 +61,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -116,14 +90,31 @@ export class Preferences extends APIResource {
     params: PreferenceBulkUpdateParams,
     options?: RequestOptions,
   ): APIPromise<PreferenceBulkUpdateResponse> {
-    const { tenant_id, ...body } = params;
-    return this._client.post(path`/users/${userID}/preferences`, { query: { tenant_id }, body, ...options });
+    const {
+      tenant_id,
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post(path`/users/${userID}/preferences`, {
+      query: { tenant_id },
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -146,7 +137,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -166,7 +158,8 @@ export class Preferences extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -216,19 +209,40 @@ export interface BulkPreferenceTopic {
 }
 
 export interface TopicPreference {
+  /**
+   * 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: Shared.PreferenceStatus;
 
+  /**
+   * 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: Shared.PreferenceStatus;
 
+  /**
+   * The unique identifier of the subscription topic this preference applies to.
+   */
   topic_id: string;
 
+  /**
+   * The display name of the subscription topic, returned on reads.
+   */
   topic_name: string;
 
   /**
-   * 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?: Array<Shared.ChannelClassification> | null;
 
+  /**
+   * 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?: boolean | null;
 }
 
@@ -346,6 +360,24 @@ export interface PreferenceBulkUpdateParams {
    * Query param: Update the preferences of a user for this specific tenant context.
    */
   tenant_id?: string | null;
+
+  /**
+   * Header param: A unique key that makes this request idempotent. If Courier
+   * receives another request with the same `Idempotency-Key`, it returns the stored
+   * response from the first request without performing the operation again
+   * (including the original status code and any error). Use it to safely retry
+   * `POST` requests after network failures without risking duplicate sends. The key
+   * is scoped to this endpoint.
+   */
+  'Idempotency-Key'?: string;
+
+  /**
+   * Header param: How long the idempotency key remains valid, as a Unix epoch
+   * timestamp in seconds or an ISO 8601 date string. Only applies when
+   * `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+   * maximum is 1 year.
+   */
+  'x-idempotency-expiration'?: string;
 }
 
 export namespace PreferenceBulkUpdateParams {
@@ -418,13 +450,23 @@ export interface PreferenceUpdateOrCreateTopicParams {
 
 export namespace PreferenceUpdateOrCreateTopicParams {
   export interface Topic {
+    /**
+     * 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: Shared.PreferenceStatus;
 
     /**
-     * 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?: Array<Shared.ChannelClassification> | null;
 
+    /**
+     * Set to true to route this topic to the channels in custom_routing instead of the
+     * topic's default routing.
+     */
     has_custom_routing?: boolean | null;
   }
 }

package/src/resources/users/tenants.ts

@@ -7,9 +7,13 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Associate a user with one or more tenants, and read or remove those associations.
+ */
 export class Tenants extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -25,9 +29,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -45,10 +48,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -67,7 +68,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -82,7 +84,8 @@ export class Tenants extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts

package/src/resources/users/tokens.ts

@@ -6,9 +6,13 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Register and manage the APNS and FCM device tokens Courier delivers push notifications to.
+ */
 export class Tokens extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -27,7 +31,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -47,7 +52,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -59,7 +65,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * Delete User Token
+   * Deletes one device token for a user, addressed by the token value, so push sends
+   * no longer target that device.
    *
    * @example
    * ```ts
@@ -77,7 +84,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -92,7 +100,8 @@ export class Tokens extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts

package/src/resources/workspace-preferences/topics.ts

@@ -8,11 +8,13 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Manage the workspace catalog of subscription topics, the sections that group them, and publishing the preference page.
+ */
 export class Topics extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -25,16 +27,32 @@ export class Topics extends APIResource {
    */
   create(
     sectionID: string,
-    body: TopicCreateParams,
+    params: TopicCreateParams,
     options?: RequestOptions,
   ): APIPromise<WorkspacePreferencesAPI.WorkspacePreferenceTopicGetResponse> {
-    return this._client.post(path`/preferences/sections/${sectionID}/topics`, { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post(path`/preferences/sections/${sectionID}/topics`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -55,7 +73,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * List the topics in a workspace preference.
+   * Returns the subscription topics inside a workspace preference, each with its
+   * default status and routing options.
    *
    * @example
    * ```ts
@@ -73,8 +92,8 @@ export class Topics extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -124,40 +143,62 @@ export class Topics extends APIResource {
 
 export interface TopicCreateParams {
   /**
-   * The default subscription status applied when a recipient has not set their own.
+   * Body param: The default subscription status applied when a recipient has not set
+   * their own.
    */
   default_status: 'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED';
 
   /**
-   * Human-readable name for the preference topic.
+   * Body param: Human-readable name for the preference topic.
    */
   name: string;
 
   /**
-   * Preference controls a recipient may customize for this topic. Defaults to empty
-   * if omitted.
+   * Body param: Preference controls a recipient may customize for this topic.
+   * Defaults to empty if omitted.
    */
   allowed_preferences?: Array<'snooze' | 'channel_preferences'> | null;
 
   /**
-   * Optional description shown under the topic on the hosted preferences page.
+   * Body param: Optional description shown under the topic on the hosted preferences
+   * page.
    */
   description?: string | null;
 
   /**
-   * Whether to include a list-unsubscribe header on emails for this topic.
+   * Body param: Whether to include a list-unsubscribe header on emails for this
+   * topic.
    */
   include_unsubscribe_header?: boolean | null;
 
   /**
-   * Default channels delivered for this topic. Defaults to empty if omitted.
+   * Body param: Default channels delivered for this topic. Defaults to empty if
+   * omitted.
    */
   routing_options?: Array<Shared.ChannelClassification> | null;
 
   /**
-   * Arbitrary metadata associated with the topic.
+   * Body param: Arbitrary metadata associated with the topic.
    */
   topic_data?: { [key: string]: unknown } | null;
+
+  /**
+   * Header param: A unique key that makes this request idempotent. If Courier
+   * receives another request with the same `Idempotency-Key`, it returns the stored
+   * response from the first request without performing the operation again
+   * (including the original status code and any error). Use it to safely retry
+   * `POST` requests after network failures without risking duplicate sends. The key
+   * is scoped to this endpoint.
+   */
+  'Idempotency-Key'?: string;
+
+  /**
+   * Header param: How long the idempotency key remains valid, as a Unix epoch
+   * timestamp in seconds or an ISO 8601 date string. Only applies when
+   * `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+   * maximum is 1 year.
+   */
+  'x-idempotency-expiration'?: string;
 }
 
 export interface TopicRetrieveParams {