@novasamatech/host-api 0.7.9-5 → 0.7.9

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export type { ConnectionStatus, HostApiMethod, Logger, RequestHandler, Subscription, SubscriptionHandler, Transport, } from './types.js';
+export type { ConnectionStatus, DebugMessageEvent, HostApiMethod, Logger, RequestHandler, Subscription, SubscriptionHandler, Transport, } from './types.js';
+export type { MessagePayloadSchema } from './protocol/messageCodec.js';
 export type { Provider } from './provider.js';
 export { createRequestId } from './helpers.js';
 export type { HostApi } from './hostApi.js';

package/dist/transport.js

@@ -79,6 +79,27 @@ export function createTransport(provider) {
     const messageProvider = createMessageProvider(provider);
     // subscriptions management (multiplexing)
     const activeSubscriptions = new Map();
+    // Lazy provider subscription — zero per-message decode cost while no
+    // debug listener is attached.
+    let debugListenerCount = 0;
+    let debugProviderUnsubscribe = null;
+    function ensureDebugProviderSubscription() {
+        if (debugProviderUnsubscribe)
+            return;
+        debugProviderUnsubscribe = messageProvider.subscribe(message => {
+            events.emit('debugMessage', {
+                direction: 'incoming',
+                requestId: message.requestId,
+                payload: message.payload,
+            });
+        });
+    }
+    function maybeDisposeDebugProviderSubscription() {
+        if (debugListenerCount > 0)
+            return;
+        debugProviderUnsubscribe?.();
+        debugProviderUnsubscribe = null;
+    }
     const transport = {
         provider,
         isCorrectEnvironment() {
@@ -288,6 +309,9 @@ export function createTransport(provider) {
         },
         postMessage(requestId, payload) {
             checks();
+            if (debugListenerCount > 0) {
+                events.emit('debugMessage', { direction: 'outgoing', requestId, payload });
+            }
             messageProvider.postMessage({ requestId, payload });
         },
         listenMessages(action, callback, onError) {
@@ -311,12 +335,44 @@ export function createTransport(provider) {
         },
         destroy() {
             disposed = true;
+            debugProviderUnsubscribe?.();
+            debugProviderUnsubscribe = null;
+            debugListenerCount = 0;
             provider.dispose();
             changeConnectionStatus('disconnected');
             events.emit('destroy');
             events.events = {};
             handshakeAbortController.abort('Transport disposed');
         },
+        onDebugMessage(callback) {
+            debugListenerCount++;
+            ensureDebugProviderSubscription();
+            // Wrap each listener individually: nanoevents iterates listeners
+            // synchronously and a throw aborts the loop, so without per-listener
+            // isolation a single broken listener could starve siblings *and*
+            // (on the incoming side) starve unrelated messageProvider subscribers.
+            // Route to console.error (not provider.logger.error) so debug-callback
+            // bugs stay distinct from real protocol errors — matches the same
+            // policy used by host-papp's debugBus.
+            const safeCallback = (event) => {
+                try {
+                    callback(event);
+                }
+                catch (e) {
+                    console.error('debug listener threw', e);
+                }
+            };
+            const unsubscribe = events.on('debugMessage', safeCallback);
+            let disposed = false;
+            return () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                unsubscribe();
+                debugListenerCount--;
+                maybeDisposeDebugProviderSubscription();
+            };
+        },
     };
     if (provider.isCorrectEnvironment()) {
         transport.handleRequest('host_handshake', async (version) => {

package/dist/transport.spec.js

@@ -1,5 +1,7 @@
+import { enumValue } from '@novasamatech/scale';
 import { createNanoEvents } from 'nanoevents';
 import { describe, expect, it, vi } from 'vitest';
+import { JAM_CODEC_PROTOCOL_ID } from './constants.js';
 import { createDefaultLogger } from './logger.js';
 import { createTransport } from './transport.js';
 function createProviders() {
@@ -18,6 +20,7 @@ function createProviders() {
         sdk: createProvider('toSdk', 'toHost'),
     };
 }
+const samplePayload = () => enumValue('host_handshake_request', enumValue('v1', JAM_CODEC_PROTOCOL_ID));
 describe('transport', () => {
     describe('subscription', () => {
         it('should multiplex subscriptions', () => {
@@ -55,4 +58,118 @@ describe('transport', () => {
             expect(s2Handler).toHaveBeenCalledTimes(2);
         });
     });
+    describe('debug hook', () => {
+        it('emits outgoing events when postMessage is called and still delivers the message', () => {
+            const providers = createProviders();
+            const host = createTransport(providers.host);
+            const sdk = createTransport(providers.sdk);
+            const debugListener = vi.fn();
+            host.onDebugMessage(debugListener);
+            const sdkReceived = vi.fn();
+            sdk.listenMessages('host_handshake_request', sdkReceived);
+            const requestId = 'req-1';
+            const payload = samplePayload();
+            host.postMessage(requestId, payload);
+            expect(debugListener).toHaveBeenCalledTimes(1);
+            expect(debugListener).toHaveBeenCalledWith(expect.objectContaining({ direction: 'outgoing', requestId, payload }));
+            expect(sdkReceived).toHaveBeenCalledTimes(1);
+            expect(sdkReceived).toHaveBeenCalledWith(requestId, expect.objectContaining({ tag: 'host_handshake_request' }));
+        });
+        it('emits incoming events with decoded payload', () => {
+            const providers = createProviders();
+            const host = createTransport(providers.host);
+            const sdk = createTransport(providers.sdk);
+            const debugListener = vi.fn();
+            host.onDebugMessage(debugListener);
+            const requestId = 'req-2';
+            const payload = samplePayload();
+            sdk.postMessage(requestId, payload);
+            // host receives sdk's message, plus host's own outgoing handshake
+            // attempts (none yet, since isReady() wasn't called). Filter to incoming.
+            const incoming = debugListener.mock.calls.map(([event]) => event).filter(e => e.direction === 'incoming');
+            expect(incoming).toHaveLength(1);
+            expect(incoming[0]).toEqual(expect.objectContaining({
+                direction: 'incoming',
+                requestId,
+                payload: expect.objectContaining({ tag: 'host_handshake_request' }),
+            }));
+        });
+        it('supports multiple listeners and stops after unsubscribe', () => {
+            const providers = createProviders();
+            const host = createTransport(providers.host);
+            const a = vi.fn();
+            const b = vi.fn();
+            const unsubscribeA = host.onDebugMessage(a);
+            host.onDebugMessage(b);
+            host.postMessage('req-a', samplePayload());
+            expect(a).toHaveBeenCalledTimes(1);
+            expect(b).toHaveBeenCalledTimes(1);
+            unsubscribeA();
+            // calling unsubscribe twice must be a no-op
+            unsubscribeA();
+            host.postMessage('req-b', samplePayload());
+            expect(a).toHaveBeenCalledTimes(1);
+            expect(b).toHaveBeenCalledTimes(2);
+        });
+        it('survives a throwing listener without breaking delivery', () => {
+            const providers = createProviders();
+            const host = createTransport(providers.host);
+            const sdk = createTransport(providers.sdk);
+            // Swap console.error directly so the expected throws don't pollute test
+            // output. Transport routes debug-callback failures to console.error (not
+            // provider.logger) so they stay distinct from real protocol errors.
+            const originalConsoleError = console.error;
+            const errorSpy = vi.fn();
+            console.error = errorSpy;
+            try {
+                host.onDebugMessage(() => {
+                    throw new Error('listener boom');
+                });
+                const goodListener = vi.fn();
+                host.onDebugMessage(goodListener);
+                const sdkReceived = vi.fn();
+                sdk.listenMessages('host_handshake_request', sdkReceived);
+                // outgoing: a throwing listener must not block messageProvider.postMessage
+                host.postMessage('out-1', samplePayload());
+                expect(sdkReceived).toHaveBeenCalledTimes(1);
+                // incoming: a throwing listener must not block other host listenMessages subscribers
+                const hostReceived = vi.fn();
+                host.listenMessages('host_handshake_request', hostReceived);
+                sdk.postMessage('in-1', samplePayload());
+                expect(hostReceived).toHaveBeenCalledTimes(1);
+                // the second good listener still fired despite the first one throwing
+                expect(goodListener).toHaveBeenCalled();
+                // and the throws were observed on console.error, not propagated
+                expect(errorSpy).toHaveBeenCalled();
+            }
+            finally {
+                console.error = originalConsoleError;
+            }
+        });
+        it('cleans up the debug subscription on destroy() and blocks further sends', () => {
+            const providers = createProviders();
+            const host = createTransport(providers.host);
+            const sdk = createTransport(providers.sdk);
+            const listener = vi.fn();
+            host.onDebugMessage(listener);
+            host.destroy();
+            // postMessage on a destroyed transport throws
+            expect(() => host.postMessage('after-destroy', samplePayload())).toThrow(/Transport is disposed/);
+            // incoming traffic from the peer no longer surfaces to the listener
+            sdk.postMessage('in-after-destroy', samplePayload());
+            expect(listener).not.toHaveBeenCalled();
+        });
+        it('does not emit outgoing events when no listener is attached', () => {
+            const providers = createProviders();
+            const host = createTransport(providers.host);
+            // sanity: no listener attached, postMessage works fine
+            expect(() => host.postMessage('req', samplePayload())).not.toThrow();
+            // attach + detach + send: no events should fire to the (now-detached) listener
+            const listener = vi.fn();
+            const unsubscribe = host.onDebugMessage(listener);
+            unsubscribe();
+            host.postMessage('req2', samplePayload());
+            expect(listener).not.toHaveBeenCalled();
+        });
+    });
 });

package/dist/types.d.ts

@@ -19,6 +19,16 @@ export type MessageProvider = {
     postMessage(message: CodecType<typeof Message>): void;
     subscribe(fn: (message: CodecType<typeof Message>) => void): VoidFunction;
 };
+/**
+ * EXPERIMENTAL. A single message observed on the transport, in its
+ * decoded (non-SCALE) form. Intended for host-side introspection.
+ */
+export type DebugMessageEvent = {
+    /** `outgoing` = sent by this side via `postMessage`; `incoming` = received from the peer. */
+    direction: 'incoming' | 'outgoing';
+    requestId: string;
+    payload: MessagePayloadSchema;
+};
 export type Transport = {
     readonly provider: Provider;
     isCorrectEnvironment(): boolean;
@@ -32,4 +42,12 @@ export type Transport = {
     handleSubscription<const Method extends HostApiMethod>(method: Method, handler: SubscriptionHandler<Method>): VoidFunction;
     postMessage(requestId: string, payload: MessagePayloadSchema): void;
     listenMessages<const Action extends MessageAction>(action: Action, callback: (requestId: string, data: PickMessagePayload<Action>) => void, onError?: (error: unknown) => void): VoidFunction;
+    /**
+     * EXPERIMENTAL. Subscribe to every message crossing this transport
+     * in either direction, in decoded form. Returns an unsubscribe
+     * function. Multiple listeners are supported; the underlying
+     * provider is subscribed lazily — there is no per-message cost
+     * while no listener is attached.
+     */
+    onDebugMessage(callback: (event: DebugMessageEvent) => void): VoidFunction;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-api",
   "type": "module",
-  "version": "0.7.9-5",
+  "version": "0.7.9",
   "description": "Host API: transport implementation for host - product integration.",
   "license": "Apache-2.0",
   "repository": {
@@ -22,7 +22,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@novasamatech/scale": "0.7.9-5",
+    "@novasamatech/scale": "0.7.9",
     "nanoevents": "9.1.0",
     "nanoid": "5.1.9",
     "neverthrow": "^8.2.0",