@trycourier/courier 7.11.0 → 7.19.1

package/src/resources/users/preferences.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
 import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -25,6 +26,125 @@ export class Preferences extends APIResource {
     return this._client.get(path`/users/${userID}/preferences`, { query, ...options });
   }
 
+  /**
+   * Replace a user's complete set of preference overrides in a single request. The
+   * topics in the request body become the recipient's entire set of overrides:
+   * listed topics are created or updated, and every existing override that is not
+   * included in the body is reset to its topic default. Submitting an empty `topics`
+   * array is a valid clear-all that resets every existing override.
+   *
+   * This operation is validation-atomic (all-or-nothing): structural validation
+   * fails fast with a single `400`, and if any topic is semantically invalid (an
+   * unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing
+   * request that is not available on the workspace's plan) the request returns a
+   * single `400` aggregating every failure in `errors` and writes nothing. On
+   * success it returns `200` with `items` (the complete resulting override set) and
+   * `deleted` (the ids of the overrides that were reset to default).
+   *
+   * Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is
+   * returned in Courier's canonical topic id form, regardless of the form supplied
+   * in the request.
+   *
+   * @example
+   * ```ts
+   * const response = await client.users.preferences.bulkReplace(
+   *   'user_id',
+   *   {
+   *     topics: [
+   *       {
+   *         topic_id: '74Q4QGFBEX481DP6JRPMV751H4XT',
+   *         status: 'OPTED_IN',
+   *         has_custom_routing: true,
+   *         custom_routing: ['inbox', 'email'],
+   *       },
+   *     ],
+   *   },
+   * );
+   * ```
+   */
+  bulkReplace(
+    userID: string,
+    params: PreferenceBulkReplaceParams,
+    options?: RequestOptions,
+  ): APIPromise<PreferenceBulkReplaceResponse> {
+    const { tenant_id, ...body } = params;
+    return this._client.put(path`/users/${userID}/preferences`, { query: { tenant_id }, body, ...options });
+  }
+
+  /**
+   * Additively create or update a user's preferences for one or more subscription
+   * topics in a single request. Only the topics included in the request body are
+   * created or updated; any existing overrides for topics not listed are left
+   * untouched.
+   *
+   * Structural validation of the request body fails fast with a single `400`. Beyond
+   * that, each topic is processed independently (partial-success, not
+   * all-or-nothing): valid topics are written and returned in `items`, while topics
+   * that cannot be applied are collected in `errors` with a per-topic `reason` (for
+   * example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom
+   * routing request that is not available on the workspace's plan, or a write
+   * failure). The request therefore returns `200` with both lists whenever the body
+   * is structurally valid.
+   *
+   * Every `topic_id` in the response — in both `items` and `errors` — is returned in
+   * Courier's canonical topic id form, regardless of the form supplied in the
+   * request.
+   *
+   * @example
+   * ```ts
+   * const response = await client.users.preferences.bulkUpdate(
+   *   'user_id',
+   *   {
+   *     topics: [
+   *       {
+   *         topic_id: '74Q4QGFBEX481DP6JRPMV751H4XT',
+   *         status: 'OPTED_IN',
+   *         has_custom_routing: true,
+   *         custom_routing: ['inbox', 'email'],
+   *       },
+   *       {
+   *         topic_id: '5Q4QGFBEX481DP6JRPMV751H4YU',
+   *         status: 'OPTED_OUT',
+   *       },
+   *     ],
+   *   },
+   * );
+   * ```
+   */
+  bulkUpdate(
+    userID: string,
+    params: PreferenceBulkUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<PreferenceBulkUpdateResponse> {
+    const { tenant_id, ...body } = params;
+    return this._client.post(path`/users/${userID}/preferences`, { query: { tenant_id }, body, ...options });
+  }
+
+  /**
+   * Remove a user's preferences for a specific subscription topic, resetting the
+   * topic to its effective default. This operation is idempotent: deleting a
+   * preference that does not exist succeeds with no error.
+   *
+   * @example
+   * ```ts
+   * await client.users.preferences.deleteTopic('topic_id', {
+   *   user_id: 'user_id',
+   * });
+   * ```
+   */
+  deleteTopic(
+    topicID: string,
+    params: PreferenceDeleteTopicParams,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { user_id, tenant_id } = params;
+    return this._client.delete(path`/users/${user_id}/preferences/${topicID}`, {
+      query: { tenant_id },
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
   /**
    * Fetch user preferences for a specific subscription topic.
    *
@@ -78,6 +198,23 @@ export class Preferences extends APIResource {
   }
 }
 
+/**
+ * A single topic override echoed in a bulk preference response.
+ */
+export interface BulkPreferenceTopic {
+  custom_routing: Array<Shared.ChannelClassification>;
+
+  has_custom_routing: boolean;
+
+  /**
+   * The applied subscription status. Echoes the requested value, so it is always
+   * OPTED_IN or OPTED_OUT.
+   */
+  status: 'OPTED_IN' | 'OPTED_OUT';
+
+  topic_id: string;
+}
+
 export interface TopicPreference {
   default_status: Shared.PreferenceStatus;
 
@@ -107,6 +244,44 @@ export interface PreferenceRetrieveResponse {
   paging: Shared.Paging;
 }
 
+export interface PreferenceBulkReplaceResponse {
+  /**
+   * The ids of the overrides that were reset to their topic default.
+   */
+  deleted: Array<string>;
+
+  /**
+   * The complete resulting set of topic overrides for the user.
+   */
+  items: Array<BulkPreferenceTopic>;
+}
+
+export interface PreferenceBulkUpdateResponse {
+  /**
+   * The topics that could not be applied, each with a reason.
+   */
+  errors: Array<PreferenceBulkUpdateResponse.Error>;
+
+  /**
+   * The topics that were successfully created or updated.
+   */
+  items: Array<BulkPreferenceTopic>;
+}
+
+export namespace PreferenceBulkUpdateResponse {
+  /**
+   * A single topic that could not be applied in a bulk preference request.
+   */
+  export interface Error {
+    /**
+     * A human-readable explanation of why the topic could not be applied.
+     */
+    reason: string;
+
+    topic_id: string;
+  }
+}
+
 export interface PreferenceRetrieveTopicResponse {
   topic: TopicPreference;
 }
@@ -122,6 +297,94 @@ export interface PreferenceRetrieveParams {
   tenant_id?: string | null;
 }
 
+export interface PreferenceBulkReplaceParams {
+  /**
+   * Body param: The complete set of topic overrides for the user. Up to 50 topics
+   * may be provided. Any existing override not listed here is reset to its topic
+   * default; an empty array resets every existing override.
+   */
+  topics: Array<PreferenceBulkReplaceParams.Topic>;
+
+  /**
+   * Query param: Replace the preferences of a user for this specific tenant context.
+   */
+  tenant_id?: string | null;
+}
+
+export namespace PreferenceBulkReplaceParams {
+  export interface Topic {
+    /**
+     * The subscription status to apply for this topic.
+     */
+    status: 'OPTED_IN' | 'OPTED_OUT';
+
+    /**
+     * A unique identifier associated with a subscription topic.
+     */
+    topic_id: string;
+
+    /**
+     * The channels a user has chosen to receive notifications through for this topic.
+     */
+    custom_routing?: Array<Shared.ChannelClassification>;
+
+    /**
+     * Whether the recipient has chosen specific delivery channels for this topic.
+     */
+    has_custom_routing?: boolean;
+  }
+}
+
+export interface PreferenceBulkUpdateParams {
+  /**
+   * Body param: The topics to create or update. Between 1 and 50 topics may be
+   * provided in a single request.
+   */
+  topics: Array<PreferenceBulkUpdateParams.Topic>;
+
+  /**
+   * Query param: Update the preferences of a user for this specific tenant context.
+   */
+  tenant_id?: string | null;
+}
+
+export namespace PreferenceBulkUpdateParams {
+  export interface Topic {
+    /**
+     * The subscription status to apply for this topic.
+     */
+    status: 'OPTED_IN' | 'OPTED_OUT';
+
+    /**
+     * A unique identifier associated with a subscription topic.
+     */
+    topic_id: string;
+
+    /**
+     * The channels a user has chosen to receive notifications through for this topic.
+     */
+    custom_routing?: Array<Shared.ChannelClassification>;
+
+    /**
+     * Whether the recipient has chosen specific delivery channels for this topic.
+     */
+    has_custom_routing?: boolean;
+  }
+}
+
+export interface PreferenceDeleteTopicParams {
+  /**
+   * Path param: A unique identifier associated with the user whose preferences you
+   * wish to delete.
+   */
+  user_id: string;
+
+  /**
+   * Query param: Delete the preferences of a user for this specific tenant context.
+   */
+  tenant_id?: string | null;
+}
+
 export interface PreferenceRetrieveTopicParams {
   /**
    * Path param: A unique identifier associated with the user whose preferences you
@@ -168,11 +431,17 @@ export namespace PreferenceUpdateOrCreateTopicParams {
 
 export declare namespace Preferences {
   export {
+    type BulkPreferenceTopic as BulkPreferenceTopic,
     type TopicPreference as TopicPreference,
     type PreferenceRetrieveResponse as PreferenceRetrieveResponse,
+    type PreferenceBulkReplaceResponse as PreferenceBulkReplaceResponse,
+    type PreferenceBulkUpdateResponse as PreferenceBulkUpdateResponse,
     type PreferenceRetrieveTopicResponse as PreferenceRetrieveTopicResponse,
     type PreferenceUpdateOrCreateTopicResponse as PreferenceUpdateOrCreateTopicResponse,
     type PreferenceRetrieveParams as PreferenceRetrieveParams,
+    type PreferenceBulkReplaceParams as PreferenceBulkReplaceParams,
+    type PreferenceBulkUpdateParams as PreferenceBulkUpdateParams,
+    type PreferenceDeleteTopicParams as PreferenceDeleteTopicParams,
     type PreferenceRetrieveTopicParams as PreferenceRetrieveTopicParams,
     type PreferenceUpdateOrCreateTopicParams as PreferenceUpdateOrCreateTopicParams,
   };

package/src/resources/users/users.ts

@@ -3,6 +3,12 @@
 import { APIResource } from '../../core/resource';
 import * as PreferencesAPI from './preferences';
 import {
+  BulkPreferenceTopic,
+  PreferenceBulkReplaceParams,
+  PreferenceBulkReplaceResponse,
+  PreferenceBulkUpdateParams,
+  PreferenceBulkUpdateResponse,
+  PreferenceDeleteTopicParams,
   PreferenceRetrieveParams,
   PreferenceRetrieveResponse,
   PreferenceRetrieveTopicParams,
@@ -46,11 +52,17 @@ Users.Tokens = Tokens;
 export declare namespace Users {
   export {
     Preferences as Preferences,
+    type BulkPreferenceTopic as BulkPreferenceTopic,
     type TopicPreference as TopicPreference,
     type PreferenceRetrieveResponse as PreferenceRetrieveResponse,
+    type PreferenceBulkReplaceResponse as PreferenceBulkReplaceResponse,
+    type PreferenceBulkUpdateResponse as PreferenceBulkUpdateResponse,
     type PreferenceRetrieveTopicResponse as PreferenceRetrieveTopicResponse,
     type PreferenceUpdateOrCreateTopicResponse as PreferenceUpdateOrCreateTopicResponse,
     type PreferenceRetrieveParams as PreferenceRetrieveParams,
+    type PreferenceBulkReplaceParams as PreferenceBulkReplaceParams,
+    type PreferenceBulkUpdateParams as PreferenceBulkUpdateParams,
+    type PreferenceDeleteTopicParams as PreferenceDeleteTopicParams,
     type PreferenceRetrieveTopicParams as PreferenceRetrieveTopicParams,
     type PreferenceUpdateOrCreateTopicParams as PreferenceUpdateOrCreateTopicParams,
   };

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

@@ -0,0 +1,25 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Topics,
+  type TopicCreateParams,
+  type TopicRetrieveParams,
+  type TopicArchiveParams,
+  type TopicReplaceParams,
+} from './topics';
+export {
+  WorkspacePreferences,
+  type PublishPreferencesRequest,
+  type PublishPreferencesResponse,
+  type WorkspacePreferenceCreateRequest,
+  type WorkspacePreferenceGetResponse,
+  type WorkspacePreferenceListResponse,
+  type WorkspacePreferenceReplaceRequest,
+  type WorkspacePreferenceTopicCreateRequest,
+  type WorkspacePreferenceTopicGetResponse,
+  type WorkspacePreferenceTopicListResponse,
+  type WorkspacePreferenceTopicReplaceRequest,
+  type WorkspacePreferenceCreateParams,
+  type WorkspacePreferencePublishParams,
+  type WorkspacePreferenceReplaceParams,
+} from './workspace-preferences';

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

@@ -0,0 +1,229 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import * as WorkspacePreferencesAPI from './workspace-preferences';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Topics extends APIResource {
+  /**
+   * Create a subscription preference topic inside a workspace preference. Fails with
+   * 404 if the workspace preference does not exist. The topic id is generated and
+   * returned.
+   *
+   * @example
+   * ```ts
+   * const workspacePreferenceTopicGetResponse =
+   *   await client.workspacePreferences.topics.create(
+   *     'section_id',
+   *     { default_status: 'OPTED_OUT', name: 'Marketing' },
+   *   );
+   * ```
+   */
+  create(
+    sectionID: string,
+    body: TopicCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<WorkspacePreferencesAPI.WorkspacePreferenceTopicGetResponse> {
+    return this._client.post(path`/preferences/sections/${sectionID}/topics`, { body, ...options });
+  }
+
+  /**
+   * Retrieve a topic within a workspace preference. Returns 404 if the workspace
+   * preference does not exist, the topic does not exist, or the topic belongs to a
+   * different workspace preference.
+   *
+   * @example
+   * ```ts
+   * const workspacePreferenceTopicGetResponse =
+   *   await client.workspacePreferences.topics.retrieve(
+   *     'topic_id',
+   *     { section_id: 'section_id' },
+   *   );
+   * ```
+   */
+  retrieve(
+    topicID: string,
+    params: TopicRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<WorkspacePreferencesAPI.WorkspacePreferenceTopicGetResponse> {
+    const { section_id } = params;
+    return this._client.get(path`/preferences/sections/${section_id}/topics/${topicID}`, options);
+  }
+
+  /**
+   * List the topics in a workspace preference.
+   *
+   * @example
+   * ```ts
+   * const workspacePreferenceTopicListResponse =
+   *   await client.workspacePreferences.topics.list(
+   *     'section_id',
+   *   );
+   * ```
+   */
+  list(
+    sectionID: string,
+    options?: RequestOptions,
+  ): APIPromise<WorkspacePreferencesAPI.WorkspacePreferenceTopicListResponse> {
+    return this._client.get(path`/preferences/sections/${sectionID}/topics`, options);
+  }
+
+  /**
+   * Archive a topic and remove it from its workspace preference. Same 404 rules as
+   * GET.
+   *
+   * @example
+   * ```ts
+   * await client.workspacePreferences.topics.archive(
+   *   'topic_id',
+   *   { section_id: 'section_id' },
+   * );
+   * ```
+   */
+  archive(topicID: string, params: TopicArchiveParams, options?: RequestOptions): APIPromise<void> {
+    const { section_id } = params;
+    return this._client.delete(path`/preferences/sections/${section_id}/topics/${topicID}`, {
+      ...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.
+   *
+   * @example
+   * ```ts
+   * const workspacePreferenceTopicGetResponse =
+   *   await client.workspacePreferences.topics.replace(
+   *     'topic_id',
+   *     {
+   *       section_id: 'section_id',
+   *       default_status: 'OPTED_OUT',
+   *       name: 'name',
+   *     },
+   *   );
+   * ```
+   */
+  replace(
+    topicID: string,
+    params: TopicReplaceParams,
+    options?: RequestOptions,
+  ): APIPromise<WorkspacePreferencesAPI.WorkspacePreferenceTopicGetResponse> {
+    const { section_id, ...body } = params;
+    return this._client.put(path`/preferences/sections/${section_id}/topics/${topicID}`, {
+      body,
+      ...options,
+    });
+  }
+}
+
+export interface TopicCreateParams {
+  /**
+   * The default subscription status applied when a recipient has not set their own.
+   */
+  default_status: 'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED';
+
+  /**
+   * Human-readable name for the preference topic.
+   */
+  name: string;
+
+  /**
+   * Preference controls a recipient may customize for this topic. Defaults to empty
+   * if omitted.
+   */
+  allowed_preferences?: Array<'snooze' | 'channel_preferences'> | null;
+
+  /**
+   * Optional description shown under the topic on the hosted preferences page.
+   */
+  description?: string | null;
+
+  /**
+   * Whether to include a list-unsubscribe header on emails for this topic.
+   */
+  include_unsubscribe_header?: boolean | null;
+
+  /**
+   * Default channels delivered for this topic. Defaults to empty if omitted.
+   */
+  routing_options?: Array<Shared.ChannelClassification> | null;
+
+  /**
+   * Arbitrary metadata associated with the topic.
+   */
+  topic_data?: { [key: string]: unknown } | null;
+}
+
+export interface TopicRetrieveParams {
+  /**
+   * Id of the workspace preference.
+   */
+  section_id: string;
+}
+
+export interface TopicArchiveParams {
+  /**
+   * Id of the workspace preference.
+   */
+  section_id: string;
+}
+
+export interface TopicReplaceParams {
+  /**
+   * Path param: Id of the workspace preference.
+   */
+  section_id: string;
+
+  /**
+   * Body param: The default subscription status applied when a recipient has not set
+   * their own.
+   */
+  default_status: 'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED';
+
+  /**
+   * Body param: Human-readable name for the preference topic.
+   */
+  name: string;
+
+  /**
+   * Body param: Preference controls a recipient may customize. Omit to clear.
+   */
+  allowed_preferences?: Array<'snooze' | 'channel_preferences'> | null;
+
+  /**
+   * Body param: Optional description shown under the topic on the hosted preferences
+   * page. Omit to clear.
+   */
+  description?: string | null;
+
+  /**
+   * Body param: Whether to include a list-unsubscribe header on emails for this
+   * topic.
+   */
+  include_unsubscribe_header?: boolean | null;
+
+  /**
+   * Body param: Default channels delivered for this topic. Omit to clear.
+   */
+  routing_options?: Array<Shared.ChannelClassification> | null;
+
+  /**
+   * Body param: Arbitrary metadata associated with the topic. Omit to clear.
+   */
+  topic_data?: { [key: string]: unknown } | null;
+}
+
+export declare namespace Topics {
+  export {
+    type TopicCreateParams as TopicCreateParams,
+    type TopicRetrieveParams as TopicRetrieveParams,
+    type TopicArchiveParams as TopicArchiveParams,
+    type TopicReplaceParams as TopicReplaceParams,
+  };
+}