@linqapp/sdk 0.25.0 → 0.26.0

package/src/client.ts

@@ -1093,55 +1093,82 @@ export class LinqAPIV3 {
    *
    * ## 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):**
@@ -1149,16 +1176,28 @@ export class LinqAPIV3 {
    * ```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; }
+   *   });
    * }
    * ```
    *
@@ -1184,55 +1223,82 @@ export class LinqAPIV3 {
    *
    * ## 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):**
@@ -1240,16 +1306,28 @@ export class LinqAPIV3 {
    * ```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; }
+   *   });
    * }
    * ```
    *

package/src/resources/chats/chats.ts

@@ -3,6 +3,8 @@
 import { APIResource } from '../../core/resource';
 import * as MessagesAPI from '../messages';
 import * as Shared from '../shared';
+import * as LocationAPI from './location';
+import { GetChatLocationResponse, Location, LocationRequestResponse } from './location';
 import * as ChatsMessagesAPI from './messages';
 import { MessageListParams, MessageSendParams, MessageSendResponse, Messages, SentMessage } from './messages';
 import * as ParticipantsAPI from './participants';
@@ -25,6 +27,7 @@ export class Chats extends APIResource {
   participants: ParticipantsAPI.Participants = new ParticipantsAPI.Participants(this._client);
   typing: TypingAPI.Typing = new TypingAPI.Typing(this._client);
   messages: ChatsMessagesAPI.Messages = new ChatsMessagesAPI.Messages(this._client);
+  location: LocationAPI.Location = new LocationAPI.Location(this._client);
 
   /**
    * Create a new chat with specified participants and send an initial message. The
@@ -817,6 +820,7 @@ export interface ChatSendVoicememoParams {
 Chats.Participants = Participants;
 Chats.Typing = Typing;
 Chats.Messages = Messages;
+Chats.Location = Location;
 
 export declare namespace Chats {
   export {
@@ -853,4 +857,10 @@ export declare namespace Chats {
     type MessageSendParams as MessageSendParams,
     type MessageListParams as MessageListParams,
   };
+
+  export {
+    Location as Location,
+    type GetChatLocationResponse as GetChatLocationResponse,
+    type LocationRequestResponse as LocationRequestResponse,
+  };
 }

package/src/resources/chats/index.ts

@@ -17,6 +17,7 @@ export {
   type ChatSendVoicememoParams,
   type ChatsListChatsPagination,
 } from './chats';
+export { Location, type GetChatLocationResponse, type LocationRequestResponse } from './location';
 export {
   Messages,
   type SentMessage,

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,
+  };
+}