@c7-digital/ledger 0.0.9 → 0.0.11

package/lib-lite/src/client.d.ts

@@ -10,6 +10,19 @@
  */
 import { operations } from "./generated/api.js";
 import { ValidationMode } from "./validation.js";
+import { type JsCantonError } from "./types.js";
+/**
+ * Error thrown when the Canton ledger API returns a non-OK HTTP response.
+ * Captures the HTTP status, status text, and — when the response body
+ * is a JsCantonError — the structured error details from Canton.
+ */
+export declare class LedgerApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly cantonError?: JsCantonError;
+    readonly responseBody?: unknown;
+    constructor(status: number, statusText: string, body?: unknown);
+}
 type SubmitAndWaitOperation = operations["postV2CommandsSubmit-and-wait"];
 type SubmitAndWaitRequest = SubmitAndWaitOperation["requestBody"]["content"]["application/json"];
 type SubmitAndWaitResponse = SubmitAndWaitOperation["responses"]["200"]["content"]["application/json"];
@@ -43,13 +56,21 @@ export declare class TypedHttpClient {
     private validator?;
     constructor(config: TypedHttpClientConfig);
     private request;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     submitAndWait(commands: SubmitAndWaitRequest): Promise<SubmitAndWaitResponse>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     submitAndWaitForTransaction(commands: SubmitAndWaitForTransactionRequest): Promise<SubmitAndWaitForTransactionResponse>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getParties(): Promise<GetPartiesResponse>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getUserInfo(userId: string): Promise<GetUserResponse>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getUserRights(userId: string): Promise<GetUserRightsResponse>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     queryActiveContracts(queryRequest: QueryActiveContractsRequest): Promise<QueryActiveContractsResponse>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     allocateParty(request: AllocatePartyRequest): Promise<AllocatePartyResponse>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getLedgerEnd(): Promise<GetLedgerEndResponse>;
 }
 export {};

package/lib-lite/src/client.js

@@ -1,5 +1,28 @@
 import { SchemaValidator } from "./validation.js";
+import { isCantonError } from "./types.js";
 import fetch from "cross-fetch";
+/**
+ * Error thrown when the Canton ledger API returns a non-OK HTTP response.
+ * Captures the HTTP status, status text, and — when the response body
+ * is a JsCantonError — the structured error details from Canton.
+ */
+export class LedgerApiError extends Error {
+    constructor(status, statusText, body) {
+        const cantonErr = isCantonError(body) ? body : undefined;
+        const detail = cantonErr
+            ? `${cantonErr.code}: ${cantonErr.cause}`
+            : (typeof body === "string" ? body : undefined);
+        const message = detail
+            ? `HTTP ${status}: ${statusText} — ${detail}`
+            : `HTTP ${status}: ${statusText}`;
+        super(message);
+        this.name = "LedgerApiError";
+        this.status = status;
+        this.statusText = statusText;
+        this.cantonError = cantonErr;
+        this.responseBody = body;
+    }
+}
 export class TypedHttpClient {
     constructor(config) {
         this.token = config.token;
@@ -22,7 +45,19 @@ export class TypedHttpClient {
         }
         const response = await fetch(url, requestInit);
         if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                try {
+                    body = await response.text();
+                }
+                catch {
+                    // Response body unreadable — leave undefined
+                }
+            }
+            throw new LedgerApiError(response.status, response.statusText, body);
         }
         const parsed = await response.json();
         if (this.validator && responseSchemaName) {
@@ -35,27 +70,35 @@ export class TypedHttpClient {
         }
         return parsed;
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async submitAndWait(commands) {
         return this.request("/v2/commands/submit-and-wait", "POST", commands, "#/components/schemas/SubmitAndWaitResponse");
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async submitAndWaitForTransaction(commands) {
         return this.request("/v2/commands/submit-and-wait-for-transaction", "POST", commands, "#/components/schemas/JsSubmitAndWaitForTransactionResponse");
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getParties() {
         return this.request("/v2/parties", "GET", undefined, "#/components/schemas/GetPartiesResponse");
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getUserInfo(userId) {
         return this.request(`/v2/users/${userId}`, "GET", undefined, "#/components/schemas/GetUserResponse");
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getUserRights(userId) {
         return this.request(`/v2/users/${userId}/rights`, "GET", undefined, "#/components/schemas/ListUserRightsResponse");
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async queryActiveContracts(queryRequest) {
         return this.request("/v2/state/active-contracts", "POST", queryRequest, "#/components/schemas/JsGetActiveContractsResponse", true);
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async allocateParty(request) {
         return this.request("/v2/parties", "POST", request, "#/components/schemas/AllocatePartyResponse");
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getLedgerEnd() {
         return this.request("/v2/state/ledger-end", "GET", undefined, "#/components/schemas/GetLedgerEndResponse");
     }

package/lib-lite/src/index.d.ts

@@ -1,5 +1,5 @@
 export { Ledger, type LedgerOptions, createCmd, createAndExerciseCmd, exerciseCmd } from "./ledger.js";
-export { TypedHttpClient, type TypedHttpClientConfig } from "./client.js";
+export { TypedHttpClient, type TypedHttpClientConfig, LedgerApiError } from "./client.js";
 export { WebSocketClient, type StreamConfig, type CompletionStreamRequest, type CompletionStreamMessage, type ActiveContractsStreamRequest, type ActiveContractsStreamMessage, type UpdatesStreamRequest, type UpdatesStreamMessage, } from "./websocket.js";
 export { type ValidationMode } from "./validation.js";
 export { type Logger, ConsoleLogger, NoOpLogger, logger, setLogger } from "./logger.js";

package/lib-lite/src/index.js

@@ -1,6 +1,6 @@
 // Main export for the new ledger package
 export { Ledger, createCmd, createAndExerciseCmd, exerciseCmd } from "./ledger.js";
-export { TypedHttpClient } from "./client.js";
+export { TypedHttpClient, LedgerApiError } from "./client.js";
 export { WebSocketClient, } from "./websocket.js";
 export { ConsoleLogger, NoOpLogger, logger, setLogger } from "./logger.js";
 export * from "./types.js";

package/lib-lite/src/ledger.d.ts

@@ -17,7 +17,7 @@
  * you need access to Canton-specific endpoints or full control over API calls.
  */
 import { ContractId, Party, Choice, InterfaceCompanion, Template } from "@daml/types";
-import { AllocatePartyRequest, AllocatePartyResponse, Command, CreateCommand, CreateAndExerciseCommand, CreateEvent, ExerciseCommand, Event, Interface, LedgerOffset, Stream, InterfaceStream, InterfaceMapping, InterfaceMultiStream, PartyDetails, User, MultiStream, TemplateMapping, VersionedRegistry } from "./types.js";
+import { AllocatePartyRequest, AllocatePartyResponse, AnyCommand, CreateCommand, CreateAndExerciseCommand, CreateEvent, ExerciseCommand, Event, Interface, LedgerOffset, Stream, InterfaceStream, InterfaceMapping, InterfaceMultiStream, PartyDetails, User, MultiStream, TemplateMapping, VersionedRegistry } from "./types.js";
 import { ValidationMode } from "./validation.js";
 import { PackageIdString } from "./valueTypes.js";
 export declare function createCmd<T extends object, K = unknown>(template: Template<T, K, string>, payload: T): CreateCommand<T, K>;
@@ -85,7 +85,9 @@ export declare class Ledger {
     private resolveOffset;
     private getLedgerEnd;
     getTokenUserId(): string;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getTokenUserInfo(): Promise<User | null>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getTokenActAsParties(): Promise<Party[]>;
     /**
      * Query for the Active Contract Set of a specific template.
@@ -96,6 +98,7 @@ export declare class Ledger {
      * @param verbose
      * @param readAsParties
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     query<T extends object, K = unknown>(template: Template<T, K, PackageIdString>, atOffset?: LedgerOffset, includeCreatedEventBlob?: boolean, verbose?: boolean, readAsParties?: Party[]): Promise<CreateEvent<T, K>[]>;
     /**
@@ -106,6 +109,7 @@ export declare class Ledger {
      * @param verbose
      * @param readAsParties
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     queryInterface<I extends object, K = unknown>(interface_: InterfaceCompanion<I, K, PackageIdString>, atOffset?: LedgerOffset, includeCreatedEventBlob?: boolean, verbose?: boolean, readAsParties?: Party[]): Promise<Interface<I>[]>;
     /**
@@ -114,6 +118,7 @@ export declare class Ledger {
      * @param payload
      * @param actAs
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     create<T extends object, K = unknown, TTemplateId extends string = string>(template: Template<T, K, TTemplateId>, payload: T, actAs?: Party[]): Promise<CreateEvent<T, K>>;
     /**
@@ -123,6 +128,7 @@ export declare class Ledger {
      * @param argument
      * @param actAs
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     exercise<T extends object, C, R, K = unknown>(choice: Choice<T, C, R, K>, contractId: ContractId<T>, argument: C, actAs?: Party[]): Promise<Event<object, unknown>[]>;
     /**
@@ -133,8 +139,9 @@ export declare class Ledger {
      * @param commands
      * @param actAs Defaults to the actAs parties of the user in the token.
      * @returns Stream of events resulting from the submitted commands.
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
-    submit(commands: Command<any, any>[], actAs?: Party[]): Promise<Event<object, unknown>[]>;
+    submit(commands: AnyCommand[], actAs?: Party[]): Promise<Event<object, unknown>[]>;
     private initClient;
     /**
      * Stream functionality using WebSockets
@@ -192,7 +199,10 @@ export declare class Ledger {
      */
     createMultiStream<TM extends TemplateMapping>(tm: TM, offset?: LedgerOffset, skipAcs?: boolean, includeCreatedEventBlob?: boolean, readAsParties?: Party[]): Promise<MultiStream<TM>>;
     createMultiInterfaceStream<IM extends InterfaceMapping>(im: IM, offset?: LedgerOffset, skipAcs?: boolean, includeCreatedEventBlob?: boolean, readAsParties?: Party[]): Promise<InterfaceMultiStream<IM>>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getUserInfo(userId: string): Promise<User | null>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     getParties(): Promise<PartyDetails[]>;
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     allocateParty(request: AllocatePartyRequest): Promise<AllocatePartyResponse>;
 }

package/lib-lite/src/ledger.js

@@ -549,6 +549,7 @@ export class Ledger {
     getTokenUserId() {
         return this.tokenUserId;
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getTokenUserInfo() {
         if (this.tokenUserInfo) {
             return this.tokenUserInfo;
@@ -558,6 +559,7 @@ export class Ledger {
             return this.tokenUserInfo;
         }
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getTokenActAsParties() {
         const userInfo = await this.getTokenUserInfo();
         return (userInfo?.rights.filter(right => right.type === "canActAs").map(right => right.party) || []);
@@ -571,6 +573,7 @@ export class Ledger {
      * @param verbose
      * @param readAsParties
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     async query(template, atOffset = "end", includeCreatedEventBlob = false, verbose = false, readAsParties) {
         const activeAtOffset = await this.resolveOffset(atOffset);
@@ -620,6 +623,7 @@ export class Ledger {
      * @param verbose
      * @param readAsParties
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     async queryInterface(interface_, atOffset = "end", includeCreatedEventBlob = false, verbose = false, readAsParties) {
         if (this.options.versionedRegistry === undefined) {
@@ -676,6 +680,7 @@ export class Ledger {
      * @param payload
      * @param actAs
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     async create(template, payload, actAs) {
         const createCommand = {
@@ -729,6 +734,7 @@ export class Ledger {
      * @param argument
      * @param actAs
      * @returns
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     async exercise(choice, contractId, argument, actAs) {
         // Extract actAs from meta or use a default
@@ -777,6 +783,7 @@ export class Ledger {
      * @param commands
      * @param actAs Defaults to the actAs parties of the user in the token.
      * @returns Stream of events resulting from the submitted commands.
+     * @throws {LedgerApiError} on non-OK HTTP response from the ledger
      */
     async submit(commands, actAs) {
         const jsCommands = commands.map((command) => convertCommand(command));
@@ -906,7 +913,7 @@ export class Ledger {
         const stream = new InterfaceStreamImpl(filters, parties_, this.initClient(), activeAtOffset, this.options.versionedRegistry, skipAcs, includeCreatedEventBlob, this.options.autoReconnect ?? true);
         return new InterfaceMultiStreamImpl(stream);
     }
-    // User information
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getUserInfo(userId) {
         const response = await this.client.getUserInfo(userId);
         if (!response.user) {
@@ -922,7 +929,7 @@ export class Ledger {
             };
         }
     }
-    // Party management
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async getParties() {
         const response = await this.client.getParties();
         return (response.partyDetails || []).map((party) => ({
@@ -931,6 +938,7 @@ export class Ledger {
             isLocal: party.isLocal || false,
         }));
     }
+    /** @throws {LedgerApiError} on non-OK HTTP response from the ledger */
     async allocateParty(request) {
         const allocateRequest = {
             partyIdHint: request.partyIdHint

package/lib-lite/src/types.d.ts

@@ -1,6 +1,8 @@
 import { ContractId, Party, Choice, Template, InterfaceCompanion } from "@daml/types";
 import { PartyIdString, UserIdString, PackageIdString } from "./valueTypes.js";
-import { JsCantonError } from "./websocket.js";
+import type { components } from "./generated/async-api.js";
+export type JsCantonError = components["schemas"]["JsCantonError"];
+export declare function isCantonError(response: unknown): response is JsCantonError;
 export type CreateEvent<T extends object, K = unknown> = {
     type: "create";
     templateId: PackageIdString;
@@ -226,6 +228,13 @@ export type ExerciseCommand<T extends object, C, R, K = unknown> = {
     argument: C;
 };
 export type Command<T extends object, C, R = unknown, K = unknown> = CreateCommand<T, K> | CreateAndExerciseCommand<T, C, R, K> | ExerciseCommand<T, C, R, K>;
+/**
+ * A command with erased type parameters, suitable for heterogeneous arrays
+ * passed to `Ledger.submit()`. Each variant is independently widened to `any`,
+ * so a `CreateCommand<A, KA>` and an `ExerciseCommand<B, CB, RB, KB>` can
+ * coexist in the same `AnyCommand[]` without a cast.
+ */
+export type AnyCommand = CreateCommand<any, any> | CreateAndExerciseCommand<any, any, any, any> | ExerciseCommand<any, any, any, any>;
 export interface AllocatePartyRequest {
     partyIdHint?: PartyIdString;
     displayName?: string;

package/lib-lite/src/types.js

@@ -1 +1,8 @@
-export {};
+// Type guard to check if a response is a JsCantonError
+export function isCantonError(response) {
+    return (typeof response === "object" &&
+        response !== null &&
+        "code" in response &&
+        "cause" in response &&
+        "context" in response);
+}

package/lib-lite/src/websocket.d.ts

@@ -7,6 +7,8 @@
  */
 import type { channels, components } from "./generated/async-api.js";
 import { ValidationMode } from "./validation.js";
+import { isCantonError, type JsCantonError } from "./types.js";
+export { JsCantonError, isCantonError };
 export interface StreamConfig {
     token: string;
     wsBaseUrl: string;
@@ -22,7 +24,6 @@ export type ActiveContractsStreamRequest = ActiveContractsChannel["publish"]["me
 export type ActiveContractsStreamMessage = ActiveContractsChannel["subscribe"]["message"];
 export type UpdatesStreamRequest = UpdatesChannel["publish"]["message"];
 export type UpdatesStreamMessage = UpdatesChannel["subscribe"]["message"];
-export type JsCantonError = components["schemas"]["JsCantonError"];
 export type Response<T> = {
     status: "success";
     data: T;
@@ -36,7 +37,6 @@ export type UpdatesResponse = Response<components["schemas"]["JsGetUpdatesRespon
 export interface StopClient {
     (): void;
 }
-export declare function isCantonError(response: unknown): response is JsCantonError;
 export declare function parseStreamResponse<T>(response: T | JsCantonError): Response<T>;
 export declare function isTransaction(response: unknown): response is {
     Transaction: components["schemas"]["Transaction"];
@@ -75,4 +75,3 @@ export declare class WebSocketClient {
      */
     streamUpdates(request: UpdatesStreamRequest, onMessage: (message: UpdatesResponse) => void, onError?: (error: Error) => void, onClose?: (code: number, reason: string) => void): StopClient;
 }
-export {};

package/lib-lite/src/websocket.js

@@ -1,7 +1,9 @@
 import { SchemaValidator } from "./validation.js";
 import { logger } from "./logger.js";
 import { logTokenExpiration } from "./token.js";
+import { isCantonError } from "./types.js";
 import WebSocket from "isomorphic-ws";
+export { isCantonError };
 // Constant mapping from endpoints to their JSON Schema validation paths
 const SCHEMA_MAP = {
     "/v2/commands/completions": "#/components/schemas/Either_JsCantonError_CompletionStreamResponse",
@@ -10,14 +12,6 @@ const SCHEMA_MAP = {
     "/v2/updates/flats": "#/components/schemas/Either_JsCantonError_JsGetUpdatesResponse",
     "/v2/updates/trees": "#/components/schemas/Either_JsCantonError_JsGetUpdateTreesResponse",
 };
-// Type guard to check if a response is a JsCantonError
-export function isCantonError(response) {
-    return (typeof response === "object" &&
-        response !== null &&
-        "code" in response &&
-        "cause" in response &&
-        "context" in response);
-}
 export function parseStreamResponse(response) {
     if (isCantonError(response)) {
         return { status: "error", error: response };