@trycourier/courier 7.21.0 → 7.22.0

package/src/resources/lists/subscriptions.ts

@@ -8,9 +8,20 @@ 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 Subscriptions extends APIResource {
   /**
-   * Get the list's subscriptions.
+   * Returns the users subscribed to a list with paging, each with the preferences
+   * recorded for that subscription.
+   *
+   * @example
+   * ```ts
+   * const subscriptions = await client.lists.subscriptions.list(
+   *   'list_id',
+   * );
+   * ```
    */
   list(
     listID: string,
@@ -23,18 +34,46 @@ export class Subscriptions extends APIResource {
   /**
    * Subscribes additional users to the list, without modifying existing
    * subscriptions. If the list does not exist, it will be automatically created.
+   *
+   * @example
+   * ```ts
+   * await client.lists.subscriptions.add('list_id', {
+   *   recipients: [{ recipientId: 'recipientId' }],
+   * });
+   * ```
    */
-  add(listID: string, body: SubscriptionAddParams, options?: RequestOptions): APIPromise<void> {
+  add(listID: string, params: SubscriptionAddParams, options?: RequestOptions): APIPromise<void> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
     return this._client.post(path`/lists/${listID}/subscriptions`, {
       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,
+      ]),
     });
   }
 
   /**
    * Subscribes the users to the list, overwriting existing subscriptions. If the
    * list does not exist, it will be automatically created.
+   *
+   * @example
+   * ```ts
+   * await client.lists.subscriptions.subscribe('list_id', {
+   *   recipients: [{ recipientId: 'recipientId' }],
+   * });
+   * ```
    */
   subscribe(listID: string, body: SubscriptionSubscribeParams, options?: RequestOptions): APIPromise<void> {
     return this._client.put(path`/lists/${listID}/subscriptions`, {
@@ -45,8 +84,15 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.lists.subscriptions.subscribeUser('user_id', {
+   *   list_id: 'list_id',
+   * });
+   * ```
    */
   subscribeUser(
     userID: string,
@@ -62,7 +108,16 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.lists.subscriptions.unsubscribeUser(
+   *   'user_id',
+   *   { list_id: 'list_id' },
+   * );
+   * ```
    */
   unsubscribeUser(
     userID: string,
@@ -101,7 +156,28 @@ export interface SubscriptionListParams {
 }
 
 export interface SubscriptionAddParams {
+  /**
+   * Body param
+   */
   recipients: Array<ListsAPI.PutSubscriptionsRecipient>;
+
+  /**
+   * 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 SubscriptionSubscribeParams {

package/src/resources/messages.ts

@@ -6,16 +6,21 @@ import { APIPromise } from '../core/api-promise';
 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 Messages extends APIResource {
   /**
-   * 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.
    */
   retrieve(messageID: string, options?: RequestOptions): APIPromise<MessageRetrieveResponse> {
     return this._client.get(path`/messages/${messageID}`, options);
   }
 
   /**
-   * 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.
    */
   list(
     query: MessageListParams | null | undefined = {},
@@ -25,25 +30,24 @@ export class Messages extends APIResource {
   }
 
   /**
-   * 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.
    */
   cancel(messageID: string, options?: RequestOptions): APIPromise<MessageDetails> {
     return this._client.post(path`/messages/${messageID}/cancel`, options);
   }
 
   /**
-   * Get message content
+   * Returns the rendered content Courier delivered for a message, broken out per
+   * channel, to confirm what the recipient received.
    */
   content(messageID: string, options?: RequestOptions): APIPromise<MessageContentResponse> {
     return this._client.get(path`/messages/${messageID}/output`, options);
   }
 
   /**
-   * 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.
    */
   history(
     messageID: string,
@@ -54,11 +58,8 @@ export class Messages extends APIResource {
   }
 
   /**
-   * 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.
    */
   resend(messageID: string, options?: RequestOptions): APIPromise<MessageResendResponse> {
     return this._client.post(path`/messages/${messageID}/resend`, options);

package/src/resources/notifications/checks.ts

@@ -7,9 +7,13 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Create, update, version, publish, and localize notification templates and their content.
+ */
 export class Checks extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -38,7 +42,8 @@ export class Checks extends APIResource {
   }
 
   /**
-   * Retrieve the submission checks for a notification template.
+   * Returns the approval checks recorded for a template submission, each with its
+   * pass or fail result.
    *
    * @example
    * ```ts
@@ -58,7 +63,8 @@ export class Checks extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts

package/src/resources/notifications/notifications.ts

@@ -16,6 +16,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Create, update, version, publish, and localize notification templates and their content.
+ */
 export class Notifications extends APIResource {
   checks: ChecksAPI.Checks = new ChecksAPI.Checks(this._client);
 
@@ -46,8 +49,28 @@ export class Notifications extends APIResource {
    *   });
    * ```
    */
-  create(body: NotificationCreateParams, options?: RequestOptions): APIPromise<NotificationTemplateResponse> {
-    return this._client.post('/notifications', { body, ...options });
+  create(
+    params: NotificationCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<NotificationTemplateResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/notifications', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -69,7 +92,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -84,7 +108,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * Archive a notification template.
+   * Archives a notification template, preventing new sends from referencing it. The
+   * template stays retrievable for its version history.
    *
    * @example
    * ```ts
@@ -99,12 +124,9 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -117,7 +139,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * List versions of a notification template.
+   * Returns a notification template's published versions, most recent first, for
+   * comparison or rollback. Paged.
    *
    * @example
    * ```ts
@@ -144,20 +167,33 @@ export class Notifications extends APIResource {
    */
   publish(
     id: string,
-    body: NotificationPublishParams | null | undefined = {},
+    params: NotificationPublishParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<void> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params ?? {};
     return this._client.post(path`/notifications/${id}/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,
+      ]),
     });
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -180,8 +216,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -204,9 +240,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -231,7 +266,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -261,10 +297,8 @@ export class Notifications extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -805,16 +839,34 @@ export type NotificationRetrieveContentResponse = NotificationContentGetResponse
 
 export interface NotificationCreateParams {
   /**
-   * Core template fields used in POST and PUT request bodies (nested under a
-   * `notification` key) and returned at the top level in responses.
+   * Body param: Core template fields used in POST and PUT request bodies (nested
+   * under a `notification` key) and returned at the top level in responses.
    */
   notification: NotificationTemplatePayload;
 
   /**
-   * Template state after creation. Case-insensitive input, normalized to uppercase
-   * in the response. Defaults to "DRAFT".
+   * Body param: Template state after creation. Case-insensitive input, normalized to
+   * uppercase in the response. Defaults to "DRAFT".
    */
   state?: 'DRAFT' | 'PUBLISHED';
+
+  /**
+   * 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 NotificationRetrieveParams {
@@ -856,9 +908,28 @@ export interface NotificationListVersionsParams {
 
 export interface NotificationPublishParams {
   /**
-   * Historical version to publish (e.g. "v001"). Omit to publish the current draft.
+   * Body param: Historical version to publish (e.g. "v001"). Omit to publish the
+   * current draft.
    */
   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 NotificationPutContentParams {

package/src/resources/profiles/lists.ts

@@ -4,12 +4,24 @@ import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
 import * as ProfilesAPI from './profiles';
 import { APIPromise } from '../../core/api-promise';
+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 Lists extends APIResource {
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const list = await client.profiles.lists.retrieve(
+   *   'user_id',
+   * );
+   * ```
    */
   retrieve(
     userID: string,
@@ -20,22 +32,53 @@ export class Lists extends APIResource {
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const list = await client.profiles.lists.delete('user_id');
+   * ```
    */
   delete(userID: string, options?: RequestOptions): APIPromise<ListDeleteResponse> {
     return this._client.delete(path`/profiles/${userID}/lists`, options);
   }
 
   /**
-   * 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.
+   *
+   * @example
+   * ```ts
+   * const response = await client.profiles.lists.subscribe(
+   *   'user_id',
+   *   { lists: [{ listId: 'listId' }] },
+   * );
+   * ```
    */
   subscribe(
     userID: string,
-    body: ListSubscribeParams,
+    params: ListSubscribeParams,
     options?: RequestOptions,
   ): APIPromise<ListSubscribeResponse> {
-    return this._client.post(path`/profiles/${userID}/lists`, { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post(path`/profiles/${userID}/lists`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 }
 
@@ -89,7 +132,28 @@ export interface ListRetrieveParams {
 }
 
 export interface ListSubscribeParams {
+  /**
+   * Body param
+   */
   lists: Array<ProfilesAPI.SubscribeToListsRequestItem>;
+
+  /**
+   * 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 declare namespace Lists {