@linqapp/sdk 0.35.1 → 0.37.0

package/src/client.ts

@@ -81,10 +81,20 @@ import {
 } from './resources/payment-requests';
 import { Payment, PaymentCreateParams, PaymentCredentialsResponse, Payments } from './resources/payments';
 import {
+  PhoneNumberGetReputationAuditParams,
   PhoneNumberListResponse,
   PhoneNumberUpdateParams,
   PhoneNumberUpdateResponse,
   PhoneNumbers,
+  ReputationActionItem,
+  ReputationAudit,
+  ReputationAuditStarted,
+  ReputationDriver,
+  ReputationDriverKey,
+  ReputationEvidence,
+  ReputationOptOutChat,
+  ReputationReport,
+  ReputationUnhealthyChat,
 } from './resources/phone-numbers';
 import { PhonenumberListResponse, Phonenumbers } from './resources/phonenumbers';
 import { WebhookEventListResponse, WebhookEventType, WebhookEvents } from './resources/webhook-events';
@@ -1300,6 +1310,41 @@ export class LinqAPIV3 {
    * branding; a newly registered experience can take up to ~24 hours to
    * activate on Apple's side, during which links open the web checkout.
    *
+   * ## Sending it as a card instead
+   *
+   * A `link` part is one way to deliver a request. The other is the
+   * **`agentpay` experience**, which sends the same request as a native card
+   * in Linq's iMessage app — the amount and reason are drawn in the bubble,
+   * and it turns itself into "Paid" in place once the payment succeeds,
+   * without a second message.
+   *
+   * Send it to `POST /v3/chats/{chatId}/messages`:
+   *
+   * ```json
+   * {
+   *   "message": {
+   *     "experience": {
+   *       "name": "agentpay",
+   *       "action": "request_payment",
+   *       "params": { "checkout_url": "https://zero.linqapp.com/pay/acme?session=tok_..." }
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * `checkout_url` is the only required field — pass back exactly what
+   * `POST /v3/payment_requests` returned. **The amount and reason are read
+   * from that request, never from you**, so the card can never claim a
+   * different figure than the checkout will charge. Optional `title` and
+   * `note` override the copy only. The link must be one of your own payment
+   * requests; another partner's is rejected.
+   *
+   * The trade-off against a `link` part: a card is an app card, so it is
+   * iMessage-only, and recipients without the app see a static version of it.
+   * A link works everywhere and is what opens the Apple Pay App Clip. Send
+   * whichever suits the conversation — both settle the same payment request
+   * and fire the same webhooks.
+   *
    * ## Webhooks
    *
    * Subscribe to payment lifecycle events to reconcile server-side rather than
@@ -1340,9 +1385,55 @@ export class LinqAPIV3 {
    */
   blockedHandles: API.BlockedHandles = new API.BlockedHandles(this);
   /**
-   * 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.
+   * An **experience** renders inside Linq's iMessage app as a native card,
+   * instead of as text or a link. You invoke one by name; Linq resolves the
+   * recipient, mints any session it needs, composes the card and sends it.
+   *
+   * Send it to `POST /v3/chats/{chatId}/messages`:
+   *
+   * ```json
+   * {
+   *   "message": {
+   *     "experience": {
+   *       "name": "agentpay",
+   *       "action": "request_payment",
+   *       "params": { "checkout_url": "https://zero.linqapp.com/pay/acme?session=tok_..." }
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * The key is `experience` — what you're invoking. Nested under it is its
+   * `name`, the action you're invoking on it, and that action's params. A card
+   * **is** the whole message on Apple's side, so a message carries either
+   * `experience` or `parts`, never both, and an action goes to exactly one
+   * recipient.
+   *
+   * ## What you can invoke
+   *
+   * | Experience | Action | What the customer sees |
+   * |---|---|---|
+   * | `agentpay` | `request_payment` | A payment request they can pay in the app. Turns itself into "Paid" in place once it settles. |
+   * | `agentcard` | `attach_card` | A prompt to add a card to their wallet. |
+   * | `agentcard` | `approve_card` | A passkey approval for a virtual card. |
+   * | `link` | `open` | A card that opens a URL you supply. |
+   *
+   * `GET /v3/experiences` is the authoritative list for your account, with
+   * every action and the fields each accepts — an action missing there cannot
+   * be sent. Fields are display copy unless documented otherwise.
+   *
+   * ## Params are checked before the card is sent
+   *
+   * Unknown fields are **rejected rather than ignored**, so copy that would
+   * never have rendered fails for you now instead of arriving wrong on
+   * somebody's phone. Some fields are read rather than sent: `agentpay`'s
+   * `request_payment` takes only a `checkout_url` and resolves the amount and
+   * reason from that payment request, so a card can never claim a figure the
+   * checkout will not charge.
+   *
+   * Cards are **iMessage-only**. Recipients without the app see a static
+   * version built from the same copy; SMS and RCS recipients cannot receive
+   * one at all (error codes 2018 and 4005).
    *
    */
   experiences: API.Experiences = new API.Experiences(this);
@@ -1704,9 +1795,19 @@ export declare namespace LinqAPIV3 {
 
   export {
     PhoneNumbers as PhoneNumbers,
+    type ReputationActionItem as ReputationActionItem,
+    type ReputationAudit as ReputationAudit,
+    type ReputationAuditStarted as ReputationAuditStarted,
+    type ReputationDriver as ReputationDriver,
+    type ReputationDriverKey as ReputationDriverKey,
+    type ReputationEvidence as ReputationEvidence,
+    type ReputationOptOutChat as ReputationOptOutChat,
+    type ReputationReport as ReputationReport,
+    type ReputationUnhealthyChat as ReputationUnhealthyChat,
     type PhoneNumberUpdateResponse as PhoneNumberUpdateResponse,
     type PhoneNumberListResponse as PhoneNumberListResponse,
     type PhoneNumberUpdateParams as PhoneNumberUpdateParams,
+    type PhoneNumberGetReputationAuditParams as PhoneNumberGetReputationAuditParams,
   };
 
   export {

package/src/resources/attachments.ts

@@ -197,10 +197,9 @@ export class Attachments extends APIResource {
    *
    * ## Step 1: Request an upload URL
    *
-   * Call this endpoint with file metadata:
+   * Call `POST /v3/attachments` with file metadata:
    *
    * ```json
-   * POST /v3/attachments
    * {
    *   "filename": "photo.jpg",
    *   "content_type": "image/jpeg",
@@ -231,11 +230,10 @@ export class Attachments extends APIResource {
    *
    * ## Step 3: Send a message with the attachment
    *
-   * Reference the `attachment_id` in a media part. The ID never expires — use it in
-   * as many messages as you want.
+   * Reference the `attachment_id` in a media part with `POST /v3/chats`. The ID
+   * never expires — use it in as many messages as you want.
    *
    * ```json
-   * POST /v3/chats
    * {
    *   "from": "+15559876543",
    *   "to": ["+15551234567"],

package/src/resources/capability.ts

@@ -30,6 +30,13 @@ export class Capability extends APIResource {
   /**
    * Check whether a recipient address (phone number) supports RCS messaging.
    *
+   * A `200` means the check ran and the answer is about the **recipient**. A `503`
+   * means the check could not produce an answer because of a fault on the **sender**
+   * line — `4004` (RCS not turned on for the line), `4009` (line has no RCS
+   * account), or `4010` (the check could not run). Treat all three as "unknown",
+   * never as "the recipient does not support RCS", and do not cache them as a
+   * negative result.
+   *
    * @example
    * ```ts
    * const handleCheckResponse =
@@ -66,6 +73,23 @@ export interface HandleCheckResponse {
    * Whether the recipient supports the checked messaging service
    */
   available: boolean;
+
+  /**
+   * Why `available` is `false`. Only present on a negative result.
+   *
+   * `not_supported` is the only value returned with a `200`, and it means the check
+   * completed and the recipient is genuinely not reachable over this service. On
+   * `check_rcs`, sender-side faults do not return `200` — they return `503` with a
+   * specific error code. `check_imessage` does not use this mapping.
+   */
+  reason?: 'not_supported';
+
+  /**
+   * The service that would actually carry a message to this address right now, which
+   * is not always the service you checked — a recipient without RCS resolves to
+   * `SMS`. Absent when the check could not determine one.
+   */
+  selected_service?: string;
 }
 
 export interface CapabilityCheckIMessageParams {

package/src/resources/chats/chats.ts

@@ -481,11 +481,17 @@ export interface MediaPart {
  * from/to).
  *
  * A message carries EITHER `parts` — text and attachments, which compose into one
- * bubble — or a single `action`, which invokes an experience inside Linq's
- * iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
- * cannot coexist with text), so copy and a card are two sends, not one.
+ * bubble — or a single `experience` invocation, which renders an experience inside
+ * Linq's iMessage app. Never both: an app card is the whole message (Apple's
+ * `MSMessage` cannot coexist with text), so copy and a card are two sends, not
+ * one.
  */
 export interface MessageContent {
+  /**
+   * iMessage effect to apply to this message (screen or bubble effect)
+   */
+  effect?: ResourcesMessagesAPI.MessageEffect;
+
   /**
    * 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
@@ -494,12 +500,7 @@ export interface MessageContent {
    * 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)
-   */
-  effect?: ResourcesMessagesAPI.MessageEffect;
+  experience?: MessageContent.Experience;
 
   /**
    * Optional idempotency key for this message. Use this to prevent duplicate sends
@@ -570,16 +571,16 @@ export namespace MessageContent {
    * Call `GET /v3/experiences/{experience}` for the actions you may invoke and the
    * fields each accepts.
    */
-  export interface Action {
+  export interface Experience {
     /**
      * Which of its actions, e.g. `attach_card`.
      */
     action: string;
 
     /**
-     * The experience to invoke, e.g. `agentcard`.
+     * The experience to invoke, e.g. `agentcard` or `agentpay`.
      */
-    experience: string;
+    name: string;
 
     /**
      * Values for the fields this action exposes. Keys are exactly the field names
@@ -587,6 +588,10 @@ export namespace MessageContent {
      *
      * Display copy only, except a `url`-type field — that value sets the destination,
      * and must be an absolute `https` URL.
+     *
+     * Some fields are read rather than sent: `agentpay`'s `request_payment` takes only
+     * a `checkout_url` and resolves the amount and reason from that payment request
+     * itself, so the card cannot state a figure the checkout will not charge.
      */
     params?: { [key: string]: unknown };
   }
@@ -1033,9 +1038,10 @@ export interface ChatCreateParams {
    * from/to).
    *
    * A message carries EITHER `parts` — text and attachments, which compose into one
-   * bubble — or a single `action`, which invokes an experience inside Linq's
-   * iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
-   * cannot coexist with text), so copy and a card are two sends, not one.
+   * bubble — or a single `experience` invocation, which renders an experience inside
+   * Linq's iMessage app. Never both: an app card is the whole message (Apple's
+   * `MSMessage` cannot coexist with text), so copy and a card are two sends, not
+   * one.
    */
   message: MessageContent;
 

package/src/resources/chats/messages.ts

@@ -393,9 +393,10 @@ export interface MessageSendParams {
    * from/to).
    *
    * A message carries EITHER `parts` — text and attachments, which compose into one
-   * bubble — or a single `action`, which invokes an experience inside Linq's
-   * iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
-   * cannot coexist with text), so copy and a card are two sends, not one.
+   * bubble — or a single `experience` invocation, which renders an experience inside
+   * Linq's iMessage app. Never both: an app card is the whole message (Apple's
+   * `MSMessage` cannot coexist with text), so copy and a card are two sends, not
+   * one.
    */
   message: ChatsAPI.MessageContent;
 

package/src/resources/experiences.ts

@@ -6,13 +6,66 @@ 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.
+ * An **experience** renders inside Linq's iMessage app as a native card,
+ * instead of as text or a link. You invoke one by name; Linq resolves the
+ * recipient, mints any session it needs, composes the card and sends it.
+ *
+ * Send it to `POST /v3/chats/{chatId}/messages`:
+ *
+ * ```json
+ * {
+ *   "message": {
+ *     "experience": {
+ *       "name": "agentpay",
+ *       "action": "request_payment",
+ *       "params": { "checkout_url": "https://zero.linqapp.com/pay/acme?session=tok_..." }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The key is `experience` — what you're invoking. Nested under it is its
+ * `name`, the action you're invoking on it, and that action's params. A card
+ * **is** the whole message on Apple's side, so a message carries either
+ * `experience` or `parts`, never both, and an action goes to exactly one
+ * recipient.
+ *
+ * ## What you can invoke
+ *
+ * | Experience | Action | What the customer sees |
+ * |---|---|---|
+ * | `agentpay` | `request_payment` | A payment request they can pay in the app. Turns itself into "Paid" in place once it settles. |
+ * | `agentcard` | `attach_card` | A prompt to add a card to their wallet. |
+ * | `agentcard` | `approve_card` | A passkey approval for a virtual card. |
+ * | `link` | `open` | A card that opens a URL you supply. |
+ *
+ * `GET /v3/experiences` is the authoritative list for your account, with
+ * every action and the fields each accepts — an action missing there cannot
+ * be sent. Fields are display copy unless documented otherwise.
+ *
+ * ## Params are checked before the card is sent
+ *
+ * Unknown fields are **rejected rather than ignored**, so copy that would
+ * never have rendered fails for you now instead of arriving wrong on
+ * somebody's phone. Some fields are read rather than sent: `agentpay`'s
+ * `request_payment` takes only a `checkout_url` and resolves the amount and
+ * reason from that payment request, so a card can never claim a figure the
+ * checkout will not charge.
+ *
+ * Cards are **iMessage-only**. Recipients without the app see a static
+ * version built from the same copy; SMS and RCS recipients cannot receive
+ * one at all (error codes 2018 and 4005).
  */
 export class Experiences extends APIResource {
   /**
    * Get one experience
+   *
+   * @example
+   * ```ts
+   * const experience = await client.experiences.retrieve(
+   *   'agentpay',
+   * );
+   * ```
    */
   retrieve(experience: string, options?: RequestOptions): APIPromise<ExperienceRetrieveResponse> {
     return this._client.get(path`/v3/experiences/${experience}`, options);
@@ -22,6 +75,11 @@ export class Experiences extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const experiences = await client.experiences.list();
+   * ```
    */
   list(options?: RequestOptions): APIPromise<ExperienceListResponse> {
     return this._client.get('/v3/experiences', options);

package/src/resources/index.ts

@@ -95,9 +95,19 @@ export {
 } from './payments';
 export {
   PhoneNumbers,
+  type ReputationActionItem,
+  type ReputationAudit,
+  type ReputationAuditStarted,
+  type ReputationDriver,
+  type ReputationDriverKey,
+  type ReputationEvidence,
+  type ReputationOptOutChat,
+  type ReputationReport,
+  type ReputationUnhealthyChat,
   type PhoneNumberUpdateResponse,
   type PhoneNumberListResponse,
   type PhoneNumberUpdateParams,
+  type PhoneNumberGetReputationAuditParams,
 } from './phone-numbers';
 export { Phonenumbers, type PhonenumberListResponse } from './phonenumbers';
 export { WebhookEvents, type WebhookEventType, type WebhookEventListResponse } from './webhook-events';

package/src/resources/messages/messages.ts

@@ -706,9 +706,10 @@ export interface MessageCreateParams {
    * fields like from/to).
    *
    * A message carries EITHER `parts` — text and attachments, which compose into one
-   * bubble — or a single `action`, which invokes an experience inside Linq's
-   * iMessage app. Never both: an app card is the whole message (Apple's `MSMessage`
-   * cannot coexist with text), so copy and a card are two sends, not one.
+   * bubble — or a single `experience` invocation, which renders an experience inside
+   * Linq's iMessage app. Never both: an app card is the whole message (Apple's
+   * `MSMessage` cannot coexist with text), so copy and a card are two sends, not
+   * one.
    */
   message: ChatsAPI.MessageContent;
 
@@ -854,7 +855,7 @@ export interface MessageUpdateAppCardParams {
    * Call `GET /v3/experiences/{experience}` for the actions you may invoke and the
    * fields each accepts.
    */
-  action?: MessageUpdateAppCardParams.Action;
+  experience?: MessageUpdateAppCardParams.Experience;
 
   /**
    * Text shown on surfaces that cannot render the card (notifications, lock screen).
@@ -878,7 +879,7 @@ export interface MessageUpdateAppCardParams {
   /**
    * URL the recipient's app opens when they tap the updated card.
    *
-   * Mutually exclusive with `action` and `raw_payload_data`.
+   * Mutually exclusive with `experience` and `raw_payload_data`.
    */
   url?: string;
 }
@@ -951,16 +952,16 @@ export namespace MessageUpdateAppCardParams {
    * Call `GET /v3/experiences/{experience}` for the actions you may invoke and the
    * fields each accepts.
    */
-  export interface Action {
+  export interface Experience {
     /**
      * Which of its actions, e.g. `attach_card`.
      */
     action: string;
 
     /**
-     * The experience to invoke, e.g. `agentcard`.
+     * The experience to invoke, e.g. `agentcard` or `agentpay`.
      */
-    experience: string;
+    name: string;
 
     /**
      * Values for the fields this action exposes. Keys are exactly the field names
@@ -968,6 +969,10 @@ export namespace MessageUpdateAppCardParams {
      *
      * Display copy only, except a `url`-type field — that value sets the destination,
      * and must be an absolute `https` URL.
+     *
+     * Some fields are read rather than sent: `agentpay`'s `request_payment` takes only
+     * a `checkout_url` and resolves the amount and reason from that payment request
+     * itself, so the card cannot state a figure the checkout will not charge.
      */
     params?: { [key: string]: unknown };
   }

package/src/resources/payment-requests.ts

@@ -112,6 +112,41 @@ import { path } from '../internal/utils/path';
  * branding; a newly registered experience can take up to ~24 hours to
  * activate on Apple's side, during which links open the web checkout.
  *
+ * ## Sending it as a card instead
+ *
+ * A `link` part is one way to deliver a request. The other is the
+ * **`agentpay` experience**, which sends the same request as a native card
+ * in Linq's iMessage app — the amount and reason are drawn in the bubble,
+ * and it turns itself into "Paid" in place once the payment succeeds,
+ * without a second message.
+ *
+ * Send it to `POST /v3/chats/{chatId}/messages`:
+ *
+ * ```json
+ * {
+ *   "message": {
+ *     "experience": {
+ *       "name": "agentpay",
+ *       "action": "request_payment",
+ *       "params": { "checkout_url": "https://zero.linqapp.com/pay/acme?session=tok_..." }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * `checkout_url` is the only required field — pass back exactly what
+ * `POST /v3/payment_requests` returned. **The amount and reason are read
+ * from that request, never from you**, so the card can never claim a
+ * different figure than the checkout will charge. Optional `title` and
+ * `note` override the copy only. The link must be one of your own payment
+ * requests; another partner's is rejected.
+ *
+ * The trade-off against a `link` part: a card is an app card, so it is
+ * iMessage-only, and recipients without the app see a static version of it.
+ * A link works everywhere and is what opens the Apple Pay App Clip. Send
+ * whichever suits the conversation — both settle the same payment request
+ * and fire the same webhooks.
+ *
  * ## Webhooks
  *
  * Subscribe to payment lifecycle events to reconcile server-side rather than