@trycourier/courier 7.3.0 → 7.8.0

package/src/resources/bulk.ts

@@ -10,7 +10,11 @@ import { path } from '../internal/utils/path';
 
 export class Bulk extends APIResource {
   /**
-   * Ingest user data into a Bulk Job
+   * 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.
    */
   addUsers(jobID: string, body: BulkAddUsersParams, options?: RequestOptions): APIPromise<void> {
     return this._client.post(path`/bulk/${jobID}`, {
@@ -21,7 +25,13 @@ export class Bulk extends APIResource {
   }
 
   /**
-   * Create a bulk job
+   * 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.
    */
   createJob(body: BulkCreateJobParams, options?: RequestOptions): APIPromise<BulkCreateJobResponse> {
     return this._client.post('/bulk', { body, ...options });
@@ -56,52 +66,67 @@ export class Bulk extends APIResource {
   }
 }
 
-export type InboundBulkMessage =
-  | InboundBulkMessage.InboundBulkTemplateMessage
-  | InboundBulkMessage.InboundBulkContentMessage;
-
-export namespace InboundBulkMessage {
-  export interface InboundBulkTemplateMessage {
-    template: string;
-
-    brand?: string | null;
-
-    data?: { [key: string]: unknown } | null;
-
-    event?: string | null;
-
-    locale?: { [key: string]: { [key: string]: unknown } } | null;
-
-    override?: { [key: string]: unknown } | null;
-  }
+/**
+ * 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;
 
-  export interface InboundBulkContentMessage {
-    /**
-     * Syntactic sugar to provide a fast shorthand for Courier Elemental Blocks.
-     */
-    content: Shared.ElementalContentSugar | Shared.ElementalContent;
+  brand?: string | null;
 
-    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;
+  data?: { [key: string]: unknown } | null;
 
-    event?: string | null;
+  locale?: { [key: string]: { [key: string]: unknown } } | null;
 
-    locale?: { [key: string]: { [key: string]: unknown } } | null;
+  override?: { [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;
 
-  profile?: unknown;
+  /**
+   * 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;
 }
 
@@ -129,6 +154,13 @@ export interface BulkRetrieveJobResponse {
 
 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;
@@ -146,6 +178,13 @@ export interface BulkAddUsersParams {
 }
 
 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;
 }
 

package/src/resources/inbound.ts

@@ -54,7 +54,7 @@ export interface InboundTrackEventParams {
   type: 'track';
 
   /**
-   * The user id associatiated with the track
+   * The user id associated with the track
    */
   userId?: string | null;
 }

package/src/resources/index.ts

@@ -4,8 +4,6 @@ export * from './shared';
 export {
   Audiences,
   type Audience,
-  type Filter,
-  type FilterConfig,
   type AudienceUpdateResponse,
   type AudienceListResponse,
   type AudienceListMembersResponse,
@@ -20,7 +18,13 @@ export {
   type AuditEventListParams,
 } from './audit-events';
 export { Auth, type AuthIssueTokenResponse, type AuthIssueTokenParams } from './auth';
-export { Automations, type AutomationInvokeResponse } from './automations/automations';
+export {
+  Automations,
+  type AutomationInvokeResponse,
+  type AutomationTemplate,
+  type AutomationTemplateListResponse,
+  type AutomationListParams,
+} from './automations/automations';
 export {
   Brands,
   type Brand,
@@ -54,6 +58,15 @@ export {
   type BulkListUsersParams,
 } from './bulk';
 export { Inbound, type InboundTrackEventResponse, type InboundTrackEventParams } from './inbound';
+export {
+  Journeys,
+  type Journey,
+  type JourneysInvokeRequest,
+  type JourneysInvokeResponse,
+  type JourneysListResponse,
+  type JourneyListParams,
+  type JourneyInvokeParams,
+} from './journeys';
 export {
   Lists,
   type PutSubscriptionsRecipient,
@@ -97,9 +110,14 @@ export {
   Tenants,
   type BaseTemplateTenantAssociation,
   type DefaultPreferences,
+  type PostTenantTemplatePublishRequest,
+  type PostTenantTemplatePublishResponse,
+  type PutTenantTemplateRequest,
+  type PutTenantTemplateResponse,
   type SubscriptionTopicNew,
   type Tenant,
   type TenantAssociation,
+  type TenantTemplateInput,
   type TenantListResponse,
   type TenantListUsersResponse,
   type TenantUpdateParams,

package/src/resources/journeys.ts

@@ -0,0 +1,174 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Journeys extends APIResource {
+  /**
+   * Get the list of journeys.
+   *
+   * @example
+   * ```ts
+   * const journeysListResponse = await client.journeys.list();
+   * ```
+   */
+  list(
+    query: JourneyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<JourneysListResponse> {
+    return this._client.get('/journeys', { query, ...options });
+  }
+
+  /**
+   * Invoke a journey run from a journey template.
+   *
+   * @example
+   * ```ts
+   * const journeysInvokeResponse = await client.journeys.invoke(
+   *   'templateId',
+   *   {
+   *     data: { order_id: 'order-456', amount: 99.99 },
+   *     user_id: 'user-123',
+   *   },
+   * );
+   * ```
+   */
+  invoke(
+    templateID: string,
+    body: JourneyInvokeParams,
+    options?: RequestOptions,
+  ): APIPromise<JourneysInvokeResponse> {
+    return this._client.post(path`/journeys/${templateID}/invoke`, { body, ...options });
+  }
+}
+
+/**
+ * A journey template representing an automation workflow.
+ */
+export interface Journey {
+  /**
+   * The unique identifier of the journey.
+   */
+  id: string;
+
+  /**
+   * The name of the journey.
+   */
+  name: string;
+
+  /**
+   * The version of the journey (published or draft).
+   */
+  version: 'published' | 'draft';
+
+  /**
+   * ISO 8601 timestamp when the journey was created.
+   */
+  createdAt?: string;
+
+  /**
+   * ISO 8601 timestamp when the journey was last updated.
+   */
+  updatedAt?: string;
+}
+
+/**
+ * Request body for invoking a journey. Requires either a user identifier or a
+ * profile with contact information. User identifiers can be provided via user_id
+ * field, or resolved from profile/data objects (user_id, userId, or anonymousId
+ * fields).
+ */
+export interface JourneysInvokeRequest {
+  /**
+   * Data payload passed to the journey. The expected shape can be predefined using
+   * the schema builder in the journey editor. This data is available in journey
+   * steps for condition evaluation and template variable interpolation. Can also
+   * contain user identifiers (user_id, userId, anonymousId) if not provided
+   * elsewhere.
+   */
+  data?: { [key: string]: unknown };
+
+  /**
+   * Profile data for the user. Can contain contact information (email,
+   * phone_number), user identifiers (user_id, userId, anonymousId), or any custom
+   * profile fields. Profile fields are merged with any existing stored profile for
+   * the user. Include context.tenant_id to load a tenant-scoped profile for
+   * multi-tenant scenarios.
+   */
+  profile?: { [key: string]: unknown };
+
+  /**
+   * A unique identifier for the user. If not provided, the system will attempt to
+   * resolve the user identifier from profile or data objects.
+   */
+  user_id?: string;
+}
+
+export interface JourneysInvokeResponse {
+  /**
+   * A unique identifier for the journey run that was created.
+   */
+  runId: string;
+}
+
+export interface JourneysListResponse {
+  /**
+   * A cursor token for pagination. Present when there are more results available.
+   */
+  cursor?: string;
+
+  templates?: Array<Journey>;
+}
+
+export interface JourneyListParams {
+  /**
+   * A cursor token for pagination. Use the cursor from the previous response to
+   * fetch the next page of results.
+   */
+  cursor?: string;
+
+  /**
+   * The version of journeys to retrieve. Accepted values are published (for
+   * published journeys) or draft (for draft journeys). Defaults to published.
+   */
+  version?: 'published' | 'draft';
+}
+
+export interface JourneyInvokeParams {
+  /**
+   * Data payload passed to the journey. The expected shape can be predefined using
+   * the schema builder in the journey editor. This data is available in journey
+   * steps for condition evaluation and template variable interpolation. Can also
+   * contain user identifiers (user_id, userId, anonymousId) if not provided
+   * elsewhere.
+   */
+  data?: { [key: string]: unknown };
+
+  /**
+   * Profile data for the user. Can contain contact information (email,
+   * phone_number), user identifiers (user_id, userId, anonymousId), or any custom
+   * profile fields. Profile fields are merged with any existing stored profile for
+   * the user. Include context.tenant_id to load a tenant-scoped profile for
+   * multi-tenant scenarios.
+   */
+  profile?: { [key: string]: unknown };
+
+  /**
+   * A unique identifier for the user. If not provided, the system will attempt to
+   * resolve the user identifier from profile or data objects.
+   */
+  user_id?: string;
+}
+
+export declare namespace Journeys {
+  export {
+    type Journey as Journey,
+    type JourneysInvokeRequest as JourneysInvokeRequest,
+    type JourneysInvokeResponse as JourneysInvokeResponse,
+    type JourneysListResponse as JourneysListResponse,
+    type JourneyListParams as JourneyListParams,
+    type JourneyInvokeParams as JourneyInvokeParams,
+  };
+}

package/src/resources/lists/subscriptions.ts

@@ -115,7 +115,7 @@ export interface SubscriptionSubscribeUserParams {
   list_id: string;
 
   /**
-   * Body param:
+   * Body param
    */
   preferences?: Shared.RecipientPreferences | null;
 }

package/src/resources/messages.ts

@@ -61,18 +61,6 @@ export interface MessageDetails {
    */
   id: string;
 
-  /**
-   * A UTC timestamp at which the recipient clicked on a tracked link for the first
-   * time. Stored as a millisecond representation of the Unix epoch.
-   */
-  clicked: number;
-
-  /**
-   * A UTC timestamp at which the Integration provider delivered the message. Stored
-   * as a millisecond representation of the Unix epoch.
-   */
-  delivered: number;
-
   /**
    * A UTC timestamp at which Courier received the message request. Stored as a
    * millisecond representation of the Unix epoch.
@@ -89,23 +77,11 @@ export interface MessageDetails {
    */
   notification: string;
 
-  /**
-   * A UTC timestamp at which the recipient opened a message for the first time.
-   * Stored as a millisecond representation of the Unix epoch.
-   */
-  opened: number;
-
   /**
    * A unique identifier associated with the recipient of the delivered message.
    */
   recipient: string;
 
-  /**
-   * A UTC timestamp at which Courier passed the message to the Integration provider.
-   * Stored as a millisecond representation of the Unix epoch.
-   */
-  sent: number;
-
   /**
    * The current status of the message.
    */
@@ -126,11 +102,29 @@ export interface MessageDetails {
     | 'UNMAPPED'
     | 'UNROUTABLE';
 
+  /**
+   * A UTC timestamp at which the recipient clicked on a tracked link for the first
+   * time. Stored as a millisecond representation of the Unix epoch.
+   */
+  clicked?: number;
+
+  /**
+   * A UTC timestamp at which the Integration provider delivered the message. Stored
+   * as a millisecond representation of the Unix epoch.
+   */
+  delivered?: number;
+
   /**
    * A message describing the error that occurred.
    */
   error?: string | null;
 
+  /**
+   * A UTC timestamp at which the recipient opened a message for the first time.
+   * Stored as a millisecond representation of the Unix epoch.
+   */
+  opened?: number;
+
   /**
    * The reason for the current status of the message.
    */
@@ -145,6 +139,12 @@ export interface MessageDetails {
     | 'UNPUBLISHED'
     | 'UNSUBSCRIBED'
     | null;
+
+  /**
+   * A UTC timestamp at which Courier passed the message to the Integration provider.
+   * Stored as a millisecond representation of the Unix epoch.
+   */
+  sent?: number;
 }
 
 export interface MessageRetrieveResponse extends MessageDetails {

package/src/resources/notifications/checks.ts

@@ -45,12 +45,12 @@ export interface CheckListResponse {
 
 export interface CheckUpdateParams {
   /**
-   * Path param:
+   * Path param
    */
   id: string;
 
   /**
-   * Body param:
+   * Body param
    */
   checks: Array<NotificationsAPI.BaseCheck>;
 }

package/src/resources/send.ts

@@ -13,7 +13,7 @@ export class Send extends APIResource {
    * ```ts
    * const response = await client.send.message({
    *   message: {
-   *     to: { user_id: 'example_user' },
+   *     to: { user_id: 'user_id' },
    *     template: 'template_id',
    *     data: { foo: 'bar' },
    *   },
@@ -89,7 +89,26 @@ export namespace SendMessageParams {
     /**
      * The recipient or a list of recipients of the message
      */
-    to?: Shared.UserRecipient | Array<Shared.Recipient> | null;
+    to?:
+      | Shared.UserRecipient
+      | Shared.AudienceRecipient
+      | Shared.ListRecipient
+      | Shared.ListPatternRecipient
+      | Shared.SlackRecipient
+      | Shared.MsTeamsRecipient
+      | Shared.PagerdutyRecipient
+      | Shared.WebhookRecipient
+      | Array<
+          | Shared.UserRecipient
+          | Shared.AudienceRecipient
+          | Shared.ListRecipient
+          | Shared.ListPatternRecipient
+          | Shared.SlackRecipient
+          | Shared.MsTeamsRecipient
+          | Shared.PagerdutyRecipient
+          | Shared.WebhookRecipient
+        >
+      | null;
   }
 
   export namespace Message {
@@ -142,6 +161,13 @@ export namespace SendMessageParams {
        */
       duration?: number | null;
 
+      /**
+       * IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Used when
+       * resolving opening hours expressions. Takes precedence over user profile timezone
+       * settings.
+       */
+      timezone?: string | null;
+
       /**
        * ISO 8601 timestamp or opening_hours-like format.
        */