@trycourier/courier 9.5.0 → 9.7.0

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

@@ -1,11 +1,15 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as WorkspacePreferencesAPI from './workspace-preferences';
 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 +219,216 @@ 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 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>;
+
+  /**
+   * The cadences this digest delivers on.
+   *
+   * The array replaces the stored schedules wholesale, so a schedule you leave out
+   * of it is deleted along with its delivery rule. Omit the key entirely to leave
+   * the stored schedules untouched — useful for changing `template_id` or
+   * `categories` without restating every schedule.
+   *
+   * A digest must end up with at least one schedule, because one with none collects
+   * events into an instance that can never fire. So sending `[]` is always a `400`,
+   * and so is omitting the key on a topic that has no schedules stored yet.
+   *
+   * On **create** the key is required outright: a topic being created has nothing
+   * stored to leave alone, and the topic row is written before its digest, so
+   * rejecting it any later would leave the topic behind and let a retry duplicate
+   * it.
+   */
+  schedules?: Array<TopicDigestScheduleRequest>;
+
+  /**
+   * 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.
+ *
+ * Updating by `schedule_id` replaces that schedule rather than merging into it:
+ * any field you leave out is cleared. Two of those change delivery silently — an
+ * omitted `timezone` reverts the schedule to UTC, and an omitted `is_default` can
+ * leave the topic with no default schedule, which is what recipients who have not
+ * chosen one fall back to. Restate every field you want to keep.
+ */
+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 +568,22 @@ export interface WorkspacePreferenceTopicCreateRequest {
    */
   description?: string | null;
 
+  /**
+   * A topic's digest, as supplied when the topic itself is created: the template
+   * that renders it, the cadences it delivers on, and how collected events are
+   * retained.
+   *
+   * Identical to `TopicDigestRequest`, which a replace uses, except that `schedules`
+   * is required — a topic being created has no stored schedules for an absent key to
+   * leave alone.
+   *
+   * 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?: WorkspacePreferenceTopicCreateRequest.Digest | null;
+
   /**
    * Whether to include a list-unsubscribe header on emails for this topic.
    */
@@ -370,6 +600,65 @@ export interface WorkspacePreferenceTopicCreateRequest {
   topic_data?: { [key: string]: unknown } | null;
 }
 
+export namespace WorkspacePreferenceTopicCreateRequest {
+  /**
+   * A topic's digest, as supplied when the topic itself is created: the template
+   * that renders it, the cadences it delivers on, and how collected events are
+   * retained.
+   *
+   * Identical to `TopicDigestRequest`, which a replace uses, except that `schedules`
+   * is required — a topic being created has no stored schedules for an absent key to
+   * leave alone.
+   *
+   * 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 Digest {
+    /**
+     * The cadences this digest delivers on.
+     *
+     * The array replaces the stored schedules wholesale, so a schedule you leave out
+     * of it is deleted along with its delivery rule. Omit the key entirely to leave
+     * the stored schedules untouched — useful for changing `template_id` or
+     * `categories` without restating every schedule.
+     *
+     * A digest must end up with at least one schedule, because one with none collects
+     * events into an instance that can never fire. So sending `[]` is always a `400`,
+     * and so is omitting the key on a topic that has no schedules stored yet.
+     *
+     * On **create** the key is required outright: a topic being created has nothing
+     * stored to leave alone, and the topic row is written before its digest, so
+     * rejecting it any later would leave the topic behind and let a retry duplicate
+     * it.
+     */
+    schedules: Array<WorkspacePreferencesAPI.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<WorkspacePreferencesAPI.TopicDigestCategory>;
+
+    /**
+     * Whether to deliver the digest even when nothing was collected.
+     */
+    trigger_empty?: boolean;
+  }
+}
+
 /**
  * A subscription preference topic in your workspace.
  */
@@ -429,6 +718,11 @@ export interface WorkspacePreferenceTopicGetResponse {
    */
   description?: string | null;
 
+  /**
+   * A topic's digest configuration.
+   */
+  digest?: TopicDigestResponse | null;
+
   /**
    * Id of the last updater.
    */
@@ -468,6 +762,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 +897,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 +920,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.7.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.7.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.7.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.7.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.7.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map