@trycourier/courier 9.5.0 → 9.6.0

package/src/resources/digests/digests.ts

@@ -26,6 +26,24 @@ export interface DigestCategory {
   sort_key?: string;
 }
 
+/**
+ * A day of the week. Accepted case-insensitively, returned lowercase.
+ */
+export type DigestDayOfWeek =
+  | 'sunday'
+  | 'monday'
+  | 'tuesday'
+  | 'wednesday'
+  | 'thursday'
+  | 'friday'
+  | 'saturday';
+
+/**
+ * How often a digest is delivered. `instant` delivers immediately without
+ * batching, and is the one value that takes no `time`.
+ */
+export type DigestFrequency = 'instant' | 'daily' | 'weekdays' | 'weekly' | 'custom_days' | 'monthly';
+
 export interface DigestInstance {
   /**
    * A unique identifier for the digest instance.
@@ -107,13 +125,76 @@ export interface DigestInstanceListResponse {
   url?: string;
 }
 
+/**
+ * A delivery cadence for a topic's digest, with its assigned id.
+ */
+export interface TopicDigestScheduleResponse {
+  /**
+   * The schedule's identifier, assigned by the server. This is the value the
+   * `/digests/schedules/{schedule_id}` endpoints are keyed by.
+   */
+  schedule_id: string;
+
+  /**
+   * ISO-8601 timestamp of when the schedule was created.
+   */
+  created?: string;
+
+  /**
+   * Day of the month, 1-31.
+   */
+  day_of_month?: number;
+
+  /**
+   * A day of the week. Accepted case-insensitively, returned lowercase.
+   */
+  day_of_week?: DigestDayOfWeek;
+
+  days_of_week?: Array<DigestDayOfWeek>;
+
+  /**
+   * Whether the schedule is disabled.
+   */
+  disabled?: boolean;
+
+  /**
+   * Omitted for a stored schedule this enum cannot express. Those schedules never
+   * fire, but their `schedule_id` is still returned so the `/digests/*` endpoints
+   * remain reachable for them.
+   */
+  frequency?: DigestFrequency;
+
+  /**
+   * Whether this is the schedule recipients are placed on by default.
+   */
+  is_default?: boolean;
+
+  /**
+   * 24-hour local delivery time, `HH:MM`.
+   */
+  time?: string;
+
+  /**
+   * IANA timezone the schedule is expressed in. Absent means UTC.
+   */
+  timezone?: string;
+
+  /**
+   * ISO-8601 timestamp of the last update.
+   */
+  updated?: string;
+}
+
 Digests.Schedules = Schedules;
 
 export declare namespace Digests {
   export {
     type DigestCategory as DigestCategory,
+    type DigestDayOfWeek as DigestDayOfWeek,
+    type DigestFrequency as DigestFrequency,
     type DigestInstance as DigestInstance,
     type DigestInstanceListResponse as DigestInstanceListResponse,
+    type TopicDigestScheduleResponse as TopicDigestScheduleResponse,
   };
 
   export { Schedules as Schedules, type ScheduleListInstancesParams as ScheduleListInstancesParams };

package/src/resources/digests/index.ts

@@ -3,7 +3,10 @@
 export {
   Digests,
   type DigestCategory,
+  type DigestDayOfWeek,
+  type DigestFrequency,
   type DigestInstance,
   type DigestInstanceListResponse,
+  type TopicDigestScheduleResponse,
 } from './digests';
 export { Schedules, type ScheduleListInstancesParams } from './schedules';

package/src/resources/index.ts

@@ -81,8 +81,11 @@ export {
 export {
   Digests,
   type DigestCategory,
+  type DigestDayOfWeek,
+  type DigestFrequency,
   type DigestInstance,
   type DigestInstanceListResponse,
+  type TopicDigestScheduleResponse,
 } from './digests/digests';
 export { Inbound, type InboundTrackEventResponse, type InboundTrackEventParams } from './inbound';
 export {
@@ -265,6 +268,11 @@ export {
   WorkspacePreferences,
   type PublishPreferencesRequest,
   type PublishPreferencesResponse,
+  type TopicDigestCategory,
+  type TopicDigestReleaseRequest,
+  type TopicDigestRequest,
+  type TopicDigestResponse,
+  type TopicDigestScheduleRequest,
   type WorkspacePreferenceCreateRequest,
   type WorkspacePreferenceGetResponse,
   type WorkspacePreferenceListResponse,

package/src/resources/journeys/journeys.ts

@@ -446,10 +446,18 @@ export interface JourneyAudienceTriggerNode {
  * - Binary form (3 elements): `[path, operator, value]` where `operator` is one of
  *   `is equal`, `is not equal`, `contains`, `does not contain`, `starts with`,
  *   `ends with`, `greater than`, `greater than or equal`, `less than`,
- *   `less than or equal`.
+ *   `less than or equal`, `was`, `was not`.
  *
  *   Example: `["user.tier", "is equal", "gold"]`.
  *
+ *   `was` / `was not` compare a `send_status.<nodeId>` path (referencing an
+ *   earlier send node's node id) against one of `SENT`, `DELIVERED`, `OPENED`,
+ *   `CLICKED`, `UNDELIVERABLE`. The first four are cumulative and ordered
+ *   `SENT < DELIVERED < OPENED < CLICKED`, so `was DELIVERED` is true once the
+ *   message has reached DELIVERED, OPENED, or CLICKED. `UNDELIVERABLE` is an exact
+ *   match only and is never part of that ordering, in either direction. Example:
+ *   `["send_status.P9Z3VCRJG647M7QNJZR3548HW741", "was", "DELIVERED"]`.
+ *
  * - Unary form (2 elements): `[path, operator]` where `operator` is one of
  *   `exists`, `does not exist`.
  *
@@ -769,7 +777,18 @@ export namespace JourneyNode {
   /**
    * Add the current event to a digest keyed by the given subscription topic. The
    * digest accumulates events and releases them on the schedule configured for the
-   * topic.
+   * topic, using the notification template configured on that topic. This node's
+   * `type` value is `add-to-digest`.
+   *
+   * **The topic must have a template configured.** If the topic has no template when
+   * the first event reaches this node, the journey run fails immediately: the run is
+   * marked `ERROR`, no digest instance is created, and the journey does not continue
+   * past this node. Configure the topic's template before using the topic in a
+   * journey.
+   *
+   * If the journey run is scoped to a tenant, digests are kept separate per tenant:
+   * two runs for the same user under different tenants accumulate and release as
+   * separate digests, even on the same topic.
    */
   export interface JourneyAddToDigestNode {
     /**

package/src/resources/users/preferences.ts

@@ -239,6 +239,14 @@ export interface TopicPreference {
    */
   custom_routing?: Array<Shared.ChannelClassification> | null;
 
+  /**
+   * The digest schedule this recipient is on for the topic. Omitted rather than null
+   * when they have not chosen one, in which case the topic's default schedule
+   * applies. Ids come from the topic's digest configuration or from
+   * `GET /digests/schedules`.
+   */
+  digest_schedule_id?: string;
+
   /**
    * Whether the user has chosen specific delivery channels for this topic (listed in
    * custom_routing) rather than the topic's default routing.
@@ -477,6 +485,15 @@ export namespace PreferenceUpdateOrCreateTopicParams {
      */
     custom_routing?: Array<Shared.ChannelClassification> | null;
 
+    /**
+     * Put this recipient on one of the topic's digest schedules. Send `null` to clear
+     * the choice and return them to the topic's default. Omit to leave an existing
+     * choice alone, unlike the routing fields, which this endpoint replaces. An id
+     * that is not an active schedule on the topic is rejected with a `400` before
+     * anything is written.
+     */
+    digest_schedule_id?: string | null;
+
     /**
      * Set to true to route this topic to the channels in custom_routing instead of the
      * topic's default routing.

package/src/resources/workspace-preferences/index.ts

@@ -5,12 +5,19 @@ export {
   type TopicCreateParams,
   type TopicRetrieveParams,
   type TopicArchiveParams,
+  type TopicDeleteDigestParams,
+  type TopicReleaseDigestParams,
   type TopicReplaceParams,
 } from './topics';
 export {
   WorkspacePreferences,
   type PublishPreferencesRequest,
   type PublishPreferencesResponse,
+  type TopicDigestCategory,
+  type TopicDigestReleaseRequest,
+  type TopicDigestRequest,
+  type TopicDigestResponse,
+  type TopicDigestScheduleRequest,
   type WorkspacePreferenceCreateRequest,
   type WorkspacePreferenceGetResponse,
   type WorkspacePreferenceListResponse,

package/src/resources/workspace-preferences/topics.ts

@@ -8,9 +8,6 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
-/**
- * Manage the workspace catalog of subscription topics, the sections that group them, and publishing the preference page.
- */
 export class Topics extends APIResource {
   /**
    * Creates a subscription topic inside a workspace preference. The default status
@@ -111,6 +108,60 @@ export class Topics extends APIResource {
     });
   }
 
+  /**
+   * Turn off a topic's digest, leaving the topic itself in place. The template is
+   * unlinked and the digest's schedules are removed along with their delivery rules.
+   * Equivalent to sending `digest: null` on a topic replace.
+   *
+   * @example
+   * ```ts
+   * await client.workspacePreferences.topics.deleteDigest(
+   *   'topic_id',
+   *   { section_id: 'section_id' },
+   * );
+   * ```
+   */
+  deleteDigest(topicID: string, params: TopicDeleteDigestParams, options?: RequestOptions): APIPromise<void> {
+    const { section_id } = params;
+    return this._client.delete(path`/preferences/sections/${section_id}/topics/${topicID}/digest`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Send one recipient's held digest now, instead of waiting for its schedule. Use
+   * it to preview what a digest will look like, or to let someone flush their own.
+   *
+   * Keyed on the topic because that is how a held digest is stored: one per
+   * recipient per topic, with the schedule recorded on it rather than part of its
+   * identity. To flush every recipient on a schedule instead, use
+   * `POST /digests/schedules/{schedule_id}/trigger`.
+   *
+   * @example
+   * ```ts
+   * await client.workspacePreferences.topics.releaseDigest(
+   *   'topic_id',
+   *   {
+   *     section_id: 'section_id',
+   *     user_id: 'user_01h1p2c3d4e5f6g7h8',
+   *   },
+   * );
+   * ```
+   */
+  releaseDigest(
+    topicID: string,
+    params: TopicReleaseDigestParams,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { section_id, ...body } = params;
+    return this._client.post(path`/preferences/sections/${section_id}/topics/${topicID}/digest/release`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
   /**
    * Replace a topic within a workspace preference. Full document replacement;
    * missing optional fields are cleared. Same 404 rules as GET.
@@ -168,6 +219,17 @@ export interface TopicCreateParams {
    */
   description?: string | null;
 
+  /**
+   * Body param: A topic's digest configuration: the template that renders it, the
+   * cadences it delivers on, and how collected events are retained.
+   *
+   * Send `null` for the whole object to turn a digest off, which unlinks the
+   * template and removes its schedules. There is no `enabled` flag, and
+   * `schedules: []` is rejected, because both states are un-deliverable rather than
+   * merely off.
+   */
+  digest?: WorkspacePreferencesAPI.TopicDigestRequest | null;
+
   /**
    * Body param: Whether to include a list-unsubscribe header on emails for this
    * topic.
@@ -218,6 +280,36 @@ export interface TopicArchiveParams {
   section_id: string;
 }
 
+export interface TopicDeleteDigestParams {
+  /**
+   * The preference section containing the topic.
+   */
+  section_id: string;
+}
+
+export interface TopicReleaseDigestParams {
+  /**
+   * Path param: The preference section containing the topic.
+   */
+  section_id: string;
+
+  /**
+   * Body param: The recipient whose digest to release. Required: there is no
+   * "release everyone on this topic" form, because a whole-schedule flush already
+   * has its own endpoint and a body-shaped difference between one recipient and all
+   * of them is too easy to get wrong.
+   */
+  user_id: string;
+
+  /**
+   * Body param: The recipient's tenant, when they were sent to as part of one -- the
+   * same value returned as `tenant_id` on a digest instance and sent as
+   * `message.context.tenant_id`. It is part of the held digest's key, so a tenanted
+   * recipient cannot be found without it. Omit for an ordinary recipient.
+   */
+  tenant_id?: string;
+}
+
 export interface TopicReplaceParams {
   /**
    * Path param: Id of the workspace preference.
@@ -246,6 +338,17 @@ export interface TopicReplaceParams {
    */
   description?: string | null;
 
+  /**
+   * Body param: A topic's digest configuration: the template that renders it, the
+   * cadences it delivers on, and how collected events are retained.
+   *
+   * Send `null` for the whole object to turn a digest off, which unlinks the
+   * template and removes its schedules. There is no `enabled` flag, and
+   * `schedules: []` is rejected, because both states are un-deliverable rather than
+   * merely off.
+   */
+  digest?: WorkspacePreferencesAPI.TopicDigestRequest | null;
+
   /**
    * Body param: Whether to include a list-unsubscribe header on emails for this
    * topic.
@@ -268,6 +371,8 @@ export declare namespace Topics {
     type TopicCreateParams as TopicCreateParams,
     type TopicRetrieveParams as TopicRetrieveParams,
     type TopicArchiveParams as TopicArchiveParams,
+    type TopicDeleteDigestParams as TopicDeleteDigestParams,
+    type TopicReleaseDigestParams as TopicReleaseDigestParams,
     type TopicReplaceParams as TopicReplaceParams,
   };
 }

package/src/resources/workspace-preferences/workspace-preferences.ts

@@ -2,10 +2,13 @@
 
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
+import * as DigestsAPI from '../digests/digests';
 import * as TopicsAPI from './topics';
 import {
   TopicArchiveParams,
   TopicCreateParams,
+  TopicDeleteDigestParams,
+  TopicReleaseDigestParams,
   TopicReplaceParams,
   TopicRetrieveParams,
   Topics,
@@ -215,6 +218,198 @@ export interface PublishPreferencesResponse {
   published_by?: string | null;
 }
 
+/**
+ * How events collected under a category key are retained when a digest holds more
+ * than it will render.
+ */
+export interface TopicDigestCategory {
+  /**
+   * The key that identifies the category within the digest.
+   */
+  category_key: string;
+
+  /**
+   * How many collected events are carried into the rendered digest. Defaults to 10.
+   *
+   * Events beyond the limit are discarded, not held back for the next digest: the
+   * release consumes everything collected so far and only `limit` of them appear.
+   * `retain` decides which ones those are.
+   */
+  limit?: number;
+
+  /**
+   * Which collected events survive the `limit`. `FIRST` and `LOWEST` keep the
+   * earliest or smallest; `LAST` and `HIGHEST` keep the latest or largest. Accepted
+   * case-insensitively, returned uppercase.
+   */
+  retain?: 'FIRST' | 'LAST' | 'HIGHEST' | 'LOWEST' | 'NONE';
+
+  /**
+   * The data key used to rank events. Required when `retain` is `HIGHEST` or
+   * `LOWEST`.
+   */
+  sort_key?: string;
+}
+
+/**
+ * Which recipient's held digest to release.
+ */
+export interface TopicDigestReleaseRequest {
+  /**
+   * The recipient whose digest to release. Required: there is no "release everyone
+   * on this topic" form, because a whole-schedule flush already has its own endpoint
+   * and a body-shaped difference between one recipient and all of them is too easy
+   * to get wrong.
+   */
+  user_id: string;
+
+  /**
+   * The recipient's tenant, when they were sent to as part of one -- the same value
+   * returned as `tenant_id` on a digest instance and sent as
+   * `message.context.tenant_id`. It is part of the held digest's key, so a tenanted
+   * recipient cannot be found without it. Omit for an ordinary recipient.
+   */
+  tenant_id?: string;
+}
+
+/**
+ * A topic's digest configuration: the template that renders it, the cadences it
+ * delivers on, and how collected events are retained.
+ *
+ * Send `null` for the whole object to turn a digest off, which unlinks the
+ * template and removes its schedules. There is no `enabled` flag, and
+ * `schedules: []` is rejected, because both states are un-deliverable rather than
+ * merely off.
+ */
+export interface TopicDigestRequest {
+  /**
+   * The cadences this digest delivers on. At least one is required: a digest with no
+   * schedule collects events into an instance that can never fire. Omitting the key
+   * on a replace leaves stored schedules untouched; sending `[]` is a `400`.
+   */
+  schedules: Array<TopicDigestScheduleRequest>;
+
+  /**
+   * The notification template that renders the digest. A digest with no template
+   * collects nothing, so this is required.
+   */
+  template_id: string;
+
+  /**
+   * Optional audience the digest is scoped to.
+   */
+  audience_id?: string;
+
+  /**
+   * Retention rules per category key. Defaults to a single `digest` category
+   * retaining `FIRST`.
+   */
+  categories?: Array<TopicDigestCategory>;
+
+  /**
+   * Whether to deliver the digest even when nothing was collected.
+   */
+  trigger_empty?: boolean;
+}
+
+/**
+ * A topic's digest configuration.
+ */
+export interface TopicDigestResponse {
+  /**
+   * Retention rules per category key.
+   */
+  categories: Array<TopicDigestCategory>;
+
+  /**
+   * The digest's delivery cadences, each with its server-assigned `schedule_id`.
+   */
+  schedules: Array<DigestsAPI.TopicDigestScheduleResponse>;
+
+  /**
+   * The notification template that renders the digest.
+   */
+  template_id: string;
+
+  /**
+   * The audience the digest is scoped to, when set.
+   */
+  audience_id?: string;
+
+  /**
+   * ISO-8601 timestamp of when the digest was configured.
+   */
+  created?: string;
+
+  /**
+   * Whether the digest is delivered even when nothing was collected.
+   */
+  trigger_empty?: boolean;
+
+  /**
+   * ISO-8601 timestamp of the last update.
+   */
+  updated?: string;
+}
+
+/**
+ * One delivery cadence for a topic's digest. Supply `schedule_id` to update an
+ * existing schedule in place; omit it and one is assigned and returned. The
+ * `schedules` array is a full replacement, so a stored schedule absent from it is
+ * deleted along with its delivery rule.
+ */
+export interface TopicDigestScheduleRequest {
+  /**
+   * How often a digest is delivered. `instant` delivers immediately without
+   * batching, and is the one value that takes no `time`.
+   */
+  frequency: DigestsAPI.DigestFrequency;
+
+  /**
+   * Required when `frequency` is `monthly`.
+   */
+  day_of_month?: number;
+
+  /**
+   * Required when `frequency` is `weekly`.
+   */
+  day_of_week?: DigestsAPI.DigestDayOfWeek;
+
+  /**
+   * Required when `frequency` is `custom_days`.
+   */
+  days_of_week?: Array<DigestsAPI.DigestDayOfWeek>;
+
+  /**
+   * Whether the schedule is disabled.
+   */
+  disabled?: boolean;
+
+  /**
+   * The schedule recipients are placed on when they have not chosen one. Set this
+   * explicitly rather than relying on array position.
+   */
+  is_default?: boolean;
+
+  /**
+   * Identifier of an existing schedule to update. Omit when creating a new one.
+   */
+  schedule_id?: string;
+
+  /**
+   * 24-hour local delivery time, `HH:MM`. Required for every frequency except
+   * `instant`.
+   */
+  time?: string;
+
+  /**
+   * IANA timezone the `time` and day fields are expressed in, e.g.
+   * `America/New_York`. Absent means UTC. Delivery follows the same local wall-clock
+   * across daylight-saving changes.
+   */
+  timezone?: string;
+}
+
 /**
  * Request body for creating a workspace preference.
  */
@@ -354,6 +549,17 @@ export interface WorkspacePreferenceTopicCreateRequest {
    */
   description?: string | null;
 
+  /**
+   * A topic's digest configuration: the template that renders it, the cadences it
+   * delivers on, and how collected events are retained.
+   *
+   * Send `null` for the whole object to turn a digest off, which unlinks the
+   * template and removes its schedules. There is no `enabled` flag, and
+   * `schedules: []` is rejected, because both states are un-deliverable rather than
+   * merely off.
+   */
+  digest?: TopicDigestRequest | null;
+
   /**
    * Whether to include a list-unsubscribe header on emails for this topic.
    */
@@ -429,6 +635,11 @@ export interface WorkspacePreferenceTopicGetResponse {
    */
   description?: string | null;
 
+  /**
+   * A topic's digest configuration.
+   */
+  digest?: TopicDigestResponse | null;
+
   /**
    * Id of the last updater.
    */
@@ -468,6 +679,17 @@ export interface WorkspacePreferenceTopicReplaceRequest {
    */
   description?: string | null;
 
+  /**
+   * A topic's digest configuration: the template that renders it, the cadences it
+   * delivers on, and how collected events are retained.
+   *
+   * Send `null` for the whole object to turn a digest off, which unlinks the
+   * template and removes its schedules. There is no `enabled` flag, and
+   * `schedules: []` is rejected, because both states are un-deliverable rather than
+   * merely off.
+   */
+  digest?: TopicDigestRequest | null;
+
   /**
    * Whether to include a list-unsubscribe header on emails for this topic.
    */
@@ -592,6 +814,11 @@ export declare namespace WorkspacePreferences {
   export {
     type PublishPreferencesRequest as PublishPreferencesRequest,
     type PublishPreferencesResponse as PublishPreferencesResponse,
+    type TopicDigestCategory as TopicDigestCategory,
+    type TopicDigestReleaseRequest as TopicDigestReleaseRequest,
+    type TopicDigestRequest as TopicDigestRequest,
+    type TopicDigestResponse as TopicDigestResponse,
+    type TopicDigestScheduleRequest as TopicDigestScheduleRequest,
     type WorkspacePreferenceCreateRequest as WorkspacePreferenceCreateRequest,
     type WorkspacePreferenceGetResponse as WorkspacePreferenceGetResponse,
     type WorkspacePreferenceListResponse as WorkspacePreferenceListResponse,
@@ -610,6 +837,8 @@ export declare namespace WorkspacePreferences {
     type TopicCreateParams as TopicCreateParams,
     type TopicRetrieveParams as TopicRetrieveParams,
     type TopicArchiveParams as TopicArchiveParams,
+    type TopicDeleteDigestParams as TopicDeleteDigestParams,
+    type TopicReleaseDigestParams as TopicReleaseDigestParams,
     type TopicReplaceParams as TopicReplaceParams,
   };
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '9.5.0'; // x-release-please-version
+export const VERSION = '9.6.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

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

package/version.mjs

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