@linqapp/sdk 0.24.2 → 0.26.0

package/src/resources/chats/location.ts

@@ -0,0 +1,138 @@
+// 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 { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Request and retrieve real-time location data via iMessage.
+ *
+ * Use these endpoints to request a contact's location, retrieve location data
+ * for contacts who are sharing with you, and subscribe to webhooks when someone
+ * starts or stops sharing their location.
+ *
+ * **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
+ * `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
+ */
+export class Location extends APIResource {
+  /**
+   * Send a location sharing request to a contact. They will receive an iMessage
+   * prompt asking them to share their location.
+   *
+   * Location requests only work in **1:1 iMessage chats** (Apple limitation).
+   * Attempting to request location in a group chat, or in an SMS or RCS chat,
+   * returns `409` (Operation not supported on this chat's service type).
+   *
+   * @example
+   * ```ts
+   * const locationRequestResponse =
+   *   await client.chats.location.request(
+   *     '975d0776-bd17-4273-8337-f346b4c661b0',
+   *   );
+   * ```
+   */
+  request(chatID: string, options?: RequestOptions): APIPromise<LocationRequestResponse> {
+    return this._client.post(path`/v3/chats/${chatID}/location/request`, options);
+  }
+
+  /**
+   * Retrieve the current location for contacts sharing with you in a chat.
+   *
+   * Returns a [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946)
+   * `FeatureCollection` with a `Feature` for each participant actively sharing their
+   * location.
+   *
+   * Works for both 1:1 and group chats. In group chats, returns a separate feature
+   * for each participant who is sharing. Each feature's `properties.handle`
+   * identifies the user.
+   *
+   * Returns an empty `features` array if no one is sharing or no location data is
+   * available yet.
+   *
+   * @example
+   * ```ts
+   * const getChatLocationResponse =
+   *   await client.chats.location.retrieve(
+   *     '975d0776-bd17-4273-8337-f346b4c661b0',
+   *   );
+   * ```
+   */
+  retrieve(chatID: string, options?: RequestOptions): APIPromise<GetChatLocationResponse> {
+    return this._client.get(path`/v3/chats/${chatID}/location`, {
+      ...options,
+      headers: buildHeaders([{ Accept: 'application/geo+json' }, options?.headers]),
+    });
+  }
+}
+
+export interface GetChatLocationResponse {
+  data: GetChatLocationResponse.Data;
+
+  success: boolean;
+}
+
+export namespace GetChatLocationResponse {
+  export interface Data {
+    features: Array<Data.Feature>;
+
+    type: 'FeatureCollection';
+  }
+
+  export namespace Data {
+    export interface Feature {
+      geometry: Feature.Geometry;
+
+      properties: Feature.Properties;
+
+      type: 'Feature';
+    }
+
+    export namespace Feature {
+      export interface Geometry {
+        /**
+         * [longitude, latitude] or [longitude, latitude, altitude]
+         */
+        coordinates: Array<number>;
+
+        type: 'Point';
+      }
+
+      export interface Properties {
+        /**
+         * Phone number or email of the person sharing their location
+         */
+        handle: string;
+
+        /**
+         * Full street address
+         */
+        address?: string;
+
+        /**
+         * City or locality name
+         */
+        locality?: string;
+
+        /**
+         * When the location was last updated
+         */
+        updated_at?: string;
+      }
+    }
+  }
+}
+
+export interface LocationRequestResponse {
+  message: string;
+
+  success: boolean;
+}
+
+export declare namespace Location {
+  export {
+    type GetChatLocationResponse as GetChatLocationResponse,
+    type LocationRequestResponse as LocationRequestResponse,
+  };
+}

package/src/resources/chats/messages.ts

@@ -35,31 +35,6 @@ import { path } from '../../internal/utils/path';
  * - Maximum URL length: 2,048 characters.
  */
 export class Messages extends APIResource {
-  /**
-   * Retrieve messages from a specific chat with pagination support.
-   *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const message of client.chats.messages.list(
-   *   '550e8400-e29b-41d4-a716-446655440000',
-   * )) {
-   *   // ...
-   * }
-   * ```
-   */
-  list(
-    chatID: string,
-    query: MessageListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<MessagesListMessagesPagination, MessagesAPI.Message> {
-    return this._client.getAPIList(
-      path`/v3/chats/${chatID}/messages`,
-      ListMessagesPagination<MessagesAPI.Message>,
-      { query, ...options },
-    );
-  }
-
   /**
    * Send a message to an existing chat. Use this endpoint when you already have a
    * chat ID and want to send additional messages to it.
@@ -119,6 +94,31 @@ export class Messages extends APIResource {
   send(chatID: string, body: MessageSendParams, options?: RequestOptions): APIPromise<MessageSendResponse> {
     return this._client.post(path`/v3/chats/${chatID}/messages`, { body, ...options });
   }
+
+  /**
+   * Retrieve messages from a specific chat with pagination support.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.chats.messages.list(
+   *   '550e8400-e29b-41d4-a716-446655440000',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    chatID: string,
+    query: MessageListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<MessagesListMessagesPagination, MessagesAPI.Message> {
+    return this._client.getAPIList(
+      path`/v3/chats/${chatID}/messages`,
+      ListMessagesPagination<MessagesAPI.Message>,
+      { query, ...options },
+    );
+  }
 }
 
 /**
@@ -201,8 +201,6 @@ export interface MessageSendResponse {
   message: SentMessage;
 }
 
-export interface MessageListParams extends ListMessagesPaginationParams {}
-
 export interface MessageSendParams {
   /**
    * Message content container. Groups all message-related fields together,
@@ -212,12 +210,14 @@ export interface MessageSendParams {
   message: ChatsAPI.MessageContent;
 }
 
+export interface MessageListParams extends ListMessagesPaginationParams {}
+
 export declare namespace Messages {
   export {
     type SentMessage as SentMessage,
     type MessageSendResponse as MessageSendResponse,
-    type MessageListParams as MessageListParams,
     type MessageSendParams as MessageSendParams,
+    type MessageListParams as MessageListParams,
   };
 }
 

package/src/resources/contact-card.ts

@@ -14,6 +14,22 @@ 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.
@@ -40,22 +56,6 @@ export class ContactCard extends APIResource {
     return this._client.post('/v3/contact_card', { body, ...options });
   }
 
-  /**
-   * 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 an existing active contact card for a phone number.
    *
@@ -127,6 +127,14 @@ 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.
@@ -150,14 +158,6 @@ 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
@@ -184,8 +184,8 @@ export declare namespace ContactCard {
   export {
     type SetContactCard as SetContactCard,
     type ContactCardRetrieveResponse as ContactCardRetrieveResponse,
-    type ContactCardCreateParams as ContactCardCreateParams,
     type ContactCardRetrieveParams as ContactCardRetrieveParams,
+    type ContactCardCreateParams as ContactCardCreateParams,
     type ContactCardUpdateParams as ContactCardUpdateParams,
   };
 }

package/src/resources/index.ts

@@ -27,8 +27,8 @@ export {
   type ChatLeaveChatResponse,
   type ChatSendVoicememoResponse,
   type ChatCreateParams,
-  type ChatUpdateParams,
   type ChatListChatsParams,
+  type ChatUpdateParams,
   type ChatSendVoicememoParams,
   type ChatsListChatsPagination,
 } from './chats/chats';
@@ -36,8 +36,8 @@ export {
   ContactCard,
   type SetContactCard,
   type ContactCardRetrieveResponse,
-  type ContactCardCreateParams,
   type ContactCardRetrieveParams,
+  type ContactCardCreateParams,
   type ContactCardUpdateParams,
 } from './contact-card';
 export {
@@ -46,9 +46,9 @@ export {
   type MessageEffect,
   type ReplyTo,
   type MessageAddReactionResponse,
-  type MessageUpdateParams,
-  type MessageAddReactionParams,
   type MessageListMessagesThreadParams,
+  type MessageAddReactionParams,
+  type MessageUpdateParams,
   type MessagesListMessagesPagination,
 } from './messages';
 export { PhoneNumbers, type PhoneNumberListResponse } from './phone-numbers';

package/src/resources/messages.ts

@@ -30,36 +30,47 @@ import { path } from '../internal/utils/path';
  */
 export class Messages extends APIResource {
   /**
-   * Retrieve a specific message by its ID. This endpoint returns the full message
-   * details including text, attachments, reactions, and metadata.
+   * Retrieve all messages in a conversation thread. Given any message ID in the
+   * thread, returns the originator message and all replies in chronological order.
+   *
+   * If the message is not part of a thread, returns just that single message.
+   *
+   * Supports pagination and configurable ordering.
    *
    * @example
    * ```ts
-   * const message = await client.messages.retrieve(
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.messages.listMessagesThread(
    *   '69a37c7d-af4f-4b5e-af42-e28e98ce873a',
-   * );
+   * )) {
+   *   // ...
+   * }
    * ```
    */
-  retrieve(messageID: string, options?: RequestOptions): APIPromise<Message> {
-    return this._client.get(path`/v3/messages/${messageID}`, options);
+  listMessagesThread(
+    messageID: string,
+    query: MessageListMessagesThreadParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<MessagesListMessagesPagination, Message> {
+    return this._client.getAPIList(path`/v3/messages/${messageID}/thread`, ListMessagesPagination<Message>, {
+      query,
+      ...options,
+    });
   }
 
   /**
-   * Edit the text content of a specific part of a previously sent message.
-   *
-   * **Note:** A message can be edited up to 5 times, and only within 15 minutes of
-   * when it was originally sent.
+   * Retrieve a specific message by its ID. This endpoint returns the full message
+   * details including text, attachments, reactions, and metadata.
    *
    * @example
    * ```ts
-   * const message = await client.messages.update(
+   * const message = await client.messages.retrieve(
    *   '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 });
+  retrieve(messageID: string, options?: RequestOptions): APIPromise<Message> {
+    return this._client.get(path`/v3/messages/${messageID}`, options);
   }
 
   /**
@@ -111,32 +122,21 @@ export class Messages extends APIResource {
   }
 
   /**
-   * Retrieve all messages in a conversation thread. Given any message ID in the
-   * thread, returns the originator message and all replies in chronological order.
-   *
-   * If the message is not part of a thread, returns just that single message.
+   * Edit the text content of a specific part of a previously sent message.
    *
-   * Supports pagination and configurable ordering.
+   * **Note:** A message can be edited up to 5 times, and only within 15 minutes of
+   * when it was originally sent.
    *
    * @example
    * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const message of client.messages.listMessagesThread(
+   * const message = await client.messages.update(
    *   '69a37c7d-af4f-4b5e-af42-e28e98ce873a',
-   * )) {
-   *   // ...
-   * }
+   *   { text: 'This is the edited message content' },
+   * );
    * ```
    */
-  listMessagesThread(
-    messageID: string,
-    query: MessageListMessagesThreadParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<MessagesListMessagesPagination, Message> {
-    return this._client.getAPIList(path`/v3/messages/${messageID}/thread`, ListMessagesPagination<Message>, {
-      query,
-      ...options,
-    });
+  update(messageID: string, body: MessageUpdateParams, options?: RequestOptions): APIPromise<Message> {
+    return this._client.patch(path`/v3/messages/${messageID}`, { body, ...options });
   }
 }
 
@@ -274,16 +274,11 @@ export interface MessageAddReactionResponse {
   trace_id?: string;
 }
 
-export interface MessageUpdateParams {
-  /**
-   * New text content for the message part
-   */
-  text: string;
-
+export interface MessageListMessagesThreadParams extends ListMessagesPaginationParams {
   /**
-   * Index of the message part to edit. Defaults to 0.
+   * Sort order for messages (asc = oldest first, desc = newest first)
    */
-  part_index?: number;
+  order?: 'asc' | 'desc';
 }
 
 export interface MessageAddReactionParams {
@@ -312,11 +307,16 @@ export interface MessageAddReactionParams {
   part_index?: number;
 }
 
-export interface MessageListMessagesThreadParams extends ListMessagesPaginationParams {
+export interface MessageUpdateParams {
   /**
-   * Sort order for messages (asc = oldest first, desc = newest first)
+   * New text content for the message part
    */
-  order?: 'asc' | 'desc';
+  text: string;
+
+  /**
+   * Index of the message part to edit. Defaults to 0.
+   */
+  part_index?: number;
 }
 
 export declare namespace Messages {
@@ -326,8 +326,8 @@ export declare namespace Messages {
     type ReplyTo as ReplyTo,
     type MessageAddReactionResponse as MessageAddReactionResponse,
     type MessagesListMessagesPagination as MessagesListMessagesPagination,
-    type MessageUpdateParams as MessageUpdateParams,
-    type MessageAddReactionParams as MessageAddReactionParams,
     type MessageListMessagesThreadParams as MessageListMessagesThreadParams,
+    type MessageAddReactionParams as MessageAddReactionParams,
+    type MessageUpdateParams as MessageUpdateParams,
   };
 }

package/src/resources/webhook-events.ts

@@ -17,55 +17,82 @@ import { RequestOptions } from '../internal/request-options';
  *
  * ## Webhook Headers
  *
- * Each webhook request includes the following headers:
+ * All webhook requests include two sets of headers. **If you have an existing integration
+ * using the `X-Webhook-*` headers, nothing changes** — those headers are still sent on
+ * every delivery and work exactly as before. The new `webhook-*` headers follow the
+ * [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) specification.
+ * You can safely ignore them if your current verification code works and you don't want to use this convention.
+ *
+ * ### Standard Webhooks Headers (Recommended)
+ *
+ * Used by [our SDK](https://github.com/linq-team/linq-node) and any [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks).
  *
  * | 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 |
+ * | `webhook-id` | Unique event identifier (use as idempotency key) |
+ * | `webhook-timestamp` | Unix timestamp (seconds) when the webhook was sent |
+ * | `webhook-signature` | Standard Webhooks signature (`v1,{base64}` format) |
  *
- * ## Verifying Webhook Signatures
+ * ### Legacy Headers (Deprecated)
+ *
+ * Still sent on every delivery for backwards compatibility. Existing verification code
+ * using these headers continues to work — no changes required.
  *
- * 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.
+ * | Header | Description |
+ * |--------|-------------|
+ * | `X-Webhook-Event` | *(deprecated)* Event type (e.g., `message.sent`) |
+ * | `X-Webhook-Subscription-ID` | *(deprecated)* Webhook subscription ID |
+ * | `X-Webhook-Timestamp` | *(deprecated)* Unix timestamp (seconds) |
+ * | `X-Webhook-Signature` | *(deprecated)* HMAC-SHA256 signature (hex-encoded) |
  *
- * **Signature Construction:**
+ * ## Signing Secrets
  *
- * The signature is computed over a concatenation of the timestamp and payload:
+ * Signing secrets use the Standard Webhooks format: a `whsec_` prefix followed
+ * by base64-encoded random bytes (e.g., `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=`).
  *
- * ```
- * {timestamp}.{payload}
- * ```
+ * Strip the `whsec_` prefix and base64-decode the remainder to get the raw key bytes.
  *
- * Where:
- * - `timestamp` is the value from the `X-Webhook-Timestamp` header
- * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ * ## Verifying Webhook Signatures
+ *
+ * Webhooks are signed following the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks).
+ * You can use any [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks) to verify
+ * signatures, or implement verification manually:
+ *
+ * **Signed content:** `{webhook-id}.{webhook-timestamp}.{body}`
  *
  * **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
+ * 1. Extract the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers
+ * 2. Reject if the timestamp is more than 5 minutes old (replay protection)
+ * 3. Get the raw request body bytes (do not parse and re-serialize)
+ * 4. Construct signed content: `"{webhook-id}.{webhook-timestamp}.{body}"`
+ * 5. Strip the `whsec_` prefix from your secret and base64-decode to get key bytes
+ * 6. Compute HMAC-SHA256 using the key bytes over the signed content
+ * 7. Base64-encode the result and compare with the value after `v1,` in `webhook-signature`
+ * 8. 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)
+ * import base64, hmac, hashlib
+ *
+ * def verify_webhook(secret, body, headers):
+ *     msg_id = headers['webhook-id']
+ *     timestamp = headers['webhook-timestamp']
+ *     signature = headers['webhook-signature']
+ *
+ *     secret_str = secret.removeprefix('whsec_')
+ *     key = base64.b64decode(secret_str)
+ *
+ *     signed_content = f"{msg_id}.{timestamp}.{body}"
+ *     expected = base64.b64encode(
+ *         hmac.new(key, signed_content.encode(), hashlib.sha256).digest()
+ *     ).decode()
+ *
+ *     for sig in signature.split(' '):
+ *         if sig.startswith('v1,') and hmac.compare_digest(expected, sig[3:]):
+ *             return True
+ *     return False
  * ```
  *
  * **Example (Node.js):**
@@ -73,16 +100,28 @@ import { RequestOptions } from '../internal/request-options';
  * ```javascript
  * const crypto = require('crypto');
  *
- * function verifyWebhook(signingSecret, payload, timestamp, signature) {
- *   const message = `${timestamp}.${payload}`;
+ * function verifyWebhook(secret, rawBody, headers) {
+ *   const msgId = headers['webhook-id'];
+ *   const timestamp = headers['webhook-timestamp'];
+ *   const signature = headers['webhook-signature'];
+ *
+ *   const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
+ *   const keyBytes = Buffer.from(secretStr, 'base64');
+ *   const signedContent = `${msgId}.${timestamp}.${rawBody}`;
  *   const expected = crypto
- *     .createHmac('sha256', signingSecret)
- *     .update(message)
- *     .digest('hex');
- *   return crypto.timingSafeEqual(
- *     Buffer.from(expected),
- *     Buffer.from(signature)
- *   );
+ *     .createHmac('sha256', keyBytes)
+ *     .update(signedContent)
+ *     .digest('base64');
+ *
+ *   return signature.split(' ').some(sig => {
+ *     if (!sig.startsWith('v1,')) return false;
+ *     try {
+ *       return crypto.timingSafeEqual(
+ *         Buffer.from(expected, 'base64'),
+ *         Buffer.from(sig.slice(3), 'base64')
+ *       );
+ *     } catch { return false; }
+ *   });
  * }
  * ```
  *
@@ -136,13 +175,15 @@ export type WebhookEventType =
   | 'call.ended'
   | 'call.failed'
   | 'call.declined'
-  | 'call.no_answer';
+  | 'call.no_answer'
+  | 'location.sharing.started'
+  | 'location.sharing.stopped';
 
 export interface WebhookEventListResponse {
   /**
    * URL to the webhook events documentation
    */
-  doc_url: 'https://apidocs.linqapp.com/documentation/webhook-events';
+  doc_url: 'https://docs.linqapp.com/guides/webhooks/events';
 
   /**
    * List of all available webhook event types