cantonjs 0.0.1

package/src/errors/ledger.ts

@@ -0,0 +1,53 @@
+import { CantonjsError, type ErrorCode } from './base.js'
+
+/** Command was rejected by the ledger. */
+export class CommandRejectedError extends CantonjsError {
+  readonly grpcStatusCode: number
+  readonly rejectionReason: string
+
+  constructor(rejectionReason: string, options?: { cause?: Error; grpcStatusCode?: number }) {
+    super(`Command rejected: ${rejectionReason}`, {
+      code: 'CJ3001' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: [
+        'The ledger rejected this command. Check the rejection reason for details.',
+        'Common causes: authorization failure, contract not active, duplicate command.',
+      ],
+    })
+    this.name = 'CommandRejectedError'
+    this.grpcStatusCode = options?.grpcStatusCode ?? 0
+    this.rejectionReason = rejectionReason
+  }
+}
+
+/** Contract was not found on the ledger. */
+export class ContractNotFoundError extends CantonjsError {
+  readonly contractId: string
+
+  constructor(contractId: string) {
+    super(`Contract not found: ${contractId}`, {
+      code: 'CJ3002' as ErrorCode,
+      metaMessages: [
+        'The contract may have been archived or may not be visible to the current party.',
+        `Contract ID: ${contractId}`,
+      ],
+    })
+    this.name = 'ContractNotFoundError'
+    this.contractId = contractId
+  }
+}
+
+/** Party is not authorized for the requested operation. */
+export class AuthorizationError extends CantonjsError {
+  constructor(message: string, options?: { cause?: Error }) {
+    super(message, {
+      code: 'CJ3003' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: [
+        'Ensure the party has the required rights (actAs or readAs) for this operation.',
+        'Check that the JWT token includes the correct party claims.',
+      ],
+    })
+    this.name = 'AuthorizationError'
+  }
+}

package/src/errors/streaming.ts

@@ -0,0 +1,51 @@
+import { CantonjsError, type ErrorCode } from './base.js'
+
+/** WebSocket connection to a Canton streaming endpoint failed. */
+export class WebSocketError extends CantonjsError {
+  constructor(url: string, options?: { cause?: Error }) {
+    super(`WebSocket connection failed: ${url}`, {
+      code: 'CJ5001' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: [
+        'Ensure the Canton node is running and WebSocket endpoint is accessible.',
+        `Attempted URL: ${url}`,
+      ],
+      docsPath: 'https://github.com/merged-one/cantonjs#streaming',
+    })
+    this.name = 'WebSocketError'
+  }
+}
+
+/** Stream was closed unexpectedly by the server. */
+export class StreamClosedError extends CantonjsError {
+  readonly code_: number
+  readonly reason: string
+
+  constructor(code: number, reason: string) {
+    super(`Stream closed unexpectedly: ${code} ${reason}`, {
+      code: 'CJ5002' as ErrorCode,
+      metaMessages: [
+        `WebSocket close code: ${code}`,
+        reason ? `Reason: ${reason}` : 'No reason provided by server.',
+      ],
+    })
+    this.name = 'StreamClosedError'
+    this.code_ = code
+    this.reason = reason
+  }
+}
+
+/** Reconnection attempts exhausted. */
+export class ReconnectFailedError extends CantonjsError {
+  constructor(attempts: number, options?: { cause?: Error }) {
+    super(`Failed to reconnect after ${attempts} attempts`, {
+      code: 'CJ5003' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: [
+        'The stream was unable to reconnect to the Canton node.',
+        'Check network connectivity and node availability.',
+      ],
+    })
+    this.name = 'ReconnectFailedError'
+  }
+}

package/src/errors/transport.ts

@@ -0,0 +1,65 @@
+import { CantonjsError, type ErrorCode } from './base.js'
+
+/** Error connecting to a Canton node. */
+export class ConnectionError extends CantonjsError {
+  constructor(url: string, options?: { cause?: Error }) {
+    super(`Failed to connect to Canton node at ${url}`, {
+      code: 'CJ1001' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: [
+        'Ensure the Canton node is running and accessible.',
+        `Attempted URL: ${url}`,
+      ],
+      docsPath: 'https://github.com/merged-one/cantonjs#connection',
+    })
+    this.name = 'ConnectionError'
+  }
+}
+
+/** HTTP error from the JSON Ledger API. */
+export class HttpError extends CantonjsError {
+  readonly status: number
+  readonly headers?: Record<string, string>
+
+  constructor(
+    status: number,
+    statusText: string,
+    options?: { cause?: Error; headers?: Record<string, string>; body?: string },
+  ) {
+    super(`HTTP ${status}: ${statusText}`, {
+      code: 'CJ1002' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: options?.body ? [`Response body: ${options.body}`] : undefined,
+    })
+    this.name = 'HttpError'
+    this.status = status
+    this.headers = options?.headers
+  }
+}
+
+/** gRPC error from the Ledger API. */
+export class GrpcError extends CantonjsError {
+  readonly grpcCode: number
+
+  constructor(grpcCode: number, message: string, options?: { cause?: Error }) {
+    super(message, {
+      code: 'CJ1003' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: [`gRPC status code: ${grpcCode}`],
+    })
+    this.name = 'GrpcError'
+    this.grpcCode = grpcCode
+  }
+}
+
+/** Request timed out. */
+export class TimeoutError extends CantonjsError {
+  constructor(timeoutMs: number, options?: { cause?: Error }) {
+    super(`Request timed out after ${timeoutMs}ms`, {
+      code: 'CJ1004' as ErrorCode,
+      cause: options?.cause,
+      metaMessages: ['Consider increasing the timeout or checking network conditions.'],
+    })
+    this.name = 'TimeoutError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+// Clients
+export {
+  createLedgerClient,
+  type LedgerClient,
+  type LedgerClientConfig,
+  type CommandOptions,
+  type QueryOptions,
+  type ConnectedSynchronizer,
+  type PrunedOffsets,
+} from './clients/createLedgerClient.js'
+
+export {
+  createAdminClient,
+  type AdminClient,
+  type AdminClientConfig,
+  type PaginationOptions,
+  type PaginatedResult,
+} from './clients/createAdminClient.js'
+
+export {
+  createTestClient,
+  type TestClient,
+  type TestClientConfig,
+} from './clients/createTestClient.js'
+
+// Transport
+export { jsonApi } from './transport/json-api.js'
+export { grpc, type GrpcTransportConfig, type GrpcTransportLike } from './transport/grpc.js'
+export { fallback, type FallbackTransportConfig } from './transport/fallback.js'
+export type { Transport, TransportConfig, TransportRequest } from './transport/types.js'
+
+// Errors
+export {
+  CantonjsError,
+  ConnectionError,
+  HttpError,
+  GrpcError,
+  TimeoutError,
+  CommandRejectedError,
+  ContractNotFoundError,
+  AuthorizationError,
+  TokenExpiredError,
+  InvalidTokenError,
+  WebSocketError,
+  StreamClosedError,
+  ReconnectFailedError,
+} from './errors/index.js'
+export type { ErrorCode, CantonjsErrorOptions } from './errors/base.js'
+
+// Chains
+export { localNet, devNet, testNet, mainNet, type CantonChain } from './chains/definitions.js'
+
+// Core types
+export type {
+  ContractId,
+  TemplateId,
+  CreatedEvent,
+  ArchivedEvent,
+  ExercisedEvent,
+  TaggedEvent,
+  ActiveContract,
+  ContractEntry,
+} from './types/contract.js'
+
+export type { Party, ObjectMeta, PartyDetails, AllocatePartyRequest } from './types/party.js'
+
+export type {
+  LedgerOffset,
+  TaggedCommand,
+  JsCommands,
+  TransactionShape,
+  EventFormat,
+  TransactionFormat,
+} from './types/command.js'
+
+export type {
+  JsTransaction,
+  TaggedUpdate,
+  UpdateFormat,
+} from './types/transaction.js'
+
+export type { User, Right, RightKind, CreateUserRequest } from './types/user.js'
+export type { PackageStatus, PackageDetails } from './types/package.js'
+export type {
+  IdentityProviderConfig,
+  CreateIdentityProviderRequest,
+  UpdateIdentityProviderRequest,
+} from './types/idp.js'
+
+export type {
+  Reassignment,
+  ReassignmentEvent,
+  AssignedEvent,
+  UnassignedEvent,
+  ReassignmentCommand,
+  UnassignCommand,
+  AssignCommand,
+} from './types/reassignment.js'
+
+export type {
+  PrepareSubmissionResponse,
+  ExecuteSubmissionRequest,
+  PartySignatures,
+  Signature,
+  SignatureFormat,
+} from './types/interactive.js'
+
+// Streaming
+export { streamUpdates } from './streaming/streamUpdates.js'
+export { streamContracts, type ActiveContractsResponse } from './streaming/streamContracts.js'
+export { streamCompletions } from './streaming/streamCompletions.js'
+export { toWebSocketUrl } from './streaming/createStream.js'
+export type {
+  WebSocketConstructor,
+  WebSocketLike,
+  ReconnectConfig,
+  StreamOptions,
+  StreamUpdatesOptions,
+  StreamContractsOptions,
+  StreamCompletionsOptions,
+  CompletionEvent,
+} from './streaming/types.js'

package/src/ledger/index.ts

@@ -0,0 +1,33 @@
+export {
+  createLedgerClient,
+  type LedgerClient,
+  type LedgerClientConfig,
+  type CommandOptions,
+  type QueryOptions,
+} from '../clients/createLedgerClient.js'
+
+export type {
+  ContractId,
+  TemplateId,
+  CreatedEvent,
+  ArchivedEvent,
+  ExercisedEvent,
+  TaggedEvent,
+  ActiveContract,
+  ContractEntry,
+} from '../types/contract.js'
+
+export type {
+  JsTransaction,
+  TaggedUpdate,
+  UpdateFormat,
+} from '../types/transaction.js'
+
+export type {
+  LedgerOffset,
+  TaggedCommand,
+  JsCommands,
+  TransactionShape,
+  EventFormat,
+  TransactionFormat,
+} from '../types/command.js'

package/src/streaming/createStream.ts

@@ -0,0 +1,321 @@
+/**
+ * Core AsyncIterable stream factory for Canton WebSocket connections.
+ *
+ * Creates a stream that:
+ * - Opens a WebSocket connection with Canton subprotocol auth
+ * - Sends a subscription request on connection open
+ * - Yields parsed JSON messages as an AsyncIterable
+ * - Auto-reconnects with exponential backoff on disconnect
+ * - Tracks offsets for gap-free resumption
+ * - Supports AbortSignal cancellation
+ *
+ * @see ADR 0005 — Streaming Architecture
+ */
+
+import type {
+  WebSocketConstructor,
+  WebSocketLike,
+  ReconnectConfig,
+} from './types.js'
+import { WebSocketError, StreamClosedError, ReconnectFailedError } from '../errors/streaming.js'
+
+/** Internal configuration for createStream. */
+export type CreateStreamConfig = {
+  /** Full WebSocket URL (ws:// or wss://). */
+  readonly url: string
+  /** JWT token for authentication. */
+  readonly token?: string
+  /** WebSocket constructor. */
+  readonly WebSocket?: WebSocketConstructor
+  /** AbortSignal for cancellation. */
+  readonly signal?: AbortSignal
+  /** Reconnect config, or false to disable. */
+  readonly reconnect?: ReconnectConfig | false
+  /** Build the subscription request body. Called on each (re)connection. */
+  readonly buildRequest: (lastOffset: number | undefined) => unknown
+  /** Extract an offset from a received message, if present. */
+  readonly extractOffset: (message: unknown) => number | undefined
+  /** Whether this is a bounded stream that ends on server close. */
+  readonly bounded?: boolean
+}
+
+const DEFAULT_RECONNECT: Required<ReconnectConfig> = {
+  initialDelay: 1000,
+  maxDelay: 30000,
+  factor: 2,
+  jitter: 0.25,
+  maxAttempts: Infinity,
+}
+
+/**
+ * Convert an HTTP(S) URL to a WebSocket URL.
+ * http://host → ws://host, https://host → wss://host
+ * If already ws/wss, return as-is.
+ */
+export function toWebSocketUrl(baseUrl: string, path: string): string {
+  const url = new URL(path, baseUrl)
+  if (url.protocol === 'https:') {
+    url.protocol = 'wss:'
+  } else if (url.protocol === 'http:') {
+    url.protocol = 'ws:'
+  }
+  return url.toString()
+}
+
+/**
+ * Calculate reconnect delay with exponential backoff and jitter.
+ */
+export function calculateDelay(attempt: number, config: Required<ReconnectConfig>): number {
+  const baseDelay = Math.min(
+    config.initialDelay * Math.pow(config.factor, attempt),
+    config.maxDelay,
+  )
+  const jitterRange = baseDelay * config.jitter
+  const jitter = (Math.random() * 2 - 1) * jitterRange
+  return Math.max(0, baseDelay + jitter)
+}
+
+/**
+ * Create a Canton WebSocket stream as an AsyncIterable.
+ *
+ * Each iteration yields a parsed JSON message from the WebSocket.
+ * The stream auto-reconnects on disconnect unless:
+ * - The AbortSignal is aborted
+ * - reconnect is set to false
+ * - The stream is bounded and the server closed normally (code 1000)
+ * - Max reconnect attempts are exhausted
+ */
+export function createStream<T>(config: CreateStreamConfig): AsyncIterable<T> {
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<T> {
+      return new StreamIterator<T>(config)
+    },
+  }
+}
+
+/**
+ * Internal AsyncIterator implementation.
+ *
+ * Uses a message queue with promise-based signaling to bridge the
+ * event-driven WebSocket API to the pull-based AsyncIterator protocol.
+ */
+class StreamIterator<T> implements AsyncIterator<T> {
+  private readonly config: CreateStreamConfig
+  private readonly reconnectConfig: Required<ReconnectConfig> | false
+  private ws: WebSocketLike | null = null
+  private lastOffset: number | undefined = undefined
+  private reconnectAttempts = 0
+  private done = false
+  private abortHandler: (() => void) | null = null
+
+  // Message queue for buffering received messages
+  private queue: T[] = []
+  // Error stored when fail() is called before next()
+  private storedError: Error | null = null
+  // Pending resolve/reject for when consumer is waiting
+  private pendingResolve: ((result: IteratorResult<T>) => void) | null = null
+  private pendingReject: ((error: Error) => void) | null = null
+
+  constructor(config: CreateStreamConfig) {
+    this.config = config
+
+    if (config.reconnect === false) {
+      this.reconnectConfig = false
+    } else {
+      this.reconnectConfig = { ...DEFAULT_RECONNECT, ...config.reconnect }
+    }
+
+    if (config.signal?.aborted) {
+      this.done = true
+    } else {
+      this.setupAbortHandler()
+      this.connect()
+    }
+  }
+
+  async next(): Promise<IteratorResult<T>> {
+    // If an error was stored before next() was called, throw it now
+    if (this.storedError) {
+      const error = this.storedError
+      this.storedError = null
+      throw error
+    }
+
+    if (this.done && this.queue.length === 0) {
+      return { done: true, value: undefined }
+    }
+
+    // If there are queued messages, return immediately
+    if (this.queue.length > 0) {
+      return { done: false, value: this.queue.shift()! }
+    }
+
+    // Wait for the next message, error, or close
+    return new Promise<IteratorResult<T>>((resolve, reject) => {
+      this.pendingResolve = resolve
+      this.pendingReject = reject
+    })
+  }
+
+  async return(): Promise<IteratorResult<T>> {
+    this.cleanup()
+    return { done: true, value: undefined }
+  }
+
+  async throw(error?: Error): Promise<IteratorResult<T>> {
+    this.cleanup()
+    throw error
+  }
+
+  private setupAbortHandler(): void {
+    if (!this.config.signal) return
+
+    this.abortHandler = () => {
+      this.cleanup()
+      if (this.pendingResolve) {
+        this.pendingResolve({ done: true, value: undefined })
+        this.pendingResolve = null
+        this.pendingReject = null
+      }
+    }
+    this.config.signal.addEventListener('abort', this.abortHandler)
+  }
+
+  private connect(): void {
+    if (this.done) return
+
+    const WS = this.config.WebSocket ?? (globalThis as Record<string, unknown>).WebSocket as WebSocketConstructor | undefined
+    if (!WS) {
+      const error = new WebSocketError(this.config.url, {
+        cause: new Error('No WebSocket implementation available. Provide a WebSocket constructor.'),
+      })
+      this.fail(error)
+      return
+    }
+
+    const protocols = this.config.token
+      ? ['daml.ws.auth', `jwt.token.${this.config.token}`]
+      : undefined
+
+    let ws: WebSocketLike
+    try {
+      ws = new WS(this.config.url, protocols) as WebSocketLike
+    } catch (err) {
+      const error = new WebSocketError(this.config.url, {
+        cause: err instanceof Error ? err : new Error(String(err)),
+      })
+      this.fail(error)
+      return
+    }
+    this.ws = ws
+
+    ws.onopen = () => {
+      this.reconnectAttempts = 0
+      const request = this.config.buildRequest(this.lastOffset)
+      ws.send(JSON.stringify(request))
+    }
+
+    ws.onmessage = (event: { data: unknown }) => {
+      let message: T
+      try {
+        message = JSON.parse(String(event.data)) as T
+      } catch {
+        return // Skip non-JSON messages
+      }
+
+      // Track offset for resumption
+      const offset = this.config.extractOffset(message)
+      if (offset !== undefined) {
+        this.lastOffset = offset
+      }
+
+      this.enqueue(message)
+    }
+
+    ws.onerror = () => {
+      // onerror is always followed by onclose, so we handle reconnection there
+    }
+
+    ws.onclose = (event: { code: number; reason: string }) => {
+      this.ws = null
+
+      // Normal close on bounded stream = stream complete
+      if (this.config.bounded && event.code === 1000) {
+        this.cleanup()
+        if (this.pendingResolve) {
+          this.pendingResolve({ done: true, value: undefined })
+          this.pendingResolve = null
+          this.pendingReject = null
+        }
+        return
+      }
+
+      // If already done (abort, return), don't reconnect
+      if (this.done) return
+
+      // Try to reconnect
+      if (this.reconnectConfig === false) {
+        const error = new StreamClosedError(event.code, event.reason)
+        this.fail(error)
+        return
+      }
+
+      if (this.reconnectAttempts >= this.reconnectConfig.maxAttempts) {
+        const error = new ReconnectFailedError(this.reconnectAttempts)
+        this.fail(error)
+        return
+      }
+
+      const delay = calculateDelay(this.reconnectAttempts, this.reconnectConfig)
+      this.reconnectAttempts++
+
+      setTimeout(() => {
+        if (!this.done) {
+          this.connect()
+        }
+      }, delay)
+    }
+  }
+
+  private enqueue(message: T): void {
+    if (this.pendingResolve) {
+      const resolve = this.pendingResolve
+      this.pendingResolve = null
+      this.pendingReject = null
+      resolve({ done: false, value: message })
+    } else {
+      this.queue.push(message)
+    }
+  }
+
+  private fail(error: Error): void {
+    this.done = true
+    if (this.pendingReject) {
+      const reject = this.pendingReject
+      this.pendingResolve = null
+      this.pendingReject = null
+      reject(error)
+    } else {
+      this.storedError = error
+    }
+  }
+
+  private cleanup(): void {
+    this.done = true
+
+    if (this.config.signal && this.abortHandler) {
+      this.config.signal.removeEventListener('abort', this.abortHandler)
+      this.abortHandler = null
+    }
+
+    if (this.ws) {
+      // Clear handlers before closing to prevent reconnect
+      this.ws.onopen = null
+      this.ws.onmessage = null
+      this.ws.onerror = null
+      this.ws.onclose = null
+      this.ws.close()
+      this.ws = null
+    }
+  }
+}

package/src/streaming/index.ts

@@ -0,0 +1,19 @@
+export { createStream, toWebSocketUrl, calculateDelay } from './createStream.js'
+export type { CreateStreamConfig } from './createStream.js'
+
+export { streamUpdates } from './streamUpdates.js'
+export { streamContracts, type ActiveContractsResponse } from './streamContracts.js'
+export { streamCompletions } from './streamCompletions.js'
+
+export type {
+  WebSocketConstructor,
+  WebSocketLike,
+  ReconnectConfig,
+  StreamOptions,
+  StreamUpdatesOptions,
+  StreamContractsOptions,
+  StreamCompletionsOptions,
+  CompletionEvent,
+} from './types.js'
+
+export { WS_READY_STATE } from './types.js'