@c7-digital/ledger 0.0.2

package/lib/src/validation.js

@@ -0,0 +1,182 @@
+/**
+ * Runtime validation utilities for API responses using JSON Schema validation
+ *
+ * Uses embedded schema strings instead of file system access for browser compatibility.
+ */
+import * as Ajv from "ajv";
+import { logger } from "./logger.js";
+export class SchemaValidator {
+    constructor(schemaType = "openapi", validation) {
+        this.schemaCount = 0;
+        this.instanceId = Math.random().toString(36).substring(2, 8);
+        this.validation = validation;
+        if (!this.validation) {
+            logger.debug(`Validation disabled for instance ${this.instanceId} - schemas not loaded (validation mode: undefined)`);
+            this.schemaReady = Promise.resolve();
+            return;
+        }
+        this.ajv = new Ajv.default({
+            allErrors: true,
+            verbose: true,
+            addUsedSchema: false, // Don't add schemas automatically
+        });
+        logger.log(`Creating SchemaValidator instance ${this.instanceId} for ${schemaType} schema`);
+        // Add support for Canton/OpenAPI formats
+        this.addCustomFormats();
+        // Load schemas asynchronously to enable tree shaking
+        this.schemaReady = this.loadSchemasAsync(schemaType);
+    }
+    async loadSchemasAsync(schemaType) {
+        try {
+            switch (schemaType) {
+                case "openapi":
+                    const { OPENAPI_SCHEMA } = await import("./generated/openapi-schema.js");
+                    await this.loadSchemasFromContent(OPENAPI_SCHEMA);
+                    break;
+                case "asyncapi":
+                    const { ASYNCAPI_SCHEMA } = await import("./generated/asyncapi-schema.js");
+                    await this.loadSchemasFromContent(ASYNCAPI_SCHEMA);
+                    break;
+            }
+        }
+        catch (error) {
+            logger.warn(` Failed to load ${schemaType} schema for validation:`, error);
+        }
+    }
+    /**
+     * Add custom format validators for Canton API types
+     */
+    addCustomFormats() {
+        if (!this.ajv)
+            return;
+        // int64 format - just validate it's a valid number or string that can be parsed as number
+        this.ajv.addFormat("int64", {
+            type: "number",
+            validate: (data) => {
+                if (typeof data === "number") {
+                    return Number.isInteger(data);
+                }
+                if (typeof data === "string") {
+                    const num = parseInt(data, 10);
+                    return !isNaN(num) && num.toString() === data;
+                }
+                return false;
+            },
+        });
+        // int32 format
+        this.ajv.addFormat("int32", {
+            type: "number",
+            validate: (data) => {
+                if (typeof data === "number") {
+                    return Number.isInteger(data) && data >= -2147483648 && data <= 2147483647;
+                }
+                return false;
+            },
+        });
+        // date-time format (if not already supported)
+        this.ajv.addFormat("date-time", {
+            type: "string",
+            validate: (dateTimeString) => {
+                if (typeof dateTimeString !== "string")
+                    return false;
+                return !isNaN(Date.parse(dateTimeString));
+            },
+        });
+    }
+    /**
+     * Helper function to handle errors based on the validation mode
+     */
+    handleError(message, error) {
+        if (this.validation === "logErrors") {
+            logger.warn(`Warning: ${message}`, error);
+            return;
+        }
+        else {
+            throw error instanceof Error ? error : new Error(message);
+        }
+    }
+    async loadSchemasFromContent(yamlContent) {
+        if (!this.ajv)
+            return;
+        try {
+            // Dynamically import yaml only when needed for tree-shaking
+            const yaml = await import("yaml");
+            const spec = yaml.parse(yamlContent);
+            // Load the complete schema document first to enable reference resolution
+            if (spec?.components?.schemas) {
+                // Add the full schema document with an ID so references can be resolved
+                this.ajv.addSchema(spec, "#");
+                logger.debug(`Added full schema document with ID "#"`);
+                // Then add individual schemas for direct validation with full reference paths
+                for (const [schemaName, schemaDefinition] of Object.entries(spec.components.schemas)) {
+                    const fullSchemaPath = `#/components/schemas/${schemaName}`;
+                    this.ajv.addSchema(schemaDefinition, fullSchemaPath);
+                    logger.debug(`Added schema: "${fullSchemaPath}"`);
+                    this.schemaCount++;
+                }
+                // Debug: Show schema count
+                logger.debug(`Instance ${this.instanceId} - Loaded ${this.schemaCount} schemas`);
+            }
+            logger.debug(`Loaded ${this.schemaCount} JSON schemas from embedded content`);
+        }
+        catch (error) {
+            this.handleError(`Could not load schemas from embedded content:`, error);
+        }
+    }
+    /**
+     * Validate an array of items against a schema
+     */
+    async validateArraySchema(data, itemSchemaName) {
+        // If validation is disabled, just return data as-is
+        if (!this.validation) {
+            return data;
+        }
+        // Wait for schema to be loaded
+        await this.schemaReady;
+        if (!Array.isArray(data)) {
+            this.handleError(`Expected array but got ${typeof data}`);
+            return data;
+        }
+        // Validate each item in the array
+        for (let i = 0; i < data.length; i++) {
+            await this.validateSchema(data[i], itemSchemaName);
+        }
+        return data;
+    }
+    /**
+     * Validate data against a schema and return typed result
+     */
+    async validateSchema(data, schemaName) {
+        // If validation is disabled, just return data as-is
+        if (!this.validation) {
+            return data;
+        }
+        // Wait for schema to be loaded
+        await this.schemaReady;
+        if (!this.ajv) {
+            this.handleError(`Validation not available - ajv not initialized`);
+            return data;
+        }
+        logger.debug(`🔍 Instance ${this.instanceId} - Attempting to validate against schema: "${schemaName}",`, { data });
+        try {
+            // Check if schema exists
+            const schema = this.ajv.getSchema(schemaName);
+            if (!schema) {
+                logger.warn(`Schema "${schemaName}" not found in AJV`);
+                this.handleError(`Schema "${schemaName}" not found`);
+                return data;
+            }
+            const isValid = this.ajv.validate(schemaName, data);
+            if (!isValid) {
+                this.handleError(`Schema validation failed for ${schemaName}:`, new Error(`Schema validation failed for ${schemaName}: ${this.ajv.errorsText()}`));
+            }
+            else {
+                logger.debug(`Validation successful for "${schemaName}"`);
+            }
+        }
+        catch (error) {
+            this.handleError(`Validation error for ${schemaName}: ${error}`);
+        }
+        return data;
+    }
+}

package/lib/src/valueTypes.d.ts

@@ -0,0 +1,34 @@
+declare const __brand: unique symbol;
+type Brand<T, TBrand> = T & {
+    [__brand]: TBrand;
+};
+export type NameString = Brand<string, "NameString">;
+export type PackageIdString = Brand<string, "PackageIdString">;
+export type PartyIdString = Brand<string, "PartyIdString">;
+export type LedgerString = Brand<string, "LedgerString">;
+export type UserIdString = Brand<string, "UserIdString">;
+export declare function isValidNameString(value: string): value is NameString;
+export declare function isValidPackageIdString(value: string): value is PackageIdString;
+export declare function isValidPartyIdString(value: string): value is PartyIdString;
+export declare function isValidLedgerString(value: string): value is LedgerString;
+export declare function isValidUserIdString(value: string): value is UserIdString;
+export declare function createNameString(value: string): NameString;
+export declare function createPackageIdString(value: string): PackageIdString;
+export declare function createPartyIdString(value: string): PartyIdString;
+export declare function createLedgerString(value: string): LedgerString;
+export declare function createUserIdString(value: string): UserIdString;
+export declare const ValueStringValidators: {
+    readonly isValidNameString: typeof isValidNameString;
+    readonly isValidPackageIdString: typeof isValidPackageIdString;
+    readonly isValidPartyIdString: typeof isValidPartyIdString;
+    readonly isValidLedgerString: typeof isValidLedgerString;
+    readonly isValidUserIdString: typeof isValidUserIdString;
+};
+export declare const ValueStringCreators: {
+    readonly createNameString: typeof createNameString;
+    readonly createPackageIdString: typeof createPackageIdString;
+    readonly createPartyIdString: typeof createPartyIdString;
+    readonly createLedgerString: typeof createLedgerString;
+    readonly createUserIdString: typeof createUserIdString;
+};
+export {};

package/lib/src/valueTypes.js

@@ -0,0 +1,76 @@
+// Branded string types based on value.proto from Daml gRPC API
+// Source: https://github.com/digital-asset/daml/blob/main/sdk/daml-lf/ledger-api-value/src/main/protobuf/com/daml/ledger/api/v2/value.proto
+// Validation patterns from value.proto
+const NAME_STRING_PATTERN = /^[A-Za-z\$_][A-Za-z0-9\$_]*$/;
+const PACKAGE_ID_STRING_PATTERN = /^[A-Za-z0-9\-_ ]+$/;
+const PARTY_ID_STRING_PATTERN = /^[A-Za-z0-9:\-_ ]+$/;
+const LEDGER_STRING_PATTERN = /^[A-Za-z0-9#:\-_/ ]+$/;
+const USER_ID_STRING_PATTERN = /^[a-zA-Z0-9@^$.!\`\-#+'~_|:]+$/;
+// Length constraints from value.proto
+const MAX_NAME_STRING_LENGTH = 1000;
+const MAX_PACKAGE_ID_STRING_LENGTH = 64;
+const MAX_PARTY_ID_STRING_LENGTH = 255;
+const MAX_LEDGER_STRING_LENGTH = 255;
+const MAX_USER_ID_STRING_LENGTH = 128;
+// Validation functions
+export function isValidNameString(value) {
+    return value.length <= MAX_NAME_STRING_LENGTH && NAME_STRING_PATTERN.test(value);
+}
+export function isValidPackageIdString(value) {
+    return value.length <= MAX_PACKAGE_ID_STRING_LENGTH && PACKAGE_ID_STRING_PATTERN.test(value);
+}
+export function isValidPartyIdString(value) {
+    return value.length <= MAX_PARTY_ID_STRING_LENGTH && PARTY_ID_STRING_PATTERN.test(value);
+}
+export function isValidLedgerString(value) {
+    return value.length <= MAX_LEDGER_STRING_LENGTH && LEDGER_STRING_PATTERN.test(value);
+}
+export function isValidUserIdString(value) {
+    return value.length <= MAX_USER_ID_STRING_LENGTH && USER_ID_STRING_PATTERN.test(value);
+}
+// Creation functions with validation
+export function createNameString(value) {
+    if (!isValidNameString(value)) {
+        throw new Error(`Invalid NameString: "${value}". Must match [A-Za-z\$_][A-Za-z0-9\$_]* and be ≤ ${MAX_NAME_STRING_LENGTH} chars`);
+    }
+    return value;
+}
+export function createPackageIdString(value) {
+    if (!isValidPackageIdString(value)) {
+        throw new Error(`Invalid PackageIdString: "${value}". Must match [A-Za-z0-9\-_ ]+ and be ≤ ${MAX_PACKAGE_ID_STRING_LENGTH} chars`);
+    }
+    return value;
+}
+export function createPartyIdString(value) {
+    if (!isValidPartyIdString(value)) {
+        throw new Error(`Invalid PartyIdString: "${value}". Must match [A-Za-z0-9:\-_ ]+ and be ≤ ${MAX_PARTY_ID_STRING_LENGTH} chars`);
+    }
+    return value;
+}
+export function createLedgerString(value) {
+    if (!isValidLedgerString(value)) {
+        throw new Error(`Invalid LedgerString: "${value}". Must match [A-Za-z0-9#:\-_/ ]+ and be ≤ ${MAX_LEDGER_STRING_LENGTH} chars`);
+    }
+    return value;
+}
+export function createUserIdString(value) {
+    if (!isValidUserIdString(value)) {
+        throw new Error(`Invalid UserIdString: "${value}". Must match [a-zA-Z0-9@^$.!\`\-#+'~_|:]+ and be ≤ ${MAX_USER_ID_STRING_LENGTH} chars`);
+    }
+    return value;
+}
+// Utility type guards for runtime checking
+export const ValueStringValidators = {
+    isValidNameString,
+    isValidPackageIdString,
+    isValidPartyIdString,
+    isValidLedgerString,
+    isValidUserIdString,
+};
+export const ValueStringCreators = {
+    createNameString,
+    createPackageIdString,
+    createPartyIdString,
+    createLedgerString,
+    createUserIdString,
+};

package/lib/src/websocket.d.ts

@@ -0,0 +1,69 @@
+/**
+ * WebSocket client for Canton's AsyncAPI v2 streaming endpoints
+ *
+ * Provides real-time event streaming for completions, active contracts,
+ * and ledger updates using WebSocket connections with proper authentication
+ * and typed message handling.
+ */
+import type { channels, components } from "./generated/async-api.js";
+import { ValidationMode } from "./validation.js";
+export interface StreamConfig {
+    token: string;
+    wsBaseUrl: string;
+    validation?: ValidationMode;
+    asyncApiSchemaPath?: string;
+}
+type CompletionChannel = channels["/v2/commands/completions"];
+type ActiveContractsChannel = channels["/v2/state/active-contracts"];
+type UpdatesChannel = channels["/v2/updates/flats"];
+export type CompletionStreamRequest = CompletionChannel["publish"]["message"];
+export type CompletionStreamMessage = CompletionChannel["subscribe"]["message"];
+export type ActiveContractsStreamRequest = ActiveContractsChannel["publish"]["message"];
+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;
+} | {
+    status: "error";
+    error: JsCantonError;
+};
+export type CompletionResponse = Response<components["schemas"]["CompletionStreamResponse"]>;
+export type ActiveContractsResponse = Response<components["schemas"]["JsGetActiveContractsResponse"]>;
+export type UpdatesResponse = Response<components["schemas"]["JsGetUpdatesResponse"]>;
+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"];
+};
+export declare function isJsTransaction(response: unknown): response is components["schemas"]["JsTransaction"];
+export declare class WebSocketClient {
+    private token;
+    private wsBaseUrl;
+    private validator?;
+    constructor(config: StreamConfig);
+    /**
+     * Generic streaming method with full type safety
+     * This method enforces that request/response types match the endpoint
+     */
+    private stream;
+    private createWebSocket;
+    /**
+     * Stream command completions in real-time
+     */
+    streamCompletions(request: CompletionStreamRequest, onMessage: (message: CompletionResponse) => void, onError?: (error: Error) => void, onClose?: (code: number, reason: string) => void): StopClient;
+    /**
+     * Stream active contracts
+     */
+    streamActiveContracts(request: ActiveContractsStreamRequest, onMessage: (message: ActiveContractsResponse) => void, onError?: (error: Error) => void, onClose?: (code: number, reason: string) => void): StopClient;
+    /**
+     * Stream all ledger updates
+     */
+    streamUpdates(request: UpdatesStreamRequest, onMessage: (message: UpdatesResponse) => void, onError?: (error: Error) => void, onClose?: (code: number, reason: string) => void): StopClient;
+}
+export {};

package/lib/src/websocket.js

@@ -0,0 +1,125 @@
+import { SchemaValidator } from "./validation.js";
+import { logger } from "./logger.js";
+import WebSocket from "isomorphic-ws";
+// Constant mapping from endpoints to their JSON Schema validation paths
+const SCHEMA_MAP = {
+    "/v2/commands/completions": "#/components/schemas/Either_JsCantonError_CompletionStreamResponse",
+    "/v2/state/active-contracts": "#/components/schemas/Either_JsCantonError_JsGetActiveContractsResponse",
+    "/v2/updates": "#/components/schemas/Either_JsCantonError_JsGetUpdatesResponse",
+    "/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 };
+    }
+    return { status: "success", data: response };
+}
+export function isTransaction(response) {
+    if (typeof response === "object" &&
+        response !== null &&
+        "Transaction" in response &&
+        typeof response.Transaction === "object" &&
+        response.Transaction !== null &&
+        "value" in response.Transaction) {
+        const transaction = response.Transaction;
+        return isJsTransaction(transaction.value);
+    }
+    return false;
+}
+export function isJsTransaction(response) {
+    return (typeof response === "object" &&
+        response !== null &&
+        "updateId" in response &&
+        "commandId" in response &&
+        "workflowId" in response &&
+        "effectiveAt" in response &&
+        "offset" in response &&
+        "synchronizerId" in response &&
+        "recordTime" in response);
+}
+export class WebSocketClient {
+    constructor(config) {
+        this.token = config.token;
+        this.wsBaseUrl = config.wsBaseUrl;
+        this.validator = config.validation
+            ? new SchemaValidator("asyncapi", config.validation)
+            : undefined;
+    }
+    /**
+     * Generic streaming method with full type safety
+     * This method enforces that request/response types match the endpoint
+     */
+    stream(endpoint, request, onMessage, onError, onClose) {
+        const ws = this.createWebSocket(endpoint);
+        ws.onopen = () => {
+            logger.debug(`Opening websocket for ${endpoint}: `, { request });
+            ws.send(JSON.stringify(request));
+        };
+        ws.onmessage = async (event) => {
+            try {
+                const parsed = JSON.parse(event.data.toString());
+                logger.debug(`Received message for ${endpoint}: `, { parsed });
+                let message = this.validator
+                    ? await this.validator.validateSchema(parsed, SCHEMA_MAP[endpoint])
+                    : parsed;
+                onMessage(message);
+            }
+            catch (error) {
+                onError?.(new Error(`Failed to parse message for ${endpoint}: ${error}`));
+            }
+        };
+        ws.onerror = (event) => {
+            const errorMsg = `WebSocket error ${event.type}, message: ${event.message}`;
+            onError?.(new Error(`WebSocket error: ${errorMsg}`));
+        };
+        ws.onclose = (closeEvent) => {
+            logger.debug(`WebSocket closed for ${endpoint}: `, {
+                code: closeEvent.code,
+                reason: closeEvent.reason,
+            });
+            onClose?.(closeEvent.code, closeEvent.reason);
+        };
+        return () => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.close();
+            }
+        };
+    }
+    createWebSocket(endpoint) {
+        const baseUrl = this.wsBaseUrl.endsWith("/") ? this.wsBaseUrl : `${this.wsBaseUrl}/`;
+        const url = endpoint.startsWith("/")
+            ? `${baseUrl}${endpoint.slice(1)}`
+            : `${baseUrl}/${endpoint}`;
+        // WebSocket authentication via Sec-WebSocket-Protocol header
+        const protocols = [`jwt.token.${this.token}`, "daml.ws.auth"];
+        logger.debug(`Connecting websocket to ${url} with protocols: ${protocols}`);
+        return new WebSocket(url, protocols);
+    }
+    /**
+     * Stream command completions in real-time
+     */
+    streamCompletions(request, onMessage, onError, onClose) {
+        return this.stream("/v2/commands/completions", request, rawMessage => onMessage(parseStreamResponse(rawMessage)), onError, onClose);
+    }
+    /**
+     * Stream active contracts
+     */
+    streamActiveContracts(request, onMessage, onError, onClose) {
+        return this.stream("/v2/state/active-contracts", request, rawMessage => onMessage(parseStreamResponse(rawMessage)), onError, onClose);
+    }
+    /**
+     * Stream all ledger updates
+     */
+    streamUpdates(request, onMessage, onError, onClose) {
+        return this.stream("/v2/updates", request, rawMessage => onMessage(parseStreamResponse(rawMessage)), onError, onClose);
+    }
+}