@aspectly/core 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2022 Zhan Isaakian
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# @aspectly/core
+
+The core bridge framework for cross-platform communication between WebViews, iframes, and web applications.
+
+## Installation
+
+```bash
+# npm
+npm install @aspectly/core
+
+# pnpm
+pnpm add @aspectly/core
+
+# yarn
+yarn add @aspectly/core
+```
+
+## Overview
+
+`@aspectly/core` provides the foundational bridge communication layer that enables bidirectional message passing between different execution contexts:
+
+- **WebView ↔ React Native**: Communication between web content and React Native apps
+- **iframe ↔ Parent Window**: Communication between iframes and their parent pages
+- **Browser Context**: Standalone browser usage with global bridge instance
+
+## Quick Start
+
+### Inside a WebView or iframe
+
+```typescript
+import { AspectlyBridge } from '@aspectly/core';
+
+// Create a bridge instance
+const bridge = new AspectlyBridge();
+
+// Initialize with handlers for incoming requests
+await bridge.init({
+  greet: async (params: { name: string }) => {
+    return { message: `Hello, ${params.name}!` };
+  },
+  getData: async () => {
+    return { timestamp: Date.now() };
+  },
+});
+
+// Send requests to the parent container
+const result = await bridge.send('parentMethod', { data: 'value' });
+console.log(result);
+```
+
+### Browser Script Tag Usage
+
+```html
+<script src="https://unpkg.com/@aspectly/core/dist/browser.js"></script>
+<script>
+  window.aspectlyBridge.init({
+    greet: async (params) => ({ message: `Hello, ${params.name}!` })
+  }).then(() => {
+    console.log('Bridge initialized');
+  });
+</script>
+```
+
+## API Reference
+
+### AspectlyBridge
+
+The main class for bridge communication.
+
+#### Constructor
+
+```typescript
+const bridge = new AspectlyBridge(options?: BridgeOptions);
+```
+
+**Options:**
+- `timeout?: number` - Handler execution timeout in ms (default: 100000)
+
+#### Methods
+
+##### `init(handlers?: BridgeHandlers): Promise<boolean>`
+
+Initialize the bridge with handlers for incoming requests.
+
+```typescript
+await bridge.init({
+  methodName: async (params) => {
+    // Handle request and return result
+    return { success: true };
+  },
+});
+```
+
+##### `send<T>(method: string, params?: object): Promise<T>`
+
+Send a request to the other side.
+
+```typescript
+const result = await bridge.send<{ data: string }>('getData', { id: 123 });
+```
+
+##### `supports(method: string): boolean`
+
+Check if a method is supported by the other side.
+
+```typescript
+if (bridge.supports('getData')) {
+  const data = await bridge.send('getData');
+}
+```
+
+##### `isAvailable(): boolean`
+
+Check if the bridge is initialized and ready.
+
+```typescript
+if (bridge.isAvailable()) {
+  // Bridge is ready
+}
+```
+
+##### `subscribe(listener: BridgeListener): number`
+
+Subscribe to all result events for monitoring/debugging.
+
+```typescript
+bridge.subscribe((result) => {
+  console.log('Event:', result.method, result.data);
+});
+```
+
+##### `unsubscribe(listener: BridgeListener): void`
+
+Remove a result event listener.
+
+##### `destroy(): void`
+
+Cleanup bridge subscriptions.
+
+```typescript
+bridge.destroy();
+```
+
+## Error Handling
+
+The bridge provides typed errors for different failure scenarios:
+
+```typescript
+import { BridgeErrorType } from '@aspectly/core';
+
+try {
+  await bridge.send('unknownMethod');
+} catch (error) {
+  switch (error.error_type) {
+    case BridgeErrorType.UNSUPPORTED_METHOD:
+      console.log('Method not registered');
+      break;
+    case BridgeErrorType.METHOD_EXECUTION_TIMEOUT:
+      console.log('Handler timed out');
+      break;
+    case BridgeErrorType.REJECTED:
+      console.log('Handler threw error:', error.error_message);
+      break;
+    case BridgeErrorType.BRIDGE_NOT_AVAILABLE:
+      console.log('Bridge not initialized');
+      break;
+  }
+}
+```
+
+## Architecture
+
+The package consists of four layers:
+
+1. **BridgeCore** - Low-level platform detection and message serialization
+2. **BridgeInternal** - Protocol management and request/response lifecycle
+3. **BridgeBase** - Clean public API interface
+4. **AspectlyBridge** - Main entry point composing all layers
+
+## Related Packages
+
+- [`@aspectly/web`](../web) - Web/iframe integration with React hooks
+- [`@aspectly/react-native`](../react-native) - React Native WebView integration
+- [`@aspectly/react-native-web`](../react-native-web) - React Native Web + iframe support
+
+## License
+
+MIT

package/dist/AspectlyBridge-hGuDjcI6.d.mts

@@ -0,0 +1,242 @@
+/**
+ * Event types used in bridge communication protocol
+ */
+declare enum BridgeEventType {
+    /** Request to invoke a method on the other side */
+    Request = "Request",
+    /** Response to a request */
+    Result = "Result",
+    /** Initialization handshake */
+    Init = "Init",
+    /** Response to initialization */
+    InitResult = "InitResult"
+}
+/**
+ * Result types for bridge responses
+ */
+declare enum BridgeResultType {
+    /** Successful response */
+    Success = "Success",
+    /** Error response */
+    Error = "Error"
+}
+/**
+ * Error types that can occur during bridge communication
+ */
+declare enum BridgeErrorType {
+    /** Handler took longer than timeout (default: 100s) */
+    METHOD_EXECUTION_TIMEOUT = "METHOD_EXECUTION_TIMEOUT",
+    /** Method is not registered on the receiving side */
+    UNSUPPORTED_METHOD = "UNSUPPORTED_METHOD",
+    /** Handler threw an error */
+    REJECTED = "REJECTED",
+    /** Bridge is not initialized or unavailable */
+    BRIDGE_NOT_AVAILABLE = "BRIDGE_NOT_AVAILABLE"
+}
+/**
+ * Error data returned when a bridge call fails
+ */
+interface BridgeResultError {
+    error_type: BridgeErrorType;
+    error_message?: string;
+}
+/**
+ * Successful result data (any object)
+ */
+type BridgeResultSuccess = object;
+/**
+ * Union type for result data
+ */
+type BridgeResultData = BridgeResultError | undefined | BridgeResultSuccess;
+/**
+ * Result event sent back after processing a request
+ */
+interface BridgeResultEvent {
+    type?: BridgeResultType;
+    method?: string;
+    request_id?: string;
+    data?: BridgeResultData;
+}
+/**
+ * Request event sent to invoke a method
+ */
+interface BridgeRequestEvent {
+    method: string;
+    params: object;
+    request_id?: string;
+}
+/**
+ * Initialization event with available methods
+ */
+interface BridgeInitEvent {
+    methods: string[];
+}
+/**
+ * Initialization result (success/failure)
+ */
+type BridgeInitResultEvent = boolean;
+/**
+ * Union of all possible bridge data payloads
+ */
+type BridgeData = BridgeResultEvent | BridgeInitEvent | BridgeInitResultEvent | BridgeRequestEvent;
+/**
+ * Complete bridge event with type and data
+ */
+interface BridgeEvent {
+    type: BridgeEventType;
+    data: BridgeData;
+}
+/**
+ * Handler function for processing incoming requests
+ */
+type BridgeHandler<TParams = object, TResult = unknown> = (params: TParams) => Promise<TResult>;
+/**
+ * Map of method names to their handlers
+ */
+interface BridgeHandlers {
+    [key: string]: BridgeHandler<any, any>;
+}
+/**
+ * Listener function for bridge result events
+ */
+type BridgeListener = (result: BridgeResultEvent) => void;
+/**
+ * Options for bridge initialization
+ */
+interface BridgeOptions {
+    /** Timeout for method execution in milliseconds (default: 100000) */
+    timeout?: number;
+}
+
+type InternalEventSender = (event: BridgeEvent) => void;
+/**
+ * BridgeInternal handles the business logic of the bridge protocol.
+ * It manages request/response lifecycle, handler registration, and event routing.
+ */
+declare class BridgeInternal {
+    private requests;
+    private handlers;
+    private available;
+    private supportedMethods;
+    private listeners;
+    private initPromise?;
+    private readonly sendEvent;
+    private readonly timeout;
+    constructor(sendEvent: InternalEventSender, options?: BridgeOptions);
+    /**
+     * Subscribe to all result events
+     */
+    subscribe: (listener: BridgeListener) => number;
+    /**
+     * Unsubscribe from result events
+     */
+    unsubscribe: (listener: BridgeListener) => void;
+    private checkDiff;
+    /**
+     * Initialize the bridge with handlers
+     * @param handlers Map of method names to handler functions
+     * @returns Promise that resolves when the other side acknowledges
+     */
+    init: (handlers?: BridgeHandlers) => Promise<boolean>;
+    /**
+     * Handle incoming bridge events
+     */
+    handleCoreEvent: (event: BridgeEvent) => void;
+    /**
+     * Handle incoming requests and execute the appropriate handler
+     */
+    handleRequest: (request: BridgeRequestEvent) => void;
+    private handleResult;
+    private handleRequestResult;
+    private handleInit;
+    private handleInitResult;
+    /**
+     * Send a request to the other side
+     * @param method Method name to invoke
+     * @param params Parameters to pass to the method
+     * @returns Promise that resolves with the result
+     */
+    send: <TResult = unknown>(method: string, params: object) => Promise<TResult>;
+    /**
+     * Check if a method is supported by the other side
+     */
+    supports: (method: string) => boolean;
+    /**
+     * Check if the bridge is available (initialized)
+     */
+    isAvailable: () => boolean;
+}
+
+/**
+ * BridgeBase provides the public API for bridge communication.
+ * It wraps BridgeInternal and exposes a clean interface for consumers.
+ */
+declare class BridgeBase {
+    protected bridge: BridgeInternal;
+    constructor(bridge: BridgeInternal);
+    /**
+     * Check if a method is supported by the other side
+     * @param method Method name to check
+     */
+    supports: (method: string) => boolean;
+    /**
+     * Check if the bridge is available (initialized)
+     */
+    isAvailable: () => boolean;
+    /**
+     * Send a request to invoke a method on the other side
+     * @param method Method name to invoke
+     * @param params Parameters to pass
+     * @returns Promise resolving with the result
+     */
+    send: <TResult = unknown>(method: string, params?: object) => Promise<TResult>;
+    /**
+     * Subscribe to all result events
+     * @param listener Callback for result events
+     * @returns Subscription index
+     */
+    subscribe: (listener: BridgeListener) => number;
+    /**
+     * Unsubscribe from result events
+     * @param listener The listener to remove
+     */
+    unsubscribe: (listener: BridgeListener) => void;
+    /**
+     * Initialize the bridge with handlers
+     * @param handlers Map of method names to handler functions
+     * @returns Promise resolving when initialization is complete
+     */
+    init: (handlers?: BridgeHandlers) => Promise<boolean>;
+}
+
+/**
+ * AspectlyBridge is the main entry point for bridge communication.
+ * Use this class when running inside a WebView or iframe that needs
+ * to communicate with its parent container.
+ *
+ * @example
+ * ```typescript
+ * // Inside a WebView or iframe
+ * const bridge = new AspectlyBridge();
+ *
+ * // Initialize with handlers
+ * await bridge.init({
+ *   greet: async (params) => {
+ *     return { message: `Hello, ${params.name}!` };
+ *   }
+ * });
+ *
+ * // Send messages to parent
+ * const result = await bridge.send('someMethod', { data: 'value' });
+ * ```
+ */
+declare class AspectlyBridge extends BridgeBase {
+    private cleanupSubscription;
+    constructor(options?: BridgeOptions);
+    /**
+     * Cleanup bridge subscriptions
+     */
+    destroy: () => void;
+}
+
+export { AspectlyBridge as A, BridgeBase as B, BridgeInternal as a, type BridgeEvent as b, type BridgeData as c, type BridgeHandler as d, type BridgeHandlers as e, type BridgeListener as f, type BridgeOptions as g, type BridgeRequestEvent as h, type BridgeResultEvent as i, type BridgeResultError as j, type BridgeResultSuccess as k, type BridgeResultData as l, type BridgeInitEvent as m, type BridgeInitResultEvent as n, BridgeEventType as o, BridgeResultType as p, BridgeErrorType as q };

package/dist/AspectlyBridge-hGuDjcI6.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Event types used in bridge communication protocol
+ */
+declare enum BridgeEventType {
+    /** Request to invoke a method on the other side */
+    Request = "Request",
+    /** Response to a request */
+    Result = "Result",
+    /** Initialization handshake */
+    Init = "Init",
+    /** Response to initialization */
+    InitResult = "InitResult"
+}
+/**
+ * Result types for bridge responses
+ */
+declare enum BridgeResultType {
+    /** Successful response */
+    Success = "Success",
+    /** Error response */
+    Error = "Error"
+}
+/**
+ * Error types that can occur during bridge communication
+ */
+declare enum BridgeErrorType {
+    /** Handler took longer than timeout (default: 100s) */
+    METHOD_EXECUTION_TIMEOUT = "METHOD_EXECUTION_TIMEOUT",
+    /** Method is not registered on the receiving side */
+    UNSUPPORTED_METHOD = "UNSUPPORTED_METHOD",
+    /** Handler threw an error */
+    REJECTED = "REJECTED",
+    /** Bridge is not initialized or unavailable */
+    BRIDGE_NOT_AVAILABLE = "BRIDGE_NOT_AVAILABLE"
+}
+/**
+ * Error data returned when a bridge call fails
+ */
+interface BridgeResultError {
+    error_type: BridgeErrorType;
+    error_message?: string;
+}
+/**
+ * Successful result data (any object)
+ */
+type BridgeResultSuccess = object;
+/**
+ * Union type for result data
+ */
+type BridgeResultData = BridgeResultError | undefined | BridgeResultSuccess;
+/**
+ * Result event sent back after processing a request
+ */
+interface BridgeResultEvent {
+    type?: BridgeResultType;
+    method?: string;
+    request_id?: string;
+    data?: BridgeResultData;
+}
+/**
+ * Request event sent to invoke a method
+ */
+interface BridgeRequestEvent {
+    method: string;
+    params: object;
+    request_id?: string;
+}
+/**
+ * Initialization event with available methods
+ */
+interface BridgeInitEvent {
+    methods: string[];
+}
+/**
+ * Initialization result (success/failure)
+ */
+type BridgeInitResultEvent = boolean;
+/**
+ * Union of all possible bridge data payloads
+ */
+type BridgeData = BridgeResultEvent | BridgeInitEvent | BridgeInitResultEvent | BridgeRequestEvent;
+/**
+ * Complete bridge event with type and data
+ */
+interface BridgeEvent {
+    type: BridgeEventType;
+    data: BridgeData;
+}
+/**
+ * Handler function for processing incoming requests
+ */
+type BridgeHandler<TParams = object, TResult = unknown> = (params: TParams) => Promise<TResult>;
+/**
+ * Map of method names to their handlers
+ */
+interface BridgeHandlers {
+    [key: string]: BridgeHandler<any, any>;
+}
+/**
+ * Listener function for bridge result events
+ */
+type BridgeListener = (result: BridgeResultEvent) => void;
+/**
+ * Options for bridge initialization
+ */
+interface BridgeOptions {
+    /** Timeout for method execution in milliseconds (default: 100000) */
+    timeout?: number;
+}
+
+type InternalEventSender = (event: BridgeEvent) => void;
+/**
+ * BridgeInternal handles the business logic of the bridge protocol.
+ * It manages request/response lifecycle, handler registration, and event routing.
+ */
+declare class BridgeInternal {
+    private requests;
+    private handlers;
+    private available;
+    private supportedMethods;
+    private listeners;
+    private initPromise?;
+    private readonly sendEvent;
+    private readonly timeout;
+    constructor(sendEvent: InternalEventSender, options?: BridgeOptions);
+    /**
+     * Subscribe to all result events
+     */
+    subscribe: (listener: BridgeListener) => number;
+    /**
+     * Unsubscribe from result events
+     */
+    unsubscribe: (listener: BridgeListener) => void;
+    private checkDiff;
+    /**
+     * Initialize the bridge with handlers
+     * @param handlers Map of method names to handler functions
+     * @returns Promise that resolves when the other side acknowledges
+     */
+    init: (handlers?: BridgeHandlers) => Promise<boolean>;
+    /**
+     * Handle incoming bridge events
+     */
+    handleCoreEvent: (event: BridgeEvent) => void;
+    /**
+     * Handle incoming requests and execute the appropriate handler
+     */
+    handleRequest: (request: BridgeRequestEvent) => void;
+    private handleResult;
+    private handleRequestResult;
+    private handleInit;
+    private handleInitResult;
+    /**
+     * Send a request to the other side
+     * @param method Method name to invoke
+     * @param params Parameters to pass to the method
+     * @returns Promise that resolves with the result
+     */
+    send: <TResult = unknown>(method: string, params: object) => Promise<TResult>;
+    /**
+     * Check if a method is supported by the other side
+     */
+    supports: (method: string) => boolean;
+    /**
+     * Check if the bridge is available (initialized)
+     */
+    isAvailable: () => boolean;
+}
+
+/**
+ * BridgeBase provides the public API for bridge communication.
+ * It wraps BridgeInternal and exposes a clean interface for consumers.
+ */
+declare class BridgeBase {
+    protected bridge: BridgeInternal;
+    constructor(bridge: BridgeInternal);
+    /**
+     * Check if a method is supported by the other side
+     * @param method Method name to check
+     */
+    supports: (method: string) => boolean;
+    /**
+     * Check if the bridge is available (initialized)
+     */
+    isAvailable: () => boolean;
+    /**
+     * Send a request to invoke a method on the other side
+     * @param method Method name to invoke
+     * @param params Parameters to pass
+     * @returns Promise resolving with the result
+     */
+    send: <TResult = unknown>(method: string, params?: object) => Promise<TResult>;
+    /**
+     * Subscribe to all result events
+     * @param listener Callback for result events
+     * @returns Subscription index
+     */
+    subscribe: (listener: BridgeListener) => number;
+    /**
+     * Unsubscribe from result events
+     * @param listener The listener to remove
+     */
+    unsubscribe: (listener: BridgeListener) => void;
+    /**
+     * Initialize the bridge with handlers
+     * @param handlers Map of method names to handler functions
+     * @returns Promise resolving when initialization is complete
+     */
+    init: (handlers?: BridgeHandlers) => Promise<boolean>;
+}
+
+/**
+ * AspectlyBridge is the main entry point for bridge communication.
+ * Use this class when running inside a WebView or iframe that needs
+ * to communicate with its parent container.
+ *
+ * @example
+ * ```typescript
+ * // Inside a WebView or iframe
+ * const bridge = new AspectlyBridge();
+ *
+ * // Initialize with handlers
+ * await bridge.init({
+ *   greet: async (params) => {
+ *     return { message: `Hello, ${params.name}!` };
+ *   }
+ * });
+ *
+ * // Send messages to parent
+ * const result = await bridge.send('someMethod', { data: 'value' });
+ * ```
+ */
+declare class AspectlyBridge extends BridgeBase {
+    private cleanupSubscription;
+    constructor(options?: BridgeOptions);
+    /**
+     * Cleanup bridge subscriptions
+     */
+    destroy: () => void;
+}
+
+export { AspectlyBridge as A, BridgeBase as B, BridgeInternal as a, type BridgeEvent as b, type BridgeData as c, type BridgeHandler as d, type BridgeHandlers as e, type BridgeListener as f, type BridgeOptions as g, type BridgeRequestEvent as h, type BridgeResultEvent as i, type BridgeResultError as j, type BridgeResultSuccess as k, type BridgeResultData as l, type BridgeInitEvent as m, type BridgeInitResultEvent as n, BridgeEventType as o, BridgeResultType as p, BridgeErrorType as q };