tally-sdk 0.1.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "tally-sdk",
+  "version": "0.1.0",
+  "description": "Accounting, tax, and compliance layer for the agent economy",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "x402",
+    "agent",
+    "accounting",
+    "crypto"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "uuid": "^11.1.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/hook.ts

@@ -0,0 +1,49 @@
+import { v4 as uuidv4 } from "uuid";
+import type { PaymentPayload, Store } from "./types.js";
+
+export interface HookOptions {
+  facilitator: string;
+}
+
+function extractPayload(body: unknown, headers: Headers, options: HookOptions): PaymentPayload {
+  const b = (body && typeof body === "object" ? body : {}) as Record<string, unknown>;
+  const now = Date.now();
+
+  return {
+    id: (b.id as string) ?? uuidv4(),
+    facilitator: options.facilitator,
+    requestId: (b.requestId as string) ?? headers.get("x-request-id") ?? "",
+    fromAddress: (b.fromAddress as string) ?? "",
+    toAddress: (b.toAddress as string) ?? headers.get("x-payment-address") ?? "",
+    amount: (b.amount as string) ?? headers.get("x-payment-amount") ?? "0",
+    asset: (b.asset as string) ?? headers.get("x-payment-asset") ?? "USDC",
+    chainId: (b.chainId as string) ?? "eip155:1",
+    txHash: (b.txHash as string) ?? "",
+    timestamp: (b.timestamp as number) ?? now,
+    memo: (b.memo as string) ?? undefined,
+    metadata: b.metadata as Record<string, unknown> ?? undefined,
+  };
+}
+
+export function createTallyFetch(
+  fetchFn: typeof fetch,
+  store: Store,
+  options?: HookOptions
+): typeof fetch {
+  return async (input, init) => {
+    const response = await fetchFn(input, init);
+
+    if (options && (response.headers.has("x-facilitator") || response.headers.has("x-request-id"))) {
+      try {
+        const cloned = response.clone();
+        const body = await cloned.json();
+        const payload = extractPayload(body, cloned.headers, options);
+        await store.insert(payload);
+      } catch {
+        // swallow — never break the agent request
+      }
+    }
+
+    return response;
+  };
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+import { SqliteStore } from "./store.js";
+import { createTallyFetch } from "./hook.js";
+import type { Store, TallyClient, TallyConfig } from "./types.js";
+
+export type { PaymentPayload, Store, TallyConfig, TallyClient } from "./types.js";
+
+export function createTally(config: TallyConfig): TallyClient {
+  const store: Store = config.store ?? new SqliteStore("./tally.db");
+  const originalFetch = globalThis.fetch;
+  const wrappedFetch = createTallyFetch(
+    originalFetch.bind(globalThis),
+    store,
+    { facilitator: config.facilitator }
+  );
+
+  return {
+    fetch: wrappedFetch,
+    wrap() {
+      globalThis.fetch = wrappedFetch;
+    },
+    unwrap() {
+      globalThis.fetch = originalFetch;
+    },
+    store,
+    async close() {
+      await store.close();
+    },
+  };
+}

package/src/store.ts

@@ -0,0 +1,97 @@
+import Database from "better-sqlite3";
+import type { PaymentPayload, Store } from "./types.js";
+
+export class SqliteStore implements Store {
+  private db: Database.Database;
+
+  constructor(path: string) {
+    this.db = new Database(path);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS payments (
+        id          TEXT PRIMARY KEY,
+        facilitator TEXT NOT NULL,
+        request_id  TEXT NOT NULL,
+        from_addr   TEXT NOT NULL,
+        to_addr     TEXT NOT NULL,
+        amount      TEXT NOT NULL,
+        asset       TEXT NOT NULL DEFAULT 'USDC',
+        chain_id    TEXT NOT NULL,
+        tx_hash     TEXT NOT NULL,
+        memo        TEXT,
+        metadata    TEXT,
+        created_at  INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_payments_facilitator ON payments(facilitator);
+      CREATE INDEX IF NOT EXISTS idx_payments_created_at ON payments(created_at);
+    `);
+  }
+
+  async insert(payload: PaymentPayload): Promise<void> {
+    const stmt = this.db.prepare(`
+      INSERT OR IGNORE INTO payments
+        (id, facilitator, request_id, from_addr, to_addr, amount, asset, chain_id, tx_hash, memo, metadata, created_at)
+      VALUES
+        (@id, @facilitator, @requestId, @fromAddress, @toAddress, @amount, @asset, @chainId, @txHash, @memo, @metadata, @createdAt)
+    `);
+    stmt.run({
+      id: payload.id,
+      facilitator: payload.facilitator,
+      requestId: payload.requestId,
+      fromAddress: payload.fromAddress,
+      toAddress: payload.toAddress,
+      amount: payload.amount,
+      asset: payload.asset,
+      chainId: payload.chainId,
+      txHash: payload.txHash,
+      memo: payload.memo ?? null,
+      metadata: payload.metadata ? JSON.stringify(payload.metadata) : null,
+      createdAt: payload.timestamp,
+    });
+  }
+
+  async list(opts?: { facilitator?: string; limit?: number; offset?: number }): Promise<PaymentPayload[]> {
+    const conditions: string[] = [];
+    const params: Record<string, unknown> = {};
+
+    if (opts?.facilitator) {
+      conditions.push("facilitator = @facilitator");
+      params.facilitator = opts.facilitator;
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = opts?.limit ?? 50;
+    const offset = opts?.offset ?? 0;
+
+    const rows = this.db.prepare(
+      `SELECT * FROM payments ${where} ORDER BY created_at DESC LIMIT @limit OFFSET @offset`
+    ).all({ ...params, limit, offset }) as Record<string, unknown>[];
+
+    return rows.map(rowToPayload);
+  }
+
+  async get(id: string): Promise<PaymentPayload | null> {
+    const row = this.db.prepare("SELECT * FROM payments WHERE id = ?").get(id) as Record<string, unknown> | undefined;
+    return row ? rowToPayload(row) : null;
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}
+
+function rowToPayload(row: Record<string, unknown>): PaymentPayload {
+  return {
+    id: row.id as string,
+    facilitator: row.facilitator as string,
+    requestId: row.request_id as string,
+    fromAddress: row.from_addr as string,
+    toAddress: row.to_addr as string,
+    amount: row.amount as string,
+    asset: row.asset as string,
+    chainId: row.chain_id as string,
+    txHash: row.tx_hash as string,
+    memo: (row.memo as string) ?? undefined,
+    metadata: row.metadata ? JSON.parse(row.metadata as string) : undefined,
+    timestamp: row.created_at as number,
+  };
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+export interface PaymentPayload {
+  id: string
+  facilitator: string
+  requestId: string
+  fromAddress: string
+  toAddress: string
+  amount: string
+  asset: string
+  chainId: string
+  txHash: string
+  timestamp: number
+  memo?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface Store {
+  insert(payload: PaymentPayload): Promise<void>
+  list(opts?: { facilitator?: string; limit?: number; offset?: number }): Promise<PaymentPayload[]>
+  get(id: string): Promise<PaymentPayload | null>
+  close(): Promise<void>
+}
+
+export interface TallyConfig {
+  facilitator: string
+  store?: Store
+}
+
+export interface TallyClient {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
+  wrap(): void
+  unwrap(): void
+  store: Store
+  close(): Promise<void>
+}

package/test/hook.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createTallyFetch } from "../src/hook.js";
+import type { Store, PaymentPayload } from "../src/types.js";
+
+function createMockStore(): Store {
+  const inserts: PaymentPayload[] = [];
+  return {
+    insert: vi.fn(async (p: PaymentPayload) => { inserts.push(p); }),
+    list: vi.fn(async () => []),
+    get: vi.fn(async () => null),
+    close: vi.fn(async () => {}),
+  };
+}
+
+describe("createTallyFetch", () => {
+  let store: Store;
+
+  beforeEach(() => {
+    store = createMockStore();
+  });
+
+  it("passes through non-payment responses", async () => {
+    const mockFetch = vi.fn(async () => new Response("ok", { status: 200 }));
+    const tallyFetch = createTallyFetch(mockFetch, store);
+
+    const res = await tallyFetch("https://api.example.com/data");
+    expect(res.status).toBe(200);
+    expect(store.insert).not.toHaveBeenCalled();
+  });
+
+  it("extracts PaymentPayload from response with x-facilitator header", async () => {
+    const paymentPayload = {
+      requestId: "req-1",
+      fromAddress: "0xsender",
+      toAddress: "0xreceiver",
+      amount: "1.50",
+      asset: "USDC",
+      chainId: "eip155:8453",
+      txHash: "0xtx",
+      timestamp: Date.now(),
+    };
+
+    const mockFetch = vi.fn(async () =>
+      Response.json(paymentPayload, {
+        status: 200,
+        headers: { "x-facilitator": "dexter", "x-request-id": "req-1" },
+      })
+    );
+
+    const tallyFetch = createTallyFetch(mockFetch, store, { facilitator: "dexter" });
+    await tallyFetch("https://api.example.com/pay");
+
+    expect(store.insert).toHaveBeenCalledTimes(1);
+    const inserted = (store.insert as ReturnType<typeof vi.fn>).mock.calls[0][0] as PaymentPayload;
+    expect(inserted.facilitator).toBe("dexter");
+    expect(inserted.amount).toBe("1.50");
+    expect(inserted.chainId).toBe("eip155:8453");
+  });
+
+  it("generates an id when none is in the response", async () => {
+    const mockFetch = vi.fn(async () =>
+      Response.json({ amount: "5.00" }, {
+        status: 200,
+        headers: { "x-facilitator": "dexter", "x-request-id": "req-2" },
+      })
+    );
+
+    const tallyFetch = createTallyFetch(mockFetch, store, { facilitator: "dexter" });
+    await tallyFetch("https://api.example.com/pay");
+
+    expect(store.insert).toHaveBeenCalledTimes(1);
+    const inserted = (store.insert as ReturnType<typeof vi.fn>).mock.calls[0][0] as PaymentPayload;
+    expect(inserted.id).toBeDefined();
+    expect(inserted.id.length).toBeGreaterThan(0);
+  });
+
+  it("does not store on error responses", async () => {
+    const mockFetch = vi.fn(async () =>
+      Response.json({ error: "not found" }, { status: 404 })
+    );
+
+    const tallyFetch = createTallyFetch(mockFetch, store);
+    const res = await tallyFetch("https://api.example.com/nope");
+    expect(res.status).toBe(404);
+    expect(store.insert).not.toHaveBeenCalled();
+  });
+});

package/test/index.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+import { createTally } from "../src/index.js";
+
+describe("createTally", () => {
+  it("returns a TallyClient with a store", () => {
+    const tally = createTally({ facilitator: "dexter" });
+    expect(tally.fetch).toBeDefined();
+    expect(tally.wrap).toBeDefined();
+    expect(tally.unwrap).toBeDefined();
+    expect(tally.store).toBeDefined();
+    expect(tally.close).toBeDefined();
+    tally.close();
+  });
+
+  it("accepts a custom store", () => {
+    const customStore = {
+      insert: async () => {},
+      list: async () => [],
+      get: async () => null,
+      close: async () => {},
+    };
+    const tally = createTally({ facilitator: "dexter", store: customStore });
+    expect(tally.store).toBe(customStore);
+    tally.close();
+  });
+
+  it("wrap and unwrap monkey-patches and restores globalThis.fetch", () => {
+    const originalFetch = globalThis.fetch;
+    const tally = createTally({ facilitator: "dexter" });
+    tally.wrap();
+    expect(globalThis.fetch).not.toBe(originalFetch);
+    tally.unwrap();
+    expect(globalThis.fetch).toBe(originalFetch);
+    tally.close();
+  });
+});

package/test/integration.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { createTally } from "../src/index.js";
+import { SqliteStore } from "../src/store.js";
+import type { Store } from "../src/types.js";
+
+describe("integration", () => {
+  let store: Store;
+
+  afterEach(async () => {
+    await store.close();
+  });
+
+  it("captures a payment end-to-end", async () => {
+    const tally = createTally({ facilitator: "dexter" });
+    store = tally.store;
+
+    // Verify store is ready
+    const list = await tally.store.list();
+    expect(list).toEqual([]);
+
+    tally.close();
+  });
+
+  it("manual pipeline: hook captures, store persists", async () => {
+    const customStore = new SqliteStore(":memory:");
+    store = customStore;
+
+    const fetchSpy = async () =>
+      Response.json(
+        { requestId: "req-int", amount: "3.00", asset: "USDC", chainId: "eip155:1", txHash: "0xint" },
+        { status: 200, headers: { "x-facilitator": "dexter", "x-request-id": "req-int" } }
+      );
+
+    const { createTallyFetch } = await import("../src/hook.js");
+    const tallyFetch = createTallyFetch(fetchSpy, customStore, { facilitator: "dexter" });
+
+    await tallyFetch("https://api.example.com/pay");
+
+    const all = await customStore.list();
+    expect(all).toHaveLength(1);
+    expect(all[0].amount).toBe("3.00");
+    expect(all[0].facilitator).toBe("dexter");
+  });
+});

package/test/store.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SqliteStore } from "../src/store.js";
+import type { PaymentPayload } from "../src/types.js";
+
+function makePayload(overrides?: Partial<PaymentPayload>): PaymentPayload {
+  return {
+    id: overrides?.id ?? "test-1",
+    facilitator: overrides?.facilitator ?? "dexter",
+    requestId: "req-1",
+    fromAddress: "0xsender",
+    toAddress: "0xreceiver",
+    amount: "10.00",
+    asset: "USDC",
+    chainId: "eip155:1",
+    txHash: "0xtx",
+    timestamp: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("SqliteStore", () => {
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    store = new SqliteStore(":memory:");
+  });
+
+  afterEach(() => {
+    store.close();
+  });
+
+  it("inserts and retrieves a payment", async () => {
+    const payload = makePayload();
+    await store.insert(payload);
+    const result = await store.get(payload.id);
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(payload.id);
+    expect(result!.amount).toBe("10.00");
+  });
+
+  it("returns null for unknown id", async () => {
+    const result = await store.get("nonexistent");
+    expect(result).toBeNull();
+  });
+
+  it("lists payments ordered by created_at desc", async () => {
+    const p1 = makePayload({ id: "1", timestamp: 1000 });
+    const p2 = makePayload({ id: "2", timestamp: 2000 });
+    await store.insert(p1);
+    await store.insert(p2);
+    const all = await store.list();
+    expect(all).toHaveLength(2);
+    expect(all[0].id).toBe("2"); // newest first
+  });
+
+  it("filters by facilitator", async () => {
+    await store.insert(makePayload({ id: "1", facilitator: "dexter" }));
+    await store.insert(makePayload({ id: "2", facilitator: "coinbase-cdp" }));
+    const filtered = await store.list({ facilitator: "dexter" });
+    expect(filtered).toHaveLength(1);
+    expect(filtered[0].facilitator).toBe("dexter");
+  });
+
+  it("paginates with limit and offset", async () => {
+    for (let i = 0; i < 10; i++) {
+      await store.insert(makePayload({ id: `p${i}`, timestamp: i }));
+    }
+    const page = await store.list({ limit: 3, offset: 0 });
+    expect(page).toHaveLength(3);
+  });
+
+  it("handles metadata serialization", async () => {
+    const payload = makePayload({ metadata: { foo: "bar", num: 42 } });
+    await store.insert(payload);
+    const result = await store.get(payload.id);
+    expect(result!.metadata).toEqual({ foo: "bar", num: 42 });
+  });
+
+  it("ignores duplicate inserts (idempotency)", async () => {
+    const payload = makePayload({ id: "dup-1" });
+    await store.insert(payload);
+    await store.insert(payload);
+    const result = await store.get("dup-1");
+    expect(result).not.toBeNull();
+    const all = await store.list();
+    expect(all).toHaveLength(1);
+  });
+});

package/test/types.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import type { PaymentPayload, Store, TallyConfig, TallyClient } from "../src/types.js";
+
+describe("types", () => {
+  it("PaymentPayload can be constructed", () => {
+    const payload: PaymentPayload = {
+      id: "abc-123",
+      facilitator: "dexter",
+      requestId: "req-1",
+      fromAddress: "0xsender",
+      toAddress: "0xreceiver",
+      amount: "10.00",
+      asset: "USDC",
+      chainId: "eip155:1",
+      txHash: "0xtx",
+      timestamp: Date.now(),
+    };
+    expect(payload.amount).toBe("10.00");
+  });
+
+  it("Store interface is structurally typed", () => {
+    const store: Store = {
+      insert: async () => {},
+      list: async () => [],
+      get: async () => null,
+      close: async () => {},
+    };
+    expect(store).toBeDefined();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}