@linqapp/sdk 0.26.0 → 0.27.1

package/resources/webhooks.mjs

@@ -1,7 +1,15 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 import { APIResource } from "../core/resource.mjs";
+import { Webhook } from 'standardwebhooks';
 export class Webhooks extends APIResource {
-    events(body) {
+    unwrap(body, { headers, key }) {
+        if (headers !== undefined) {
+            const keyStr = key === undefined ? this._client.webhookSecret : key;
+            if (keyStr === null)
+                throw new Error('Webhook key must not be null in order to unwrap');
+            const wh = new Webhook(keyStr);
+            wh.verify(body, headers);
+        }
         return JSON.parse(body);
     }
 }

package/resources/webhooks.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.mjs","sourceRoot":"","sources":["../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAI/C,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAChD,CAAC;CACF"}
+{"version":3,"file":"webhooks.mjs","sourceRoot":"","sources":["../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAG/C,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC,MAAM,CACJ,IAAY,EACZ,EAAE,OAAO,EAAE,GAAG,EAAqD;QAEnE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAkB,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC;YACnF,IAAI,MAAM,KAAK,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;YACxF,MAAM,EAAE,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;YAC/B,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAChD,CAAC;CACF"}

package/src/client.ts

@@ -34,8 +34,8 @@ import {
 } from './resources/attachments';
 import {
   Capability,
+  CapabilityCheckIMessageParams,
   CapabilityCheckRCSParams,
-  CapabilityCheckiMessageParams,
   HandleCheck,
   HandleCheckResponse,
 } from './resources/capability';
@@ -77,7 +77,6 @@ import {
   ChatGroupNameUpdatedWebhookEvent,
   ChatTypingIndicatorStartedWebhookEvent,
   ChatTypingIndicatorStoppedWebhookEvent,
-  EventsWebhookEvent,
   MessageDeliveredWebhookEvent,
   MessageEditedWebhookEvent,
   MessageEventV2,
@@ -95,6 +94,7 @@ import {
   SchemasMediaPartResponse,
   SchemasMessageEffect,
   SchemasTextPartResponse,
+  UnwrapWebhookEvent,
   Webhooks,
 } from './resources/webhooks';
 import {
@@ -136,6 +136,16 @@ export interface ClientOptions {
    */
   apiKey?: string | undefined;
 
+  /**
+   * Webhook signing secret used by `client.webhooks.unwrap()` to verify the
+   * Standard Webhooks signature on incoming webhook requests.
+   *
+   * Format: a base64-encoded key, optionally with a `whsec_` prefix
+   * (e.g. `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=`).
+   *
+   */
+  webhookSecret?: string | null | undefined;
+
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
    *
@@ -210,6 +220,7 @@ export interface ClientOptions {
  */
 export class LinqAPIV3 {
   apiKey: string;
+  webhookSecret: string | null;
 
   baseURL: string;
   maxRetries: number;
@@ -227,6 +238,7 @@ export class LinqAPIV3 {
    * API Client for interfacing with the Linq API V3 API.
    *
    * @param {string | undefined} [opts.apiKey=process.env['LINQ_API_V3_API_KEY'] ?? undefined]
+   * @param {string | null | undefined} [opts.webhookSecret=process.env['LINQ_WEBHOOK_SECRET'] ?? null]
    * @param {string} [opts.baseURL=process.env['LINQ_API_V3_BASE_URL'] ?? https://api.linqapp.com/api/partner] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
@@ -238,6 +250,7 @@ export class LinqAPIV3 {
   constructor({
     baseURL = readEnv('LINQ_API_V3_BASE_URL'),
     apiKey = readEnv('LINQ_API_V3_API_KEY'),
+    webhookSecret = readEnv('LINQ_WEBHOOK_SECRET') ?? null,
     ...opts
   }: ClientOptions = {}) {
     if (apiKey === undefined) {
@@ -248,6 +261,7 @@ export class LinqAPIV3 {
 
     const options: ClientOptions = {
       apiKey,
+      webhookSecret,
       ...opts,
       baseURL: baseURL || `https://api.linqapp.com/api/partner`,
     };
@@ -282,6 +296,7 @@ export class LinqAPIV3 {
     this._options = options;
 
     this.apiKey = apiKey;
+    this.webhookSecret = webhookSecret;
   }
 
   /**
@@ -298,6 +313,7 @@ export class LinqAPIV3 {
       fetch: this.fetch,
       fetchOptions: this.fetchOptions,
       apiKey: this.apiKey,
+      webhookSecret: this.webhookSecret,
       ...options,
     });
     return client;
@@ -1446,7 +1462,7 @@ export declare namespace LinqAPIV3 {
     Capability as Capability,
     type HandleCheck as HandleCheck,
     type HandleCheckResponse as HandleCheckResponse,
-    type CapabilityCheckiMessageParams as CapabilityCheckiMessageParams,
+    type CapabilityCheckIMessageParams as CapabilityCheckIMessageParams,
     type CapabilityCheckRCSParams as CapabilityCheckRCSParams,
   };
 
@@ -1476,7 +1492,7 @@ export declare namespace LinqAPIV3 {
     type ChatTypingIndicatorStartedWebhookEvent as ChatTypingIndicatorStartedWebhookEvent,
     type ChatTypingIndicatorStoppedWebhookEvent as ChatTypingIndicatorStoppedWebhookEvent,
     type PhoneNumberStatusUpdatedWebhookEvent as PhoneNumberStatusUpdatedWebhookEvent,
-    type EventsWebhookEvent as EventsWebhookEvent,
+    type UnwrapWebhookEvent as UnwrapWebhookEvent,
   };
 
   export {

package/src/resources/capability.ts

@@ -15,13 +15,13 @@ export class Capability extends APIResource {
    * @example
    * ```ts
    * const handleCheckResponse =
-   *   await client.capability.checkiMessage({
+   *   await client.capability.checkIMessage({
    *     address: '+15551234567',
    *   });
    * ```
    */
-  checkiMessage(
-    body: CapabilityCheckiMessageParams,
+  checkIMessage(
+    body: CapabilityCheckIMessageParams,
     options?: RequestOptions,
   ): APIPromise<HandleCheckResponse> {
     return this._client.post('/v3/capability/check_imessage', { body, ...options });
@@ -68,7 +68,7 @@ export interface HandleCheckResponse {
   available: boolean;
 }
 
-export interface CapabilityCheckiMessageParams {
+export interface CapabilityCheckIMessageParams {
   /**
    * The recipient phone number or email address to check
    */
@@ -98,7 +98,7 @@ export declare namespace Capability {
   export {
     type HandleCheck as HandleCheck,
     type HandleCheckResponse as HandleCheckResponse,
-    type CapabilityCheckiMessageParams as CapabilityCheckiMessageParams,
+    type CapabilityCheckIMessageParams as CapabilityCheckIMessageParams,
     type CapabilityCheckRCSParams as CapabilityCheckRCSParams,
   };
 }

package/src/resources/chats/chats.ts

@@ -478,7 +478,7 @@ export interface MessageContent {
    *   sub-limit. For bulk media sends exceeding 40 files, pre-upload via
    *   `POST /v3/attachments` and reference by `attachment_id` or `download_url`.
    */
-  parts: Array<TextPart | MediaPart | LinkPart>;
+  parts: Array<TextPart | MediaPart | LinkPart | MessageContent.IMessageAppPart>;
 
   /**
    * iMessage effect to apply to this message (screen or bubble effect)
@@ -502,6 +502,122 @@ export interface MessageContent {
   reply_to?: MessagesAPI.ReplyTo;
 }
 
+export namespace MessageContent {
+  /**
+   * 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
+   * delivered over SMS/RCS. See the IMessageAppServiceUnsupported (2018) and
+   * RecipientUnsupportedMessageType (4005) error codes.
+   */
+  export interface IMessageAppPart {
+    /**
+     * Identifies the iMessage app (Messages app extension) that backs the card.
+     */
+    app: IMessageAppPart.App;
+
+    /**
+     * 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.
+     */
+    layout: IMessageAppPart.Layout;
+
+    /**
+     * Indicates this is an iMessage app card part.
+     */
+    type: 'imessage_app';
+
+    /**
+     * Absolute HTTPS URL delivered to the recipient's installed iMessage app when they
+     * tap the card. Opaque to Messages.
+     */
+    url: string;
+
+    /**
+     * Text shown on surfaces that cannot render the card (notifications, lock screen).
+     * Defaults to the caption when omitted.
+     */
+    fallback_text?: string;
+
+    /**
+     * Optional client-supplied identifier to correlate updatable/collaborative app
+     * sessions (advanced). Not interpreted by Synapse.
+     */
+    session_id?: string;
+  }
+
+  export namespace IMessageAppPart {
+    /**
+     * Identifies the iMessage app (Messages app extension) that backs the card.
+     */
+    export interface App {
+      /**
+       * Bundle identifier of the Messages app extension. Must not contain `:`.
+       */
+      bundle_id: string;
+
+      /**
+       * Display name of the app, shown by Messages' fallback UI.
+       */
+      name: string;
+
+      /**
+       * The app's 10-character uppercase alphanumeric team identifier.
+       */
+      team_id: string;
+
+      /**
+       * The owning app's App Store id (optional). When set, recipients without the
+       * iMessage app installed see a "Get the app" affordance.
+       */
+      app_store_id?: number;
+    }
+
+    /**
+     * 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.
+     */
+    export interface Layout {
+      /**
+       * Primary label, top-left and bold.
+       */
+      caption?: string;
+
+      /**
+       * Overlay text shown below `image_title`. Requires `image_url`.
+       */
+      image_subtitle?: string;
+
+      /**
+       * Overlay text shown above the image. Requires `image_url`.
+       */
+      image_title?: string;
+
+      /**
+       * Optional HTTPS URL of a preview image. The server downloads it and embeds it in
+       * the card as JPEG (10MB max, same fetch rules as media parts).
+       */
+      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 interface TextPart {
   /**
    * Indicates this is a text message part

package/src/resources/chats/messages.ts

@@ -138,17 +138,23 @@ export interface SentMessage {
   /**
    * Current delivery status of a message
    */
-  delivery_status: 'pending' | 'queued' | 'sent' | 'delivered' | 'failed';
+  delivery_status: 'pending' | 'queued' | 'sent' | 'delivered' | 'received' | 'read' | 'failed';
 
   /**
-   * Whether the message has been read
+   * @deprecated DEPRECATED: Use `delivery_status == "read"` instead. Whether the
+   * message has been read.
    */
   is_read: boolean;
 
   /**
    * Message parts in order (text, media, and link)
    */
-  parts: Array<Shared.TextPartResponse | Shared.MediaPartResponse | Shared.LinkPartResponse>;
+  parts: Array<
+    | Shared.TextPartResponse
+    | Shared.MediaPartResponse
+    | Shared.LinkPartResponse
+    | SentMessage.IMessageAppPartResponse
+  >;
 
   /**
    * When the message was actually sent (null if still queued)
@@ -186,6 +192,121 @@ export interface SentMessage {
   service?: Shared.ServiceType | null;
 }
 
+export namespace SentMessage {
+  /**
+   * An iMessage app card part.
+   */
+  export interface IMessageAppPartResponse {
+    /**
+     * Identifies the iMessage app (Messages app extension) that backs the card.
+     */
+    app: IMessageAppPartResponse.App;
+
+    /**
+     * 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.
+     */
+    layout: IMessageAppPartResponse.Layout;
+
+    /**
+     * Reactions on this message part
+     */
+    reactions: Array<Shared.Reaction> | null;
+
+    /**
+     * Indicates this is an iMessage app card part.
+     */
+    type: 'imessage_app';
+
+    /**
+     * The URL delivered to the iMessage app on tap.
+     */
+    url: string;
+
+    /**
+     * Fallback text for surfaces that cannot render the card.
+     */
+    fallback_text?: string | null;
+
+    /**
+     * Client-supplied session identifier, echoed back when provided.
+     */
+    session_id?: string | null;
+  }
+
+  export namespace IMessageAppPartResponse {
+    /**
+     * Identifies the iMessage app (Messages app extension) that backs the card.
+     */
+    export interface App {
+      /**
+       * Bundle identifier of the Messages app extension. Must not contain `:`.
+       */
+      bundle_id: string;
+
+      /**
+       * Display name of the app, shown by Messages' fallback UI.
+       */
+      name: string;
+
+      /**
+       * The app's 10-character uppercase alphanumeric team identifier.
+       */
+      team_id: string;
+
+      /**
+       * The owning app's App Store id (optional). When set, recipients without the
+       * iMessage app installed see a "Get the app" affordance.
+       */
+      app_store_id?: number;
+    }
+
+    /**
+     * 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.
+     */
+    export interface Layout {
+      /**
+       * Primary label, top-left and bold.
+       */
+      caption?: string;
+
+      /**
+       * Overlay text shown below `image_title`. Requires `image_url`.
+       */
+      image_subtitle?: string;
+
+      /**
+       * Overlay text shown above the image. Requires `image_url`.
+       */
+      image_title?: string;
+
+      /**
+       * Optional HTTPS URL of a preview image. The server downloads it and embeds it in
+       * the card as JPEG (10MB max, same fetch rules as media parts).
+       */
+      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;
+    }
+  }
+}
+
 /**
  * Response for sending a message to a chat
  */

package/src/resources/index.ts

@@ -12,7 +12,7 @@ export {
   Capability,
   type HandleCheck,
   type HandleCheckResponse,
-  type CapabilityCheckiMessageParams,
+  type CapabilityCheckIMessageParams,
   type CapabilityCheckRCSParams,
 } from './capability';
 export {
@@ -88,5 +88,5 @@ export {
   type ChatTypingIndicatorStartedWebhookEvent,
   type ChatTypingIndicatorStoppedWebhookEvent,
   type PhoneNumberStatusUpdatedWebhookEvent,
-  type EventsWebhookEvent,
+  type UnwrapWebhookEvent,
 } from './webhooks';

package/src/resources/messages.ts

@@ -159,7 +159,14 @@ export interface Message {
   created_at: string;
 
   /**
-   * Whether the message has been delivered
+   * Current delivery status of a message
+   */
+  delivery_status: 'pending' | 'queued' | 'sent' | 'delivered' | 'received' | 'read' | 'failed';
+
+  /**
+   * @deprecated DEPRECATED: Use `delivery_status` instead (true when
+   * `delivery_status` is `delivered` or `read`). Whether the message has been
+   * delivered.
    */
   is_delivered: boolean;
 
@@ -169,7 +176,8 @@ export interface Message {
   is_from_me: boolean;
 
   /**
-   * Whether the message has been read
+   * @deprecated DEPRECATED: Use `delivery_status == "read"` instead. Whether the
+   * message has been read.
    */
   is_read: boolean;
 
@@ -202,7 +210,12 @@ export interface Message {
   /**
    * Message parts in order (text, media, and link)
    */
-  parts?: Array<Shared.TextPartResponse | Shared.MediaPartResponse | Shared.LinkPartResponse> | null;
+  parts?: Array<
+    | Shared.TextPartResponse
+    | Shared.MediaPartResponse
+    | Shared.LinkPartResponse
+    | Message.IMessageAppPartResponse
+  > | null;
 
   /**
    * Messaging service type
@@ -230,6 +243,121 @@ export interface Message {
   service?: Shared.ServiceType | null;
 }
 
+export namespace Message {
+  /**
+   * An iMessage app card part.
+   */
+  export interface IMessageAppPartResponse {
+    /**
+     * Identifies the iMessage app (Messages app extension) that backs the card.
+     */
+    app: IMessageAppPartResponse.App;
+
+    /**
+     * 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.
+     */
+    layout: IMessageAppPartResponse.Layout;
+
+    /**
+     * Reactions on this message part
+     */
+    reactions: Array<Shared.Reaction> | null;
+
+    /**
+     * Indicates this is an iMessage app card part.
+     */
+    type: 'imessage_app';
+
+    /**
+     * The URL delivered to the iMessage app on tap.
+     */
+    url: string;
+
+    /**
+     * Fallback text for surfaces that cannot render the card.
+     */
+    fallback_text?: string | null;
+
+    /**
+     * Client-supplied session identifier, echoed back when provided.
+     */
+    session_id?: string | null;
+  }
+
+  export namespace IMessageAppPartResponse {
+    /**
+     * Identifies the iMessage app (Messages app extension) that backs the card.
+     */
+    export interface App {
+      /**
+       * Bundle identifier of the Messages app extension. Must not contain `:`.
+       */
+      bundle_id: string;
+
+      /**
+       * Display name of the app, shown by Messages' fallback UI.
+       */
+      name: string;
+
+      /**
+       * The app's 10-character uppercase alphanumeric team identifier.
+       */
+      team_id: string;
+
+      /**
+       * The owning app's App Store id (optional). When set, recipients without the
+       * iMessage app installed see a "Get the app" affordance.
+       */
+      app_store_id?: number;
+    }
+
+    /**
+     * 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.
+     */
+    export interface Layout {
+      /**
+       * Primary label, top-left and bold.
+       */
+      caption?: string;
+
+      /**
+       * Overlay text shown below `image_title`. Requires `image_url`.
+       */
+      image_subtitle?: string;
+
+      /**
+       * Overlay text shown above the image. Requires `image_url`.
+       */
+      image_title?: string;
+
+      /**
+       * Optional HTTPS URL of a preview image. The server downloads it and embeds it in
+       * the card as JPEG (10MB max, same fetch rules as media parts).
+       */
+      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;
+    }
+  }
+}
+
 /**
  * iMessage effect applied to a message (screen or bubble effect)
  */