@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta → 1.0.2

package/dist/cjs/ai/gateway/x402/paywall.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @module ai/gateway/x402/paywall
+ * @description x402 Paywall — Resource Server side of the x402 protocol.
+ *
+ * When the gateway acts as a SELLER, this module handles:
+ *  1. Generating 402 Payment Required responses with proper headers
+ *  2. Parsing incoming PAYMENT-SIGNATURE headers from buyers
+ *  3. Coordinating verify → execute → settle flow with the facilitator
+ *  4. Attaching PAYMENT-RESPONSE headers to successful responses
+ *
+ * The paywall is transport-agnostic: it produces header/body objects
+ * that can be used with Express, Hono, Next.js, raw HTTP, or any framework.
+ *
+ * @since 1.0.0
+ */
+import type { X402PaymentRequired, X402PaymentPayload, X402PaymentRequirements, X402VerifyResponse, X402SettleResponse, X402Config } from './types';
+import { FacilitatorClient } from './facilitator';
+/**
+ * @description Encode an object to base64 JSON (for x402 headers).
+ * @param {unknown} obj - The object to encode
+ * @returns {string} Base64-encoded JSON string
+ * @since 1.0.0
+ */
+export declare function encodePaymentHeader(obj: unknown): string;
+/**
+ * @description Decode a base64 JSON header back to an object.
+ * @template T The expected type of the decoded object
+ * @param {string} base64 - The base64-encoded JSON string
+ * @returns {T} The decoded object
+ * @since 1.0.0
+ */
+export declare function decodePaymentHeader<T>(base64: string): T;
+/**
+ * @description The result of processing an incoming request through the paywall.
+ * @since 1.0.0
+ */
+export type PaywallResult = {
+    type: 'payment-required';
+    statusCode: 402;
+    headers: Record<string, string>;
+    body: X402PaymentRequired;
+} | {
+    type: 'payment-valid';
+    verifyResponse: X402VerifyResponse;
+    paymentPayload: X402PaymentPayload;
+    requirements: X402PaymentRequirements;
+} | {
+    type: 'no-payment-needed';
+};
+/**
+ * @description The result of settling a payment after the resource was served.
+ * @since 1.0.0
+ */
+export interface SettleResult {
+    success: boolean;
+    settleResponse: X402SettleResponse | null;
+    /** Base64-encoded PAYMENT-RESPONSE header value */
+    responseHeader: string | null;
+}
+/**
+ * @description Resource Server paywall for x402.
+ *
+ * The developer provides an X402Config, and the paywall handles
+ * the full verify → execute → settle lifecycle.
+ *
+ * @example
+ * ```ts
+ * const paywall = new X402Paywall(x402Config);
+ *
+ * // On incoming request:
+ * const result = await paywall.processRequest('getBalance', headers);
+ *
+ * if (result.type === 'payment-required') {
+ *   return new Response(JSON.stringify(result.body), {
+ *     status: 402,
+ *     headers: result.headers,
+ *   });
+ * }
+ *
+ * if (result.type === 'payment-valid') {
+ *   // Execute the RPC call, then settle
+ *   const settle = await paywall.settleAfterResponse(
+ *     result.paymentPayload,
+ *     result.requirements,
+ *   );
+ *   // Attach settle.responseHeader to the response
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare class X402Paywall {
+    private readonly config;
+    private readonly facilitator;
+    /** Cached supported kinds from the facilitator */
+    private supportedKindsCache;
+    private readonly supportedKindsCacheTtlMs;
+    /**
+     * @description Create a new X402Paywall.
+     * @param {X402Config} config - x402 configuration including facilitator and pricing
+     * @since 1.0.0
+     */
+    constructor(config: X402Config);
+    /**
+     * @description Process an incoming request and determine if payment is needed.
+     *
+     * @param {string} method - The RPC method being called (used to look up route config)
+     * @param {Record<string, string | undefined>} headers - Incoming HTTP headers (to check for PAYMENT-SIGNATURE)
+     * @returns {Promise<PaywallResult>} PaywallResult indicating what to do next
+     * @since 1.0.0
+     */
+    processRequest(method: string, headers: Record<string, string | undefined>): Promise<PaywallResult>;
+    /**
+     * @description Settle the payment after the resource has been served.
+     * Call this after successfully executing the RPC call.
+     *
+     * @param {X402PaymentPayload} paymentPayload - The verified payment payload
+     * @param {X402PaymentRequirements} requirements - The requirements that were fulfilled
+     * @returns {Promise<SettleResult>} SettleResult with the PAYMENT-RESPONSE header
+     * @since 1.0.0
+     */
+    settleAfterResponse(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /**
+     * @description Build PaymentRequirements for a given method.
+     * @param {string} method - The RPC method name
+     * @returns {X402PaymentRequirements} The constructed payment requirements
+     * @since 1.0.0
+     */
+    buildRequirements(method: string): X402PaymentRequirements;
+    /**
+     * @description Build PaymentRequirements with feePayer resolved from the facilitator.
+     * This calls /supported to get the facilitator's feePayer address.
+     * @param {string} method - The RPC method name
+     * @returns {Promise<X402PaymentRequirements>} Requirements with feePayer resolved
+     * @since 1.0.0
+     */
+    buildRequirementsWithFeePayer(method: string): Promise<X402PaymentRequirements>;
+    private buildPaymentRequired;
+    /**
+     * Get the facilitator's feePayer address for a given network.
+     * Caches the result for 1 minute.
+     */
+    private getFeePayer;
+    private findFeePayer;
+    /** Get the underlying facilitator client */
+    get facilitatorClient(): FacilitatorClient;
+}
+//# sourceMappingURL=paywall.d.ts.map

package/dist/cjs/ai/gateway/x402/paywall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paywall.d.ts","sourceRoot":"","sources":["../../../../../src/ai/gateway/x402/paywall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EAEvB,kBAAkB,EAClB,kBAAkB,EAElB,UAAU,EAGX,MAAM,SAAS,CAAC;AAQjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMlD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAExD;AAMD;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,UAAU,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,cAAc,EAAE,kBAAkB,CAAC;IAAC,cAAc,EAAE,kBAAkB,CAAC;IAAC,YAAY,EAAE,uBAAuB,CAAA;CAAE,GACxI;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,mDAAmD;IACnD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD,kDAAkD;IAClD,OAAO,CAAC,mBAAmB,CAAoH;IAC/I,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAU;IAEnD;;;;OAIG;gBACS,MAAM,EAAE,UAAU;IAO9B;;;;;;;OAOG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,OAAO,CAAC,aAAa,CAAC;IA2CzB;;;;;;;;OAQG;IACG,mBAAmB,CACvB,cAAc,EAAE,kBAAkB,EAClC,YAAY,EAAE,uBAAuB,GACpC,OAAO,CAAC,YAAY,CAAC;IA2BxB;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,uBAAuB;IAc1D;;;;;;OAMG;IACG,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;YAcvE,oBAAoB;IAkClC;;;OAGG;YACW,WAAW;IAwBzB,OAAO,CAAC,YAAY;IAYpB,4CAA4C;IAC5C,IAAI,iBAAiB,IAAI,iBAAiB,CAEzC;CACF"}

package/dist/cjs/ai/gateway/x402/paywall.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * @module ai/gateway/x402/paywall
+ * @description x402 Paywall — Resource Server side of the x402 protocol.
+ *
+ * When the gateway acts as a SELLER, this module handles:
+ *  1. Generating 402 Payment Required responses with proper headers
+ *  2. Parsing incoming PAYMENT-SIGNATURE headers from buyers
+ *  3. Coordinating verify → execute → settle flow with the facilitator
+ *  4. Attaching PAYMENT-RESPONSE headers to successful responses
+ *
+ * The paywall is transport-agnostic: it produces header/body objects
+ * that can be used with Express, Hono, Next.js, raw HTTP, or any framework.
+ *
+ * @since 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402Paywall = void 0;
+exports.encodePaymentHeader = encodePaymentHeader;
+exports.decodePaymentHeader = decodePaymentHeader;
+const types_1 = require("./types");
+const facilitator_1 = require("./facilitator");
+/* ═══════════════════════════════════════════════════════════════
+ *  Encoding helpers
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Encode an object to base64 JSON (for x402 headers).
+ * @param {unknown} obj - The object to encode
+ * @returns {string} Base64-encoded JSON string
+ * @since 1.0.0
+ */
+function encodePaymentHeader(obj) {
+    return Buffer.from(JSON.stringify(obj)).toString('base64');
+}
+/**
+ * @description Decode a base64 JSON header back to an object.
+ * @template T The expected type of the decoded object
+ * @param {string} base64 - The base64-encoded JSON string
+ * @returns {T} The decoded object
+ * @since 1.0.0
+ */
+function decodePaymentHeader(base64) {
+    return JSON.parse(Buffer.from(base64, 'base64').toString('utf-8'));
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  X402Paywall
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Resource Server paywall for x402.
+ *
+ * The developer provides an X402Config, and the paywall handles
+ * the full verify → execute → settle lifecycle.
+ *
+ * @example
+ * ```ts
+ * const paywall = new X402Paywall(x402Config);
+ *
+ * // On incoming request:
+ * const result = await paywall.processRequest('getBalance', headers);
+ *
+ * if (result.type === 'payment-required') {
+ *   return new Response(JSON.stringify(result.body), {
+ *     status: 402,
+ *     headers: result.headers,
+ *   });
+ * }
+ *
+ * if (result.type === 'payment-valid') {
+ *   // Execute the RPC call, then settle
+ *   const settle = await paywall.settleAfterResponse(
+ *     result.paymentPayload,
+ *     result.requirements,
+ *   );
+ *   // Attach settle.responseHeader to the response
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+class X402Paywall {
+    config;
+    facilitator;
+    /** Cached supported kinds from the facilitator */
+    supportedKindsCache = null;
+    supportedKindsCacheTtlMs = 60_000; // 1 min
+    /**
+     * @description Create a new X402Paywall.
+     * @param {X402Config} config - x402 configuration including facilitator and pricing
+     * @since 1.0.0
+     */
+    constructor(config) {
+        this.config = config;
+        this.facilitator = new facilitator_1.FacilitatorClient(config.facilitator);
+    }
+    /* ── Process incoming request ────────────────────────────── */
+    /**
+     * @description Process an incoming request and determine if payment is needed.
+     *
+     * @param {string} method - The RPC method being called (used to look up route config)
+     * @param {Record<string, string | undefined>} headers - Incoming HTTP headers (to check for PAYMENT-SIGNATURE)
+     * @returns {Promise<PaywallResult>} PaywallResult indicating what to do next
+     * @since 1.0.0
+     */
+    async processRequest(method, headers) {
+        if (!this.config.enabled) {
+            return { type: 'no-payment-needed' };
+        }
+        // Check for incoming payment
+        const paymentSignatureRaw = headers[types_1.X402_HEADER_PAYMENT_SIGNATURE]
+            ?? headers[types_1.X402_HEADER_PAYMENT_SIGNATURE.toLowerCase()]
+            ?? headers['payment-signature'];
+        if (!paymentSignatureRaw) {
+            // No payment → return 402
+            return this.buildPaymentRequired(method);
+        }
+        // Decode & verify the payment
+        const paymentPayload = decodePaymentHeader(paymentSignatureRaw);
+        const requirements = this.buildRequirements(method);
+        // Verify with facilitator (or local verifier)
+        let verifyResponse;
+        if (this.config.localVerifier) {
+            verifyResponse = await this.config.localVerifier(paymentPayload, requirements);
+        }
+        else {
+            verifyResponse = await this.facilitator.verify(paymentPayload, requirements);
+        }
+        if (!verifyResponse.isValid) {
+            // Invalid payment → return 402 again
+            return this.buildPaymentRequired(method, verifyResponse.invalidReason);
+        }
+        return {
+            type: 'payment-valid',
+            verifyResponse,
+            paymentPayload,
+            requirements,
+        };
+    }
+    /* ── Settle after response ───────────────────────────────── */
+    /**
+     * @description Settle the payment after the resource has been served.
+     * Call this after successfully executing the RPC call.
+     *
+     * @param {X402PaymentPayload} paymentPayload - The verified payment payload
+     * @param {X402PaymentRequirements} requirements - The requirements that were fulfilled
+     * @returns {Promise<SettleResult>} SettleResult with the PAYMENT-RESPONSE header
+     * @since 1.0.0
+     */
+    async settleAfterResponse(paymentPayload, requirements) {
+        try {
+            const settleResponse = await this.facilitator.settle(paymentPayload, requirements);
+            const settlementHeader = {
+                success: settleResponse.success,
+                transaction: settleResponse.transaction,
+                network: settleResponse.network,
+                payer: settleResponse.payer,
+            };
+            return {
+                success: true,
+                settleResponse,
+                responseHeader: encodePaymentHeader(settlementHeader),
+            };
+        }
+        catch {
+            return {
+                success: false,
+                settleResponse: null,
+                responseHeader: null,
+            };
+        }
+    }
+    /* ── Build payment requirements ──────────────────────────── */
+    /**
+     * @description Build PaymentRequirements for a given method.
+     * @param {string} method - The RPC method name
+     * @returns {X402PaymentRequirements} The constructed payment requirements
+     * @since 1.0.0
+     */
+    buildRequirements(method) {
+        const routeConfig = this.config.routes?.[method];
+        return {
+            scheme: 'exact',
+            network: routeConfig?.network ?? this.config.defaultNetwork,
+            asset: routeConfig?.asset ?? this.config.defaultAsset,
+            amount: routeConfig?.price ?? this.config.defaultPrice ?? '0',
+            payTo: this.config.payTo,
+            maxTimeoutSeconds: routeConfig?.maxTimeoutSeconds ?? this.config.defaultMaxTimeoutSeconds ?? 60,
+            extra: {}, // feePayer will be resolved from facilitator /supported
+        };
+    }
+    /**
+     * @description Build PaymentRequirements with feePayer resolved from the facilitator.
+     * This calls /supported to get the facilitator's feePayer address.
+     * @param {string} method - The RPC method name
+     * @returns {Promise<X402PaymentRequirements>} Requirements with feePayer resolved
+     * @since 1.0.0
+     */
+    async buildRequirementsWithFeePayer(method) {
+        const base = this.buildRequirements(method);
+        // Resolve feePayer from facilitator
+        const feePayer = await this.getFeePayer(base.network);
+        if (feePayer) {
+            base.extra = { ...base.extra, feePayer };
+        }
+        return base;
+    }
+    /* ── Build 402 response ──────────────────────────────────── */
+    async buildPaymentRequired(method, error) {
+        const requirements = await this.buildRequirementsWithFeePayer(method);
+        const resource = {
+            url: method, // In RPC context, the method IS the resource
+            description: this.config.routes?.[method]?.description ?? `Solana RPC: ${method}`,
+            mimeType: this.config.routes?.[method]?.mimeType ?? 'application/json',
+        };
+        const body = {
+            x402Version: types_1.X402_VERSION,
+            error,
+            resource,
+            accepts: [requirements],
+        };
+        const headerValue = encodePaymentHeader(body);
+        return {
+            type: 'payment-required',
+            statusCode: types_1.X402_STATUS_CODE,
+            headers: {
+                [types_1.X402_HEADER_PAYMENT_REQUIRED]: headerValue,
+                'Content-Type': 'application/json',
+            },
+            body,
+        };
+    }
+    /* ── Facilitator helpers ─────────────────────────────────── */
+    /**
+     * Get the facilitator's feePayer address for a given network.
+     * Caches the result for 1 minute.
+     */
+    async getFeePayer(network) {
+        try {
+            const now = Date.now();
+            if (this.supportedKindsCache &&
+                now - this.supportedKindsCache.cachedAt < this.supportedKindsCacheTtlMs) {
+                return this.findFeePayer(this.supportedKindsCache.kinds, network);
+            }
+            const response = await this.facilitator.supported();
+            this.supportedKindsCache = {
+                kinds: response.kinds,
+                cachedAt: now,
+            };
+            return this.findFeePayer(response.kinds, network);
+        }
+        catch {
+            // Facilitator may be unavailable — return undefined
+            return undefined;
+        }
+    }
+    findFeePayer(kinds, network) {
+        for (const kind of kinds) {
+            if (kind.network === network && kind.scheme === 'exact') {
+                return kind.extra?.feePayer;
+            }
+        }
+        return undefined;
+    }
+    /** Get the underlying facilitator client */
+    get facilitatorClient() {
+        return this.facilitator;
+    }
+}
+exports.X402Paywall = X402Paywall;
+//# sourceMappingURL=paywall.js.map

package/dist/cjs/ai/gateway/x402/paywall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paywall.js","sourceRoot":"","sources":["../../../../../src/ai/gateway/x402/paywall.ts"],"names":[],"mappings":"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"}

package/dist/cjs/ai/gateway/x402/registry.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @module ai/gateway/x402/registry
+ * @description x402 Facilitator Registry — Native registry of known x402 facilitators.
+ *
+ * Provides instant access to pre-configured facilitator clients for
+ * the most popular x402 facilitators in the Coinbase ecosystem.
+ *
+ * All facilitators implement the standard x402 protocol endpoints:
+ *  - POST /verify   — verify a payment payload
+ *  - POST /settle   — settle payment on-chain
+ *  - GET  /supported — query supported schemes / networks
+ *
+ * @example Quick start with a known facilitator
+ * ```ts
+ * import { createFacilitator, KnownFacilitator } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * // One-liner: get a pre-configured PayAI client
+ * const facilitator = createFacilitator(KnownFacilitator.PayAI);
+ *
+ * // Or use the registry directly
+ * import { FACILITATOR_REGISTRY, getFacilitatorInfo } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const info = getFacilitatorInfo(KnownFacilitator.RelAI);
+ * console.log(info.url); // "https://facilitator.x402.fi"
+ * ```
+ *
+ * @since 1.0.0
+ */
+import type { X402FacilitatorConfig, X402Network, KnownFacilitatorInfo } from './types';
+import { KnownFacilitator } from './types';
+/**
+ * @description Complete registry of known x402 facilitators with their configuration,
+ * supported networks, and metadata.
+ *
+ * Data sourced from the official x402 ecosystem:
+ * https://x402.org/ecosystem
+ *
+ * @since 1.0.0
+ */
+export declare const FACILITATOR_REGISTRY: ReadonlyMap<KnownFacilitator, KnownFacilitatorInfo>;
+/**
+ * @description Get the metadata for a known facilitator.
+ *
+ * @param {KnownFacilitator} facilitator - A KnownFacilitator enum value
+ * @returns {KnownFacilitatorInfo | undefined} Full facilitator info or undefined if not found
+ * @since 1.0.0
+ */
+export declare function getFacilitatorInfo(facilitator: KnownFacilitator): KnownFacilitatorInfo | undefined;
+/**
+ * @description Find all known facilitators that support a given network.
+ *
+ * @example
+ * ```ts
+ * const solanaFacilitators = findFacilitatorsByNetwork(SOLANA_MAINNET);
+ * // → [PayAI, Dexter, RelAI, CDP, AutoIncentive, SolPay, ...]
+ * ```
+ *
+ * @param {X402Network} network - CAIP-2 network identifier
+ * @returns {KnownFacilitatorInfo[]} Array of facilitators supporting the network
+ * @since 1.0.0
+ */
+export declare function findFacilitatorsByNetwork(network: X402Network): KnownFacilitatorInfo[];
+/**
+ * @description Find all known facilitators that support gas sponsoring.
+ * @returns {KnownFacilitatorInfo[]} Array of gas-sponsored facilitators
+ * @since 1.0.0
+ */
+export declare function findGasSponsoredFacilitators(): KnownFacilitatorInfo[];
+/**
+ * @description List all known facilitator IDs.
+ * @returns {KnownFacilitator[]} Array of all known facilitator enum values
+ * @since 1.0.0
+ */
+export declare function listKnownFacilitators(): KnownFacilitator[];
+/**
+ * @description Resolve a KnownFacilitator enum to a FacilitatorConfig
+ * ready to be passed to `FacilitatorClient` or `createFacilitator()`.
+ *
+ * @param {KnownFacilitator} facilitator - KnownFacilitator enum value
+ * @param {Partial<Omit<X402FacilitatorConfig, 'url'>>} [overrides] - Optional overrides (auth headers, timeout)
+ * @returns {X402FacilitatorConfig} The resolved facilitator configuration
+ * @throws {Error} If the facilitator is not found in the registry
+ * @since 1.0.0
+ */
+export declare function resolveKnownFacilitator(facilitator: KnownFacilitator, overrides?: Partial<Omit<X402FacilitatorConfig, 'url'>>): X402FacilitatorConfig;
+//# sourceMappingURL=registry.d.ts.map

package/dist/cjs/ai/gateway/x402/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../../src/ai/gateway/x402/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACxF,OAAO,EACL,gBAAgB,EAUjB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,gBAAgB,EAAE,oBAAoB,CA8KnF,CAAC;AAMH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,gBAAgB,GAC5B,oBAAoB,GAAG,SAAS,CAElC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,WAAW,GACnB,oBAAoB,EAAE,CAQxB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,oBAAoB,EAAE,CAQrE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,EAAE,CAE1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,gBAAgB,EAC7B,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAC,GACtD,qBAAqB,CAWvB"}