@sentdm/sentdm 0.7.2 → 0.14.0

package/src/resources/messages.ts

@@ -1,283 +1,442 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
+import * as WebhooksAPI from './webhooks';
 import { APIPromise } from '../core/api-promise';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Send and track SMS and WhatsApp messages
+ */
 export class Messages extends APIResource {
   /**
-   * Retrieves comprehensive details about a specific message using the message ID.
-   * Returns complete message data including delivery status, channel information,
-   * template details, contact information, and pricing. The customer ID is extracted
-   * from the authentication token to ensure the message belongs to the authenticated
-   * customer.
+   * Retrieves the activity log for a specific message. Activities track the message
+   * lifecycle including acceptance, processing, sending, delivery, and any errors.
    *
    * @example
    * ```ts
-   * const message = await client.messages.retrieve(
-   *   '7ba7b820-9dad-11d1-80b4-00c04fd430c8',
+   * const response = await client.messages.retrieveActivities(
+   *   '8ba7b830-9dad-11d1-80b4-00c04fd430c8',
    * );
    * ```
    */
-  retrieve(id: string, options?: RequestOptions): APIPromise<MessageRetrieveResponse> {
-    return this._client.get(path`/v2/messages/${id}`, options);
-  }
-
-  /**
-   * Sends a message to a phone number using the default template. This endpoint is
-   * rate limited to 5 messages per customer per day. The customer ID is extracted
-   * from the authentication token.
-   *
-   * @example
-   * ```ts
-   * await client.messages.sendQuickMessage({
-   *   customMessage: 'Hello, this is a test message!',
-   *   phoneNumber: '+1234567890',
-   * });
-   * ```
-   */
-  sendQuickMessage(body: MessageSendQuickMessageParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.post('/v2/messages/quick-message', {
-      body,
+  retrieveActivities(
+    id: string,
+    params: MessageRetrieveActivitiesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<MessageRetrieveActivitiesResponse> {
+    const { 'x-profile-id': xProfileID } = params ?? {};
+    return this._client.get(path`/v3/messages/${id}/activities`, {
       ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+      headers: buildHeaders([
+        { ...(xProfileID != null ? { 'x-profile-id': xProfileID } : undefined) },
+        options?.headers,
+      ]),
     });
   }
 
   /**
-   * Sends a message to a specific contact using a template. The message can be sent
-   * via SMS or WhatsApp depending on the contact's capabilities. Optionally specify
-   * a webhook URL to receive delivery status updates. The customer ID is extracted
-   * from the authentication token.
+   * Retrieves the current status and details of a message by ID. Includes delivery
+   * status, timestamps, and error information if applicable.
    *
    * @example
    * ```ts
-   * await client.messages.sendToContact({
-   *   contactId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
-   *   templateId: '7ba7b820-9dad-11d1-80b4-00c04fd430c8',
-   * });
+   * const response = await client.messages.retrieveStatus(
+   *   '8ba7b830-9dad-11d1-80b4-00c04fd430c8',
+   * );
    * ```
    */
-  sendToContact(body: MessageSendToContactParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.post('/v2/messages/contact', {
-      body,
+  retrieveStatus(
+    id: string,
+    params: MessageRetrieveStatusParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<MessageRetrieveStatusResponse> {
+    const { 'x-profile-id': xProfileID } = params ?? {};
+    return this._client.get(path`/v3/messages/${id}`, {
       ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+      headers: buildHeaders([
+        { ...(xProfileID != null ? { 'x-profile-id': xProfileID } : undefined) },
+        options?.headers,
+      ]),
     });
   }
 
   /**
-   * Sends a message to a phone number using a template. The phone number doesn't
-   * need to be a pre-existing contact. The message can be sent via SMS or WhatsApp.
-   * Optionally specify a webhook URL to receive delivery status updates. The
-   * customer ID is extracted from the authentication token.
+   * Sends a message to one or more recipients using a template. Supports
+   * multi-channel broadcast — when multiple channels are specified (e.g. ["sms",
+   * "whatsapp"]), a separate message is created for each (recipient, channel) pair.
+   * Returns immediately with per-recipient message IDs for async tracking via
+   * webhooks or the GET /messages/{id} endpoint.
    *
    * @example
    * ```ts
-   * await client.messages.sendToPhone({
-   *   phoneNumber: '+1234567890',
-   *   templateId: '7ba7b820-9dad-11d1-80b4-00c04fd430c8',
-   * });
+   * const response = await client.messages.send();
    * ```
    */
-  sendToPhone(body: MessageSendToPhoneParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.post('/v2/messages/phone', {
+  send(params: MessageSendParams, options?: RequestOptions): APIPromise<MessageSendResponse> {
+    const { 'Idempotency-Key': idempotencyKey, 'x-profile-id': xProfileID, ...body } = params;
+    return this._client.post('/v3/messages', {
       body,
       ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+      headers: buildHeaders([
+        {
+          ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined),
+          ...(xProfileID != null ? { 'x-profile-id': xProfileID } : undefined),
+        },
+        options?.headers,
+      ]),
     });
   }
 }
 
 /**
- * Represents a sent message with comprehensive delivery and template information
- * (v2)
+ * Standard API response envelope for all v3 endpoints
  */
-export interface MessageRetrieveResponse {
+export interface MessageRetrieveActivitiesResponse {
   /**
-   * The unique identifier of the message
+   * Response for GET /messages/{id}/activities
    */
-  id?: string;
+  data?: MessageRetrieveActivitiesResponse.Data | null;
 
   /**
-   * The messaging channel used (e.g., SMS, WhatsApp)
+   * Error information
    */
-  channel?: string;
+  error?: WebhooksAPI.ErrorDetail | null;
 
   /**
-   * The unique identifier of the contact who received the message
+   * Request and response metadata
    */
-  contactId?: string;
+  meta?: WebhooksAPI.APIMeta;
 
   /**
-   * The final price charged for sending this message
+   * Indicates whether the request was successful
    */
-  correctedPrice?: number | null;
+  success?: boolean;
+}
 
+export namespace MessageRetrieveActivitiesResponse {
   /**
-   * The date and time when the message was created
+   * Response for GET /messages/{id}/activities
    */
-  createdAt?: string;
+  export interface Data {
+    /**
+     * List of activity events ordered by most recent first
+     */
+    activities?: Array<Data.Activity>;
 
-  /**
-   * The unique identifier of the customer who sent the message
-   */
-  customerId?: string;
+    /**
+     * The message ID these activities belong to
+     */
+    message_id?: string;
+  }
 
+  export namespace Data {
+    /**
+     * A single message activity event for v3 API
+     */
+    export interface Activity {
+      /**
+       * Active contact markup applied on top of the channel cost, formatted to 4 decimal
+       * places.
+       */
+      active_contact_price?: string | null;
+
+      /**
+       * Human-readable description of the activity
+       */
+      description?: string;
+
+      /**
+       * Channel cost for this activity (e.g., SMS/WhatsApp provider cost), formatted to
+       * 4 decimal places.
+       */
+      price?: string | null;
+
+      /**
+       * Activity status (e.g., ACCEPTED, PROCESSED, SENT, DELIVERED, FAILED)
+       */
+      status?: string;
+
+      /**
+       * When this activity occurred
+       */
+      timestamp?: string;
+    }
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface MessageRetrieveStatusResponse {
   /**
-   * A chronological list of status change events for this message. Each event
-   * includes a status and timestamp, following industry standards (Twilio, SendGrid,
-   * Mailgun). Events are ordered chronologically from oldest to newest.
+   * Message response for v3 API — same shape as v2 with snake_case JSON conventions
    */
-  events?: Array<MessageRetrieveResponse.Event> | null;
+  data?: MessageRetrieveStatusResponse.Data | null;
 
   /**
-   * The message body content with variables substituted
+   * Error information
    */
-  messageBody?: MessageRetrieveResponse.MessageBody | null;
+  error?: WebhooksAPI.ErrorDetail | null;
 
   /**
-   * The phone number of the recipient (E.164 format)
+   * Request and response metadata
    */
-  phoneNumber?: string;
+  meta?: WebhooksAPI.APIMeta;
 
   /**
-   * The phone number in international format
+   * Indicates whether the request was successful
    */
-  phoneNumberInternational?: string;
+  success?: boolean;
+}
 
+export namespace MessageRetrieveStatusResponse {
   /**
-   * The region code of the phone number (e.g., US, GB, DE)
+   * Message response for v3 API — same shape as v2 with snake_case JSON conventions
    */
-  regionCode?: string;
+  export interface Data {
+    id?: string;
+
+    active_contact_price?: number | null;
+
+    channel?: string;
+
+    contact_id?: string;
+
+    created_at?: string;
+
+    customer_id?: string;
+
+    events?: Array<Data.Event> | null;
+
+    /**
+     * Structured message body format for database storage. Preserves channel-specific
+     * components (header, body, footer, buttons).
+     */
+    message_body?: Data.MessageBody | null;
+
+    phone?: string;
+
+    phone_international?: string;
+
+    price?: number | null;
+
+    region_code?: string;
+
+    status?: string;
+
+    template_category?: string;
+
+    template_id?: string | null;
+
+    template_name?: string;
+  }
 
+  export namespace Data {
+    /**
+     * Represents a status change event in a message's lifecycle (v3)
+     */
+    export interface Event {
+      description?: string | null;
+
+      status?: string;
+
+      timestamp?: string;
+    }
+
+    /**
+     * Structured message body format for database storage. Preserves channel-specific
+     * components (header, body, footer, buttons).
+     */
+    export interface MessageBody {
+      buttons?: Array<MessageBody.Button> | null;
+
+      content?: string;
+
+      footer?: string | null;
+
+      header?: string | null;
+    }
+
+    export namespace MessageBody {
+      export interface Button {
+        type?: string;
+
+        value?: string;
+      }
+    }
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface MessageSendResponse {
   /**
-   * The delivery status of the message (e.g., sent, delivered, failed, read)
+   * Response for the multi-recipient send message endpoint
    */
-  status?: string;
+  data?: MessageSendResponse.Data | null;
 
   /**
-   * The category of the template (e.g., MARKETING, UTILITY, AUTHENTICATION)
+   * Error information
    */
-  templateCategory?: string;
+  error?: WebhooksAPI.ErrorDetail | null;
 
   /**
-   * The unique identifier of the template used for this message (null if no template
-   * was used)
+   * Request and response metadata
    */
-  templateId?: string | null;
+  meta?: WebhooksAPI.APIMeta;
 
   /**
-   * The display name of the template
+   * Indicates whether the request was successful
    */
-  templateName?: string;
+  success?: boolean;
 }
 
-export namespace MessageRetrieveResponse {
+export namespace MessageSendResponse {
   /**
-   * Represents a status change event in a message's lifecycle Follows industry
-   * standards (Twilio, SendGrid, Mailgun pattern)
+   * Response for the multi-recipient send message endpoint
    */
-  export interface Event {
+  export interface Data {
     /**
-     * Optional human-readable description of the event Useful for error messages or
-     * additional context
+     * Resolved template body text
      */
-    description?: string | null;
+    body?: string | null;
 
     /**
-     * The status of the message at this point in time Examples: "queued", "sent",
-     * "delivered", "read", "failed"
+     * Per-recipient message results
      */
-    status?: string;
+    recipients?: Array<Data.Recipient>;
 
     /**
-     * When this status change occurred (ISO 8601 format)
+     * Overall request status (e.g. "accepted")
      */
-    timestamp?: string;
-  }
-
-  /**
-   * The message body content with variables substituted
-   */
-  export interface MessageBody {
-    buttons?: Array<MessageBody.Button> | null;
-
-    content?: string;
+    status?: string;
 
-    footer?: string | null;
+    /**
+     * Template ID that was used
+     */
+    template_id?: string;
 
-    header?: string | null;
+    /**
+     * Template display name
+     */
+    template_name?: string;
   }
 
-  export namespace MessageBody {
-    export interface Button {
-      type?: string;
-
-      value?: string;
+  export namespace Data {
+    /**
+     * Per-recipient result in the send message response
+     */
+    export interface Recipient {
+      /**
+       * Channel this message will be sent on (e.g. "sms", "whatsapp"), or null for
+       * auto-detect
+       */
+      channel?: string | null;
+
+      /**
+       * Unique message identifier for tracking this recipient's message
+       */
+      message_id?: string;
+
+      /**
+       * Phone number in E.164 format
+       */
+      to?: string;
     }
   }
 }
 
-export interface MessageSendQuickMessageParams {
+export interface MessageRetrieveActivitiesParams {
   /**
-   * The custom message content to include in the template
+   * Profile UUID to scope the request to a child profile. Only organization API keys
+   * can use this header. The profile must belong to the calling organization.
    */
-  customMessage: string;
+  'x-profile-id'?: string;
+}
 
+export interface MessageRetrieveStatusParams {
   /**
-   * The phone number to send the message to, in international format (e.g.,
-   * +1234567890)
+   * Profile UUID to scope the request to a child profile. Only organization API keys
+   * can use this header. The profile must belong to the calling organization.
    */
-  phoneNumber: string;
+  'x-profile-id'?: string;
 }
 
-export interface MessageSendToContactParams {
+export interface MessageSendParams {
   /**
-   * The unique identifier of the contact to send the message to
+   * Body param: Channels to broadcast on, e.g. ["whatsapp", "sms"]. Each channel
+   * produces a separate message per recipient. "sent" = auto-detect, "rcs" =
+   * reserved (skipped). Defaults to ["sent"] (auto-detect) if omitted.
    */
-  contactId: string;
+  channel?: Array<string> | null;
 
   /**
-   * The unique identifier of the template to use for the message
+   * Body param: Sandbox flag - when true, the operation is simulated without side
+   * effects Useful for testing integrations without actual execution
    */
-  templateId: string;
+  sandbox?: boolean;
 
   /**
-   * Optional key-value pairs of template variables to replace in the template body.
-   * For example, if your template contains "Hello {{name}}", you would provide {
-   * "name": "John Doe" }
+   * Body param: SDK-style template reference: resolve by ID or by name, with
+   * optional parameters.
    */
-  templateVariables?: { [key: string]: string } | null;
-}
+  template?: MessageSendParams.Template;
+
+  /**
+   * Body param: List of recipient phone numbers in E.164 format (multi-recipient
+   * fan-out)
+   */
+  to?: Array<string>;
 
-export interface MessageSendToPhoneParams {
   /**
-   * The phone number to send the message to, in international format (e.g.,
-   * +1234567890)
+   * Header param: Unique key to ensure idempotent request processing. Must be 1-255
+   * alphanumeric characters, hyphens, or underscores. Responses are cached for 24
+   * hours per key per customer.
    */
-  phoneNumber: string;
+  'Idempotency-Key'?: string;
 
   /**
-   * The unique identifier of the template to use for the message
+   * Header param: Profile UUID to scope the request to a child profile. Only
+   * organization API keys can use this header. The profile must belong to the
+   * calling organization.
    */
-  templateId: string;
+  'x-profile-id'?: string;
+}
 
+export namespace MessageSendParams {
   /**
-   * Optional key-value pairs of template variables to replace in the template body.
-   * For example, if your template contains "Hello {{name}}", you would provide {
-   * "name": "John Doe" }
+   * SDK-style template reference: resolve by ID or by name, with optional
+   * parameters.
    */
-  templateVariables?: { [key: string]: string } | null;
+  export interface Template {
+    /**
+     * Template ID (mutually exclusive with name)
+     */
+    id?: string | null;
+
+    /**
+     * Template name (mutually exclusive with id)
+     */
+    name?: string | null;
+
+    /**
+     * Template variable parameters for personalization
+     */
+    parameters?: { [key: string]: string } | null;
+  }
 }
 
 export declare namespace Messages {
   export {
-    type MessageRetrieveResponse as MessageRetrieveResponse,
-    type MessageSendQuickMessageParams as MessageSendQuickMessageParams,
-    type MessageSendToContactParams as MessageSendToContactParams,
-    type MessageSendToPhoneParams as MessageSendToPhoneParams,
+    type MessageRetrieveActivitiesResponse as MessageRetrieveActivitiesResponse,
+    type MessageRetrieveStatusResponse as MessageRetrieveStatusResponse,
+    type MessageSendResponse as MessageSendResponse,
+    type MessageRetrieveActivitiesParams as MessageRetrieveActivitiesParams,
+    type MessageRetrieveStatusParams as MessageRetrieveStatusParams,
+    type MessageSendParams as MessageSendParams,
   };
 }