@trycourier/courier 9.1.0 → 9.3.0

package/src/resources/journeys/journeys.ts

@@ -1073,6 +1073,11 @@ export namespace JourneySendNode {
 
     template?: string;
 
+    /**
+     * Recipient override for this send. Provide exactly one of `email_override`,
+     * `phone_number_override`, `user_id_override`, `slack`, or `ms_teams` — not a
+     * combination.
+     */
     to?: Message.To;
   }
 
@@ -1104,16 +1109,143 @@ export namespace JourneySendNode {
       timezone?: string;
     }
 
+    /**
+     * Recipient override for this send. Provide exactly one of `email_override`,
+     * `phone_number_override`, `user_id_override`, `slack`, or `ms_teams` — not a
+     * combination.
+     */
     export interface To {
       email_override?: string;
 
+      /**
+       * Send to a Microsoft Teams address directly, bypassing the recipient's stored
+       * profile. Requires exactly one target: `channel_id`, `channel_name` (with
+       * `team_id`), `user_id`, or `email`. `channel_name`, `user_id`, and `email` also
+       * need at least one of `service_url` or `tenant_id` — if you provide both, they
+       * must agree. `channel_id` doesn't require tenant context to publish, but provide
+       * `service_url` or `tenant_id` anyway: sends without either have failed at
+       * delivery in testing. `conversation_id` and `reply_to_activity_id`, available on
+       * the send API's `MsTeams` profile, aren't supported here yet.
+       */
+      ms_teams?: JourneysAPI.JourneySendNodeToMsTeams;
+
       phone_number_override?: string;
 
+      /**
+       * Send to a Slack address directly, bypassing the recipient's stored profile.
+       * Requires exactly one of `channel`, `user_id`, or `email`.
+       */
+      slack?: JourneysAPI.JourneySendNodeToSlack;
+
       user_id_override?: string;
     }
   }
 }
 
+/**
+ * Send to a Microsoft Teams address directly, bypassing the recipient's stored
+ * profile. Requires exactly one target: `channel_id`, `channel_name` (with
+ * `team_id`), `user_id`, or `email`. `channel_name`, `user_id`, and `email` also
+ * need at least one of `service_url` or `tenant_id` — if you provide both, they
+ * must agree. `channel_id` doesn't require tenant context to publish, but provide
+ * `service_url` or `tenant_id` anyway: sends without either have failed at
+ * delivery in testing. `conversation_id` and `reply_to_activity_id`, available on
+ * the send API's `MsTeams` profile, aren't supported here yet.
+ */
+export interface JourneySendNodeToMsTeams {
+  /**
+   * Bot Framework channel ID to send to.
+   */
+  channel_id?: string;
+
+  /**
+   * Teams channel name to send to. Requires `team_id`.
+   */
+  channel_name?: string;
+
+  /**
+   * Email address of the Teams user to send to.
+   */
+  email?: string;
+
+  /**
+   * The regional Bot Framework host for this conversation, e.g.
+   * `https://smba.trafficmanager.net/amer`. A path segment naming the Microsoft
+   * tenant may follow it and is used to derive `tenant_id` when it is not supplied
+   * directly.
+   */
+  service_url?: string;
+
+  /**
+   * Microsoft Teams team ID. Required alongside `channel_name`.
+   */
+  team_id?: string;
+
+  /**
+   * The Microsoft (Azure AD) tenant this send targets or authenticates against.
+   * Unrelated to `message.context.tenant_id`, which is the Courier customer's own
+   * multi-tenant context.
+   */
+  tenant_id?: string;
+
+  /**
+   * Microsoft Teams user ID to send to.
+   */
+  user_id?: string;
+}
+
+/**
+ * Send to a Slack address directly, bypassing the recipient's stored profile.
+ * Requires exactly one of `channel`, `user_id`, or `email`.
+ */
+export type JourneySendNodeToSlack =
+  | JourneySendNodeToSlackChannel
+  | JourneySendNodeToSlackUserID
+  | JourneySendNodeToSlackEmail;
+
+export interface JourneySendNodeToSlackChannel {
+  /**
+   * Slack channel to send to, by name or ID.
+   */
+  channel: string;
+
+  /**
+   * A runtime reference to a Slack access token, such as `{{data.slack_token}}`.
+   * Literal values are rejected — they'd be stored permanently with no way to rotate
+   * them. Omit to use the token on the recipient's stored Slack profile.
+   */
+  access_token?: string;
+}
+
+export interface JourneySendNodeToSlackEmail {
+  /**
+   * Email address of the Slack user to send to, resolved via the workspace
+   * directory.
+   */
+  email: string;
+
+  /**
+   * A runtime reference to a Slack access token, such as `{{data.slack_token}}`.
+   * Literal values are rejected — they'd be stored permanently with no way to rotate
+   * them. Omit to use the token on the recipient's stored Slack profile.
+   */
+  access_token?: string;
+}
+
+export interface JourneySendNodeToSlackUserID {
+  /**
+   * Slack user ID to send to.
+   */
+  user_id: string;
+
+  /**
+   * A runtime reference to a Slack access token, such as `{{data.slack_token}}`.
+   * Literal values are rejected — they'd be stored permanently with no way to rotate
+   * them. Omit to use the token on the recipient's stored Slack profile.
+   */
+  access_token?: string;
+}
+
 /**
  * Lifecycle state of a journey.
  */
@@ -1674,6 +1806,11 @@ export declare namespace Journeys {
     type JourneyRunStepsResponse as JourneyRunStepsResponse,
     type JourneySegmentTriggerNode as JourneySegmentTriggerNode,
     type JourneySendNode as JourneySendNode,
+    type JourneySendNodeToMsTeams as JourneySendNodeToMsTeams,
+    type JourneySendNodeToSlack as JourneySendNodeToSlack,
+    type JourneySendNodeToSlackChannel as JourneySendNodeToSlackChannel,
+    type JourneySendNodeToSlackEmail as JourneySendNodeToSlackEmail,
+    type JourneySendNodeToSlackUserID as JourneySendNodeToSlackUserID,
     type JourneyState as JourneyState,
     type JourneyTemplateCreateRequest as JourneyTemplateCreateRequest,
     type JourneyTemplateGetResponse as JourneyTemplateGetResponse,

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/shared.ts

@@ -383,6 +383,10 @@ export interface Metadata {
   utm?: Utm | null;
 }
 
+/**
+ * Provide at least one of `tenant_id` or `service_url`. If you provide both, they
+ * must agree.
+ */
 export type MsTeams =
   | SendToMsTeamsUserID
   | SendToMsTeamsEmail
@@ -390,16 +394,26 @@ export type MsTeams =
   | SendToMsTeamsConversationID
   | SendToMsTeamsChannelName;
 
+/**
+ * Tenant context shared by every MS Teams send variant. Provide at least one of
+ * `tenant_id` or `service_url`. If you provide both, they must agree — a
+ * `service_url` pointing at a different Microsoft tenant than `tenant_id` is
+ * rejected.
+ */
 export interface MsTeamsBaseProperties {
-  service_url: string;
+  service_url?: string;
 
-  tenant_id: string;
+  tenant_id?: string;
 }
 
 /**
  * Send via Microsoft Teams
  */
 export interface MsTeamsRecipient {
+  /**
+   * Provide at least one of `tenant_id` or `service_url`. If you provide both, they
+   * must agree.
+   */
   ms_teams: MsTeams;
 }
 
@@ -474,22 +488,31 @@ export interface SendToChannel {
   channel_id: string;
 }
 
+/**
+ * Sends directly to a Microsoft Teams channel by its Bot Framework ID. Still
+ * provide at least one of `tenant_id` or `service_url` — sends without either have
+ * failed Bot Framework authentication in testing.
+ */
 export interface SendToMsTeamsChannelID {
   channel_id: string;
 
-  service_url: string;
+  service_url?: string;
 
-  tenant_id: string;
+  tenant_id?: string;
 }
 
+/**
+ * `team_id` is required alongside `channel_name`. Also provide at least one of
+ * `tenant_id` or `service_url`; if you provide both, they must agree.
+ */
 export interface SendToMsTeamsChannelName {
   channel_name: string;
 
-  service_url: string;
-
   team_id: string;
 
-  tenant_id: string;
+  service_url?: string;
+
+  tenant_id?: string;
 }
 
 export interface SendToMsTeamsConversationID {
@@ -500,20 +523,28 @@ export interface SendToMsTeamsConversationID {
   tenant_id: string;
 }
 
+/**
+ * Provide at least one of `tenant_id` or `service_url`. If you provide both, they
+ * must agree.
+ */
 export interface SendToMsTeamsEmail {
   email: string;
 
-  service_url: string;
+  service_url?: string;
 
-  tenant_id: string;
+  tenant_id?: string;
 }
 
+/**
+ * Provide at least one of `tenant_id` or `service_url`. If you provide both, they
+ * must agree.
+ */
 export interface SendToMsTeamsUserID {
-  service_url: string;
+  user_id: string;
 
-  tenant_id: string;
+  service_url?: string;
 
-  user_id: string;
+  tenant_id?: string;
 }
 
 export interface SendToSlackChannel {
@@ -613,6 +644,10 @@ export interface UserProfile {
 
   middle_name?: string | null;
 
+  /**
+   * Provide at least one of `tenant_id` or `service_url`. If you provide both, they
+   * must agree.
+   */
   ms_teams?: MsTeams | null;
 
   name?: string | null;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '9.1.0'; // x-release-please-version
+export const VERSION = '9.3.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "9.1.0";
+export declare const VERSION = "9.3.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.1.0'; // x-release-please-version
+exports.VERSION = '9.3.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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