@trycourier/courier 7.21.0 → 7.22.0

package/resources/lists/lists.js

@@ -8,19 +8,36 @@ const SubscriptionsAPI = tslib_1.__importStar(require("./subscriptions.js"));
 const subscriptions_1 = require("./subscriptions.js");
 const headers_1 = require("../../internal/headers.js");
 const path_1 = require("../../internal/utils/path.js");
+/**
+ * Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern.
+ */
 class Lists extends resource_1.APIResource {
     constructor() {
         super(...arguments);
         this.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, options) {
         return this._client.get((0, path_1.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, body, options) {
         return this._client.put((0, path_1.path) `/lists/${listID}`, {
@@ -30,13 +47,25 @@ class Lists extends resource_1.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 = {}, options) {
         return this._client.get('/lists', { query, ...options });
     }
     /**
-     * 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, options) {
         return this._client.delete((0, path_1.path) `/lists/${listID}`, {
@@ -45,7 +74,13 @@ class Lists extends resource_1.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, body, options) {
         return this._client.put((0, path_1.path) `/lists/${listID}/restore`, {

package/resources/lists/lists.js.map

@@ -1 +1 @@
-{"version":3,"file":"lists.js","sourceRoot":"","sources":["../../src/resources/lists/lists.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;;AAEtF,qDAAkD;AAElD,6EAAoD;AACpD,sDAQyB;AAEzB,uDAAsD;AAEtD,uDAAiD;AAEjD,MAAa,KAAM,SAAQ,sBAAW;IAAtC;;QACE,kBAAa,GAAmC,IAAI,gBAAgB,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAkDnG,CAAC;IAhDC;;OAEG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAc,EAAE,IAAsB,EAAE,OAAwB;QACrE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,EAAE,EAAE;YAC9C,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,CACF,QAA2C,EAAE,EAC7C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAc,EAAE,OAAwB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,EAAE,EAAE;YACjD,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,MAAc,EAAE,IAAuB,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,UAAU,EAAE;YACtD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAnDD,sBAmDC;AA+CD,KAAK,CAAC,aAAa,GAAG,6BAAa,CAAC"}
+{"version":3,"file":"lists.js","sourceRoot":"","sources":["../../src/resources/lists/lists.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;;AAEtF,qDAAkD;AAElD,6EAAoD;AACpD,sDAQyB;AAEzB,uDAAsD;AAEtD,uDAAiD;AAEjD;;GAEG;AACH,MAAa,KAAM,SAAQ,sBAAW;IAAtC;;QACE,kBAAa,GAAmC,IAAI,gBAAgB,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAkFnG,CAAC;IAhFC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAc,EAAE,IAAsB,EAAE,OAAwB;QACrE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,EAAE,EAAE;YAC9C,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CACF,QAA2C,EAAE,EAC7C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAc,EAAE,OAAwB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,EAAE,EAAE;YACjD,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAc,EAAE,IAAuB,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,UAAU,EAAE;YACtD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAnFD,sBAmFC;AA+CD,KAAK,CAAC,aAAa,GAAG,6BAAa,CAAC"}

package/resources/lists/lists.mjs

@@ -4,19 +4,36 @@ import * as SubscriptionsAPI from "./subscriptions.mjs";
 import { Subscriptions, } from "./subscriptions.mjs";
 import { buildHeaders } from "../../internal/headers.mjs";
 import { path } from "../../internal/utils/path.mjs";
+/**
+ * Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern.
+ */
 export class Lists extends APIResource {
     constructor() {
         super(...arguments);
         this.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, options) {
         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, body, options) {
         return this._client.put(path `/lists/${listID}`, {
@@ -26,13 +43,25 @@ 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 = {}, options) {
         return this._client.get('/lists', { query, ...options });
     }
     /**
-     * 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, options) {
         return this._client.delete(path `/lists/${listID}`, {
@@ -41,7 +70,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, body, options) {
         return this._client.put(path `/lists/${listID}/restore`, {

package/resources/lists/lists.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"lists.mjs","sourceRoot":"","sources":["../../src/resources/lists/lists.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAElD,OAAO,KAAK,gBAAgB,4BAAwB;AACpD,OAAO,EAOL,aAAa,GACd,4BAAwB;AAEzB,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD,MAAM,OAAO,KAAM,SAAQ,WAAW;IAAtC;;QACE,kBAAa,GAAmC,IAAI,gBAAgB,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAkDnG,CAAC;IAhDC;;OAEG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAc,EAAE,IAAsB,EAAE,OAAwB;QACrE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,EAAE,EAAE;YAC9C,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,CACF,QAA2C,EAAE,EAC7C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAc,EAAE,OAAwB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,UAAU,MAAM,EAAE,EAAE;YACjD,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,MAAc,EAAE,IAAuB,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,UAAU,EAAE;YACtD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AA+CD,KAAK,CAAC,aAAa,GAAG,aAAa,CAAC"}
+{"version":3,"file":"lists.mjs","sourceRoot":"","sources":["../../src/resources/lists/lists.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAElD,OAAO,KAAK,gBAAgB,4BAAwB;AACpD,OAAO,EAOL,aAAa,GACd,4BAAwB;AAEzB,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD;;GAEG;AACH,MAAM,OAAO,KAAM,SAAQ,WAAW;IAAtC;;QACE,kBAAa,GAAmC,IAAI,gBAAgB,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAkFnG,CAAC;IAhFC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAc,EAAE,IAAsB,EAAE,OAAwB;QACrE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,EAAE,EAAE;YAC9C,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CACF,QAA2C,EAAE,EAC7C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAc,EAAE,OAAwB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,UAAU,MAAM,EAAE,EAAE;YACjD,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAc,EAAE,IAAuB,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,UAAU,EAAE;YACtD,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AA+CD,KAAK,CAAC,aAAa,GAAG,aAAa,CAAC"}

package/resources/lists/subscriptions.d.mts

@@ -3,28 +3,69 @@ import * as Shared from "../shared.mjs";
 import * as ListsAPI from "./lists.mjs";
 import { APIPromise } from "../../core/api-promise.mjs";
 import { RequestOptions } from "../../internal/request-options.mjs";
+/**
+ * Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern.
+ */
 export declare 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, query?: SubscriptionListParams | null | undefined, options?: RequestOptions): APIPromise<SubscriptionListResponse>;
     /**
      * 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>;
     /**
      * 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>;
     /**
-     * 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, params: SubscriptionSubscribeUserParams, options?: RequestOptions): APIPromise<void>;
     /**
-     * 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, params: SubscriptionUnsubscribeUserParams, options?: RequestOptions): APIPromise<void>;
 }
@@ -46,7 +87,26 @@ export interface SubscriptionListParams {
     cursor?: string | null;
 }
 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 {
     recipients: Array<ListsAPI.PutSubscriptionsRecipient>;

package/resources/lists/subscriptions.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriptions.d.mts","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAClD,OAAO,KAAK,MAAM,sBAAkB;AACpC,OAAO,KAAK,QAAQ,oBAAgB;AACpC,OAAO,EAAE,UAAU,EAAE,mCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,2CAAuC;AAGhE,qBAAa,aAAc,SAAQ,WAAW;IAC5C;;OAEG;IACH,IAAI,CACF,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,sBAAsB,GAAG,IAAI,GAAG,SAAc,EACrD,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,wBAAwB,CAAC;IAIvC;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAQ5F;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAQxG;;;OAGG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,+BAA+B,EACvC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;IASnB;;OAEG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iCAAiC,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;CAOpB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,KAAK,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAE5C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB;AAED,yBAAiB,wBAAwB,CAAC;IACxC,UAAiB,IAAI;QACnB,WAAW,EAAE,MAAM,CAAC;QAEpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAExB,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;KAClD;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,iCAAiC;IAChD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,CAAC,OAAO,WAAW,aAAa,CAAC;IACrC,OAAO,EACL,KAAK,wBAAwB,IAAI,wBAAwB,EACzD,KAAK,sBAAsB,IAAI,sBAAsB,EACrD,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,2BAA2B,IAAI,2BAA2B,EAC/D,KAAK,+BAA+B,IAAI,+BAA+B,EACvE,KAAK,iCAAiC,IAAI,iCAAiC,GAC5E,CAAC;CACH"}
+{"version":3,"file":"subscriptions.d.mts","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAClD,OAAO,KAAK,MAAM,sBAAkB;AACpC,OAAO,KAAK,QAAQ,oBAAgB;AACpC,OAAO,EAAE,UAAU,EAAE,mCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,2CAAuC;AAGhE;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C;;;;;;;;;;OAUG;IACH,IAAI,CACF,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,sBAAsB,GAAG,IAAI,GAAG,SAAc,EACrD,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,wBAAwB,CAAC;IAIvC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAsB9F;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAQxG;;;;;;;;;;OAUG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,+BAA+B,EACvC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;IASnB;;;;;;;;;;;OAWG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iCAAiC,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;CAOpB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,KAAK,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAE5C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB;AAED,yBAAiB,wBAAwB,CAAC;IACxC,UAAiB,IAAI;QACnB,WAAW,EAAE,MAAM,CAAC;QAEpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAExB,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;KAClD;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IAEtD;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,iCAAiC;IAChD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,CAAC,OAAO,WAAW,aAAa,CAAC;IACrC,OAAO,EACL,KAAK,wBAAwB,IAAI,wBAAwB,EACzD,KAAK,sBAAsB,IAAI,sBAAsB,EACrD,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,2BAA2B,IAAI,2BAA2B,EAC/D,KAAK,+BAA+B,IAAI,+BAA+B,EACvE,KAAK,iCAAiC,IAAI,iCAAiC,GAC5E,CAAC;CACH"}

package/resources/lists/subscriptions.d.ts

@@ -3,28 +3,69 @@ import * as Shared from "../shared.js";
 import * as ListsAPI from "./lists.js";
 import { APIPromise } from "../../core/api-promise.js";
 import { RequestOptions } from "../../internal/request-options.js";
+/**
+ * Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern.
+ */
 export declare 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, query?: SubscriptionListParams | null | undefined, options?: RequestOptions): APIPromise<SubscriptionListResponse>;
     /**
      * 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>;
     /**
      * 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>;
     /**
-     * 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, params: SubscriptionSubscribeUserParams, options?: RequestOptions): APIPromise<void>;
     /**
-     * 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, params: SubscriptionUnsubscribeUserParams, options?: RequestOptions): APIPromise<void>;
 }
@@ -46,7 +87,26 @@ export interface SubscriptionListParams {
     cursor?: string | null;
 }
 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 {
     recipients: Array<ListsAPI.PutSubscriptionsRecipient>;

package/resources/lists/subscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,+BAA4B;AAClD,OAAO,KAAK,MAAM,qBAAkB;AACpC,OAAO,KAAK,QAAQ,mBAAgB;AACpC,OAAO,EAAE,UAAU,EAAE,kCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,0CAAuC;AAGhE,qBAAa,aAAc,SAAQ,WAAW;IAC5C;;OAEG;IACH,IAAI,CACF,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,sBAAsB,GAAG,IAAI,GAAG,SAAc,EACrD,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,wBAAwB,CAAC;IAIvC;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAQ5F;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAQxG;;;OAGG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,+BAA+B,EACvC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;IASnB;;OAEG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iCAAiC,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;CAOpB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,KAAK,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAE5C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB;AAED,yBAAiB,wBAAwB,CAAC;IACxC,UAAiB,IAAI;QACnB,WAAW,EAAE,MAAM,CAAC;QAEpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAExB,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;KAClD;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,iCAAiC;IAChD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,CAAC,OAAO,WAAW,aAAa,CAAC;IACrC,OAAO,EACL,KAAK,wBAAwB,IAAI,wBAAwB,EACzD,KAAK,sBAAsB,IAAI,sBAAsB,EACrD,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,2BAA2B,IAAI,2BAA2B,EAC/D,KAAK,+BAA+B,IAAI,+BAA+B,EACvE,KAAK,iCAAiC,IAAI,iCAAiC,GAC5E,CAAC;CACH"}
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,+BAA4B;AAClD,OAAO,KAAK,MAAM,qBAAkB;AACpC,OAAO,KAAK,QAAQ,mBAAgB;AACpC,OAAO,EAAE,UAAU,EAAE,kCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,0CAAuC;AAGhE;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C;;;;;;;;;;OAUG;IACH,IAAI,CACF,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,sBAAsB,GAAG,IAAI,GAAG,SAAc,EACrD,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,wBAAwB,CAAC;IAIvC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAsB9F;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAQxG;;;;;;;;;;OAUG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,+BAA+B,EACvC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;IASnB;;;;;;;;;;;OAWG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iCAAiC,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,IAAI,CAAC;CAOpB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,KAAK,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAE5C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB;AAED,yBAAiB,wBAAwB,CAAC;IACxC,UAAiB,IAAI;QACnB,WAAW,EAAE,MAAM,CAAC;QAEpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAExB,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;KAClD;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IAEtD;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,iCAAiC;IAChD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,CAAC,OAAO,WAAW,aAAa,CAAC;IACrC,OAAO,EACL,KAAK,wBAAwB,IAAI,wBAAwB,EACzD,KAAK,sBAAsB,IAAI,sBAAsB,EACrD,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,2BAA2B,IAAI,2BAA2B,EAC/D,KAAK,+BAA+B,IAAI,+BAA+B,EACvE,KAAK,iCAAiC,IAAI,iCAAiC,GAC5E,CAAC;CACH"}

package/resources/lists/subscriptions.js

@@ -5,9 +5,20 @@ exports.Subscriptions = void 0;
 const resource_1 = require("../../core/resource.js");
 const headers_1 = require("../../internal/headers.js");
 const path_1 = require("../../internal/utils/path.js");
+/**
+ * Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern.
+ */
 class Subscriptions extends resource_1.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, query = {}, options) {
         return this._client.get((0, path_1.path) `/lists/${listID}/subscriptions`, { query, ...options });
@@ -15,17 +26,41 @@ class Subscriptions extends resource_1.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, body, options) {
+    add(listID, params, options) {
+        const { 'Idempotency-Key': idempotencyKey, 'x-idempotency-expiration': xIdempotencyExpiration, ...body } = params;
         return this._client.post((0, path_1.path) `/lists/${listID}/subscriptions`, {
             body,
             ...options,
-            headers: (0, headers_1.buildHeaders)([{ Accept: '*/*' }, options?.headers]),
+            headers: (0, headers_1.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, body, options) {
         return this._client.put((0, path_1.path) `/lists/${listID}/subscriptions`, {
@@ -35,8 +70,15 @@ class Subscriptions extends resource_1.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, params, options) {
         const { list_id, ...body } = params;
@@ -47,7 +89,16 @@ class Subscriptions extends resource_1.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, params, options) {
         const { list_id } = params;

package/resources/lists/subscriptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAIlD,uDAAsD;AAEtD,uDAAiD;AAEjD,MAAa,aAAc,SAAQ,sBAAW;IAC5C;;OAEG;IACH,IAAI,CACF,MAAc,EACd,QAAmD,EAAE,EACrD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,gBAAgB,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,MAAc,EAAE,IAA2B,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,gBAAgB,EAAE;YAC7D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAc,EAAE,IAAiC,EAAE,OAAwB;QACnF,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,gBAAgB,EAAE;YAC5D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,aAAa,CACX,MAAc,EACd,MAAuC,EACvC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YACvE,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,eAAe,CACb,MAAc,EACd,MAAyC,EACzC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YAC1E,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAnED,sCAmEC"}
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAIlD,uDAAsD;AAEtD,uDAAiD;AAEjD;;GAEG;AACH,MAAa,aAAc,SAAQ,sBAAW;IAC5C;;;;;;;;;;OAUG;IACH,IAAI,CACF,MAAc,EACd,QAAmD,EAAE,EACrD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,gBAAgB,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,MAAc,EAAE,MAA6B,EAAE,OAAwB;QACzE,MAAM,EACJ,iBAAiB,EAAE,cAAc,EACjC,0BAA0B,EAAE,sBAAsB,EAClD,GAAG,IAAI,EACR,GAAG,MAAM,CAAC;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,gBAAgB,EAAE;YAC7D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC;gBACpB;oBACE,MAAM,EAAE,KAAK;oBACb,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;oBAC/E,GAAG,CAAC,sBAAsB,IAAI,IAAI,CAAC,CAAC;wBAClC,EAAE,0BAA0B,EAAE,sBAAsB,EAAE;wBACxD,CAAC,CAAC,SAAS,CAAC;iBACb;gBACD,OAAO,EAAE,OAAO;aACjB,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAc,EAAE,IAAiC,EAAE,OAAwB;QACnF,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,MAAM,gBAAgB,EAAE;YAC5D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,aAAa,CACX,MAAc,EACd,MAAuC,EACvC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YACvE,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;OAWG;IACH,eAAe,CACb,MAAc,EACd,MAAyC,EACzC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YAC1E,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAvHD,sCAuHC"}

package/resources/lists/subscriptions.mjs

@@ -2,9 +2,20 @@
 import { APIResource } from "../../core/resource.mjs";
 import { buildHeaders } from "../../internal/headers.mjs";
 import { path } from "../../internal/utils/path.mjs";
+/**
+ * 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, query = {}, options) {
         return this._client.get(path `/lists/${listID}/subscriptions`, { query, ...options });
@@ -12,17 +23,41 @@ 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, body, options) {
+    add(listID, params, options) {
+        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, body, options) {
         return this._client.put(path `/lists/${listID}/subscriptions`, {
@@ -32,8 +67,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, params, options) {
         const { list_id, ...body } = params;
@@ -44,7 +86,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, params, options) {
         const { list_id } = params;

package/resources/lists/subscriptions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"subscriptions.mjs","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAIlD,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C;;OAEG;IACH,IAAI,CACF,MAAc,EACd,QAAmD,EAAE,EACrD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,gBAAgB,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,MAAc,EAAE,IAA2B,EAAE,OAAwB;QACvE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA,UAAU,MAAM,gBAAgB,EAAE;YAC7D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAc,EAAE,IAAiC,EAAE,OAAwB;QACnF,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,gBAAgB,EAAE;YAC5D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,aAAa,CACX,MAAc,EACd,MAAuC,EACvC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YACvE,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,eAAe,CACb,MAAc,EACd,MAAyC,EACzC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YAC1E,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"subscriptions.mjs","sourceRoot":"","sources":["../../src/resources/lists/subscriptions.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAIlD,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC5C;;;;;;;;;;OAUG;IACH,IAAI,CACF,MAAc,EACd,QAAmD,EAAE,EACrD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,gBAAgB,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,MAAc,EAAE,MAA6B,EAAE,OAAwB;QACzE,MAAM,EACJ,iBAAiB,EAAE,cAAc,EACjC,0BAA0B,EAAE,sBAAsB,EAClD,GAAG,IAAI,EACR,GAAG,MAAM,CAAC;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA,UAAU,MAAM,gBAAgB,EAAE;YAC7D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC;gBACpB;oBACE,MAAM,EAAE,KAAK;oBACb,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;oBAC/E,GAAG,CAAC,sBAAsB,IAAI,IAAI,CAAC,CAAC;wBAClC,EAAE,0BAA0B,EAAE,sBAAsB,EAAE;wBACxD,CAAC,CAAC,SAAS,CAAC;iBACb;gBACD,OAAO,EAAE,OAAO;aACjB,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAc,EAAE,IAAiC,EAAE,OAAwB;QACnF,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,MAAM,gBAAgB,EAAE;YAC5D,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,aAAa,CACX,MAAc,EACd,MAAuC,EACvC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YACvE,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;OAWG;IACH,eAAe,CACb,MAAc,EACd,MAAyC,EACzC,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,UAAU,OAAO,kBAAkB,MAAM,EAAE,EAAE;YAC1E,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF"}