@trycourier/courier 7.24.0 → 7.25.1

package/src/resources/bulk.ts

@@ -0,0 +1,249 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as BulkAPI from './bulk';
+import * as Shared from './shared';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Bulk extends APIResource {
+  /**
+   * Ingest user data into a Bulk Job.
+   *
+   * **Important**: For email-based bulk jobs, each user must include `profile.email`
+   * for provider routing to work correctly. The `to.email` field is not sufficient
+   * for email provider routing.
+   *
+   * @example
+   * ```ts
+   * await client.bulk.addUsers('job_id', {
+   *   users: [
+   *     {
+   *       recipient: 'user_abc',
+   *       profile: { email: 'jdoe@example.com' },
+   *       data: { name: 'Jane' },
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  addUsers(jobID: string, body: BulkAddUsersParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/bulk/${jobID}`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Creates a new bulk job for sending messages to multiple recipients.
+   *
+   * **Required**: `message.event` (event ID or notification ID)
+   *
+   * **Optional (V2 format)**: `message.template` (notification ID) or
+   * `message.content` (Elemental content) can be provided to override the
+   * notification associated with the event.
+   *
+   * @example
+   * ```ts
+   * const response = await client.bulk.createJob({
+   *   message: {
+   *     event: 'welcome-series',
+   *     brand: 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag',
+   *     data: { campaign: 'spring-2024' },
+   *   },
+   * });
+   * ```
+   */
+  createJob(body: BulkCreateJobParams, options?: RequestOptions): APIPromise<BulkCreateJobResponse> {
+    return this._client.post('/bulk', { body, ...options });
+  }
+
+  /**
+   * Get Bulk Job Users
+   *
+   * @example
+   * ```ts
+   * const response = await client.bulk.listUsers('job_id');
+   * ```
+   */
+  listUsers(
+    jobID: string,
+    query: BulkListUsersParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BulkListUsersResponse> {
+    return this._client.get(path`/bulk/${jobID}/users`, { query, ...options });
+  }
+
+  /**
+   * Get a bulk job
+   *
+   * @example
+   * ```ts
+   * const response = await client.bulk.retrieveJob('job_id');
+   * ```
+   */
+  retrieveJob(jobID: string, options?: RequestOptions): APIPromise<BulkRetrieveJobResponse> {
+    return this._client.get(path`/bulk/${jobID}`, options);
+  }
+
+  /**
+   * Run a bulk job
+   *
+   * @example
+   * ```ts
+   * await client.bulk.runJob('job_id');
+   * ```
+   */
+  runJob(jobID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/bulk/${jobID}/run`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+/**
+ * Bulk message definition. Supports two formats:
+ *
+ * - V1 format: Requires `event` field (event ID or notification ID)
+ * - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+ *   content) in addition to `event`
+ */
+export interface InboundBulkMessage {
+  /**
+   * Event ID or Notification ID (required). Can be either a Notification ID (e.g.,
+   * "FRH3QXM9E34W4RKP7MRC8NZ1T8V8") or a custom Event ID (e.g., "welcome-email")
+   * mapped to a notification.
+   */
+  event: string;
+
+  brand?: string | null;
+
+  /**
+   * Elemental content (optional, for V2 format). When provided, this will be used
+   * instead of the notification associated with the `event` field.
+   */
+  content?: Shared.ElementalContentSugar | Shared.ElementalContent | null;
+
+  data?: { [key: string]: unknown } | null;
+
+  locale?: { [key: string]: { [key: string]: unknown } } | null;
+
+  override?: { [key: string]: unknown } | null;
+
+  /**
+   * Notification ID or template ID (optional, for V2 format). When provided, this
+   * will be used instead of the notification associated with the `event` field.
+   */
+  template?: string | null;
+}
+
+export interface InboundBulkMessageUser {
+  /**
+   * User-specific data that will be merged with message.data
+   */
+  data?: unknown;
+
+  preferences?: Shared.RecipientPreferences | null;
+
+  /**
+   * User profile information. For email-based bulk jobs, `profile.email` is required
+   * for provider routing to determine if the message can be delivered. The email
+   * address should be provided here rather than in `to.email`.
+   */
+  profile?: { [key: string]: unknown } | null;
+
+  /**
+   * User ID (legacy field, use profile or to.user_id instead)
+   */
+  recipient?: string | null;
+
+  /**
+   * Optional recipient information. Note: For email provider routing, use
+   * `profile.email` instead of `to.email`. The `to` field is primarily used for
+   * recipient identification and data merging.
+   */
+  to?: Shared.UserRecipient | null;
+}
+
+export interface BulkCreateJobResponse {
+  jobId: string;
+}
+
+export interface BulkListUsersResponse {
+  items: Array<BulkListUsersResponse.Item>;
+
+  paging: Shared.Paging;
+}
+
+export namespace BulkListUsersResponse {
+  export interface Item extends BulkAPI.InboundBulkMessageUser {
+    status: 'PENDING' | 'ENQUEUED' | 'ERROR';
+
+    messageId?: string | null;
+  }
+}
+
+export interface BulkRetrieveJobResponse {
+  job: BulkRetrieveJobResponse.Job;
+}
+
+export namespace BulkRetrieveJobResponse {
+  export interface Job {
+    /**
+     * Bulk message definition. Supports two formats:
+     *
+     * - V1 format: Requires `event` field (event ID or notification ID)
+     * - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+     *   content) in addition to `event`
+     */
+    definition: BulkAPI.InboundBulkMessage;
+
+    enqueued: number;
+
+    failures: number;
+
+    received: number;
+
+    status: 'CREATED' | 'PROCESSING' | 'COMPLETED' | 'ERROR';
+  }
+}
+
+export interface BulkAddUsersParams {
+  users: Array<InboundBulkMessageUser>;
+}
+
+export interface BulkCreateJobParams {
+  /**
+   * Bulk message definition. Supports two formats:
+   *
+   * - V1 format: Requires `event` field (event ID or notification ID)
+   * - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+   *   content) in addition to `event`
+   */
+  message: InboundBulkMessage;
+}
+
+export interface BulkListUsersParams {
+  /**
+   * A unique identifier that allows for fetching the next set of users added to the
+   * bulk job
+   */
+  cursor?: string | null;
+}
+
+export declare namespace Bulk {
+  export {
+    type InboundBulkMessage as InboundBulkMessage,
+    type InboundBulkMessageUser as InboundBulkMessageUser,
+    type BulkCreateJobResponse as BulkCreateJobResponse,
+    type BulkListUsersResponse as BulkListUsersResponse,
+    type BulkRetrieveJobResponse as BulkRetrieveJobResponse,
+    type BulkAddUsersParams as BulkAddUsersParams,
+    type BulkCreateJobParams as BulkCreateJobParams,
+    type BulkListUsersParams as BulkListUsersParams,
+  };
+}

package/src/resources/index.ts

@@ -63,6 +63,17 @@ export {
   type BroadcastScheduleParams,
   type BroadcastSendParams,
 } from './broadcasts';
+export {
+  Bulk,
+  type InboundBulkMessage,
+  type InboundBulkMessageUser,
+  type BulkCreateJobResponse,
+  type BulkListUsersResponse,
+  type BulkRetrieveJobResponse,
+  type BulkAddUsersParams,
+  type BulkCreateJobParams,
+  type BulkListUsersParams,
+} from './bulk';
 export {
   Digests,
   type DigestCategory,
@@ -148,6 +159,7 @@ export {
   type NotificationElementPutRequest,
   type NotificationGetContent,
   type NotificationLocalePutRequest,
+  type NotificationTemplateAlias,
   type NotificationTemplateCreateRequest,
   type NotificationTemplatePayload,
   type NotificationTemplatePublishRequest,
@@ -156,6 +168,7 @@ export {
   type NotificationTemplateSummary,
   type NotificationTemplateUpdateRequest,
   type NotificationTemplateVersionListResponse,
+  type NotificationTemplateWritePayload,
   type VersionNode,
   type NotificationListResponse,
   type NotificationRetrieveContentResponse,

package/src/resources/lists/lists.ts

@@ -44,7 +44,9 @@ export class Lists extends APIResource {
    *
    * @example
    * ```ts
-   * await client.lists.update('list_id', { name: 'name' });
+   * await client.lists.update('list_id', {
+   *   name: 'Product Updates',
+   * });
    * ```
    */
   update(listID: string, body: ListUpdateParams, options?: RequestOptions): APIPromise<void> {

package/src/resources/lists/subscriptions.ts

@@ -38,7 +38,10 @@ export class Subscriptions extends APIResource {
    * @example
    * ```ts
    * await client.lists.subscriptions.add('list_id', {
-   *   recipients: [{ recipientId: 'recipientId' }],
+   *   recipients: [
+   *     { recipientId: 'user_abc' },
+   *     { recipientId: 'user_def' },
+   *   ],
    * });
    * ```
    */
@@ -71,7 +74,10 @@ export class Subscriptions extends APIResource {
    * @example
    * ```ts
    * await client.lists.subscriptions.subscribe('list_id', {
-   *   recipients: [{ recipientId: 'recipientId' }],
+   *   recipients: [
+   *     { recipientId: 'user_abc' },
+   *     { recipientId: 'user_def' },
+   *   ],
    * });
    * ```
    */
@@ -91,6 +97,11 @@ export class Subscriptions extends APIResource {
    * ```ts
    * await client.lists.subscriptions.subscribeUser('user_id', {
    *   list_id: 'list_id',
+   *   preferences: {
+   *     notifications: {
+   *       nt_01kx4h2jdafq8bk9aftxak4b40: { status: 'OPTED_IN' },
+   *     },
+   *   },
    * });
    * ```
    */

package/src/resources/notifications/checks.ts

@@ -23,9 +23,9 @@ export class Checks extends APIResource {
    *     id: 'id',
    *     checks: [
    *       {
-   *         id: 'id',
-   *         status: 'RESOLVED',
+   *         id: 'abc-123',
    *         type: 'custom',
+   *         status: 'RESOLVED',
    *       },
    *     ],
    *   },

package/src/resources/notifications/index.ts

@@ -19,6 +19,7 @@ export {
   type NotificationElementPutRequest,
   type NotificationGetContent,
   type NotificationLocalePutRequest,
+  type NotificationTemplateAlias,
   type NotificationTemplateCreateRequest,
   type NotificationTemplatePayload,
   type NotificationTemplatePublishRequest,
@@ -27,6 +28,7 @@ export {
   type NotificationTemplateSummary,
   type NotificationTemplateUpdateRequest,
   type NotificationTemplateVersionListResponse,
+  type NotificationTemplateWritePayload,
   type VersionNode,
   type NotificationListResponse,
   type NotificationRetrieveContentResponse,

package/src/resources/notifications/notifications.ts

@@ -44,6 +44,7 @@ export class Notifications extends APIResource {
    *         version: '2022-01-01',
    *         elements: [{ type: 'channel' }],
    *       },
+   *       alias: 'welcome',
    *     },
    *     state: 'DRAFT',
    *   });
@@ -560,15 +561,24 @@ export namespace NotificationLocalePutRequest {
   }
 }
 
+/**
+ * A template's send-time alias as returned by a read, omitted entirely when it has
+ * none. Usually a single string; an array for a template that resolves from
+ * several aliases, which writes through this API can no longer produce — only
+ * templates predating that restriction, or aliases attached outside this API, hold
+ * more than one.
+ */
+export type NotificationTemplateAlias = string | Array<string>;
+
 /**
  * Request body for creating a notification template.
  */
 export interface NotificationTemplateCreateRequest {
   /**
-   * Core template fields used in POST and PUT request bodies (nested under a
-   * `notification` key) and returned at the top level in responses.
+   * Template fields accepted in POST and PUT request bodies, nested under a
+   * `notification` key.
    */
-  notification: NotificationTemplatePayload;
+  notification: NotificationTemplateWritePayload;
 
   /**
    * Template state after creation. Case-insensitive input, normalized to uppercase
@@ -672,6 +682,15 @@ export interface NotificationTemplateResponse extends NotificationTemplatePayloa
    */
   state: 'DRAFT' | 'PUBLISHED';
 
+  /**
+   * A template's send-time alias as returned by a read, omitted entirely when it has
+   * none. Usually a single string; an array for a template that resolves from
+   * several aliases, which writes through this API can no longer produce — only
+   * templates predating that restriction, or aliases attached outside this API, hold
+   * more than one.
+   */
+  alias?: NotificationTemplateAlias;
+
   /**
    * Epoch milliseconds of last update.
    */
@@ -735,14 +754,15 @@ export interface NotificationTemplateSummary {
 
 /**
  * Request body for replacing a notification template. Same shape as create. All
- * fields required (PUT = full replacement).
+ * fields required (PUT = full replacement), except `alias`, whose omission means
+ * "leave the existing aliases alone".
  */
 export interface NotificationTemplateUpdateRequest {
   /**
-   * Core template fields used in POST and PUT request bodies (nested under a
-   * `notification` key) and returned at the top level in responses.
+   * Template fields accepted in POST and PUT request bodies, nested under a
+   * `notification` key.
    */
-  notification: NotificationTemplatePayload;
+  notification: NotificationTemplateWritePayload;
 
   /**
    * Template state after update. Case-insensitive input, normalized to uppercase in
@@ -757,6 +777,23 @@ export interface NotificationTemplateVersionListResponse {
   versions: Array<VersionNode>;
 }
 
+/**
+ * Template fields accepted in POST and PUT request bodies, nested under a
+ * `notification` key.
+ */
+export interface NotificationTemplateWritePayload extends NotificationTemplatePayload {
+  /**
+   * Send-time alias for this template — the value you pass as `event` to POST /send.
+   * Writes accept a single alias only. Optional, with three distinct meanings. Omit
+   * it to leave any existing aliases untouched. Send a string to make this the
+   * template's only alias — a template that already resolved from several aliases
+   * keeps just this one and the rest are detached. Send null to remove every alias
+   * from the template. An alias may not be claimed by another template — doing so
+   * returns 409 — and may not begin with "tenant/".
+   */
+  alias?: string | null;
+}
+
 /**
  * A version entry for a notification template.
  */
@@ -839,10 +876,10 @@ export type NotificationRetrieveContentResponse = NotificationContentGetResponse
 
 export interface NotificationCreateParams {
   /**
-   * 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.
+   * Body param: Template fields accepted in POST and PUT request bodies, nested
+   * under a `notification` key.
    */
-  notification: NotificationTemplatePayload;
+  notification: NotificationTemplateWritePayload;
 
   /**
    * Body param: Template state after creation. Case-insensitive input, normalized to
@@ -1033,10 +1070,10 @@ export namespace NotificationPutLocaleParams {
 
 export interface NotificationReplaceParams {
   /**
-   * Core template fields used in POST and PUT request bodies (nested under a
-   * `notification` key) and returned at the top level in responses.
+   * Template fields accepted in POST and PUT request bodies, nested under a
+   * `notification` key.
    */
-  notification: NotificationTemplatePayload;
+  notification: NotificationTemplateWritePayload;
 
   /**
    * Template state after update. Case-insensitive input, normalized to uppercase in
@@ -1066,6 +1103,7 @@ export declare namespace Notifications {
     type NotificationElementPutRequest as NotificationElementPutRequest,
     type NotificationGetContent as NotificationGetContent,
     type NotificationLocalePutRequest as NotificationLocalePutRequest,
+    type NotificationTemplateAlias as NotificationTemplateAlias,
     type NotificationTemplateCreateRequest as NotificationTemplateCreateRequest,
     type NotificationTemplatePayload as NotificationTemplatePayload,
     type NotificationTemplatePublishRequest as NotificationTemplatePublishRequest,
@@ -1074,6 +1112,7 @@ export declare namespace Notifications {
     type NotificationTemplateSummary as NotificationTemplateSummary,
     type NotificationTemplateUpdateRequest as NotificationTemplateUpdateRequest,
     type NotificationTemplateVersionListResponse as NotificationTemplateVersionListResponse,
+    type NotificationTemplateWritePayload as NotificationTemplateWritePayload,
     type VersionNode as VersionNode,
     type NotificationListResponse as NotificationListResponse,
     type NotificationRetrieveContentResponse as NotificationRetrieveContentResponse,

package/src/resources/profiles/lists.ts

@@ -52,7 +52,7 @@ export class Lists extends APIResource {
    * ```ts
    * const response = await client.profiles.lists.subscribe(
    *   'user_id',
-   *   { lists: [{ listId: 'listId' }] },
+   *   { lists: [{ listId: 'example.list.id' }] },
    * );
    * ```
    */

package/src/resources/profiles/profiles.ts

@@ -29,7 +29,10 @@ export class Profiles extends APIResource {
    * @example
    * ```ts
    * const profile = await client.profiles.create('user_id', {
-   *   profile: { foo: 'bar' },
+   *   profile: {
+   *     email: 'jdoe@example.com',
+   *     phone_number: '+15558675309',
+   *   },
    * });
    * ```
    */
@@ -80,9 +83,9 @@ export class Profiles extends APIResource {
    * await client.profiles.update('user_id', {
    *   patch: [
    *     {
-   *       op: 'op',
-   *       path: 'path',
-   *       value: 'value',
+   *       op: 'replace',
+   *       path: '/email',
+   *       value: 'jdoe@example.com',
    *     },
    *   ],
    * });
@@ -119,7 +122,11 @@ export class Profiles extends APIResource {
    * @example
    * ```ts
    * const response = await client.profiles.replace('user_id', {
-   *   profile: { foo: 'bar' },
+   *   profile: {
+   *     email: 'jdoe@example.com',
+   *     phone_number: '+15558675309',
+   *     locale: 'en-US',
+   *   },
    * });
    * ```
    */

package/src/resources/providers/providers.ts

@@ -22,7 +22,9 @@ export class Providers extends APIResource {
    * @example
    * ```ts
    * const provider = await client.providers.create({
-   *   provider: 'provider',
+   *   provider: 'sendgrid',
+   *   settings: { api_key: 'SG.xxxxxxxx' },
+   *   title: 'Production SendGrid',
    * });
    * ```
    */
@@ -67,7 +69,9 @@ export class Providers extends APIResource {
    * @example
    * ```ts
    * const provider = await client.providers.update('id', {
-   *   provider: 'provider',
+   *   provider: 'sendgrid',
+   *   settings: { api_key: 'SG.xxxxxxxx' },
+   *   title: 'Production SendGrid',
    * });
    * ```
    */

package/src/resources/send.ts

@@ -12,7 +12,8 @@ import { RequestOptions } from '../internal/request-options';
 export class Send extends APIResource {
   /**
    * Sends a message to one or more recipients and returns a requestId. Courier
-   * routes it to email, SMS, push, chat, or in-app based on your rules.
+   * routes it to email, SMS, push, chat, or in-app based on your rules. Use the
+   * returned requestId to look up delivery status via the Messages API.
    *
    * @example
    * ```ts

package/src/resources/shared.ts

@@ -135,6 +135,25 @@ export interface ElementalChannelNode extends ElementalBaseNode {
    */
   channel?: string;
 
+  /**
+   * Email only. Document-level base font size (CSS px, e.g. `16px`) for body content
+   * — text, quote, list and action button labels. Heading styles (`h1`/`h2`/`h3`)
+   * and `subtext` keep their preset sizes.
+   */
+  font_size?: string | null;
+
+  /**
+   * Email only. Document-level line height (CSS px or unitless multiplier, e.g.
+   * `24px` or `1.5`) applied to all body content unless overridden per block.
+   */
+  line_height?: string | null;
+
+  /**
+   * Email only. Document-level body padding applied once around the email body, as a
+   * CSS px shorthand (1–4 values), e.g. `48px 64px`.
+   */
+  padding?: string | null;
+
   /**
    * Raw data to apply to the channel. If `elements` has not been specified, `raw` is
    * required.

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

@@ -84,6 +84,7 @@ export class Templates extends APIResource {
    * const postTenantTemplatePublishResponse =
    *   await client.tenants.templates.publish('template_id', {
    *     tenant_id: 'tenant_id',
+   *     version: 'latest',
    *   });
    * ```
    */
@@ -109,8 +110,13 @@ export class Templates extends APIResource {
    *   await client.tenants.templates.replace('template_id', {
    *     tenant_id: 'tenant_id',
    *     template: {
-   *       content: { elements: [{}], version: 'version' },
+   *       content: {
+   *         version: '2022-01-01',
+   *         elements: [{ type: 'text' }],
+   *       },
+   *       routing: { method: 'single', channels: ['email'] },
    *     },
+   *     published: true,
    *   });
    * ```
    */

package/src/resources/tenants/tenants.ts

@@ -47,7 +47,9 @@ export class Tenants extends APIResource {
    * @example
    * ```ts
    * const tenant = await client.tenants.update('tenant_id', {
-   *   name: 'name',
+   *   name: 'Acme Corp',
+   *   brand_id: 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag',
+   *   properties: { plan: 'enterprise' },
    * });
    * ```
    */

package/src/resources/translations.ts

@@ -13,6 +13,14 @@ export class Translations extends APIResource {
   /**
    * Returns the translation strings stored for one domain and locale, for use in
    * localized notification content.
+   *
+   * @example
+   * ```ts
+   * const translation = await client.translations.retrieve(
+   *   'locale',
+   *   { domain: 'domain' },
+   * );
+   * ```
    */
   retrieve(locale: string, params: TranslationRetrieveParams, options?: RequestOptions): APIPromise<string> {
     const { domain } = params;
@@ -22,6 +30,14 @@ export class Translations extends APIResource {
   /**
    * Uploads the translation strings for one domain and locale. Courier uses them to
    * render localized content for recipients in that locale.
+   *
+   * @example
+   * ```ts
+   * await client.translations.update('locale', {
+   *   domain: 'domain',
+   *   body: 'msgid "Hello"\nmsgstr "Hola"',
+   * });
+   * ```
    */
   update(locale: string, params: TranslationUpdateParams, options?: RequestOptions): APIPromise<void> {
     const { domain, body } = params;