@bardioc/app-sdk 0.4.10 → 0.5.0

package/dist/dev-proxy.js

@@ -1,5 +1,7 @@
 import { createServer } from 'node:http';
 import { resolveDevAuthEnv } from './dev-auth-env.js';
+// BFF mount of the dynamic relay to published REST backends.
+const RELAY_PATH_PREFIX = '/relay';
 export async function readRequestBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -95,9 +97,12 @@ export function createDevAuthProxyHandler(options) {
         }
         addDevSecretHeader(req, headers, devSecret);
         dropOriginKeepReferer(headers);
-        // Dev auth is dev-secret only: never forward X-App-Id, so the BFF app-token
-        // exchange (which would also demand X-Scope-ID) can never be triggered here.
-        headers.delete('X-App-Id');
+        // Dev auth is dev-secret only, so X-App-Id is dropped and the BFF app-token exchange
+        // (which would also demand X-Scope-ID) is never triggered. The relay is the exception:
+        // it authorizes on the exchanged app identity and answers 403 without one.
+        if (!upstreamPath.startsWith(`${RELAY_PATH_PREFIX}/`)) {
+            headers.delete('X-App-Id');
+        }
         // BFF rejects /bardioc/ calls without this CSRF marker header; stamp it like the host does.
         headers.set('X-Requested-With', 'XMLHttpRequest');
         let body;

package/dist/dev.d.ts

@@ -1,6 +1,12 @@
 export interface DevBridgeOptions {
     /** Base URL prepended to SDK transport paths. Defaults to `/rest`. */
     apiBaseUrl?: string;
+    /**
+     * The app's ogit/Auth/Application id, sent as X-App-ID on scoped calls like the host
+     * does. Needed for `transport.backend(...)`: the relay authorizes on the exchanged app
+     * identity and refuses calls without it.
+     */
+    appId?: string;
     debug?: boolean;
 }
 export declare function isInsideIframe(): boolean;

package/dist/dev.js

@@ -12,6 +12,7 @@ export function isDevStandalone() {
 }
 export function installDevBridge(options = {}) {
     const apiBaseUrl = getBaseUrl(options.apiBaseUrl);
+    const appId = options.appId?.trim() || undefined;
     const debug = options.debug ?? false;
     const origin = window.location.origin;
     const log = (...args) => {
@@ -49,6 +50,11 @@ export function installDevBridge(options = {}) {
         }
         if (resolvedScopeId) {
             headers.set('X-Scope-ID', resolvedScopeId);
+            // The BFF app-token exchange rejects X-App-ID without X-Scope-ID, so a scopeless
+            // call goes out as the user, exactly as the host sends it.
+            if (appId) {
+                headers.set('X-App-ID', appId);
+            }
         }
         const url = `${apiBaseUrl}${payload.path}`;
         log('[transport]', payload.method ?? 'GET', url);

package/dist/host-bridge.d.ts

@@ -1,3 +1,3 @@
 import type { HostBridge, HostBridgeConfig } from './types.js';
-/** Create a bridge between an iframe app and its host OS via `postMessage`. */
+/** Create a bridge between an app and its host OS, over `postMessage` unless `config.channel` says otherwise. */
 export declare function createHostBridge(config: HostBridgeConfig): HostBridge;

package/dist/host-bridge.js

@@ -1,4 +1,5 @@
 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;
@@ -12,29 +13,49 @@ function assertStoreName(storeName) {
     }
     return normalized;
 }
-/** Create a bridge between an iframe app and its host OS via `postMessage`. */
+/** 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;
-    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;
     function log(...args) {
         if (debug)
             console.log('[app-sdk]', ...args);
     }
-    log('createHostBridge', { appId: hintAppId, targetOrigin, isInsideIframe });
+    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;
@@ -42,9 +63,6 @@ export function createHostBridge(config) {
     const osConfigUpdateCallbacks = new Set();
     const eventHandlers = new Map();
     const pending = new Map();
-    function isAllowedMessageOrigin(origin) {
-        return origin === targetOrigin || origin === hostWindow.location.origin;
-    }
     function handleCommandInvoke(data) {
         const { commandId } = data.payload;
         const handler = commandHandlers.get(commandId);
@@ -101,12 +119,7 @@ export function createHostBridge(config) {
         }
         request.resolve(data.payload);
     }
-    function onMessage(event) {
-        if (!isAllowedMessageOrigin(event.origin)) {
-            log('ignoring message from', event.origin, '(expected', targetOrigin, ')');
-            return;
-        }
-        const data = event.data;
+    function receive(data) {
         if (!data || typeof data.type !== 'string')
             return;
         if (!data.id)
@@ -130,9 +143,9 @@ export function createHostBridge(config) {
                 return;
         }
     }
-    hostWindow.addEventListener('message', onMessage);
+    const unsubscribe = channel.subscribe(receive);
     function postToHost(message) {
-        hostWindow.parent.postMessage(message, targetOrigin);
+        channel.post(message);
     }
     function respondToHost(id, payload, error) {
         postToHost({
@@ -176,6 +189,7 @@ export function createHostBridge(config) {
     const transport = {
         graph: new GraphTransport(baseRequest, { debug }),
         os: new OsTransport(baseRequest),
+        backend: routeKey => new BackendTransport(baseRequest, routeKey),
     };
     function idb(storeName) {
         const normalizedStoreName = assertStoreName(storeName);
@@ -291,7 +305,7 @@ export function createHostBridge(config) {
             }
             eventHandlers.clear();
             _destroyed = true;
-            hostWindow.removeEventListener('message', onMessage);
+            unsubscribe();
             for (const [, p] of pending)
                 p.reject(new Error('Bridge destroyed'));
             pending.clear();

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contr
 export { ALLOWED_KERNEL_MESSAGES, SDK_MSG } from './protocol.js';
 export type { SdkMessageType } from './protocol.js';
 export { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from './errors.js';
-export type { Application, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, EventsApi, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphEvent, GraphEventPushPayload, GraphEventType, GraphNodeRaw, GraphTransport, GremlinOptions, HistoryEntry, HistoryOptions, HostBridge, HostBridgeConfig, InstanceList, MutationOptions, NotifyLevel, OrgMember, OrgStructure, OrgUnit, OsConfig, OsRequestOptions, OsTransport, QueryOptions, SdkCommandDefinition, SdkCommandHandler, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbEntry, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkIdbStore, SdkInitResponse, SdkKernelProxyPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorage, SdkStorageDeletePayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransport, SdkTransportPayload, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';
+export type { Application, BackendRequestOptions, BackendTransport, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, EventsApi, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphEvent, GraphEventPushPayload, GraphEventType, GraphNodeRaw, GraphTransport, GremlinOptions, HistoryEntry, HistoryOptions, HostBridge, HostBridgeConfig, InstanceList, MutationOptions, NotifyLevel, OrgMember, OrgStructure, OrgUnit, OsConfig, OsRequestOptions, OsTransport, QueryOptions, SdkChannel, SdkCommandDefinition, SdkCommandHandler, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbEntry, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkIdbStore, SdkInitResponse, SdkKernelProxyPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorage, SdkStorageDeletePayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransport, SdkTransportPayload, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';

package/dist/react.d.ts

@@ -2,12 +2,14 @@ import { type ReactNode } from 'react';
 import type { GraphEvent, HostBridge, HostBridgeConfig, NotifyLevel, OsConfig, SdkCommandDefinition, SdkCommandHandler, SdkMenuRoot } from './types.js';
 export interface AppSdkProviderProps extends HostBridgeConfig {
     children: ReactNode;
+    /** Apply theme, language and size to this document. Default: `true`; `false` when the app shares the host document. */
+    applyOsConfig?: boolean;
 }
 export interface AppCommand extends SdkCommandDefinition {
     handler: SdkCommandHandler;
 }
 /** Mounts the SDK bridge and makes it available to descendant hooks. */
-export declare function AppSdkProvider({ children, ...config }: Readonly<AppSdkProviderProps>): import("react/jsx-runtime").JSX.Element | null;
+export declare function AppSdkProvider({ children, applyOsConfig, ...config }: Readonly<AppSdkProviderProps>): import("react/jsx-runtime").JSX.Element | null;
 /** Returns the raw {@link HostBridge}. Must be used inside `<AppSdkProvider>`. */
 export declare function useSdk(): HostBridge;
 /** Returns a stable callback that fires a host notification toast. */

package/dist/react.js

@@ -2,6 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useRef, useState, } from 'react';
 import { createHostBridge } from './host-bridge.js';
 const SdkContext = createContext(null);
+// One handshake per bridge, however often the effect that owns it reconnects.
+const connections = new WeakMap();
 const SYSTEM_SIZE_CLASS_NAMES = ['text-sm', 'text-base', 'text-lg', 'text-xl'];
 function applyOsConfigToDocument(osConfig) {
     if (!osConfig) {
@@ -39,28 +41,46 @@ function hasShortcutRoots(menu) {
     return menu.some(root => hasShortcutItems(root.items));
 }
 /** Mounts the SDK bridge and makes it available to descendant hooks. */
-export function AppSdkProvider({ children, ...config }) {
+export function AppSdkProvider({ children, applyOsConfig = true, ...config }) {
     const bridgeRef = useRef(null);
-    const { appId, connectTimeout, debug, targetOrigin } = config;
+    const { appId, channel, connectTimeout, debug, targetOrigin } = config;
     const configKey = JSON.stringify([
         appId ?? null,
         connectTimeout ?? null,
         debug ?? false,
         targetOrigin ?? null,
     ]);
-    const bridgeConfig = { appId, connectTimeout, debug, targetOrigin };
+    const bridgeConfig = { appId, channel, connectTimeout, debug, targetOrigin };
     const bridgeConfigKeyRef = useRef(null);
+    const pendingDestroyRef = useRef(null);
     const [readyConfigKey, setReadyConfigKey] = useState(null);
     const [errorState, setErrorState] = useState(null);
     useEffect(() => {
         let cancelled = false;
-        setReadyConfigKey(null);
-        setErrorState(null);
-        const bridge = createHostBridge(bridgeConfig);
+        // A disconnect followed at once by a reconnect (StrictMode, Activity) keeps the live bridge:
+        // the children holding it reconnect their own effects over it before this one runs.
+        const pending = pendingDestroyRef.current;
+        pendingDestroyRef.current = null;
+        if (pending)
+            clearTimeout(pending.timer);
+        let bridge;
+        if (pending && pending.configKey === configKey && pending.channel === channel) {
+            bridge = pending.bridge;
+        }
+        else {
+            pending?.destroy();
+            setReadyConfigKey(null);
+            setErrorState(null);
+            bridge = createHostBridge(bridgeConfig);
+        }
         bridgeRef.current = bridge;
         bridgeConfigKeyRef.current = configKey;
-        bridge
-            .connect()
+        let connecting = connections.get(bridge);
+        if (!connecting) {
+            connecting = bridge.connect();
+            connections.set(bridge, connecting);
+        }
+        connecting
             .then(() => {
             if (!cancelled) {
                 setReadyConfigKey(configKey);
@@ -75,17 +95,28 @@ export function AppSdkProvider({ children, ...config }) {
         });
         return () => {
             cancelled = true;
-            bridge.destroy();
-            if (bridgeRef.current === bridge) {
-                bridgeRef.current = null;
-            }
-            if (bridgeConfigKeyRef.current === configKey) {
-                bridgeConfigKeyRef.current = null;
-            }
+            const destroy = () => {
+                bridge.destroy();
+                if (bridgeRef.current === bridge) {
+                    bridgeRef.current = null;
+                    bridgeConfigKeyRef.current = null;
+                }
+            };
+            pendingDestroyRef.current = {
+                bridge,
+                configKey,
+                channel,
+                destroy,
+                timer: setTimeout(() => {
+                    pendingDestroyRef.current = null;
+                    destroy();
+                }),
+            };
         };
-    }, [appId, configKey, connectTimeout, debug, targetOrigin]);
+    }, [appId, channel, configKey, connectTimeout, debug, targetOrigin]);
     useEffect(() => {
-        if (readyConfigKey !== configKey ||
+        if (!applyOsConfig ||
+            readyConfigKey !== configKey ||
             bridgeConfigKeyRef.current !== configKey ||
             !bridgeRef.current) {
             return;
@@ -95,7 +126,7 @@ export function AppSdkProvider({ children, ...config }) {
             applyOsConfigToDocument(newConfig);
         });
         return unsubscribe;
-    }, [configKey, readyConfigKey]);
+    }, [applyOsConfig, configKey, readyConfigKey]);
     if (errorState?.configKey === configKey) {
         return _jsx("div", { "data-sdk-error": true, children: errorState.message });
     }

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,
+            });
+        }
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { Application, Configuration, CreateMemberInput, CreateUnitInput, FileEntry, InstanceList, OrgMember, OrgStructure, OrgUnit, OsRequestOptions, SdkTransportPayload, UpdateMemberInput, UpdateUnitInput, UserProfile } from '../types.js';
+export declare function parseOsError(error: any, operation: string, context?: Record<string, unknown>): Error;
 /** OS transport class providing OS/system operations */
 export declare class OsTransport {
     private readonly _request;

package/dist/transports/os-transport.js

@@ -1,7 +1,7 @@
 import { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from '../errors.js';
 const OS_BASE = '/os';
 // Maps backend errors to typed SDK errors
-function parseOsError(error, operation, context) {
+export function parseOsError(error, operation, context) {
     let statusCode;
     let errorMessage = error.message || 'Unknown error';
     if (error.responsePayload && typeof error.responsePayload === 'object') {

package/dist/types.d.ts

@@ -168,9 +168,18 @@ export interface SdkIdbQueryPayload {
     prefix?: string;
     limit?: number;
 }
+/** How bridge messages travel between an app and its host. */
+export interface SdkChannel {
+    /** Delivers one message to the host. */
+    post(message: SdkMessage | SdkResponse): void;
+    /** Hands every message from the host to `receive`; returns the unsubscribe. */
+    subscribe(receive: (message: SdkResponse) => void): () => void;
+}
 /** Configuration passed to {@link createHostBridge}. */
 export interface HostBridgeConfig {
     appId?: string;
+    /** Message transport. Default: `postMessage` with the parent window. */
+    channel?: SdkChannel;
     /** Override the host origin for `postMessage`. Inferred from `document.referrer` by default. */
     targetOrigin?: string;
     /** Handshake timeout in ms. Default: `5000`. */
@@ -202,6 +211,7 @@ export interface SdkIdbStore {
 export interface SdkTransport {
     graph: GraphTransport;
     os: OsTransport;
+    backend(routeKey: string): BackendTransport;
 }
 /** Graph node in raw backend format (ogit/* fields) */
 export interface GraphNodeRaw {
@@ -363,6 +373,7 @@ export interface OsRequestOptions extends TransportScopeOptions {
     contentType?: string;
     scopePolicy?: 'none' | 'optional' | 'required';
 }
+export type BackendRequestOptions = OsRequestOptions;
 /** Live connection between an iframe app and its host OS. */
 export interface HostBridge {
     /** Perform the SDK handshake. Resolves with host context. Cached after first call. */
@@ -392,3 +403,4 @@ export interface HostBridge {
 /** Forward declarations for transport classes */
 export type GraphTransport = import('./transports/graph-transport.js').GraphTransport;
 export type OsTransport = import('./transports/os-transport.js').OsTransport;
+export type BackendTransport = import('./transports/backend-transport.js').BackendTransport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bardioc/app-sdk",
-  "version": "0.4.10",
+  "version": "0.5.0",
   "description": "SDK for building apps for the Bardioc OS",
   "license": "MIT",
   "private": false,