@sentdm/sentdm 0.37.0 → 0.39.0

package/src/resources/index.ts

@@ -6,13 +6,13 @@ export {
   type APIResponseOfContactMessageSummary,
   type ContactMessageSummary,
   type ContactResponse,
-  type ContactListResponse,
   type ContactCreateParams,
   type ContactRetrieveParams,
   type ContactUpdateParams,
   type ContactListParams,
   type ContactDeleteParams,
   type ContactRetrieveMessageSummaryParams,
+  type ContactResponsesContactsPage,
 } from './contacts';
 export {
   Conversations,
@@ -20,6 +20,7 @@ export {
   type ConversationMessagesList,
   type ConversationListParams,
   type ConversationListMessagesParams,
+  type ConversationMessagesListMessagesConversationsPage,
 } from './conversations';
 export { Me, type ProfileSettings, type MeRetrieveResponse, type MeRetrieveParams } from './me';
 export {
@@ -67,12 +68,12 @@ export {
   type TemplateFooter,
   type TemplateHeader,
   type TemplateVariable,
-  type TemplateListResponse,
   type TemplateCreateParams,
   type TemplateRetrieveParams,
   type TemplateUpdateParams,
   type TemplateListParams,
   type TemplateDeleteParams,
+  type TemplatesTemplatesPage,
 } from './templates';
 export {
   Users,
@@ -89,6 +90,10 @@ export {
   Webhooks,
   type APIMeta,
   type APIResponseWebhook,
+  type ChannelEvent,
+  type ChannelEventPayload,
+  type ContactEvent,
+  type ContactEventPayload,
   type ErrorDetail,
   type InboundMessageEvent,
   type InboundMessageEventPayload,
@@ -100,7 +105,6 @@ export {
   type TemplateEventPayload,
   type WebhookEventType,
   type WebhookResponse,
-  type WebhookListResponse,
   type WebhookListEventTypesResponse,
   type WebhookListEventsResponse,
   type WebhookRotateSecretResponse,
@@ -115,4 +119,6 @@ export {
   type WebhookRotateSecretParams,
   type WebhookTestParams,
   type WebhookToggleStatusParams,
+  type WebhookResponsesWebhooksPage,
+  type WebhookListEventsResponsesWebhookEventsPage,
 } from './webhooks';

package/src/resources/templates.ts

@@ -1,9 +1,9 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
-import * as TemplatesAPI from './templates';
 import * as WebhooksAPI from './webhooks';
 import { APIPromise } from '../core/api-promise';
+import { PagePromise, TemplatesPage, type TemplatesPageParams } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
@@ -17,7 +17,9 @@ export class Templates extends APIResource {
   /**
    * Creates a new message template with header, body, footer, and buttons. The
    * template can be submitted for review immediately or saved as draft for later
-   * submission.
+   * submission. There is no `name` field on create — the display name is derived
+   * from the template's content and can be changed afterwards with
+   * `PUT /v3/templates/{id}`.
    *
    * @example
    * ```ts
@@ -67,7 +69,31 @@ export class Templates extends APIResource {
 
   /**
    * Updates an existing template's name, category, language, definition, or submits
-   * it for review.
+   * it for review. While the template is in review (status PENDING, or any channel
+   * awaiting a verdict) its definition, category and language are frozen and a
+   * resubmission is refused — those requests answer 409 CONFLICT_006. The display
+   * name stays editable throughout.
+   *
+   * `definition`, `category` and `language` are editable only from status DRAFT,
+   * REJECTED or APPROVED. An edit to any of them on a template in another state
+   * (PAUSED, DISABLED or REVOKED) is refused with 400 VALIDATION_001 and the detail
+   * "Template (except display name) cannot be updated unless it is in draft or
+   * rejected status"; `name` stays editable in every state. `submit_for_review` on a
+   * PAUSED, DISABLED or REVOKED template is accepted and answers 200, but opens no
+   * review and does not move the status — only the reviewer can reinstate it.
+   *
+   * Editing an APPROVED template is a live edit: the new content is stored
+   * immediately, and sending `submit_for_review: true` re-opens review, which
+   * returns the affected channels to PENDING so they stop sending until they are
+   * approved again. The previously approved content is never sent during re-review.
+   * Watch the per-channel `templates` webhook events rather than assuming the
+   * template-level status.
+   *
+   * Templates provisioned by Sent (light-onboarding templates, whose names carry the
+   * reserved `sent_` prefix) are read-only: every field is refused with 400
+   * VALIDATION*001 and the detail "This template is read-only. Only 'submit for
+   * review' is allowed.", and only `submit_for_review` is accepted. A `name`
+   * starting with `sent*` is refused for the same reason — the prefix is reserved.
    *
    * @example
    * ```ts
@@ -101,15 +127,18 @@ export class Templates extends APIResource {
    *
    * @example
    * ```ts
-   * const templates = await client.templates.list({
-   *   page: 0,
-   *   page_size: 0,
-   * });
+   * // Automatically fetches more pages as needed.
+   * for await (const template of client.templates.list()) {
+   *   // ...
+   * }
    * ```
    */
-  list(params: TemplateListParams, options?: RequestOptions): APIPromise<TemplateListResponse> {
-    const { 'x-profile-id': xProfileID, ...query } = params;
-    return this._client.get('/v3/templates', {
+  list(
+    params: TemplateListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TemplatesTemplatesPage, Template> {
+    const { 'x-profile-id': xProfileID, ...query } = params ?? {};
+    return this._client.getAPIList('/v3/templates', TemplatesPage<Template>, {
       query,
       ...options,
       headers: buildHeaders([
@@ -143,6 +172,8 @@ export class Templates extends APIResource {
   }
 }
 
+export type TemplatesTemplatesPage = TemplatesPage<Template>;
+
 /**
  * Standard API response envelope for all v3 endpoints
  */
@@ -200,13 +231,40 @@ export interface Template {
    */
   id?: string;
 
+  /**
+   * Which consent keyword this template answers, when it is one of Sent's
+   * auto-replies: OPT_IN, OPT_OUT, HELP, or OTHER for a customer-defined keyword.
+   * Null for an ordinary template, and omitted from the response, so its presence is
+   * the answer to "is this an auto-reply".
+   *
+   * Deliberately not required, unlike CustomerId, even though the same "no single
+   * mapper" argument applies: NJsonSchema publishes a C# required member in the
+   * schema's required array, so the contract would have advertised a field this
+   * response omits for every ordinary template, and a generated client could refuse
+   * the common case. A compile-time guard is not worth a wrong published contract.
+   * Every mapping site sets it explicitly, and TemplateResponseSchemaTests pins the
+   * field as optional so it cannot be reintroduced.
+   */
+  auto_reply_action?: string | null;
+
   /**
    * Template category: MARKETING, UTILITY, AUTHENTICATION
    */
   category?: string;
 
   /**
-   * Supported channels: sms, whatsapp
+   * The channels this template's definition can render on, in canonical order: sms,
+   * whatsapp, rcs.
+   *
+   * Derived from the definition's body, mirroring each channel's send-time fallback
+   * chain, so a channel is listed only when a real body would be produced for it:
+   * SMS reads sms ?? multiChannel, WhatsApp reads whatsapp ?? multiChannel, and RCS
+   * reads rcs ?? multiChannel ?? sms. A multiChannel body therefore reports all
+   * three, and the extra SMS fallback on RCS is why an sms/whatsapp pair reports RCS
+   * too.
+   *
+   * This says what the content can render on, not what may be sent: sending also
+   * needs the template approved for that channel.
    */
   channels?: Array<string> | null;
 
@@ -231,7 +289,8 @@ export interface Template {
   name?: string;
 
   /**
-   * Template status: APPROVED, PENDING, REJECTED
+   * Template status: DRAFT, PENDING, APPROVED, REJECTED. A template created with
+   * submit_for_review: false starts as DRAFT and stays there until it is submitted.
    */
   status?: string;
 
@@ -247,37 +306,79 @@ export interface Template {
 }
 
 /**
- * Body section of a message template with channel-specific content
+ * Body section of a message template.
+ *
+ * A body picks one of two authoring strategies, and mixing them is refused
+ * (TemplateDefinitionValidator.HaveValidChannelConfiguration): a shared
+ * multiChannel body on its own, or an explicit sms + whatsapp pair, both present.
+ *
+ * multiChannel together with sms or whatsapp is rejected, and so is sms or
+ * whatsapp on its own — every template is expected to be deliverable on every
+ * channel. rcs is the one true override: it may accompany either strategy to vary
+ * the copy, but cannot stand alone.
  */
 export interface TemplateBody {
   /**
-   * Content that will be used for all channels (SMS and WhatsApp) unless
-   * channel-specific content is provided
+   * The shared body, used for every channel. One half of the choice described above.
    */
   multiChannel?: TemplateBodyContent | null;
 
   /**
-   * RCS-specific content that overrides multi-channel content for RCS messages
+   * RCS-specific copy that overrides the chosen strategy for RCS only. The one true
+   * override: optional on top of either strategy, but it cannot be the only body
+   * present. Its length cap is the higher one described on Template.
    */
   rcs?: TemplateBodyContent | null;
 
   /**
-   * SMS-specific content that overrides multi-channel content for SMS messages
+   * The SMS body. It does not override multiChannel, it replaces it.
    */
   sms?: TemplateBodyContent | null;
 
   /**
-   * WhatsApp-specific content that overrides multi-channel content for WhatsApp
-   * messages
+   * The WhatsApp body. It does not override multiChannel, it replaces it.
    */
   whatsapp?: TemplateBodyContent | null;
 }
 
 export interface TemplateBodyContent {
+  /**
+   * The body copy, with variables written as {{index:variable}}.
+   *
+   * Length cap depends on which channel this body belongs to:
+   * TemplateContentLimits.MaxBodyLength (1024) for multiChannel, sms and whatsapp —
+   * Meta's BODY limit, which a multiChannel body may be delivered under — and
+   * TemplateContentLimits.MaxRcsBodyLength (3072) for an rcs body, which never
+   * reaches Meta. The maxLength advertised on this schema is the 1024 one, because
+   * all four channel bodies share this single schema — an rcs body between the two
+   * is accepted.
+   *
+   * Meta requires every variable to carry surrounding context, so a body is refused
+   * unless it also satisfies all of the following (enforced by
+   * TemplateDefinitionValidator): At least one letter before the first variable and
+   * after the last — trailing punctuation such as "... {{1:variable}}." does not
+   * count. At least (2 × variable count) + 1 words once the placeholders are
+   * removed. No two variables adjacent with only whitespace between them. No leading
+   * or trailing newline, no more than two consecutive line breaks, and no more than
+   * four consecutive spaces.
+   *
+   * Example: "Hello {{0:variable}}! Welcome to {{1:variable}}. We are glad to have
+   * you on board." — two variables, so at least five words are required, and the
+   * copy after the final variable contains letters.
+   */
   template: string;
 
+  /**
+   * The type of body content — send "text". It is dropped from the stored definition
+   * when null, so a body posted without it is saved with no type key at all and the
+   * template editor has nothing to render the block from.
+   */
   type?: string | null;
 
+  /**
+   * The variables referenced by the body copy, one entry per {{index:variable}}
+   * placeholder.
+   */
   variables?: Array<TemplateVariable> | null;
 }
 
@@ -296,7 +397,13 @@ export interface TemplateButton {
   type: string;
 
   /**
-   * The unique identifier of the button (1-based index)
+   * The button's identifier (1-based index), unique within the template.
+   *
+   * Omitting it is only safe for a template holding a single button. The field is a
+   * non-nullable int, so every button that leaves it out defaults to 0, and two such
+   * buttons are refused by the unique-id rule ("Button IDs must be unique"). Number
+   * them from 1 in the order they should appear — order matters on RCS, where only
+   * the first four buttons render.
    */
   id?: number;
 }
@@ -312,6 +419,19 @@ export interface TemplateButtonProps {
 
   quickReplyType: string;
 
+  /**
+   * The button's label. Required for every button type, and capped at
+   * TemplateContentLimits.MaxButtonTextLength (25) characters.
+   *
+   * Meta accepts only static text here, so a label is refused when it contains a
+   * {{...}} variable placeholder, a newline, an emoji, or WhatsApp formatting markup
+   * (\*, \_, ~) — enforced by ApplyButtonLabelContentRules in
+   * TemplateButtonValidator. Meta reports all four as one error: "Buttons can't have
+   * any variables, newlines, emojis, or formatting characters."
+   *
+   * AUTHENTICATION OTP buttons are the exception: Meta auto-localizes their label
+   * from the template language, and the converter drops whatever text was sent.
+   */
   text: string;
 
   url: string;
@@ -340,7 +460,16 @@ export interface TemplateButtonProps {
  */
 export interface TemplateDefinition {
   /**
-   * Body section of a message template with channel-specific content
+   * Body section of a message template.
+   *
+   * A body picks one of two authoring strategies, and mixing them is refused
+   * (TemplateDefinitionValidator.HaveValidChannelConfiguration): a shared
+   * multiChannel body on its own, or an explicit sms + whatsapp pair, both present.
+   *
+   * multiChannel together with sms or whatsapp is rejected, and so is sms or
+   * whatsapp on its own — every template is expected to be deliverable on every
+   * channel. rcs is the one true override: it may accompany either strategy to vary
+   * the copy, but cannot stand alone.
    */
   body: TemplateBody;
 
@@ -412,12 +541,29 @@ export interface TemplateHeader {
 }
 
 export interface TemplateVariable {
+  /**
+   * The variable's name, and the key callers use for it in a send request's
+   * parameters object. Must start with a letter and hold only letters, digits and
+   * underscores.
+   */
   name: string;
 
   props: TemplateVariable.Props;
 
+  /**
+   * One of variable, link or media. Decides which Props fields are required.
+   */
   type: string;
 
+  /**
+   * The variable's index, and the number its {{index:variable}} placeholder refers
+   * to.
+   *
+   * Omitting it is only safe for a section holding a single variable. The field is a
+   * non-nullable int, so every variable that leaves it out defaults to 0, and a
+   * section with two such variables is refused by the unique-id rule ("variables
+   * must have unique IDs"). Number them from 0 in the order they appear.
+   */
   id?: number;
 }
 
@@ -439,48 +585,6 @@ export namespace TemplateVariable {
   }
 }
 
-/**
- * Standard API response envelope for all v3 endpoints
- */
-export interface TemplateListResponse {
-  /**
-   * A paginated list of templates.
-   */
-  data?: TemplateListResponse.Data | null;
-
-  /**
-   * Error information
-   */
-  error?: WebhooksAPI.ErrorDetail | null;
-
-  /**
-   * Request and response metadata
-   */
-  meta?: WebhooksAPI.APIMeta;
-
-  /**
-   * Indicates whether the request was successful
-   */
-  success?: boolean;
-}
-
-export namespace TemplateListResponse {
-  /**
-   * A paginated list of templates.
-   */
-  export interface Data {
-    /**
-     * Pagination metadata for list responses
-     */
-    pagination?: WebhooksAPI.PaginationMeta;
-
-    /**
-     * The templates on this page.
-     */
-    templates?: Array<TemplatesAPI.Template>;
-  }
-}
-
 export interface TemplateCreateParams {
   /**
    * Body param: Template category: MARKETING, UTILITY, AUTHENTICATION (optional,
@@ -589,17 +693,7 @@ export interface TemplateUpdateParams {
   'x-profile-id'?: string;
 }
 
-export interface TemplateListParams {
-  /**
-   * Query param: Page number (1-indexed)
-   */
-  page: number;
-
-  /**
-   * Query param: Number of items per page
-   */
-  page_size: number;
-
+export interface TemplateListParams extends TemplatesPageParams {
   /**
    * Query param: Optional category filter: MARKETING, UTILITY, AUTHENTICATION
    */
@@ -666,7 +760,7 @@ export declare namespace Templates {
     type TemplateFooter as TemplateFooter,
     type TemplateHeader as TemplateHeader,
     type TemplateVariable as TemplateVariable,
-    type TemplateListResponse as TemplateListResponse,
+    type TemplatesTemplatesPage as TemplatesTemplatesPage,
     type TemplateCreateParams as TemplateCreateParams,
     type TemplateRetrieveParams as TemplateRetrieveParams,
     type TemplateUpdateParams as TemplateUpdateParams,