@linqapp/sdk 0.32.1 → 0.33.1

package/src/resources/chats/polls.ts

@@ -0,0 +1,196 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Messages are individual communications within a chat thread.
+ *
+ * Messages can include text, media attachments, rich link previews, special effects
+ * (like confetti or fireworks), and reactions. All messages are associated with a
+ * specific chat and sent from a phone number you own.
+ *
+ * Messages support delivery status tracking, read receipts, and editing capabilities.
+ *
+ * ## Rich Link Previews
+ *
+ * Send a URL as a `link` part to deliver it with a rich preview card showing the
+ * page's title, description, and image (when available). A `link` part must be the
+ * **only** part in the message — it cannot be combined with text or media parts.
+ * To send a URL without a preview card, include it in a `text` part instead.
+ *
+ * **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 Polls extends APIResource {
+  /**
+   * Create an iMessage poll in an existing chat and send it. Polls are
+   * iMessage-only.
+   *
+   * The chat must already exist — **a poll cannot be the first message of a new
+   * chat** (use `POST /v3/chats` for that). Options are **add-only and immutable**:
+   * you can add options later via `POST /v3/messages/{messageId}/poll/options`, but
+   * never edit or remove them.
+   *
+   * @example
+   * ```ts
+   * const pollEnvelope = await client.chats.polls.create(
+   *   '550e8400-e29b-41d4-a716-446655440000',
+   *   {
+   *     poll: {
+   *       options: [{ text: 'Tacos' }, { text: 'Sushi' }],
+   *       idempotency_key: 'poll-abc123',
+   *     },
+   *   },
+   * );
+   * ```
+   */
+  create(chatID: string, body: PollCreateParams, options?: RequestOptions): APIPromise<PollEnvelope> {
+    return this._client.post(path`/v3/chats/${chatID}/polls`, { body, ...options });
+  }
+}
+
+/**
+ * Poll content — options and the aggregate voter count.
+ */
+export interface Poll {
+  options: Array<Poll.Option>;
+
+  /**
+   * Distinct participants across the whole poll (a voter picking two options counts
+   * once).
+   */
+  total_voters: number;
+}
+
+export namespace Poll {
+  export interface Option {
+    can_be_edited: boolean;
+
+    /**
+     * The participant who added this option (poll creator for the initial options;
+     * whoever added later ones).
+     */
+    creator_handle: Shared.ChatHandle;
+
+    option_id: string;
+
+    text: string;
+
+    /**
+     * Participants who voted for this option (vote_count = voters.length).
+     */
+    voters: Array<Option.Voter>;
+  }
+
+  export namespace Option {
+    export interface Voter {
+      handle: string;
+
+      voted_at: string;
+    }
+  }
+}
+
+/**
+ * Message-level envelope returned by every poll endpoint.
+ */
+export interface PollEnvelope {
+  chat_id: string;
+
+  created_at: string;
+
+  /**
+   * The poll-definition message's ID — reference this poll by it.
+   */
+  message_id: string;
+
+  /**
+   * Poll content — options and the aggregate voter count.
+   */
+  poll: Poll;
+
+  /**
+   * Tapbacks/stickers on the whole poll (message part 0).
+   */
+  reactions: Array<Shared.Reaction>;
+
+  updated_at: string;
+}
+
+export interface PollCreateParams {
+  /**
+   * Poll content to create. A poll needs at least two options. Options are add-only
+   * and immutable — there is no title/question (send that as a normal text message).
+   */
+  poll: PollCreateParams.Poll;
+}
+
+export namespace PollCreateParams {
+  /**
+   * Poll content to create. A poll needs at least two options. Options are add-only
+   * and immutable — there is no title/question (send that as a normal text message).
+   */
+  export interface Poll {
+    options: Array<Poll.Option>;
+
+    /**
+     * Optional key to deduplicate the poll creation.
+     */
+    idempotency_key?: string;
+  }
+
+  export namespace Poll {
+    export interface Option {
+      text: string;
+    }
+  }
+}
+
+export declare namespace Polls {
+  export { type Poll as Poll, type PollEnvelope as PollEnvelope, type PollCreateParams as PollCreateParams };
+}

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,
   };
 }

package/src/resources/experiences.ts

@@ -0,0 +1,118 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Let an agent pay on a customer's behalf with a single-use virtual card.
+ * Connect a customer once, then create a payment — a virtual card is minted
+ * scoped to that purchase and the card details are handed back for checkout.
+ */
+export class Experiences extends APIResource {
+  /**
+   * Get one experience
+   */
+  retrieve(experience: string, options?: RequestOptions): APIPromise<ExperienceRetrieveResponse> {
+    return this._client.get(path`/v3/experiences/${experience}`, options);
+  }
+
+  /**
+   * The experiences enabled for your account, with the actions you may invoke on
+   * each and the fields each action accepts. This is the authoritative list — an
+   * action missing here cannot be sent.
+   */
+  list(options?: RequestOptions): APIPromise<ExperienceListResponse> {
+    return this._client.get('/v3/experiences', options);
+  }
+}
+
+/**
+ * What an experience offers you. Deliberately a projection: where its templates
+ * live and how they are built is not yours to depend on, so it is not here.
+ */
+export interface ExperienceRetrieveResponse {
+  actions?: Array<ExperienceRetrieveResponse.Action>;
+
+  display_name?: string;
+
+  experience?: string;
+}
+
+export namespace ExperienceRetrieveResponse {
+  export interface Action {
+    /**
+     * Fields you may send in `params`, keyed by the exact name to use.
+     */
+    fields?: { [key: string]: Action.Fields };
+
+    name?: string;
+
+    summary?: string;
+  }
+
+  export namespace Action {
+    export interface Fields {
+      /**
+       * Maximum length, for strings.
+       */
+      max?: number;
+
+      required?: boolean;
+
+      type?: 'string' | 'cents' | 'int' | 'url';
+    }
+  }
+}
+
+export interface ExperienceListResponse {
+  experiences?: Array<ExperienceListResponse.Experience>;
+}
+
+export namespace ExperienceListResponse {
+  /**
+   * What an experience offers you. Deliberately a projection: where its templates
+   * live and how they are built is not yours to depend on, so it is not here.
+   */
+  export interface Experience {
+    actions?: Array<Experience.Action>;
+
+    display_name?: string;
+
+    experience?: string;
+  }
+
+  export namespace Experience {
+    export interface Action {
+      /**
+       * Fields you may send in `params`, keyed by the exact name to use.
+       */
+      fields?: { [key: string]: Action.Fields };
+
+      name?: string;
+
+      summary?: string;
+    }
+
+    export namespace Action {
+      export interface Fields {
+        /**
+         * Maximum length, for strings.
+         */
+        max?: number;
+
+        required?: boolean;
+
+        type?: 'string' | 'cents' | 'int' | 'url';
+      }
+    }
+  }
+}
+
+export declare namespace Experiences {
+  export {
+    type ExperienceRetrieveResponse as ExperienceRetrieveResponse,
+    type ExperienceListResponse as ExperienceListResponse,
+  };
+}

package/src/resources/index.ts

@@ -32,8 +32,8 @@ export {
   type ChatLeaveChatResponse,
   type ChatSendVoicememoResponse,
   type ChatCreateParams,
-  type ChatListChatsParams,
   type ChatUpdateParams,
+  type ChatListChatsParams,
   type ChatSendVoicememoParams,
   type ChatsListChatsPagination,
 } from './chats/chats';
@@ -41,10 +41,11 @@ export {
   ContactCard,
   type SetContactCard,
   type ContactCardRetrieveResponse,
-  type ContactCardRetrieveParams,
   type ContactCardCreateParams,
+  type ContactCardRetrieveParams,
   type ContactCardUpdateParams,
 } from './contact-card';
+export { Experiences, type ExperienceRetrieveResponse, type ExperienceListResponse } from './experiences';
 export {
   Messages,
   type Message,
@@ -54,12 +55,23 @@ export {
   type MessageAddReactionResponse,
   type MessageUpdateAppCardResponse,
   type MessageCreateParams,
-  type MessageListMessagesThreadParams,
-  type MessageAddReactionParams,
   type MessageUpdateParams,
+  type MessageAddReactionParams,
+  type MessageListMessagesThreadParams,
   type MessageUpdateAppCardParams,
   type MessagesListMessagesPagination,
-} from './messages';
+} from './messages/messages';
+export {
+  PaymentHandles,
+  type PaymentHandleConnection,
+  type PaymentHandleVerifyParams,
+} from './payment-handles';
+export {
+  PaymentProviders,
+  type PaymentProvider,
+  type PaymentProviderConnectResponse,
+  type PaymentProviderConnectParams,
+} from './payment-providers';
 export {
   PaymentRequests,
   type PaymentRequest,
@@ -67,6 +79,12 @@ export {
   type PaymentRequestCreateParams,
   type PaymentRequestListParams,
 } from './payment-requests';
+export {
+  Payments,
+  type Payment,
+  type PaymentCredentialsResponse,
+  type PaymentCreateParams,
+} from './payments';
 export {
   PhoneNumbers,
   type PhoneNumberUpdateResponse,

package/src/resources/messages/index.ts

@@ -0,0 +1,18 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Messages,
+  type Message,
+  type MessageEffect,
+  type ReplyTo,
+  type MessageCreateResponse,
+  type MessageAddReactionResponse,
+  type MessageUpdateAppCardResponse,
+  type MessageCreateParams,
+  type MessageUpdateParams,
+  type MessageAddReactionParams,
+  type MessageListMessagesThreadParams,
+  type MessageUpdateAppCardParams,
+  type MessagesListMessagesPagination,
+} from './messages';
+export { Poll, type PollAddOptionsParams, type PollVoteParams } from './poll';