@codespar/sdk 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @codespar/sdk
+
+Commerce SDK for AI agents — sessions, managed auth, Complete Loop orchestration for Latin American commercial APIs.
+
+## Install
+
+```bash
+npm install @codespar/sdk
+```
+
+## Usage
+
+```typescript
+import { CodeSpar } from "@codespar/sdk";
+
+const cs = new CodeSpar({ apiKey: "ak_..." });
+
+const session = await cs.create("user_123", {
+  preset: "brazilian",
+  manageConnections: { waitForConnections: true },
+});
+
+// Natural language
+const result = await session.send("Charge R$150 via Pix and issue the NF-e");
+
+// Direct tool execution
+const charge = await session.execute("ZOOP_CREATE_CHARGE", {
+  amount: 150.0,
+  payment_type: "pix",
+});
+
+// Complete Loop
+const loop = await session.loop({
+  steps: [
+    { server: "mcp-zoop", tool: "ZOOP_CREATE_CHARGE", params: { amount: 150, payment_type: "pix" } },
+    { server: "mcp-nuvem-fiscal", tool: "NUVEMFISCAL_EMITIR_NFE", params: (prev) => ({ chargeId: prev[0].data }) },
+    { server: "mcp-melhor-envio", tool: "MELHORENVIO_GENERATE_LABEL", params: {} },
+    { server: "mcp-z-api", tool: "ZAPI_SEND_MESSAGE", params: { text: "Your order is on the way!" } },
+  ],
+  onStepComplete: (step, result) => console.log(`✓ ${step.tool}`),
+  retryPolicy: { maxRetries: 3, backoff: "exponential" },
+});
+```
+
+## API
+
+### `new CodeSpar(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | `CODESPAR_API_KEY` env | Your API key |
+| `baseUrl` | `string` | `https://api.codespar.dev` | API base URL |
+| `managed` | `boolean` | `true` | Enable managed billing/logging |
+
+### `cs.create(userId, config)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `servers` | `string[]` | MCP servers to connect |
+| `preset` | `string` | `"brazilian"`, `"mexican"`, `"argentinian"`, `"colombian"`, `"all"` |
+| `manageConnections.waitForConnections` | `boolean` | Block until all servers connected |
+
+### Session Methods
+
+| Method | Description |
+|--------|-------------|
+| `session.tools()` | Get all available tools |
+| `session.findTools(intent)` | Search tools by description |
+| `session.execute(tool, params)` | Execute a specific tool |
+| `session.send(message)` | Send natural language message |
+| `session.loop(config)` | Run Complete Loop workflow |
+| `session.authorize(serverId)` | Start OAuth flow for a server |
+| `session.connections()` | List connected servers |
+| `session.mcp` | MCP transport URL and headers |
+| `session.close()` | Close session |
+
+## License
+
+MIT — [codespar.dev](https://codespar.dev)

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codespar.test.d.ts.map

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

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

package/dist/__tests__/codespar.test.js

@@ -0,0 +1,257 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { CodeSpar, SessionConfigSchema } from "../index.js";
+import { createSession } from "../session.js";
+/* ── Helpers ── */
+function mockTool(overrides = {}) {
+    return {
+        name: "ZOOP_CREATE_CHARGE",
+        slug: "zoop_create_charge",
+        description: "Create a Pix charge",
+        server: "zoop",
+        inputSchema: { type: "object", properties: { amount: { type: "number" } } },
+        ...overrides,
+    };
+}
+function successResult(tool = "ZOOP_CREATE_CHARGE") {
+    return { success: true, data: { id: "ch_1" }, duration: 42, server: "zoop", tool };
+}
+function failResult(tool = "ZOOP_CREATE_CHARGE") {
+    return { success: false, data: null, error: "500: Internal Server Error", duration: 10, server: "zoop", tool };
+}
+function mockFetchResponse(body, ok = true, status = 200) {
+    return vi.fn().mockResolvedValue({
+        ok,
+        status,
+        json: () => Promise.resolve(body),
+        text: () => Promise.resolve(JSON.stringify(body)),
+    });
+}
+/* ── CodeSpar constructor ── */
+describe("CodeSpar", () => {
+    const originalEnv = { ...process.env };
+    afterEach(() => {
+        process.env = { ...originalEnv };
+    });
+    it("throws without API key", () => {
+        delete process.env.CODESPAR_API_KEY;
+        expect(() => new CodeSpar()).toThrow("CodeSpar API key is required");
+    });
+    it("accepts apiKey via config", () => {
+        const cs = new CodeSpar({ apiKey: "ak_test" });
+        expect(cs).toBeInstanceOf(CodeSpar);
+    });
+    it("reads API key from env when not in config", () => {
+        process.env.CODESPAR_API_KEY = "ak_env";
+        const cs = new CodeSpar();
+        expect(cs).toBeInstanceOf(CodeSpar);
+    });
+});
+/* ── SessionConfigSchema ── */
+describe("SessionConfigSchema", () => {
+    it("validates a valid config", () => {
+        const result = SessionConfigSchema.safeParse({
+            servers: ["zoop", "nfe"],
+            preset: "brazilian",
+            manageConnections: { waitForConnections: true, timeout: 5000 },
+            metadata: { org: "acme" },
+        });
+        expect(result.success).toBe(true);
+    });
+    it("validates empty config", () => {
+        expect(SessionConfigSchema.safeParse({}).success).toBe(true);
+    });
+    it("rejects invalid preset", () => {
+        const result = SessionConfigSchema.safeParse({ preset: "invalid" });
+        expect(result.success).toBe(false);
+    });
+    it("rejects non-string servers", () => {
+        const result = SessionConfigSchema.safeParse({ servers: [123] });
+        expect(result.success).toBe(false);
+    });
+});
+/* ── createSession ── */
+describe("createSession", () => {
+    let fetchMock;
+    beforeEach(() => {
+        fetchMock = mockFetchResponse({
+            id: "sess_1",
+            servers: [{ id: "zoop", name: "Zoop", pkg: "@codespar/zoop", connected: true, auth: "oauth2", toolCount: 3 }],
+            mcp: { url: "https://mcp.codespar.dev/sess_1", headers: { Authorization: "Bearer tok" } },
+        });
+        vi.stubGlobal("fetch", fetchMock);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("makes POST to /v1/sessions", async () => {
+        await createSession("user_1", { preset: "brazilian" }, {
+            baseUrl: "https://api.codespar.dev",
+            apiKey: "ak_test",
+            managed: true,
+        });
+        expect(fetchMock).toHaveBeenCalledWith("https://api.codespar.dev/v1/sessions", expect.objectContaining({ method: "POST" }));
+    });
+    it("throws on non-ok response", async () => {
+        fetchMock = mockFetchResponse("Unauthorized", false, 401);
+        vi.stubGlobal("fetch", fetchMock);
+        await expect(createSession("user_1", {}, { baseUrl: "https://api.codespar.dev", apiKey: "bad", managed: true })).rejects.toThrow("Failed to create session");
+    });
+    it("returns session with correct id and userId", async () => {
+        const session = await createSession("user_1", {}, {
+            baseUrl: "https://api.codespar.dev",
+            apiKey: "ak_test",
+            managed: true,
+        });
+        expect(session.id).toBe("sess_1");
+        expect(session.userId).toBe("user_1");
+    });
+});
+/* ── session.findTools ── */
+describe("session.findTools", () => {
+    let session;
+    beforeEach(async () => {
+        const sessionResponse = {
+            id: "sess_1",
+            servers: [],
+            mcp: { url: "https://mcp.codespar.dev/sess_1", headers: {} },
+        };
+        const connectionsResponse = {
+            servers: [],
+            tools: [
+                mockTool({ name: "ZOOP_CREATE_CHARGE", slug: "zoop_create_charge", description: "Create a Pix charge", server: "zoop" }),
+                mockTool({ name: "NFE_ISSUE", slug: "nfe_issue", description: "Issue an NF-e invoice", server: "nfe" }),
+                mockTool({ name: "ZOOP_REFUND", slug: "zoop_refund", description: "Refund a charge", server: "zoop" }),
+            ],
+        };
+        let callCount = 0;
+        vi.stubGlobal("fetch", vi.fn().mockImplementation(() => {
+            callCount++;
+            if (callCount === 1) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve(sessionResponse) });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve(connectionsResponse) });
+        }));
+        session = await createSession("u1", {}, { baseUrl: "https://api.test", apiKey: "ak", managed: true });
+        await session.connections();
+    });
+    afterEach(() => vi.restoreAllMocks());
+    it("filters by tool name", () => {
+        expect(session.findTools("refund")).toHaveLength(1);
+        expect(session.findTools("refund")[0].slug).toBe("zoop_refund");
+    });
+    it("filters by server name", () => {
+        const zoopTools = session.findTools("zoop");
+        expect(zoopTools).toHaveLength(2);
+    });
+    it("filters by description", () => {
+        expect(session.findTools("invoice")).toHaveLength(1);
+    });
+    it("returns empty when no tools cached", async () => {
+        // Create fresh session without calling connections()
+        vi.stubGlobal("fetch", mockFetchResponse({
+            id: "sess_2", servers: [], mcp: { url: "u", headers: {} },
+        }));
+        const fresh = await createSession("u2", {}, { baseUrl: "https://api.test", apiKey: "ak", managed: true });
+        expect(fresh.findTools("anything")).toEqual([]);
+    });
+});
+/* ── session.loop ── */
+describe("session.loop", () => {
+    let session;
+    let fetchImpl;
+    beforeEach(async () => {
+        const sessionData = { id: "sess_1", servers: [], mcp: { url: "u", headers: {} } };
+        fetchImpl = vi.fn()
+            .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(sessionData) }); // createSession
+        vi.stubGlobal("fetch", fetchImpl);
+        session = await createSession("u1", {}, { baseUrl: "https://api.test", apiKey: "ak", managed: true });
+    });
+    afterEach(() => vi.restoreAllMocks());
+    it("executes steps in order", async () => {
+        fetchImpl
+            .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(successResult("step_a")) })
+            .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(successResult("step_b")) });
+        const result = await session.loop({
+            steps: [
+                { server: "a", tool: "step_a", params: { x: 1 } },
+                { server: "b", tool: "step_b", params: { y: 2 } },
+            ],
+        });
+        expect(result.success).toBe(true);
+        expect(result.completedSteps).toBe(2);
+        expect(result.totalSteps).toBe(2);
+        expect(result.results).toHaveLength(2);
+    });
+    it("aborts on error by default", async () => {
+        fetchImpl
+            .mockResolvedValueOnce({ ok: false, status: 500, text: () => Promise.resolve("err") })
+            .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(successResult("step_b")) });
+        const result = await session.loop({
+            steps: [
+                { server: "a", tool: "step_a", params: {} },
+                { server: "b", tool: "step_b", params: {} },
+            ],
+        });
+        expect(result.success).toBe(false);
+        expect(result.completedSteps).toBe(0);
+        // Second step should not have been called
+        expect(fetchImpl).toHaveBeenCalledTimes(2); // 1 createSession + 1 failed execute
+    });
+    it("continues on error when abortOnError is false", async () => {
+        fetchImpl
+            .mockResolvedValueOnce({ ok: false, status: 500, text: () => Promise.resolve("err") })
+            .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(successResult("step_b")) });
+        const result = await session.loop({
+            steps: [
+                { server: "a", tool: "step_a", params: {} },
+                { server: "b", tool: "step_b", params: {} },
+            ],
+            abortOnError: false,
+        });
+        expect(result.completedSteps).toBe(1);
+        expect(result.results).toHaveLength(2);
+    });
+    it("retries failed steps", async () => {
+        fetchImpl
+            .mockResolvedValueOnce({ ok: false, status: 500, text: () => Promise.resolve("err") }) // attempt 0
+            .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(successResult("step_a")) }); // attempt 1
+        const result = await session.loop({
+            steps: [{ server: "a", tool: "step_a", params: {} }],
+            retryPolicy: { maxRetries: 1, baseDelay: 1 },
+        });
+        expect(result.success).toBe(true);
+        expect(result.completedSteps).toBe(1);
+    });
+    it("skips steps when 'when' returns false", async () => {
+        fetchImpl
+            .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(successResult("step_a")) });
+        const result = await session.loop({
+            steps: [
+                { server: "a", tool: "step_a", params: {} },
+                { server: "b", tool: "step_b", params: {}, when: () => false },
+            ],
+        });
+        expect(result.success).toBe(true);
+        expect(result.results).toHaveLength(1);
+    });
+    it("calls onStepComplete callback", async () => {
+        fetchImpl.mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(successResult("s")) });
+        const onComplete = vi.fn();
+        await session.loop({
+            steps: [{ server: "a", tool: "s", params: {} }],
+            onStepComplete: onComplete,
+        });
+        expect(onComplete).toHaveBeenCalledOnce();
+        expect(onComplete).toHaveBeenCalledWith(expect.objectContaining({ tool: "s" }), expect.objectContaining({ success: true }), 0);
+    });
+    it("calls onStepError callback on failure", async () => {
+        fetchImpl.mockResolvedValueOnce({ ok: false, status: 500, text: () => Promise.resolve("boom") });
+        const onError = vi.fn();
+        await session.loop({
+            steps: [{ server: "a", tool: "s", params: {} }],
+            onStepError: onError,
+        });
+        expect(onError).toHaveBeenCalledOnce();
+    });
+});
+//# sourceMappingURL=codespar.test.js.map

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

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

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @codespar/sdk — Commerce SDK for AI agents
+ *
+ * Sessions, managed auth, Complete Loop orchestration
+ * for Latin American commercial APIs.
+ *
+ * @example
+ * ```ts
+ * import { CodeSpar } from "@codespar/sdk";
+ *
+ * const cs = new CodeSpar({ apiKey: "ak_..." });
+ * const session = await cs.create("user_123", { preset: "brazilian" });
+ * const result = await session.send("Charge R$150 via Pix and issue the NF-e");
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { CodeSparConfig, Session, SessionConfig, Tool, ToolResult, LoopConfig, LoopStep, LoopResult, AuthConfig, AuthResult, ServerConnection, SendResult, } from "./types.js";
+export { SessionConfigSchema } from "./types.js";
+import type { CodeSparConfig, Session, SessionConfig } from "./types.js";
+export declare class CodeSpar {
+    private readonly config;
+    constructor(config?: CodeSparConfig);
+    /**
+     * Create a new session for a user.
+     *
+     * @param userId - Unique user identifier
+     * @param config - Session configuration (servers, preset, auth)
+     * @returns A session with tools, execute, loop, and send methods
+     *
+     * @example
+     * ```ts
+     * const session = await cs.create("user_123", {
+     *   preset: "brazilian",
+     *   manageConnections: { waitForConnections: true },
+     * });
+     * ```
+     */
+    create(userId: string, config?: SessionConfig): Promise<Session>;
+    /**
+     * Auth manager for programmatic OAuth flows.
+     */
+    get authManager(): {
+        /**
+         * Get the OAuth connect URL for a provider.
+         * Redirect the user to this URL to start the OAuth flow.
+         */
+        getConnectUrl(serverId: string, redirectUrl?: string): string;
+        /**
+         * Check connection status for a server.
+         */
+        getStatus(serverId: string): Promise<{
+            connected: boolean;
+            expiresAt?: string;
+        }>;
+    };
+}
+export default CodeSpar;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,YAAY,EACV,cAAc,EACd,OAAO,EACP,aAAa,EACb,IAAI,EACJ,UAAU,EACV,UAAU,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMzE,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;gBAEtC,MAAM,GAAE,cAAmB;IAevC;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAW1E;;OAEG;IACH,IAAI,WAAW;QAKX;;;WAGG;gCACqB,MAAM,gBAAgB,MAAM,GAAG,MAAM;QAM7D;;WAEG;4BACuB,MAAM,GAAG,OAAO,CAAC;YAAE,SAAS,EAAE,OAAO,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;MAQzF;CACF;AAED,eAAe,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * @codespar/sdk — Commerce SDK for AI agents
+ *
+ * Sessions, managed auth, Complete Loop orchestration
+ * for Latin American commercial APIs.
+ *
+ * @example
+ * ```ts
+ * import { CodeSpar } from "@codespar/sdk";
+ *
+ * const cs = new CodeSpar({ apiKey: "ak_..." });
+ * const session = await cs.create("user_123", { preset: "brazilian" });
+ * const result = await session.send("Charge R$150 via Pix and issue the NF-e");
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { SessionConfigSchema } from "./types.js";
+import { SessionConfigSchema } from "./types.js";
+import { createSession } from "./session.js";
+const DEFAULT_BASE_URL = "https://api.codespar.dev";
+export class CodeSpar {
+    config;
+    constructor(config = {}) {
+        this.config = {
+            apiKey: config.apiKey || process.env.CODESPAR_API_KEY || "",
+            baseUrl: config.baseUrl || process.env.CODESPAR_BASE_URL || DEFAULT_BASE_URL,
+            managed: config.managed ?? true,
+        };
+        if (!this.config.apiKey) {
+            throw new Error("CodeSpar API key is required. Pass { apiKey: '...' } or set CODESPAR_API_KEY env var.\n" +
+                "Get your key at https://dashboard.codespar.dev/settings?tab=api-keys");
+        }
+    }
+    /**
+     * Create a new session for a user.
+     *
+     * @param userId - Unique user identifier
+     * @param config - Session configuration (servers, preset, auth)
+     * @returns A session with tools, execute, loop, and send methods
+     *
+     * @example
+     * ```ts
+     * const session = await cs.create("user_123", {
+     *   preset: "brazilian",
+     *   manageConnections: { waitForConnections: true },
+     * });
+     * ```
+     */
+    async create(userId, config = {}) {
+        // Validate config
+        SessionConfigSchema.parse(config);
+        return createSession(userId, config, {
+            baseUrl: this.config.baseUrl,
+            apiKey: this.config.apiKey,
+            managed: this.config.managed,
+        });
+    }
+    /**
+     * Auth manager for programmatic OAuth flows.
+     */
+    get authManager() {
+        const baseUrl = this.config.baseUrl;
+        const apiKey = this.config.apiKey;
+        return {
+            /**
+             * Get the OAuth connect URL for a provider.
+             * Redirect the user to this URL to start the OAuth flow.
+             */
+            getConnectUrl(serverId, redirectUrl) {
+                const params = new URLSearchParams({ serverId });
+                if (redirectUrl)
+                    params.set("redirect", redirectUrl);
+                return `${baseUrl}/v1/auth/connect?${params.toString()}&key=${apiKey}`;
+            },
+            /**
+             * Check connection status for a server.
+             */
+            async getStatus(serverId) {
+                const res = await fetch(`${baseUrl}/v1/auth/status/${serverId}`, {
+                    headers: { Authorization: `Bearer ${apiKey}` },
+                });
+                if (!res.ok)
+                    return { connected: false };
+                return res.json();
+            },
+        };
+    }
+}
+export default CodeSpar;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAiBH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD,MAAM,OAAO,QAAQ;IACF,MAAM,CAA2B;IAElD,YAAY,SAAyB,EAAE;QACrC,IAAI,CAAC,MAAM,GAAG;YACZ,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE;YAC3D,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,gBAAgB;YAC5E,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;SAChC,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,yFAAyF;gBACzF,sEAAsE,CACvE,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,SAAwB,EAAE;QACrD,kBAAkB;QAClB,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAElC,OAAO,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE;YACnC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;SAC7B,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAElC,OAAO;YACL;;;eAGG;YACH,aAAa,CAAC,QAAgB,EAAE,WAAoB;gBAClD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;gBACjD,IAAI,WAAW;oBAAE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;gBACrD,OAAO,GAAG,OAAO,oBAAoB,MAAM,CAAC,QAAQ,EAAE,QAAQ,MAAM,EAAE,CAAC;YACzE,CAAC;YAED;;eAEG;YACH,KAAK,CAAC,SAAS,CAAC,QAAgB;gBAC9B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,mBAAmB,QAAQ,EAAE,EAAE;oBAC/D,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;iBAC/C,CAAC,CAAC;gBACH,IAAI,CAAC,GAAG,CAAC,EAAE;oBAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;gBACzC,OAAO,GAAG,CAAC,IAAI,EAAyD,CAAC;YAC3E,CAAC;SACF,CAAC;IACJ,CAAC;CACF;AAED,eAAe,QAAQ,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,9 @@
+import type { Session, SessionConfig } from "./types.js";
+interface SessionDeps {
+    baseUrl: string;
+    apiKey: string;
+    managed: boolean;
+}
+export declare function createSession(userId: string, config: SessionConfig, deps: SessionDeps): Promise<Session>;
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EASd,MAAM,YAAY,CAAC;AAEpB,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,OAAO,CAAC,CAqNlB"}

package/dist/session.js

@@ -0,0 +1,180 @@
+export async function createSession(userId, config, deps) {
+    const { baseUrl, apiKey, managed } = deps;
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+    };
+    // Create session on backend
+    const res = await fetch(`${baseUrl}/v1/sessions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ userId, ...config }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Failed to create session: ${res.status} ${body}`);
+    }
+    const data = await res.json();
+    let cachedTools = null;
+    const session = {
+        id: data.id,
+        userId,
+        servers: data.servers,
+        createdAt: new Date(),
+        mcp: data.mcp,
+        tools() {
+            if (cachedTools)
+                return cachedTools;
+            // Tools are loaded lazily on first call
+            throw new Error("Call await session.connections() first to load tools, or use session.findTools()");
+        },
+        findTools(intent) {
+            if (!cachedTools)
+                return [];
+            const q = intent.toLowerCase();
+            return cachedTools.filter((t) => t.name.toLowerCase().includes(q) ||
+                t.description.toLowerCase().includes(q) ||
+                t.server.toLowerCase().includes(q));
+        },
+        async execute(toolName, params) {
+            const start = Date.now();
+            const r = await fetch(`${baseUrl}/v1/sessions/${data.id}/execute`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ tool: toolName, params }),
+            });
+            if (!r.ok) {
+                const body = await r.text();
+                return {
+                    success: false,
+                    data: null,
+                    error: `${r.status}: ${body}`,
+                    duration: Date.now() - start,
+                    server: "",
+                    tool: toolName,
+                };
+            }
+            const result = await r.json();
+            return { ...result, duration: result.duration || Date.now() - start };
+        },
+        async loop(loopConfig) {
+            const start = Date.now();
+            const results = [];
+            const maxRetries = loopConfig.retryPolicy?.maxRetries ?? 0;
+            const abortOnError = loopConfig.abortOnError ?? true;
+            for (let i = 0; i < loopConfig.steps.length; i++) {
+                const step = loopConfig.steps[i];
+                // Check conditional
+                if (step.when && !step.when(results)) {
+                    continue;
+                }
+                // Resolve params (can be a function of previous results)
+                const params = typeof step.params === "function" ? step.params(results) : step.params;
+                let lastError = null;
+                let result = null;
+                for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                    try {
+                        result = await session.execute(step.tool, params);
+                        if (result.success) {
+                            lastError = null;
+                            break;
+                        }
+                        lastError = new Error(result.error || "Tool execution failed");
+                    }
+                    catch (err) {
+                        lastError = err instanceof Error ? err : new Error(String(err));
+                    }
+                    // Backoff before retry
+                    if (attempt < maxRetries) {
+                        const baseDelay = loopConfig.retryPolicy?.baseDelay ?? 1000;
+                        const delay = loopConfig.retryPolicy?.backoff === "exponential"
+                            ? baseDelay * Math.pow(2, attempt)
+                            : baseDelay * (attempt + 1);
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                    }
+                }
+                if (lastError || !result?.success) {
+                    if (loopConfig.onStepError) {
+                        loopConfig.onStepError(step, lastError || new Error("Unknown error"), i);
+                    }
+                    if (result)
+                        results.push(result);
+                    if (abortOnError) {
+                        return {
+                            success: false,
+                            results,
+                            duration: Date.now() - start,
+                            completedSteps: results.filter((r) => r.success).length,
+                            totalSteps: loopConfig.steps.length,
+                        };
+                    }
+                    continue;
+                }
+                results.push(result);
+                if (loopConfig.onStepComplete) {
+                    loopConfig.onStepComplete(step, result, i);
+                }
+            }
+            return {
+                success: results.every((r) => r.success),
+                results,
+                duration: Date.now() - start,
+                completedSteps: results.filter((r) => r.success).length,
+                totalSteps: loopConfig.steps.length,
+            };
+        },
+        async send(message) {
+            const start = Date.now();
+            const r = await fetch(`${baseUrl}/v1/sessions/${data.id}/send`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ message }),
+            });
+            if (!r.ok) {
+                const body = await r.text();
+                throw new Error(`Send failed: ${r.status} ${body}`);
+            }
+            const result = await r.json();
+            return { ...result, duration: result.duration || Date.now() - start };
+        },
+        async authorize(serverId, authConfig) {
+            const r = await fetch(`${baseUrl}/v1/sessions/${data.id}/authorize`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ serverId, ...authConfig }),
+            });
+            if (!r.ok) {
+                return { connected: false, error: `Auth failed: ${r.status}` };
+            }
+            return r.json();
+        },
+        async connections() {
+            const r = await fetch(`${baseUrl}/v1/sessions/${data.id}/connections`, { headers });
+            if (!r.ok)
+                return session.servers;
+            const connections = await r.json();
+            session.servers = connections.servers;
+            cachedTools = connections.tools;
+            return connections.servers;
+        },
+        async close() {
+            await fetch(`${baseUrl}/v1/sessions/${data.id}`, {
+                method: "DELETE",
+                headers,
+            });
+        },
+    };
+    // If waitForConnections, poll until ready
+    if (config.manageConnections?.waitForConnections) {
+        const timeout = config.manageConnections.timeout ?? 30000;
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const conns = await session.connections();
+            if (conns.every((c) => c.connected))
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+    }
+    return session;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+import { z } from "zod";
+export interface CodeSparConfig {
+    /** API key for managed mode. Obtain from dashboard.codespar.dev */
+    apiKey?: string;
+    /** Base URL for CodeSpar API. Defaults to https://api.codespar.dev */
+    baseUrl?: string;
+    /** Enable managed mode (billing, logging, rate limiting via CodeSpar backend) */
+    managed?: boolean;
+}
+export interface SessionConfig {
+    /** MCP servers to connect. Use package names or IDs. */
+    servers?: string[];
+    /** Preset configurations. "brazilian" enables all BR servers. */
+    preset?: "brazilian" | "mexican" | "argentinian" | "colombian" | "all";
+    /** Connection management options */
+    manageConnections?: {
+        /** Block until all servers are connected */
+        waitForConnections?: boolean;
+        /** Timeout in ms for connection wait. Default: 30000 */
+        timeout?: number;
+    };
+    /** Metadata attached to every tool call in this session */
+    metadata?: Record<string, string>;
+}
+export interface Session {
+    /** Unique session ID */
+    id: string;
+    /** User ID that owns this session */
+    userId: string;
+    /** Connected servers */
+    servers: ServerConnection[];
+    /** Session creation timestamp */
+    createdAt: Date;
+    /** Get all available tools from connected servers */
+    tools(): Tool[];
+    /** Find tools by intent description */
+    findTools(intent: string): Tool[];
+    /** Execute a specific tool */
+    execute(toolName: string, params: Record<string, unknown>): Promise<ToolResult>;
+    /** Run a Complete Loop workflow */
+    loop(config: LoopConfig): Promise<LoopResult>;
+    /** Send a natural language message for the agent to process */
+    send(message: string): Promise<SendResult>;
+    /** Initiate OAuth flow for a server */
+    authorize(serverId: string, config?: AuthConfig): Promise<AuthResult>;
+    /** List connected servers and their auth status */
+    connections(): Promise<ServerConnection[]>;
+    /** MCP transport URLs for IDE integration */
+    mcp: {
+        url: string;
+        headers: Record<string, string>;
+    };
+    /** Close session and clean up resources */
+    close(): Promise<void>;
+}
+export interface Tool {
+    /** Fully qualified tool name (e.g., ZOOP_CREATE_CHARGE) */
+    name: string;
+    /** Tool slug for execution */
+    slug: string;
+    /** Human-readable description */
+    description: string;
+    /** Server that provides this tool */
+    server: string;
+    /** Input schema (JSON Schema) */
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolResult {
+    success: boolean;
+    data: unknown;
+    error?: string;
+    /** Execution time in ms */
+    duration: number;
+    /** Server that executed the tool */
+    server: string;
+    /** Tool that was executed */
+    tool: string;
+}
+export interface LoopStep {
+    /** Server ID or package name */
+    server: string;
+    /** Tool name to execute */
+    tool: string;
+    /** Tool parameters */
+    params: Record<string, unknown> | ((prevResults: ToolResult[]) => Record<string, unknown>);
+    /** Optional: skip this step if condition returns false */
+    when?: (prevResults: ToolResult[]) => boolean;
+}
+export interface LoopConfig {
+    /** Steps to execute in order */
+    steps: LoopStep[];
+    /** Called after each step completes */
+    onStepComplete?: (step: LoopStep, result: ToolResult, index: number) => void;
+    /** Called if a step fails */
+    onStepError?: (step: LoopStep, error: Error, index: number) => void;
+    /** Retry policy for failed steps */
+    retryPolicy?: {
+        maxRetries?: number;
+        backoff?: "linear" | "exponential";
+        baseDelay?: number;
+    };
+    /** Abort all remaining steps on first failure. Default: true */
+    abortOnError?: boolean;
+}
+export interface LoopResult {
+    success: boolean;
+    /** Results from each step, in order */
+    results: ToolResult[];
+    /** Total execution time in ms */
+    duration: number;
+    /** Number of steps completed */
+    completedSteps: number;
+    /** Total steps attempted */
+    totalSteps: number;
+}
+export interface AuthConfig {
+    /** API key for direct auth */
+    token?: string;
+    /** OAuth2 client credentials */
+    clientId?: string;
+    clientSecret?: string;
+}
+export interface AuthResult {
+    /** Whether auth was successful */
+    connected: boolean;
+    /** OAuth redirect URL (if OAuth flow required) */
+    redirectUrl?: string;
+    /** Error message if failed */
+    error?: string;
+}
+export interface ServerConnection {
+    /** Server ID */
+    id: string;
+    /** Server display name */
+    name: string;
+    /** npm package name */
+    pkg: string;
+    /** Whether the server is connected and ready */
+    connected: boolean;
+    /** Auth method used */
+    auth: "oauth2" | "api_key" | "none";
+    /** Number of tools available */
+    toolCount: number;
+}
+export interface SendResult {
+    /** Agent response text */
+    text: string;
+    /** Tools that were called */
+    toolCalls: ToolResult[];
+    /** Total execution time in ms */
+    duration: number;
+}
+export declare const SessionConfigSchema: z.ZodObject<{
+    servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    preset: z.ZodOptional<z.ZodEnum<["brazilian", "mexican", "argentinian", "colombian", "all"]>>;
+    manageConnections: z.ZodOptional<z.ZodObject<{
+        waitForConnections: z.ZodOptional<z.ZodBoolean>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        waitForConnections?: boolean | undefined;
+        timeout?: number | undefined;
+    }, {
+        waitForConnections?: boolean | undefined;
+        timeout?: number | undefined;
+    }>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    servers?: string[] | undefined;
+    preset?: "brazilian" | "mexican" | "argentinian" | "colombian" | "all" | undefined;
+    manageConnections?: {
+        waitForConnections?: boolean | undefined;
+        timeout?: number | undefined;
+    } | undefined;
+    metadata?: Record<string, string> | undefined;
+}, {
+    servers?: string[] | undefined;
+    preset?: "brazilian" | "mexican" | "argentinian" | "colombian" | "all" | undefined;
+    manageConnections?: {
+        waitForConnections?: boolean | undefined;
+        timeout?: number | undefined;
+    } | undefined;
+    metadata?: Record<string, string> | undefined;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/* ── Validation schemas ── */
+export const SessionConfigSchema = z.object({
+    servers: z.array(z.string()).optional(),
+    preset: z.enum(["brazilian", "mexican", "argentinian", "colombian", "all"]).optional(),
+    manageConnections: z.object({
+        waitForConnections: z.boolean().optional(),
+        timeout: z.number().optional(),
+    }).optional(),
+    metadata: z.record(z.string()).optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgLxB,8BAA8B;AAE9B,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACvC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;IACtF,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC;QAC1B,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC,CAAC,QAAQ,EAAE;IACb,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}

package/package.json

@@ -1 +1,57 @@
-{"name":"@codespar/sdk","version":"0.0.1","description":"test"}
+{
+  "name": "@codespar/sdk",
+  "version": "0.1.0",
+  "description": "Commerce SDK for AI agents — sessions, managed auth, Complete Loop orchestration for Latin American APIs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai-agent",
+    "commerce",
+    "mcp",
+    "pix",
+    "nfe",
+    "latam",
+    "sdk",
+    "codespar"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codespar/codespar-core",
+    "directory": "packages/core"
+  },
+  "homepage": "https://codespar.dev",
+  "bugs": {
+    "url": "https://github.com/codespar/codespar-core/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  }
+}