@c7-digital/ledger 0.0.2

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

@@ -0,0 +1 @@
+export {};

package/lib-lite/src/ledger.test.js

@@ -0,0 +1,23 @@
+// Basic tests for the new ledger implementation
+import { Ledger } from "./ledger.js";
+// Valid JWT token for testing with sub field
+// Header: {"alg":"HS256","typ":"JWT"}
+// Payload: {"sub":"test-user","iat":1516239022}
+const TEST_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0LXVzZXIiLCJpYXQiOjE1MTYyMzkwMjJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
+describe("Ledger", () => {
+    it("should create a ledger instance with default options", () => {
+        const ledger = new Ledger({
+            token: TEST_TOKEN,
+            httpBaseUrl: "http://localhost:7575",
+        });
+        expect(ledger).toBeInstanceOf(Ledger);
+    });
+    it("should create a ledger instance with custom options", () => {
+        const ledger = new Ledger({
+            token: TEST_TOKEN,
+            httpBaseUrl: "http://example.com:8080",
+            wsBaseUrl: "ws://example.com:8080",
+        });
+        expect(ledger).toBeInstanceOf(Ledger);
+    });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * Logger interface for injecting custom logging behavior into the ledger package
+ */
+export interface Logger {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    log(message: string, ...args: any[]): void;
+}
+/**
+ * Default console-based logger implementation
+ */
+export declare class ConsoleLogger implements Logger {
+    private usePrefix;
+    constructor(usePrefix?: boolean);
+    private addPrefix;
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    log(message: string, ...args: any[]): void;
+}
+/**
+ * No-op logger that discards all log messages
+ */
+export declare class NoOpLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+    log(): void;
+}
+/**
+ * Set the global logger instance used by the ledger package
+ */
+export declare function setLogger(newLogger: Logger): void;
+/**
+ * Global logger proxy that delegates to the current logger instance
+ */
+export declare const logger: Logger;

package/lib-lite/src/logger.js

@@ -0,0 +1,56 @@
+/**
+ * Default console-based logger implementation
+ */
+export class ConsoleLogger {
+    constructor(usePrefix = true) {
+        this.usePrefix = usePrefix;
+    }
+    addPrefix(message) {
+        return this.usePrefix ? `ledger: ${message}` : message;
+    }
+    debug(message, ...args) {
+        console.debug(this.addPrefix(message), ...args);
+    }
+    info(message, ...args) {
+        console.info(this.addPrefix(message), ...args);
+    }
+    warn(message, ...args) {
+        console.warn(this.addPrefix(message), ...args);
+    }
+    error(message, ...args) {
+        console.error(this.addPrefix(message), ...args);
+    }
+    log(message, ...args) {
+        console.log(this.addPrefix(message), ...args);
+    }
+}
+/**
+ * No-op logger that discards all log messages
+ */
+export class NoOpLogger {
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+    log() { }
+}
+/**
+ * Internal logger instance holder
+ */
+let globalLoggerInstance = new ConsoleLogger(true);
+/**
+ * Set the global logger instance used by the ledger package
+ */
+export function setLogger(newLogger) {
+    globalLoggerInstance = newLogger;
+}
+/**
+ * Global logger proxy that delegates to the current logger instance
+ */
+export const logger = {
+    debug: (message, ...args) => globalLoggerInstance.debug(message, ...args),
+    info: (message, ...args) => globalLoggerInstance.info(message, ...args),
+    warn: (message, ...args) => globalLoggerInstance.warn(message, ...args),
+    error: (message, ...args) => globalLoggerInstance.error(message, ...args),
+    log: (message, ...args) => globalLoggerInstance.log(message, ...args),
+};

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

@@ -0,0 +1,47 @@
+import { ArchiveEvent, CantonError, CreateEvent, MultiStream, Stream, StreamState, TemplateMapping } from "./types.js";
+/**
+ * Adapts a Stream instance to the MultiStream interface
+ * Provides template-specific event handlers with proper typing
+ */
+export declare class MultiStreamAdapter<TM extends TemplateMapping> implements MultiStream<TM> {
+    private stream;
+    private templateEmitters;
+    private errorEmitter;
+    private stateEmitter;
+    /**
+     * Create a new MultiStream adapter
+     * @param stream The underlying Stream instance
+     */
+    constructor(stream: Stream<object, unknown>);
+    /**
+     * Get or create an EventEmitter for a specific template
+     */
+    private getEmitterForTemplate;
+    /**
+     * Handle create events from the underlying stream
+     * and route them to the appropriate template emitter
+     */
+    private handleCreateEvent;
+    /**
+     * Handle archive events from the underlying stream
+     * and route them to the appropriate template emitter
+     */
+    private handleArchiveEvent;
+    /**
+     * Handle error events from the underlying stream
+     * and emit them to the dedicated error emitter
+     */
+    private handleError;
+    private handleStateEvent;
+    onCreate<TID extends keyof TM>(templateId: TID, listener: (event: CreateEvent<TM[TID]["contractType"] & object, TM[TID]["keyType"]>) => void): void;
+    onArchive<TID extends keyof TM>(templateId: TID, listener: (event: ArchiveEvent<TM[TID]["contractType"]>) => void): void;
+    onError(listener: (error: CantonError) => void): void;
+    onState(listener: (state: StreamState) => void): void;
+    offCreate<TID extends keyof TM>(templateId: TID, listener: (event: CreateEvent<TM[TID]["contractType"], TM[TID]["keyType"]>) => void): void;
+    offArchive<TID extends keyof TM>(templateId: TID, listener: (event: ArchiveEvent<TM[TID]["contractType"]>) => void): void;
+    offError(listener: (error: CantonError) => void): void;
+    offState(listener: (state: StreamState) => void): void;
+    start(): void;
+    state(): StreamState;
+    close(): void;
+}

package/lib-lite/src/multistream.js

@@ -0,0 +1,123 @@
+import { EventEmitter } from "eventemitter3";
+import { logger } from "./logger.js";
+import { TemplateEmitterMap } from "./TemplateEmitterMap.js";
+/**
+ * Adapts a Stream instance to the MultiStream interface
+ * Provides template-specific event handlers with proper typing
+ */
+export class MultiStreamAdapter {
+    /**
+     * Create a new MultiStream adapter
+     * @param stream The underlying Stream instance
+     */
+    constructor(stream) {
+        this.templateEmitters = new TemplateEmitterMap();
+        this.errorEmitter = new EventEmitter(); // Dedicated error emitter
+        this.stateEmitter = new EventEmitter(); // Dedicated state emitter
+        this.stream = stream;
+        // Set up global listeners that route events to template-specific emitters
+        this.stream.on("create", this.handleCreateEvent.bind(this));
+        this.stream.on("archive", this.handleArchiveEvent.bind(this));
+        this.stream.on("error", this.handleError.bind(this));
+        this.stream.on("state", this.handleStateEvent.bind(this));
+    }
+    /**
+     * Get or create an EventEmitter for a specific template
+     */
+    getEmitterForTemplate(templateId) {
+        if (!this.templateEmitters.has(templateId)) {
+            this.templateEmitters.set(templateId, new EventEmitter());
+        }
+        return this.templateEmitters.get(templateId);
+    }
+    /**
+     * Handle create events from the underlying stream
+     * and route them to the appropriate template emitter
+     */
+    handleCreateEvent(event) {
+        const templateId = event.templateId;
+        if (this.templateEmitters.has(templateId)) {
+            this.templateEmitters.get(templateId).emit("create", event);
+        }
+        else {
+            logger.warn(`Received create event for unknown template ${templateId}`);
+        }
+    }
+    /**
+     * Handle archive events from the underlying stream
+     * and route them to the appropriate template emitter
+     */
+    handleArchiveEvent(event) {
+        const templateId = event.templateId;
+        if (this.templateEmitters.has(templateId)) {
+            this.templateEmitters.get(templateId).emit("archive", event);
+        }
+        else {
+            logger.warn(`Received archive event for unknown template ${templateId}`);
+        }
+    }
+    /**
+     * Handle error events from the underlying stream
+     * and emit them to the dedicated error emitter
+     */
+    handleError(error) {
+        // Emit to the dedicated error emitter instead of all template emitters
+        this.errorEmitter.emit("error", error);
+    }
+    handleStateEvent(state) {
+        this.stateEmitter.emit("state", state);
+    }
+    // MultiStream interface implementation
+    onCreate(templateId, listener) {
+        const emitter = this.getEmitterForTemplate(templateId);
+        emitter.on("create", (event) => {
+            // Type assertion: we know the event has the correct type based on templateId
+            listener(event);
+        });
+    }
+    onArchive(templateId, listener) {
+        const emitter = this.getEmitterForTemplate(templateId);
+        emitter.on("archive", (event) => {
+            // Type assertion: we know the event has the correct type based on templateId
+            listener(event);
+        });
+    }
+    onError(listener) {
+        this.errorEmitter.on("error", listener);
+    }
+    onState(listener) {
+        this.stream.on("state", listener);
+    }
+    offCreate(templateId, listener) {
+        if (this.templateEmitters.has(templateId)) {
+            this.templateEmitters.get(templateId).off("create", listener);
+        }
+    }
+    offArchive(templateId, listener) {
+        if (this.templateEmitters.has(templateId)) {
+            this.templateEmitters.get(templateId).off("archive", listener);
+        }
+    }
+    offError(listener) {
+        this.errorEmitter.off("error", listener);
+    }
+    offState(listener) {
+        this.stream.off("state", listener);
+    }
+    start() {
+        this.stream.start();
+    }
+    state() {
+        return this.stream.state();
+    }
+    close() {
+        this.stream.close();
+        for (const emitter of this.templateEmitters.values()) {
+            emitter.removeAllListeners();
+        }
+        this.templateEmitters.clear();
+        // Clean up the error emitter too
+        this.errorEmitter.removeAllListeners();
+        this.stateEmitter.removeAllListeners();
+    }
+}

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

@@ -0,0 +1,5 @@
+import { UserRight } from "./types.js";
+import { components } from "./generated/api.js";
+type Schemas = components["schemas"];
+export declare function userRights(right: Schemas["Right"]): UserRight;
+export {};

package/lib-lite/src/translate.js

@@ -0,0 +1,30 @@
+export function userRights(right) {
+    const kind = right.kind;
+    if ("CanActAs" in kind) {
+        return {
+            type: "canActAs",
+            party: kind.CanActAs.value.party,
+        };
+    }
+    else if ("CanReadAs" in kind) {
+        return {
+            type: "canReadAs",
+            party: kind.CanReadAs.value.party,
+        };
+    }
+    else if ("CanReadAsAnyParty" in kind) {
+        return { type: "canReadAsAnyParty" };
+    }
+    else if ("Empty" in kind) {
+        return { type: "empty" };
+    }
+    else if ("IdentityProviderAdmin" in kind) {
+        return { type: "identityProviderAdmin" };
+    }
+    else if ("ParticipantAdmin" in kind) {
+        return { type: "participantAdmin" };
+    }
+    else {
+        throw new Error(`Unknown right kind: ${JSON.stringify(right)}`);
+    }
+}

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

@@ -0,0 +1,201 @@
+import { ContractId, Party, Choice, Template, InterfaceCompanion } from "@daml/types";
+import { PartyIdString, UserIdString, PackageIdString } from "./valueTypes.js";
+import { JsCantonError } from "./websocket.js";
+export type CreateEvent<T extends object, K = unknown> = {
+    type: "create";
+    templateId: PackageIdString;
+    contractId: ContractId<T>;
+    payload: T;
+    signatories: Party[];
+    observers: Party[];
+    key?: K;
+    createdEventBlob: string;
+    /**
+     * Package version string (e.g., "0.0.6")
+     * Only present if using VersionedRegistry
+     */
+    packageVersion?: string;
+};
+/**
+ * An ArchiveEvent of a given template
+ */
+export type ArchiveEvent<T extends object> = {
+    type: "archive";
+    templateId: PackageIdString;
+    contractId: ContractId<T>;
+    witnessParties: Party[];
+    offset: number;
+};
+export type Event<T extends object, K = unknown> = CreateEvent<T, K> | ArchiveEvent<T>;
+/**
+ * The Daml interface of the subscribed 'interfaceId'
+ *
+ * We use 'templateId' here because the name specified in the codegen field,
+ * though this is specified as 'interfaceId' in the OpenAPI spec.
+ */
+export type Interface<I extends object> = {
+    type: "interface";
+    templateId: PackageIdString;
+    contractId: ContractId<I>;
+    payload?: any;
+    signatories: Party[];
+    observers: Party[];
+    key?: any;
+    createdEventBlob: string;
+    interfaceView: I;
+    /**
+     * Package version string (e.g., "0.0.6")
+     * Only present if using VersionedRegistry
+     */
+    packageVersion?: string;
+};
+export type VersionedLookupResult = {
+    type: "template";
+    template: Template<object, unknown, string>;
+    version: string;
+} | {
+    type: "interface";
+    interface_: InterfaceCompanion<object, unknown, string>;
+    version: string;
+};
+/**
+ * By default the codegen models use @daml/types registerTemplate function to
+ * add the Template instance to a map. This is insufficient on two counts; it
+ * does not track the packageId of the containing dar, which is what the stream
+ * returns. Furthermore, it does not register the InterfaceView instance which
+ * one can also get from the stream.
+ *
+ * This type can be passed into our Ledger so that we can use it instead. We
+ * overload the name of the lookup parameter 'templateId' even though in the
+ * interface we really mean the interfaceId as in the spec OpenAPI spec.
+ */
+export type VersionedRegistry = (templateId: string) => VersionedLookupResult | undefined;
+export type LedgerOffset = "start" | "end" | number;
+export type CantonError = JsCantonError;
+export interface StreamCloseEvent {
+    code: number;
+    reason: string;
+}
+export type StreamState = "start" | "init" | "live" | "stop";
+/**
+ * The return interface of streamQuery and streamQueries.
+ */
+export interface Stream<T extends object, K> {
+    on(type: "create", listener: (event: CreateEvent<T, K>) => void): void;
+    on(type: "archive", listener: (event: ArchiveEvent<T>) => void): void;
+    on(type: "error", listener: (event: CantonError) => void): void;
+    on(type: "state", listener: (event: StreamState) => void): void;
+    off(type: "create", listener: (event: CreateEvent<T, K>) => void): void;
+    off(type: "archive", listener: (event: ArchiveEvent<T>) => void): void;
+    off(type: "error", listener: (event: CantonError) => void): void;
+    off(type: "state", listener: (event: StreamState) => void): void;
+    start(): void;
+    state(): StreamState;
+    close(): void;
+}
+/**
+ * Template mapping type for MultiStream:
+ * template IDs to their corresponding contract and key types
+ */
+export type TemplateMapping = Record<string, {
+    contractType: object;
+    keyType: unknown;
+}>;
+/**
+ * Provides template-specific event handlers.
+ */
+export interface MultiStream<TM extends TemplateMapping> {
+    /**
+     * Register a listener for create events for a specific template
+     * @param templateId The template ID to listen for
+     * @param listener The callback function that will receive properly typed events
+     */
+    onCreate<TID extends keyof TM>(templateId: TID, listener: (event: CreateEvent<TM[TID]["contractType"], TM[TID]["keyType"]>) => void): void;
+    /**
+     * Register a listener for archive events for a specific template
+     * @param templateId The template ID to listen for
+     * @param listener The callback function that will receive properly typed events
+     */
+    onArchive<TID extends keyof TM>(templateId: TID, listener: (event: ArchiveEvent<TM[TID]["contractType"]>) => void): void;
+    /**
+     * Register a listener for error events
+     * @param listener The callback function that will receive error events
+     */
+    onError(listener: (error: CantonError) => void): void;
+    onState(listener: (state: StreamState) => void): void;
+    /**
+     * Remove a create event listener for a specific template
+     * @param templateId The template ID to stop listening for
+     * @param listener The callback function to remove
+     */
+    offCreate<TID extends keyof TM>(templateId: TID, listener: (event: CreateEvent<TM[TID]["contractType"], TM[TID]["keyType"]>) => void): void;
+    /**
+     * Remove an archive event listener for a specific template
+     * @param templateId The template ID to stop listening for
+     * @param listener The callback function to remove
+     */
+    offArchive<TID extends keyof TM>(templateId: TID, listener: (event: ArchiveEvent<TM[TID]["contractType"]>) => void): void;
+    /**
+     * Remove an error event listener
+     * @param listener The callback function to remove
+     */
+    offError(listener: (error: CantonError) => void): void;
+    offState(listener: (state: StreamState) => void): void;
+    start(): void;
+    state(): StreamState;
+    close(): void;
+}
+export interface Query<T = unknown> {
+    [key: string]: unknown;
+}
+export type CreateCommand<T extends object, K = unknown> = {
+    type: 'create';
+    template: Template<T, K, string>;
+    payload: T;
+};
+export type CreateAndExerciseCommand<T extends object, C, R, K = unknown> = {
+    type: 'createAndExercise';
+    template: Template<T, K, string>;
+    payload: T;
+    choice: Choice<T, C, R, K>;
+    argument: C;
+};
+export type ExerciseCommand<T extends object, C, R, K = unknown> = {
+    type: 'exercise';
+    choice: Choice<T, C, R, K>;
+    contractId: ContractId<T>;
+    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>;
+export interface AllocatePartyRequest {
+    partyIdHint?: PartyIdString;
+    displayName?: string;
+}
+export interface AllocatePartyResponse {
+    partyDetails: PartyDetails;
+}
+export interface PartyDetails {
+    party: Party;
+    displayName?: string;
+    isLocal: boolean;
+}
+export type UserRight = {
+    type: "canActAs";
+    party: Party;
+} | {
+    type: "canReadAs";
+    party: Party;
+} | {
+    type: "canReadAsAnyParty";
+} | {
+    type: "empty";
+} | {
+    type: "identityProviderAdmin";
+} | {
+    type: "participantAdmin";
+};
+export interface User {
+    userId: UserIdString;
+    primaryParty?: Party;
+    rights: UserRight[];
+}

package/lib-lite/src/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+import { PackageIdString } from "./valueTypes.js";
+export declare function partiallyQualified(templateId: PackageIdString): string;
+export declare function matchesPartiallyQualified(templateId: PackageIdString, other: string): boolean;

package/lib-lite/src/util.js

@@ -0,0 +1,7 @@
+export function partiallyQualified(templateId) {
+    return templateId.split(":").slice(1).join(":");
+}
+//
+export function matchesPartiallyQualified(templateId, other) {
+    return partiallyQualified(templateId) === other.split(":").slice(1).join(":");
+}

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

@@ -0,0 +1,14 @@
+export type ValidationMode = "throwOnError" | "logErrors";
+export declare class SchemaValidator {
+    private instanceId;
+    private schemaReady;
+    constructor(schemaType?: "openapi" | "asyncapi", validation?: ValidationMode);
+    /**
+     * Validate an array of items against a schema (lite: pass-through)
+     */
+    validateArraySchema<T>(data: unknown, _itemSchemaName: string): Promise<T[]>;
+    /**
+     * Validate data against a schema and return typed result (lite: pass-through)
+     */
+    validateSchema<T>(data: unknown, _schemaName: string): Promise<T>;
+}

package/lib-lite/src/validation.js

@@ -0,0 +1,31 @@
+/**
+ * Lite runtime validation utilities - validation is disabled in lite builds
+ *
+ * This module provides stub implementations that pass data through without validation.
+ * Use the full @c7-digital/ledger package if you need runtime schema validation.
+ */
+import { logger } from "./logger.js";
+export class SchemaValidator {
+    constructor(schemaType = "openapi", validation) {
+        this.instanceId = Math.random().toString(36).substring(2, 8);
+        if (validation) {
+            logger.warn(`SchemaValidator instance ${this.instanceId}: Validation requested but using lite build. ` +
+                `Install the full @c7-digital/ledger package for runtime validation support.`);
+        }
+        this.schemaReady = Promise.resolve();
+    }
+    /**
+     * Validate an array of items against a schema (lite: pass-through)
+     */
+    async validateArraySchema(data, _itemSchemaName) {
+        await this.schemaReady;
+        return data;
+    }
+    /**
+     * Validate data against a schema and return typed result (lite: pass-through)
+     */
+    async validateSchema(data, _schemaName) {
+        await this.schemaReady;
+        return data;
+    }
+}

package/lib-lite/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 {};