@gemigo/app-sdk 0.2.5

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 GemiGo Contributors
+
+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,117 @@
+# @gemigo/app-sdk
+
+GemiGo App SDK that auto-adapts for Web / Desktop / Browser Extension.
+
+## Installation
+
+### CDN (Recommended)
+
+```html
+<script src="https://unpkg.com/@gemigo/app-sdk/dist/gemigo-app-sdk.umd.js"></script>
+```
+
+### npm
+
+```bash
+npm install @gemigo/app-sdk
+```
+
+## Quick Start
+
+```html
+<script src="https://unpkg.com/@gemigo/app-sdk/dist/gemigo-app-sdk.umd.js"></script>
+<script>
+  // SDK auto-connects, use gemigo.extension.* APIs directly
+  gemigo.extension.getPageInfo().then(console.log);
+  
+  // Subscribe to context menu events
+  gemigo.extension.onContextMenu((event) => {
+    console.log('Menu clicked:', event.menuId, event.selectionText);
+  });
+</script>
+```
+
+## API Reference
+
+### Page Content Reading
+
+| Method | Description |
+|--------|-------------|
+| `getPageInfo()` | Get current page URL, title, favicon |
+| `getPageHTML()` | Get full page HTML content |
+| `getPageText()` | Get page text content |
+| `getSelection()` | Get selected text and position `{ text, rect? }` |
+| `extractArticle()` | Extract article title, content, excerpt |
+| `extractLinks()` | Extract all links from page |
+| `extractImages()` | Extract all images from page |
+| `queryElement(selector, limit?)` | Query elements by CSS selector |
+
+### Page Manipulation
+
+| Method | Description |
+|--------|-------------|
+| `highlight(selector, color?)` | Highlight elements (returns highlightId) |
+| `removeHighlight(highlightId)` | Remove highlight |
+| `insertWidget(html, position)` | Insert floating widget |
+| `updateWidget(widgetId, html)` | Update widget content |
+| `removeWidget(widgetId)` | Remove widget |
+| `injectCSS(css)` | Inject CSS (returns styleId) |
+| `removeCSS(styleId)` | Remove injected CSS |
+
+### Screenshots
+
+| Method | Description |
+|--------|-------------|
+| `captureVisible()` | Capture visible area screenshot |
+
+### Events
+
+| Method | Description |
+|--------|-------------|
+| `onContextMenu(handler)` | Subscribe to context menu events |
+| `onSelectionChange(handler)` | Subscribe to selection changes `(text, rect, url)` |
+| `getContextMenuEvent()` | Get pending context menu event |
+
+### Common APIs
+
+| Method | Description |
+|--------|-------------|
+| `gemigo.notify(title, message)` | Send system notification |
+
+## Example: Translation Bubble
+
+```html
+<script src="https://unpkg.com/@gemigo/app-sdk/dist/gemigo-app-sdk.umd.js"></script>
+<script>
+  gemigo.extension.onContextMenu(async (event) => {
+    if (event.selectionText) {
+      const translated = await translateText(event.selectionText);
+      
+      // Show translation bubble on page
+      await gemigo.extension.insertWidget(
+        `<div style="background:#667eea;color:#fff;padding:16px;border-radius:12px;">
+          ${translated}
+        </div>`,
+        'bottom-right'
+      );
+    }
+  });
+</script>
+```
+
+## Example: Reader Mode
+
+```javascript
+// Inject reader-friendly CSS
+const { styleId } = await gemigo.extension.injectCSS(`
+  body { max-width: 720px; margin: 0 auto; font-family: Georgia, serif; }
+  nav, aside, .ads { display: none !important; }
+`);
+
+// Remove later
+await gemigo.extension.removeCSS(styleId);
+```
+
+## License
+
+MIT

package/dist/apis/index.d.ts

@@ -0,0 +1,10 @@
+import { ChildMethods } from '../core';
+import { GemigoSDK, Platform, Capabilities } from '../types';
+/**
+ * Update the SDK's host environment information.
+ */
+export declare const updateHostInfo: (info: {
+    platform: Platform;
+    capabilities: Capabilities;
+} | null) => void;
+export declare const sdk: GemigoSDK, childMethods: ChildMethods;

package/dist/connection-C-IGR2wz.js

@@ -0,0 +1,2 @@
+import { i as tryGetHost, n as createRPCProxy, r as initConnection, t as callHost } from "./connection-DwOg1Kh5.js";
+export { initConnection };

package/dist/connection-DwOg1Kh5.js

@@ -0,0 +1,248 @@
+var MessageType;
+(function(e) {
+	e.Call = "call", e.Reply = "reply", e.Syn = "syn", e.SynAck = "synAck", e.Ack = "ack";
+})(MessageType ||= {});
+var Resolution;
+(function(e) {
+	e.Fulfilled = "fulfilled", e.Rejected = "rejected";
+})(Resolution ||= {});
+var ErrorCode;
+(function(e) {
+	e.ConnectionDestroyed = "ConnectionDestroyed", e.ConnectionTimeout = "ConnectionTimeout", e.NoIframeSrc = "NoIframeSrc";
+})(ErrorCode ||= {});
+var NativeErrorName;
+(function(e) {
+	e.DataCloneError = "DataCloneError";
+})(NativeErrorName ||= {});
+var NativeEventType;
+(function(e) {
+	e.Message = "message";
+})(NativeEventType ||= {});
+var createDestructor_default = (e, g) => {
+	let _ = [], v = !1;
+	return {
+		destroy(y) {
+			v || (v = !0, g(`${e}: Destroying connection`), _.forEach((e) => {
+				e(y);
+			}));
+		},
+		onDestroy(e) {
+			v ? e() : _.push(e);
+		}
+	};
+}, createLogger_default = (e) => (...g) => {
+	e && console.log("[Penpal]", ...g);
+};
+const serializeError = ({ name: e, message: g, stack: _ }) => ({
+	name: e,
+	message: g,
+	stack: _
+}), deserializeError = (e) => {
+	let g = /* @__PURE__ */ Error();
+	return Object.keys(e).forEach((_) => g[_] = e[_]), g;
+};
+var connectCallReceiver_default = (_, b, x) => {
+	let { localName: C, local: w, remote: T, originForSending: E, originForReceiving: D } = _, O = !1, k = (_) => {
+		if (_.source !== T || _.data.penpal !== MessageType.Call) return;
+		if (D !== "*" && _.origin !== D) {
+			x(`${C} received message from origin ${_.origin} which did not match expected origin ${D}`);
+			return;
+		}
+		let { methodName: y, args: w, id: k } = _.data;
+		x(`${C}: Received ${y}() call`);
+		let A = (_) => (b) => {
+			if (x(`${C}: Sending ${y}() reply`), O) {
+				x(`${C}: Unable to send ${y}() reply due to destroyed connection`);
+				return;
+			}
+			let w = {
+				penpal: MessageType.Reply,
+				id: k,
+				resolution: _,
+				returnValue: b
+			};
+			_ === Resolution.Rejected && b instanceof Error && (w.returnValue = serializeError(b), w.returnValueIsError = !0);
+			try {
+				T.postMessage(w, E);
+			} catch (_) {
+				if (_.name === NativeErrorName.DataCloneError) {
+					let v = {
+						penpal: MessageType.Reply,
+						id: k,
+						resolution: Resolution.Rejected,
+						returnValue: serializeError(_),
+						returnValueIsError: !0
+					};
+					T.postMessage(v, E);
+				}
+				throw _;
+			}
+		};
+		new Promise((e) => e(b[y].apply(b, w))).then(A(Resolution.Fulfilled), A(Resolution.Rejected));
+	};
+	return w.addEventListener(NativeEventType.Message, k), () => {
+		O = !0, w.removeEventListener(NativeEventType.Message, k);
+	};
+}, id = 0, generateId_default = () => ++id, KEY_PATH_DELIMITER = ".", keyPathToSegments = (e) => e ? e.split(KEY_PATH_DELIMITER) : [], segmentsToKeyPath = (e) => e.join(KEY_PATH_DELIMITER), createKeyPath = (e, g) => {
+	let _ = keyPathToSegments(g || "");
+	return _.push(e), segmentsToKeyPath(_);
+};
+const setAtKeyPath = (e, g, _) => {
+	let v = keyPathToSegments(g);
+	return v.reduce((e, g, y) => (e[g] === void 0 && (e[g] = {}), y === v.length - 1 && (e[g] = _), e[g]), e), e;
+}, serializeMethods = (e, g) => {
+	let _ = {};
+	return Object.keys(e).forEach((v) => {
+		let y = e[v], b = createKeyPath(v, g);
+		typeof y == "object" && Object.assign(_, serializeMethods(y, b)), typeof y == "function" && (_[b] = y);
+	}), _;
+}, deserializeMethods = (e) => {
+	let g = {};
+	for (let _ in e) setAtKeyPath(g, _, e[_]);
+	return g;
+};
+var connectCallSender_default = (v, b, x, S, w) => {
+	let { localName: T, local: D, remote: O, originForSending: k, originForReceiving: A } = b, j = !1;
+	w(`${T}: Connecting call sender`);
+	let M = (v) => (...b) => {
+		w(`${T}: Sending ${v}() call`);
+		let x;
+		try {
+			O.closed && (x = !0);
+		} catch {
+			x = !0;
+		}
+		if (x && S(), j) {
+			let e = /* @__PURE__ */ Error(`Unable to send ${v}() call due to destroyed connection`);
+			throw e.code = ErrorCode.ConnectionDestroyed, e;
+		}
+		return new Promise((_, x) => {
+			let S = generateId_default(), j = (b) => {
+				if (b.source !== O || b.data.penpal !== MessageType.Reply || b.data.id !== S) return;
+				if (A !== "*" && b.origin !== A) {
+					w(`${T} received message from origin ${b.origin} which did not match expected origin ${A}`);
+					return;
+				}
+				let E = b.data;
+				w(`${T}: Received ${v}() reply`), D.removeEventListener(NativeEventType.Message, j);
+				let k = E.returnValue;
+				E.returnValueIsError && (k = deserializeError(k)), (E.resolution === Resolution.Fulfilled ? _ : x)(k);
+			};
+			D.addEventListener(NativeEventType.Message, j);
+			let M = {
+				penpal: MessageType.Call,
+				id: S,
+				methodName: v,
+				args: b
+			};
+			O.postMessage(M, k);
+		});
+	}, N = x.reduce((e, g) => (e[g] = M(g), e), {});
+	return Object.assign(v, deserializeMethods(N)), () => {
+		j = !0;
+	};
+}, startConnectionTimeout_default = (e, g) => {
+	let v;
+	return e !== void 0 && (v = window.setTimeout(() => {
+		let v = /* @__PURE__ */ Error(`Connection timed out after ${e}ms`);
+		v.code = ErrorCode.ConnectionTimeout, g(v);
+	}, e)), () => {
+		clearTimeout(v);
+	};
+}, handleSynAckMessageFactory_default = (g, _, v, y) => {
+	let { destroy: b, onDestroy: x } = v;
+	return (v) => {
+		if (!(g instanceof RegExp ? g.test(v.origin) : g === "*" || g === v.origin)) {
+			y(`Child: Handshake - Received SYN-ACK from origin ${v.origin} which did not match expected origin ${g}`);
+			return;
+		}
+		y("Child: Handshake - Received SYN-ACK, responding with ACK");
+		let S = v.origin === "null" ? "*" : v.origin, C = {
+			penpal: MessageType.Ack,
+			methodNames: Object.keys(_)
+		};
+		window.parent.postMessage(C, S);
+		let T = {
+			localName: "Child",
+			local: window,
+			remote: window.parent,
+			originForSending: S,
+			originForReceiving: v.origin
+		};
+		x(connectCallReceiver_default(T, _, y));
+		let E = {};
+		return x(connectCallSender_default(E, T, v.data.methodNames, b, y)), E;
+	};
+}, areGlobalsAccessible = () => {
+	try {
+		clearTimeout();
+	} catch {
+		return !1;
+	}
+	return !0;
+}, connectToParent_default = (g = {}) => {
+	let { parentOrigin: _ = "*", methods: v = {}, timeout: S, debug: C = !1 } = g, w = createLogger_default(C), T = createDestructor_default("Child", w), { destroy: E, onDestroy: D } = T, O = handleSynAckMessageFactory_default(_, serializeMethods(v), T, w), k = () => {
+		w("Child: Handshake - Sending SYN");
+		let g = { penpal: MessageType.Syn }, v = _ instanceof RegExp ? "*" : _;
+		window.parent.postMessage(g, v);
+	};
+	return {
+		promise: new Promise((g, _) => {
+			let v = startConnectionTimeout_default(S, E), b = (_) => {
+				if (areGlobalsAccessible() && !(_.source !== parent || !_.data) && _.data.penpal === MessageType.SynAck) {
+					let e = O(_);
+					e && (window.removeEventListener(NativeEventType.Message, b), v(), g(e));
+				}
+			};
+			window.addEventListener(NativeEventType.Message, b), k(), D((e) => {
+				window.removeEventListener(NativeEventType.Message, b), e && _(e);
+			});
+		}),
+		destroy() {
+			E();
+		}
+	};
+}, connectionPromise = null, resolvedHost = null, connectionFailed = !1, defaultChildMethods, DEFAULT_TIMEOUT_MS = 1500;
+function isInIframe() {
+	try {
+		return window.self !== window.top;
+	} catch {
+		return !0;
+	}
+}
+async function tryGetHost(e, g) {
+	if (resolvedHost) return resolvedHost;
+	if (connectionFailed) return null;
+	if (!isInIframe()) return connectionFailed = !0, null;
+	if (!connectionPromise) {
+		let _ = {}, v = e ?? defaultChildMethods;
+		v && Object.assign(_, v), connectionPromise = connectToParent_default({
+			methods: _,
+			timeout: g?.timeoutMs ?? DEFAULT_TIMEOUT_MS
+		}).promise.then((e) => (resolvedHost = e, e)).catch((e) => (console.error("[GemiGo Connection] Promise failed:", e), connectionFailed = !0, connectionPromise = null, null));
+	}
+	return connectionPromise;
+}
+function initConnection(e, g) {
+	defaultChildMethods = e, tryGetHost(e, g);
+}
+async function callHost(e, g = [], _) {
+	let v = await tryGetHost();
+	if (v && typeof v[e] == "function") {
+		let y = await v[e](...g);
+		if (y?.success !== !1) return y?.data === void 0 ? y?.value === void 0 ? y : y.value : y.data;
+		if (_) return _(...g);
+		throw Error(y?.error || `Host method ${String(e)} failed`);
+	}
+	if (_) return _(...g);
+	throw Error(`Method ${String(e)} not supported in this environment`);
+}
+function createRPCProxy(e, g = {}) {
+	let _ = {};
+	for (let v of e) {
+		let e = g.mapping?.[v] || v, y = g.fallbacks?.[v];
+		_[v] = (...g) => callHost(e, g, y);
+	}
+	return _;
+}
+export { tryGetHost as i, createRPCProxy as n, initConnection as r, callHost as t };

package/dist/core/api-factory.d.ts

@@ -0,0 +1,84 @@
+import { HostMethods } from './connection';
+import { SDKEvents } from './event-bus';
+export interface APIConfig<TAPI extends object> {
+    /** RPC methods mapping to host functions */
+    rpc?: {
+        methods: readonly (keyof TAPI)[];
+        mapping?: Partial<Record<keyof TAPI, keyof HostMethods>>;
+        fallbacks?: Partial<Record<keyof TAPI, (...args: any[]) => any>>;
+    };
+    /** Event methods mapping to SDK event bus */
+    events?: readonly (keyof TAPI)[] | {
+        [K in keyof TAPI]?: keyof SDKEvents | {
+            event: keyof SDKEvents;
+            childMethod?: string;
+        };
+    };
+}
+/**
+ * Create a unified API instance from a declarative configuration.
+ *
+ * @param config - API configuration
+ * @returns Object with generated API instance and child methods for host injection
+ */
+export declare function createUnifiedAPI<TAPI extends object, TChild extends object = Record<string, any>>(config: APIConfig<TAPI>): {
+    api: TAPI;
+    childMethods: TChild;
+};
+/**
+ * Create a standalone RPC action with argument transformation and fallback handling.
+ *
+ * @param methodName - Host method name to call
+ * @param config - Action configuration
+ * @returns An async function that handles the full RPC cycle
+ */
+export declare function createRPCAction<TArgs extends any[], TResult, THostResult = any>(methodName: keyof HostMethods, config: {
+    /** Transform input arguments for host method */
+    transform?: (...args: TArgs) => any[];
+    /** Fallback if host fails */
+    fallback: (...args: TArgs) => TResult | Promise<TResult>;
+    /** Process host result */
+    onSuccess?: (result: THostResult) => TResult;
+}): (...args: TArgs) => Promise<TResult>;
+/**
+ * Master SDK Action Configuration
+ */
+export interface ActionConfig<TFunc extends (...args: any[]) => any> {
+    method: keyof HostMethods;
+    /** Transform input arguments for host method */
+    transform?: (...args: Parameters<TFunc>) => any[];
+    /** Fallback if host fails */
+    fallback: TFunc;
+    /** Process host result */
+    onSuccess?: (result: any) => ReturnType<TFunc> extends Promise<infer R> ? R : ReturnType<TFunc>;
+}
+/**
+ * Master SDK Factory - Create the entire SDK and child methods from a single config.
+ */
+export declare function createSDK<TSDK extends object, TChild extends object = Record<string, any>>(config: {
+    /** Sub-modules (e.g., storage, extension) */
+    modules?: {
+        [K in keyof TSDK]?: NonNullable<TSDK[K]> extends (...args: any[]) => any ? never : NonNullable<TSDK[K]> extends object ? APIConfig<NonNullable<TSDK[K]>> : never;
+    };
+    /** Standalone functions (e.g., notify) */
+    actions?: {
+        [K in keyof TSDK]?: TSDK[K] extends (...args: any[]) => any ? ActionConfig<TSDK[K]> : never;
+    };
+    /** Dynamic getter properties (e.g., platform, capabilities) */
+    getters?: {
+        [K in keyof TSDK]?: () => TSDK[K];
+    };
+    /** Static values or stubs (e.g., platform, ai) */
+    statics?: {
+        [K in keyof TSDK]?: TSDK[K];
+    };
+}): {
+    sdk: TSDK;
+    childMethods: TChild;
+};
+/**
+ * Bootstrap the SDK connection and discover host protocol info.
+ */
+export declare function bootstrapSDK(childMethods: any, options?: {
+    timeoutMs?: number;
+}): Promise<any>;

package/dist/core/connection.d.ts

@@ -0,0 +1,99 @@
+import { AsyncMethodReturns } from 'penpal';
+import { Capabilities, ExtensionRPCMethods, RPCResult, Platform } from '../types';
+import { SDKEvents } from './event-bus';
+export interface ProtocolRPCMethods {
+    getProtocolInfo(): Promise<{
+        protocolVersion: number;
+        platform: Platform;
+        appId: string;
+        capabilities: Capabilities;
+    }>;
+    ping(): Promise<{
+        pong: boolean;
+    }>;
+}
+export interface StorageRPCMethods {
+    storageGet(key: string): Promise<{
+        success: boolean;
+        data?: unknown;
+    }>;
+    storageSet(key: string, value: unknown): Promise<RPCResult>;
+    storageDelete(key: string): Promise<RPCResult>;
+    storageClear(): Promise<RPCResult>;
+}
+export interface NetworkRPCMethods {
+    networkRequest(url: string, options?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string | object;
+        responseType?: 'json' | 'text' | 'arraybuffer';
+        timeoutMs?: number;
+    }): Promise<{
+        success: boolean;
+        status?: number;
+        headers?: Record<string, string>;
+        data?: any;
+        error?: string;
+        code?: string;
+    }>;
+}
+export interface NotifyRPCMethods {
+    notify(payload: {
+        title: string;
+        message: string;
+    }): Promise<RPCResult<string>>;
+}
+/**
+ * Host methods interface - what the host provides to apps.
+ * Same interface for all platforms.
+ */
+export interface HostMethods extends ExtensionRPCMethods, ProtocolRPCMethods, StorageRPCMethods, NetworkRPCMethods, NotifyRPCMethods {
+}
+/**
+ * Child methods interface - what apps expose to the host.
+ * Automatically derived from SDK event definitions.
+ */
+export type ChildMethods = {
+    [K in keyof SDKEvents]?: (...args: SDKEvents[K]) => void;
+};
+/**
+ * Get or create connection to parent (host).
+ * Returns null if connection failed or not in iframe.
+ */
+export declare function tryGetHost(childMethods?: ChildMethods, options?: {
+    timeoutMs?: number;
+}): Promise<AsyncMethodReturns<HostMethods> | null>;
+/**
+ * Get host connection (throws if not available).
+ */
+export declare function getHost(): Promise<AsyncMethodReturns<HostMethods>>;
+/**
+ * Check if connected to host.
+ */
+export declare function isConnected(): boolean;
+/**
+ * Check if connection failed.
+ */
+export declare function hasConnectionFailed(): boolean;
+/**
+ * Initialize connection immediately.
+ */
+export declare function initConnection(childMethods?: ChildMethods, options?: {
+    timeoutMs?: number;
+}): void;
+/**
+ * Generic host call with optional fallback.
+ */
+export declare function callHost<T>(methodName: keyof HostMethods, args?: any[], fallback?: (...args: any[]) => T | Promise<T>): Promise<T>;
+/**
+ * Create a simple RPC proxy for a set of methods.
+ */
+export declare function createRPCProxy<T extends Record<string, any>>(methodNames: readonly (keyof T)[], config?: {
+    mapping?: Record<string, keyof HostMethods>;
+    fallbacks?: Record<string, (...args: any[]) => any>;
+}): T;
+/**
+ * Wrap an async function with a fallback.
+ * If the primary function throws, the fallback is called with the same arguments.
+ */
+export declare function withFallback<TArgs extends unknown[], TResult>(primary: (...args: TArgs) => Promise<TResult>, fallback: (...args: TArgs) => TResult | Promise<TResult>): (...args: TArgs) => Promise<TResult>;

package/dist/core/event-bus.d.ts

@@ -0,0 +1,77 @@
+import { ExtensionAPI } from '../types';
+export type EventHandler<T extends unknown[] = unknown[]> = (...args: T) => void;
+export interface EventBus<TEvents extends Record<string, unknown[]>> {
+    /**
+     * Subscribe to an event
+     * @returns Unsubscribe function
+     */
+    on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void;
+    /**
+     * Emit an event to all subscribers
+     */
+    emit<K extends keyof TEvents>(event: K, ...args: TEvents[K]): void;
+    /**
+     * Remove all subscribers for an event (or all events)
+     */
+    off<K extends keyof TEvents>(event?: K): void;
+}
+/**
+ * Create a type-safe event bus
+ */
+export declare function createEventBus<TEvents extends Record<string, unknown[]>>(): EventBus<TEvents>;
+/**
+ * SDK-level event types
+ * Add new event types here as the SDK grows
+ */
+export type SDKEvents = {
+    onContextMenu: Parameters<Parameters<ExtensionAPI['onContextMenu']>[0]>;
+    onSelectionChange: Parameters<Parameters<ExtensionAPI['onSelectionChange']>[0]>;
+};
+/**
+ * Shared SDK event bus instance
+ * Use this for SDK-wide event communication
+ */
+export declare const sdkEventBus: EventBus<SDKEvents>;
+/**
+ * Create a callback handler that subscribes to the SDK event bus.
+ * Useful for building callback APIs like onContextMenu, onSelectionChange, etc.
+ *
+ * @param eventName - The SDK event to subscribe to
+ * @param ensureConnection - Optional function to ensure host connection (e.g., tryGetHost)
+ * @returns A function that accepts a callback and returns an unsubscribe function
+ *
+ * @example
+ * const onContextMenu = createCallbackHandler('extension:contextMenu', tryGetHost);
+ */
+export declare function createCallbackHandler<K extends keyof SDKEvents>(eventName: K, ensureConnection?: () => void): (callback: EventHandler<SDKEvents[K]>) => () => void;
+/**
+ * Create both emitter (for childMethods) and subscriber (for callbackAPI) from a single config.
+ * This ensures event names and signatures stay in sync.
+ *
+ * @param config - Map of local method names to SDK event names
+ * @param ensureConnection - Optional function to ensure host connection
+ * @returns Object with emitters and subscribers
+ *
+ * @example
+ * const { emitters, subscribers } = createEventPair({
+ *   onContextMenuEvent: 'extension:contextMenu',
+ *   onSelectionChange: 'extension:selectionChange',
+ * }, tryGetHost);
+ *
+ * // Use emitters in childMethods
+ * export const childMethods = emitters;
+ *
+ * // Use subscribers in callbackAPI
+ * export const callbackAPI = {
+ *   onContextMenu: subscribers.onContextMenuEvent,
+ *   onSelectionChange: subscribers.onSelectionChange,
+ * };
+ */
+export declare function createEventPair<TConfig extends Record<string, keyof SDKEvents>>(config: TConfig, ensureConnection?: () => void): {
+    emitters: {
+        [K in keyof TConfig]: (...args: SDKEvents[TConfig[K]]) => void;
+    };
+    subscribers: {
+        [K in keyof TConfig]: (callback: EventHandler<SDKEvents[TConfig[K]]>) => () => void;
+    };
+};

package/dist/core/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Core Module
+ */
+export { getHost, tryGetHost, initConnection, isConnected, hasConnectionFailed, callHost, createRPCProxy, withFallback, } from './connection';
+export { createEventBus, sdkEventBus, createCallbackHandler, createEventPair } from './event-bus';
+export type { EventBus, EventHandler, SDKEvents } from './event-bus';
+export { createUnifiedAPI, createRPCAction, createSDK, bootstrapSDK } from './api-factory';
+export type { APIConfig } from './api-factory';
+export type { HostMethods, ChildMethods } from './connection';

package/dist/fallback/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fallback Implementations
+ *
+ * Used when no host is available.
+ */
+export { fallbackStorage } from './storage';
+export { fallbackNotify } from './notify';
+export { fallbackNetwork } from './network';

package/dist/fallback/network.d.ts

@@ -0,0 +1,2 @@
+import { NetworkAPI } from '../types';
+export declare const fallbackNetwork: NetworkAPI;

package/dist/fallback/notify.d.ts

@@ -0,0 +1,2 @@
+import { NotifyOptions, NotifyResult } from '../types';
+export declare const fallbackNotify: (options: NotifyOptions) => Promise<NotifyResult>;