@aspectly/transports 0.1.0

package/src/transports/CefSharpTransport.ts

@@ -0,0 +1,73 @@
+import { BaseTransport } from '../BaseTransport';
+import type { TransportListener, TransportUnsubscribe, TransportDetector } from '../types';
+
+declare global {
+  interface Window {
+    CefSharp?: {
+      PostMessage: (message: string) => void;
+      BindObjectAsync: (...args: unknown[]) => Promise<void>;
+    };
+  }
+}
+
+/**
+ * Transport for CefSharp (Chromium Embedded Framework for .NET)
+ * Used in desktop applications with embedded Chromium browsers
+ *
+ * @example
+ * ```typescript
+ * import { CefSharpTransport } from '@aspectly/transports/cefsharp';
+ *
+ * const transport = new CefSharpTransport();
+ * if (transport.isAvailable()) {
+ *   transport.send(JSON.stringify({ type: 'hello' }));
+ * }
+ * ```
+ */
+export class CefSharpTransport extends BaseTransport {
+  readonly name = 'cefsharp';
+
+  isAvailable(): boolean {
+    const win = this.getWindow();
+    return typeof win?.CefSharp?.PostMessage === 'function';
+  }
+
+  send(message: string): void {
+    const win = this.getWindow();
+    if (!win?.CefSharp?.PostMessage) {
+      console.warn('[CefSharpTransport] CefSharp.PostMessage is not available');
+      return;
+    }
+    win.CefSharp.PostMessage(message);
+  }
+
+  subscribe(listener: TransportListener): TransportUnsubscribe {
+    const win = this.getWindow();
+    if (!win) {
+      return () => {};
+    }
+
+    // CefSharp sends messages via window.postMessage
+    const handler = (event: MessageEvent): void => {
+      if (typeof event.data === 'string') {
+        listener(event.data);
+      }
+    };
+
+    win.addEventListener('message', handler);
+    return () => win.removeEventListener('message', handler);
+  }
+}
+
+/**
+ * Detector for auto-detection registry
+ */
+export const cefSharpDetector: TransportDetector = {
+  name: 'cefsharp',
+  priority: 100, // Highest priority - check first
+  detect: () => {
+    return typeof window !== 'undefined' &&
+           typeof window.CefSharp?.PostMessage === 'function';
+  },
+  createTransport: () => new CefSharpTransport(),
+};

package/src/transports/IframeTransport.test.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { IframeTransport, iframeDetector } from './IframeTransport';
+
+describe('IframeTransport', () => {
+  let transport: IframeTransport;
+  let originalParent: Window;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    transport = new IframeTransport();
+    originalParent = window.parent;
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    Object.defineProperty(window, 'parent', {
+      value: originalParent,
+      writable: true,
+      configurable: true,
+    });
+    consoleWarnSpy.mockRestore();
+  });
+
+  it('should have name property equal to "iframe"', () => {
+    expect(transport.name).toBe('iframe');
+  });
+
+  it('should have default targetOrigin of "*"', () => {
+    // Access private property for testing
+    expect((transport as any).targetOrigin).toBe('*');
+  });
+
+  it('should accept custom targetOrigin in constructor', () => {
+    const customTransport = new IframeTransport('https://example.com');
+    expect((customTransport as any).targetOrigin).toBe('https://example.com');
+  });
+
+  it('should return false when not in iframe (parent === window)', () => {
+    Object.defineProperty(window, 'parent', {
+      value: window,
+      writable: true,
+      configurable: true,
+    });
+    expect(transport.isAvailable()).toBe(false);
+  });
+
+  it('should return true when in iframe (parent !== window)', () => {
+    const mockParent = { ...window, isParent: true };
+    Object.defineProperty(window, 'parent', {
+      value: mockParent,
+      writable: true,
+      configurable: true,
+    });
+    expect(transport.isAvailable()).toBe(true);
+  });
+
+  it('should call window.parent.postMessage with message and targetOrigin', () => {
+    const mockPostMessage = vi.fn();
+    const mockParent = { postMessage: mockPostMessage };
+    Object.defineProperty(window, 'parent', {
+      value: mockParent,
+      writable: true,
+      configurable: true,
+    });
+
+    transport.send('test message');
+
+    expect(mockPostMessage).toHaveBeenCalledWith('test message', '*');
+    expect(mockPostMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('should use custom targetOrigin when sending', () => {
+    const customTransport = new IframeTransport('https://example.com');
+    const mockPostMessage = vi.fn();
+    const mockParent = { postMessage: mockPostMessage };
+    Object.defineProperty(window, 'parent', {
+      value: mockParent,
+      writable: true,
+      configurable: true,
+    });
+
+    customTransport.send('test message');
+
+    expect(mockPostMessage).toHaveBeenCalledWith('test message', 'https://example.com');
+  });
+
+  it('should warn when not in iframe during send', () => {
+    Object.defineProperty(window, 'parent', {
+      value: window,
+      writable: true,
+      configurable: true,
+    });
+
+    transport.send('test message');
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith('[IframeTransport] Not inside an iframe');
+  });
+
+  it('should add message event listener when subscribing', () => {
+    const addEventListenerSpy = vi.spyOn(window, 'addEventListener');
+    const listener = vi.fn();
+
+    transport.subscribe(listener);
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+
+    addEventListenerSpy.mockRestore();
+  });
+
+  it('should call listener with string data from message event', () => {
+    const listener = vi.fn();
+    transport.subscribe(listener);
+
+    const event = new MessageEvent('message', { data: 'test data' });
+    window.dispatchEvent(event);
+
+    expect(listener).toHaveBeenCalledWith('test data');
+  });
+
+  it('should not call listener with non-string data', () => {
+    const listener = vi.fn();
+    transport.subscribe(listener);
+
+    const event1 = new MessageEvent('message', { data: 123 });
+    const event2 = new MessageEvent('message', { data: { foo: 'bar' } });
+    const event3 = new MessageEvent('message', { data: null });
+
+    window.dispatchEvent(event1);
+    window.dispatchEvent(event2);
+    window.dispatchEvent(event3);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('should remove event listener when cleanup function is called', () => {
+    const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener');
+    const listener = vi.fn();
+
+    const unsubscribe = transport.subscribe(listener);
+    unsubscribe();
+
+    expect(removeEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+
+    removeEventListenerSpy.mockRestore();
+  });
+
+  it('should not receive messages after unsubscribing', () => {
+    const listener = vi.fn();
+    const unsubscribe = transport.subscribe(listener);
+
+    const event1 = new MessageEvent('message', { data: 'before unsubscribe' });
+    window.dispatchEvent(event1);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unsubscribe();
+
+    const event2 = new MessageEvent('message', { data: 'after unsubscribe' });
+    window.dispatchEvent(event2);
+
+    expect(listener).toHaveBeenCalledTimes(1); // Still 1, not 2
+  });
+});
+
+describe('iframeDetector', () => {
+  let originalParent: Window;
+
+  beforeEach(() => {
+    originalParent = window.parent;
+  });
+
+  afterEach(() => {
+    Object.defineProperty(window, 'parent', {
+      value: originalParent,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  it('should have name property equal to "iframe"', () => {
+    expect(iframeDetector.name).toBe('iframe');
+  });
+
+  it('should have priority of 80', () => {
+    expect(iframeDetector.priority).toBe(80);
+  });
+
+  it('should detect() return false when not in iframe', () => {
+    Object.defineProperty(window, 'parent', {
+      value: window,
+      writable: true,
+      configurable: true,
+    });
+    expect(iframeDetector.detect()).toBe(false);
+  });
+
+  it('should detect() return true when in iframe', () => {
+    const mockParent = { ...window, isParent: true };
+    Object.defineProperty(window, 'parent', {
+      value: mockParent,
+      writable: true,
+      configurable: true,
+    });
+    expect(iframeDetector.detect()).toBe(true);
+  });
+
+  it('should createTransport() return IframeTransport instance', () => {
+    const transport = iframeDetector.createTransport();
+    expect(transport).toBeInstanceOf(IframeTransport);
+    expect(transport.name).toBe('iframe');
+  });
+});

package/src/transports/IframeTransport.ts

@@ -0,0 +1,79 @@
+import { BaseTransport } from '../BaseTransport';
+import type { TransportListener, TransportUnsubscribe, TransportDetector } from '../types';
+
+/**
+ * Transport for iframe/window.postMessage communication
+ * Used when web content is displayed inside an iframe
+ *
+ * @example
+ * ```typescript
+ * import { IframeTransport } from '@aspectly/transports/iframe';
+ *
+ * const transport = new IframeTransport();
+ * if (transport.isAvailable()) {
+ *   transport.send(JSON.stringify({ type: 'hello' }));
+ * }
+ * ```
+ */
+export class IframeTransport extends BaseTransport {
+  readonly name = 'iframe';
+  private readonly targetOrigin: string;
+
+  /**
+   * Create an iframe transport
+   * @param targetOrigin Origin to send messages to (default: '*')
+   */
+  constructor(targetOrigin: string = '*') {
+    super();
+    this.targetOrigin = targetOrigin;
+  }
+
+  isAvailable(): boolean {
+    const win = this.getWindow();
+    if (!win) return false;
+    // Check if we're inside an iframe (parent !== self)
+    return win.parent !== win;
+  }
+
+  send(message: string): void {
+    const win = this.getWindow();
+    if (!win) {
+      console.warn('[IframeTransport] Window is not available');
+      return;
+    }
+    if (win.parent === win) {
+      console.warn('[IframeTransport] Not inside an iframe');
+      return;
+    }
+    win.parent.postMessage(message, this.targetOrigin);
+  }
+
+  subscribe(listener: TransportListener): TransportUnsubscribe {
+    const win = this.getWindow();
+    if (!win) {
+      return () => {};
+    }
+
+    const handler = (event: MessageEvent): void => {
+      // Optionally filter by origin here if targetOrigin !== '*'
+      if (typeof event.data === 'string') {
+        listener(event.data);
+      }
+    };
+
+    win.addEventListener('message', handler);
+    return () => win.removeEventListener('message', handler);
+  }
+}
+
+/**
+ * Detector for auto-detection registry
+ */
+export const iframeDetector: TransportDetector = {
+  name: 'iframe',
+  priority: 80, // Lowest priority - fallback
+  detect: () => {
+    return typeof window !== 'undefined' && window.parent !== window;
+  },
+  createTransport: () => new IframeTransport(),
+};

package/src/transports/NullTransport.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { NullTransport } from './NullTransport';
+
+describe('NullTransport', () => {
+  let transport: NullTransport;
+  let originalNodeEnv: string | undefined;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    transport = new NullTransport();
+    originalNodeEnv = process.env.NODE_ENV;
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.env.NODE_ENV = originalNodeEnv;
+    consoleWarnSpy.mockRestore();
+  });
+
+  it('should have name property equal to "null"', () => {
+    expect(transport.name).toBe('null');
+  });
+
+  it('should have isAvailable() always return true', () => {
+    expect(transport.isAvailable()).toBe(true);
+  });
+
+  it('should have send() be a no-op without errors', () => {
+    expect(() => transport.send('test message')).not.toThrow();
+  });
+
+  it('should log warning in development mode when send() is called', () => {
+    process.env.NODE_ENV = 'development';
+    transport.send('test message');
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[NullTransport] No transport available, message not sent'
+    );
+  });
+
+  it('should not log warning in production mode when send() is called', () => {
+    process.env.NODE_ENV = 'production';
+    transport.send('test message');
+    expect(consoleWarnSpy).not.toHaveBeenCalled();
+  });
+
+  it('should have subscribe() return a cleanup function', () => {
+    const listener = vi.fn();
+    const unsubscribe = transport.subscribe(listener);
+    expect(typeof unsubscribe).toBe('function');
+  });
+
+  it('should have subscribe() cleanup function be a no-op without errors', () => {
+    const listener = vi.fn();
+    const unsubscribe = transport.subscribe(listener);
+    expect(() => unsubscribe()).not.toThrow();
+  });
+
+  it('should never call listener (messages are no-op)', () => {
+    const listener = vi.fn();
+    transport.subscribe(listener);
+    // Since NullTransport doesn't actually receive messages, listener should never be called
+    expect(listener).not.toHaveBeenCalled();
+  });
+});

package/src/transports/NullTransport.ts

@@ -0,0 +1,27 @@
+import { BaseTransport } from '../BaseTransport';
+import type { TransportListener, TransportUnsubscribe } from '../types';
+
+/**
+ * Null transport - used when no transport is available
+ * All operations are no-ops. Useful for SSR or testing.
+ */
+export class NullTransport extends BaseTransport {
+  readonly name = 'null';
+
+  isAvailable(): boolean {
+    // Always "available" as a fallback, but does nothing
+    return true;
+  }
+
+  send(_message: string): void {
+    // No-op
+    if (process.env.NODE_ENV === 'development') {
+      console.warn('[NullTransport] No transport available, message not sent');
+    }
+  }
+
+  subscribe(_listener: TransportListener): TransportUnsubscribe {
+    // No-op
+    return () => {};
+  }
+}

package/src/transports/PostMessageTransport.ts

@@ -0,0 +1,50 @@
+import { BaseTransport } from '../BaseTransport';
+import type { TransportListener, TransportUnsubscribe, TransportDetector } from '../types';
+
+/**
+ * Fallback transport for browser environments.
+ * Listens for window.postMessage events, allowing parent windows
+ * to receive messages from child iframes.
+ */
+export class PostMessageTransport extends BaseTransport {
+  readonly name = 'postmessage';
+
+  isAvailable(): boolean {
+    return typeof this.getWindow()?.addEventListener === 'function';
+  }
+
+  send(message: string): void {
+    const win = this.getWindow();
+    if (!win) return;
+    win.postMessage(message, '*');
+  }
+
+  subscribe(listener: TransportListener): TransportUnsubscribe {
+    const win = this.getWindow();
+    if (!win) {
+      return () => {};
+    }
+
+    const handler = (event: MessageEvent): void => {
+      if (typeof event.data === 'string') {
+        listener(event.data);
+      }
+    };
+
+    win.addEventListener('message', handler);
+    return () => win.removeEventListener('message', handler);
+  }
+}
+
+/**
+ * Detector for auto-detection registry
+ */
+export const postMessageDetector: TransportDetector = {
+  name: 'postmessage',
+  priority: 10, // Lowest priority — fallback for any browser environment
+  detect: () => {
+    return typeof window !== 'undefined' &&
+           typeof window.addEventListener === 'function';
+  },
+  createTransport: () => new PostMessageTransport(),
+};

package/src/transports/ReactNativeTransport.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ReactNativeTransport, reactNativeDetector } from './ReactNativeTransport';
+
+interface ReactNativeWindow extends Window {
+  ReactNativeWebView?: {
+    postMessage: (message: string) => void;
+  };
+}
+
+const testWindow = window as ReactNativeWindow;
+
+describe('ReactNativeTransport', () => {
+  let transport: ReactNativeTransport;
+  let originalRNW: typeof testWindow.ReactNativeWebView;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    transport = new ReactNativeTransport();
+    originalRNW = testWindow.ReactNativeWebView;
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    testWindow.ReactNativeWebView = originalRNW;
+    consoleWarnSpy.mockRestore();
+  });
+
+  it('should have name property equal to "react-native"', () => {
+    expect(transport.name).toBe('react-native');
+  });
+
+  it('should return false when ReactNativeWebView not present', () => {
+    testWindow.ReactNativeWebView = undefined;
+    expect(transport.isAvailable()).toBe(false);
+  });
+
+  it('should return false when ReactNativeWebView.postMessage not a function', () => {
+    testWindow.ReactNativeWebView = {} as any;
+    expect(transport.isAvailable()).toBe(false);
+  });
+
+  it('should return true when ReactNativeWebView.postMessage exists', () => {
+    testWindow.ReactNativeWebView = {
+      postMessage: vi.fn(),
+    };
+    expect(transport.isAvailable()).toBe(true);
+  });
+
+  it('should call ReactNativeWebView.postMessage with quoted message (iOS quirk)', () => {
+    const mockPostMessage = vi.fn();
+    testWindow.ReactNativeWebView = {
+      postMessage: mockPostMessage,
+    };
+
+    transport.send('test message');
+
+    // iOS quirk: message is wrapped in quotes
+    expect(mockPostMessage).toHaveBeenCalledWith("'test message'");
+    expect(mockPostMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('should handle JSON messages with proper quoting', () => {
+    const mockPostMessage = vi.fn();
+    testWindow.ReactNativeWebView = {
+      postMessage: mockPostMessage,
+    };
+
+    const jsonMessage = JSON.stringify({ type: 'test', data: 'foo' });
+    transport.send(jsonMessage);
+
+    expect(mockPostMessage).toHaveBeenCalledWith(`'${jsonMessage}'`);
+  });
+
+  it('should warn when ReactNativeWebView not available during send', () => {
+    testWindow.ReactNativeWebView = undefined;
+
+    transport.send('test message');
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[ReactNativeTransport] ReactNativeWebView.postMessage is not available'
+    );
+  });
+
+  it('should warn when ReactNativeWebView.postMessage not available during send', () => {
+    testWindow.ReactNativeWebView = {} as any;
+
+    transport.send('test message');
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[ReactNativeTransport] ReactNativeWebView.postMessage is not available'
+    );
+  });
+
+  it('should add message event listener when subscribing', () => {
+    const addEventListenerSpy = vi.spyOn(window, 'addEventListener');
+    const listener = vi.fn();
+
+    transport.subscribe(listener);
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+
+    addEventListenerSpy.mockRestore();
+  });
+
+  it('should call listener with string data from message event', () => {
+    const listener = vi.fn();
+    transport.subscribe(listener);
+
+    const event = new MessageEvent('message', { data: 'test data' });
+    window.dispatchEvent(event);
+
+    expect(listener).toHaveBeenCalledWith('test data');
+  });
+
+  it('should not call listener with non-string data', () => {
+    const listener = vi.fn();
+    transport.subscribe(listener);
+
+    const event1 = new MessageEvent('message', { data: 123 });
+    const event2 = new MessageEvent('message', { data: { foo: 'bar' } });
+    const event3 = new MessageEvent('message', { data: null });
+
+    window.dispatchEvent(event1);
+    window.dispatchEvent(event2);
+    window.dispatchEvent(event3);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('should remove event listener when cleanup function is called', () => {
+    const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener');
+    const listener = vi.fn();
+
+    const unsubscribe = transport.subscribe(listener);
+    unsubscribe();
+
+    expect(removeEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+
+    removeEventListenerSpy.mockRestore();
+  });
+
+  it('should not receive messages after unsubscribing', () => {
+    const listener = vi.fn();
+    const unsubscribe = transport.subscribe(listener);
+
+    const event1 = new MessageEvent('message', { data: 'before unsubscribe' });
+    window.dispatchEvent(event1);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unsubscribe();
+
+    const event2 = new MessageEvent('message', { data: 'after unsubscribe' });
+    window.dispatchEvent(event2);
+
+    expect(listener).toHaveBeenCalledTimes(1); // Still 1, not 2
+  });
+});
+
+describe('reactNativeDetector', () => {
+  let originalRNW: typeof testWindow.ReactNativeWebView;
+
+  beforeEach(() => {
+    originalRNW = testWindow.ReactNativeWebView;
+  });
+
+  afterEach(() => {
+    testWindow.ReactNativeWebView = originalRNW;
+  });
+
+  it('should have name property equal to "react-native"', () => {
+    expect(reactNativeDetector.name).toBe('react-native');
+  });
+
+  it('should have priority of 90', () => {
+    expect(reactNativeDetector.priority).toBe(90);
+  });
+
+  it('should detect() return false when ReactNativeWebView not present', () => {
+    testWindow.ReactNativeWebView = undefined;
+    expect(reactNativeDetector.detect()).toBe(false);
+  });
+
+  it('should detect() return true when ReactNativeWebView.postMessage exists', () => {
+    testWindow.ReactNativeWebView = {
+      postMessage: vi.fn(),
+    };
+    expect(reactNativeDetector.detect()).toBe(true);
+  });
+
+  it('should createTransport() return ReactNativeTransport instance', () => {
+    const transport = reactNativeDetector.createTransport();
+    expect(transport).toBeInstanceOf(ReactNativeTransport);
+    expect(transport.name).toBe('react-native');
+  });
+});