@caypo/canton-sdk 0.1.0

package/src/__tests__/client.test.ts

@@ -0,0 +1,516 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { CantonClient } from "../canton/client.js";
+import { CantonApiError, CantonAuthError, CantonTimeoutError } from "../canton/errors.js";
+import type { Command, LedgerError } from "../canton/types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const BASE_URL = "http://localhost:7575";
+const TOKEN = "test-jwt-token";
+const USER_ID = "ledger-api-user";
+const PARTY = "Alice::122084768362d0ce21f1ffec870e55e365a292cdf8f54c5c38ad7775b9bdd462e141";
+
+function makeClient(overrides?: { timeout?: number }) {
+  return new CantonClient({
+    ledgerUrl: BASE_URL,
+    token: TOKEN,
+    userId: USER_ID,
+    timeout: overrides?.timeout,
+  });
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function errorResponse(error: LedgerError, status = 400): Response {
+  return new Response(JSON.stringify(error), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const mockFetch = vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>();
+
+beforeEach(() => {
+  vi.stubGlobal("fetch", mockFetch);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Auth header inclusion
+// ---------------------------------------------------------------------------
+
+describe("auth header", () => {
+  it("includes Bearer token on every request", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(jsonResponse({ offset: 42 }));
+
+    await client.getLedgerEnd();
+
+    expect(mockFetch).toHaveBeenCalledOnce();
+    const [, init] = mockFetch.mock.calls[0];
+    expect((init?.headers as Record<string, string>)["Authorization"]).toBe(`Bearer ${TOKEN}`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// submitAndWait
+// ---------------------------------------------------------------------------
+
+describe("submitAndWait", () => {
+  const commands: Command[] = [
+    {
+      CreateCommand: {
+        templateId: "#json-tests:Main:Asset",
+        createArguments: { issuer: PARTY, owner: PARTY, name: "Asset" },
+      },
+    },
+  ];
+
+  it("sends correct request and returns updateId + completionOffset", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse({ updateId: "update-123", completionOffset: 20 }),
+    );
+
+    const result = await client.submitAndWait({
+      commands,
+      commandId: "cmd-1",
+      actAs: [PARTY],
+      readAs: [PARTY],
+    });
+
+    expect(result).toEqual({ updateId: "update-123", completionOffset: 20 });
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe(`${BASE_URL}/v2/commands/submit-and-wait`);
+    expect(init?.method).toBe("POST");
+    expect((init?.headers as Record<string, string>)["Content-Type"]).toBe("application/json");
+
+    const body = JSON.parse(init?.body as string);
+    expect(body.userId).toBe(USER_ID);
+    expect(body.commandId).toBe("cmd-1");
+    expect(body.actAs).toEqual([PARTY]);
+    expect(body.readAs).toEqual([PARTY]);
+    expect(body.commands).toEqual(commands);
+  });
+
+  it("throws CantonApiError on ledger error response", async () => {
+    const client = makeClient();
+    const ledgerError: LedgerError = {
+      cause: "Invalid template ID",
+      code: "INVALID_ARGUMENT",
+      context: { category: "8", participant: "participant1" },
+      errorCategory: 8,
+      grpcCodeValue: 3,
+    };
+    mockFetch.mockResolvedValueOnce(errorResponse(ledgerError));
+
+    await expect(
+      client.submitAndWait({ commands, commandId: "cmd-2", actAs: [PARTY] }),
+    ).rejects.toThrow(CantonApiError);
+
+    try {
+      await client.submitAndWait({ commands, commandId: "cmd-2", actAs: [PARTY] });
+    } catch (err) {
+      // fetch was only mocked once, so we test the first rejection
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// submitAndWaitForTransaction
+// ---------------------------------------------------------------------------
+
+describe("submitAndWaitForTransaction", () => {
+  it("sends to correct endpoint and returns transaction", async () => {
+    const client = makeClient();
+    const txResponse = {
+      transaction: {
+        updateId: "tx-456",
+        commandId: "cmd-3",
+        effectiveAt: "2025-01-01T00:00:00Z",
+        offset: 30,
+        events: [{ createdEvent: { contractId: "cid-1", templateId: "pkg:M:T", createArgument: {} } }],
+      },
+    };
+    mockFetch.mockResolvedValueOnce(jsonResponse(txResponse));
+
+    const result = await client.submitAndWaitForTransaction({
+      commands: [
+        {
+          ExerciseCommand: {
+            templateId: "pkg:Module:Template",
+            contractId: "00572c50",
+            choice: "ChoiceName",
+            choiceArgument: { field: "value" },
+          },
+        },
+      ],
+      commandId: "cmd-3",
+      actAs: [PARTY],
+    });
+
+    expect(result.transaction.updateId).toBe("tx-456");
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe(`${BASE_URL}/v2/commands/submit-and-wait-for-transaction`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// queryActiveContracts
+// ---------------------------------------------------------------------------
+
+describe("queryActiveContracts", () => {
+  it("returns parsed active contracts", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse({
+        contractEntry: [
+          {
+            createdEvent: {
+              contractId: "cid-100",
+              templateId: "pkg:Token:Holding",
+              createArgument: { amount: "5.000000" },
+              witnessParties: [PARTY],
+              signatories: [PARTY],
+              observers: [],
+            },
+          },
+          {
+            createdEvent: {
+              contractId: "cid-101",
+              templateId: "pkg:Token:Holding",
+              createArgument: { amount: "3.000000" },
+              witnessParties: [PARTY],
+              signatories: [PARTY],
+              observers: [],
+            },
+          },
+        ],
+      }),
+    );
+
+    const contracts = await client.queryActiveContracts({
+      filtersByParty: {
+        [PARTY]: {
+          cumulative: [
+            {
+              identifierFilter: {
+                TemplateFilter: { value: { templateId: "pkg:Token:Holding" } },
+              },
+            },
+          ],
+        },
+      },
+      activeAtOffset: 20,
+    });
+
+    expect(contracts).toHaveLength(2);
+    expect(contracts[0].contractId).toBe("cid-100");
+    expect(contracts[1].createArgument).toEqual({ amount: "3.000000" });
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1]?.body as string);
+    expect(body.activeAtOffset).toBe(20);
+    expect(body.eventFormat.verbose).toBe(true);
+  });
+
+  it("returns empty array when no contractEntry", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(jsonResponse({}));
+
+    const contracts = await client.queryActiveContracts({ activeAtOffset: 0 });
+    expect(contracts).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTransactionById
+// ---------------------------------------------------------------------------
+
+describe("getTransactionById", () => {
+  it("returns transaction tree on success", async () => {
+    const client = makeClient();
+    const tree = {
+      updateId: "upd-789",
+      commandId: "cmd-4",
+      effectiveAt: "2025-06-01T12:00:00Z",
+      offset: 50,
+      eventsById: {},
+      rootEventIds: ["evt-1"],
+    };
+    mockFetch.mockResolvedValueOnce(jsonResponse(tree));
+
+    const result = await client.getTransactionById("upd-789");
+
+    expect(result).toEqual(tree);
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe(`${BASE_URL}/v2/updates/transaction-by-id/upd-789`);
+  });
+
+  it("returns null when NOT_FOUND", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(
+      errorResponse(
+        {
+          cause: "Transaction not found",
+          code: "NOT_FOUND",
+          context: {},
+          errorCategory: 5,
+          grpcCodeValue: 5,
+        },
+        404,
+      ),
+    );
+
+    const result = await client.getTransactionById("nonexistent");
+    expect(result).toBeNull();
+  });
+
+  it("URL-encodes the updateId", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse({ updateId: "id/with/slashes", commandId: "", effectiveAt: "", offset: 0, eventsById: {}, rootEventIds: [] }),
+    );
+
+    await client.getTransactionById("id/with/slashes");
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe(`${BASE_URL}/v2/updates/transaction-by-id/id%2Fwith%2Fslashes`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getLedgerEnd
+// ---------------------------------------------------------------------------
+
+describe("getLedgerEnd", () => {
+  it("returns the offset number", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(jsonResponse({ offset: 42 }));
+
+    const offset = await client.getLedgerEnd();
+    expect(offset).toBe(42);
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe(`${BASE_URL}/v2/state/ledger-end`);
+    expect(init?.method).toBe("GET");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// allocateParty
+// ---------------------------------------------------------------------------
+
+describe("allocateParty", () => {
+  it("sends partyIdHint and returns PartyDetails", async () => {
+    const client = makeClient();
+    const partyDetails = {
+      party: PARTY,
+      isLocal: true,
+      localMetadata: { resourceVersion: "0", annotations: {} },
+      identityProviderId: "",
+    };
+    mockFetch.mockResolvedValueOnce(jsonResponse({ partyDetails }));
+
+    const result = await client.allocateParty("Alice");
+
+    expect(result).toEqual(partyDetails);
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1]?.body as string);
+    expect(body.partyIdHint).toBe("Alice");
+    expect(body.identityProviderId).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listParties
+// ---------------------------------------------------------------------------
+
+describe("listParties", () => {
+  it("returns array of PartyDetails", async () => {
+    const client = makeClient();
+    const parties = [
+      {
+        party: PARTY,
+        isLocal: true,
+        localMetadata: { resourceVersion: "0", annotations: {} },
+        identityProviderId: "",
+      },
+    ];
+    mockFetch.mockResolvedValueOnce(jsonResponse({ partyDetails: parties }));
+
+    const result = await client.listParties();
+    expect(result).toHaveLength(1);
+    expect(result[0].party).toBe(PARTY);
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe(`${BASE_URL}/v2/parties`);
+    expect(init?.method).toBe("GET");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isHealthy
+// ---------------------------------------------------------------------------
+
+describe("isHealthy", () => {
+  it("returns true when /livez responds 200", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(new Response("ok", { status: 200 }));
+
+    expect(await client.isHealthy()).toBe(true);
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe(`${BASE_URL}/livez`);
+  });
+
+  it("returns false when /livez responds non-200", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(new Response("", { status: 503 }));
+
+    expect(await client.isHealthy()).toBe(false);
+  });
+
+  it("returns false when fetch throws (network error)", async () => {
+    const client = makeClient();
+    mockFetch.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+
+    expect(await client.isHealthy()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Error handling
+// ---------------------------------------------------------------------------
+
+describe("error handling", () => {
+  it("throws CantonAuthError on 401", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(new Response("Unauthorized", { status: 401 }));
+
+    await expect(client.getLedgerEnd()).rejects.toThrow(CantonAuthError);
+  });
+
+  it("throws CantonAuthError on 403", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(new Response("Forbidden", { status: 403 }));
+
+    await expect(client.getLedgerEnd()).rejects.toThrow(CantonAuthError);
+  });
+
+  it("CantonAuthError preserves status code", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(new Response("Forbidden", { status: 403 }));
+
+    try {
+      await client.getLedgerEnd();
+    } catch (err) {
+      expect(err).toBeInstanceOf(CantonAuthError);
+      expect((err as CantonAuthError).statusCode).toBe(403);
+    }
+  });
+
+  it("throws CantonApiError with full details on structured error", async () => {
+    const client = makeClient();
+    const ledgerError: LedgerError = {
+      cause: "Contract already exists",
+      code: "ALREADY_EXISTS",
+      context: { category: "6" },
+      errorCategory: 6,
+      grpcCodeValue: 6,
+    };
+    mockFetch.mockResolvedValueOnce(errorResponse(ledgerError, 409));
+
+    try {
+      await client.getLedgerEnd();
+      expect.fail("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(CantonApiError);
+      const apiErr = err as CantonApiError;
+      expect(apiErr.code).toBe("ALREADY_EXISTS");
+      expect(apiErr.ledgerCause).toBe("Contract already exists");
+      expect(apiErr.grpcCodeValue).toBe(6);
+      expect(apiErr.errorCategory).toBe(6);
+    }
+  });
+
+  it("throws generic Error on non-structured error response", async () => {
+    const client = makeClient();
+    mockFetch.mockResolvedValueOnce(new Response("Internal Server Error", { status: 500 }));
+
+    await expect(client.getLedgerEnd()).rejects.toThrow("Canton API error: HTTP 500");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Timeout handling
+// ---------------------------------------------------------------------------
+
+describe("timeout handling", () => {
+  it("throws CantonTimeoutError when request times out", async () => {
+    const client = makeClient({ timeout: 100 });
+    mockFetch.mockImplementationOnce(() => {
+      const err = new DOMException("The operation was aborted.", "TimeoutError");
+      return Promise.reject(err);
+    });
+
+    await expect(client.getLedgerEnd()).rejects.toThrow(CantonTimeoutError);
+  });
+
+  it("CantonTimeoutError includes path and timeout value", async () => {
+    const client = makeClient({ timeout: 5000 });
+    mockFetch.mockImplementationOnce(() => {
+      return Promise.reject(new DOMException("Aborted", "TimeoutError"));
+    });
+
+    try {
+      await client.getLedgerEnd();
+      expect.fail("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(CantonTimeoutError);
+      const timeoutErr = err as CantonTimeoutError;
+      expect(timeoutErr.path).toBe("/v2/state/ledger-end");
+      expect(timeoutErr.timeoutMs).toBe(5000);
+    }
+  });
+
+  it("treats AbortError as timeout", async () => {
+    const client = makeClient({ timeout: 100 });
+    mockFetch.mockImplementationOnce(() => {
+      return Promise.reject(new DOMException("Aborted", "AbortError"));
+    });
+
+    await expect(client.getLedgerEnd()).rejects.toThrow(CantonTimeoutError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// URL construction
+// ---------------------------------------------------------------------------
+
+describe("URL construction", () => {
+  it("strips trailing slash from ledgerUrl", async () => {
+    const client = new CantonClient({
+      ledgerUrl: "http://localhost:7575/",
+      token: TOKEN,
+      userId: USER_ID,
+    });
+    mockFetch.mockResolvedValueOnce(jsonResponse({ offset: 1 }));
+
+    await client.getLedgerEnd();
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toBe("http://localhost:7575/v2/state/ledger-end");
+  });
+});

package/src/__tests__/e2e/canton-client.e2e.test.ts

@@ -0,0 +1,190 @@
+/**
+ * CantonClient E2E tests — runs against a real Canton sandbox.
+ * Uses capability detection to skip tests that need unavailable features.
+ * Skipped entirely if no Canton node is reachable.
+ */
+
+import { beforeAll, describe, expect, it } from "vitest";
+import { CantonClient } from "../../canton/client.js";
+import { CantonApiError, CantonAuthError } from "../../canton/errors.js";
+import {
+  getCantonConnection,
+  detectCapabilities,
+  createTestClient,
+  createTestParty,
+  type CantonCapabilities,
+} from "./setup.js";
+
+let client: CantonClient;
+let cantonAvailable = false;
+let caps: CantonCapabilities = {
+  cantonAvailable: false,
+  v2ApiAvailable: false,
+  partyCreation: false,
+  authRequired: false,
+};
+
+beforeAll(async () => {
+  const conn = await getCantonConnection();
+  cantonAvailable = conn.isAvailable;
+  if (cantonAvailable) {
+    client = createTestClient(conn.ledgerUrl);
+    caps = await detectCapabilities(conn.ledgerUrl);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Core — only needs /livez
+// ---------------------------------------------------------------------------
+
+describe.skipIf(!cantonAvailable)("CantonClient E2E — Core", () => {
+  it("should confirm Canton node is healthy via /livez", async () => {
+    expect(await client.isHealthy()).toBe(true);
+  });
+
+  it("should return false for non-routable IP", async () => {
+    const bad = new CantonClient({ ledgerUrl: "http://192.0.2.1:7575", token: "t", userId: "u", timeout: 1000 });
+    expect(await bad.isHealthy()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// v2 API — needs /v2/state/ledger-end
+// ---------------------------------------------------------------------------
+
+describe.skipIf(!caps.v2ApiAvailable)("CantonClient E2E — v2 API", () => {
+  it("should return ledger offset as number >= 0", async () => {
+    const offset = await client.getLedgerEnd();
+    expect(typeof offset).toBe("number");
+    expect(offset).toBeGreaterThanOrEqual(0);
+  });
+
+  it("should query active contracts with WildcardFilter", async () => {
+    const offset = await client.getLedgerEnd();
+    const contracts = await client.queryActiveContracts({
+      filtersForAnyParty: {
+        cumulative: [{ identifierFilter: { WildcardFilter: { value: { includeCreatedEventBlob: false } } } }],
+      },
+      activeAtOffset: offset,
+    });
+    expect(Array.isArray(contracts)).toBe(true);
+  });
+
+  it("should return null for non-existent transaction", async () => {
+    expect(await client.getTransactionById("nonexistent-99999")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Parties — needs party creation
+// ---------------------------------------------------------------------------
+
+describe.skipIf(!caps.partyCreation)("CantonClient E2E — Parties", () => {
+  it("should allocate party matching Name::hexfingerprint", async () => {
+    const party = await createTestParty(client, "e2e-test");
+    expect(party).toMatch(/^e2e-test.*::[a-f0-9]+$/);
+  });
+
+  it("should list parties including newly created one", async () => {
+    const newParty = await createTestParty(client, "e2e-list");
+    const parties = await client.listParties();
+    expect(parties.length).toBeGreaterThan(0);
+    expect(parties.some((p) => p.party === newParty)).toBe(true);
+  });
+
+  it("should return isLocal=true with valid localMetadata", async () => {
+    const details = await client.allocateParty(`e2e-local-${Date.now()}`);
+    expect(details.isLocal).toBe(true);
+    expect(details.localMetadata).toBeDefined();
+    expect(details.localMetadata.resourceVersion).toBeDefined();
+  });
+
+  it("should produce unique party IDs for same prefix", async () => {
+    const p1 = await createTestParty(client, "e2e-dup");
+    const p2 = await createTestParty(client, "e2e-dup");
+    expect(p1).not.toBe(p2);
+  });
+
+  it("should advance ledger offset after party creation", async () => {
+    const off1 = await client.getLedgerEnd();
+    await createTestParty(client, "e2e-advance");
+    const off2 = await client.getLedgerEnd();
+    expect(off2).toBeGreaterThanOrEqual(off1);
+  });
+
+  it("should return empty contracts for fresh party", async () => {
+    const party = await createTestParty(client, "e2e-empty");
+    const offset = await client.getLedgerEnd();
+    const contracts = await client.queryActiveContracts({
+      filtersByParty: {
+        [party]: { cumulative: [{ identifierFilter: { WildcardFilter: { value: {} } } }] },
+      },
+      activeAtOffset: offset,
+    });
+    expect(contracts).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Errors — needs v2 API
+// ---------------------------------------------------------------------------
+
+describe.skipIf(!caps.v2ApiAvailable)("CantonClient E2E — Errors", () => {
+  it("should throw structured error for invalid command", async () => {
+    try {
+      await client.submitAndWait({
+        commands: [{ CreateCommand: { createArguments: {}, templateId: "nonexistent:Module:Template" } }],
+        commandId: `err-${Date.now()}`,
+        actAs: ["nonexistent::0000"],
+      });
+      expect.fail("Should have thrown");
+    } catch (err) {
+      expect(err instanceof CantonApiError || err instanceof CantonAuthError || err instanceof Error).toBe(true);
+      if (err instanceof CantonApiError) {
+        expect(err.code).toBeTruthy();
+        expect(typeof err.grpcCodeValue).toBe("number");
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CreateCommand + Query cycle — requires DAR
+// ---------------------------------------------------------------------------
+
+describe.skipIf(!caps.partyCreation)("CantonClient E2E — Command Cycle", () => {
+  it("should submit CreateCommand and query back (if DAR loaded)", async () => {
+    const party = await createTestParty(client, "e2e-create");
+    try {
+      const result = await client.submitAndWait({
+        commands: [{
+          CreateCommand: {
+            templateId: "#caypo-test-token:Token:Token",
+            createArguments: { issuer: party, owner: party, amount: "100.0", name: "TestUSDCx" },
+          },
+        }],
+        commandId: `create-${Date.now()}`,
+        actAs: [party],
+      });
+
+      expect(result.updateId).toBeTruthy();
+      expect(result.completionOffset).toBeGreaterThan(0);
+
+      // Query back
+      const offset = await client.getLedgerEnd();
+      const contracts = await client.queryActiveContracts({
+        filtersByParty: { [party]: { cumulative: [{ identifierFilter: { WildcardFilter: { value: {} } } }] } },
+        activeAtOffset: offset,
+      });
+      expect(contracts.length).toBeGreaterThan(0);
+      const token = contracts.find((c) => c.createArgument.name === "TestUSDCx");
+      expect(token).toBeDefined();
+    } catch (err) {
+      // DAR not loaded — expected on bare sandbox
+      if (err instanceof CantonApiError && (err.code === "INVALID_ARGUMENT" || err.code === "NOT_FOUND")) {
+        return;
+      }
+      throw err;
+    }
+  });
+});