@trycourier/courier 7.21.0 → 7.22.0

package/src/resources/journeys/journeys.ts

@@ -22,16 +22,15 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Build, version, publish, invoke, and cancel multi-step notification workflows, along with the templates scoped to them.
+ */
 export class Journeys extends APIResource {
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -50,8 +49,25 @@ export class Journeys extends APIResource {
    * });
    * ```
    */
-  create(body: JourneyCreateParams, options?: RequestOptions): APIPromise<JourneyResponse> {
-    return this._client.post('/journeys', { body, ...options });
+  create(params: JourneyCreateParams, options?: RequestOptions): APIPromise<JourneyResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/journeys', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -72,7 +88,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * Get the list of journeys.
+   * Lists the workspace's journeys, each carrying a name, state, and enabled flag.
+   * Paged by cursor.
    *
    * @example
    * ```ts
@@ -87,8 +104,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -103,12 +120,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -117,13 +130,30 @@ export class Journeys extends APIResource {
    * });
    * ```
    */
-  cancel(body: JourneyCancelParams, options?: RequestOptions): APIPromise<CancelJourneyResponse> {
-    return this._client.post('/journeys/cancel', { body, ...options });
+  cancel(params: JourneyCancelParams, options?: RequestOptions): APIPromise<CancelJourneyResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/journeys/cancel', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -138,14 +168,32 @@ export class Journeys extends APIResource {
    */
   invoke(
     templateID: string,
-    body: JourneyInvokeParams,
+    params: JourneyInvokeParams,
     options?: RequestOptions,
   ): APIPromise<JourneysInvokeResponse> {
-    return this._client.post(path`/journeys/${templateID}/invoke`, { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post(path`/journeys/${templateID}/invoke`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -158,9 +206,8 @@ export class Journeys extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -169,18 +216,32 @@ export class Journeys extends APIResource {
    */
   publish(
     templateID: string,
-    body: JourneyPublishParams | null | undefined = {},
+    params: JourneyPublishParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<JourneyResponse> {
-    return this._client.post(path`/journeys/${templateID}/publish`, { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params ?? {};
+    return this._client.post(path`/journeys/${templateID}/publish`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -1135,16 +1196,43 @@ export interface JourneysListResponse {
 }
 
 export interface JourneyCreateParams {
+  /**
+   * Body param
+   */
   name: string;
 
+  /**
+   * Body param
+   */
   nodes: Array<JourneyNode>;
 
+  /**
+   * Body param
+   */
   enabled?: boolean;
 
   /**
-   * Lifecycle state of a journey.
+   * Body param: Lifecycle state of a journey.
    */
   state?: JourneyState;
+
+  /**
+   * 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 JourneyRetrieveParams {
@@ -1172,26 +1260,68 @@ export type JourneyCancelParams = JourneyCancelParams.ByCancelationToken | Journ
 
 export declare namespace JourneyCancelParams {
   export interface ByCancelationToken {
+    /**
+     * Body param
+     */
     cancelation_token: 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 ByRunID {
+    /**
+     * Body param
+     */
     run_id: 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 JourneyInvokeParams {
   /**
-   * Data payload passed to the journey. The expected shape can be predefined using
-   * the schema builder in the journey editor. This data is available in journey
-   * steps for condition evaluation and template variable interpolation. Can also
-   * contain user identifiers (user_id, userId, anonymousId) if not provided
-   * elsewhere.
+   * Body param: Data payload passed to the journey. The expected shape can be
+   * predefined using the schema builder in the journey editor. This data is
+   * available in journey steps for condition evaluation and template variable
+   * interpolation. Can also contain user identifiers (user_id, userId, anonymousId)
+   * if not provided elsewhere.
    */
   data?: { [key: string]: unknown };
 
   /**
-   * Profile data for the user. Can contain contact information (email,
+   * Body param: Profile data for the user. Can contain contact information (email,
    * phone_number), user identifiers (user_id, userId, anonymousId), or any custom
    * profile fields. Profile fields are merged with any existing stored profile for
    * the user. Include context.tenant_id to load a tenant-scoped profile for
@@ -1200,14 +1330,53 @@ export interface JourneyInvokeParams {
   profile?: { [key: string]: unknown };
 
   /**
-   * A unique identifier for the user. If not provided, the system will attempt to
-   * resolve the user identifier from profile or data objects.
+   * Body param: A unique identifier for the user. If not provided, the system will
+   * attempt to resolve the user identifier from profile or data objects.
    */
   user_id?: 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 JourneyPublishParams {
+  /**
+   * Body param
+   */
   version?: 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 JourneyReplaceParams {

package/src/resources/journeys/templates.ts

@@ -9,6 +9,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Build, version, publish, invoke, and cancel multi-step notification workflows, along with the templates scoped to them.
+ */
 export class Templates extends APIResource {
   /**
    * Create a notification template scoped to this journey. Defaults to `DRAFT`
@@ -34,16 +37,32 @@ export class Templates extends APIResource {
    */
   create(
     templateID: string,
-    body: TemplateCreateParams,
+    params: TemplateCreateParams,
     options?: RequestOptions,
   ): APIPromise<JourneysAPI.JourneyTemplateGetResponse> {
-    return this._client.post(path`/journeys/${templateID}/templates`, { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post(path`/journeys/${templateID}/templates`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -81,8 +100,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -100,8 +119,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -121,9 +140,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -133,11 +151,25 @@ export class Templates extends APIResource {
    * ```
    */
   publish(notificationID: string, params: TemplatePublishParams, options?: RequestOptions): APIPromise<void> {
-    const { templateId, ...body } = params;
+    const {
+      templateId,
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
     return this._client.post(path`/journeys/${templateId}/templates/${notificationID}/publish`, {
       body,
       ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+      headers: buildHeaders([
+        {
+          Accept: '*/*',
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
     });
   }
 
@@ -201,7 +233,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -228,11 +261,8 @@ export class Templates extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -256,13 +286,43 @@ export class Templates extends APIResource {
 }
 
 export interface TemplateCreateParams {
+  /**
+   * Body param
+   */
   channel: string;
 
+  /**
+   * Body param
+   */
   notification: TemplateCreateParams.Notification;
 
+  /**
+   * Body param
+   */
   providerKey?: string;
 
+  /**
+   * Body param
+   */
   state?: 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 namespace TemplateCreateParams {
@@ -340,6 +400,24 @@ export interface TemplatePublishParams {
    * Body param
    */
   version?: 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 TemplatePutContentParams {

package/src/resources/lists/lists.ts

@@ -17,18 +17,35 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern.
+ */
 export class Lists extends APIResource {
   subscriptions: SubscriptionsAPI.Subscriptions = new SubscriptionsAPI.Subscriptions(this._client);
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const subscriptionList = await client.lists.retrieve(
+   *   'list_id',
+   * );
+   * ```
    */
   retrieve(listID: string, options?: RequestOptions): APIPromise<SubscriptionList> {
     return this._client.get(path`/lists/${listID}`, options);
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.lists.update('list_id', { name: 'name' });
+   * ```
    */
   update(listID: string, body: ListUpdateParams, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/lists/${listID}`, {
@@ -39,7 +56,13 @@ export class Lists extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const lists = await client.lists.list();
+   * ```
    */
   list(
     query: ListListParams | null | undefined = {},
@@ -49,7 +72,13 @@ export class Lists extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.lists.delete('list_id');
+   * ```
    */
   delete(listID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/lists/${listID}`, {
@@ -59,7 +88,13 @@ export class Lists extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.lists.restore('list_id');
+   * ```
    */
   restore(listID: string, body: ListRestoreParams, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/lists/${listID}/restore`, {