@trycourier/courier 7.20.0 → 7.22.0

package/src/resources/profiles/profiles.ts

@@ -16,30 +16,77 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Store the contact information Courier delivers to for each user — email, phone number, push tokens, and any custom data you send to.
+ */
 export class Profiles extends APIResource {
   lists: ListsAPI.Lists = new ListsAPI.Lists(this._client);
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const profile = await client.profiles.create('user_id', {
+   *   profile: { foo: 'bar' },
+   * });
+   * ```
    */
   create(
     userID: string,
-    body: ProfileCreateParams,
+    params: ProfileCreateParams,
     options?: RequestOptions,
   ): APIPromise<ProfileCreateResponse> {
-    return this._client.post(path`/profiles/${userID}`, { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post(path`/profiles/${userID}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const profile = await client.profiles.retrieve('user_id');
+   * ```
    */
   retrieve(userID: string, options?: RequestOptions): APIPromise<ProfileRetrieveResponse> {
     return this._client.get(path`/profiles/${userID}`, options);
   }
 
   /**
-   * Update a profile
+   * Applies a JSON Patch to a user profile, adding, removing, or replacing
+   * individual fields without sending the whole object.
+   *
+   * @example
+   * ```ts
+   * await client.profiles.update('user_id', {
+   *   patch: [
+   *     {
+   *       op: 'op',
+   *       path: 'path',
+   *       value: 'value',
+   *     },
+   *   ],
+   * });
+   * ```
    */
   update(userID: string, body: ProfileUpdateParams, options?: RequestOptions): APIPromise<void> {
     return this._client.patch(path`/profiles/${userID}`, {
@@ -50,7 +97,13 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.profiles.delete('user_id');
+   * ```
    */
   delete(userID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/profiles/${userID}`, {
@@ -60,11 +113,15 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const response = await client.profiles.replace('user_id', {
+   *   profile: { foo: 'bar' },
+   * });
+   * ```
    */
   replace(
     userID: string,
@@ -96,7 +153,28 @@ export interface ProfileReplaceResponse {
 }
 
 export interface ProfileCreateParams {
+  /**
+   * Body param
+   */
   profile: { [key: string]: unknown };
+
+  /**
+   * 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 ProfileUpdateParams {

package/src/resources/providers/catalog.ts

@@ -6,12 +6,18 @@ import * as ProvidersAPI from './providers';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * Configure the channel providers Courier delivers through, and browse the provider types it supports.
+ */
 export class Catalog extends APIResource {
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const catalogs = await client.providers.catalog.list();
+   * ```
    */
   list(
     query: CatalogListParams | null | undefined = {},

package/src/resources/providers/providers.ts

@@ -9,38 +9,80 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Configure the channel providers Courier delivers through, and browse the provider types it supports.
+ */
 export class Providers extends APIResource {
   catalog: CatalogAPI.Catalog = new CatalogAPI.Catalog(this._client);
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const provider = await client.providers.create({
+   *   provider: 'provider',
+   * });
+   * ```
    */
-  create(body: ProviderCreateParams, options?: RequestOptions): APIPromise<Provider> {
-    return this._client.post('/providers', { body, ...options });
+  create(params: ProviderCreateParams, options?: RequestOptions): APIPromise<Provider> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/providers', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * Fetch a single provider configuration by ID.
+   * Returns one configured provider by id, including its channel, provider key,
+   * alias, title, and current settings.
+   *
+   * @example
+   * ```ts
+   * const provider = await client.providers.retrieve('id');
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Provider> {
     return this._client.get(path`/providers/${id}`, options);
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const provider = await client.providers.update('id', {
+   *   provider: 'provider',
+   * });
+   * ```
    */
   update(id: string, body: ProviderUpdateParams, options?: RequestOptions): APIPromise<Provider> {
     return this._client.put(path`/providers/${id}`, { body, ...options });
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const providers = await client.providers.list();
+   * ```
    */
   list(
     query: ProviderListParams | null | undefined = {},
@@ -50,8 +92,13 @@ export class Providers extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.providers.delete('id');
+   * ```
    */
   delete(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/providers/${id}`, {
@@ -168,27 +215,45 @@ export interface ProviderListResponse {
 
 export interface ProviderCreateParams {
   /**
-   * The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a
-   * known Courier provider — see the catalog endpoint for valid keys.
+   * Body param: The provider key identifying the type (e.g. "sendgrid", "twilio").
+   * Must be a known Courier provider — see the catalog endpoint for valid keys.
    */
   provider: string;
 
   /**
-   * Optional alias for this configuration.
+   * Body param: Optional alias for this configuration.
    */
   alias?: string;
 
   /**
-   * Provider-specific settings (snake_case keys). Defaults to an empty object when
-   * omitted. Use the catalog endpoint to discover required fields for a given
-   * provider — omitting a required field returns a 400 validation error.
+   * Body param: Provider-specific settings (snake_case keys). Defaults to an empty
+   * object when omitted. Use the catalog endpoint to discover required fields for a
+   * given provider — omitting a required field returns a 400 validation error.
    */
   settings?: { [key: string]: unknown };
 
   /**
-   * Optional display title. Omit to use "Default Configuration".
+   * Body param: Optional display title. Omit to use "Default Configuration".
    */
   title?: string;
+
+  /**
+   * 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 ProviderUpdateParams {

package/src/resources/requests.ts

@@ -6,9 +6,13 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Look up the messages Courier has accepted, inspect their delivery history and rendered output, and cancel, resend, or archive them.
+ */
 export class Requests extends APIResource {
   /**
-   * 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.
    */
   archive(requestID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/requests/${requestID}/archive`, {

package/src/resources/routing-strategies.ts

@@ -8,6 +8,9 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Define reusable channel routing and failover strategies, and see which templates use them.
+ */
 export class RoutingStrategies extends APIResource {
   /**
    * Create a routing strategy. Requires a name and routing configuration at minimum.
@@ -28,15 +31,32 @@ export class RoutingStrategies extends APIResource {
    * ```
    */
   create(
-    body: RoutingStrategyCreateParams,
+    params: RoutingStrategyCreateParams,
     options?: RequestOptions,
   ): APIPromise<RoutingStrategyGetResponse> {
-    return this._client.post('/routing-strategies', { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/routing-strategies', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -83,8 +103,8 @@ export class RoutingStrategies extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -323,34 +343,52 @@ export interface RoutingStrategySummary {
 
 export interface RoutingStrategyCreateParams {
   /**
-   * Human-readable name for the routing strategy.
+   * Body param: Human-readable name for the routing strategy.
    */
   name: string;
 
   /**
-   * Routing tree defining channel selection method and order.
+   * Body param: Routing tree defining channel selection method and order.
    */
   routing: Shared.MessageRouting;
 
   /**
-   * Per-channel delivery configuration. Defaults to empty if omitted.
+   * Body param: Per-channel delivery configuration. Defaults to empty if omitted.
    */
   channels?: Shared.MessageChannels | null;
 
   /**
-   * Optional description of the routing strategy.
+   * Body param: Optional description of the routing strategy.
    */
   description?: string | null;
 
   /**
-   * Per-provider delivery configuration. Defaults to empty if omitted.
+   * Body param: Per-provider delivery configuration. Defaults to empty if omitted.
    */
   providers?: Shared.MessageProviders | null;
 
   /**
-   * Optional tags for categorization.
+   * Body param: Optional tags for categorization.
    */
   tags?: Array<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 interface RoutingStrategyListParams {

package/src/resources/send.ts

@@ -3,11 +3,16 @@
 import { APIResource } from '../core/resource';
 import * as Shared from './shared';
 import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Send a message to one or more recipients — users, lists, audiences, or tenants — across every channel you have configured.
+ */
 export class Send extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -20,8 +25,25 @@ export class Send extends APIResource {
    * });
    * ```
    */
-  message(body: SendMessageParams, options?: RequestOptions): APIPromise<SendMessageResponse> {
-    return this._client.post('/send', { body, ...options });
+  message(params: SendMessageParams, options?: RequestOptions): APIPromise<SendMessageResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/send', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 }
 
@@ -37,10 +59,28 @@ export interface SendMessageResponse {
 
 export interface SendMessageParams {
   /**
-   * The message property has the following primary top-level properties. They define
-   * the destination and content of the message.
+   * Body param: The message property has the following primary top-level properties.
+   * They define the destination and content of the message.
    */
   message: SendMessageParams.Message;
+
+  /**
+   * 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 SendMessageParams {

package/src/resources/tenants/preferences/items.ts

@@ -7,9 +7,13 @@ 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 Items extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -31,7 +35,8 @@ export class Items extends APIResource {
   }
 
   /**
-   * Remove Default Preferences For Topic
+   * Removes a tenant's default preference for one subscription topic, addressed by
+   * tenant id and topic id.
    *
    * @example
    * ```ts

package/src/resources/tenants/templates/templates.ts

@@ -10,11 +10,15 @@ import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * Manage the templates and template versions scoped to a single tenant, including the ones authored in the embedded designer.
+ */
 export class Templates extends APIResource {
   versions: VersionsAPI.Versions = new VersionsAPI.Versions(this._client);
 
   /**
-   * Get a Template in Tenant
+   * Returns a tenant's notification template with its content, version, and created,
+   * updated, and published timestamps.
    *
    * @example
    * ```ts
@@ -34,7 +38,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * List Templates in Tenant
+   * Lists a tenant's notification templates, each carrying its version and published
+   * timestamp. Paged.
    *
    * @example
    * ```ts
@@ -52,12 +57,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -75,10 +76,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -101,13 +100,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts

package/src/resources/tenants/templates/versions.ts

@@ -6,15 +6,13 @@ import { APIPromise } from '../../../core/api-promise';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * Manage the templates and template versions scoped to a single tenant, including the ones authored in the embedded designer.
+ */
 export class Versions extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts