@bardioc/app-sdk 1.0.1 → 1.0.3

package/dist/host-bridge.js

@@ -0,0 +1,318 @@
+import { SDK_MSG } from './protocol.js';
+import { BackendTransport } from './transports/backend-transport.js';
+import { GraphTransport } from './transports/graph-transport.js';
+import { OsTransport } from './transports/os-transport.js';
+let counter = 0;
+function nextId() {
+    return `sdk_${Date.now()}_${++counter}`;
+}
+function assertStoreName(storeName) {
+    const normalized = storeName.trim();
+    if (!normalized) {
+        throw new Error('storeName must be a non-empty string');
+    }
+    return normalized;
+}
+/** Create a bridge between an app and its host OS, over `postMessage` unless `config.channel` says otherwise. */
+export function createHostBridge(config) {
+    const { appId: hintAppId, connectTimeout = 5000, debug = false } = config;
+    function log(...args) {
+        if (debug)
+            console.log('[app-sdk]', ...args);
+    }
+    function windowChannel() {
+        const hostWindow = globalThis.window;
+        // When inside an iframe, document.referrer gives us the parent's origin.
+        const inferredHostOrigin = (() => {
+            try {
+                if (hostWindow.parent !== hostWindow && document.referrer) {
+                    return new URL(document.referrer).origin;
+                }
+            }
+            catch {
+                // ignore parse errors
+            }
+            return hostWindow.location.origin;
+        })();
+        const targetOrigin = config.targetOrigin ?? inferredHostOrigin;
+        const isInsideIframe = hostWindow.parent !== hostWindow;
+        log('createHostBridge', { appId: hintAppId, targetOrigin, isInsideIframe });
+        function isAllowedMessageOrigin(origin) {
+            return origin === targetOrigin || origin === hostWindow.location.origin;
+        }
+        return {
+            post: message => hostWindow.parent.postMessage(message, targetOrigin),
+            subscribe(receive) {
+                const onMessage = (event) => {
+                    if (!isAllowedMessageOrigin(event.origin)) {
+                        log('ignoring message from', event.origin, '(expected', targetOrigin, ')');
+                        return;
+                    }
+                    receive(event.data);
+                };
+                hostWindow.addEventListener('message', onMessage);
+                return () => hostWindow.removeEventListener('message', onMessage);
+            },
+        };
+    }
+    const channel = config.channel ?? windowChannel();
+    let _connected = false;
+    let _context = null;
+    let _destroyed = false;
+    const commandHandlers = new Map();
+    const osConfigUpdateCallbacks = new Set();
+    const eventHandlers = new Map();
+    const pending = new Map();
+    function handleCommandInvoke(data) {
+        const { commandId } = data.payload;
+        const handler = commandHandlers.get(commandId);
+        if (!handler) {
+            respondToHost(data.id, null, `Command "${commandId}" is not registered`);
+            return;
+        }
+        Promise.resolve()
+            .then(() => handler())
+            .then(() => {
+            respondToHost(data.id, { ok: true });
+        })
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            respondToHost(data.id, null, message);
+        });
+    }
+    function handleOsConfigUpdate(data) {
+        const newOsConfig = data.payload;
+        if (_context) {
+            _context.osConfig = newOsConfig;
+        }
+        for (const callback of osConfigUpdateCallbacks) {
+            try {
+                callback(newOsConfig);
+            }
+            catch (error) {
+                console.error('[app-sdk] OS config update callback error:', error);
+            }
+        }
+    }
+    function handleGraphEvent(data) {
+        const { subscriptionId, event } = data.payload;
+        const handler = eventHandlers.get(subscriptionId);
+        if (!handler) {
+            return;
+        }
+        try {
+            handler(event);
+        }
+        catch (error) {
+            console.error('[app-sdk] graph event handler error:', error);
+        }
+    }
+    function handlePendingResponse(data) {
+        const request = pending.get(data.id);
+        if (!request) {
+            return;
+        }
+        pending.delete(data.id);
+        if (data.error) {
+            request.reject(new Error(data.error));
+            return;
+        }
+        request.resolve(data.payload);
+    }
+    function receive(data) {
+        if (!data || typeof data.type !== 'string')
+            return;
+        if (!data.id)
+            return;
+        log('received', data.type, data.id, data.error ? `error: ${data.error}` : '');
+        switch (data.type) {
+            case SDK_MSG.COMMAND_INVOKE:
+                handleCommandInvoke(data);
+                return;
+            case SDK_MSG.OS_CONFIG_UPDATE:
+                handleOsConfigUpdate(data);
+                return;
+            case SDK_MSG.GRAPH_EVENT:
+                handleGraphEvent(data);
+                return;
+            case SDK_MSG.INIT_ACK:
+            case SDK_MSG.RESPONSE:
+                handlePendingResponse(data);
+                return;
+            default:
+                return;
+        }
+    }
+    const unsubscribe = channel.subscribe(receive);
+    function postToHost(message) {
+        channel.post(message);
+    }
+    function respondToHost(id, payload, error) {
+        postToHost({
+            type: SDK_MSG.RESPONSE,
+            id,
+            payload: error ? undefined : payload,
+            error,
+        });
+    }
+    function send(type, payload) {
+        if (_destroyed)
+            throw new Error('Bridge is destroyed — cannot send messages');
+        const id = nextId();
+        const msg = { type, id, payload };
+        log('sending', type, id);
+        postToHost(msg);
+        return id;
+    }
+    function request(type, payload, timeout = 60000) {
+        return new Promise((resolve, reject) => {
+            const id = send(type, payload);
+            pending.set(id, { resolve, reject });
+            setTimeout(() => {
+                if (pending.has(id)) {
+                    pending.delete(id);
+                    reject(new Error(`SDK request ${type} timed out after ${timeout}ms`));
+                }
+            }, timeout);
+        });
+    }
+    const storage = {
+        get: key => request(SDK_MSG.STORAGE_GET, { key }),
+        set: (key, value) => request(SDK_MSG.STORAGE_SET, { key, value }),
+        delete: key => request(SDK_MSG.STORAGE_DELETE, { key }),
+        keys: () => request(SDK_MSG.STORAGE_KEYS, {}),
+    };
+    const baseRequest = (payload) => {
+        log('[SDK] transport.request', payload);
+        return request(SDK_MSG.TRANSPORT, payload);
+    };
+    const transport = {
+        graph: new GraphTransport(baseRequest, { debug }),
+        os: new OsTransport(baseRequest),
+        backend: routeKey => new BackendTransport(baseRequest, routeKey),
+    };
+    function idb(storeName) {
+        const normalizedStoreName = assertStoreName(storeName);
+        return {
+            get: key => request(SDK_MSG.IDB_GET, { storeName: normalizedStoreName, key }),
+            put: (key, value) => request(SDK_MSG.IDB_PUT, { storeName: normalizedStoreName, key, value }),
+            delete: key => request(SDK_MSG.IDB_DELETE, { storeName: normalizedStoreName, key }),
+            query: (options = {}) => request(SDK_MSG.IDB_QUERY, {
+                storeName: normalizedStoreName,
+                prefix: options.prefix,
+                limit: options.limit,
+            }),
+        };
+    }
+    const events = {
+        subscribe({ types }, handler) {
+            const subscriptionId = nextId();
+            eventHandlers.set(subscriptionId, handler);
+            // Fire-and-forget the ack: the app-generated id removes any race, so a
+            // failed ack only means no events will arrive — surface it and clean up.
+            request(SDK_MSG.EVENT_SUBSCRIBE, { subscriptionId, types }).catch((error) => {
+                eventHandlers.delete(subscriptionId);
+                console.error('[app-sdk] events.subscribe failed:', error);
+            });
+            return () => {
+                if (!eventHandlers.delete(subscriptionId)) {
+                    return;
+                }
+                if (_destroyed) {
+                    return;
+                }
+                send(SDK_MSG.EVENT_UNSUBSCRIBE, { subscriptionId });
+            };
+        },
+    };
+    const bridge = {
+        get connected() {
+            return _connected;
+        },
+        get context() {
+            return _context;
+        },
+        async connect() {
+            if (_connected && _context)
+                return _context;
+            const result = await request(SDK_MSG.INIT, { appId: hintAppId }, connectTimeout);
+            _context = result;
+            _connected = true;
+            return result;
+        },
+        notify(message, level = 'info') {
+            send(SDK_MSG.NOTIFY, { message, level });
+        },
+        storage,
+        transport,
+        idb,
+        events,
+        setCommands(commands) {
+            const payload = { commands };
+            return request(SDK_MSG.SET_COMMANDS, payload);
+        },
+        setMenu(menu) {
+            const payload = { menu };
+            return request(SDK_MSG.SET_MENU, payload);
+        },
+        setActiveTab(activeTab) {
+            const payload = { activeTab };
+            return request(SDK_MSG.SET_ACTIVE_TAB, payload);
+        },
+        sendShortcutEvent(payload) {
+            send(SDK_MSG.SHORTCUT_EVENT, payload);
+        },
+        registerCommandHandlers(handlers) {
+            for (const [commandId, handler] of Object.entries(handlers)) {
+                commandHandlers.set(commandId, handler);
+            }
+            return () => {
+                for (const [commandId, handler] of Object.entries(handlers)) {
+                    if (commandHandlers.get(commandId) === handler) {
+                        commandHandlers.delete(commandId);
+                    }
+                }
+            };
+        },
+        onOsConfigUpdate(callback) {
+            osConfigUpdateCallbacks.add(callback);
+            return () => {
+                osConfigUpdateCallbacks.delete(callback);
+            };
+        },
+        /**
+         * @deprecated Legacy/internal only. Hosted apps should use scoped SDK APIs
+         * such as `idb`, `transport`, and `launchApp` instead of kernel-proxy.
+         */
+        sendToKernel(kernelType, kernelPayload) {
+            return request(SDK_MSG.KERNEL_PROXY, { kernelType, kernelPayload });
+        },
+        launchApp(appId) {
+            return request(SDK_MSG.LAUNCH_APP, { appId });
+        },
+        destroy() {
+            if (_destroyed)
+                return;
+            log('bridge.destroy(), pending requests:', pending.size);
+            // Best-effort unsubscribe every open stream before flipping the flag.
+            for (const subscriptionId of eventHandlers.keys()) {
+                try {
+                    send(SDK_MSG.EVENT_UNSUBSCRIBE, { subscriptionId });
+                }
+                catch {
+                    // ignore — host will drop the frame on window close anyway
+                }
+            }
+            eventHandlers.clear();
+            _destroyed = true;
+            unsubscribe();
+            for (const [, p] of pending)
+                p.reject(new Error('Bridge destroyed'));
+            pending.clear();
+            commandHandlers.clear();
+            _connected = false;
+            _context = null;
+        },
+    };
+    return bridge;
+}

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { connect } from './client.js';
 export type { Bardioc } from './client.js';
 export { BardiocError } from './errors.js';
 export type { ErrorCode } from './errors.js';
-export type { AppRecord, AppUpload, BffRequest, Command, Context, GraphEvent, IdbEntry, InstalledApp, MenuItem, MenuRoot, NotifyLevel, OsConfig, Shortcut, UploadResult, } from './contract.js';
+export type { AppRecord, AppUpload, BffRequest, Command, Context, DevAppConfig, GraphEvent, IdbEntry, InstalledApp, MenuItem, MenuRoot, NotifyLevel, OsConfig, Setting, SettingValue, Shortcut, UploadResult, } from './contract.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
 export type { AppManifest, AppManifestRole, AppManifestRules, AppManifestWindowConfig, CustomWindowSize, WindowSizePreset, } from './manifest.js';
 export type { Application, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphNodeRaw, GremlinOptions, HistoryEntry, HistoryOptions, InstanceList, MutationOptions, OrgMember, OrgStructure, OrgUnit, QueryOptions, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';

package/dist/protocol.d.ts

@@ -1,5 +1,5 @@
 export { APP_METHODS, GRAPH_EVENT_TYPES, HOST_METHODS, PROTOCOL_VERSION, graphEventFilter, } from './contract.js';
-export type { AppMethods, AppRecord, AppUpload, BffRequest, CallMethod, Command, Context, GraphEvent, HostEvents, HostMethods, IdbEntry, InstalledApp, MenuItem, MenuRoot, Method, NotifyLevel, OsConfig, Params, Result, Shortcut, StreamMethod, UploadResult, } from './contract.js';
+export type { AppMethods, AppRecord, AppUpload, BffRequest, CallMethod, Command, Context, DevAppConfig, GraphEvent, HostEvents, HostMethods, IdbEntry, InstalledApp, MenuItem, MenuRoot, Method, NotifyLevel, OsConfig, Params, Result, Setting, SettingValue, Shortcut, StreamMethod, UploadResult, } from './contract.js';
 export { BardiocError } from './errors.js';
 export type { ErrorCode, WireError } from './errors.js';
 export { acceptApp, serve } from './serve.js';

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { type DependencyList, type ReactNode } from 'react';
 import { type Bardioc } from './client.js';
-import type { Command, GraphEvent, MenuRoot, NotifyLevel, OsConfig } from './contract.js';
+import type { Command, GraphEvent, MenuRoot, NotifyLevel, OsConfig, SettingValue } from './contract.js';
 export interface AppSdkProviderProps {
     children: ReactNode;
     /** Apply theme, language and size to this document. Default: `true`. */
@@ -21,6 +21,8 @@ export declare function useCommandMenu(commands: AppCommand[], menu: MenuRoot[]
 export declare function useActiveTab(activeTab: string | null): void;
 /** The host's current theme, language and size. */
 export declare function useOsConfig(): OsConfig;
+/** The app's own settings, keyed `<group>.<field>`; follows every change the host pushes. */
+export declare function useSettings(): Record<string, SettingValue>;
 /** Streams graph events of `types` while mounted; `handler` may change without resubscribing. */
 export declare function useGraphEvents({ types }: {
     types: string[];

package/dist/react.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useRef, useState, } from 'react';
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, } from 'react';
 import { connect } from './client.js';
 const BardiocContext = createContext(null);
 const reportFailure = (what) => (error) => console.error(`[app-sdk] ${what} failed`, error);
@@ -25,7 +25,8 @@ export function AppSdkProvider({ children, applyOsConfig: apply = true, }) {
             active = false;
         };
     }, []);
-    useEffect(() => {
+    // Same commit as children: no frame renders with the wrong theme.
+    useLayoutEffect(() => {
         if (!apply || !bardioc)
             return;
         applyOsConfig(bardioc.context.osConfig);
@@ -102,6 +103,17 @@ export function useOsConfig() {
     }, [bardioc]);
     return osConfig;
 }
+/** The app's own settings, keyed `<group>.<field>`; follows every change the host pushes. */
+export function useSettings() {
+    const bardioc = useSdk();
+    const [settings, setSettings] = useState(bardioc.context.settings ?? NO_SETTINGS);
+    useEffect(() => {
+        setSettings(bardioc.context.settings ?? NO_SETTINGS);
+        return bardioc.onContextChange(context => setSettings(context.settings ?? NO_SETTINGS));
+    }, [bardioc]);
+    return settings;
+}
+const NO_SETTINGS = {};
 /** Streams graph events of `types` while mounted; `handler` may change without resubscribing. */
 export function useGraphEvents({ types }, handler, deps = []) {
     const { events } = useSdk();

package/dist/transports/backend-transport.d.ts

@@ -0,0 +1,24 @@
+import type { BackendRequestOptions, SdkTransportPayload } from '../types.js';
+export declare function isRouteKey(routeKey: string): boolean;
+/**
+ * Client for an application's own REST backend, reached through the BFF relay at
+ * `/relay/{routeKey}`. The host stamps the calling app id and scope; the BFF checks the
+ * app against the route's whitelist and forwards the request with an app-scoped token.
+ */
+export declare class BackendTransport {
+    private _request;
+    private readonly routeKey;
+    constructor(_request: <T = unknown>(payload: SdkTransportPayload) => Promise<T>, routeKey: string);
+    /**
+     * Send a request to the backend. `path` is what the backend sees, after the relay
+     * stripped `/relay/{routeKey}`. Scope is required unless stated otherwise: the relay
+     * refuses an app-scoped call without one.
+     *
+     * @throws {EntityNotFoundError} on 404 errors
+     * @throws {ValidationError} on 400 errors
+     * @throws {PermissionError} on 403 errors (app not whitelisted for the route)
+     * @throws {NetworkError} on HTTP errors, including 502 when the backend is unreachable
+     * @throws {TimeoutError} on request timeout
+     */
+    request<T = unknown>(options: BackendRequestOptions): Promise<T>;
+}

package/dist/transports/backend-transport.js

@@ -0,0 +1,54 @@
+import { ValidationError } from '../errors.js';
+import { parseOsError } from './os-transport.js';
+const RELAY_BASE = '/relay';
+// Mirrors the BFF's route key rule: one path segment, "." and ".." excluded.
+const ROUTE_KEY_PATTERN = /^[A-Za-z0-9._-]+$/;
+export function isRouteKey(routeKey) {
+    return routeKey !== '.' && routeKey !== '..' && ROUTE_KEY_PATTERN.test(routeKey);
+}
+/**
+ * Client for an application's own REST backend, reached through the BFF relay at
+ * `/relay/{routeKey}`. The host stamps the calling app id and scope; the BFF checks the
+ * app against the route's whitelist and forwards the request with an app-scoped token.
+ */
+export class BackendTransport {
+    _request;
+    routeKey;
+    constructor(_request, routeKey) {
+        this._request = _request;
+        this.routeKey = routeKey;
+        if (!isRouteKey(routeKey)) {
+            throw new ValidationError(`Invalid relay route key: "${routeKey}"`, 'routeKey');
+        }
+    }
+    /**
+     * Send a request to the backend. `path` is what the backend sees, after the relay
+     * stripped `/relay/{routeKey}`. Scope is required unless stated otherwise: the relay
+     * refuses an app-scoped call without one.
+     *
+     * @throws {EntityNotFoundError} on 404 errors
+     * @throws {ValidationError} on 400 errors
+     * @throws {PermissionError} on 403 errors (app not whitelisted for the route)
+     * @throws {NetworkError} on HTTP errors, including 502 when the backend is unreachable
+     * @throws {TimeoutError} on request timeout
+     */
+    async request(options) {
+        const path = options.path.startsWith('/') ? options.path : `/${options.path}`;
+        try {
+            return await this._request({
+                path: `${RELAY_BASE}/${this.routeKey}${path}`,
+                method: options.method || 'GET',
+                body: options.body,
+                contentType: options.contentType,
+                scopeId: options.scopeId,
+                scopePolicy: options.scopePolicy ?? 'required',
+            });
+        }
+        catch (error) {
+            throw parseOsError(error, `backend.${this.routeKey}.request`, {
+                path: options.path,
+                method: options.method,
+            });
+        }
+    }
+}