@c7-digital/ledger 0.0.3 → 0.0.4

package/BUILD.md

@@ -1,4 +1,4 @@
-# Ledger Build
+# Ledger Build 
 
 A standalone, repeatable build system for generating TypeScript types from OpenAPI and AsyncAPI specifications with value.proto branding.
 
@@ -30,7 +30,7 @@ pnpm exec ledger-build --sdk-version=3.4.0    # Target specific SDK version
 ### Programmatic Usage
 
 ```typescript
-import { build } from "@c7-digital/ledger/scripts/build";
+import { build } from "@c7/ledger/scripts/build";
 
 await build();
 ```
@@ -89,7 +89,7 @@ To use this build system in other projects:
 1. **Install the package**:
 
    ```bash
-   pnpm install @c7-digital/ledger
+   pnpm install @c7/ledger
    ```
 
 2. **Add to package.json**:

package/README.md

@@ -1,4 +1,4 @@
-# @c7-digital/ledger
+# @c7/ledger
 
 OpenAPI v2 compatible Daml ledger client (that could replace `@daml/ledger`) for the new Canton JSON API v2.
 
@@ -27,7 +27,7 @@ This package follows the Canton SDK versioning scheme. The package version match
 ## Installation
 
 ```bash
-pnpm install @c7-digital/ledger
+pnpm install @c7/ledger
 ```
 
 Or build from source:
@@ -40,7 +40,7 @@ pnpm build
 ## Usage
 
 ```typescript
-import { Ledger } from "@c7-digital/ledger";
+import { Ledger } from "@c7/ledger";
 
 const ledger = new Ledger({
   token: "your-jwt-token",
@@ -54,9 +54,7 @@ const contracts = await ledger.query(MyTemplate);
 const result = await ledger.create(MyTemplate, payload, [actAsParty]);
 
 // Exercise choices
-const choiceResult = await ledger.exercise(MyChoice, contractId, argument, [
-  actAsParty,
-]);
+const choiceResult = await ledger.exercise(MyChoice, contractId, argument, [actAsParty]);
 ```
 
 ## Migration from @daml/ledger

package/lib/src/PackageIdEmitterMap.d.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from "eventemitter3";
+import { PackageIdString } from "./valueTypes.js";
+/**
+ * A specialized Map wrapper for package ID emitters that uses partiallyQualified
+ * IDs for comparison to ensure consistent lookup regardless of package ID.
+ * Can be used for both template IDs and interface IDs.
+ */
+export declare class PackageIdEmitterMap {
+    private emitters;
+    /**
+     * Set an EventEmitter for a specific package ID
+     * @param packageId The full package ID (template or interface)
+     * @param emitter The EventEmitter instance
+     */
+    set(packageId: PackageIdString, emitter: EventEmitter): void;
+    /**
+     * Get the EventEmitter for a specific package ID
+     * @param packageId The package ID (full or partial)
+     * @returns The EventEmitter or undefined if not found
+     */
+    get(packageId: PackageIdString): EventEmitter | undefined;
+    /**
+     * Check if an emitter exists for a specific package ID
+     * @param packageId The package ID (full or partial)
+     * @returns True if an emitter exists, false otherwise
+     */
+    has(packageId: PackageIdString): boolean;
+    /**
+     * Get all emitters in the map
+     * @returns An iterator of all EventEmitter instances
+     */
+    values(): IterableIterator<EventEmitter>;
+    /**
+     * Clear all emitters from the map
+     */
+    clear(): void;
+    /**
+     * Get the number of emitters in the map
+     */
+    get size(): number;
+}
+export declare const TemplateEmitterMap: typeof PackageIdEmitterMap;

package/lib/src/PackageIdEmitterMap.js

@@ -0,0 +1,60 @@
+import { partiallyQualified } from "./util.js";
+/**
+ * A specialized Map wrapper for package ID emitters that uses partiallyQualified
+ * IDs for comparison to ensure consistent lookup regardless of package ID.
+ * Can be used for both template IDs and interface IDs.
+ */
+export class PackageIdEmitterMap {
+    constructor() {
+        this.emitters = new Map();
+    }
+    /**
+     * Set an EventEmitter for a specific package ID
+     * @param packageId The full package ID (template or interface)
+     * @param emitter The EventEmitter instance
+     */
+    set(packageId, emitter) {
+        const partialId = partiallyQualified(packageId);
+        this.emitters.set(partialId, { fullId: packageId, emitter });
+    }
+    /**
+     * Get the EventEmitter for a specific package ID
+     * @param packageId The package ID (full or partial)
+     * @returns The EventEmitter or undefined if not found
+     */
+    get(packageId) {
+        const partialId = partiallyQualified(packageId);
+        return this.emitters.get(partialId)?.emitter;
+    }
+    /**
+     * Check if an emitter exists for a specific package ID
+     * @param packageId The package ID (full or partial)
+     * @returns True if an emitter exists, false otherwise
+     */
+    has(packageId) {
+        const partialId = partiallyQualified(packageId);
+        return this.emitters.has(partialId);
+    }
+    /**
+     * Get all emitters in the map
+     * @returns An iterator of all EventEmitter instances
+     */
+    values() {
+        return Array.from(this.emitters.values())
+            .map(entry => entry.emitter)[Symbol.iterator]();
+    }
+    /**
+     * Clear all emitters from the map
+     */
+    clear() {
+        this.emitters.clear();
+    }
+    /**
+     * Get the number of emitters in the map
+     */
+    get size() {
+        return this.emitters.size;
+    }
+}
+// Backward compatibility alias
+export const TemplateEmitterMap = PackageIdEmitterMap;

package/lib/src/generated/asyncapi-schema.js

@@ -1,5 +1,5 @@
 // Auto-generated file - do not edit manually
-// Generated from /Users/stefanpla/Development/c7/sandbox/publish_to_npm/c7_ledger/ledger/specs/asyncapi_3.4.7.yaml
+// Generated from /Users/stefanpla/Development/c7/sandbox/stream_interfaces/c7_ledger/ledger/specs/asyncapi_3.4.7.yaml
 export const ASYNCAPI_SCHEMA = `asyncapi: 2.6.0
 info:
   title: JSON Ledger API WebSocket endpoints

package/lib/src/generated/openapi-schema.js

@@ -1,5 +1,5 @@
 // Auto-generated file - do not edit manually
-// Generated from /Users/stefanpla/Development/c7/sandbox/publish_to_npm/c7_ledger/ledger/specs/openapi_3.4.7.yaml
+// Generated from /Users/stefanpla/Development/c7/sandbox/stream_interfaces/c7_ledger/ledger/specs/openapi_3.4.7.yaml
 export const OPENAPI_SCHEMA = `openapi: 3.0.3
 info:
   title: JSON Ledger API HTTP endpoints

package/lib/src/ledger.d.ts

@@ -16,8 +16,8 @@
  * Use this for most Daml application needs. Use TypedHttpClient directly when
  * you need access to Canton-specific endpoints or full control over API calls.
  */
-import { ContractId, Party, Choice, InterfaceCompanion, Template, TemplateOrInterface } from "@daml/types";
-import { AllocatePartyRequest, AllocatePartyResponse, Command, CreateCommand, CreateAndExerciseCommand, CreateEvent, ExerciseCommand, Event, Interface, LedgerOffset, Stream, PartyDetails, User, MultiStream, TemplateMapping, VersionedRegistry } from "./types.js";
+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 { 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>;
@@ -63,6 +63,11 @@ export interface LedgerOptions {
      * querying and decoding interfaces views.
      */
     versionedRegistry?: VersionedRegistry;
+    /**
+     * Whether to automatically reconnect WebSocket streams on abnormal close (1006).
+     * Defaults to true for backward compatibility.
+     */
+    autoReconnect?: boolean;
 }
 /**
  * Meant to be a simple replacement for Ledger from @daml/ledger
@@ -140,9 +145,12 @@ export declare class Ledger {
      * @param offset Optional offset to start streaming from
      * @param skipAcs Whether to skip archived contracts
      * @param includeCreatedEventBlob Whether to include created event blobs
-     * @returns A stream of events for the specified template
+     * @param readAsParties Array of parties to stream for, if not specified default to
+     *          the actAs parties of the user in the token.
+     * @returns A stream of events for the specified template or interface
      */
-    streamQuery<T extends object, K = unknown>(template: TemplateOrInterface<T, K>, offset?: LedgerOffset, skipAcs?: boolean, includeCreatedEventBlob?: boolean, readAsParties?: Party[]): Promise<Stream<T, K>>;
+    streamQuery<T extends object, K = unknown>(template: Template<T, K>, offset?: LedgerOffset, skipAcs?: boolean, includeCreatedEventBlob?: boolean, readAsParties?: Party[]): Promise<Stream<T, K>>;
+    streamQueryInterface<I extends object, K = unknown>(interface_: InterfaceCompanion<I, K>, offset?: LedgerOffset, skipAcs?: boolean, includeCreatedEventBlob?: boolean, readAsParties?: Party[]): Promise<InterfaceStream<I>>;
     /**
      * Create a type-safe MultiStream for working with multiple templates
      *
@@ -174,14 +182,16 @@ export declare class Ledger {
      * stream.start();
      * ```
      *
-     * @param templates Array of templates to stream
+     * @param tm Template mapping for the streams
      * @param offset Optional offset to start streaming from
+     * @param skipAcs Whether to skip loading the initial active contract set
      * @param includeCreatedEventBlob Whether to include created event blobs
      * @param readAsParties Array of parties to stream for, if not specified default to
      *          the actAs parties of the user in the token.
      * @returns A type-safe MultiStream for working with multiple templates
      */
     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>>;
     getUserInfo(userId: string): Promise<User | null>;
     getParties(): Promise<PartyDetails[]>;
     allocateParty(request: AllocatePartyRequest): Promise<AllocatePartyResponse>;

package/lib/src/ledger.js

@@ -17,12 +17,12 @@
  * you need access to Canton-specific endpoints or full control over API calls.
  */
 import { lookupTemplate, } from "@daml/types";
-import { decodeJwt } from "jose";
 import { EventEmitter } from "eventemitter3";
 import { logger } from "./logger.js";
+import { logTokenExpiration } from "./token.js";
 import { TypedHttpClient } from "./client.js";
 import { WebSocketClient, isTransaction, } from "./websocket.js";
-import { MultiStreamAdapter } from "./multistream.js";
+import { MultiStreamAdapter, InterfaceMultiStreamImpl } from "./multistream.js";
 import { matchesPartiallyQualified } from "./util.js";
 import * as translate from "./translate.js";
 import { createLedgerString, createPartyIdString, createNameString, createUserIdString, } from "./valueTypes.js";
@@ -30,6 +30,18 @@ import { createLedgerString, createPartyIdString, createNameString, createUserId
 function isCreateEvent(event) {
     return "CreatedEvent" in event;
 }
+function createEventWithoutDecoder(cantonEvent) {
+    return {
+        type: "create",
+        templateId: cantonEvent.templateId,
+        contractId: cantonEvent.contractId,
+        payload: cantonEvent.createArgument ?? {},
+        signatories: (cantonEvent.signatories || []),
+        observers: (cantonEvent.observers || []),
+        key: undefined,
+        createdEventBlob: cantonEvent.createdEventBlob || "",
+    };
+}
 // This term is so overloaded, lets add a '_' to help differentiate
 function createEvent_(cantonEvent, versionedRegistry) {
     let t;
@@ -76,8 +88,8 @@ function archiveEvent_(cantonEvent) {
         offset: cantonEvent.offset,
     };
 }
-// It is possible that we query for a given interview that we are interested in,
-// but the underlying contract has multiple interview implementations that we are NOT
+// It is possible that we query for a given interface that we are interested in,
+// but the underlying contract has multiple interface implementations that we are NOT
 // interested in, and consequently not registered in our versionedRegistry.
 // In this case we return null.
 function interfaceEvent_(cantonEvent, interfaceView, versionedRegistry) {
@@ -103,6 +115,7 @@ function interfaceEvent_(cantonEvent, interfaceView, versionedRegistry) {
         key: cantonEvent.contractKey,
         createdEventBlob: cantonEvent.createdEventBlob || "",
         interfaceView: decodedInterfaceView,
+        interfaceId: interfaceView.interfaceId,
         packageVersion,
     };
 }
@@ -192,12 +205,12 @@ class LedgerStream {
     /**
      * Creates a new stream for active contracts
      *
-     * @param template The template to stream contracts for
+     * @param filters The filters to stream contracts for - FilterSpec[]
      * @param parties The parties to stream contracts for
      * @param wsClient The WebSocket client to use
      * @param activeAtOffset Optional offset to start streaming from
      */
-    constructor(templateIds, parties, wsClient, startOffset, skipAcs = false, includeCreatedEventBlob = true, versionedRegistry) {
+    constructor(filters, parties, wsClient, startOffset, skipAcs = false, includeCreatedEventBlob = true, versionedRegistry, autoReconnect = false) {
         this.eventEmitter = new EventEmitter();
         this.state_ = "start";
         this.parties = parties;
@@ -205,9 +218,12 @@ class LedgerStream {
         this.offset = startOffset;
         this.skipAcs = skipAcs;
         this.versionedRegistry = versionedRegistry;
-        let cumulative = templateIds.map(templateId => {
+        this.autoReconnect = autoReconnect;
+        let cumulative = filters.map(filter => {
             return {
-                identifierFilter: templateFilter(templateId, includeCreatedEventBlob),
+                identifierFilter: filter.type === "template"
+                    ? templateFilter(filter.templateId, includeCreatedEventBlob)
+                    : interfaceFilter(filter.interfaceId, includeCreatedEventBlob),
             };
         });
         this.filtersByParty = this.parties.reduce((acc, party) => {
@@ -232,6 +248,12 @@ class LedgerStream {
         // Start streaming and store the stop function
         this.stopClient = this.wsClient.streamActiveContracts(request, response => this.handleActiveContractsResponse(response), error => this.handleError(error), (code, reason) => this.handleActiveContractsClose(code, reason));
     }
+    handleCreatedEvent(createdEvent) {
+        this.eventEmitter.emit("create", createEvent_(createdEvent, this.versionedRegistry));
+    }
+    handleArchivedEvent(archivedEvent) {
+        this.eventEmitter.emit("archive", archiveEvent_(archivedEvent));
+    }
     /**
      * Handle responses from the active contracts stream
      */
@@ -251,7 +273,7 @@ class LedgerStream {
                 logger.warn(`While receiving ACS, updating offset from ${this.offset} to ${activeContract.createdEvent.offset}`);
                 this.offset = activeContract.createdEvent.offset;
             }
-            this.eventEmitter.emit("create", createEvent_(activeContract.createdEvent, this.versionedRegistry));
+            this.handleCreatedEvent(activeContract.createdEvent);
         }
     }
     /**
@@ -308,11 +330,11 @@ class LedgerStream {
             for (const event of jsTransaction.events || []) {
                 if ("CreatedEvent" in event) {
                     this.offset = Math.max(this.offset, event.CreatedEvent.offset);
-                    this.eventEmitter.emit("create", createEvent_(event.CreatedEvent, this.versionedRegistry));
+                    this.handleCreatedEvent(event.CreatedEvent);
                 }
                 else if ("ArchivedEvent" in event) {
                     this.offset = Math.max(this.offset, event.ArchivedEvent.offset);
-                    this.eventEmitter.emit("archive", archiveEvent_(event.ArchivedEvent));
+                    this.handleArchivedEvent(event.ArchivedEvent);
                 }
                 else {
                     logger.warn(`Unexpected event type in transaction stream: ${JSON.stringify(event)}`);
@@ -333,17 +355,22 @@ class LedgerStream {
         // Emit close event
         const closeEvent = { code, reason };
         this.eventEmitter.emit("close", closeEvent);
-        // Auto-reconnect on abnormal close (1006) if stream is still active
-        if (code === 1006 && this.state_ === "live") {
+        // Auto-reconnect on abnormal close (1006) if stream is still active and auto-reconnect is enabled
+        if (code === 1006 && this.state_ === "live" && this.autoReconnect) {
             logger.log(`WebSocket closed abnormally (1006), reconnecting in 3 seconds...`);
             setTimeout(() => {
                 if (this.state_ === "live") {
                     // Double-check we're still active
                     logger.log(`Attempting to reconnect stream...`);
+                    // Log token expiration info before reconnection attempt
+                    logTokenExpiration(this.wsClient.getToken(), "WebSocket reconnection attempt");
                     this.startUpdatesStream();
                 }
             }, 3000);
         }
+        else if (code === 1006 && this.state_ === "live" && !this.autoReconnect) {
+            logger.log(`WebSocket closed abnormally (1006), but auto-reconnect is disabled`);
+        }
     }
     // This is a websocket error, not a Canton error
     handleError(error) {
@@ -400,6 +427,65 @@ class LedgerStream {
         // Clean up event listeners
         this.eventEmitter.removeAllListeners();
     }
+    /**
+     * Update the authentication token and restart the stream
+     */
+    updateToken(newToken) {
+        logger.debug(`🔄 Stream token update requested for state: ${this.state_}`);
+        logTokenExpiration(newToken, "Stream updateToken()");
+        // Update the token in the WebSocket client
+        this.wsClient.setToken(newToken);
+        logger.debug("WebSocket client token updated");
+        // Handle token update based on current stream state
+        switch (this.state_) {
+            case "live":
+                logger.debug(`Restarting live stream with new token`);
+                // Close current connection
+                if (this.stopClient) {
+                    this.stopClient();
+                    this.stopClient = undefined;
+                }
+                // Restart the updates stream with the new token
+                this.startUpdatesStream();
+                break;
+            case "init":
+                logger.debug(`Stream is in init state, will use new token when transitioning to live`);
+                // Stream is still in ACS phase, new token will be used when it transitions to updates
+                break;
+            case "start":
+                logger.debug(`Stream is in start state, token updated but no restart needed`);
+                break;
+            case "stop":
+                logger.debug(`Stream is stopped, token updated but no restart needed`);
+                break;
+            default:
+                // TypeScript exhaustiveness check
+                const _exhaustive = this.state_;
+                throw new Error(`Unknown stream state: ${_exhaustive}`);
+        }
+    }
+}
+class InterfaceStreamImpl extends LedgerStream {
+    constructor(filters, parties, wsClient, startOffset, 
+    // Required for interface streams
+    versionedRegistry, skipAcs = false, includeCreatedEventBlob = true, autoReconnect = false) {
+        super(filters, parties, wsClient, startOffset, skipAcs, includeCreatedEventBlob, versionedRegistry, autoReconnect);
+    }
+    on(type, listener) {
+        this.eventEmitter.on(type, listener);
+    }
+    off(type, listener) {
+        this.eventEmitter.off(type, listener);
+    }
+    handleCreatedEvent(createdEvent) {
+        this.eventEmitter.emit("create", createEventWithoutDecoder(createdEvent));
+        for (const interfaceView of createdEvent.interfaceViews ?? []) {
+            this.eventEmitter.emit("interfaceView", interfaceEvent_(createdEvent, interfaceView, this.versionedRegistry));
+        }
+    }
+    handleArchivedEvent(archivedEvent) {
+        this.eventEmitter.emit("archive", archiveEvent_(archivedEvent));
+    }
 }
 /**
  * Meant to be a simple replacement for Ledger from @daml/ledger
@@ -408,12 +494,9 @@ export class Ledger {
     constructor(options) {
         this.tokenUserInfo = null;
         this.httpBaseUrl = options.httpBaseUrl;
-        const payload = decodeJwt(options.token);
-        logger.debug(`Token payload: ${JSON.stringify(payload)}`);
-        if (payload.sub === undefined) {
-            throw new Error(`Token payload missing 'sub' field`);
-        }
-        this.tokenUserId = payload.sub;
+        // Log token expiration info during ledger initialization
+        const tokenInfo = logTokenExpiration(options.token, `Ledger initialization`);
+        this.tokenUserId = tokenInfo.userId;
         this.client = new TypedHttpClient({
             token: options.token,
             baseUrl: this.httpBaseUrl,
@@ -745,12 +828,22 @@ export class Ledger {
      * @param offset Optional offset to start streaming from
      * @param skipAcs Whether to skip archived contracts
      * @param includeCreatedEventBlob Whether to include created event blobs
-     * @returns A stream of events for the specified template
+     * @param readAsParties Array of parties to stream for, if not specified default to
+     *          the actAs parties of the user in the token.
+     * @returns A stream of events for the specified template or interface
      */
     async streamQuery(template, offset = "end", skipAcs = false, includeCreatedEventBlob = false, readAsParties) {
         const activeAtOffset = await this.resolveOffset(offset);
         const parties_ = readAsParties || (await this.getTokenActAsParties());
-        return new LedgerStream([template.templateId], parties_, this.initClient(), activeAtOffset, skipAcs, includeCreatedEventBlob, this.options.versionedRegistry);
+        return new LedgerStream([{ type: "template", templateId: template.templateId }], parties_, this.initClient(), activeAtOffset, skipAcs, includeCreatedEventBlob, this.options.versionedRegistry, this.options.autoReconnect ?? true);
+    }
+    async streamQueryInterface(interface_, offset = "end", skipAcs = false, includeCreatedEventBlob = false, readAsParties) {
+        const activeAtOffset = await this.resolveOffset(offset);
+        const parties_ = readAsParties || (await this.getTokenActAsParties());
+        if (!this.options.versionedRegistry) {
+            throw new Error("VersionedRegistry expected for streamQueryInterface provided");
+        }
+        return new InterfaceStreamImpl([{ type: "interface", interfaceId: interface_.templateId }], parties_, this.initClient(), activeAtOffset, this.options.versionedRegistry, skipAcs, includeCreatedEventBlob, this.options.autoReconnect ?? true);
     }
     /**
      * Create a type-safe MultiStream for working with multiple templates
@@ -783,8 +876,9 @@ export class Ledger {
      * stream.start();
      * ```
      *
-     * @param templates Array of templates to stream
+     * @param tm Template mapping for the streams
      * @param offset Optional offset to start streaming from
+     * @param skipAcs Whether to skip loading the initial active contract set
      * @param includeCreatedEventBlob Whether to include created event blobs
      * @param readAsParties Array of parties to stream for, if not specified default to
      *          the actAs parties of the user in the token.
@@ -792,11 +886,25 @@ export class Ledger {
      */
     async createMultiStream(tm, offset = "end", skipAcs = false, includeCreatedEventBlob = false, readAsParties) {
         const activeAtOffset = await this.resolveOffset(offset);
-        const templateIds = Object.keys(tm);
+        const filters = Object.keys(tm).map((id) => {
+            return { type: 'template', templateId: id };
+        });
         const parties_ = readAsParties || (await this.getTokenActAsParties());
-        const stream = new LedgerStream(templateIds, parties_, this.initClient(), activeAtOffset, skipAcs, includeCreatedEventBlob, this.options.versionedRegistry);
+        const stream = new LedgerStream(filters, parties_, this.initClient(), activeAtOffset, skipAcs, includeCreatedEventBlob, this.options.versionedRegistry, this.options.autoReconnect ?? true);
         return new MultiStreamAdapter(stream);
     }
+    async createMultiInterfaceStream(im, offset = "end", skipAcs = false, includeCreatedEventBlob = false, readAsParties) {
+        const activeAtOffset = await this.resolveOffset(offset);
+        const filters = Object.keys(im).map((id) => {
+            return { type: 'interface', interfaceId: id };
+        });
+        const parties_ = readAsParties || (await this.getTokenActAsParties());
+        if (!this.options.versionedRegistry) {
+            throw new Error("VersionedRegistry expected for createMultiInterfaceStream");
+        }
+        const stream = new InterfaceStreamImpl(filters, parties_, this.initClient(), activeAtOffset, this.options.versionedRegistry, skipAcs, includeCreatedEventBlob, this.options.autoReconnect ?? true);
+        return new InterfaceMultiStreamImpl(stream);
+    }
     // User information
     async getUserInfo(userId) {
         const response = await this.client.getUserInfo(userId);

package/lib/src/multistream.d.ts

@@ -1,11 +1,14 @@
-import { ArchiveEvent, CantonError, CreateEvent, MultiStream, Stream, StreamState, TemplateMapping } from "./types.js";
+import { EventEmitter } from "eventemitter3";
+import { ArchiveEvent, CantonError, CreateEvent, Interface, InterfaceMapping, InterfaceMultiStream, InterfaceStream, MultiStream, Stream, StreamState, TemplateMapping } from "./types.js";
+import { PackageIdString } from "./valueTypes.js";
+import { PackageIdEmitterMap } from "./PackageIdEmitterMap.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;
+    protected stream: Stream<object, unknown>;
+    protected packageIdEmitters: PackageIdEmitterMap;
     private errorEmitter;
     private stateEmitter;
     /**
@@ -14,17 +17,17 @@ export declare class MultiStreamAdapter<TM extends TemplateMapping> implements M
      */
     constructor(stream: Stream<object, unknown>);
     /**
-     * Get or create an EventEmitter for a specific template
+     * Get or create an EventEmitter for a specific package ID
      */
-    private getEmitterForTemplate;
+    protected getEmitterForPackageId(packageId: PackageIdString): EventEmitter;
     /**
      * Handle create events from the underlying stream
-     * and route them to the appropriate template emitter
+     * and route them to the appropriate package ID emitter
      */
     private handleCreateEvent;
     /**
      * Handle archive events from the underlying stream
-     * and route them to the appropriate template emitter
+     * and route them to the appropriate package ID emitter
      */
     private handleArchiveEvent;
     /**
@@ -44,4 +47,28 @@ export declare class MultiStreamAdapter<TM extends TemplateMapping> implements M
     start(): void;
     state(): StreamState;
     close(): void;
+    updateToken(newToken: string): void;
+}
+/**
+ * Extends MultiStreamAdapter to add interface-specific event handling
+ * Provides both template-specific and interface-specific event handlers with proper typing
+ */
+export declare class InterfaceMultiStreamImpl<IM extends InterfaceMapping> extends MultiStreamAdapter<{
+    [K in keyof IM]: {
+        contractType: object;
+        keyType: unknown;
+    };
+}> implements InterfaceMultiStream<IM> {
+    private interfaceStream;
+    /**
+     * Create a new InterfaceMultiStream adapter
+     * @param stream The underlying InterfaceStream instance
+     */
+    constructor(stream: InterfaceStream<object>);
+    /**
+     * Handle interfaceView events from the underlying stream
+     */
+    private handleInterfaceViewEvent;
+    onInterfaceView<IID extends keyof IM>(interfaceId: IID, listener: (event: Interface<IM[IID]["contractType"]>) => void): void;
+    offInterfaceView<IID extends keyof IM>(interfaceId: IID, listener: (event: Interface<IM[IID]["contractType"]>) => void): void;
 }