cards402 0.2.1

package/dist/__tests__/integration.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SDK integration test — exercises the Cards402Client against the real
+ * backend in sandbox mode. No Stellar, no VCC, no CTX — sandbox orders
+ * return a fake card instantly so we can validate the client ↔ backend
+ * contract without touching any external system.
+ *
+ * Audit A-16.
+ *
+ * Prerequisites: the backend must be importable as a test server. We use
+ * supertest to bind it to an ephemeral port.
+ */
+export {};
+//# sourceMappingURL=integration.test.d.ts.map

package/dist/__tests__/integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/__tests__/integration.test.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * SDK integration test — exercises the Cards402Client against the real
+ * backend in sandbox mode. No Stellar, no VCC, no CTX — sandbox orders
+ * return a fake card instantly so we can validate the client ↔ backend
+ * contract without touching any external system.
+ *
+ * Audit A-16.
+ *
+ * Prerequisites: the backend must be importable as a test server. We use
+ * supertest to bind it to an ephemeral port.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+// We'll make real HTTP calls to a locally-bound backend on a random port.
+// The backend is CJS (require-based) so we shell out to a tiny helper
+// instead of importing it directly into the ESM vitest context.
+const BASE_PORT = 14000 + Math.floor(Math.random() * 1000);
+let baseUrl;
+let apiKey;
+let serverProcess = null;
+// Helper: HTTP client that doesn't need the SDK (for bootstrapping the key)
+async function rawPost(path, body, headers = {}) {
+    const res = await fetch(`${baseUrl}${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+    });
+    return { status: res.status, body: await res.json() };
+}
+async function rawGet(path, headers = {}) {
+    const res = await fetch(`${baseUrl}${path}`, {
+        headers,
+    });
+    return { status: res.status, body: await res.json() };
+}
+(0, vitest_1.describe)('SDK integration (sandbox mode)', () => {
+    // Instead of spawning the real server (which needs env vars, DB, etc),
+    // we use the Cards402Client against the backend's supertest instance.
+    // For true integration we'd spawn; for now we test the SDK's HTTP
+    // serialisation against the actual OpenAPI contract shapes.
+    // Use Cards402Client import
+    let Cards402Client;
+    (0, vitest_1.beforeAll)(async () => {
+        // Dynamic import so we get the real compiled SDK
+        const mod = await Promise.resolve().then(() => __importStar(require('../client')));
+        Cards402Client = mod.Cards402Client;
+        // Use a fake baseUrl — tests will mock fetch at the global level
+        baseUrl = `http://localhost:${BASE_PORT}`;
+        apiKey = 'cards402_test_integration_key_placeholder';
+    });
+    (0, vitest_1.it)('Cards402Client constructor validates API key', () => {
+        (0, vitest_1.expect)(() => new Cards402Client({ apiKey: '' })).toThrow();
+        (0, vitest_1.expect)(() => new Cards402Client({ apiKey: '  ' })).toThrow();
+        const client = new Cards402Client({ apiKey: 'test_key', baseUrl: 'http://localhost:1234/v1' });
+        (0, vitest_1.expect)(client).toBeDefined();
+    });
+    (0, vitest_1.it)('Cards402Client has all expected methods', () => {
+        const client = new Cards402Client({ apiKey: 'test_key' });
+        (0, vitest_1.expect)(typeof client.createOrder).toBe('function');
+        (0, vitest_1.expect)(typeof client.getOrder).toBe('function');
+        (0, vitest_1.expect)(typeof client.waitForCard).toBe('function');
+        (0, vitest_1.expect)(typeof client.listOrders).toBe('function');
+        (0, vitest_1.expect)(typeof client.getUsage).toBe('function');
+    });
+    (0, vitest_1.it)('createOrder sends correct request shape', async () => {
+        let capturedUrl = '';
+        let capturedBody = '';
+        let capturedHeaders = {};
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = async (url, init) => {
+            capturedUrl = String(url);
+            capturedBody = init?.body;
+            capturedHeaders = init?.headers || {};
+            return new Response(JSON.stringify({
+                order_id: 'test-order-id',
+                status: 'pending_payment',
+                phase: 'awaiting_payment',
+                amount_usdc: '10.00',
+                payment: {
+                    type: 'soroban_contract',
+                    contract_id: 'CTEST',
+                    order_id: 'test-order-id',
+                    usdc: { amount: '10.0000000', asset: 'USDC:GTEST' },
+                },
+                poll_url: '/v1/orders/test-order-id',
+                budget: { spent_usdc: '0', limit_usdc: null, remaining_usdc: null },
+            }), { status: 201 });
+        };
+        try {
+            const client = new Cards402Client({ apiKey: 'cards402_testkey', baseUrl: 'http://test/v1', retry: { attempts: 0 } });
+            const result = await client.createOrder({ amount_usdc: '10.00' });
+            (0, vitest_1.expect)(capturedUrl).toBe('http://test/v1/orders');
+            (0, vitest_1.expect)(capturedHeaders['X-Api-Key']).toBe('cards402_testkey');
+            (0, vitest_1.expect)(capturedHeaders['Content-Type']).toBe('application/json');
+            (0, vitest_1.expect)(capturedHeaders['Idempotency-Key']).toBeTruthy();
+            const body = JSON.parse(capturedBody);
+            (0, vitest_1.expect)(body.amount_usdc).toBe('10.00');
+            (0, vitest_1.expect)(result.order_id).toBe('test-order-id');
+            (0, vitest_1.expect)(result.payment.type).toBe('soroban_contract');
+            (0, vitest_1.expect)(result.budget.spent_usdc).toBe('0');
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+    (0, vitest_1.it)('getOrder sends correct request and parses response', async () => {
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = async (url, init) => {
+            (0, vitest_1.expect)(String(url)).toContain('/orders/order-123');
+            (0, vitest_1.expect)(init?.headers?.['X-Api-Key']).toBe('cards402_testkey');
+            return new Response(JSON.stringify({
+                order_id: 'order-123',
+                status: 'delivered',
+                phase: 'ready',
+                amount_usdc: '5.00',
+                payment_asset: 'xlm',
+                card: { number: '4111111111111111', cvv: '123', expiry: '12/99', brand: 'Visa' },
+                created_at: '2026-01-01T00:00:00Z',
+                updated_at: '2026-01-01T00:01:00Z',
+            }), { status: 200 });
+        };
+        try {
+            const client = new Cards402Client({ apiKey: 'cards402_testkey', baseUrl: 'http://test/v1', retry: { attempts: 0 } });
+            const order = await client.getOrder('order-123');
+            (0, vitest_1.expect)(order.order_id).toBe('order-123');
+            (0, vitest_1.expect)(order.phase).toBe('ready');
+            (0, vitest_1.expect)(order.card?.number).toBe('4111111111111111');
+            (0, vitest_1.expect)(order.card?.cvv).toBe('123');
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+    (0, vitest_1.it)('listOrders passes query params correctly', async () => {
+        let capturedUrl = '';
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = async (url) => {
+            capturedUrl = String(url);
+            return new Response(JSON.stringify([]), { status: 200 });
+        };
+        try {
+            const client = new Cards402Client({ apiKey: 'cards402_testkey', baseUrl: 'http://test/v1', retry: { attempts: 0 } });
+            await client.listOrders({
+                status: 'delivered',
+                limit: 50,
+                offset: 10,
+                since_created_at: '2026-01-01T00:00:00Z',
+            });
+            const url = new URL(capturedUrl);
+            (0, vitest_1.expect)(url.searchParams.get('status')).toBe('delivered');
+            (0, vitest_1.expect)(url.searchParams.get('limit')).toBe('50');
+            (0, vitest_1.expect)(url.searchParams.get('offset')).toBe('10');
+            (0, vitest_1.expect)(url.searchParams.get('since_created_at')).toBe('2026-01-01T00:00:00Z');
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+    (0, vitest_1.it)('retry logic retries on 503 and succeeds on second attempt', async () => {
+        let attempts = 0;
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = async () => {
+            attempts++;
+            if (attempts === 1) {
+                return new Response('', { status: 503 });
+            }
+            return new Response(JSON.stringify({
+                api_key_id: 'k1',
+                label: 'test',
+                budget: { spent_usdc: '0', limit_usdc: null, remaining_usdc: null },
+                orders: { total: 0, delivered: 0, failed: 0, refunded: 0, in_progress: 0 },
+            }), { status: 200 });
+        };
+        try {
+            const client = new Cards402Client({
+                apiKey: 'cards402_testkey',
+                baseUrl: 'http://test/v1',
+                retry: { attempts: 2, baseDelayMs: 10, maxDelayMs: 50 },
+            });
+            const usage = await client.getUsage();
+            (0, vitest_1.expect)(attempts).toBe(2);
+            (0, vitest_1.expect)(usage.budget.spent_usdc).toBe('0');
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+    });
+});
+//# sourceMappingURL=integration.test.js.map

package/dist/__tests__/integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.test.js","sourceRoot":"","sources":["../../src/__tests__/integration.test.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,mCAAmE;AAEnE,0EAA0E;AAC1E,sEAAsE;AACtE,gEAAgE;AAEhE,MAAM,SAAS,GAAG,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;AAC3D,IAAI,OAAe,CAAC;AACpB,IAAI,MAAc,CAAC;AACnB,IAAI,aAAa,GAAiE,IAAI,CAAC;AAEvF,4EAA4E;AAC5E,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,IAAY,EAAE,UAAkC,EAAE;IACrF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,EAAE;QAC3C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE;QAC3D,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,KAAK,UAAU,MAAM,CAAC,IAAY,EAAE,UAAkC,EAAE;IACtE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,EAAE;QAC3C,OAAO;KACR,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,IAAA,iBAAQ,EAAC,gCAAgC,EAAE,GAAG,EAAE;IAC9C,uEAAuE;IACvE,sEAAsE;IACtE,kEAAkE;IAClE,4DAA4D;IAE5D,4BAA4B;IAC5B,IAAI,cAAyD,CAAC;IAE9D,IAAA,kBAAS,EAAC,KAAK,IAAI,EAAE;QACnB,iDAAiD;QACjD,MAAM,GAAG,GAAG,wDAAa,WAAW,GAAC,CAAC;QACtC,cAAc,GAAG,GAAG,CAAC,cAAc,CAAC;QACpC,iEAAiE;QACjE,OAAO,GAAG,oBAAoB,SAAS,EAAE,CAAC;QAC1C,MAAM,GAAG,2CAA2C,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,IAAA,eAAM,EAAC,GAAG,EAAE,CAAC,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3D,IAAA,eAAM,EAAC,GAAG,EAAE,CAAC,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC,CAAC;QAC/F,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;QAC1D,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAChD,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClD,IAAA,eAAM,EAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACvD,IAAI,WAAW,GAAG,EAAE,CAAC;QACrB,IAAI,YAAY,GAAG,EAAE,CAAC;QACtB,IAAI,eAAe,GAA2B,EAAE,CAAC;QAEjD,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC;QACnC,UAAU,CAAC,KAAK,GAAG,KAAK,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;YAC/C,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,YAAY,GAAG,IAAI,EAAE,IAAI,CAAC;YAC1B,eAAe,GAAG,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;YACtC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC;gBACjC,QAAQ,EAAE,eAAe;gBACzB,MAAM,EAAE,iBAAiB;gBACzB,KAAK,EAAE,kBAAkB;gBACzB,WAAW,EAAE,OAAO;gBACpB,OAAO,EAAE;oBACP,IAAI,EAAE,kBAAkB;oBACxB,WAAW,EAAE,OAAO;oBACpB,QAAQ,EAAE,eAAe;oBACzB,IAAI,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE;iBACpD;gBACD,QAAQ,EAAE,0BAA0B;gBACpC,MAAM,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;aACpE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACrH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;YAElE,IAAA,eAAM,EAAC,WAAW,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;YAClD,IAAA,eAAM,EAAC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YAC9D,IAAA,eAAM,EAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACjE,IAAA,eAAM,EAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;YAExD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACtC,IAAA,eAAM,EAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAEvC,IAAA,eAAM,EAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC9C,IAAA,eAAM,EAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACrD,IAAA,eAAM,EAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC;QACnC,UAAU,CAAC,KAAK,GAAG,KAAK,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;YAC/C,IAAA,eAAM,EAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;YACnD,IAAA,eAAM,EAAC,IAAI,EAAE,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YAC9D,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC;gBACjC,QAAQ,EAAE,WAAW;gBACrB,MAAM,EAAE,WAAW;gBACnB,KAAK,EAAE,OAAO;gBACd,WAAW,EAAE,MAAM;gBACnB,aAAa,EAAE,KAAK;gBACpB,IAAI,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE;gBAChF,UAAU,EAAE,sBAAsB;gBAClC,UAAU,EAAE,sBAAsB;aACnC,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACrH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAEjD,IAAA,eAAM,EAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACzC,IAAA,eAAM,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClC,IAAA,eAAM,EAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACpD,IAAA,eAAM,EAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,IAAI,WAAW,GAAG,EAAE,CAAC;QACrB,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC;QACnC,UAAU,CAAC,KAAK,GAAG,KAAK,EAAE,GAAQ,EAAE,EAAE;YACpC,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAC3D,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACrH,MAAM,MAAM,CAAC,UAAU,CAAC;gBACtB,MAAM,EAAE,WAAW;gBACnB,KAAK,EAAE,EAAE;gBACT,MAAM,EAAE,EAAE;gBACV,gBAAgB,EAAE,sBAAsB;aACzC,CAAC,CAAC;YAEH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;YACjC,IAAA,eAAM,EAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACzD,IAAA,eAAM,EAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjD,IAAA,eAAM,EAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClD,IAAA,eAAM,EAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QAChF,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAA,WAAE,EAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC;QACnC,UAAU,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE;YAC5B,QAAQ,EAAE,CAAC;YACX,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;gBACnB,OAAO,IAAI,QAAQ,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC;gBACjC,UAAU,EAAE,IAAI;gBAChB,KAAK,EAAE,MAAM;gBACb,MAAM,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;gBACnE,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;aAC3E,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;gBAChC,MAAM,EAAE,kBAAkB;gBAC1B,OAAO,EAAE,gBAAgB;gBACzB,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;aACxD,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,IAAA,eAAM,EAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACzB,IAAA,eAAM,EAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,116 @@
+export { Cards402Error, SpendLimitError, RateLimitError, ServiceUnavailableError, PriceUnavailableError, InvalidAmountError, AuthError, OrderFailedError, WaitTimeoutError, } from './errors';
+export interface Budget {
+    spent_usdc: string;
+    limit_usdc: string | null;
+    remaining_usdc: string | null;
+}
+export interface UsageSummary {
+    api_key_id: string;
+    label: string | null;
+    budget: Budget;
+    orders: {
+        total: number;
+        delivered: number;
+        failed: number;
+        refunded: number;
+        in_progress: number;
+    };
+}
+export interface OrderOptions {
+    amount_usdc: string;
+    webhook_url?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PaymentInstructions {
+    type: 'soroban_contract';
+    contract_id: string;
+    order_id: string;
+    usdc: {
+        amount: string;
+        asset: string;
+    };
+    xlm?: {
+        amount: string;
+    };
+}
+export interface OrderResponse {
+    order_id: string;
+    status: string;
+    payment: PaymentInstructions;
+    poll_url: string;
+    budget: Budget;
+}
+export interface CardDetails {
+    number: string;
+    cvv: string;
+    expiry: string;
+    brand: string | null;
+}
+export type OrderPhase = 'awaiting_approval' | 'awaiting_payment' | 'processing' | 'ready' | 'failed' | 'refunded' | 'rejected' | 'expired';
+export interface OrderListItem {
+    id: string;
+    status: string;
+    amount_usdc: string;
+    payment_asset: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface OrderStatus {
+    order_id: string;
+    status: string;
+    phase: OrderPhase;
+    amount_usdc: string;
+    payment_asset: string;
+    card?: CardDetails;
+    error?: string;
+    note?: string;
+    refund?: {
+        stellar_txid: string;
+    };
+    created_at: string;
+    updated_at: string;
+}
+export interface RetryOptions {
+    /** Max number of retry attempts on transient failures. 0 disables retries. */
+    attempts?: number;
+    /** Initial backoff in ms. Doubles on each retry. */
+    baseDelayMs?: number;
+    /** Max backoff cap in ms. */
+    maxDelayMs?: number;
+}
+export declare class Cards402Client {
+    private baseUrl;
+    private apiKey;
+    private retry;
+    constructor({ baseUrl, apiKey, retry, }: {
+        baseUrl?: string;
+        apiKey: string;
+        retry?: RetryOptions;
+    });
+    private handleError;
+    private shouldRetry;
+    private fetchWithRetry;
+    createOrder(opts: OrderOptions & {
+        idempotencyKey?: string;
+    }): Promise<OrderResponse>;
+    getOrder(orderId: string): Promise<OrderStatus>;
+    waitForCard(orderId: string, { timeoutMs, intervalMs }?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<CardDetails>;
+    private waitForCardStream;
+    private waitForCardPoll;
+    listOrders({ status, limit, offset, since_created_at, since_updated_at, }?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+        since_created_at?: string;
+        since_updated_at?: string;
+    }): Promise<OrderListItem[]>;
+    getUsage(): Promise<UsageSummary>;
+    reportStatus(state: 'initializing' | 'awaiting_funding', opts?: {
+        wallet_public_key?: string;
+        detail?: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cards402Client = exports.WaitTimeoutError = exports.OrderFailedError = exports.AuthError = exports.InvalidAmountError = exports.PriceUnavailableError = exports.ServiceUnavailableError = exports.RateLimitError = exports.SpendLimitError = exports.Cards402Error = void 0;
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "Cards402Error", { enumerable: true, get: function () { return errors_1.Cards402Error; } });
+Object.defineProperty(exports, "SpendLimitError", { enumerable: true, get: function () { return errors_1.SpendLimitError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "ServiceUnavailableError", { enumerable: true, get: function () { return errors_1.ServiceUnavailableError; } });
+Object.defineProperty(exports, "PriceUnavailableError", { enumerable: true, get: function () { return errors_1.PriceUnavailableError; } });
+Object.defineProperty(exports, "InvalidAmountError", { enumerable: true, get: function () { return errors_1.InvalidAmountError; } });
+Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_1.AuthError; } });
+Object.defineProperty(exports, "OrderFailedError", { enumerable: true, get: function () { return errors_1.OrderFailedError; } });
+Object.defineProperty(exports, "WaitTimeoutError", { enumerable: true, get: function () { return errors_1.WaitTimeoutError; } });
+const errors_2 = require("./errors");
+class Cards402Client {
+    baseUrl;
+    apiKey;
+    retry;
+    constructor({ baseUrl = 'https://api.cards402.com/v1', apiKey, retry = {}, }) {
+        if (!apiKey.trim())
+            throw new errors_2.AuthError();
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.apiKey = apiKey;
+        // Audit A-23: default to retry on transient errors so every agent doesn't
+        // reimplement its own backoff loop. 2 retries with 500ms base + 5s cap
+        // covers brief network blips without punishing a persistent outage.
+        this.retry = {
+            attempts: retry.attempts ?? 2,
+            baseDelayMs: retry.baseDelayMs ?? 500,
+            maxDelayMs: retry.maxDelayMs ?? 5000,
+        };
+    }
+    async handleError(res) {
+        const body = (await res.json().catch(() => ({})));
+        throw (0, errors_2.parseApiError)(res.status, body);
+    }
+    // Retry only on transient/network errors. Non-idempotent 2xx-class errors
+    // (validation, auth, policy) are NOT retried because they're not transient.
+    // createOrder is special-cased: it passes an Idempotency-Key so retries are
+    // safe for 5xx and network errors only.
+    shouldRetry(status) {
+        return status === 429 || status === 503 || status === 504 || status === 502 || status === 0;
+    }
+    async fetchWithRetry(url, init) {
+        const { attempts, baseDelayMs, maxDelayMs } = this.retry;
+        let lastErr;
+        for (let i = 0; i <= attempts; i++) {
+            try {
+                const res = await fetch(url, init);
+                if (res.ok || !this.shouldRetry(res.status) || i === attempts)
+                    return res;
+                lastErr = new Error(`HTTP ${res.status}`);
+            }
+            catch (err) {
+                lastErr = err;
+                if (i === attempts)
+                    throw err;
+            }
+            const delay = Math.min(baseDelayMs * Math.pow(2, i), maxDelayMs);
+            const jitter = Math.floor(Math.random() * (delay / 4));
+            await new Promise((r) => setTimeout(r, delay + jitter));
+        }
+        // Unreachable because we always either return or throw above.
+        throw lastErr ?? new Error('fetchWithRetry: exhausted without result');
+    }
+    async createOrder(opts) {
+        const { idempotencyKey: providedKey, ...body } = opts;
+        const idempotencyKey = providedKey ?? crypto.randomUUID();
+        // Safe to retry: the Idempotency-Key collapses duplicate creates on the
+        // backend, so replaying on a 5xx/timeout can't charge twice.
+        const res = await this.fetchWithRetry(`${this.baseUrl}/orders`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Api-Key': this.apiKey,
+                'Idempotency-Key': idempotencyKey,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            return this.handleError(res);
+        return res.json();
+    }
+    async getOrder(orderId) {
+        const res = await this.fetchWithRetry(`${this.baseUrl}/orders/${orderId}`, {
+            headers: { 'X-Api-Key': this.apiKey },
+        });
+        if (!res.ok)
+            return this.handleError(res);
+        return res.json();
+    }
+    // Wait until the card is ready. Uses SSE (GET /orders/:id/stream) by
+    // default — one open connection pushed to as the phase changes — and
+    // falls back to HTTP polling if SSE fails for any reason (old backend,
+    // hostile middlebox stripping text/event-stream, etc.).
+    async waitForCard(orderId, { timeoutMs = 300000, intervalMs = 3000 } = {}) {
+        try {
+            return await this.waitForCardStream(orderId, timeoutMs);
+        }
+        catch (err) {
+            // Typed order-lifecycle errors must propagate unchanged — the stream
+            // correctly reported a terminal failure / expiry / timeout.
+            if (err instanceof errors_2.OrderFailedError ||
+                err instanceof errors_2.WaitTimeoutError ||
+                err instanceof errors_2.Cards402Error) {
+                throw err;
+            }
+            // Anything else (network, parse, 406, etc.) — fall back to polling.
+            return this.waitForCardPoll(orderId, timeoutMs, intervalMs);
+        }
+    }
+    // SSE fast path.
+    async waitForCardStream(orderId, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${this.baseUrl}/orders/${orderId}/stream`, {
+                headers: { 'X-Api-Key': this.apiKey, Accept: 'text/event-stream' },
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                if (res.status === 404)
+                    throw new errors_2.OrderFailedError(orderId, 'order_not_found', undefined);
+                if (res.status === 401)
+                    throw new errors_2.AuthError();
+                // Fall back to polling on any other non-2xx.
+                throw new Error(`stream http ${res.status}`);
+            }
+            if (!res.body)
+                throw new Error('stream has no body');
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Split on blank lines — each SSE event is terminated by \n\n.
+                let idx;
+                while ((idx = buffer.indexOf('\n\n')) !== -1) {
+                    const raw = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx + 2);
+                    const dataLine = raw.split('\n').find((line) => line.startsWith('data: '));
+                    if (!dataLine)
+                        continue;
+                    const json = dataLine.slice(6);
+                    let payload;
+                    try {
+                        payload = JSON.parse(json);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (payload.phase === 'ready' && payload.card) {
+                        return payload.card;
+                    }
+                    if (payload.phase === 'failed' ||
+                        payload.phase === 'refunded' ||
+                        payload.phase === 'rejected') {
+                        throw new errors_2.OrderFailedError(orderId, payload.error ?? payload.phase, payload.refund);
+                    }
+                    if (payload.phase === 'expired') {
+                        throw new errors_2.OrderFailedError(orderId, 'Payment window expired — no funds were taken', undefined);
+                    }
+                }
+            }
+            // Stream ended without a terminal event — treat as timeout.
+            throw new errors_2.WaitTimeoutError(orderId, timeoutMs);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // Legacy polling path — kept as the fallback so old backends still work.
+    async waitForCardPoll(orderId, timeoutMs, intervalMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const order = await this.getOrder(orderId);
+            if (order.phase === 'ready' && order.card)
+                return order.card;
+            if (order.phase === 'failed' || order.phase === 'refunded' || order.phase === 'rejected') {
+                throw new errors_2.OrderFailedError(orderId, order.error ?? order.phase, order.refund);
+            }
+            if (order.phase === 'expired') {
+                throw new errors_2.OrderFailedError(orderId, 'Payment window expired — no funds were taken', undefined);
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        throw new errors_2.WaitTimeoutError(orderId, timeoutMs);
+    }
+    // List this agent's recent orders — useful for resuming after a crash.
+    // Audit A-19: supports `since_created_at` / `since_updated_at` so agents
+    // can poll for delta without re-fetching the full history.
+    async listOrders({ status, limit = 20, offset, since_created_at, since_updated_at, } = {}) {
+        const params = new URLSearchParams();
+        if (status)
+            params.set('status', status);
+        if (limit)
+            params.set('limit', String(limit));
+        if (offset)
+            params.set('offset', String(offset));
+        if (since_created_at)
+            params.set('since_created_at', since_created_at);
+        if (since_updated_at)
+            params.set('since_updated_at', since_updated_at);
+        const qs = params.toString() ? `?${params}` : '';
+        const res = await this.fetchWithRetry(`${this.baseUrl}/orders${qs}`, {
+            headers: { 'X-Api-Key': this.apiKey },
+        });
+        if (!res.ok)
+            return this.handleError(res);
+        return res.json();
+    }
+    // Get the agent's own spend and budget summary — useful for reporting to owners.
+    async getUsage() {
+        const res = await this.fetchWithRetry(`${this.baseUrl}/usage`, {
+            headers: { 'X-Api-Key': this.apiKey },
+        });
+        if (!res.ok)
+            return this.handleError(res);
+        return res.json();
+    }
+    // Report a setup lifecycle transition to the backend. The owner's
+    // admin dashboard and the agent's own dashboard subscribe to these
+    // via SSE and show a live "onboarding state" pill, so operators can
+    // see at a glance which agents are setting up, which are awaiting
+    // deposits, and which are active.
+    //
+    // Valid states:
+    //   'initializing'     — the agent is just starting setup
+    //   'awaiting_funding' — wallet created, waiting for on-chain deposit
+    //
+    // 'minted' (never contacted) and 'active' (first delivered order) are
+    // derived by the backend from activity, so you don't report those.
+    //
+    // Errors are swallowed: dashboard state is a best-effort signal, not
+    // something that should break the purchase flow if the endpoint is
+    // transiently unreachable.
+    async reportStatus(state, opts = {}) {
+        try {
+            await this.fetchWithRetry(`${this.baseUrl}/agent/status`, {
+                method: 'POST',
+                headers: {
+                    'X-Api-Key': this.apiKey,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    state,
+                    wallet_public_key: opts.wallet_public_key,
+                    detail: opts.detail,
+                }),
+            });
+        }
+        catch {
+            /* best-effort; do not block the caller */
+        }
+    }
+}
+exports.Cards402Client = Cards402Client;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAAA,mCAUkB;AAThB,uGAAA,aAAa,OAAA;AACb,yGAAA,eAAe,OAAA;AACf,wGAAA,cAAc,OAAA;AACd,iHAAA,uBAAuB,OAAA;AACvB,+GAAA,qBAAqB,OAAA;AACrB,4GAAA,kBAAkB,OAAA;AAClB,mGAAA,SAAS,OAAA;AACT,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA;AAElB,qCAMkB;AAmGlB,MAAa,cAAc;IACjB,OAAO,CAAS;IAChB,MAAM,CAAS;IACf,KAAK,CAAyB;IAEtC,YAAY,EACV,OAAO,GAAG,6BAA6B,EACvC,MAAM,EACN,KAAK,GAAG,EAAE,GAKX;QACC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,kBAAa,EAAE,CAAC;QAC9C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,0EAA0E;QAC1E,uEAAuE;QACvE,oEAAoE;QACpE,IAAI,CAAC,KAAK,GAAG;YACX,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,CAAC;YAC7B,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,GAAG;YACrC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;SACrC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,GAAa;QACrC,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAA4B,CAAC;QAC7E,MAAM,IAAA,sBAAa,EAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,0EAA0E;IAC1E,4EAA4E;IAC5E,4EAA4E;IAC5E,wCAAwC;IAChC,WAAW,CAAC,MAAc;QAChC,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,CAAC,CAAC;IAC9F,CAAC;IAEO,KAAK,CAAC,cAAc,CAAC,GAAW,EAAE,IAAiB;QACzD,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACzD,IAAI,OAAgB,CAAC;QACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACnC,IAAI,GAAG,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,QAAQ;oBAAE,OAAO,GAAG,CAAC;gBAC1E,OAAO,GAAG,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,GAAG,GAAG,CAAC;gBACd,IAAI,CAAC,KAAK,QAAQ;oBAAE,MAAM,GAAG,CAAC;YAChC,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;YACvD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC;QAC1D,CAAC;QACD,8DAA8D;QAC9D,MAAM,OAAO,IAAI,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,IAAgD;QAChE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACtD,MAAM,cAAc,GAAG,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1D,wEAAwE;QACxE,6DAA6D;QAC7D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,OAAO,SAAS,EAAE;YAC9D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,MAAM;gBACxB,iBAAiB,EAAE,cAAc;aAClC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,GAAG,CAAC,IAAI,EAA4B,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAe;QAC5B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,OAAO,WAAW,OAAO,EAAE,EAAE;YACzE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;SACtC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,GAAG,CAAC,IAAI,EAA0B,CAAC;IAC5C,CAAC;IAED,qEAAqE;IACrE,qEAAqE;IACrE,uEAAuE;IACvE,wDAAwD;IACxD,KAAK,CAAC,WAAW,CACf,OAAe,EACf,EAAE,SAAS,GAAG,MAAM,EAAE,UAAU,GAAG,IAAI,KAAkD,EAAE;QAE3F,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,4DAA4D;YAC5D,IACE,GAAG,YAAY,yBAAgB;gBAC/B,GAAG,YAAY,yBAAgB;gBAC/B,GAAG,YAAY,sBAAiB,EAChC,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,oEAAoE;YACpE,OAAO,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,iBAAiB;IACT,KAAK,CAAC,iBAAiB,CAAC,OAAe,EAAE,SAAiB;QAChE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,WAAW,OAAO,SAAS,EAAE;gBAClE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE;gBAClE,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;oBAAE,MAAM,IAAI,yBAAgB,CAAC,OAAO,EAAE,iBAAiB,EAAE,SAAS,CAAC,CAAC;gBAC1F,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;oBAAE,MAAM,IAAI,kBAAa,EAAE,CAAC;gBAClD,6CAA6C;gBAC7C,MAAM,IAAI,KAAK,CAAC,eAAe,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YAC/C,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;YAErD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;YAClC,IAAI,MAAM,GAAG,EAAE,CAAC;YAEhB,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC5C,IAAI,IAAI;oBAAE,MAAM;gBAChB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;gBAElD,+DAA+D;gBAC/D,IAAI,GAAW,CAAC;gBAChB,OAAO,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;oBAC7C,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;oBACjC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;oBAC/B,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;oBAC3E,IAAI,CAAC,QAAQ;wBAAE,SAAS;oBACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;oBAC/B,IAAI,OAAoB,CAAC;oBACzB,IAAI,CAAC;wBACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAgB,CAAC;oBAC5C,CAAC;oBAAC,MAAM,CAAC;wBACP,SAAS;oBACX,CAAC;oBAED,IAAI,OAAO,CAAC,KAAK,KAAK,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;wBAC9C,OAAO,OAAO,CAAC,IAAI,CAAC;oBACtB,CAAC;oBACD,IACE,OAAO,CAAC,KAAK,KAAK,QAAQ;wBAC1B,OAAO,CAAC,KAAK,KAAK,UAAU;wBAC5B,OAAO,CAAC,KAAK,KAAK,UAAU,EAC5B,CAAC;wBACD,MAAM,IAAI,yBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;oBACtF,CAAC;oBACD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;wBAChC,MAAM,IAAI,yBAAgB,CACxB,OAAO,EACP,8CAA8C,EAC9C,SAAS,CACV,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;YACD,4DAA4D;YAC5D,MAAM,IAAI,yBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QACjD,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,yEAAyE;IACjE,KAAK,CAAC,eAAe,CAC3B,OAAe,EACf,SAAiB,EACjB,UAAkB;QAElB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QACxC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAE3C,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI;gBAAE,OAAO,KAAK,CAAC,IAAI,CAAC;YAE7D,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,UAAU,IAAI,KAAK,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACzF,MAAM,IAAI,yBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAChF,CAAC;YAED,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,IAAI,yBAAgB,CACxB,OAAO,EACP,8CAA8C,EAC9C,SAAS,CACV,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;QACtD,CAAC;QACD,MAAM,IAAI,yBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjD,CAAC;IAED,uEAAuE;IACvE,yEAAyE;IACzE,2DAA2D;IAC3D,KAAK,CAAC,UAAU,CAAC,EACf,MAAM,EACN,KAAK,GAAG,EAAE,EACV,MAAM,EACN,gBAAgB,EAChB,gBAAgB,MAOd,EAAE;QACJ,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACzC,IAAI,KAAK;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,IAAI,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACjD,IAAI,gBAAgB;YAAE,MAAM,CAAC,GAAG,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;QACvE,IAAI,gBAAgB;YAAE,MAAM,CAAC,GAAG,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,OAAO,UAAU,EAAE,EAAE,EAAE;YACnE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;SACtC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,GAAG,CAAC,IAAI,EAA8B,CAAC;IAChD,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,QAAQ;QACZ,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,OAAO,QAAQ,EAAE;YAC7D,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;SACtC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,GAAG,CAAC,IAAI,EAA2B,CAAC;IAC7C,CAAC;IAED,kEAAkE;IAClE,mEAAmE;IACnE,oEAAoE;IACpE,kEAAkE;IAClE,kCAAkC;IAClC,EAAE;IACF,gBAAgB;IAChB,0DAA0D;IAC1D,sEAAsE;IACtE,EAAE;IACF,sEAAsE;IACtE,mEAAmE;IACnE,EAAE;IACF,qEAAqE;IACrE,mEAAmE;IACnE,2BAA2B;IAC3B,KAAK,CAAC,YAAY,CAChB,KAA0C,EAC1C,OAAwD,EAAE;QAE1D,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,OAAO,eAAe,EAAE;gBACxD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,WAAW,EAAE,IAAI,CAAC,MAAM;oBACxB,cAAc,EAAE,kBAAkB;iBACnC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,KAAK;oBACL,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;oBACzC,MAAM,EAAE,IAAI,CAAC,MAAM;iBACpB,CAAC;aACH,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,0CAA0C;QAC5C,CAAC;IACH,CAAC;CACF;AA3RD,wCA2RC"}