@trycourier/courier 9.0.0 → 9.2.0

package/src/resources/journeys/journeys.ts

@@ -3,6 +3,8 @@
 import { APIResource } from '../../core/resource';
 import * as JourneysAPI from './journeys';
 import * as Shared from '../shared';
+import * as RunsAPI from './runs';
+import { RunListParams, Runs } from './runs';
 import * as TemplatesAPI from './templates';
 import {
   TemplateArchiveParams,
@@ -27,6 +29,7 @@ import { path } from '../../internal/utils/path';
  */
 export class Journeys extends APIResource {
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
+  runs: RunsAPI.Runs = new RunsAPI.Runs(this._client);
 
   /**
    * Creates a journey from a set of nodes, in draft state unless you pass a
@@ -409,6 +412,34 @@ export interface JourneyAPIInvokeTriggerNode {
   schema?: { [key: string]: unknown };
 }
 
+/**
+ * Trigger fired when a user newly matches an Audience. Leaving and re-joining the
+ * Audience re-enters the Journey. Membership is new-members-only: users already in
+ * the Audience when the Journey is published do not enter. Unlike the v2
+ * Automations audience trigger, there is no member scope, event type, or frequency
+ * mode to configure, and `audience_id` must name one Audience — wildcards are not
+ * supported.
+ */
+export interface JourneyAudienceTriggerNode {
+  /**
+   * The Audience to watch. Must name a single Audience; wildcards are not supported.
+   */
+  audience_id: string;
+
+  trigger_type: 'audience';
+
+  type: 'trigger';
+
+  id?: string;
+
+  /**
+   * Condition spec for a journey node. Accepts a single condition atom, an AND/OR
+   * group, or an AND/OR nested group. Omit the `conditions` property entirely to
+   * express "no conditions".
+   */
+  conditions?: JourneyConditionsField;
+}
+
 /**
  * A single condition expressed as a positional tuple of strings.
  *
@@ -650,6 +681,8 @@ export type JourneyMergeStrategy = 'overwrite' | 'soft-merge' | 'replace' | 'non
 export type JourneyNode =
   | JourneyAPIInvokeTriggerNode
   | JourneySegmentTriggerNode
+  | JourneyAudienceTriggerNode
+  | JourneyWebhookTriggerNode
   | JourneySendNode
   | JourneyDelayDurationNode
   | JourneyDelayUntilNode
@@ -829,10 +862,157 @@ export interface JourneyResponse {
 }
 
 /**
- * Trigger fired by a segment event (`identify`, `group`, or `track`).
+ * One run of a Journey. `status` and `created_at` are absent on a small number of
+ * legacy runs stored without them.
+ */
+export interface JourneyRun {
+  /**
+   * A unique identifier representing the run.
+   */
+  run_id: string;
+
+  /**
+   * Internal provenance strings describing what started the run, e.g.
+   * `invoke/<journey_id>` or `segment/page/Pricing Page`. Diagnostic only — the
+   * format is unstable and should not be parsed.
+   */
+  source: Array<string>;
+
+  /**
+   * When the run started, as an ISO 8601 timestamp.
+   */
+  created_at?: string;
+
+  /**
+   * The state of the run: `PROCESSING`, `PROCESSED`, `WAITING`, `CANCELED`, `ERROR`,
+   * `THROTTLED`, or `NOT PROCESSED`. Not an enum — new values have been added
+   * before.
+   */
+  status?: string;
+
+  /**
+   * The id of the Journey this run belongs to.
+   */
+  template_id?: string;
+
+  /**
+   * When the run last changed state, as an ISO 8601 timestamp.
+   */
+  updated_at?: string;
+}
+
+/**
+ * A Journey run as it appears in a list response, without `updated_at`.
+ */
+export interface JourneyRunListItem {
+  /**
+   * A unique identifier representing the run.
+   */
+  run_id: string;
+
+  /**
+   * Internal provenance strings describing what started the run. Diagnostic only.
+   */
+  source: Array<string>;
+
+  /**
+   * When the run started, as an ISO 8601 timestamp.
+   */
+  created_at?: string;
+
+  /**
+   * The state of the run. See `JourneyRun.status` for the values it takes.
+   */
+  status?: string;
+
+  /**
+   * The id of the Journey this run belongs to.
+   */
+  template_id?: string;
+}
+
+/**
+ * A page of Journey runs.
+ */
+export interface JourneyRunListResponse {
+  runs: Array<JourneyRunListItem>;
+
+  /**
+   * Pass back as `cursor` to fetch the next page. Absent on the last page.
+   */
+  next_cursor?: string;
+
+  /**
+   * Pass back as `cursor` to fetch the previous page. Absent on the first page.
+   */
+  prev_cursor?: string;
+}
+
+/**
+ * A single Journey run.
+ */
+export interface JourneyRunResponse {
+  /**
+   * One run of a Journey. `status` and `created_at` are absent on a small number of
+   * legacy runs stored without them.
+   */
+  run: JourneyRun;
+}
+
+/**
+ * One executed node of a Journey run. `node_id` is the id of the node in the
+ * published Journey, so a step maps directly onto the Journey graph.
+ */
+export interface JourneyRunStep {
+  /**
+   * The kind of node that ran, e.g. `send`, `delay`, or `exit`.
+   */
+  action: string;
+
+  /**
+   * The state of the step: the seven run statuses, plus `SKIPPED` and `COMPUTING`.
+   * Not an enum — new values have been added before.
+   */
+  status: string;
+
+  /**
+   * When the step started, as an ISO 8601 timestamp.
+   */
+  created_at?: string;
+
+  /**
+   * The message this step produced, present on send steps. Pass it to
+   * `GET /messages/{message_id}` for delivery status. A send to a List or an
+   * Audience yields one id for the request, not one per recipient.
+   */
+  message_id?: string;
+
+  /**
+   * The id of the node in the published Journey that this step executed.
+   */
+  node_id?: string;
+
+  /**
+   * When the step last changed state, as an ISO 8601 timestamp.
+   */
+  updated_at?: string;
+}
+
+/**
+ * Every step of a Journey run. Not paginated.
+ */
+export interface JourneyRunStepsResponse {
+  steps: Array<JourneyRunStep>;
+}
+
+/**
+ * Trigger fired by a segment event (`identify`, `group`, `track`, or `page`). A
+ * trigger with no `event_id` fires on any event of its type — the only shape
+ * `identify` and `group` can take, and the one that catches a stock
+ * `analytics.page()` call.
  */
 export interface JourneySegmentTriggerNode {
-  request_type: 'identify' | 'group' | 'track';
+  request_type: 'identify' | 'group' | 'track' | 'page';
 
   trigger_type: 'segment';
 
@@ -1181,6 +1361,39 @@ export interface JourneyVersionsListResponse {
   results: Array<JourneyVersionItem>;
 }
 
+/**
+ * Trigger fired when an external system POSTs to the webhook URL minted for
+ * `event_source`. Narrow it to one event with `event_id`, or omit `event_id` to
+ * accept every event delivered to the URL.
+ */
+export interface JourneyWebhookTriggerNode {
+  /**
+   * The provider key the webhook URL is minted for. Required, and must not contain a
+   * forward slash.
+   */
+  event_source: string;
+
+  trigger_type: 'webhook';
+
+  type: 'trigger';
+
+  id?: string;
+
+  /**
+   * Condition spec for a journey node. Accepts a single condition atom, an AND/OR
+   * group, or an AND/OR nested group. Omit the `conditions` property entirely to
+   * express "no conditions".
+   */
+  conditions?: JourneyConditionsField;
+
+  /**
+   * An optional event filter, matched against the payload's `event` field. A sender
+   * that supplies no `event` matches the literal `custom`. Must not contain a
+   * forward slash. Omit to accept every event delivered to the URL.
+   */
+  event_id?: 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
@@ -1427,6 +1640,7 @@ export interface JourneyReplaceParams {
 }
 
 Journeys.Templates = Templates;
+Journeys.Runs = Runs;
 
 export declare namespace Journeys {
   export {
@@ -1436,6 +1650,7 @@ export declare namespace Journeys {
     type Journey as Journey,
     type JourneyAINode as JourneyAINode,
     type JourneyAPIInvokeTriggerNode as JourneyAPIInvokeTriggerNode,
+    type JourneyAudienceTriggerNode as JourneyAudienceTriggerNode,
     type JourneyConditionAtom as JourneyConditionAtom,
     type JourneyConditionGroup as JourneyConditionGroup,
     type JourneyConditionNestedGroup as JourneyConditionNestedGroup,
@@ -1451,6 +1666,12 @@ export declare namespace Journeys {
     type JourneyNode as JourneyNode,
     type JourneyPublishRequest as JourneyPublishRequest,
     type JourneyResponse as JourneyResponse,
+    type JourneyRun as JourneyRun,
+    type JourneyRunListItem as JourneyRunListItem,
+    type JourneyRunListResponse as JourneyRunListResponse,
+    type JourneyRunResponse as JourneyRunResponse,
+    type JourneyRunStep as JourneyRunStep,
+    type JourneyRunStepsResponse as JourneyRunStepsResponse,
     type JourneySegmentTriggerNode as JourneySegmentTriggerNode,
     type JourneySendNode as JourneySendNode,
     type JourneyState as JourneyState,
@@ -1464,6 +1685,7 @@ export declare namespace Journeys {
     type JourneyThrottleStaticNode as JourneyThrottleStaticNode,
     type JourneyVersionItem as JourneyVersionItem,
     type JourneyVersionsListResponse as JourneyVersionsListResponse,
+    type JourneyWebhookTriggerNode as JourneyWebhookTriggerNode,
     type JourneysInvokeRequest as JourneysInvokeRequest,
     type JourneysInvokeResponse as JourneysInvokeResponse,
     type JourneysListResponse as JourneysListResponse,
@@ -1489,4 +1711,6 @@ export declare namespace Journeys {
     type TemplateReplaceParams as TemplateReplaceParams,
     type TemplateRetrieveContentParams as TemplateRetrieveContentParams,
   };
+
+  export { Runs as Runs, type RunListParams as RunListParams };
 }

package/src/resources/journeys/runs.ts

@@ -0,0 +1,104 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as JourneysAPI from './journeys';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Build, version, publish, invoke, and cancel multi-step notification workflows, along with the templates scoped to them.
+ */
+export class Runs extends APIResource {
+  /**
+   * Fetch one Journey run by id. Returns `404` for an unknown run, a run belonging
+   * to another workspace, a run past the 95-day retention window, or an Automation
+   * run id — the same body in every case, so the response never reveals whether a
+   * run exists elsewhere.
+   *
+   * @example
+   * ```ts
+   * const journeyRunResponse =
+   *   await client.journeys.runs.retrieve('x');
+   * ```
+   */
+  retrieve(runID: string, options?: RequestOptions): APIPromise<JourneysAPI.JourneyRunResponse> {
+    return this._client.get(path`/journeys/runs/${runID}`, options);
+  }
+
+  /**
+   * List runs of the workspace's Journeys, newest first, filtered by status,
+   * Journey, or date range and paged by cursor. Runs of v2 Automations are listed by
+   * `GET /automations/runs` instead — the two surfaces never return each other's
+   * runs. Runs are retained for 95 days.
+   *
+   * @example
+   * ```ts
+   * const journeyRunListResponse =
+   *   await client.journeys.runs.list();
+   * ```
+   */
+  list(
+    query: RunListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<JourneysAPI.JourneyRunListResponse> {
+    return this._client.get('/journeys/runs', { query, ...options });
+  }
+
+  /**
+   * List the per-node state of one Journey run, in full — this endpoint is not
+   * paginated. Each step's `node_id` is the id of the node in the published Journey,
+   * so a step maps directly onto the Journey graph. `message_id` is present on send
+   * steps that produced a message; follow it to `GET /messages/{message_id}` for
+   * delivery status.
+   *
+   * @example
+   * ```ts
+   * const journeyRunStepsResponse =
+   *   await client.journeys.runs.listSteps('x');
+   * ```
+   */
+  listSteps(runID: string, options?: RequestOptions): APIPromise<JourneysAPI.JourneyRunStepsResponse> {
+    return this._client.get(path`/journeys/runs/${runID}/steps`, options);
+  }
+}
+
+export interface RunListParams {
+  /**
+   * A cursor token for pagination. Use the `next_cursor` from the previous response
+   * to fetch the next page of results. Treat it as opaque.
+   */
+  cursor?: string;
+
+  /**
+   * An inclusive upper bound on `created_at`, in the same format as `start_date`.
+   */
+  end_date?: string;
+
+  /**
+   * The number of runs to return per page, between `1` and `50`. Defaults to `20`.
+   * Values outside the range are clamped, and a non-numeric value falls back to
+   * `20`.
+   */
+  limit?: string;
+
+  /**
+   * An inclusive lower bound on `created_at`, as an ISO 8601 date or timestamp (e.g.
+   * `2026-08-18` or `2026-08-18T20:06:36.259Z`). Any other format returns `400`.
+   */
+  start_date?: string;
+
+  /**
+   * A comma-separated list of run statuses to filter on, e.g. `PROCESSED,ERROR`.
+   */
+  status?: string;
+
+  /**
+   * A comma-separated list of Journey ids to filter on.
+   */
+  template_id?: string;
+}
+
+export declare namespace Runs {
+  export { type RunListParams as RunListParams };
+}

package/src/resources/notifications/index.ts

@@ -19,6 +19,7 @@ export {
   type NotificationElementPutRequest,
   type NotificationGetContent,
   type NotificationLocalePutRequest,
+  type NotificationMetricsResponse,
   type NotificationTemplateAlias,
   type NotificationTemplateCreateRequest,
   type NotificationTemplatePayload,
@@ -35,6 +36,7 @@ export {
   type NotificationCreateParams,
   type NotificationRetrieveParams,
   type NotificationListParams,
+  type NotificationGetMetricsParams,
   type NotificationListVersionsParams,
   type NotificationPublishParams,
   type NotificationPutContentParams,

package/src/resources/notifications/notifications.ts

@@ -124,6 +124,42 @@ export class Notifications extends APIResource {
     });
   }
 
+  /**
+   * Fetch the delivery funnel for one Notification Template as a time series — sent,
+   * delivered, opened, clicked, errors, and undeliverable — broken out per provider
+   * and channel inside each bucket. Sum the entries in a bucket for its totals;
+   * there is no bucket-level total.
+   *
+   * Choose the window absolutely with `start` and `end`, or relatively with
+   * `lookback` (an ISO 8601 duration). `start` and `end` take precedence when both
+   * are supplied, and a request carrying neither defaults to `lookback=P30D`. The
+   * window is snapped outwards onto the `granularity` grid so every bucket it
+   * overlaps is returned whole, and the snapped boundaries come back as `start` and
+   * `end` — align a chart on those rather than on what was requested. Every boundary
+   * is UTC; there is no timezone support.
+   *
+   * Every bucket in the window is returned, including the quiet ones, whose `data`
+   * array is empty, so a series is directly plottable with no gap filling
+   * client-side. An unknown template id returns `200` with an all-empty series
+   * rather than `404`, and messages sent without a Notification Template never
+   * appear here.
+   *
+   * Available in the US region only.
+   *
+   * @example
+   * ```ts
+   * const notificationMetricsResponse =
+   *   await client.notifications.getMetrics('x');
+   * ```
+   */
+  getMetrics(
+    id: string,
+    query: NotificationGetMetricsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<NotificationMetricsResponse> {
+    return this._client.get(path`/notifications/${id}/metrics`, { query, ...options });
+  }
+
   /**
    * Returns a notification template's published versions, most recent first, for
    * comparison or rollback. Paged.
@@ -546,6 +582,96 @@ export namespace NotificationLocalePutRequest {
   }
 }
 
+export interface NotificationMetricsResponse {
+  /**
+   * End of the window actually queried, ceiled onto the granularity grid.
+   * Second-precision UTC.
+   */
+  end: string;
+
+  /**
+   * Bucket size the series was built at.
+   */
+  granularity: 'HOUR' | 'DAY' | 'WEEK' | 'MONTH';
+
+  /**
+   * The template the series describes, echoed from the request.
+   */
+  notificationId: string;
+
+  /**
+   * One entry per bucket between `start` and `end`, oldest first, including buckets
+   * with no activity.
+   */
+  series: Array<NotificationMetricsResponse.Series>;
+
+  /**
+   * Inclusive start of the window actually queried, floored onto the granularity
+   * grid. Second-precision UTC.
+   */
+  start: string;
+}
+
+export namespace NotificationMetricsResponse {
+  export interface Series {
+    /**
+     * One entry per provider and channel that handled a message in this bucket. Empty
+     * when nothing was sent.
+     */
+    data: Array<Series.Data>;
+
+    /**
+     * Start of the bucket, second-precision UTC.
+     */
+    period: string;
+  }
+
+  export namespace Series {
+    export interface Data {
+      /**
+       * Channel the provider delivered on, e.g. `email`.
+       */
+      channel: string;
+
+      /**
+       * Messages with at least one tracked link click.
+       */
+      clicked: number;
+
+      /**
+       * Messages the provider confirmed as delivered.
+       */
+      delivered: number;
+
+      /**
+       * Messages the provider rejected or failed on, including ones a later provider
+       * then delivered.
+       */
+      errors: number;
+
+      /**
+       * Messages opened at least once. Always `0` on channels with no open tracking.
+       */
+      opened: number;
+
+      /**
+       * Provider that handled the messages, e.g. `sendgrid`.
+       */
+      provider: string;
+
+      /**
+       * Messages handed to the provider.
+       */
+      sent: number;
+
+      /**
+       * Messages Courier could not deliver on any provider for the channel.
+       */
+      undeliverable: number;
+    }
+  }
+}
+
 /**
  * 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
@@ -916,6 +1042,38 @@ export interface NotificationListParams {
   notes?: boolean | null;
 }
 
+export interface NotificationGetMetricsParams {
+  /**
+   * The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied
+   * together with `start`. An `end` in the future is accepted and not clamped — the
+   * trailing buckets come back empty.
+   */
+  end?: string;
+
+  /**
+   * The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start
+   * on Sunday. A fine granularity caps the window it can cover: `HOUR` spans at most
+   * 7 days and `DAY` at most 90 days, and a wider window returns `400` — request a
+   * coarser granularity instead. `WEEK` and `MONTH` are uncapped, subject to the
+   * 1000-bucket limit on a single response.
+   */
+  granularity?: 'HOUR' | 'DAY' | 'WEEK' | 'MONTH';
+
+  /**
+   * The length of the window, counted back from now, as an ISO 8601 duration
+   * (`P30D`, `P12W`, `PT12H`). Defaults to `P30D`, and is ignored when `start` and
+   * `end` are supplied. A malformed or non-positive duration returns `400`.
+   */
+  lookback?: string;
+
+  /**
+   * The inclusive start of the window, as an ISO 8601 timestamp with an offset
+   * (`2026-04-01T00:00:00Z`). Must be supplied together with `end` and be earlier
+   * than it; either one alone returns `400`.
+   */
+  start?: string;
+}
+
 export interface NotificationListVersionsParams {
   /**
    * Opaque pagination cursor from a previous response. Omit for the first page.
@@ -1088,6 +1246,7 @@ export declare namespace Notifications {
     type NotificationElementPutRequest as NotificationElementPutRequest,
     type NotificationGetContent as NotificationGetContent,
     type NotificationLocalePutRequest as NotificationLocalePutRequest,
+    type NotificationMetricsResponse as NotificationMetricsResponse,
     type NotificationTemplateAlias as NotificationTemplateAlias,
     type NotificationTemplateCreateRequest as NotificationTemplateCreateRequest,
     type NotificationTemplatePayload as NotificationTemplatePayload,
@@ -1104,6 +1263,7 @@ export declare namespace Notifications {
     type NotificationCreateParams as NotificationCreateParams,
     type NotificationRetrieveParams as NotificationRetrieveParams,
     type NotificationListParams as NotificationListParams,
+    type NotificationGetMetricsParams as NotificationGetMetricsParams,
     type NotificationListVersionsParams as NotificationListVersionsParams,
     type NotificationPublishParams as NotificationPublishParams,
     type NotificationPutContentParams as NotificationPutContentParams,

package/src/resources/users/preferences.ts

@@ -244,6 +244,20 @@ export interface TopicPreference {
    * custom_routing) rather than the topic's default routing.
    */
   has_custom_routing?: boolean | null;
+
+  /**
+   * The unique identifier of the section this topic belongs to. Always present when
+   * listing a user's preferences; omitted by the single-topic read when the topic
+   * has no resolvable section.
+   */
+  section_id?: string;
+
+  /**
+   * The display name of the section this topic belongs to. Always present when
+   * listing a user's preferences; omitted by the single-topic read when the topic
+   * has no resolvable section.
+   */
+  section_name?: string;
 }
 
 export interface PreferenceRetrieveResponse {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '9.0.0'; // x-release-please-version
+export const VERSION = '9.2.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "9.0.0";
+export declare const VERSION = "9.2.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "9.0.0";
+export declare const VERSION = "9.2.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '9.0.0'; // x-release-please-version
+exports.VERSION = '9.2.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '9.0.0'; // x-release-please-version
+export const VERSION = '9.2.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map