cantonjs 0.0.1

package/dist/esm/streaming/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Streaming types for Canton WebSocket connections.
+ *
+ * Canton WebSocket protocol:
+ * - Auth via subprotocols: ['daml.ws.auth', 'jwt.token.<JWT>']
+ * - One subscription per connection (no multiplexing)
+ * - Messages are individual JSON frames
+ * - OffsetCheckpoint messages serve as heartbeats
+ */
+import type { EventFormat } from '../types/command.js';
+/**
+ * WebSocket constructor type.
+ * Accepts browser-native WebSocket or Node.js `ws` package.
+ */
+export type WebSocketConstructor = {
+    new (url: string, protocols?: string | string[]): WebSocketLike;
+};
+/** Minimal WebSocket interface needed by the streaming layer. */
+export type WebSocketLike = {
+    readyState: number;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    close(code?: number, reason?: string): void;
+    send(data: string): void;
+};
+/** WebSocket readyState constants. */
+export declare const WS_READY_STATE: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/** Reconnection configuration. */
+export type ReconnectConfig = {
+    /** Initial delay in milliseconds. Default: 1000. */
+    readonly initialDelay?: number;
+    /** Maximum delay in milliseconds. Default: 30000. */
+    readonly maxDelay?: number;
+    /** Backoff multiplier. Default: 2. */
+    readonly factor?: number;
+    /** Jitter factor (0 to 1). Default: 0.25. */
+    readonly jitter?: number;
+    /** Maximum reconnection attempts. Default: Infinity. */
+    readonly maxAttempts?: number;
+};
+/** Base options shared by all stream functions. */
+export type StreamOptions = {
+    /** Base URL of the Canton node (http/https, will be converted to ws/wss). */
+    readonly url: string;
+    /** JWT token for authentication. */
+    readonly token?: string;
+    /** WebSocket constructor to use. Defaults to globalThis.WebSocket. */
+    readonly WebSocket?: WebSocketConstructor;
+    /** AbortSignal to cancel the stream. */
+    readonly signal?: AbortSignal;
+    /** Reconnection configuration. Set to false to disable auto-reconnect. */
+    readonly reconnect?: ReconnectConfig | false;
+};
+/** Options for the /v2/updates stream. */
+export type StreamUpdatesOptions = StreamOptions & {
+    /** Start reading after this offset (exclusive). */
+    readonly beginExclusive?: number;
+    /** Stop reading at this offset (inclusive). Omit for open-ended stream. */
+    readonly endInclusive?: number;
+    /** Format for received updates. */
+    readonly updateFormat?: {
+        readonly includeTransactions?: {
+            readonly transactionShape: 'TRANSACTION_SHAPE_ACS_DELTA' | 'TRANSACTION_SHAPE_LEDGER_EFFECTS';
+            readonly eventFormat: EventFormat;
+        };
+        readonly includeReassignments?: EventFormat;
+        readonly includeTopologyEvents?: unknown;
+    };
+};
+/** Options for the /v2/state/active-contracts stream. */
+export type StreamContractsOptions = StreamOptions & {
+    /** Event format with party filters. */
+    readonly eventFormat: EventFormat;
+    /** Offset to read the ACS at. Omit for current. */
+    readonly activeAtOffset?: number;
+};
+/** Options for the /v2/commands/completions stream. */
+export type StreamCompletionsOptions = StreamOptions & {
+    /** Start reading after this offset (exclusive). */
+    readonly beginExclusive?: number;
+    /** Parties whose completions to receive. */
+    readonly parties: readonly string[];
+    /** Application ID filter. */
+    readonly applicationId?: string;
+};
+/** Completion event from the completions stream. */
+export type CompletionEvent = {
+    readonly completion: {
+        readonly commandId: string;
+        readonly updateId?: string;
+        readonly status?: {
+            readonly code: number;
+            readonly message: string;
+        };
+        readonly offset?: number;
+        readonly synchronizerId?: string;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/streaming/types.d.ts.map

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

package/dist/esm/streaming/types.js

@@ -0,0 +1,17 @@
+/**
+ * Streaming types for Canton WebSocket connections.
+ *
+ * Canton WebSocket protocol:
+ * - Auth via subprotocols: ['daml.ws.auth', 'jwt.token.<JWT>']
+ * - One subscription per connection (no multiplexing)
+ * - Messages are individual JSON frames
+ * - OffsetCheckpoint messages serve as heartbeats
+ */
+/** WebSocket readyState constants. */
+export const WS_READY_STATE = {
+    CONNECTING: 0,
+    OPEN: 1,
+    CLOSING: 2,
+    CLOSED: 3,
+};
+//# sourceMappingURL=types.js.map

package/dist/esm/streaming/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/streaming/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,sCAAsC;AACtC,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU,EAAE,CAAC;IACb,IAAI,EAAE,CAAC;IACP,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,CAAC;CACD,CAAA"}

package/dist/esm/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { createTestClient, type TestClient, type TestClientConfig, } from '../clients/createTestClient.js';
+export { setupCantonSandbox, type SandboxConfig, type SandboxContext, } from './setupSandbox.js';
+export { createMockTransport, createRecordingTransport, type RecordedExchange, type RequestMatcher, } from './mockTransport.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAA"}

package/dist/esm/testing/index.js

@@ -0,0 +1,4 @@
+export { createTestClient, } from '../clients/createTestClient.js';
+export { setupCantonSandbox, } from './setupSandbox.js';
+export { createMockTransport, createRecordingTransport, } from './mockTransport.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAGjB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,EACL,kBAAkB,GAGnB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,GAGzB,MAAM,oBAAoB,CAAA"}

package/dist/esm/testing/mockTransport.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Mock transport for testing dApp code without a running Canton node.
+ *
+ * Provides two patterns:
+ * - createMockTransport() — respond with pre-configured responses
+ * - createRecordingTransport() — record real responses for later replay
+ */
+import type { Transport } from '../transport/types.js';
+/** A recorded request/response pair. */
+export type RecordedExchange = {
+    readonly request: {
+        readonly method: string;
+        readonly path: string;
+        readonly body?: unknown;
+    };
+    readonly response: unknown;
+};
+/** Matcher for routing mock responses. */
+export type RequestMatcher = {
+    /** HTTP method to match. If omitted, matches any method. */
+    readonly method?: string;
+    /** Path prefix or exact path to match. */
+    readonly path: string;
+    /** Response to return when matched. */
+    readonly response: unknown;
+};
+/**
+ * Create a mock transport that returns pre-configured responses.
+ *
+ * Responses are matched by path (prefix match) and optionally method.
+ * If no matcher is found, returns the `defaultResponse` or throws.
+ *
+ * @example
+ * ```typescript
+ * const transport = createMockTransport({
+ *   matchers: [
+ *     { path: '/v2/parties', response: { partyDetails: [] } },
+ *     { method: 'POST', path: '/v2/commands', response: { transaction: { ... } } },
+ *   ],
+ * })
+ *
+ * const client = createLedgerClient({ transport, actAs: party })
+ * ```
+ */
+export declare function createMockTransport(options?: {
+    matchers?: readonly RequestMatcher[];
+    defaultResponse?: unknown;
+    url?: string;
+}): Transport & {
+    readonly calls: readonly RecordedExchange[];
+};
+/**
+ * Create a transport that records all exchanges from a real transport.
+ *
+ * Wraps an existing transport and stores every request/response pair.
+ * Use `transport.recordings` to access recorded exchanges for replay.
+ *
+ * @example
+ * ```typescript
+ * const real = jsonApi({ url: 'http://localhost:7575', token: jwt })
+ * const recording = createRecordingTransport(real)
+ *
+ * // Use recording transport with your client...
+ * const client = createLedgerClient({ transport: recording, actAs: party })
+ * await client.queryContracts(templateId)
+ *
+ * // Later, replay the recordings
+ * const replay = createMockTransport({
+ *   matchers: recording.recordings.map(r => ({
+ *     method: r.request.method,
+ *     path: r.request.path,
+ *     response: r.response,
+ *   })),
+ * })
+ * ```
+ */
+export declare function createRecordingTransport(inner: Transport): Transport & {
+    readonly recordings: readonly RecordedExchange[];
+};
+//# sourceMappingURL=mockTransport.d.ts.map

package/dist/esm/testing/mockTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mockTransport.d.ts","sourceRoot":"","sources":["../../../src/testing/mockTransport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,uBAAuB,CAAA;AAExE,wCAAwC;AACxC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KACxB,CAAA;IACD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE;IAC3C,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IACpC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,GAAG,CAAC,EAAE,MAAM,CAAA;CACR,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAAE,CA+BnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,GACf,SAAS,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAAE,CAmBlE"}

package/dist/esm/testing/mockTransport.js

@@ -0,0 +1,93 @@
+/**
+ * Mock transport for testing dApp code without a running Canton node.
+ *
+ * Provides two patterns:
+ * - createMockTransport() — respond with pre-configured responses
+ * - createRecordingTransport() — record real responses for later replay
+ */
+/**
+ * Create a mock transport that returns pre-configured responses.
+ *
+ * Responses are matched by path (prefix match) and optionally method.
+ * If no matcher is found, returns the `defaultResponse` or throws.
+ *
+ * @example
+ * ```typescript
+ * const transport = createMockTransport({
+ *   matchers: [
+ *     { path: '/v2/parties', response: { partyDetails: [] } },
+ *     { method: 'POST', path: '/v2/commands', response: { transaction: { ... } } },
+ *   ],
+ * })
+ *
+ * const client = createLedgerClient({ transport, actAs: party })
+ * ```
+ */
+export function createMockTransport(options = {}) {
+    const { matchers = [], defaultResponse, url = 'http://mock:7575' } = options;
+    const calls = [];
+    return {
+        type: 'mock',
+        url,
+        calls,
+        async request(args) {
+            const matcher = matchers.find((m) => {
+                if (m.method && m.method !== args.method)
+                    return false;
+                return args.path.startsWith(m.path);
+            });
+            const response = matcher?.response ?? defaultResponse;
+            if (response === undefined) {
+                throw new Error(`No mock response for ${args.method} ${args.path}. ` +
+                    `Add a matcher or set defaultResponse.`);
+            }
+            calls.push({
+                request: { method: args.method, path: args.path, body: args.body },
+                response,
+            });
+            return response;
+        },
+    };
+}
+/**
+ * Create a transport that records all exchanges from a real transport.
+ *
+ * Wraps an existing transport and stores every request/response pair.
+ * Use `transport.recordings` to access recorded exchanges for replay.
+ *
+ * @example
+ * ```typescript
+ * const real = jsonApi({ url: 'http://localhost:7575', token: jwt })
+ * const recording = createRecordingTransport(real)
+ *
+ * // Use recording transport with your client...
+ * const client = createLedgerClient({ transport: recording, actAs: party })
+ * await client.queryContracts(templateId)
+ *
+ * // Later, replay the recordings
+ * const replay = createMockTransport({
+ *   matchers: recording.recordings.map(r => ({
+ *     method: r.request.method,
+ *     path: r.request.path,
+ *     response: r.response,
+ *   })),
+ * })
+ * ```
+ */
+export function createRecordingTransport(inner) {
+    const recordings = [];
+    return {
+        type: `recording(${inner.type})`,
+        url: inner.url,
+        recordings,
+        async request(args) {
+            const response = await inner.request(args);
+            recordings.push({
+                request: { method: args.method, path: args.path, body: args.body },
+                response,
+            });
+            return response;
+        },
+    };
+}
+//# sourceMappingURL=mockTransport.js.map

package/dist/esm/testing/mockTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mockTransport.js","sourceRoot":"","sources":["../../../src/testing/mockTransport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwBH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAIhC,EAAE;IACJ,MAAM,EAAE,QAAQ,GAAG,EAAE,EAAE,eAAe,EAAE,GAAG,GAAG,kBAAkB,EAAE,GAAG,OAAO,CAAA;IAC5E,MAAM,KAAK,GAAuB,EAAE,CAAA;IAEpC,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,GAAG;QACH,KAAK;QAEL,KAAK,CAAC,OAAO,CAAY,IAAsB;YAC7C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;gBAClC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;oBAAE,OAAO,KAAK,CAAA;gBACtD,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YACrC,CAAC,CAAC,CAAA;YAEF,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,eAAe,CAAA;YACrD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,IAAI;oBACpD,uCAAuC,CACxC,CAAA;YACH,CAAC;YAED,KAAK,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;gBAClE,QAAQ;aACT,CAAC,CAAA;YAEF,OAAO,QAAqB,CAAA;QAC9B,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAgB;IAEhB,MAAM,UAAU,GAAuB,EAAE,CAAA;IAEzC,OAAO;QACL,IAAI,EAAE,aAAa,KAAK,CAAC,IAAI,GAAG;QAChC,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,UAAU;QAEV,KAAK,CAAC,OAAO,CAAY,IAAsB;YAC7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAY,IAAI,CAAC,CAAA;YAErD,UAAU,CAAC,IAAI,CAAC;gBACd,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;gBAClE,QAAQ;aACT,CAAC,CAAA;YAEF,OAAO,QAAQ,CAAA;QACjB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/esm/testing/setupSandbox.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Vitest fixture for Canton sandbox lifecycle via cantonctl.
+ *
+ * Requires cantonctl to be installed and available on PATH.
+ * If cantonctl is not available, the fixture throws with a helpful message.
+ *
+ * @example
+ * ```typescript
+ * import { setupCantonSandbox } from 'cantonjs/testing'
+ *
+ * const sandbox = await setupCantonSandbox()
+ * // sandbox.client is a fully configured TestClient
+ * // sandbox.transport is the underlying transport
+ * // sandbox.url is the JSON API base URL
+ *
+ * // ... run tests ...
+ *
+ * await sandbox.teardown()
+ * ```
+ */
+import { type TestClient } from '../clients/createTestClient.js';
+import type { Transport } from '../transport/types.js';
+import type { Party } from '../types/party.js';
+/** Configuration for sandbox setup. */
+export type SandboxConfig = {
+    /** Port for the JSON API. Default: 7575. */
+    readonly port?: number;
+    /** Timeout in milliseconds for sandbox to become ready. Default: 30000. */
+    readonly timeout?: number;
+    /** JWT token. If not provided, attempts to use cantonctl auth. */
+    readonly token?: string;
+    /** Party for the TestClient. Default: allocated via sandbox. */
+    readonly party?: Party;
+    /** Custom fetch implementation (for testing the fixture itself). */
+    readonly fetchFn?: typeof fetch;
+    /** Custom exec implementation (for testing the fixture itself). */
+    readonly execFn?: (cmd: string) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+};
+/** Result from setupCantonSandbox(). */
+export type SandboxContext = {
+    /** The base URL of the running sandbox JSON API. */
+    readonly url: string;
+    /** The transport connected to the sandbox. */
+    readonly transport: Transport;
+    /** A fully configured TestClient. */
+    readonly client: TestClient;
+    /** Tear down the sandbox. */
+    readonly teardown: () => Promise<void>;
+};
+/**
+ * Set up a Canton sandbox for integration testing.
+ *
+ * Requires `cantonctl` to be installed. Starts a sandbox,
+ * waits for it to be ready, and returns a configured TestClient.
+ *
+ * Call `teardown()` when done to stop the sandbox.
+ */
+export declare function setupCantonSandbox(config?: SandboxConfig): Promise<SandboxContext>;
+//# sourceMappingURL=setupSandbox.d.ts.map

package/dist/esm/testing/setupSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupSandbox.d.ts","sourceRoot":"","sources":["../../../src/testing/setupSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C,uCAAuC;AACvC,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/E,CAAA;AAED,wCAAwC;AACxC,MAAM,MAAM,cAAc,GAAG;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACvC,CAAA;AAiDD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,GAAE,aAAkB,GACzB,OAAO,CAAC,cAAc,CAAC,CAmDzB"}

package/dist/esm/testing/setupSandbox.js

@@ -0,0 +1,106 @@
+/**
+ * Vitest fixture for Canton sandbox lifecycle via cantonctl.
+ *
+ * Requires cantonctl to be installed and available on PATH.
+ * If cantonctl is not available, the fixture throws with a helpful message.
+ *
+ * @example
+ * ```typescript
+ * import { setupCantonSandbox } from 'cantonjs/testing'
+ *
+ * const sandbox = await setupCantonSandbox()
+ * // sandbox.client is a fully configured TestClient
+ * // sandbox.transport is the underlying transport
+ * // sandbox.url is the JSON API base URL
+ *
+ * // ... run tests ...
+ *
+ * await sandbox.teardown()
+ * ```
+ */
+import { jsonApi } from '../transport/json-api.js';
+import { createTestClient } from '../clients/createTestClient.js';
+/** Default exec using child_process (Node.js only). */
+async function defaultExec(cmd) {
+    // Dynamic import to avoid bundling Node.js modules in browser builds
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cp = await Function('return import("node:child_process")')();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const util = await Function('return import("node:util")')();
+    const execAsync = util.promisify(cp.exec);
+    return execAsync(cmd);
+}
+/** Check if cantonctl is available on PATH. */
+async function checkCantonctl(execFn) {
+    try {
+        await execFn('cantonctl --version');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Wait for the sandbox health endpoint to respond. */
+async function waitForHealth(url, timeoutMs, fetchFn) {
+    const deadline = Date.now() + timeoutMs;
+    const interval = 500;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetchFn(`${url}/livez`);
+            if (response.ok)
+                return;
+        }
+        catch {
+            // Not ready yet
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(`Canton sandbox did not become ready within ${timeoutMs}ms at ${url}`);
+}
+/**
+ * Set up a Canton sandbox for integration testing.
+ *
+ * Requires `cantonctl` to be installed. Starts a sandbox,
+ * waits for it to be ready, and returns a configured TestClient.
+ *
+ * Call `teardown()` when done to stop the sandbox.
+ */
+export async function setupCantonSandbox(config = {}) {
+    const { port = 7575, timeout = 30000, fetchFn = globalThis.fetch, execFn = defaultExec, } = config;
+    const url = `http://localhost:${port}`;
+    // Check cantonctl is available
+    const available = await checkCantonctl(execFn);
+    if (!available) {
+        throw new Error('cantonctl is not installed or not on PATH.\n' +
+            'Install it from: https://github.com/merged-one/cantonctl\n' +
+            'Or provide a custom execFn for testing.');
+    }
+    // Start sandbox
+    await execFn(`cantonctl dev start --port ${port}`);
+    // Wait for health
+    await waitForHealth(url, timeout, fetchFn);
+    // Get or generate token
+    let token = config.token;
+    if (!token) {
+        const result = await execFn('cantonctl auth token');
+        token = result.stdout.trim();
+    }
+    // Create transport and client
+    const transport = jsonApi({ url, token, fetchFn });
+    const party = config.party ?? 'test-party';
+    const client = createTestClient({ transport, party });
+    return {
+        url,
+        transport,
+        client,
+        async teardown() {
+            try {
+                await execFn(`cantonctl dev stop --port ${port}`);
+            }
+            catch {
+                // Best effort cleanup
+            }
+        },
+    };
+}
+//# sourceMappingURL=setupSandbox.js.map

package/dist/esm/testing/setupSandbox.js.map

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

package/dist/esm/transport/fallback.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Fallback transport — tries transports in order until one succeeds.
+ *
+ * Useful for high-availability setups where a primary node may be unavailable.
+ * On each request, tries the first transport. If it fails with a connection
+ * error, tries the next, and so on.
+ */
+import type { Transport } from './types.js';
+export type FallbackTransportConfig = {
+    /** Transports to try, in order of preference. */
+    readonly transports: readonly Transport[];
+};
+/**
+ * Create a fallback transport that tries multiple transports in sequence.
+ *
+ * Only retries on connection-level failures (ConnectionError, TimeoutError).
+ * Application-level errors (HttpError, 4xx/5xx) are thrown immediately since
+ * a different transport would get the same result.
+ */
+export declare function fallback(config: FallbackTransportConfig): Transport;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/esm/transport/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../../src/transport/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAA;AAE7D,MAAM,MAAM,uBAAuB,GAAG;IACpC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;CAC1C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,GAAG,SAAS,CA6BnE"}

package/dist/esm/transport/fallback.js

@@ -0,0 +1,45 @@
+/**
+ * Fallback transport — tries transports in order until one succeeds.
+ *
+ * Useful for high-availability setups where a primary node may be unavailable.
+ * On each request, tries the first transport. If it fails with a connection
+ * error, tries the next, and so on.
+ */
+import { ConnectionError, TimeoutError } from '../errors/transport.js';
+/**
+ * Create a fallback transport that tries multiple transports in sequence.
+ *
+ * Only retries on connection-level failures (ConnectionError, TimeoutError).
+ * Application-level errors (HttpError, 4xx/5xx) are thrown immediately since
+ * a different transport would get the same result.
+ */
+export function fallback(config) {
+    const { transports } = config;
+    if (transports.length === 0) {
+        throw new Error('fallback() requires at least one transport');
+    }
+    return {
+        type: 'fallback',
+        url: transports[0].url,
+        async request(args) {
+            let lastError;
+            for (const transport of transports) {
+                try {
+                    return await transport.request(args);
+                }
+                catch (error) {
+                    lastError = error;
+                    if (isRetryableError(error)) {
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+            throw lastError;
+        },
+    };
+}
+function isRetryableError(error) {
+    return error instanceof ConnectionError || error instanceof TimeoutError;
+}
+//# sourceMappingURL=fallback.js.map

package/dist/esm/transport/fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../../../src/transport/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAQtE;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA+B;IACtD,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAA;IAE7B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;IAC/D,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,GAAG,EAAE,UAAU,CAAC,CAAC,CAAE,CAAC,GAAG;QAEvB,KAAK,CAAC,OAAO,CAAsB,IAAsB;YACvD,IAAI,SAAkB,CAAA;YAEtB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,OAAO,MAAM,SAAS,CAAC,OAAO,CAAY,IAAI,CAAC,CAAA;gBACjD,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,SAAS,GAAG,KAAK,CAAA;oBACjB,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;wBAC5B,SAAQ;oBACV,CAAC;oBACD,MAAM,KAAK,CAAA;gBACb,CAAC;YACH,CAAC;YAED,MAAM,SAAS,CAAA;QACjB,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,KAAK,YAAY,eAAe,IAAI,KAAK,YAAY,YAAY,CAAA;AAC1E,CAAC"}

package/dist/esm/transport/grpc.d.ts

@@ -0,0 +1,51 @@
+/**
+ * gRPC transport factory for Canton Ledger API V2.
+ *
+ * Uses a custom fetch-based adapter to translate Transport requests into
+ * gRPC-Web calls via ConnectRPC's HTTP/2 or HTTP/1.1 protocol. This keeps
+ * cantonjs zero-dependency — users bring their own `@connectrpc/connect-web`
+ * or `@connectrpc/connect-node` transport.
+ *
+ * Since Canton's JSON API V2 and gRPC API share the same semantics, this
+ * transport maps JSON API paths to gRPC service methods and re-encodes
+ * request/response bodies.
+ *
+ * Usage:
+ *   import { grpc } from 'cantonjs'
+ *   import { createGrpcWebTransport } from '@connectrpc/connect-web'
+ *
+ *   const transport = grpc({
+ *     url: 'http://localhost:7575',
+ *     grpcTransport: createGrpcWebTransport({ baseUrl: 'http://localhost:7575' }),
+ *   })
+ */
+import type { Transport } from './types.js';
+/** Configuration for the gRPC transport. */
+export type GrpcTransportConfig = {
+    /** Base URL of the Canton node. */
+    readonly url: string;
+    /** JWT Bearer token for authentication. */
+    readonly token?: string;
+    /**
+     * A ConnectRPC transport instance (from @connectrpc/connect-web or connect-node).
+     * Injected to keep cantonjs zero-dependency.
+     */
+    readonly grpcTransport: GrpcTransportLike;
+};
+/**
+ * Minimal interface for a ConnectRPC transport.
+ * Compatible with @connectrpc/connect's Transport type.
+ */
+export type GrpcTransportLike = {
+    readonly unary: (service: unknown, method: unknown, signal: AbortSignal | undefined, timeoutMs: number | undefined, header: unknown, message: unknown) => Promise<{
+        readonly message: unknown;
+    }>;
+};
+/**
+ * Create a gRPC transport for the Canton Ledger API.
+ *
+ * Requires @connectrpc/connect as a peer dependency (not bundled).
+ * Maps Transport requests to gRPC unary calls.
+ */
+export declare function grpc(config: GrpcTransportConfig): Transport;
+//# sourceMappingURL=grpc.d.ts.map

package/dist/esm/transport/grpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grpc.d.ts","sourceRoot":"","sources":["../../../src/transport/grpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAA;AAE7D,4CAA4C;AAC5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAA;CAC1C,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,KAAK,EAAE,CACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,KACb,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAC5C,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,CA0B3D"}