@linqapp/sdk 0.28.0 → 0.28.2

package/src/resources/messages.ts

@@ -2,6 +2,8 @@
 
 import { APIResource } from '../core/resource';
 import * as Shared from './shared';
+import * as ChatsAPI from './chats/chats';
+import * as ChatsMessagesAPI from './chats/messages';
 import { APIPromise } from '../core/api-promise';
 import { ListMessagesPagination, type ListMessagesPaginationParams, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
@@ -27,8 +29,118 @@ import { path } from '../internal/utils/path';
  * **Limitations:**
  * - A `link` part cannot be combined with other parts in the same message.
  * - Maximum URL length: 2,048 characters.
+ *
+ * ## Ephemeral Messages (Privacy Tier)
+ *
+ * For regulated or sensitive conversations, opt in to the **ephemeral messages** tier by contacting your Linq support contact. When enabled, every message on the covered phone numbers is automatically given a fixed **24-hour retention window** — after that window the platform permanently deletes the message from Linq storage. There is no per-message flag; ephemerality is applied automatically based on your configuration.
+ *
+ * You can request it at two scopes:
+ *
+ * | Scope | Effect |
+ * |---|---|
+ * | **Partner-wide** | Every outbound and inbound message on every phone number under your account is retained for 24 hours, then deleted. |
+ * | **Per phone number** | Only the specified phone numbers have their messages auto-deleted. The rest follow the standard message-retention policy. |
+ *
+ * **Behavioral differences vs the standard default:**
+ *
+ * | Aspect | Standard | Ephemeral |
+ * |---|---|---|
+ * | Retention | Retained per the standard message-retention policy | **Hard backstop: 24 hours** from when the message is created |
+ * | After expiry | Message stays retrievable | Message is permanently deleted — `GET /v3/messages/{messageId}` returns `404` and it no longer appears in `GET /v3/chats/{chatId}/messages` |
+ * | Content on expiry | N/A | Text, formatting, and attachment references are scrubbed; the message is gone, not blanked out |
+ * | Cross-partner isolation | Enforced | Enforced |
+ *
+ * **How the 24-hour window works:**
+ *
+ * - The window is fixed at **24 hours from message creation** (`created_at`) and cannot be configured per message.
+ * - It mirrors the ephemeral *attachments* 1-day backstop, so a message and any media it carries expire together.
+ * - Expiry is delivery-independent — the clock starts when the message is created, not when it is delivered or read.
+ *
+ * **What you observe:**
+ *
+ * - **No expiry timestamp is exposed.** API responses and webhook payloads do not include the deletion time. If you need it, compute `created_at + 24h` yourself.
+ * - **No deletion webhook is sent.** There is no `message.deleted` event — a message simply stops being retrievable once its window passes.
+ * - **Delivery is unaffected.** Ephemeral messages send, deliver, and fire the usual `message.sent` / `message.received` and status webhooks exactly like standard messages. Only retention changes.
+ *
+ * **When to choose ephemeral:**
+ *
+ * - You have a compliance requirement that the platform must not retain message content beyond a short window.
+ * - The conversation is high-sensitivity (PHI, financial, identity verification) and you do not want it sitting in storage long-term.
+ * - Your application is the system of record — you capture what you need from the delivery webhook in real time and do not rely on reading message history back from Linq later.
+ *
+ * **Important:** ephemeral applies in *both directions* — messages you send **and** messages received by the phone numbers in that scope. Because Linq can no longer return the message after 24 hours, persist anything you need to keep from the webhook payload at the time it is delivered.
  */
 export class Messages extends APIResource {
+  /**
+   * Send a message to one or more recipients **without supplying a `from` number**.
+   * Linq resolves both the sending line and the target chat for you, then returns
+   * exactly which line was used, which chat the message landed in, whether a new
+   * chat was created, and every resulting message id.
+   *
+   * This fuses "create chat" and "send message" behind a single message-centric
+   * resource. Provide only the recipients (`to`) and the `message`; the platform
+   * decides the rest.
+   *
+   * ## How the from-number and chat are chosen
+   *
+   * - **Reuse** — if a chat with exactly these recipients already exists and the
+   *   line it lives on is healthy, the message is sent into that chat on its
+   *   existing line (`from_selection.reason = reused_active_chat`).
+   * - **New** — if no such chat exists, a new chat is created on the best available
+   *   line (`from_selection.reason = new_best_number`).
+   * - **Failover** — if a matching chat exists but its line has been flagged, a
+   *   **new** chat is created on a fresh best line and the flagged chat is abandoned
+   *   (`from_selection.reason = failover_flagged`, `previous_chat_id` set). If you
+   *   supply `continuation_message`, that text is sent as the single message INSTEAD
+   *   of `message` (useful as a fresh-number-appropriate opener). Exactly one
+   *   message is sent either way.
+   *
+   * Recipients (`to`) are an order-independent set: a single handle is a direct
+   * chat, multiple handles a group chat.
+   *
+   * ## Differences from POST /v3/chats
+   *
+   * - The first message **may contain a link** (including for a newly created chat).
+   *   Note: sending a link as the very first message on a freshly selected line can
+   *   elevate that line's flagging risk — it is allowed, not recommended.
+   * - Voice memos are **not** supported here. To send an iMessage voice-memo bubble,
+   *   use `POST /v3/chats/{chatId}/voicememo` with a known chat id.
+   *
+   * ## Service preference, effects, decorations
+   *
+   * Set `message.preferred_service` (`iMessage` | `RCS` | `SMS`), `message.effect`,
+   * and per-part `text_decorations` exactly as on the other send endpoints.
+   *
+   * Always responds `202 Accepted` — chat creation is incidental to the send.
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.create({
+   *   message: {
+   *     parts: [
+   *       {
+   *         type: 'text',
+   *         value:
+   *           'Hi! Thanks for reaching out — how can we help?',
+   *       },
+   *     ],
+   *   },
+   *   to: ['+14155559876'],
+   * });
+   * ```
+   */
+  create(params: MessageCreateParams, options?: RequestOptions): APIPromise<MessageCreateResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/v3/messages', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Retrieve all messages in a conversation thread. Given any message ID in the
    * thread, returns the originator message and all replies in chronological order.
@@ -138,6 +250,50 @@ export class Messages extends APIResource {
   update(messageID: string, body: MessageUpdateParams, options?: RequestOptions): APIPromise<Message> {
     return this._client.patch(path`/v3/messages/${messageID}`, { body, ...options });
   }
+
+  /**
+   * Replaces a previously delivered `imessage_app` card on the recipient's screen
+   * with new content, instead of posting a new bubble (like a game move redrawing
+   * the board).
+   *
+   * The update is delivered as a **new message** with its own id and delivery
+   * lifecycle (`message.sent` / `message.delivered` / `message.failed` webhooks fire
+   * for the new id). To update the card again, reference the message id returned by
+   * this call.
+   *
+   * Constraints:
+   *
+   * - The referenced message must be an `imessage_app` card sent by you (`400`
+   *   otherwise — inbound cards cannot be updated).
+   * - The referenced card must already be delivered (`409` otherwise — retry after
+   *   the `message.delivered` webhook for it).
+   * - The app identity (`team_id`, `bundle_id`, name) is inherited from the original
+   *   card and cannot change; only `url`, `fallback_text`, and `layout` are
+   *   replaced.
+   * - iMessage-only, like all app cards.
+   * - Concurrent updates against the same card are not serialized server-side; the
+   *   last one delivered wins on the recipient's screen. Serialize updates by always
+   *   referencing the message id returned by the previous call.
+   *
+   * @example
+   * ```ts
+   * const response = await client.messages.updateAppCard(
+   *   '69a37c7d-af4f-4b5e-af42-e28e98ce873a',
+   *   {
+   *     layout: { caption: 'Score: 2 – 1' },
+   *     fallback_text: 'Score update',
+   *     url: 'https://app.example.com/card?game=7f3a&move=2',
+   *   },
+   * );
+   * ```
+   */
+  updateAppCard(
+    messageID: string,
+    body: MessageUpdateAppCardParams,
+    options?: RequestOptions,
+  ): APIPromise<MessageUpdateAppCardResponse> {
+    return this._client.post(path`/v3/messages/${messageID}/update`, { body, ...options });
+  }
 }
 
 export type MessagesListMessagesPagination = ListMessagesPagination<Message>;
@@ -255,9 +411,19 @@ export namespace Message {
 
     /**
      * Visible layout of the card. At least one of `caption`, `subcaption`,
-     * `trailing_caption`, or `trailing_subcaption` must be set, otherwise the card
-     * renders as an empty bubble. Any image on the card is drawn by the recipient's
-     * installed app extension; it cannot be supplied here.
+     * `trailing_caption`, `trailing_subcaption`, or `image_url` must be set, otherwise
+     * the card renders as an empty bubble.
+     *
+     * `image_url` displays a preview image at the top of the card. The image renders
+     * on the recipient's card whether or not they have your app installed. The small
+     * icon beside the caption is the app's own icon and is not settable here.
+     *
+     * `* Note - requires a trusted chat w/ inbound activity`
+     *
+     * `image_title` and `image_subtitle` render as text overlaid on the image (title
+     * bold, subtitle beneath it). They only appear when `image_url` is set — without
+     * an image there is nothing to overlay — so setting either without `image_url` is
+     * rejected.
      */
     layout: IMessageAppPartResponse.Layout;
 
@@ -311,9 +477,19 @@ export namespace Message {
 
     /**
      * Visible layout of the card. At least one of `caption`, `subcaption`,
-     * `trailing_caption`, or `trailing_subcaption` must be set, otherwise the card
-     * renders as an empty bubble. Any image on the card is drawn by the recipient's
-     * installed app extension; it cannot be supplied here.
+     * `trailing_caption`, `trailing_subcaption`, or `image_url` must be set, otherwise
+     * the card renders as an empty bubble.
+     *
+     * `image_url` displays a preview image at the top of the card. The image renders
+     * on the recipient's card whether or not they have your app installed. The small
+     * icon beside the caption is the app's own icon and is not settable here.
+     *
+     * `* Note - requires a trusted chat w/ inbound activity`
+     *
+     * `image_title` and `image_subtitle` render as text overlaid on the image (title
+     * bold, subtitle beneath it). They only appear when `image_url` is set — without
+     * an image there is nothing to overlay — so setting either without `image_url` is
+     * rejected.
      */
     export interface Layout {
       /**
@@ -321,6 +497,27 @@ export namespace Message {
        */
       caption?: string;
 
+      /**
+       * Text shown below `image_title`, overlaid on the card image. Requires
+       * `image_url`.
+       */
+      image_subtitle?: string;
+
+      /**
+       * Bold text overlaid on the card image. Requires `image_url` (rejected without
+       * it).
+       */
+      image_title?: string;
+
+      /**
+       * URL of an image (JPEG, PNG, HEIF, or WebP) to display as the card's preview
+       * image; an unreachable or non-image URL returns a validation error. Renders for
+       * all recipients regardless of whether they have the app. Note - requires a
+       * trusted chat w/ inbound activity. In responses, this is the re-hosted
+       * `cdn.linqapp.com` copy of the image you supplied, not your original URL.
+       */
+      image_url?: string;
+
       /**
        * Secondary label, below `caption` on the left.
        */
@@ -375,6 +572,79 @@ export interface ReplyTo {
   part_index?: number;
 }
 
+/**
+ * Result of an auto-from send. Self-describing: which line was used, which chat
+ * the message landed in, whether a new chat was created, and the resulting message
+ * id(s).
+ */
+export interface MessageCreateResponse {
+  /**
+   * The resolved chat (reused or newly created) the message landed in.
+   */
+  chat_id: string;
+
+  /**
+   * True when a new chat was created (new or failover), false on reuse.
+   */
+  created_new_chat: boolean;
+
+  /**
+   * The line (E.164) the message was actually sent from.
+   */
+  from: string;
+
+  /**
+   * Why this line/chat was chosen.
+   */
+  from_selection: MessageCreateResponse.FromSelection;
+
+  /**
+   * Participants of the resolved chat.
+   */
+  handles: Array<Shared.ChatHandle>;
+
+  /**
+   * Whether the resolved chat is a group chat.
+   */
+  is_group: boolean;
+
+  /**
+   * A message that was sent (used in CreateChat and SendMessage responses)
+   */
+  message: ChatsMessagesAPI.SentMessage;
+
+  /**
+   * Messaging service type
+   */
+  service: Shared.ServiceType;
+
+  /**
+   * Set ONLY on `failover_flagged`: the abandoned flagged chat that was NOT sent
+   * into. Null otherwise.
+   */
+  previous_chat_id?: string | null;
+}
+
+export namespace MessageCreateResponse {
+  /**
+   * Why this line/chat was chosen.
+   */
+  export interface FromSelection {
+    /**
+     * - `reused_active_chat` — reused an existing chat on its healthy line
+     * - `new_best_number` — created a new chat on the best available line
+     * - `failover_flagged` — prior chat's line was flagged; created a new chat on a
+     *   fresh line
+     */
+    reason: 'reused_active_chat' | 'new_best_number' | 'failover_flagged';
+
+    /**
+     * True only when an existing chat was reused.
+     */
+    reused_existing_chat: boolean;
+  }
+}
+
 export interface MessageAddReactionResponse {
   message?: string;
 
@@ -383,6 +653,74 @@ export interface MessageAddReactionResponse {
   trace_id?: string;
 }
 
+/**
+ * Response for sending a message to a chat
+ */
+export interface MessageUpdateAppCardResponse {
+  /**
+   * Unique identifier of the chat this message was sent to
+   */
+  chat_id: string;
+
+  /**
+   * A message that was sent (used in CreateChat and SendMessage responses)
+   */
+  message: ChatsMessagesAPI.SentMessage;
+}
+
+export interface MessageCreateParams {
+  /**
+   * Body param: Message content container. Groups all message-related fields
+   * together, separating the "what" (message content) from the "where" (routing
+   * fields like from/to).
+   */
+  message: ChatsAPI.MessageContent;
+
+  /**
+   * Body param: Recipient handles (E.164 phone numbers or email addresses). One
+   * handle is a direct chat; multiple handles a group chat. Order-independent — the
+   * set identifies the chat.
+   */
+  to: Array<string>;
+
+  /**
+   * Body param: Text-only fallback that **replaces** `message` ONLY on the failover
+   * branch — when a chat with these recipients already existed but its line was
+   * flagged, so a new chat is created on a fresh line. On that branch this text is
+   * sent as the single message instead of `message` (the recipient is on a new
+   * number, so you typically want a fresh-number-appropriate opener rather than the
+   * original content). Ignored otherwise (a healthy reuse, or genuine first
+   * contact). Carries no parts, media, or effects — exactly one message is ever
+   * sent.
+   */
+  continuation_message?: MessageCreateParams.ContinuationMessage;
+
+  /**
+   * Header param: Optional idempotency key for the send. Reuse the same key to
+   * safely retry without sending twice. May also be supplied as
+   * `message.idempotency_key`.
+   */
+  'Idempotency-Key'?: string;
+}
+
+export namespace MessageCreateParams {
+  /**
+   * Text-only fallback that **replaces** `message` ONLY on the failover branch —
+   * when a chat with these recipients already existed but its line was flagged, so a
+   * new chat is created on a fresh line. On that branch this text is sent as the
+   * single message instead of `message` (the recipient is on a new number, so you
+   * typically want a fresh-number-appropriate opener rather than the original
+   * content). Ignored otherwise (a healthy reuse, or genuine first contact). Carries
+   * no parts, media, or effects — exactly one message is ever sent.
+   */
+  export interface ContinuationMessage {
+    /**
+     * The replacement message text, sent as the single message on failover.
+     */
+    text: string;
+  }
+}
+
 export interface MessageListMessagesThreadParams extends ListMessagesPaginationParams {
   /**
    * Sort order for messages (asc = oldest first, desc = newest first)
@@ -428,15 +766,124 @@ export interface MessageUpdateParams {
   part_index?: number;
 }
 
+export interface MessageUpdateAppCardParams {
+  /**
+   * Visible layout of the card. At least one of `caption`, `subcaption`,
+   * `trailing_caption`, `trailing_subcaption`, or `image_url` must be set, otherwise
+   * the card renders as an empty bubble.
+   *
+   * `image_url` displays a preview image at the top of the card. The image renders
+   * on the recipient's card whether or not they have your app installed. The small
+   * icon beside the caption is the app's own icon and is not settable here.
+   *
+   * `* Note - requires a trusted chat w/ inbound activity`
+   *
+   * `image_title` and `image_subtitle` render as text overlaid on the image (title
+   * bold, subtitle beneath it). They only appear when `image_url` is set — without
+   * an image there is nothing to overlay — so setting either without `image_url` is
+   * rejected.
+   */
+  layout: MessageUpdateAppCardParams.Layout;
+
+  /**
+   * Text shown on surfaces that cannot render the card (notifications, lock screen).
+   * Defaults to the caption when omitted.
+   */
+  fallback_text?: string;
+
+  /**
+   * Whether the updated card renders as your app's interactive balloon for
+   * recipients who have your iMessage app installed. `true` (default) lets your
+   * installed extension draw its live view; `false` always shows the static `layout`
+   * card. Recipients without your app always see the static card regardless of this
+   * flag.
+   *
+   * Defaults to `true` when omitted — it is **not** inherited from the original
+   * card. To keep a card static across updates, re-send `interactive: false` on each
+   * update.
+   */
+  interactive?: boolean;
+
+  /**
+   * URL the recipient's app opens when they tap the updated card.
+   */
+  url?: string;
+}
+
+export namespace MessageUpdateAppCardParams {
+  /**
+   * Visible layout of the card. At least one of `caption`, `subcaption`,
+   * `trailing_caption`, `trailing_subcaption`, or `image_url` must be set, otherwise
+   * the card renders as an empty bubble.
+   *
+   * `image_url` displays a preview image at the top of the card. The image renders
+   * on the recipient's card whether or not they have your app installed. The small
+   * icon beside the caption is the app's own icon and is not settable here.
+   *
+   * `* Note - requires a trusted chat w/ inbound activity`
+   *
+   * `image_title` and `image_subtitle` render as text overlaid on the image (title
+   * bold, subtitle beneath it). They only appear when `image_url` is set — without
+   * an image there is nothing to overlay — so setting either without `image_url` is
+   * rejected.
+   */
+  export interface Layout {
+    /**
+     * Primary label, top-left and bold.
+     */
+    caption?: string;
+
+    /**
+     * Text shown below `image_title`, overlaid on the card image. Requires
+     * `image_url`.
+     */
+    image_subtitle?: string;
+
+    /**
+     * Bold text overlaid on the card image. Requires `image_url` (rejected without
+     * it).
+     */
+    image_title?: string;
+
+    /**
+     * URL of an image (JPEG, PNG, HEIF, or WebP) to display as the card's preview
+     * image; an unreachable or non-image URL returns a validation error. Renders for
+     * all recipients regardless of whether they have the app. Note - requires a
+     * trusted chat w/ inbound activity. In responses, this is the re-hosted
+     * `cdn.linqapp.com` copy of the image you supplied, not your original URL.
+     */
+    image_url?: string;
+
+    /**
+     * Secondary label, below `caption` on the left.
+     */
+    subcaption?: string;
+
+    /**
+     * Label shown top-right.
+     */
+    trailing_caption?: string;
+
+    /**
+     * Label shown below `trailing_caption`, on the right.
+     */
+    trailing_subcaption?: string;
+  }
+}
+
 export declare namespace Messages {
   export {
     type Message as Message,
     type MessageEffect as MessageEffect,
     type ReplyTo as ReplyTo,
+    type MessageCreateResponse as MessageCreateResponse,
     type MessageAddReactionResponse as MessageAddReactionResponse,
+    type MessageUpdateAppCardResponse as MessageUpdateAppCardResponse,
     type MessagesListMessagesPagination as MessagesListMessagesPagination,
+    type MessageCreateParams as MessageCreateParams,
     type MessageListMessagesThreadParams as MessageListMessagesThreadParams,
     type MessageAddReactionParams as MessageAddReactionParams,
     type MessageUpdateParams as MessageUpdateParams,
+    type MessageUpdateAppCardParams as MessageUpdateAppCardParams,
   };
 }