@beacon-build/sdk 1.18.0 → 1.18.1

package/dist/react/RealtimeProvider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * RealtimeProvider — F141
+ *
+ * Context provider for the beacon Realtime SSE client.
+ * Wrap your app with <RealtimeProvider baseUrl authToken> to enable useRealtime().
+ *
+ * INV-19: useRealtime() without <RealtimeProvider> throws RealtimeProviderNotFoundError.
+ */
+import React from 'react';
+export interface RealtimeContextValue {
+    baseUrl: string;
+    authToken: string;
+}
+export declare class RealtimeProviderNotFoundError extends Error {
+    constructor();
+}
+export interface RealtimeProviderProps {
+    /** API base URL, e.g. 'https://api.beacon.build' */
+    baseUrl: string;
+    /** User-JWT or Agent-JWT */
+    authToken: string;
+    children: React.ReactNode;
+}
+export declare const RealtimeProvider: React.FC<RealtimeProviderProps>;
+/**
+ * Internal hook — reads RealtimeContext. Throws RealtimeProviderNotFoundError
+ * if called outside of <RealtimeProvider>.
+ */
+export declare function useRealtimeContext(): RealtimeContextValue;
+//# sourceMappingURL=RealtimeProvider.d.ts.map

package/dist/react/RealtimeProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RealtimeProvider.d.ts","sourceRoot":"","sources":["../../src/react/RealtimeProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAoC,MAAM,OAAO,CAAA;AAIxD,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CACpB;AAMD,qBAAa,6BAA8B,SAAQ,KAAK;;CAQvD;AAID,MAAM,WAAW,qBAAqB;IAClC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC5B;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAU5D,CAAA;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,oBAAoB,CAIzD"}

package/dist/react/RealtimeProvider.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * RealtimeProvider — F141
+ *
+ * Context provider for the beacon Realtime SSE client.
+ * Wrap your app with <RealtimeProvider baseUrl authToken> to enable useRealtime().
+ *
+ * INV-19: useRealtime() without <RealtimeProvider> throws RealtimeProviderNotFoundError.
+ */
+import { createContext, useContext } from 'react';
+const RealtimeContext = createContext(null);
+// ─── Error ────────────────────────────────────────────────────────────────────
+export class RealtimeProviderNotFoundError extends Error {
+    constructor() {
+        super('useRealtime() was called outside of <RealtimeProvider>. ' +
+            'Wrap your app with <RealtimeProvider baseUrl={...} authToken={...}>.');
+        this.name = 'RealtimeProviderNotFoundError';
+    }
+}
+export const RealtimeProvider = ({ baseUrl, authToken, children, }) => {
+    return (_jsx(RealtimeContext.Provider, { value: { baseUrl, authToken }, children: children }));
+};
+// ─── Context hook ─────────────────────────────────────────────────────────────
+/**
+ * Internal hook — reads RealtimeContext. Throws RealtimeProviderNotFoundError
+ * if called outside of <RealtimeProvider>.
+ */
+export function useRealtimeContext() {
+    const ctx = useContext(RealtimeContext);
+    if (!ctx)
+        throw new RealtimeProviderNotFoundError();
+    return ctx;
+}
+//# sourceMappingURL=RealtimeProvider.js.map

package/dist/react/RealtimeProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RealtimeProvider.js","sourceRoot":"","sources":["../../src/react/RealtimeProvider.tsx"],"names":[],"mappings":";AAAA;;;;;;;GAOG;AAEH,OAAc,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AASxD,MAAM,eAAe,GAAG,aAAa,CAA8B,IAAI,CAAC,CAAA;AAExE,iFAAiF;AAEjF,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACpD;QACI,KAAK,CACD,0DAA0D;YACtD,sEAAsE,CAC7E,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAA;IAC/C,CAAC;CACJ;AAYD,MAAM,CAAC,MAAM,gBAAgB,GAAoC,CAAC,EAC9D,OAAO,EACP,SAAS,EACT,QAAQ,GACX,EAAE,EAAE;IACD,OAAO,CACH,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,YAClD,QAAQ,GACc,CAC9B,CAAA;AACL,CAAC,CAAA;AAED,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAC9B,MAAM,GAAG,GAAG,UAAU,CAAC,eAAe,CAAC,CAAA;IACvC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,6BAA6B,EAAE,CAAA;IACnD,OAAO,GAAG,CAAA;AACd,CAAC"}

package/dist/react/index.d.ts

@@ -0,0 +1,5 @@
+export { RealtimeProvider, useRealtimeContext, RealtimeProviderNotFoundError, } from './RealtimeProvider.js';
+export type { RealtimeProviderProps, RealtimeContextValue } from './RealtimeProvider.js';
+export { useRealtime } from './useRealtime.js';
+export type { UseRealtimeOptions, UseRealtimeResult } from './useRealtime.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACH,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,GAChC,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAExF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/react/index.js

@@ -0,0 +1,7 @@
+// ─── React Integration for @beacon-build/sdk (F141) ───────────────────────────
+//
+// These exports moved from @beacon-build/ui → @beacon-build/sdk (C128).
+// Consumers should import directly from @beacon-build/sdk.
+export { RealtimeProvider, useRealtimeContext, RealtimeProviderNotFoundError, } from './RealtimeProvider.js';
+export { useRealtime } from './useRealtime.js';
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,EAAE;AACF,wEAAwE;AACxE,2DAA2D;AAE3D,OAAO,EACH,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,GAChC,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/react/useRealtime.d.ts

@@ -0,0 +1,30 @@
+/**
+ * useRealtime — F141
+ *
+ * Thin React wrapper over RealtimeSdkClient.
+ * Subscribes to one or more channels and calls onEvent when an event arrives.
+ *
+ * Lifecycle:
+ * - Connects on mount (if enabled !== false).
+ * - Disconnects on unmount (INV-13).
+ * - React StrictMode-compatible: double-mount produces effectively one connection
+ *   after the cleanup cycle.
+ * - Reconnects when channels string representation changes.
+ *
+ * INV-19: Must be used inside <RealtimeProvider>. Throws RealtimeProviderNotFoundError otherwise.
+ */
+import type { RealtimeChannel, RealtimeEventType } from '@beacon-build/core';
+export interface UseRealtimeOptions<T extends Record<string, unknown> = Record<string, unknown>> {
+    channels: RealtimeChannel[];
+    eventType: RealtimeEventType;
+    onEvent: (data: T) => void;
+    /** default: true */
+    enabled?: boolean;
+    onError?: (error: Error) => void;
+}
+export interface UseRealtimeResult {
+    isConnected: boolean;
+    error: Error | null;
+}
+export declare function useRealtime<T extends Record<string, unknown> = Record<string, unknown>>(options: UseRealtimeOptions<T>): UseRealtimeResult;
+//# sourceMappingURL=useRealtime.d.ts.map

package/dist/react/useRealtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRealtime.d.ts","sourceRoot":"","sources":["../../src/react/useRealtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAK5E,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3F,QAAQ,EAAE,eAAe,EAAE,CAAA;IAC3B,SAAS,EAAE,iBAAiB,CAAA;IAC5B,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;IAC1B,oBAAoB;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,iBAAiB;IAC9B,WAAW,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACtB;AAID,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnF,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,iBAAiB,CAkDnB"}

package/dist/react/useRealtime.js

@@ -0,0 +1,63 @@
+/**
+ * useRealtime — F141
+ *
+ * Thin React wrapper over RealtimeSdkClient.
+ * Subscribes to one or more channels and calls onEvent when an event arrives.
+ *
+ * Lifecycle:
+ * - Connects on mount (if enabled !== false).
+ * - Disconnects on unmount (INV-13).
+ * - React StrictMode-compatible: double-mount produces effectively one connection
+ *   after the cleanup cycle.
+ * - Reconnects when channels string representation changes.
+ *
+ * INV-19: Must be used inside <RealtimeProvider>. Throws RealtimeProviderNotFoundError otherwise.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { RealtimeSdkClient } from '../realtime/realtime.client.js';
+import { useRealtimeContext } from './RealtimeProvider.js';
+// ─── Hook ─────────────────────────────────────────────────────────────────────
+export function useRealtime(options) {
+    const { baseUrl, authToken } = useRealtimeContext();
+    const [isConnected, setIsConnected] = useState(false);
+    const [error, setError] = useState(null);
+    // Stable refs for handlers — avoids triggering re-connects on every render
+    const onEventRef = useRef(options.onEvent);
+    onEventRef.current = options.onEvent;
+    const onErrorRef = useRef(options.onError);
+    onErrorRef.current = options.onError;
+    const enabled = options.enabled !== false;
+    // Serialize channels for deep-compare in useEffect deps
+    const channelsKey = options.channels.slice().sort().join(',');
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const client = new RealtimeSdkClient({
+            baseUrl,
+            authToken,
+            channels: options.channels,
+            onConnect: () => {
+                setIsConnected(true);
+                setError(null);
+            },
+            onDisconnect: () => {
+                setIsConnected(false);
+            },
+            onError: (err) => {
+                setError(err);
+                onErrorRef.current?.(err);
+            },
+        });
+        client.on(options.eventType, (data) => {
+            onEventRef.current(data);
+        });
+        client.connect();
+        return () => {
+            client.disconnect();
+            setIsConnected(false);
+        };
+        // channelsKey covers the channels array. authToken + baseUrl + eventType are stable by convention.
+    }, [baseUrl, authToken, channelsKey, options.eventType, enabled]);
+    return { isConnected, error };
+}
+//# sourceMappingURL=useRealtime.js.map

package/dist/react/useRealtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRealtime.js","sourceRoot":"","sources":["../../src/react/useRealtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAElE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAkB1D,iFAAiF;AAEjF,MAAM,UAAU,WAAW,CACvB,OAA8B;IAE9B,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,kBAAkB,EAAE,CAAA;IACnD,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IACrD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAA;IAEtD,2EAA2E;IAC3E,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1C,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;IACpC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1C,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;IAEpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,KAAK,KAAK,CAAA;IAEzC,wDAAwD;IACxD,MAAM,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAE7D,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,OAAO;YAAE,OAAM;QAEpB,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;YACjC,OAAO;YACP,SAAS;YACT,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,SAAS,EAAE,GAAG,EAAE;gBACZ,cAAc,CAAC,IAAI,CAAC,CAAA;gBACpB,QAAQ,CAAC,IAAI,CAAC,CAAA;YAClB,CAAC;YACD,YAAY,EAAE,GAAG,EAAE;gBACf,cAAc,CAAC,KAAK,CAAC,CAAA;YACzB,CAAC;YACD,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACb,QAAQ,CAAC,GAAG,CAAC,CAAA;gBACb,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAA;YAC7B,CAAC;SACJ,CAAC,CAAA;QAEF,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;YAClC,UAAU,CAAC,OAAO,CAAC,IAAS,CAAC,CAAA;QACjC,CAAC,CAAC,CAAA;QAEF,MAAM,CAAC,OAAO,EAAE,CAAA;QAEhB,OAAO,GAAG,EAAE;YACR,MAAM,CAAC,UAAU,EAAE,CAAA;YACnB,cAAc,CAAC,KAAK,CAAC,CAAA;QACzB,CAAC,CAAA;QACD,mGAAmG;IACvG,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA;IAEjE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC"}

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@beacon-build/sdk",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    }
+  },
   "files": [
     "dist",
     "README.md",
@@ -13,11 +23,22 @@
   "dependencies": {
     "@types/event-source-polyfill": "^1.0.5",
     "event-source-polyfill": "^1.0.31",
-    "@beacon-build/core": "1.18.0"
+    "@beacon-build/core": "1.18.1"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^4.7.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "vitest": "^4.1.2"
   },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"