@multiplatform.one/frappe 6.6.0 → 6.7.0

package/types/realtime.d.ts

@@ -6,6 +6,90 @@ export declare enum RealtimePlatform {
     Web = "web",
     ReactNative = "react-native"
 }
+export type RealtimeTransport = "socketio" | "sse";
+/** One SSE frame as received off the wire (before any mapping). */
+export interface SSEFrame {
+    /** SSE event type — the `event:` classification line, or `"message"` for unnamed frames. */
+    type: string;
+    /** Raw `data:` payload (SSE data is always a string). */
+    data: string;
+    /** The stream's last `id:` line as of this frame (empty when the server sent none). */
+    lastEventId: string;
+}
+/** One handler-map delivery produced by `RealtimeSSEConfig.mapFrame`. */
+export interface SSEMappedEvent {
+    event: string;
+    payload: unknown;
+}
+/** Minimal structural slice of a WHATWG `MessageEvent` the SSE transport reads. */
+export interface SSEMessageEventLike {
+    type?: string;
+    data?: unknown;
+    lastEventId?: string;
+}
+/**
+ * Minimal structural slice of the WHATWG EventSource interface used by the
+ * SSE transport. The global browser/Node implementation satisfies it, and so
+ * do the common polyfills (`eventsource` on npm, `react-native-sse`).
+ */
+export interface SSEEventSourceLike {
+    addEventListener(type: string, listener: (event: SSEMessageEventLike) => void): void;
+    removeEventListener(type: string, listener: (event: SSEMessageEventLike) => void): void;
+    close(): void;
+}
+export type SSEEventSourceConstructor = new (url: string, init?: {
+    withCredentials?: boolean;
+}) => SSEEventSourceLike;
+export interface RealtimeSSEConfig {
+    /** Absolute stream URL. Wins over `path` when both are set. */
+    url?: string;
+    /**
+     * Stream path resolved against `baseURL` (e.g.
+     * `"/api/method/shc.events.stream"` for the SHC daemon). One of `url` or
+     * `path` is REQUIRED: SSE endpoints are server-specific — a real Frappe
+     * bench has none at all — so a framework default would only ever 404, and
+     * `connect()` throws a descriptive error instead of guessing.
+     */
+    path?: string;
+    /**
+     * Browser EventSource credential mode: send cookies on the stream request.
+     * This is the primary browser auth path — EventSource cannot set request
+     * headers, so header-based token auth is impossible there (see
+     * `queryParams` for the token alternative).
+     */
+    withCredentials?: boolean;
+    /**
+     * Injectable EventSource constructor for runtimes without a global one
+     * (React Native, Node < 22, GJS) — e.g. the `eventsource` npm package or
+     * `react-native-sse`. When omitted the global `EventSource` is used, and
+     * `connect()` throws an error naming this option when neither exists.
+     */
+    EventSource?: SSEEventSourceConstructor;
+    /**
+     * Named SSE event types (`event:` classification lines) to listen for, in
+     * addition to unnamed `"message"` frames and handler-registered names.
+     * EventSource only dispatches a NAMED event when a listener for that exact
+     * type is attached, so `mapFrame`-driven apps — whose handler names differ
+     * from the wire's frame types — must list the server's classifications
+     * here (e.g. `["docker", "audit", "error", "event"]` for the SHC daemon).
+     */
+    events?: string[];
+    /**
+     * Translate one SSE frame into zero or more handler deliveries. Return
+     * `null`/`undefined` to drop the frame. When omitted, the default mapping
+     * delivers under the frame's `event:` type name with `JSON.parse(data)` as
+     * the payload (falling back to the raw string when the data isn't JSON).
+     */
+    mapFrame?: (frame: SSEFrame) => SSEMappedEvent[] | null | undefined;
+    /**
+     * Extra query parameters appended to the stream URL — the token-auth path
+     * for SSE (headers are off-limits in browsers, see `withCredentials`).
+     * Values may be getters; they are re-resolved every time the EventSource
+     * is (re)created, so a rotated token is picked up by `updateAuth()`'s
+     * reconnect.
+     */
+    queryParams?: Record<string, string | (() => string | Promise<string>)>;
+}
 export interface RealtimeConfig {
     auth?: AuthConfig;
     baseURL: string;
@@ -37,14 +121,49 @@ export interface RealtimeConfig {
     siteName?: string;
     platform?: RealtimePlatform;
     socketOptions?: Partial<ManagerOptions & SocketOptions>;
+    /**
+     * Wire transport for realtime events.
+     *
+     * - `"socketio"` (default): Frappe's real realtime server — Socket.IO with
+     *   doc/doctype rooms and two-way subscribe emits. Omitting `transport`
+     *   keeps this exact behavior.
+     * - `"sse"`: a one-way `text/event-stream` endpoint consumed via
+     *   EventSource. Built for Frappe-wire-compatible servers that serve
+     *   realtime as SSE instead of Socket.IO (e.g. the SHC daemon's
+     *   `GET /api/method/shc.events.stream`). Requires `sse.url` or `sse.path`.
+     *   Room subscriptions become client-side bookkeeping (nothing can be
+     *   emitted upstream) and `sse.mapFrame` decides how server frames fan out
+     *   to handler events. Missed-event resume via the `Last-Event-ID` header
+     *   is native EventSource behavior and is not reimplemented here.
+     */
+    transport?: RealtimeTransport;
+    /** SSE transport options — only read when `transport` is `"sse"`. */
+    sse?: RealtimeSSEConfig;
 }
+export type DocRoom = {
+    doctype: string;
+    name: string;
+};
+export type ListRoom = {
+    doctype: string;
+    filters?: Record<string, unknown>;
+};
 export declare class RealtimeModule {
     private socket;
+    /** Live EventSource when the `"sse"` transport is active. */
+    private eventSource;
     private handlerMap;
     /** Tracks events with socket listeners attached to prevent duplicates. */
     private attachedSocketEvents;
     /** Stored socket event handler references for proper cleanup. */
     private socketEventHandlers;
+    /** Tracks SSE event types with listeners attached to prevent duplicates. */
+    private attachedSseEvents;
+    /** Stored SSE listener references for proper cleanup. */
+    private sseListeners;
+    /** One-shot debug notices for SSE's one-way limitations. */
+    private sseRoomNoticeLogged;
+    private sseEmitNoticeLogged;
     /** Active doc rooms — re-emitted on every (re)connect. */
     private docRooms;
     /** Active list rooms — re-emitted on every (re)connect. */
@@ -70,10 +189,46 @@ export declare class RealtimeModule {
      */
     private refreshSocketAuth;
     private resolveHealthyWaiters;
+    private isSSE;
     private waitUntilHealthy;
     private ensureConnected;
     private resubscribeRooms;
-    private connect;
+    /**
+     * Open the realtime transport now. Room-driven auto-connect
+     * (subscribeDoc/subscribeList) remains the primary lifecycle in both
+     * transports — this is public for SSE consumers that use no doc/list room
+     * bookkeeping: a one-way stream has nothing to emit on join, so nothing
+     * else would ever open it. Idempotent while a transport exists or a
+     * connect is in flight.
+     */
+    connect(): Promise<void>;
+    /**
+     * SSE branch of connect(): construct an EventSource against the configured
+     * stream URL. EventSource connects at construction, auto-reconnects on
+     * failure, and resumes missed frames itself by sending the stream's last
+     * `id:` as the `Last-Event-ID` request header — none of that is
+     * reimplemented here.
+     */
+    private connectSSE;
+    private buildSSEURL;
+    private initSSEHandlers;
+    private attachSSEListener;
+    private detachSSEListener;
+    private isCoreSSEType;
+    /**
+     * Single entry point for everything the EventSource dispatches. Dataless
+     * events are transport lifecycle (`open`/`error` as plain Events); anything
+     * carrying `data` is a server frame — including frames the server
+     * classified `event: error`, which arrive as MessageEvents WITH data and
+     * must not be mistaken for connection errors.
+     */
+    private handleSSEEvent;
+    /**
+     * Logged once: SSE is one-way, so doc/list room membership can't be sent
+     * upstream — rooms are recorded client-side (see getDocRooms/getListRooms)
+     * for mapFrame-driven filtering and for a future two-way transport.
+     */
+    private logSSERoomNoticeOnce;
     /**
      * Tear down the socket without clearing app handlers or room subscriptions.
      * Used by auth refresh so listeners/rooms survive credential rotation.
@@ -117,5 +272,15 @@ export declare class RealtimeModule {
     updateAuth(auth: AuthConfig): Promise<void>;
     emit(event: string, data: unknown): void;
     getSocket(): Socket<import("@socket.io/component-emitter").DefaultEventsMap, import("@socket.io/component-emitter").DefaultEventsMap> | undefined;
+    /** Live EventSource when the SSE transport is connected (undefined otherwise). */
+    getEventSource(): SSEEventSourceLike | undefined;
+    /**
+     * Doc rooms recorded by subscribeDoc. Under SSE these are client-side
+     * bookkeeping only (nothing is emitted upstream) — mapFrame-driven apps
+     * consult them to filter or route frames.
+     */
+    getDocRooms(): DocRoom[];
+    /** List rooms recorded by subscribeList — same client-side semantics as getDocRooms. */
+    getListRooms(): ListRoom[];
 }
 //# sourceMappingURL=realtime.d.ts.map

package/types/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEjD,oBAAY,gBAAgB;IAC1B,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,WAAW,iBAAiB;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,CAAC;CACzD;AASD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAmC;IACrD,0EAA0E;IAC1E,OAAO,CAAC,oBAAoB,CAAqB;IACjD,iEAAiE;IACjE,OAAO,CAAC,mBAAmB,CAAiD;IAC5E,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAA8B;IAC9C,2DAA2D;IAC3D,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,MAAM,CAAiB;IAC/B,oEAAoE;IACpE,OAAO,CAAC,mBAAmB,CAAC,CAAgB;gBAEhC,MAAM,EAAE,cAAc;IAOlC,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,YAAY;YA0BN,cAAc;IA2D5B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,gBAAgB;YAeV,eAAe;IAQ7B,OAAO,CAAC,gBAAgB;YAYV,OAAO;IA0CrB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,YAAY;IAwCpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,cAAc;IAQhB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAUpC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQnD;;;;;;OAMG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtF,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQtC;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IASxB,SAAS;IAIT,UAAU,IAAI,IAAI;IAOZ,UAAU,CAAC,IAAI,EAAE,UAAU;IAejC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;IAMjC,SAAS;CAGV"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}