@sentdm/sentdm 0.38.0 → 0.40.0

package/src/resources/templates.ts

@@ -1,6 +1,7 @@
 // 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';
@@ -17,7 +18,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 +70,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
@@ -205,13 +232,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;
 
@@ -236,7 +290,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;
 
@@ -252,37 +307,142 @@ 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
+   * MMS-specific content — subject, text and attachments.
+   *
+   * Like Rcs, an override that cannot stand on its own: a template still needs a
+   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
+   * Rcs, it has no fallback at send time — MMS with no media is a more expensive
+   * SMS, so a template without this slot is deliberately not MMS-capable and never
+   * produces an MMS route candidate.
+   */
+  mms?: TemplateBody.Mms | null;
+
+  /**
+   * 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 namespace TemplateBody {
+  /**
+   * MMS-specific content — subject, text and attachments.
+   *
+   * Like Rcs, an override that cannot stand on its own: a template still needs a
+   * MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
+   * Rcs, it has no fallback at send time — MMS with no media is a more expensive
+   * SMS, so a template without this slot is deliberately not MMS-capable and never
+   * produces an MMS route candidate.
+   */
+  export interface Mms extends TemplatesAPI.TemplateBodyContent {
+    /**
+     * Attachments carried by every send on this template, in order. A per-send
+     * media_urls on the request replaces this list rather than adding to it, so a
+     * template can hold a default creative and a caller can still send something
+     * recipient-specific.
+     */
+    media?: Array<Mms.Media> | null;
+
+    /**
+     * MMS subject line. Optional — most handsets render it above the body, some ignore
+     * it entirely. Deliberately its own field rather than riding TemplateHeader: the
+     * header is authored once and shared across every channel, and carries Meta's
+     * 60-character cap plus its no-newline, no-emoji text rules, none of which
+     * describe an MMS subject.
+     */
+    subject?: string | null;
+  }
+
+  export namespace Mms {
+    /**
+     * One attachment on an MMS template body.
+     */
+    export interface Media {
+      /**
+       * One of MmsMediaTypes. Advisory: the carrier reads the Content-Type off the
+       * fetched object, not this field. It exists so an authoring UI can render the
+       * right preview and so a reviewer can see what was intended.
+       */
+      mediaType?: string | null;
+
+      /**
+       * Publicly fetchable https URL. The carrier's MMSC fetches this at send time, so
+       * it has to stay reachable and unauthenticated for the life of the send —
+       * including retries and a DLQ replay — which is why a presigned URL is not a valid
+       * value here.
+       */
+      url?: string;
+    }
+  }
+}
+
 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;
 }
 
@@ -301,7 +461,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;
 }
@@ -317,6 +483,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;
@@ -345,7 +524,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;
 
@@ -406,7 +594,52 @@ export interface TemplateHeader {
   template: string;
 
   /**
-   * The type of header (e.g., "text", "image", "video", "document")
+   * Request-only. The s.dm URL of the asset Meta's reviewers see —
+   * https://s.dm/s/{ID}, eight uppercase characters, uploaded to s.dm out of band.
+   * NormalizeRichHeader folds it into the synthesized media variable's Props.Sample
+   * and clears it, so it never persists and a stored definition is indistinguishable
+   * from an imported one.
+   *
+   * Stricter than the send path on purpose:
+   * TemplateUtils.ValidateMediaVariableValues accepts any absolute https URL for the
+   * per-send asset, because that one is the customer's and may live behind a signed
+   * CDN link. This one is the review sample, has to outlive every resubmission, and
+   * so must be ours. Do not "fix" one to match the other.
+   */
+  example_url?: string | null;
+
+  /**
+   * The map pin a location header drops. Meta wants none of this at creation — the
+   * component is just {"type":"header","format":"location"} — so these values exist
+   * for Sent: a preview, and the default a StaticResource header falls back to at
+   * send.
+   */
+  location?: TemplateHeader.Location | null;
+
+  /**
+   * Whether the asset registered at creation is reused when a caller omits the
+   * header's variable at send time. Default false — the caller must supply it per
+   * message, which is the behaviour every existing template has. Written only when
+   * true, so a default-valued header serializes byte-identically to one imported
+   * from Meta.
+   *
+   * Stored and validated but not yet honoured at send: that lands with the Resumable
+   * Upload work, alongside the code that lets such a template be approved in the
+   * first place.
+   */
+  static_resource?: boolean;
+
+  /**
+   * The kind of header. One of:
+   *
+   * text — up to 60 characters, at most one variable. image — png, jpg or jpeg.
+   * Needs ExampleUrl. video — mp4. Needs ExampleUrl. gif — mp4, max 3.5MB. WhatsApp
+   * renders larger files as an ordinary video. Needs ExampleUrl. document — pdf or
+   * docx; only the first page is shown as a thumbnail, so pdf is the practical
+   * choice. Needs ExampleUrl. location — a map pin, supplied through Location.
+   *
+   * Kept lowercase because MetaToTemplateConverter writes Meta's format through
+   * ToLowerInvariant() into this field on import, and the two are compared directly.
    */
   type?: string | null;
 
@@ -416,13 +649,48 @@ export interface TemplateHeader {
   variables?: Array<TemplateVariable> | null;
 }
 
+export namespace TemplateHeader {
+  /**
+   * The map pin a location header drops. Meta wants none of this at creation — the
+   * component is just {"type":"header","format":"location"} — so these values exist
+   * for Sent: a preview, and the default a StaticResource header falls back to at
+   * send.
+   */
+  export interface Location {
+    address: string;
+
+    latitude: string;
+
+    longitude: string;
+
+    name: string;
+  }
+}
+
 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;
 }
 
@@ -430,6 +698,13 @@ export namespace TemplateVariable {
   export interface Props {
     mediaType: string;
 
+    /**
+     * Example value substituted into the template when previewing it and when
+     * submitting it to Meta for review. Free text by nature, so the converter accepts
+     * a JSON number or boolean here and normalizes it — see
+     * JsonScalarToStringConverter for why — and guarantees it is always serialized
+     * back out as a JSON string.
+     */
     sample: string;
 
     url: string;