@linqapp/sdk 0.32.0 → 0.33.0

package/src/resources/chats/chats.ts

@@ -122,46 +122,6 @@ export class Chats extends APIResource {
     return this._client.post('/v3/chats', { body, ...options });
   }
 
-  /**
-   * Retrieves a paginated list of chats for the authenticated partner.
-   *
-   * **Filtering:**
-   *
-   * - If `from` is provided, returns chats for that specific phone number
-   * - If `from` is omitted, returns chats across all phone numbers owned by the
-   *   partner
-   * - If `to` is provided, only returns chats where the specified handle is a
-   *   participant
-   *
-   * **Pagination:**
-   *
-   * - Use `limit` to control page size (default: 20, max: 100)
-   * - The response includes `next_cursor` for fetching the next page
-   * - When `next_cursor` is `null`, there are no more results to fetch
-   * - Pass the `next_cursor` value as the `cursor` parameter for the next request
-   *
-   * **Example pagination flow:**
-   *
-   * 1. First request: `GET /v3/chats?from=%2B12223334444&limit=20`
-   * 2. Response includes `next_cursor: "20"` (more results exist)
-   * 3. Next request: `GET /v3/chats?from=%2B12223334444&limit=20&cursor=20`
-   * 4. Response includes `next_cursor: null` (no more results)
-   *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const chat of client.chats.listChats()) {
-   *   // ...
-   * }
-   * ```
-   */
-  listChats(
-    query: ChatListChatsParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<ChatsListChatsPagination, Chat> {
-    return this._client.getAPIList('/v3/chats', ListChatsPagination<Chat>, { query, ...options });
-  }
-
   /**
    * Retrieve a chat by its unique identifier.
    *
@@ -195,23 +155,6 @@ export class Chats extends APIResource {
     return this._client.put(path`/v3/chats/${chatID}`, { body, ...options });
   }
 
-  /**
-   * Mark all messages in a chat as read.
-   *
-   * @example
-   * ```ts
-   * await client.chats.markAsRead(
-   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-   * );
-   * ```
-   */
-  markAsRead(chatID: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/v3/chats/${chatID}/read`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
-  }
-
   /**
    * Removes your phone number from a group chat. Once you leave, you will no longer
    * receive messages from the group and all interaction endpoints (send message,
@@ -239,21 +182,57 @@ export class Chats extends APIResource {
   }
 
   /**
-   * Share your contact information (Name and Photo Sharing) with a chat.
+   * Retrieves a paginated list of chats for the authenticated partner.
    *
-   * **Note:** A contact card must be configured before sharing. You can set up your
-   * contact card via the [Contact Card API](#tag/Contact-Card) or on the
-   * [Linq dashboard](https://dashboard.linqapp.com/contact-cards).
+   * **Filtering:**
+   *
+   * - If `from` is provided, returns chats for that specific phone number
+   * - If `from` is omitted, returns chats across all phone numbers owned by the
+   *   partner
+   * - If `to` is provided, only returns chats where the specified handle is a
+   *   participant
+   *
+   * **Pagination:**
+   *
+   * - Use `limit` to control page size (default: 20, max: 100)
+   * - The response includes `next_cursor` for fetching the next page
+   * - When `next_cursor` is `null`, there are no more results to fetch
+   * - Pass the `next_cursor` value as the `cursor` parameter for the next request
+   *
+   * **Example pagination flow:**
+   *
+   * 1. First request: `GET /v3/chats?from=%2B12223334444&limit=20`
+   * 2. Response includes `next_cursor: "20"` (more results exist)
+   * 3. Next request: `GET /v3/chats?from=%2B12223334444&limit=20&cursor=20`
+   * 4. Response includes `next_cursor: null` (no more results)
    *
    * @example
    * ```ts
-   * await client.chats.shareContactCard(
+   * // Automatically fetches more pages as needed.
+   * for await (const chat of client.chats.listChats()) {
+   *   // ...
+   * }
+   * ```
+   */
+  listChats(
+    query: ChatListChatsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ChatsListChatsPagination, Chat> {
+    return this._client.getAPIList('/v3/chats', ListChatsPagination<Chat>, { query, ...options });
+  }
+
+  /**
+   * Mark all messages in a chat as read.
+   *
+   * @example
+   * ```ts
+   * await client.chats.markAsRead(
    *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
    * );
    * ```
    */
-  shareContactCard(chatID: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/v3/chats/${chatID}/share_contact_card`, {
+  markAsRead(chatID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/v3/chats/${chatID}/read`, {
       ...options,
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
@@ -290,6 +269,27 @@ export class Chats extends APIResource {
   ): APIPromise<ChatSendVoicememoResponse> {
     return this._client.post(path`/v3/chats/${chatID}/voicememo`, { body, ...options });
   }
+
+  /**
+   * Share your contact information (Name and Photo Sharing) with a chat.
+   *
+   * **Note:** A contact card must be configured before sharing. You can set up your
+   * contact card via the [Contact Card API](#tag/Contact-Card) or on the
+   * [Linq dashboard](https://dashboard.linqapp.com/contact-cards).
+   *
+   * @example
+   * ```ts
+   * await client.chats.shareContactCard(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  shareContactCard(chatID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/v3/chats/${chatID}/share_contact_card`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
 }
 
 export type ChatsListChatsPagination = ListChatsPagination<Chat>;
@@ -383,6 +383,17 @@ export namespace Chat {
      * Current health bucket for the chat. See the
      * [Chat Health guide](/guides/chats/chat-health) for what each value means and how
      * to react. `doc_url` deep-links to the relevant section.
+     *
+     * `OPTED_OUT` is terminal — the recipient sent `STOP`, `UNSUBSCRIBE`, `OPTOUT`,
+     * `CANCEL`, `END`, or `QUIT`, and you should send nothing further on this chat.
+     * The keyword must be the whole trimmed message, never part of a longer one:
+     * `STOP` counts, `please stop` does not. Most keywords must match exactly,
+     * including case. `OPT OUT` is the exception — it matches in any casing, with or
+     * without the space or a hyphen, so `opt out`, `Opt-Out` and `optout` all count.
+     * It clears if they later send `START`, `OPTIN`, or `UNSTOP`, or if they keep
+     * replying on the chat — sustained two-way conversation is treated as a sign the
+     * stop keyword was a false positive. Suppressing sends to opted-out recipients is
+     * your responsibility — Linq surfaces the status but does not block the send.
      */
     status: 'HEALTHY' | 'AT_RISK' | 'CRITICAL' | 'OPTED_OUT';
 
@@ -468,6 +479,16 @@ export interface MediaPart {
  * cannot coexist with text), so copy and a card are two sends, not one.
  */
 export interface MessageContent {
+  /**
+   * Invokes an action on an experience — a third party that renders inside Linq's
+   * iMessage app. Linq resolves the recipient's connection, mints any session the
+   * action needs, composes the card and sends it; none of that is visible to you.
+   *
+   * Call `GET /v3/experiences/{experience}` for the actions you may invoke and the
+   * fields each accepts.
+   */
+  action?: MessageContent.Action;
+
   /**
    * iMessage effect to apply to this message (screen or bubble effect)
    */
@@ -475,7 +496,9 @@ export interface MessageContent {
 
   /**
    * Optional idempotency key for this message. Use this to prevent duplicate sends
-   * of the same message.
+   * of the same message. Reusing a key whose message was deleted — or was an
+   * ephemeral message that has since expired — returns 404; the message is never
+   * resent.
    */
   idempotency_key?: string;
 
@@ -532,6 +555,35 @@ export interface MessageContent {
 }
 
 export namespace MessageContent {
+  /**
+   * Invokes an action on an experience — a third party that renders inside Linq's
+   * iMessage app. Linq resolves the recipient's connection, mints any session the
+   * action needs, composes the card and sends it; none of that is visible to you.
+   *
+   * Call `GET /v3/experiences/{experience}` for the actions you may invoke and the
+   * fields each accepts.
+   */
+  export interface Action {
+    /**
+     * Which of its actions, e.g. `attach_card`.
+     */
+    action: string;
+
+    /**
+     * The experience to invoke, e.g. `agentcard`.
+     */
+    experience: string;
+
+    /**
+     * Values for the fields this action exposes. Keys are exactly the field names
+     * listed for the action — no mapping, no nesting.
+     *
+     * Display copy only, except a `url`-type field — that value sets the destination,
+     * and must be an absolute `https` URL.
+     */
+    params?: { [key: string]: unknown };
+  }
+
   /**
    * An iMessage app card, backed by a Messages app extension. iMessage only — an
    * `imessage_app` part must be the **only** part in the message and is never
@@ -795,6 +847,17 @@ export namespace ChatCreateResponse {
        * Current health bucket for the chat. See the
        * [Chat Health guide](/guides/chats/chat-health) for what each value means and how
        * to react. `doc_url` deep-links to the relevant section.
+       *
+       * `OPTED_OUT` is terminal — the recipient sent `STOP`, `UNSUBSCRIBE`, `OPTOUT`,
+       * `CANCEL`, `END`, or `QUIT`, and you should send nothing further on this chat.
+       * The keyword must be the whole trimmed message, never part of a longer one:
+       * `STOP` counts, `please stop` does not. Most keywords must match exactly,
+       * including case. `OPT OUT` is the exception — it matches in any casing, with or
+       * without the space or a hyphen, so `opt out`, `Opt-Out` and `optout` all count.
+       * It clears if they later send `START`, `OPTIN`, or `UNSTOP`, or if they keep
+       * replying on the chat — sustained two-way conversation is treated as a sign the
+       * stop keyword was a false positive. Suppressing sends to opted-out recipients is
+       * your responsibility — Linq surfaces the status but does not block the send.
        */
       status: 'HEALTHY' | 'AT_RISK' | 'CRITICAL' | 'OPTED_OUT';
 
@@ -952,6 +1015,18 @@ export interface ChatCreateParams {
   to: Array<string>;
 }
 
+export interface ChatUpdateParams {
+  /**
+   * New display name for the chat (group chats only)
+   */
+  display_name?: string;
+
+  /**
+   * URL of an image to set as the group chat icon (group chats only)
+   */
+  group_chat_icon?: string;
+}
+
 export interface ChatListChatsParams extends ListChatsPaginationParams {
   /**
    * Phone number to filter chats by. Returns chats made from this phone number. Must
@@ -970,18 +1045,6 @@ export interface ChatListChatsParams extends ListChatsPaginationParams {
   to?: string;
 }
 
-export interface ChatUpdateParams {
-  /**
-   * New display name for the chat (group chats only)
-   */
-  display_name?: string;
-
-  /**
-   * URL of an image to set as the group chat icon (group chats only)
-   */
-  group_chat_icon?: string;
-}
-
 export interface ChatSendVoicememoParams {
   /**
    * Reference to a voice memo file pre-uploaded via `POST /v3/attachments`. The file
@@ -1017,8 +1080,8 @@ export declare namespace Chats {
     type ChatSendVoicememoResponse as ChatSendVoicememoResponse,
     type ChatsListChatsPagination as ChatsListChatsPagination,
     type ChatCreateParams as ChatCreateParams,
-    type ChatListChatsParams as ChatListChatsParams,
     type ChatUpdateParams as ChatUpdateParams,
+    type ChatListChatsParams as ChatListChatsParams,
     type ChatSendVoicememoParams as ChatSendVoicememoParams,
   };
 
@@ -1036,8 +1099,8 @@ export declare namespace Chats {
     Messages as Messages,
     type SentMessage as SentMessage,
     type MessageSendResponse as MessageSendResponse,
-    type MessageSendParams as MessageSendParams,
     type MessageListParams as MessageListParams,
+    type MessageSendParams as MessageSendParams,
   };
 
   export {

package/src/resources/chats/index.ts

@@ -12,8 +12,8 @@ export {
   type ChatLeaveChatResponse,
   type ChatSendVoicememoResponse,
   type ChatCreateParams,
-  type ChatListChatsParams,
   type ChatUpdateParams,
+  type ChatListChatsParams,
   type ChatSendVoicememoParams,
   type ChatsListChatsPagination,
 } from './chats';
@@ -22,8 +22,8 @@ export {
   Messages,
   type SentMessage,
   type MessageSendResponse,
-  type MessageSendParams,
   type MessageListParams,
+  type MessageSendParams,
 } from './messages';
 export {
   Participants,

package/src/resources/chats/location.ts

@@ -45,34 +45,6 @@ import { path } from '../../internal/utils/path';
  * Messages conversation** with your number.
  */
 export class Location extends APIResource {
-  /**
-   * Request a contact in a chat to share their location. They receive an iMessage
-   * prompt and must accept before any location is available; once they do, read
-   * their location coordinates with `GET /v3/chats/{chatId}/location`.
-   *
-   * The request is delivered asynchronously. The endpoint returns immediately with
-   * `{ "success": true, "message": "Location request sent" }` and does not return
-   * coordinates.
-   *
-   * Location requests only work in **1:1 iMessage chats** (Apple limitation):
-   *
-   * - Group chats (any service) return `409` with code `2016`
-   *   (`GroupChatNotSupported`).
-   * - 1:1 SMS and RCS chats return `409` with code `2017`
-   *   (`ChatServiceNotSupported`).
-   *
-   * @example
-   * ```ts
-   * const locationRequestResponse =
-   *   await client.chats.location.request(
-   *     '975d0776-bd17-4273-8337-f346b4c661b0',
-   *   );
-   * ```
-   */
-  request(chatID: string, options?: RequestOptions): APIPromise<LocationRequestResponse> {
-    return this._client.post(path`/v3/chats/${chatID}/location/request`, options);
-  }
-
   /**
    * Retrieve the current location for contacts sharing with you in a chat.
    *
@@ -107,6 +79,34 @@ export class Location extends APIResource {
       headers: buildHeaders([{ Accept: 'application/geo+json' }, options?.headers]),
     });
   }
+
+  /**
+   * Request a contact in a chat to share their location. They receive an iMessage
+   * prompt and must accept before any location is available; once they do, read
+   * their location coordinates with `GET /v3/chats/{chatId}/location`.
+   *
+   * The request is delivered asynchronously. The endpoint returns immediately with
+   * `{ "success": true, "message": "Location request sent" }` and does not return
+   * coordinates.
+   *
+   * Location requests only work in **1:1 iMessage chats** (Apple limitation):
+   *
+   * - Group chats (any service) return `409` with code `2016`
+   *   (`GroupChatNotSupported`).
+   * - 1:1 SMS and RCS chats return `409` with code `2017`
+   *   (`ChatServiceNotSupported`).
+   *
+   * @example
+   * ```ts
+   * const locationRequestResponse =
+   *   await client.chats.location.request(
+   *     '975d0776-bd17-4273-8337-f346b4c661b0',
+   *   );
+   * ```
+   */
+  request(chatID: string, options?: RequestOptions): APIPromise<LocationRequestResponse> {
+    return this._client.post(path`/v3/chats/${chatID}/location/request`, options);
+  }
 }
 
 export interface GetChatLocationResponse {

package/src/resources/chats/messages.ts

@@ -75,6 +75,31 @@ import { path } from '../../internal/utils/path';
  * **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 {
+  /**
+   * Retrieve messages from a specific chat with pagination support.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.chats.messages.list(
+   *   '550e8400-e29b-41d4-a716-446655440000',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    chatID: string,
+    query: MessageListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<MessagesListMessagesPagination, MessagesAPI.Message> {
+    return this._client.getAPIList(
+      path`/v3/chats/${chatID}/messages`,
+      ListMessagesPagination<MessagesAPI.Message>,
+      { query, ...options },
+    );
+  }
+
   /**
    * Send a message to an existing chat. Use this endpoint when you already have a
    * chat ID and want to send additional messages to it.
@@ -134,31 +159,6 @@ export class Messages extends APIResource {
   send(chatID: string, body: MessageSendParams, options?: RequestOptions): APIPromise<MessageSendResponse> {
     return this._client.post(path`/v3/chats/${chatID}/messages`, { body, ...options });
   }
-
-  /**
-   * Retrieve messages from a specific chat with pagination support.
-   *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const message of client.chats.messages.list(
-   *   '550e8400-e29b-41d4-a716-446655440000',
-   * )) {
-   *   // ...
-   * }
-   * ```
-   */
-  list(
-    chatID: string,
-    query: MessageListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<MessagesListMessagesPagination, MessagesAPI.Message> {
-    return this._client.getAPIList(
-      path`/v3/chats/${chatID}/messages`,
-      ListMessagesPagination<MessagesAPI.Message>,
-      { query, ...options },
-    );
-  }
 }
 
 /**
@@ -384,6 +384,8 @@ export interface MessageSendResponse {
   message: SentMessage;
 }
 
+export interface MessageListParams extends ListMessagesPaginationParams {}
+
 export interface MessageSendParams {
   /**
    * Message content container. Groups all message-related fields together,
@@ -398,14 +400,12 @@ export interface MessageSendParams {
   message: ChatsAPI.MessageContent;
 }
 
-export interface MessageListParams extends ListMessagesPaginationParams {}
-
 export declare namespace Messages {
   export {
     type SentMessage as SentMessage,
     type MessageSendResponse as MessageSendResponse,
-    type MessageSendParams as MessageSendParams,
     type MessageListParams as MessageListParams,
+    type MessageSendParams as MessageSendParams,
   };
 }
 

package/src/resources/contact-card.ts

@@ -14,32 +14,16 @@ import { RequestOptions } from '../internal/request-options';
  * **Sharing behavior:** Sharing may not take effect in every chat due to limitations outside our control. We recommend calling the share endpoint once per day, after the first outbound activity.
  */
 export class ContactCard extends APIResource {
-  /**
-   * Returns the contact card for a specific phone number, or all contact cards for
-   * the authenticated partner if no `phone_number` is provided.
-   *
-   * @example
-   * ```ts
-   * const contactCard = await client.contactCard.retrieve();
-   * ```
-   */
-  retrieve(
-    query: ContactCardRetrieveParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<ContactCardRetrieveResponse> {
-    return this._client.get('/v3/contact_card', { query, ...options });
-  }
-
   /**
    * Creates a contact card for a phone number. This endpoint is intended for
    * initial, one-time setup only.
    *
-   * The contact card is stored in an inactive state first. Once it's applied
-   * successfully, it is activated and `is_active` is returned as `true`. On failure,
-   * `is_active` is `false`.
+   * If setup does not complete, the response is `500` (`2022`) — call this endpoint
+   * again.
    *
-   * **Note:** To update an existing contact card after setup, use
-   * `PATCH /v3/contact_card` instead.
+   * **Note:** once a card is active, this endpoint returns `409` (`2014`) so an
+   * existing card is never overwritten by accident. Use `PATCH /v3/contact_card` to
+   * change it.
    *
    * @example
    * ```ts
@@ -57,13 +41,30 @@ export class ContactCard extends APIResource {
   }
 
   /**
-   * Partially updates an existing active contact card for a phone number.
+   * Returns the contact card for a specific phone number, or all contact cards for
+   * the authenticated partner if no `phone_number` is provided.
+   *
+   * @example
+   * ```ts
+   * const contactCard = await client.contactCard.retrieve();
+   * ```
+   */
+  retrieve(
+    query: ContactCardRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ContactCardRetrieveResponse> {
+    return this._client.get('/v3/contact_card', { query, ...options });
+  }
+
+  /**
+   * Partially updates the contact card for a phone number.
    *
-   * Fetches the current active contact card and merges the provided fields. Only
-   * fields present in the request body are updated; omitted fields retain their
-   * existing values.
+   * Fetches the current contact card and merges the provided fields. Only fields
+   * present in the request body are updated; omitted fields retain their existing
+   * values.
    *
-   * Requires an active contact card to exist for the phone number.
+   * If the update does not complete, the response is `500` (`2022`) — call this
+   * endpoint again.
    *
    * @example
    * ```ts
@@ -127,14 +128,6 @@ export namespace ContactCardRetrieveResponse {
   }
 }
 
-export interface ContactCardRetrieveParams {
-  /**
-   * E.164 phone number to filter by. If omitted, all my cards for the partner are
-   * returned.
-   */
-  phone_number?: string;
-}
-
 export interface ContactCardCreateParams {
   /**
    * First name for the contact card. Required.
@@ -157,6 +150,14 @@ export interface ContactCardCreateParams {
   last_name?: string;
 }
 
+export interface ContactCardRetrieveParams {
+  /**
+   * E.164 phone number to filter by. If omitted, all my cards for the partner are
+   * returned.
+   */
+  phone_number?: string;
+}
+
 export interface ContactCardUpdateParams {
   /**
    * Query param: E.164 phone number of the contact card to update
@@ -183,8 +184,8 @@ export declare namespace ContactCard {
   export {
     type SetContactCard as SetContactCard,
     type ContactCardRetrieveResponse as ContactCardRetrieveResponse,
-    type ContactCardRetrieveParams as ContactCardRetrieveParams,
     type ContactCardCreateParams as ContactCardCreateParams,
+    type ContactCardRetrieveParams as ContactCardRetrieveParams,
     type ContactCardUpdateParams as ContactCardUpdateParams,
   };
 }