@linqapp/sdk 0.35.0 → 0.36.1

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

package/src/resources/phone-numbers.ts

@@ -50,6 +50,275 @@ export class PhoneNumbers extends APIResource {
   list(options?: RequestOptions): APIPromise<PhoneNumberListResponse> {
     return this._client.get('/v3/phone_numbers', options);
   }
+
+  /**
+   * Returns the audit's status and, once complete, the report. Audits are scoped to
+   * the line in the URL — an `auditId` started on a different line returns `404`.
+   *
+   * @example
+   * ```ts
+   * const reputationAudit =
+   *   await client.phoneNumbers.getReputationAudit('auditId', {
+   *     phoneNumber: 'phoneNumber',
+   *   });
+   * ```
+   */
+  getReputationAudit(
+    auditID: string,
+    params: PhoneNumberGetReputationAuditParams,
+    options?: RequestOptions,
+  ): APIPromise<ReputationAudit> {
+    const { phoneNumber } = params;
+    return this._client.get(path`/v3/phone_numbers/${phoneNumber}/reputation_audit/${auditID}`, options);
+  }
+
+  /**
+   * Starts an asynchronous reputation audit for a line and returns an `audit_id`.
+   * Poll the GET endpoint for the result.
+   *
+   * Rate limited per line: only one audit may run at a time (a second request
+   * returns `409` while the first is still in progress), and a new audit can't be
+   * started for the same line until a cooldown elapses (`429`, with `Retry-After`
+   * carrying the wait).
+   *
+   * @example
+   * ```ts
+   * const reputationAuditStarted =
+   *   await client.phoneNumbers.startReputationAudit(
+   *     'phoneNumber',
+   *   );
+   * ```
+   */
+  startReputationAudit(phoneNumber: string, options?: RequestOptions): APIPromise<ReputationAuditStarted> {
+    return this._client.post(path`/v3/phone_numbers/${phoneNumber}/reputation_audit`, options);
+  }
+}
+
+export interface ReputationActionItem {
+  detail?: string;
+
+  expected_impact?: 'high' | 'medium' | 'low';
+
+  /**
+   * 1 = do first
+   */
+  priority?: number;
+
+  title?: string;
+}
+
+export interface ReputationAudit {
+  audit_id: string;
+
+  /**
+   * `pending` until the report is ready — poll until `complete` or `error`.
+   */
+  status: 'pending' | 'complete' | 'error';
+
+  /**
+   * Present only when `status` is `error`. Short, generic reason safe to display.
+   */
+  error?: string;
+
+  /**
+   * When the report was generated; signals reflect the line at this moment.
+   */
+  generated_at?: string;
+
+  /**
+   * The line audited, E.164.
+   */
+  phone?: string;
+
+  /**
+   * Present only when `status` is `complete`.
+   */
+  report?: ReputationReport;
+}
+
+export interface ReputationAuditStarted {
+  /**
+   * Identifier for this audit. Poll
+   * `GET /v3/phone_numbers/{phoneNumber}/reputation_audit/{auditId}` until `status`
+   * is `complete` or `error`.
+   */
+  audit_id: string;
+
+  /**
+   * A newly started audit is `pending`.
+   */
+  status: 'pending' | 'complete' | 'error';
+}
+
+export interface ReputationDriver {
+  /**
+   * Stable driver-category identifier — what is dragging the line, or one of its
+   * conversations, down.
+   *
+   * - `low_engagement` — The conversation is one-sided: several messages sent, few
+   *   or no replies back. Pause or rework outreach where recipients are not
+   *   replying, and lead with messages that invite a response. Conversation-level:
+   *   it appears on `evidence.unhealthy_chats[].driver_keys`, never in `drivers`.
+   * - `overall_conversation_health` — A large share of the line's active
+   *   conversations are trending unhealthy. Fix those conversations first — review
+   *   their content and timing, and whether recipients are engaging.
+   * - `volume_spike` — The line's daily sending volume jumped far above its own
+   *   normal level. Ramp gradually instead of spiking, spread large sends across
+   *   days, and prioritize people who have already engaged.
+   * - `new_conversation_rate` — The line is starting too many brand-new
+   *   conversations in a single day. Spread new conversations out over time instead
+   *   of starting many at once.
+   * - `opt_out_handling` — Recipients asked this line to stop. Honor every stop
+   *   request immediately: send nothing further to that recipient unless they opt
+   *   back in. Every send to them is rejected with `403` (error code `2024`),
+   *   including a final courtesy message — to send one telling them they can reply
+   *   to resume, set `override_optout: true` on that single request.
+   * - `flagged` — The line is currently restricted and its messages may not be
+   *   reaching recipients. Move active traffic to a healthy line now, and let this
+   *   one recover before sending more.
+   * - `other` — Fallback for a signal without dedicated partner copy.
+   */
+  key?: ReputationDriverKey;
+
+  /**
+   * A specific observed figure when available; otherwise a short qualitative note.
+   */
+  metric?: string;
+
+  /**
+   * One plain-English sentence.
+   */
+  summary?: string;
+}
+
+/**
+ * Stable driver-category identifier — what is dragging the line, or one of its
+ * conversations, down.
+ *
+ * - `low_engagement` — The conversation is one-sided: several messages sent, few
+ *   or no replies back. Pause or rework outreach where recipients are not
+ *   replying, and lead with messages that invite a response. Conversation-level:
+ *   it appears on `evidence.unhealthy_chats[].driver_keys`, never in `drivers`.
+ * - `overall_conversation_health` — A large share of the line's active
+ *   conversations are trending unhealthy. Fix those conversations first — review
+ *   their content and timing, and whether recipients are engaging.
+ * - `volume_spike` — The line's daily sending volume jumped far above its own
+ *   normal level. Ramp gradually instead of spiking, spread large sends across
+ *   days, and prioritize people who have already engaged.
+ * - `new_conversation_rate` — The line is starting too many brand-new
+ *   conversations in a single day. Spread new conversations out over time instead
+ *   of starting many at once.
+ * - `opt_out_handling` — Recipients asked this line to stop. Honor every stop
+ *   request immediately: send nothing further to that recipient unless they opt
+ *   back in. Every send to them is rejected with `403` (error code `2024`),
+ *   including a final courtesy message — to send one telling them they can reply
+ *   to resume, set `override_optout: true` on that single request.
+ * - `flagged` — The line is currently restricted and its messages may not be
+ *   reaching recipients. Move active traffic to a healthy line now, and let this
+ *   one recover before sending more.
+ * - `other` — Fallback for a signal without dedicated partner copy.
+ */
+export type ReputationDriverKey =
+  | 'low_engagement'
+  | 'overall_conversation_health'
+  | 'volume_spike'
+  | 'new_conversation_rate'
+  | 'opt_out_handling'
+  | 'flagged'
+  | 'other';
+
+/**
+ * The specific conversations behind the drivers, so partners can verify every
+ * claim against their own send logs. Each `chat_id` can be fetched via
+ * `GET /v3/chats/{chatId}` — its current health appears there.
+ */
+export interface ReputationEvidence {
+  /**
+   * Worst first — most messages sent after the stop request; honor these
+   * immediately.
+   */
+  opt_out_chats?: Array<ReputationOptOutChat>;
+
+  /**
+   * Up to 15, worst first.
+   */
+  unhealthy_chats?: Array<ReputationUnhealthyChat>;
+}
+
+export interface ReputationOptOutChat {
+  chat_id?: string;
+
+  /**
+   * Outbound messages sent after the recipient asked to stop.
+   */
+  messages_after_stop?: number;
+}
+
+export interface ReputationReport {
+  /**
+   * Ordered by `priority`; 1 = do first.
+   */
+  action_items?: Array<ReputationActionItem>;
+
+  /**
+   * Ranked, highest impact first.
+   */
+  drivers?: Array<ReputationDriver>;
+
+  /**
+   * The specific conversations behind the drivers, so partners can verify every
+   * claim against their own send logs. Each `chat_id` can be fetched via
+   * `GET /v3/chats/{chatId}` — its current health appears there.
+   */
+  evidence?: ReputationEvidence;
+
+  /**
+   * The `key` of the most important driver. Empty string when the line has nothing
+   * to act on — the report then carries a single reassurance action item. Its values
+   * are the `ReputationDriverKey` vocabulary — see that schema for what each means
+   * and what to do about it.
+   */
+  primary_driver?: string;
+
+  /**
+   * Current reputation of this phone line.
+   *
+   * - `HEALTHY` — The line is in good standing. Send normally.
+   * - `AT_RISK` — Warning signs on the line: engagement is low across many of its
+   *   conversations, or it's starting too many brand-new conversations in a single
+   *   day — and a spike in send volume can add to either. Slow the line's send pace,
+   *   avoid opening many new conversations at once, and review your messaging
+   *   patterns.
+   * - `CRITICAL` — Strong signals that messages from this line aren't landing well.
+   *   Pause outbound on the line until it recovers.
+   *
+   * Defaults to `HEALTHY` for lines that have not yet been scored.
+   */
+  severity?: 'HEALTHY' | 'AT_RISK' | 'CRITICAL';
+
+  /**
+   * Deterministic markdown rendering of this report, suitable for feeding directly
+   * to automated systems and AI agents as investigation context. Rendered from the
+   * structured fields above, which remain the source of truth.
+   */
+  summary_markdown?: string;
+}
+
+export interface ReputationUnhealthyChat {
+  chat_id?: string;
+
+  /**
+   * What is dragging this conversation down, in the same vocabulary as the report's
+   * drivers. Each key's meaning and the fix for it are documented on
+   * `ReputationDriverKey`.
+   */
+  driver_keys?: Array<ReputationDriverKey>;
+
+  /**
+   * The conversation's current health — the same value `GET /v3/chats/{chatId}`
+   * reports for it.
+   */
+  status?: 'AT_RISK' | 'CRITICAL' | 'OPTED_OUT';
 }
 
 export interface PhoneNumberUpdateResponse {
@@ -152,10 +421,27 @@ export interface PhoneNumberUpdateParams {
   forwarding_number: string | null;
 }
 
+export interface PhoneNumberGetReputationAuditParams {
+  /**
+   * The line in E.164 format.
+   */
+  phoneNumber: string;
+}
+
 export declare namespace PhoneNumbers {
   export {
+    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,
   };
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.35.0'; // x-release-please-version
+export const VERSION = '0.36.1'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.35.0";
+export declare const VERSION = "0.36.1";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.35.0";
+export declare const VERSION = "0.36.1";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.35.0'; // x-release-please-version
+exports.VERSION = '0.36.1'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.35.0'; // x-release-please-version
+export const VERSION = '0.36.1'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map