@c7-digital/ledger 0.0.3 → 0.0.4

package/lib/src/multistream.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from "eventemitter3";
 import { logger } from "./logger.js";
-import { TemplateEmitterMap } from "./TemplateEmitterMap.js";
+import { PackageIdEmitterMap, } from "./PackageIdEmitterMap.js";
 /**
  * Adapts a Stream instance to the MultiStream interface
  * Provides template-specific event handlers with proper typing
@@ -11,7 +11,7 @@ export class MultiStreamAdapter {
      * @param stream The underlying Stream instance
      */
     constructor(stream) {
-        this.templateEmitters = new TemplateEmitterMap();
+        this.packageIdEmitters = new PackageIdEmitterMap();
         this.errorEmitter = new EventEmitter(); // Dedicated error emitter
         this.stateEmitter = new EventEmitter(); // Dedicated state emitter
         this.stream = stream;
@@ -22,38 +22,38 @@ export class MultiStreamAdapter {
         this.stream.on("state", this.handleStateEvent.bind(this));
     }
     /**
-     * Get or create an EventEmitter for a specific template
+     * Get or create an EventEmitter for a specific package ID
      */
-    getEmitterForTemplate(templateId) {
-        if (!this.templateEmitters.has(templateId)) {
-            this.templateEmitters.set(templateId, new EventEmitter());
+    getEmitterForPackageId(packageId) {
+        if (!this.packageIdEmitters.has(packageId)) {
+            this.packageIdEmitters.set(packageId, new EventEmitter());
         }
-        return this.templateEmitters.get(templateId);
+        return this.packageIdEmitters.get(packageId);
     }
     /**
      * Handle create events from the underlying stream
-     * and route them to the appropriate template emitter
+     * and route them to the appropriate package ID emitter
      */
     handleCreateEvent(event) {
-        const templateId = event.templateId;
-        if (this.templateEmitters.has(templateId)) {
-            this.templateEmitters.get(templateId).emit("create", event);
+        const packageId = event.templateId;
+        if (this.packageIdEmitters.has(packageId)) {
+            this.packageIdEmitters.get(packageId).emit("create", event);
         }
         else {
-            logger.warn(`Received create event for unknown template ${templateId}`);
+            logger.warn(`Received create event for unknown template ${packageId}`);
         }
     }
     /**
      * Handle archive events from the underlying stream
-     * and route them to the appropriate template emitter
+     * and route them to the appropriate package ID emitter
      */
     handleArchiveEvent(event) {
-        const templateId = event.templateId;
-        if (this.templateEmitters.has(templateId)) {
-            this.templateEmitters.get(templateId).emit("archive", event);
+        const packageId = event.templateId;
+        if (this.packageIdEmitters.has(packageId)) {
+            this.packageIdEmitters.get(packageId).emit("archive", event);
         }
         else {
-            logger.warn(`Received archive event for unknown template ${templateId}`);
+            logger.warn(`Received archive event for unknown template ${packageId}`);
         }
     }
     /**
@@ -69,14 +69,14 @@ export class MultiStreamAdapter {
     }
     // MultiStream interface implementation
     onCreate(templateId, listener) {
-        const emitter = this.getEmitterForTemplate(templateId);
+        const emitter = this.getEmitterForPackageId(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);
+        const emitter = this.getEmitterForPackageId(templateId);
         emitter.on("archive", (event) => {
             // Type assertion: we know the event has the correct type based on templateId
             listener(event);
@@ -89,13 +89,13 @@ export class MultiStreamAdapter {
         this.stream.on("state", listener);
     }
     offCreate(templateId, listener) {
-        if (this.templateEmitters.has(templateId)) {
-            this.templateEmitters.get(templateId).off("create", listener);
+        if (this.packageIdEmitters.has(templateId)) {
+            this.packageIdEmitters.get(templateId).off("create", listener);
         }
     }
     offArchive(templateId, listener) {
-        if (this.templateEmitters.has(templateId)) {
-            this.templateEmitters.get(templateId).off("archive", listener);
+        if (this.packageIdEmitters.has(templateId)) {
+            this.packageIdEmitters.get(templateId).off("archive", listener);
         }
     }
     offError(listener) {
@@ -112,12 +112,56 @@ export class MultiStreamAdapter {
     }
     close() {
         this.stream.close();
-        for (const emitter of this.templateEmitters.values()) {
+        for (const emitter of this.packageIdEmitters.values()) {
             emitter.removeAllListeners();
         }
-        this.templateEmitters.clear();
+        this.packageIdEmitters.clear();
         // Clean up the error emitter too
         this.errorEmitter.removeAllListeners();
         this.stateEmitter.removeAllListeners();
     }
+    updateToken(newToken) {
+        this.stream.updateToken(newToken);
+    }
+}
+/**
+ * Extends MultiStreamAdapter to add interface-specific event handling
+ * Provides both template-specific and interface-specific event handlers with proper typing
+ */
+export class InterfaceMultiStreamImpl extends MultiStreamAdapter {
+    /**
+     * Create a new InterfaceMultiStream adapter
+     * @param stream The underlying InterfaceStream instance
+     */
+    constructor(stream) {
+        // Pass the stream to the parent MultiStreamAdapter
+        super(stream);
+        this.interfaceStream = stream;
+        // Set up interface-specific event listener
+        this.interfaceStream.on("interfaceView", this.handleInterfaceViewEvent.bind(this));
+    }
+    /**
+     * Handle interfaceView events from the underlying stream
+     */
+    handleInterfaceViewEvent(event) {
+        const interfaceId = event.interfaceId;
+        if (this.packageIdEmitters.has(interfaceId)) {
+            this.packageIdEmitters.get(interfaceId).emit("interfaceView", event);
+        }
+        else {
+            logger.warn(`Received interfaceView event for unknown interface ${interfaceId}`);
+        }
+    }
+    // InterfaceMultiStreamMethods implementation
+    onInterfaceView(interfaceId, listener) {
+        const emitter = this.getEmitterForPackageId(interfaceId);
+        emitter.on("interfaceView", (event) => {
+            listener(event);
+        });
+    }
+    offInterfaceView(interfaceId, listener) {
+        if (this.packageIdEmitters.has(interfaceId)) {
+            this.packageIdEmitters.get(interfaceId).off("interfaceView", listener);
+        }
+    }
 }

package/lib/src/token.d.ts

@@ -0,0 +1,13 @@
+export interface TokenInfo {
+    userId: string;
+    expiresAt: number;
+    issuedAt: number;
+    isExpired: boolean;
+    timeUntilExpiry: number;
+}
+/**
+ * Log token expiration information
+ * @param token The JWT token string
+ * @param context Additional context for logging (e.g., "connection", "reconnection")
+ */
+export declare function logTokenExpiration(token: string, context?: string): TokenInfo;

package/lib/src/token.js

@@ -0,0 +1,64 @@
+/**
+ * JWT token utilities for Canton ledger authentication
+ */
+import { decodeJwt } from "jose";
+import { logger } from "./logger.js";
+/**
+ * Decode and analyze a JWT token
+ * @param token The JWT token string
+ * @returns Token information including expiration details
+ */
+function analyzeToken(token) {
+    const payload = decodeJwt(token);
+    if (!payload.sub) {
+        throw new Error("Token payload missing 'sub' field");
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const expiresAt = payload.exp || 0;
+    const issuedAt = payload.iat || 0;
+    const isExpired = expiresAt > 0 && expiresAt <= now;
+    const timeUntilExpiry = expiresAt > 0 ? expiresAt - now : 0;
+    return {
+        userId: payload.sub,
+        expiresAt,
+        issuedAt,
+        isExpired,
+        timeUntilExpiry,
+    };
+}
+/**
+ * Log token expiration information
+ * @param token The JWT token string
+ * @param context Additional context for logging (e.g., "connection", "reconnection")
+ */
+export function logTokenExpiration(token, context = "token") {
+    try {
+        const tokenInfo = analyzeToken(token);
+        if (tokenInfo.isExpired) {
+            logger.warn(`${context}: Token is EXPIRED`, {
+                expiresAt: new Date(tokenInfo.expiresAt * 1000).toISOString(),
+                expiredSecondsAgo: Math.abs(tokenInfo.timeUntilExpiry),
+                userId: tokenInfo.userId,
+            });
+        }
+        else if (tokenInfo.timeUntilExpiry < 300) { // Less than 5 minutes
+            logger.warn(`${context}: Token expires soon`, {
+                expiresAt: new Date(tokenInfo.expiresAt * 1000).toISOString(),
+                secondsUntilExpiry: tokenInfo.timeUntilExpiry,
+                userId: tokenInfo.userId,
+            });
+        }
+        else {
+            logger.debug(`${context}: Token is valid`, {
+                expiresAt: new Date(tokenInfo.expiresAt * 1000).toISOString(),
+                secondsUntilExpiry: tokenInfo.timeUntilExpiry,
+                userId: tokenInfo.userId,
+            });
+        }
+        return tokenInfo;
+    }
+    catch (error) {
+        logger.error(`${context}: Failed to analyze token`, { error: error instanceof Error ? error.message : String(error) });
+        return { userId: "", expiresAt: 0, issuedAt: 0, isExpired: true, timeUntilExpiry: 0 };
+    }
+}

package/lib/src/types.d.ts

@@ -43,6 +43,7 @@ export type Interface<I extends object> = {
     key?: any;
     createdEventBlob: string;
     interfaceView: I;
+    interfaceId: PackageIdString;
     /**
      * Package version string (e.g., "0.0.6")
      * Only present if using VersionedRegistry
@@ -67,7 +68,7 @@ export type VersionedLookupResult = {
  *
  * 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.
+ * interface we really mean the interfaceId as in the OpenAPI spec.
  */
 export type VersionedRegistry = (templateId: string) => VersionedLookupResult | undefined;
 export type LedgerOffset = "start" | "end" | number;
@@ -78,7 +79,7 @@ export interface StreamCloseEvent {
 }
 export type StreamState = "start" | "init" | "live" | "stop";
 /**
- * The return interface of streamQuery and streamQueries.
+ * The return interface of streamTemplate - for template-specific streaming with known types.
  */
 export interface Stream<T extends object, K> {
     on(type: "create", listener: (event: CreateEvent<T, K>) => void): void;
@@ -92,7 +93,24 @@ export interface Stream<T extends object, K> {
     start(): void;
     state(): StreamState;
     close(): void;
+    updateToken(newToken: string): void;
 }
+/**
+ * Additional interface-specific methods for interface streaming.
+ */
+export interface InterfaceStreamMethods<I extends object> {
+    on(type: "interfaceView", listener: (event: Interface<I>) => void): void;
+    off(type: "interfaceView", listener: (event: Interface<I>) => void): void;
+}
+/**
+ * The return interface of streamInterface - combines Stream with interface-specific events.
+ *
+ * Most of the time, if you are subscribing to an interface, the underlying
+ * template is operationally not interesting to you (otherwise, you would be
+ * subscribing to the template directly). Consequently we will emit the
+ * template related events but not make an effort to decode them.
+ */
+export type InterfaceStream<I extends object> = Stream<object, unknown> & InterfaceStreamMethods<I>;
 /**
  * Template mapping type for MultiStream:
  * template IDs to their corresponding contract and key types
@@ -101,6 +119,30 @@ export type TemplateMapping = Record<string, {
     contractType: object;
     keyType: unknown;
 }>;
+/**
+ * Interface mapping type for InterfaceMultiStream:
+ * interface IDs to their corresponding contract types
+ */
+export type InterfaceMapping = Record<string, {
+    contractType: object;
+}>;
+/**
+ * Interface-specific methods for MultiStream
+ */
+export interface InterfaceMultiStreamMethods<IM extends InterfaceMapping> {
+    /**
+     * Register a listener for interfaceView events for a specific interface
+     * @param interfaceId The interface ID to listen for
+     * @param listener The callback function that will receive properly typed interface events
+     */
+    onInterfaceView<IID extends keyof IM>(interfaceId: IID, listener: (event: Interface<IM[IID]["contractType"]>) => void): void;
+    /**
+     * Remove an interfaceView event listener for a specific interface
+     * @param interfaceId The interface ID to stop listening for
+     * @param listener The callback function to remove
+     */
+    offInterfaceView<IID extends keyof IM>(interfaceId: IID, listener: (event: Interface<IM[IID]["contractType"]>) => void): void;
+}
 /**
  * Provides template-specific event handlers.
  */
@@ -144,7 +186,24 @@ export interface MultiStream<TM extends TemplateMapping> {
     start(): void;
     state(): StreamState;
     close(): void;
+    updateToken(newToken: string): void;
 }
+/**
+ * Derives a TemplateMapping from an InterfaceMapping
+ * Templates underlying interfaces have generic object contractType and unknown keyType
+ */
+type DerivedTemplateMapping<IM extends InterfaceMapping> = {
+    [K in keyof IM]: {
+        contractType: object;
+        keyType: unknown;
+    };
+};
+/**
+ * Extended MultiStream interface that includes interface-specific event handlers
+ * Similar to how InterfaceStream extends Stream
+ * Derives the template mapping from the interface mapping since interfaces are implemented for templates
+ */
+export type InterfaceMultiStream<IM extends InterfaceMapping> = MultiStream<DerivedTemplateMapping<IM>> & InterfaceMultiStreamMethods<IM>;
 export interface Query<T = unknown> {
     [key: string]: unknown;
 }
@@ -199,3 +258,4 @@ export interface User {
     primaryParty?: Party;
     rights: UserRight[];
 }
+export {};

package/lib/src/websocket.d.ts

@@ -47,6 +47,15 @@ export declare class WebSocketClient {
     private wsBaseUrl;
     private validator?;
     constructor(config: StreamConfig);
+    /**
+     * Get the current token (for logging and validation purposes)
+     */
+    getToken(): string;
+    /**
+     * Update the token used for authentication
+     * Note: This only updates the stored token. Active connections need to be recreated.
+     */
+    setToken(newToken: string): void;
     /**
      * Generic streaming method with full type safety
      * This method enforces that request/response types match the endpoint

package/lib/src/websocket.js

@@ -1,5 +1,6 @@
 import { SchemaValidator } from "./validation.js";
 import { logger } from "./logger.js";
+import { logTokenExpiration } from "./token.js";
 import WebSocket from "isomorphic-ws";
 // Constant mapping from endpoints to their JSON Schema validation paths
 const SCHEMA_MAP = {
@@ -54,6 +55,19 @@ export class WebSocketClient {
             ? new SchemaValidator("asyncapi", config.validation)
             : undefined;
     }
+    /**
+     * Get the current token (for logging and validation purposes)
+     */
+    getToken() {
+        return this.token;
+    }
+    /**
+     * Update the token used for authentication
+     * Note: This only updates the stored token. Active connections need to be recreated.
+     */
+    setToken(newToken) {
+        this.token = newToken;
+    }
     /**
      * Generic streaming method with full type safety
      * This method enforces that request/response types match the endpoint
@@ -99,6 +113,8 @@ export class WebSocketClient {
         const url = endpoint.startsWith("/")
             ? `${baseUrl}${endpoint.slice(1)}`
             : `${baseUrl}/${endpoint}`;
+        // Log token expiration info before connecting
+        logTokenExpiration(this.token, `WebSocket connection to ${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}`);