@bardioc/app-sdk 0.4.0 → 0.4.2

package/dist/contract-matrix.d.ts

@@ -108,6 +108,24 @@ export declare const SDK_CONTRACT_MATRIX: {
         readonly permission: null;
         readonly expectedHostBehavior: "Host-to-app command callback delivery.";
     };
+    readonly SDK_EVENT_SUBSCRIBE: {
+        readonly requestPayload: "EventSubscribeRequest";
+        readonly responsePayload: "EventSubscribeResponse";
+        readonly permission: "events";
+        readonly expectedHostBehavior: "Open a scoped graph-event SSE stream for the requested OGIT types.";
+    };
+    readonly SDK_EVENT_UNSUBSCRIBE: {
+        readonly requestPayload: "EventUnsubscribeRequest";
+        readonly responsePayload: "{ ok: true }";
+        readonly permission: "events";
+        readonly expectedHostBehavior: "Close the graph-event SSE stream for the given subscription.";
+    };
+    readonly SDK_GRAPH_EVENT: {
+        readonly requestPayload: "GraphEventPushPayload";
+        readonly responsePayload: null;
+        readonly permission: null;
+        readonly expectedHostBehavior: "Host-to-app graph-event push delivery (no ack).";
+    };
     readonly SDK_OS_CONFIG_UPDATE: {
         readonly requestPayload: "OsConfig";
         readonly responsePayload: null;

package/dist/contract-matrix.js

@@ -108,6 +108,24 @@ export const SDK_CONTRACT_MATRIX = {
         permission: null,
         expectedHostBehavior: 'Host-to-app command callback delivery.',
     },
+    [SDK_MSG.EVENT_SUBSCRIBE]: {
+        requestPayload: 'EventSubscribeRequest',
+        responsePayload: 'EventSubscribeResponse',
+        permission: 'events',
+        expectedHostBehavior: 'Open a scoped graph-event SSE stream for the requested OGIT types.',
+    },
+    [SDK_MSG.EVENT_UNSUBSCRIBE]: {
+        requestPayload: 'EventUnsubscribeRequest',
+        responsePayload: '{ ok: true }',
+        permission: 'events',
+        expectedHostBehavior: 'Close the graph-event SSE stream for the given subscription.',
+    },
+    [SDK_MSG.GRAPH_EVENT]: {
+        requestPayload: 'GraphEventPushPayload',
+        responsePayload: null,
+        permission: null,
+        expectedHostBehavior: 'Host-to-app graph-event push delivery (no ack).',
+    },
     [SDK_MSG.OS_CONFIG_UPDATE]: {
         requestPayload: 'OsConfig',
         responsePayload: null,

package/dist/host-bridge.js

@@ -45,6 +45,7 @@ export function createHostBridge(config) {
     let _destroyed = false;
     const commandHandlers = new Map();
     const osConfigUpdateCallbacks = new Set();
+    const eventHandlers = new Map();
     const pending = new Map();
     function isAllowedMessageOrigin(origin) {
         return origin === targetOrigin || origin === hostWindow.location.origin;
@@ -80,6 +81,19 @@ export function createHostBridge(config) {
             }
         }
     }
+    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) {
@@ -110,6 +124,9 @@ export function createHostBridge(config) {
             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);
@@ -178,6 +195,27 @@ export function createHostBridge(config) {
             }),
         };
     }
+    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;
@@ -199,6 +237,7 @@ export function createHostBridge(config) {
         storage,
         transport,
         idb,
+        events,
         setCommands(commands) {
             const payload = { commands };
             return request(SDK_MSG.SET_COMMANDS, payload);
@@ -246,6 +285,16 @@ export function createHostBridge(config) {
             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;
             hostWindow.removeEventListener('message', onMessage);
             for (const [, p] of pending)

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { createHostBridge } from './host-bridge.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
 export type { AppManifest, AppManifestPermission, AppManifestWindowConfig, CustomWindowSize, WindowSizePreset, } from './manifest.js';
-export { useOsConfig } from './react.js';
+export { useGraphEvents, useOsConfig } from './react.js';
 export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contract-matrix.js';
 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, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, FileEntry, GetNodeOptions, GraphEdgeRaw, 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, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';
+export type { Application, BatchResult, 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, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { createHostBridge } from './host-bridge.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
-export { useOsConfig } from './react.js';
+export { useGraphEvents, useOsConfig } from './react.js';
 export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contract-matrix.js';
 export { ALLOWED_KERNEL_MESSAGES, SDK_MSG } from './protocol.js';
 export { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from './errors.js';

package/dist/manifest.d.ts

@@ -1,5 +1,5 @@
 /** Schema for `public/app-manifest.json` — required in every iframe app's build output. */
-export type AppManifestPermission = 'notify' | 'storage' | 'indexdb' | 'kernel-proxy' | 'transport';
+export type AppManifestPermission = 'notify' | 'storage' | 'indexdb' | 'kernel-proxy' | 'transport' | 'events';
 export interface CustomWindowSize {
     width: number;
     height: number;

package/dist/manifest.js

@@ -17,6 +17,7 @@ const VALID_PERMISSIONS = new Set([
     // Deprecated: legacy/internal only. Do not request for normal hosted apps.
     'kernel-proxy',
     'transport',
+    'events',
 ]);
 function validateBooleanField(value, fieldPath, errors) {
     if (value !== undefined && typeof value !== 'boolean') {

package/dist/protocol.d.ts

@@ -1,4 +1,4 @@
-export type { SdkCommandDefinition, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransportPayload, } from './types.js';
+export type { EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, GraphEvent, GraphEventPushPayload, GraphEventType, SdkCommandDefinition, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransportPayload, } from './types.js';
 export declare const ALLOWED_KERNEL_MESSAGES: ReadonlySet<string>;
 export declare const SDK_MSG: {
     readonly INIT: "SDK_INIT";
@@ -22,5 +22,8 @@ export declare const SDK_MSG: {
     readonly IDB_QUERY: "SDK_IDB_QUERY";
     readonly LAUNCH_APP: "SDK_LAUNCH_APP";
     readonly OS_CONFIG_UPDATE: "SDK_OS_CONFIG_UPDATE";
+    readonly EVENT_SUBSCRIBE: "SDK_EVENT_SUBSCRIBE";
+    readonly EVENT_UNSUBSCRIBE: "SDK_EVENT_UNSUBSCRIBE";
+    readonly GRAPH_EVENT: "SDK_GRAPH_EVENT";
 };
 export type SdkMessageType = (typeof SDK_MSG)[keyof typeof SDK_MSG];

package/dist/protocol.js

@@ -25,4 +25,7 @@ export const SDK_MSG = {
     IDB_QUERY: 'SDK_IDB_QUERY',
     LAUNCH_APP: 'SDK_LAUNCH_APP',
     OS_CONFIG_UPDATE: 'SDK_OS_CONFIG_UPDATE',
+    EVENT_SUBSCRIBE: 'SDK_EVENT_SUBSCRIBE',
+    EVENT_UNSUBSCRIBE: 'SDK_EVENT_UNSUBSCRIBE',
+    GRAPH_EVENT: 'SDK_GRAPH_EVENT',
 };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import { type DevAuthStorageOptions } from './dev.js';
-import type { HostBridge, HostBridgeConfig, NotifyLevel, OsConfig, SdkCommandDefinition, SdkCommandHandler, SdkMenuRoot } from './types.js';
+import type { GraphEvent, HostBridge, HostBridgeConfig, NotifyLevel, OsConfig, SdkCommandDefinition, SdkCommandHandler, SdkMenuRoot } from './types.js';
 export interface AppSdkProviderProps extends HostBridgeConfig {
     children: ReactNode;
 }
@@ -22,5 +22,13 @@ export declare function useActiveTab(activeTab: string | null): void;
  * Automatically subscribes to updates and returns the latest values.
  */
 export declare function useOsConfig(): OsConfig | null;
+/**
+ * Subscribes to live graph events for the given OGIT types while mounted.
+ * The handler is kept in a ref so its identity may change without resubscribing;
+ * the subscription is recreated only when `types` (or extra `deps`) change.
+ */
+export declare function useGraphEvents(options: {
+    types: string[];
+}, handler: (event: GraphEvent) => void, deps?: React.DependencyList): void;
 /** Returns a stable callback that clears standalone dev auth state and reloads the page. */
 export declare function useStandaloneDevLogout(options: DevAuthStorageOptions): () => void;

package/dist/react.js

@@ -199,6 +199,22 @@ export function useOsConfig() {
     }, [bridge]);
     return osConfig;
 }
+/**
+ * Subscribes to live graph events for the given OGIT types while mounted.
+ * The handler is kept in a ref so its identity may change without resubscribing;
+ * the subscription is recreated only when `types` (or extra `deps`) change.
+ */
+export function useGraphEvents(options, handler, deps = []) {
+    const bridge = useSdk();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const typesKey = JSON.stringify(options.types);
+    useEffect(() => {
+        const unsubscribe = bridge.events.subscribe({ types: JSON.parse(typesKey) }, event => handlerRef.current(event));
+        return unsubscribe;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [bridge, typesKey, ...deps]);
+}
 /** Returns a stable callback that clears standalone dev auth state and reloads the page. */
 export function useStandaloneDevLogout(options) {
     return useCallback(() => {

package/dist/types.d.ts

@@ -84,6 +84,42 @@ export interface SdkShortcutEventPayload {
     altKey: boolean;
     shiftKey: boolean;
 }
+/** Mirrors the BFF `GraphEvent` SSE contract delivered by the host. */
+export type GraphEventType = 'CREATE' | 'REPLACE' | 'UPDATE' | 'CONNECT' | 'DISCONNECT' | 'DELETE' | 'WRITE_TIMESERIES';
+export interface GraphEvent {
+    id: string;
+    type: GraphEventType;
+    timestamp: number;
+    nanotime?: number;
+    body?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface EventSubscribeRequest {
+    /** App-generated subscription id, echoed by the host and stamped on pushes. */
+    subscriptionId: string;
+    /** OGIT types to subscribe to, e.g. `['ogit/Documents/Document']`. */
+    types: string[];
+}
+export interface EventSubscribeResponse {
+    subscriptionId: string;
+}
+export interface EventUnsubscribeRequest {
+    subscriptionId: string;
+}
+export interface GraphEventPushPayload {
+    subscriptionId: string;
+    event: GraphEvent;
+}
+/** Live graph-event subscription surface exposed to hosted apps. */
+export interface EventsApi {
+    /**
+     * Subscribe to graph mutations for the given OGIT types. Returns an
+     * unsubscribe function; the handler fires for each matching event.
+     */
+    subscribe(options: {
+        types: string[];
+    }, handler: (event: GraphEvent) => void): () => void;
+}
 export type NotifyLevel = 'success' | 'error' | 'info' | 'warning';
 export interface SdkNotifyPayload {
     message: string;
@@ -325,6 +361,7 @@ export interface HostBridge {
     storage: SdkStorage;
     idb(storeName: string): SdkIdbStore;
     transport: SdkTransport;
+    events: EventsApi;
     setCommands(commands: SdkCommandDefinition[]): Promise<void>;
     setMenu(menu: SdkMenuRoot[] | null): Promise<void>;
     setActiveTab(activeTab: string | null): Promise<void>;

package/package.json

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