@trycourier/courier 7.21.0 → 7.23.0

package/resources/workspace-preferences/workspace-preferences.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-preferences.mjs","sourceRoot":"","sources":["../../src/resources/workspace-preferences/workspace-preferences.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAElD,OAAO,KAAK,SAAS,qBAAiB;AACtC,OAAO,EAKL,MAAM,GACP,qBAAiB;AAElB,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD,MAAM,OAAO,oBAAqB,SAAQ,WAAW;IAArD;;QACE,WAAM,GAAqB,IAAI,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAsGhE,CAAC;IApGC;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,IAAqC,EACrC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAiB,EAAE,OAAwB;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,yBAAyB,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAwB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAiB,EAAE,OAAwB;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,yBAAyB,SAAS,EAAE,EAAE;YACnE,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,OAAO,CACL,OAA4D,EAAE,EAC9D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CACL,SAAiB,EACjB,IAAsC,EACtC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,yBAAyB,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC1F,CAAC;CACF;AAmYD,oBAAoB,CAAC,MAAM,GAAG,MAAM,CAAC"}
+{"version":3,"file":"workspace-preferences.mjs","sourceRoot":"","sources":["../../src/resources/workspace-preferences/workspace-preferences.ts"],"names":[],"mappings":"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"}

package/src/client.ts

@@ -55,6 +55,23 @@ import {
   Logo,
   WidgetBackground,
 } from './resources/brands';
+import {
+  Broadcast,
+  BroadcastCreateParams,
+  BroadcastListParams,
+  BroadcastListResponse,
+  BroadcastPutContentParams,
+  BroadcastRetrieveContentParams,
+  BroadcastSchedule,
+  BroadcastScheduleParams,
+  BroadcastSendParams,
+  BroadcastUpdateParams,
+  Broadcasts,
+  CreateBroadcastRequest,
+  ScheduleBroadcastRequest,
+  SendBroadcastRequest,
+  UpdateBroadcastRequest,
+} from './resources/broadcasts';
 import { Inbound, InboundTrackEventParams, InboundTrackEventResponse } from './resources/inbound';
 import {
   MessageContentResponse,
@@ -101,6 +118,7 @@ import {
   DigestInstanceListResponse,
   Digests,
 } from './resources/digests/digests';
+import { Inbox } from './resources/inbox/inbox';
 import {
   CancelJourneyRequest,
   CancelJourneyResponse,
@@ -961,24 +979,80 @@ export class Courier {
 
   static toFile = Uploads.toFile;
 
+  /**
+   * Send a message to one or more recipients — users, lists, audiences, or tenants — across every channel you have configured.
+   */
   send: API.Send = new API.Send(this);
+  /**
+   * Define filter-based groups whose membership Courier recalculates as user profiles change.
+   */
   audiences: API.Audiences = new API.Audiences(this);
+  /**
+   * Configure the channel providers Courier delivers through, and browse the provider types it supports.
+   */
   providers: API.Providers = new API.Providers(this);
+  /**
+   * Read the audit trail of configuration and access changes in your workspace.
+   */
   auditEvents: API.AuditEvents = new API.AuditEvents(this);
+  /**
+   * Issue scoped, short-lived JWTs so client-side SDKs — Inbox, Preferences, and the embedded designer — can call Courier as a single user. Server-side requests authenticate with your workspace API key instead.
+   */
   auth: API.Auth = new API.Auth(this);
+  /**
+   * Invoke a stored automation template or an ad hoc automation defined in the request.
+   */
   automations: API.Automations = new API.Automations(this);
+  /**
+   * Build, version, publish, invoke, and cancel multi-step notification workflows, along with the templates scoped to them.
+   */
   journeys: API.Journeys = new API.Journeys(this);
+  broadcasts: API.Broadcasts = new API.Broadcasts(this);
+  /**
+   * Manage the logos, colors, and layout that give the templates you send a consistent look.
+   */
   brands: API.Brands = new API.Brands(this);
   digests: API.Digests = new API.Digests(this);
+  /**
+   * Record an inbound event that triggers the journeys and automations mapped to it.
+   */
   inbound: API.Inbound = new API.Inbound(this);
+  /**
+   * Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern.
+   */
   lists: API.Lists = new API.Lists(this);
+  inbox: API.Inbox = new API.Inbox(this);
+  /**
+   * Look up the messages Courier has accepted, inspect their delivery history and rendered output, and cancel, resend, or archive them.
+   */
   messages: API.Messages = new API.Messages(this);
+  /**
+   * Look up the messages Courier has accepted, inspect their delivery history and rendered output, and cancel, resend, or archive them.
+   */
   requests: API.Requests = new API.Requests(this);
+  /**
+   * Create, update, version, publish, and localize notification templates and their content.
+   */
   notifications: API.Notifications = new API.Notifications(this);
+  /**
+   * Define reusable channel routing and failover strategies, and see which templates use them.
+   */
   routingStrategies: API.RoutingStrategies = new API.RoutingStrategies(this);
+  /**
+   * Manage the workspace catalog of subscription topics, the sections that group them, and publishing the preference page.
+   */
   workspacePreferences: API.WorkspacePreferences = new API.WorkspacePreferences(this);
+  /**
+   * Store the contact information Courier delivers to for each user — email, phone number, push tokens, and any custom data you send to.
+   */
   profiles: API.Profiles = new API.Profiles(this);
+  /**
+   * Manage tenants — the organizations, teams, or accounts your users belong to — along with their users and default preferences.
+   */
   tenants: API.Tenants = new API.Tenants(this);
+  /**
+   * Store and retrieve the translation strings Courier uses to render localized template content.
+   */
   translations: API.Translations = new API.Translations(this);
   users: API.Users = new API.Users(this);
 }
@@ -990,10 +1064,12 @@ Courier.AuditEvents = AuditEvents;
 Courier.Auth = Auth;
 Courier.Automations = Automations;
 Courier.Journeys = Journeys;
+Courier.Broadcasts = Broadcasts;
 Courier.Brands = Brands;
 Courier.Digests = Digests;
 Courier.Inbound = Inbound;
 Courier.Lists = Lists;
+Courier.Inbox = Inbox;
 Courier.Messages = Messages;
 Courier.Requests = Requests;
 Courier.Notifications = Notifications;
@@ -1103,6 +1179,24 @@ export declare namespace Courier {
     type JourneyReplaceParams as JourneyReplaceParams,
   };
 
+  export {
+    Broadcasts as Broadcasts,
+    type Broadcast as Broadcast,
+    type BroadcastListResponse as BroadcastListResponse,
+    type BroadcastSchedule as BroadcastSchedule,
+    type CreateBroadcastRequest as CreateBroadcastRequest,
+    type ScheduleBroadcastRequest as ScheduleBroadcastRequest,
+    type SendBroadcastRequest as SendBroadcastRequest,
+    type UpdateBroadcastRequest as UpdateBroadcastRequest,
+    type BroadcastCreateParams as BroadcastCreateParams,
+    type BroadcastUpdateParams as BroadcastUpdateParams,
+    type BroadcastListParams as BroadcastListParams,
+    type BroadcastPutContentParams as BroadcastPutContentParams,
+    type BroadcastRetrieveContentParams as BroadcastRetrieveContentParams,
+    type BroadcastScheduleParams as BroadcastScheduleParams,
+    type BroadcastSendParams as BroadcastSendParams,
+  };
+
   export {
     Brands as Brands,
     type Brand as Brand,
@@ -1148,6 +1242,8 @@ export declare namespace Courier {
     type ListRestoreParams as ListRestoreParams,
   };
 
+  export { Inbox as Inbox };
+
   export {
     Messages as Messages,
     type MessageDetails as MessageDetails,

package/src/resources/audiences.ts

@@ -7,16 +7,21 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Define filter-based groups whose membership Courier recalculates as user profiles change.
+ */
 export class Audiences extends APIResource {
   /**
-   * Returns the specified audience by id.
+   * Returns one audience with its name, description, and the filter and AND or OR
+   * operator that decide which users belong to it.
    */
   retrieve(audienceID: string, options?: RequestOptions): APIPromise<Audience> {
     return this._client.get(path`/audiences/${audienceID}`, options);
   }
 
   /**
-   * Creates or updates audience.
+   * Creates or replaces an audience from a filter and an AND or OR operator.
+   * Membership recalculates automatically as profiles change.
    */
   update(
     audienceID: string,
@@ -27,7 +32,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Get the audiences associated with the authorization token.
+   * Returns the audiences in the workspace with paging. Audiences are filter-based
+   * groups that recalculate as user profiles change.
    */
   list(
     query: AudienceListParams | null | undefined = {},
@@ -37,7 +43,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Deletes the specified audience.
+   * Deletes an audience permanently, so update any caller sending to it by audience
+   * id first. Those sends fail once the audience is gone.
    */
   delete(audienceID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/audiences/${audienceID}`, {
@@ -47,7 +54,8 @@ export class Audiences extends APIResource {
   }
 
   /**
-   * Get list of members of an audience.
+   * Returns the users currently matching an audience filter, with paging. Membership
+   * is recalculated, so results shift as profiles change.
    */
   listMembers(
     audienceID: string,

package/src/resources/audit-events.ts

@@ -6,16 +6,21 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Read the audit trail of configuration and access changes in your workspace.
+ */
 export class AuditEvents extends APIResource {
   /**
-   * Fetch a specific audit event by ID.
+   * Returns one audit event by id, including the actor who performed it, the target
+   * they changed, the source, the event type, and a timestamp.
    */
   retrieve(auditEventID: string, options?: RequestOptions): APIPromise<AuditEvent> {
     return this._client.get(path`/audit-events/${auditEventID}`, options);
   }
 
   /**
-   * Fetch the list of audit events
+   * Returns the workspace's audit event log with cursor paging. Each event records
+   * the actor, target, source, type, and timestamp of a change.
    */
   list(
     query: AuditEventListParams | null | undefined = {},

package/src/resources/auth.ts

@@ -4,9 +4,13 @@ import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Issue scoped, short-lived JWTs so client-side SDKs — Inbox, Preferences, and the embedded designer — can call Courier as a single user. Server-side requests authenticate with your workspace API key instead.
+ */
 export class Auth extends APIResource {
   /**
-   * Returns a new access token.
+   * Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply
+   * the scope and an expires_in duration, both required.
    *
    * @example
    * ```ts

package/src/resources/automations/automations.ts

@@ -6,11 +6,15 @@ import { Invoke, InvokeInvokeAdHocParams, InvokeInvokeByTemplateParams } from '.
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * Invoke a stored automation template or an ad hoc automation defined in the request.
+ */
 export class Automations extends APIResource {
   invoke: InvokeAPI.Invoke = new InvokeAPI.Invoke(this._client);
 
   /**
-   * Get the list of automations.
+   * Lists the workspace's saved automation templates, each with its id and a cursor
+   * for paging to the next page of results.
    *
    * @example
    * ```ts

package/src/resources/automations/invoke.ts

@@ -3,15 +3,17 @@
 import { APIResource } from '../../core/resource';
 import * as AutomationsAPI from './automations';
 import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Invoke a stored automation template or an ad hoc automation defined in the request.
+ */
 export class Invoke extends APIResource {
   /**
-   * Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a
-   * series of automation steps. For information about what steps are available,
-   * checkout the ad hoc automation guide
-   * [here](https://www.courier.com/docs/automations/steps/).
+   * Runs a series of automation steps supplied inline, without a saved template, and
+   * returns a runId.
    *
    * @example
    * ```ts
@@ -34,14 +36,32 @@ export class Invoke extends APIResource {
    * ```
    */
   invokeAdHoc(
-    body: InvokeInvokeAdHocParams,
+    params: InvokeInvokeAdHocParams,
     options?: RequestOptions,
   ): APIPromise<AutomationsAPI.AutomationInvokeResponse> {
-    return this._client.post('/automations/invoke', { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/automations/invoke', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * Invoke an automation run from an automation template.
+   * Starts an automation run from a saved template for one recipient, with optional
+   * data and profile, and returns a runId.
    *
    * @example
    * ```ts
@@ -54,25 +74,78 @@ export class Invoke extends APIResource {
    */
   invokeByTemplate(
     templateID: string,
-    body: InvokeInvokeByTemplateParams,
+    params: InvokeInvokeByTemplateParams,
     options?: RequestOptions,
   ): APIPromise<AutomationsAPI.AutomationInvokeResponse> {
-    return this._client.post(path`/automations/${templateID}/invoke`, { body, ...options });
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post(path`/automations/${templateID}/invoke`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 }
 
 export interface InvokeInvokeAdHocParams {
+  /**
+   * Body param
+   */
   automation: InvokeInvokeAdHocParams.Automation;
 
+  /**
+   * Body param
+   */
   brand?: string | null;
 
+  /**
+   * Body param
+   */
   data?: { [key: string]: unknown } | null;
 
+  /**
+   * Body param
+   */
   profile?: { [key: string]: unknown } | null;
 
+  /**
+   * Body param
+   */
   recipient?: string | null;
 
+  /**
+   * Body param
+   */
   template?: string | null;
+
+  /**
+   * Header param: A unique key that makes this request idempotent. If Courier
+   * receives another request with the same `Idempotency-Key`, it returns the stored
+   * response from the first request without performing the operation again
+   * (including the original status code and any error). Use it to safely retry
+   * `POST` requests after network failures without risking duplicate sends. The key
+   * is scoped to this endpoint.
+   */
+  'Idempotency-Key'?: string;
+
+  /**
+   * Header param: How long the idempotency key remains valid, as a Unix epoch
+   * timestamp in seconds or an ISO 8601 date string. Only applies when
+   * `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+   * maximum is 1 year.
+   */
+  'x-idempotency-expiration'?: string;
 }
 
 export namespace InvokeInvokeAdHocParams {
@@ -168,15 +241,48 @@ export namespace InvokeInvokeAdHocParams {
 }
 
 export interface InvokeInvokeByTemplateParams {
+  /**
+   * Body param
+   */
   recipient: string | null;
 
+  /**
+   * Body param
+   */
   brand?: string | null;
 
+  /**
+   * Body param
+   */
   data?: { [key: string]: unknown } | null;
 
+  /**
+   * Body param
+   */
   profile?: { [key: string]: unknown } | null;
 
+  /**
+   * Body param
+   */
   template?: 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 declare namespace Invoke {

package/src/resources/brands.ts

@@ -8,10 +8,13 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Manage the logos, colors, and layout that give the templates you send a consistent look.
+ */
 export class Brands extends APIResource {
   /**
-   * Create a new brand. Requires `name` and `settings` (with at least
-   * `colors.primary` and `colors.secondary`).
+   * Creates a brand from a name and settings, including primary and secondary
+   * colors. Brands supply the logo, colors, and styling that templates render with.
    *
    * @example
    * ```ts
@@ -23,12 +26,30 @@ export class Brands extends APIResource {
    * });
    * ```
    */
-  create(body: BrandCreateParams, options?: RequestOptions): APIPromise<Brand> {
-    return this._client.post('/brands', { body, ...options });
+  create(params: BrandCreateParams, options?: RequestOptions): APIPromise<Brand> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'x-idempotency-expiration': xIdempotencyExpiration,
+      ...body
+    } = params;
+    return this._client.post('/brands', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xIdempotencyExpiration != null ?
+            { 'x-idempotency-expiration': xIdempotencyExpiration }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * Fetch a specific brand by brand ID.
+   * Returns one brand by id, including its colors, logo and styling settings,
+   * Handlebars snippets, and published version.
    *
    * @example
    * ```ts
@@ -40,7 +61,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Replace an existing brand with the supplied values.
+   * Replaces a brand with the values you supply, so send the complete settings and
+   * snippets rather than only the fields you want changed.
    *
    * @example
    * ```ts
@@ -54,7 +76,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Get the list of brands.
+   * Lists the workspace's brands. Every entry carries its name, styling settings,
+   * snippets, and published version.
    *
    * @example
    * ```ts
@@ -69,7 +92,8 @@ export class Brands extends APIResource {
   }
 
   /**
-   * Delete a brand by brand ID.
+   * Deletes a brand by id. Reassign any template or tenant that references it before
+   * deleting to keep their styling intact.
    *
    * @example
    * ```ts
@@ -225,13 +249,43 @@ export interface BrandListResponse {
 }
 
 export interface BrandCreateParams {
+  /**
+   * Body param
+   */
   name: string;
 
+  /**
+   * Body param
+   */
   settings: BrandSettings;
 
+  /**
+   * Body param
+   */
   id?: string | null;
 
+  /**
+   * Body param
+   */
   snippets?: BrandSnippets | 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 BrandUpdateParams {