cantonjs 0.0.1

package/src/streaming/streamCompletions.ts

@@ -0,0 +1,49 @@
+/**
+ * Stream command completions from Canton's /v2/commands/completions WebSocket endpoint.
+ *
+ * Yields completion events as an AsyncIterable with auto-reconnect.
+ */
+
+import type { CompletionEvent, StreamCompletionsOptions } from './types.js'
+import { createStream, toWebSocketUrl } from './createStream.js'
+
+/**
+ * Stream command completions from a Canton node.
+ *
+ * @example
+ * ```typescript
+ * const completions = streamCompletions({
+ *   url: 'http://localhost:7575',
+ *   token: jwt,
+ *   parties: ['Alice::1220'],
+ *   beginExclusive: 0,
+ * })
+ *
+ * for await (const event of completions) {
+ *   console.log('Completion:', event.completion.commandId, event.completion.status)
+ * }
+ * ```
+ */
+export function streamCompletions(
+  options: StreamCompletionsOptions,
+): AsyncIterable<CompletionEvent> {
+  const wsUrl = toWebSocketUrl(options.url, '/v2/commands/completions')
+
+  return createStream<CompletionEvent>({
+    url: wsUrl,
+    token: options.token,
+    WebSocket: options.WebSocket,
+    signal: options.signal,
+    reconnect: options.reconnect,
+    bounded: false,
+    buildRequest: (lastOffset) => ({
+      beginExclusive: lastOffset ?? options.beginExclusive ?? 0,
+      parties: options.parties,
+      ...(options.applicationId && { applicationId: options.applicationId }),
+    }),
+    extractOffset: (message) => {
+      const msg = message as CompletionEvent
+      return msg.completion?.offset
+    },
+  })
+}

package/src/streaming/streamContracts.ts

@@ -0,0 +1,64 @@
+/**
+ * Stream active contracts from Canton's /v2/state/active-contracts WebSocket endpoint.
+ *
+ * This is a bounded stream: the server sends all matching active contracts
+ * and then closes the connection. No auto-reconnect is used.
+ */
+
+import type { StreamContractsOptions } from './types.js'
+import { createStream, toWebSocketUrl } from './createStream.js'
+
+/** Response message from the active contracts stream. */
+export type ActiveContractsResponse = {
+  readonly contractEntry?: { readonly [key: string]: unknown }
+  readonly offset?: number
+}
+
+/**
+ * Stream active contracts from a Canton node.
+ *
+ * The stream yields contract entries matching the provided filters.
+ * It is bounded: the server closes the connection when all contracts
+ * have been sent.
+ *
+ * @example
+ * ```typescript
+ * const contracts = streamContracts({
+ *   url: 'http://localhost:7575',
+ *   token: jwt,
+ *   eventFormat: {
+ *     filtersByParty: {
+ *       [party]: { cumulative: [{ identifierFilter: { WildcardFilter: { value: {} } } }] }
+ *     }
+ *   }
+ * })
+ *
+ * for await (const entry of contracts) {
+ *   if (entry.contractEntry && 'JsActiveContract' in entry.contractEntry) {
+ *     console.log('Contract:', entry.contractEntry.JsActiveContract)
+ *   }
+ * }
+ * ```
+ */
+export function streamContracts(
+  options: StreamContractsOptions,
+): AsyncIterable<ActiveContractsResponse> {
+  const wsUrl = toWebSocketUrl(options.url, '/v2/state/active-contracts')
+
+  return createStream<ActiveContractsResponse>({
+    url: wsUrl,
+    token: options.token,
+    WebSocket: options.WebSocket,
+    signal: options.signal,
+    reconnect: false, // Bounded stream — no reconnect
+    bounded: true,
+    buildRequest: () => ({
+      eventFormat: options.eventFormat,
+      ...(options.activeAtOffset !== undefined && { activeAtOffset: options.activeAtOffset }),
+    }),
+    extractOffset: (message) => {
+      const msg = message as ActiveContractsResponse
+      return msg.offset
+    },
+  })
+}

package/src/streaming/streamUpdates.ts

@@ -0,0 +1,67 @@
+/**
+ * Stream updates from Canton's /v2/updates WebSocket endpoint.
+ *
+ * Yields TaggedUpdate messages (Transaction, Reassignment, OffsetCheckpoint,
+ * TopologyTransaction) as an AsyncIterable with auto-reconnect.
+ */
+
+import type { TaggedUpdate } from '../types/transaction.js'
+import type { StreamUpdatesOptions } from './types.js'
+import { createStream, toWebSocketUrl } from './createStream.js'
+
+/**
+ * Stream ledger updates from a Canton node.
+ *
+ * @example
+ * ```typescript
+ * const updates = streamUpdates({
+ *   url: 'http://localhost:7575',
+ *   token: jwt,
+ *   beginExclusive: 0,
+ *   updateFormat: {
+ *     includeTransactions: {
+ *       transactionShape: 'TRANSACTION_SHAPE_ACS_DELTA',
+ *       eventFormat: {
+ *         filtersByParty: {
+ *           [party]: { cumulative: [{ identifierFilter: { WildcardFilter: { value: {} } } }] }
+ *         }
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * for await (const update of updates) {
+ *   if ('Transaction' in update) {
+ *     console.log('Transaction:', update.Transaction.value.updateId)
+ *   }
+ * }
+ * ```
+ */
+export function streamUpdates(options: StreamUpdatesOptions): AsyncIterable<TaggedUpdate> {
+  const wsUrl = toWebSocketUrl(options.url, '/v2/updates')
+  const isOpen = options.endInclusive === undefined
+
+  return createStream<TaggedUpdate>({
+    url: wsUrl,
+    token: options.token,
+    WebSocket: options.WebSocket,
+    signal: options.signal,
+    reconnect: isOpen ? options.reconnect : false,
+    bounded: !isOpen,
+    buildRequest: (lastOffset) => ({
+      beginExclusive: lastOffset ?? options.beginExclusive ?? 0,
+      ...(options.endInclusive !== undefined && { endInclusive: options.endInclusive }),
+      ...(options.updateFormat && { updateFormat: options.updateFormat }),
+    }),
+    extractOffset: (message) => {
+      const msg = message as TaggedUpdate
+      if ('Transaction' in msg) {
+        return msg.Transaction.value.offset
+      }
+      if ('OffsetCheckpoint' in msg) {
+        return msg.OffsetCheckpoint.value.offset
+      }
+      return undefined
+    },
+  })
+}

package/src/streaming/types.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 const WS_READY_STATE = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const
+
+/** 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
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,18 @@
+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'

package/src/testing/mockTransport.ts

@@ -0,0 +1,132 @@
+/**
+ * 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, TransportRequest } 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 function createMockTransport(options: {
+  matchers?: readonly RequestMatcher[]
+  defaultResponse?: unknown
+  url?: string
+} = {}): Transport & { readonly calls: readonly RecordedExchange[] } {
+  const { matchers = [], defaultResponse, url = 'http://mock:7575' } = options
+  const calls: RecordedExchange[] = []
+
+  return {
+    type: 'mock',
+    url,
+    calls,
+
+    async request<TResponse>(args: TransportRequest): Promise<TResponse> {
+      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 as TResponse
+    },
+  }
+}
+
+/**
+ * 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: Transport,
+): Transport & { readonly recordings: readonly RecordedExchange[] } {
+  const recordings: RecordedExchange[] = []
+
+  return {
+    type: `recording(${inner.type})`,
+    url: inner.url,
+    recordings,
+
+    async request<TResponse>(args: TransportRequest): Promise<TResponse> {
+      const response = await inner.request<TResponse>(args)
+
+      recordings.push({
+        request: { method: args.method, path: args.path, body: args.body },
+        response,
+      })
+
+      return response
+    },
+  }
+}

package/src/testing/setupSandbox.ts

@@ -0,0 +1,163 @@
+/**
+ * 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, 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>
+}
+
+/** Default exec using child_process (Node.js only). */
+async function defaultExec(cmd: string): Promise<{ stdout: string; stderr: string }> {
+  // 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")')() as Promise<any>)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const util = await (Function('return import("node:util")')() as Promise<any>)
+  const execAsync = util.promisify(cp.exec)
+  return execAsync(cmd) as Promise<{ stdout: string; stderr: string }>
+}
+
+/** Check if cantonctl is available on PATH. */
+async function checkCantonctl(
+  execFn: (cmd: string) => Promise<{ stdout: string; stderr: string }>,
+): Promise<boolean> {
+  try {
+    await execFn('cantonctl --version')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Wait for the sandbox health endpoint to respond. */
+async function waitForHealth(
+  url: string,
+  timeoutMs: number,
+  fetchFn: typeof fetch,
+): Promise<void> {
+  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: SandboxConfig = {},
+): Promise<SandboxContext> {
+  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' as Party)
+  const client = createTestClient({ transport, party })
+
+  return {
+    url,
+    transport,
+    client,
+    async teardown() {
+      try {
+        await execFn(`cantonctl dev stop --port ${port}`)
+      } catch {
+        // Best effort cleanup
+      }
+    },
+  }
+}

package/src/transport/fallback.ts

@@ -0,0 +1,57 @@
+/**
+ * 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'
+import type { Transport, TransportRequest } 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 function fallback(config: FallbackTransportConfig): Transport {
+  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<TResponse = unknown>(args: TransportRequest): Promise<TResponse> {
+      let lastError: unknown
+
+      for (const transport of transports) {
+        try {
+          return await transport.request<TResponse>(args)
+        } catch (error) {
+          lastError = error
+          if (isRetryableError(error)) {
+            continue
+          }
+          throw error
+        }
+      }
+
+      throw lastError
+    },
+  }
+}
+
+function isRetryableError(error: unknown): boolean {
+  return error instanceof ConnectionError || error instanceof TimeoutError
+}