@linqapp/sdk 0.1.5 → 0.4.0

package/src/resources/messages.ts

@@ -3,10 +3,20 @@
 import { APIResource } from '../core/resource';
 import * as Shared from './shared';
 import { APIPromise } from '../core/api-promise';
+import { ListMessagesPagination, type ListMessagesPaginationParams, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Messages are individual text or multimedia communications within a chat thread.
+ *
+ * Messages can include text, attachments, 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.
+ */
 export class Messages extends APIResource {
   /**
    * Retrieve a specific message by its ID. This endpoint returns the full message
@@ -23,6 +33,21 @@ export class Messages extends APIResource {
     return this._client.get(path`/v3/messages/${messageID}`, options);
   }
 
+  /**
+   * Edit the text content of a specific part of a previously sent message.
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.update(
+   *   '69a37c7d-af4f-4b5e-af42-e28e98ce873a',
+   *   { text: 'This is the edited message content' },
+   * );
+   * ```
+   */
+  update(messageID: string, body: MessageUpdateParams, options?: RequestOptions): APIPromise<Message> {
+    return this._client.patch(path`/v3/messages/${messageID}`, { body, ...options });
+  }
+
   /**
    * Deletes a message from the Linq API only. This does NOT unsend or remove the
    * message from the actual chat - recipients will still see the message.
@@ -86,20 +111,28 @@ export class Messages extends APIResource {
    *
    * @example
    * ```ts
-   * const response = await client.messages.retrieveThread(
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.messages.listMessagesThread(
    *   '69a37c7d-af4f-4b5e-af42-e28e98ce873a',
-   * );
+   * )) {
+   *   // ...
+   * }
    * ```
    */
-  retrieveThread(
+  listMessagesThread(
     messageID: string,
-    query: MessageRetrieveThreadParams | null | undefined = {},
+    query: MessageListMessagesThreadParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<MessageRetrieveThreadResponse> {
-    return this._client.get(path`/v3/messages/${messageID}/thread`, { query, ...options });
+  ): PagePromise<MessagesListMessagesPagination, Message> {
+    return this._client.getAPIList(path`/v3/messages/${messageID}/thread`, ListMessagesPagination<Message>, {
+      query,
+      ...options,
+    });
   }
 }
 
+export type MessagesListMessagesPagination = ListMessagesPagination<Message>;
+
 export interface ChatHandle {
   /**
    * Unique identifier for this handle
@@ -137,46 +170,6 @@ export interface ChatHandle {
   status?: 'active' | 'left' | 'removed' | null;
 }
 
-/**
- * A media attachment part
- */
-export interface MediaPart {
-  /**
-   * Unique attachment identifier
-   */
-  id: string;
-
-  /**
-   * Original filename
-   */
-  filename: string;
-
-  /**
-   * MIME type of the file
-   */
-  mime_type: string;
-
-  /**
-   * Reactions on this message part
-   */
-  reactions: Array<Reaction> | null;
-
-  /**
-   * File size in bytes
-   */
-  size_bytes: number;
-
-  /**
-   * Indicates this is a media attachment part
-   */
-  type: 'media';
-
-  /**
-   * Presigned URL for downloading the attachment (expires in 1 hour).
-   */
-  url: string;
-}
-
 export interface Message {
   /**
    * Unique identifier for the message
@@ -237,7 +230,7 @@ export interface Message {
   /**
    * Message parts in order (text and media)
    */
-  parts?: Array<TextPart | MediaPart> | null;
+  parts?: Array<Shared.TextPartResponse | Shared.MediaPartResponse> | null;
 
   /**
    * Messaging service type
@@ -378,26 +371,6 @@ export interface ReplyTo {
   part_index?: number;
 }
 
-/**
- * A text message part
- */
-export interface TextPart {
-  /**
-   * Reactions on this message part
-   */
-  reactions: Array<Reaction> | null;
-
-  /**
-   * Indicates this is a text message part
-   */
-  type: 'text';
-
-  /**
-   * The text content
-   */
-  value: string;
-}
-
 export interface MessageAddReactionResponse {
   message?: string;
 
@@ -406,19 +379,16 @@ export interface MessageAddReactionResponse {
   trace_id?: string;
 }
 
-/**
- * Response containing messages in a thread with pagination
- */
-export interface MessageRetrieveThreadResponse {
+export interface MessageUpdateParams {
   /**
-   * Messages in the thread, ordered by the specified order parameter
+   * New text content for the message part
    */
-  messages: Array<Message>;
+  text: string;
 
   /**
-   * Cursor for fetching the next page of results (null if no more results)
+   * Index of the message part to edit. Defaults to 0.
    */
-  next_cursor?: string | null;
+  part_index?: number;
 }
 
 export interface MessageDeleteParams {
@@ -454,17 +424,7 @@ export interface MessageAddReactionParams {
   part_index?: number;
 }
 
-export interface MessageRetrieveThreadParams {
-  /**
-   * Pagination cursor from previous next_cursor response
-   */
-  cursor?: string;
-
-  /**
-   * Maximum number of messages to return
-   */
-  limit?: number;
-
+export interface MessageListMessagesThreadParams extends ListMessagesPaginationParams {
   /**
    * Sort order for messages (asc = oldest first, desc = newest first)
    */
@@ -474,17 +434,16 @@ export interface MessageRetrieveThreadParams {
 export declare namespace Messages {
   export {
     type ChatHandle as ChatHandle,
-    type MediaPart as MediaPart,
     type Message as Message,
     type MessageEffect as MessageEffect,
     type Reaction as Reaction,
     type ReactionType as ReactionType,
     type ReplyTo as ReplyTo,
-    type TextPart as TextPart,
     type MessageAddReactionResponse as MessageAddReactionResponse,
-    type MessageRetrieveThreadResponse as MessageRetrieveThreadResponse,
+    type MessagesListMessagesPagination as MessagesListMessagesPagination,
+    type MessageUpdateParams as MessageUpdateParams,
     type MessageDeleteParams as MessageDeleteParams,
     type MessageAddReactionParams as MessageAddReactionParams,
-    type MessageRetrieveThreadParams as MessageRetrieveThreadParams,
+    type MessageListMessagesThreadParams as MessageListMessagesThreadParams,
   };
 }

package/src/resources/phone-numbers.ts

@@ -4,6 +4,15 @@ import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Phone Numbers represent the phone numbers assigned to your partner account.
+ *
+ * Use the list phone numbers endpoint to discover which phone numbers are available
+ * for sending messages.
+ *
+ * When creating chats, listing chats, or sending a voice memo, use one of your assigned phone numbers
+ * in the `from` field.
+ */
 export class PhoneNumbers extends APIResource {
   /**
    * Returns all phone numbers assigned to the authenticated partner. Use this

package/src/resources/phonenumbers.ts

@@ -4,6 +4,15 @@ import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Phone Numbers represent the phone numbers assigned to your partner account.
+ *
+ * Use the list phone numbers endpoint to discover which phone numbers are available
+ * for sending messages.
+ *
+ * When creating chats, listing chats, or sending a voice memo, use one of your assigned phone numbers
+ * in the `from` field.
+ */
 export class Phonenumbers extends APIResource {
   /**
    * **Deprecated.** Use `GET /v3/phone_numbers` instead.

package/src/resources/shared.ts

@@ -1,6 +1,68 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import * as MessagesAPI from './messages';
+
+/**
+ * A media attachment part
+ */
+export interface MediaPartResponse {
+  /**
+   * Unique attachment identifier
+   */
+  id: string;
+
+  /**
+   * Original filename
+   */
+  filename: string;
+
+  /**
+   * MIME type of the file
+   */
+  mime_type: string;
+
+  /**
+   * Reactions on this message part
+   */
+  reactions: Array<MessagesAPI.Reaction> | null;
+
+  /**
+   * File size in bytes
+   */
+  size_bytes: number;
+
+  /**
+   * Indicates this is a media attachment part
+   */
+  type: 'media';
+
+  /**
+   * Presigned URL for downloading the attachment (expires in 1 hour).
+   */
+  url: string;
+}
+
 /**
  * Messaging service type
  */
 export type ServiceType = 'iMessage' | 'SMS' | 'RCS';
+
+/**
+ * A text message part
+ */
+export interface TextPartResponse {
+  /**
+   * Reactions on this message part
+   */
+  reactions: Array<MessagesAPI.Reaction> | null;
+
+  /**
+   * Indicates this is a text message part
+   */
+  type: 'text';
+
+  /**
+   * The text content
+   */
+  value: string;
+}

package/src/resources/webhook-events.ts

@@ -4,6 +4,95 @@ import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
+/**
+ * Webhook Subscriptions allow you to receive real-time notifications when events
+ * occur on your account.
+ *
+ * Configure webhook endpoints to receive events such as messages sent/received,
+ * delivery status changes, reactions, typing indicators, and more.
+ *
+ * Failed deliveries (5xx, 429, network errors) are retried up to 10 times over
+ * ~2 hours with exponential backoff. Each event includes a unique ID for
+ * deduplication.
+ *
+ * ## Webhook Headers
+ *
+ * Each webhook request includes the following headers:
+ *
+ * | Header | Description |
+ * |--------|-------------|
+ * | `X-Webhook-Event` | The event type (e.g., `message.sent`, `message.received`) |
+ * | `X-Webhook-Subscription-ID` | Your webhook subscription ID |
+ * | `X-Webhook-Timestamp` | Unix timestamp (seconds) when the webhook was sent |
+ * | `X-Webhook-Signature` | HMAC-SHA256 signature for verification |
+ *
+ * ## Verifying Webhook Signatures
+ *
+ * All webhooks are signed using HMAC-SHA256. You should always verify the signature
+ * to ensure the webhook originated from Linq and hasn't been tampered with.
+ *
+ * **Signature Construction:**
+ *
+ * The signature is computed over a concatenation of the timestamp and payload:
+ *
+ * ```
+ * {timestamp}.{payload}
+ * ```
+ *
+ * Where:
+ * - `timestamp` is the value from the `X-Webhook-Timestamp` header
+ * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ *
+ * **Verification Steps:**
+ *
+ * 1. Extract the `X-Webhook-Timestamp` and `X-Webhook-Signature` headers
+ * 2. Get the raw request body bytes (do not parse and re-serialize)
+ * 3. Concatenate: `"{timestamp}.{payload}"`
+ * 4. Compute HMAC-SHA256 using your signing secret as the key
+ * 5. Hex-encode the result and compare with `X-Webhook-Signature`
+ * 6. Use constant-time comparison to prevent timing attacks
+ *
+ * **Example (Python):**
+ *
+ * ```python
+ * import hmac
+ * import hashlib
+ *
+ * def verify_webhook(signing_secret, payload, timestamp, signature):
+ *     message = f"{timestamp}.{payload.decode('utf-8')}"
+ *     expected = hmac.new(
+ *         signing_secret.encode('utf-8'),
+ *         message.encode('utf-8'),
+ *         hashlib.sha256
+ *     ).hexdigest()
+ *     return hmac.compare_digest(expected, signature)
+ * ```
+ *
+ * **Example (Node.js):**
+ *
+ * ```javascript
+ * const crypto = require('crypto');
+ *
+ * function verifyWebhook(signingSecret, payload, timestamp, signature) {
+ *   const message = `${timestamp}.${payload}`;
+ *   const expected = crypto
+ *     .createHmac('sha256', signingSecret)
+ *     .update(message)
+ *     .digest('hex');
+ *   return crypto.timingSafeEqual(
+ *     Buffer.from(expected),
+ *     Buffer.from(signature)
+ *   );
+ * }
+ * ```
+ *
+ * **Security Best Practices:**
+ *
+ * - Reject webhooks with timestamps older than 5 minutes to prevent replay attacks
+ * - Always use constant-time comparison for signature verification
+ * - Store your signing secret securely (e.g., environment variable, secrets manager)
+ * - Return a 2xx status code quickly, then process the webhook asynchronously
+ */
 export class WebhookEvents extends APIResource {
   /**
    * Returns all available webhook event types that can be subscribed to. Use this
@@ -24,6 +113,7 @@ export type WebhookEventType =
   | 'message.read'
   | 'message.delivered'
   | 'message.failed'
+  | 'message.edited'
   | 'reaction.added'
   | 'reaction.removed'
   | 'participant.added'

package/src/resources/webhook-subscriptions.ts

@@ -7,6 +7,95 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Webhook Subscriptions allow you to receive real-time notifications when events
+ * occur on your account.
+ *
+ * Configure webhook endpoints to receive events such as messages sent/received,
+ * delivery status changes, reactions, typing indicators, and more.
+ *
+ * Failed deliveries (5xx, 429, network errors) are retried up to 10 times over
+ * ~2 hours with exponential backoff. Each event includes a unique ID for
+ * deduplication.
+ *
+ * ## Webhook Headers
+ *
+ * Each webhook request includes the following headers:
+ *
+ * | Header | Description |
+ * |--------|-------------|
+ * | `X-Webhook-Event` | The event type (e.g., `message.sent`, `message.received`) |
+ * | `X-Webhook-Subscription-ID` | Your webhook subscription ID |
+ * | `X-Webhook-Timestamp` | Unix timestamp (seconds) when the webhook was sent |
+ * | `X-Webhook-Signature` | HMAC-SHA256 signature for verification |
+ *
+ * ## Verifying Webhook Signatures
+ *
+ * All webhooks are signed using HMAC-SHA256. You should always verify the signature
+ * to ensure the webhook originated from Linq and hasn't been tampered with.
+ *
+ * **Signature Construction:**
+ *
+ * The signature is computed over a concatenation of the timestamp and payload:
+ *
+ * ```
+ * {timestamp}.{payload}
+ * ```
+ *
+ * Where:
+ * - `timestamp` is the value from the `X-Webhook-Timestamp` header
+ * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ *
+ * **Verification Steps:**
+ *
+ * 1. Extract the `X-Webhook-Timestamp` and `X-Webhook-Signature` headers
+ * 2. Get the raw request body bytes (do not parse and re-serialize)
+ * 3. Concatenate: `"{timestamp}.{payload}"`
+ * 4. Compute HMAC-SHA256 using your signing secret as the key
+ * 5. Hex-encode the result and compare with `X-Webhook-Signature`
+ * 6. Use constant-time comparison to prevent timing attacks
+ *
+ * **Example (Python):**
+ *
+ * ```python
+ * import hmac
+ * import hashlib
+ *
+ * def verify_webhook(signing_secret, payload, timestamp, signature):
+ *     message = f"{timestamp}.{payload.decode('utf-8')}"
+ *     expected = hmac.new(
+ *         signing_secret.encode('utf-8'),
+ *         message.encode('utf-8'),
+ *         hashlib.sha256
+ *     ).hexdigest()
+ *     return hmac.compare_digest(expected, signature)
+ * ```
+ *
+ * **Example (Node.js):**
+ *
+ * ```javascript
+ * const crypto = require('crypto');
+ *
+ * function verifyWebhook(signingSecret, payload, timestamp, signature) {
+ *   const message = `${timestamp}.${payload}`;
+ *   const expected = crypto
+ *     .createHmac('sha256', signingSecret)
+ *     .update(message)
+ *     .digest('hex');
+ *   return crypto.timingSafeEqual(
+ *     Buffer.from(expected),
+ *     Buffer.from(signature)
+ *   );
+ * }
+ * ```
+ *
+ * **Security Best Practices:**
+ *
+ * - Reject webhooks with timestamps older than 5 minutes to prevent replay attacks
+ * - Always use constant-time comparison for signature verification
+ * - Store your signing secret securely (e.g., environment variable, secrets manager)
+ * - Return a 2xx status code quickly, then process the webhook asynchronously
+ */
 export class WebhookSubscriptions extends APIResource {
   /**
    * Create a new webhook subscription to receive events at a target URL. Upon