@linqapp/sdk 0.24.2 → 0.26.0

package/resources/webhook-subscriptions.d.ts

@@ -15,55 +15,82 @@ import { RequestOptions } from "../internal/request-options.js";
  *
  * ## 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.
+ *
+ * | 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) |
  *
- * 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.
+ * ## Signing Secrets
  *
- * **Signature Construction:**
+ * Signing secrets use the Standard Webhooks format: a `whsec_` prefix followed
+ * by base64-encoded random bytes (e.g., `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=`).
  *
- * The signature is computed over a concatenation of the timestamp and payload:
+ * Strip the `whsec_` prefix and base64-decode the remainder to get the raw key bytes.
  *
- * ```
- * {timestamp}.{payload}
- * ```
+ * ## Verifying Webhook Signatures
  *
- * Where:
- * - `timestamp` is the value from the `X-Webhook-Timestamp` header
- * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ * 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
+ * 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)
  *
- * 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)
+ *     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):**
@@ -71,16 +98,28 @@ import { RequestOptions } from "../internal/request-options.js";
  * ```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; }
+ *   });
  * }
  * ```
  *
@@ -110,9 +149,15 @@ export declare class WebhookSubscriptions extends APIResource {
      * **Webhook Delivery:**
      *
      * - Events are sent via HTTP POST to the target URL
-     * - Each request includes `X-Webhook-Signature` and `X-Webhook-Timestamp` headers
-     * - Signature is HMAC-SHA256 over `{timestamp}.{payload}` — see
-     *   [Webhook Events](/docs/webhook-events) for verification details
+     * - Each request includes
+     *   [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks)
+     *   headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) for signature
+     *   verification
+     * - Legacy `X-Webhook-*` headers are also sent for backwards compatibility
+     *   (deprecated)
+     * - See
+     *   [Verifying Webhook Signatures](https://docs.linqapp.com/guides/webhooks#verifying-webhook-signatures)
+     *   for verification details
      * - Failed deliveries (5xx, 429, network errors) are retried up to 10 times over
      *   ~25 minutes with exponential backoff
      * - Client errors (4xx except 429) are not retried
@@ -131,6 +176,17 @@ export declare class WebhookSubscriptions extends APIResource {
      * ```
      */
     create(body: WebhookSubscriptionCreateParams, options?: RequestOptions): APIPromise<WebhookSubscriptionCreateResponse>;
+    /**
+     * Retrieve all webhook subscriptions for the authenticated partner. Returns a list
+     * of active and inactive subscriptions with their configuration and status.
+     *
+     * @example
+     * ```ts
+     * const webhookSubscriptions =
+     *   await client.webhookSubscriptions.list();
+     * ```
+     */
+    list(options?: RequestOptions): APIPromise<WebhookSubscriptionListResponse>;
     /**
      * Retrieve details for a specific webhook subscription including its target URL,
      * subscribed events, and current status.
@@ -163,17 +219,6 @@ export declare class WebhookSubscriptions extends APIResource {
      * ```
      */
     update(subscriptionID: string, body: WebhookSubscriptionUpdateParams, options?: RequestOptions): APIPromise<WebhookSubscription>;
-    /**
-     * Retrieve all webhook subscriptions for the authenticated partner. Returns a list
-     * of active and inactive subscriptions with their configuration and status.
-     *
-     * @example
-     * ```ts
-     * const webhookSubscriptions =
-     *   await client.webhookSubscriptions.list();
-     * ```
-     */
-    list(options?: RequestOptions): APIPromise<WebhookSubscriptionListResponse>;
     /**
      * Delete a webhook subscription.
      *

package/resources/webhook-subscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-subscriptions.d.ts","sourceRoot":"","sources":["../src/resources/webhook-subscriptions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhook-subscriptions.d.ts","sourceRoot":"","sources":["../src/resources/webhook-subscriptions.ts"],"names":[],"mappings":"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"}

package/resources/webhook-subscriptions.js

@@ -18,55 +18,82 @@ const path_1 = require("../internal/utils/path.js");
  *
  * ## 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)
  *
- * 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.
+ * Still sent on every delivery for backwards compatibility. Existing verification code
+ * using these headers continues to work — no changes required.
  *
- * **Signature Construction:**
+ * | 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) |
  *
- * The signature is computed over a concatenation of the timestamp and payload:
+ * ## Signing Secrets
  *
- * ```
- * {timestamp}.{payload}
- * ```
+ * Signing secrets use the Standard Webhooks format: a `whsec_` prefix followed
+ * by base64-encoded random bytes (e.g., `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=`).
+ *
+ * Strip the `whsec_` prefix and base64-decode the remainder to get the raw key bytes.
+ *
+ * ## 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:
  *
- * Where:
- * - `timestamp` is the value from the `X-Webhook-Timestamp` header
- * - `payload` is the raw JSON request body (exact bytes, not re-serialized)
+ * **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):**
@@ -74,16 +101,28 @@ const path_1 = require("../internal/utils/path.js");
  * ```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; }
+ *   });
  * }
  * ```
  *
@@ -113,9 +152,15 @@ class WebhookSubscriptions extends resource_1.APIResource {
      * **Webhook Delivery:**
      *
      * - Events are sent via HTTP POST to the target URL
-     * - Each request includes `X-Webhook-Signature` and `X-Webhook-Timestamp` headers
-     * - Signature is HMAC-SHA256 over `{timestamp}.{payload}` — see
-     *   [Webhook Events](/docs/webhook-events) for verification details
+     * - Each request includes
+     *   [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks)
+     *   headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) for signature
+     *   verification
+     * - Legacy `X-Webhook-*` headers are also sent for backwards compatibility
+     *   (deprecated)
+     * - See
+     *   [Verifying Webhook Signatures](https://docs.linqapp.com/guides/webhooks#verifying-webhook-signatures)
+     *   for verification details
      * - Failed deliveries (5xx, 429, network errors) are retried up to 10 times over
      *   ~25 minutes with exponential backoff
      * - Client errors (4xx except 429) are not retried
@@ -136,6 +181,19 @@ class WebhookSubscriptions extends resource_1.APIResource {
     create(body, options) {
         return this._client.post('/v3/webhook-subscriptions', { body, ...options });
     }
+    /**
+     * Retrieve all webhook subscriptions for the authenticated partner. Returns a list
+     * of active and inactive subscriptions with their configuration and status.
+     *
+     * @example
+     * ```ts
+     * const webhookSubscriptions =
+     *   await client.webhookSubscriptions.list();
+     * ```
+     */
+    list(options) {
+        return this._client.get('/v3/webhook-subscriptions', options);
+    }
     /**
      * Retrieve details for a specific webhook subscription including its target URL,
      * subscribed events, and current status.
@@ -172,19 +230,6 @@ class WebhookSubscriptions extends resource_1.APIResource {
     update(subscriptionID, body, options) {
         return this._client.put((0, path_1.path) `/v3/webhook-subscriptions/${subscriptionID}`, { body, ...options });
     }
-    /**
-     * Retrieve all webhook subscriptions for the authenticated partner. Returns a list
-     * of active and inactive subscriptions with their configuration and status.
-     *
-     * @example
-     * ```ts
-     * const webhookSubscriptions =
-     *   await client.webhookSubscriptions.list();
-     * ```
-     */
-    list(options) {
-        return this._client.get('/v3/webhook-subscriptions', options);
-    }
     /**
      * Delete a webhook subscription.
      *

package/resources/webhook-subscriptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-subscriptions.js","sourceRoot":"","sources":["../src/resources/webhook-subscriptions.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAG/C,oDAAmD;AAEnD,oDAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,MAAa,oBAAqB,SAAQ,sBAAW;IACnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,MAAM,CACJ,IAAqC,EACrC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAsB,EAAE,OAAwB;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,6BAA6B,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;IACtF,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CACJ,cAAsB,EACtB,IAAqC,EACrC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,6BAA6B,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAwB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAsB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,6BAA6B,cAAc,EAAE,EAAE;YAC5E,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAtHD,oDAsHC"}
+{"version":3,"file":"webhook-subscriptions.js","sourceRoot":"","sources":["../src/resources/webhook-subscriptions.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAG/C,oDAAmD;AAEnD,oDAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,MAAa,oBAAqB,SAAQ,sBAAW;IACnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CACJ,IAAqC,EACrC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAwB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAsB,EAAE,OAAwB;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,6BAA6B,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;IACtF,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CACJ,cAAsB,EACtB,IAAqC,EACrC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,6BAA6B,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAsB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,6BAA6B,cAAc,EAAE,EAAE;YAC5E,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AA5HD,oDA4HC"}