@digimuza/saas-core 0.0.2

package/dist/streams/client.d.ts

@@ -0,0 +1,91 @@
+import { Observable } from "rxjs";
+/**
+ * Client-side realtime, as an Observable over the SSE endpoint.
+ *
+ * Deliberately standalone: this module imports nothing from the server half of
+ * the package — no config, no database, no transport. It runs in a browser, and a
+ * shared import would drag server code into the bundle.
+ *
+ * It is also the *shared* abstraction the architecture calls for. Every component
+ * piping this one stream beats each of them opening its own `EventSource`: one
+ * connection, one reconnect policy, one place to reason about ordering.
+ */
+/** The subset of `EventSource` this module uses. */
+export interface EventSourceLike {
+    addEventListener(type: string, listener: (event: MessageEventLike) => void): void;
+    close(): void;
+    readonly readyState?: number;
+}
+export interface MessageEventLike {
+    readonly data?: unknown;
+    readonly lastEventId?: string;
+}
+/** A realtime message as it arrives in the browser. */
+export interface ClientRealtimeMessage {
+    readonly channel: string;
+    readonly eventId: string;
+    readonly type: string;
+    readonly occurredAt: string;
+    readonly data?: unknown;
+    /** True when the payload was too large to carry; re-read the event by id. */
+    readonly truncated?: boolean;
+}
+export interface EventStreamSourceOptions {
+    /** Endpoint serving the stream, e.g. `/api/realtime`. */
+    readonly url: string;
+    /** Channels to request. Appended as repeated `channel` query parameters. */
+    readonly channels: readonly string[];
+    /**
+     * Event types to listen for.
+     *
+     * Required because SSE dispatches by event name, and the server names each
+     * frame after the event type. Listening for `message` alone would receive
+     * nothing.
+     */
+    readonly types: readonly string[];
+    /**
+     * Construct the underlying source. Defaults to the global `EventSource`.
+     * Injectable so reconnect behaviour is testable without a browser.
+     */
+    readonly createSource?: (url: string) => EventSourceLike;
+    /** First reconnect delay, doubling up to {@link maxRetryDelayMs}. */
+    readonly initialRetryDelayMs?: number;
+    readonly maxRetryDelayMs?: number;
+    /** Called on every transport error, before the reconnect is scheduled. */
+    readonly onError?: (error: unknown) => void;
+    /** Injectable clock, so tests need no real waiting. */
+    readonly setTimeoutImpl?: (handler: () => void, ms: number) => unknown;
+    readonly clearTimeoutImpl?: (handle: unknown) => void;
+}
+export declare function buildStreamUrl(url: string, channels: readonly string[]): string;
+/**
+ * Subscribe to the server's SSE endpoint, reconnecting with exponential backoff.
+ *
+ * ```ts
+ * const events$ = fromEventStream({
+ *   url: "/api/realtime",
+ *   channels: [`workspace:${workspaceId}`],
+ *   types: ["project.created", "job.progress"],
+ * });
+ *
+ * const sub = events$.pipe(
+ *   filter((message) => message.type === "job.progress"),
+ *   map((message) => message.data as { percent?: number }),
+ *   distinctUntilChanged((a, b) => a.percent === b.percent),
+ * ).subscribe(render);
+ *
+ * // Every subscription needs a lifecycle. In React, this is the effect cleanup.
+ * return () => sub.unsubscribe();
+ * ```
+ *
+ * The Observable never completes on its own — a realtime stream has no natural
+ * end. It stays open until unsubscribed, so bound it with `takeUntil` if
+ * something else should end it.
+ *
+ * Errors do **not** terminate the stream. A dropped connection is expected, not
+ * exceptional: it is reported through `onError` and then retried, because
+ * surfacing it as an RxJS error would tear down every downstream operator and
+ * lose the subscriber's accumulated state on a transient blip.
+ */
+export declare function fromEventStream(options: EventStreamSourceOptions): Observable<ClientRealtimeMessage>;
+//# sourceMappingURL=client.d.ts.map

package/dist/streams/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/streams/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAiB,MAAM,MAAM,CAAC;AAEjD;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAAC;IAClF,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,eAAe,CAAC;IACzD,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACvE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACvD;AAKD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAQ/E;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,wBAAwB,GAChC,UAAU,CAAC,qBAAqB,CAAC,CAgFnC"}

package/dist/streams/client.js

@@ -0,0 +1,128 @@
+import { Observable } from "rxjs";
+const DEFAULT_INITIAL_RETRY_MS = 1_000;
+const DEFAULT_MAX_RETRY_MS = 30_000;
+export function buildStreamUrl(url, channels) {
+    // Relative endpoints are normal in a browser, so a base is supplied and then
+    // discarded rather than requiring an absolute URL.
+    const parsed = new URL(url, "http://local");
+    for (const channel of channels) {
+        parsed.searchParams.append("channel", channel);
+    }
+    return url.startsWith("http") ? parsed.toString() : `${parsed.pathname}${parsed.search}`;
+}
+function parseMessage(raw) {
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Validated, not cast: this crossed the network.
+        if (typeof parsed.channel !== "string" ||
+            typeof parsed.eventId !== "string" ||
+            typeof parsed.type !== "string" ||
+            typeof parsed.occurredAt !== "string") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Subscribe to the server's SSE endpoint, reconnecting with exponential backoff.
+ *
+ * ```ts
+ * const events$ = fromEventStream({
+ *   url: "/api/realtime",
+ *   channels: [`workspace:${workspaceId}`],
+ *   types: ["project.created", "job.progress"],
+ * });
+ *
+ * const sub = events$.pipe(
+ *   filter((message) => message.type === "job.progress"),
+ *   map((message) => message.data as { percent?: number }),
+ *   distinctUntilChanged((a, b) => a.percent === b.percent),
+ * ).subscribe(render);
+ *
+ * // Every subscription needs a lifecycle. In React, this is the effect cleanup.
+ * return () => sub.unsubscribe();
+ * ```
+ *
+ * The Observable never completes on its own — a realtime stream has no natural
+ * end. It stays open until unsubscribed, so bound it with `takeUntil` if
+ * something else should end it.
+ *
+ * Errors do **not** terminate the stream. A dropped connection is expected, not
+ * exceptional: it is reported through `onError` and then retried, because
+ * surfacing it as an RxJS error would tear down every downstream operator and
+ * lose the subscriber's accumulated state on a transient blip.
+ */
+export function fromEventStream(options) {
+    const initialDelay = options.initialRetryDelayMs ?? DEFAULT_INITIAL_RETRY_MS;
+    const maxDelay = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_MS;
+    const schedule = options.setTimeoutImpl ?? ((handler, ms) => setTimeout(handler, ms));
+    const cancel = options.clearTimeoutImpl ?? ((handle) => clearTimeout(handle));
+    const createSource = options.createSource ??
+        ((url) => {
+            const Ctor = globalThis
+                .EventSource;
+            if (Ctor === undefined) {
+                throw new Error("No EventSource available. Pass `createSource` when running outside a browser.");
+            }
+            return new Ctor(url);
+        });
+    const url = buildStreamUrl(options.url, options.channels);
+    return new Observable((subscriber) => {
+        let source;
+        let retryHandle;
+        let delay = initialDelay;
+        let stopped = false;
+        const connect = () => {
+            if (stopped) {
+                return;
+            }
+            try {
+                source = createSource(url);
+            }
+            catch (error) {
+                // Cannot construct a source at all — a configuration fault, not a blip.
+                subscriber.error(error);
+                return;
+            }
+            for (const type of options.types) {
+                source.addEventListener(type, (event) => {
+                    const message = parseMessage(event.data);
+                    if (message === undefined) {
+                        options.onError?.(new Error(`Discarded a malformed "${type}" frame.`));
+                        return;
+                    }
+                    // A frame arrived, so the connection is healthy; reset the backoff.
+                    delay = initialDelay;
+                    subscriber.next(message);
+                });
+            }
+            source.addEventListener("error", (event) => {
+                options.onError?.(event);
+                if (stopped) {
+                    return;
+                }
+                source?.close();
+                source = undefined;
+                retryHandle = schedule(connect, delay);
+                // Doubling, capped. Unbounded retries would hammer a recovering server.
+                delay = Math.min(delay * 2, maxDelay);
+            });
+        };
+        connect();
+        return () => {
+            stopped = true;
+            if (retryHandle !== undefined) {
+                cancel(retryHandle);
+            }
+            source?.close();
+            source = undefined;
+        };
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/streams/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/streams/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAiB,MAAM,MAAM,CAAC;AAiEjD,MAAM,wBAAwB,GAAG,KAAK,CAAC;AACvC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAEpC,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,QAA2B;IACrE,6EAA6E;IAC7E,mDAAmD;IACnD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;AAC3F,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmC,CAAC;QAEjE,iDAAiD;QACjD,IACE,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAClC,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAClC,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAC/B,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,EACrC,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,MAA+B,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAiC;IAEjC,MAAM,YAAY,GAAG,OAAO,CAAC,mBAAmB,IAAI,wBAAwB,CAAC;IAC7E,MAAM,QAAQ,GAAG,OAAO,CAAC,eAAe,IAAI,oBAAoB,CAAC;IACjE,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IACtF,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,MAAe,CAAC,CAAC,CAAC;IAEvF,MAAM,YAAY,GAChB,OAAO,CAAC,YAAY;QACpB,CAAC,CAAC,GAAW,EAAE,EAAE;YACf,MAAM,IAAI,GAAI,UAAqE;iBAChF,WAAW,CAAC;YACf,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IAEL,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE1D,OAAO,IAAI,UAAU,CAAwB,CAAC,UAA2C,EAAE,EAAE;QAC3F,IAAI,MAAmC,CAAC;QACxC,IAAI,WAAoB,CAAC;QACzB,IAAI,KAAK,GAAG,YAAY,CAAC;QACzB,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,wEAAwE;gBACxE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACxB,OAAO;YACT,CAAC;YAED,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBACjC,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;oBACtC,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;wBAC1B,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,CAAC,0BAA0B,IAAI,UAAU,CAAC,CAAC,CAAC;wBACvE,OAAO;oBACT,CAAC;oBACD,oEAAoE;oBACpE,KAAK,GAAG,YAAY,CAAC;oBACrB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC3B,CAAC,CAAC,CAAC;YACL,CAAC;YAED,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBACzC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;gBAEzB,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO;gBACT,CAAC;gBAED,MAAM,EAAE,KAAK,EAAE,CAAC;gBAChB,MAAM,GAAG,SAAS,CAAC;gBAEnB,WAAW,GAAG,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBACvC,wEAAwE;gBACxE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,EAAE,CAAC;QAEV,OAAO,GAAG,EAAE;YACV,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,CAAC,WAAW,CAAC,CAAC;YACtB,CAAC;YACD,MAAM,EAAE,KAAK,EAAE,CAAC;YAChB,MAAM,GAAG,SAAS,CAAC;QACrB,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/streams/events.d.ts

@@ -0,0 +1,68 @@
+import { Observable, type MonoTypeOperatorFunction, type OperatorFunction } from "rxjs";
+import type { EventSchemaMap, EventTypeOf, SaasEvent, SaasEventOf } from "../events/registry.ts";
+import type { EventsService } from "../events/service.ts";
+/**
+ * An Observable of application events, from the in-process dispatcher.
+ *
+ * Streams, not promises: a sequence of events over time is exactly what an
+ * Observable is for. Nothing else in the core returns one — a one-shot database
+ * read stays a promise, because wrapping it would add a lifecycle to manage for
+ * no benefit.
+ *
+ * ## Lifecycle
+ *
+ * The events subscription is created when the Observable is subscribed and torn
+ * down when it is unsubscribed. Nothing is registered before the first
+ * subscriber, and nothing lingers after the last one — so a caller that forgets
+ * `takeUntil` leaks one handler, not a growing set.
+ *
+ * ## What this is not
+ *
+ * Not durable. A crash loses the reaction, not the event, because the event is
+ * already committed. Anything that must survive a restart belongs in
+ * `@digimuza/saas-core/jobs`, reading the persisted row — never in an operator's
+ * accumulated state.
+ */
+export declare function fromEvents<S extends EventSchemaMap>(events: EventsService<S>): Observable<SaasEvent<S>>;
+/**
+ * Narrow a stream to one or more event types, in the type system as well as at
+ * runtime.
+ *
+ * ```ts
+ * fromEvents(events).pipe(
+ *   ofType("project.created", "project.deleted"),
+ *   map((event) => event.data.projectId),   // narrowed to those two payloads
+ * );
+ * ```
+ *
+ * A plain `filter((e) => e.type === "project.created")` would filter correctly
+ * but leave `data` as the union of every payload in the registry, so every
+ * downstream operator would need a cast.
+ */
+export declare function ofType<S extends EventSchemaMap, const K extends readonly EventTypeOf<S>[]>(...types: K): OperatorFunction<SaasEvent<S>, SaasEventOf<S, K[number]>>;
+/**
+ * Keep only events belonging to one workspace.
+ *
+ * A server-side stream sees every workspace's events, because the in-process
+ * dispatcher is process-wide. This is the filter that makes a per-tenant stream
+ * out of it — and it is *not* an authorization boundary. The caller must already
+ * hold a verified `WorkspaceContext`; see `workspaces.requireContext`.
+ */
+export declare function inWorkspace<T extends {
+    readonly workspaceId: string | null;
+}>(workspaceId: string): MonoTypeOperatorFunction<T>;
+/** Keep only events caused by one actor. */
+export declare function byActor<T extends {
+    readonly actorId: string | null;
+}>(actorId: string): MonoTypeOperatorFunction<T>;
+/**
+ * Project each event down to its payload.
+ *
+ * The type parameter is inferred from the *source*, not supplied by the caller —
+ * declaring it over the registry and the event key would leave both unbound at
+ * the call site and collapse `data` to `unknown`.
+ */
+export declare function toData<E extends {
+    readonly data: unknown;
+}>(): OperatorFunction<E, E["data"]>;
+//# sourceMappingURL=events.d.ts.map

package/dist/streams/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/streams/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,wBAAwB,EAAE,KAAK,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAGxF,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EACjD,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GACvB,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAW1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,CAAC,CAAC,SAAS,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,EACxF,GAAG,KAAK,EAAE,CAAC,GACV,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAM3D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC3E,WAAW,EAAE,MAAM,GAClB,wBAAwB,CAAC,CAAC,CAAC,CAE7B;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACnE,OAAO,EAAE,MAAM,GACd,wBAAwB,CAAC,CAAC,CAAC,CAE7B;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,KAAK,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAE7F"}

package/dist/streams/events.js

@@ -0,0 +1,81 @@
+import { Observable } from "rxjs";
+import { filter, map } from "rxjs/operators";
+/**
+ * An Observable of application events, from the in-process dispatcher.
+ *
+ * Streams, not promises: a sequence of events over time is exactly what an
+ * Observable is for. Nothing else in the core returns one — a one-shot database
+ * read stays a promise, because wrapping it would add a lifecycle to manage for
+ * no benefit.
+ *
+ * ## Lifecycle
+ *
+ * The events subscription is created when the Observable is subscribed and torn
+ * down when it is unsubscribed. Nothing is registered before the first
+ * subscriber, and nothing lingers after the last one — so a caller that forgets
+ * `takeUntil` leaks one handler, not a growing set.
+ *
+ * ## What this is not
+ *
+ * Not durable. A crash loses the reaction, not the event, because the event is
+ * already committed. Anything that must survive a restart belongs in
+ * `@digimuza/saas-core/jobs`, reading the persisted row — never in an operator's
+ * accumulated state.
+ */
+export function fromEvents(events) {
+    return new Observable((subscriber) => {
+        /**
+         * `onAny` returns its own unsubscribe, which is returned as the teardown —
+         * so RxJS's own lifecycle drives the handler's, and there is one place where
+         * it is removed.
+         */
+        return events.onAny((event) => {
+            subscriber.next(event);
+        });
+    });
+}
+/**
+ * Narrow a stream to one or more event types, in the type system as well as at
+ * runtime.
+ *
+ * ```ts
+ * fromEvents(events).pipe(
+ *   ofType("project.created", "project.deleted"),
+ *   map((event) => event.data.projectId),   // narrowed to those two payloads
+ * );
+ * ```
+ *
+ * A plain `filter((e) => e.type === "project.created")` would filter correctly
+ * but leave `data` as the union of every payload in the registry, so every
+ * downstream operator would need a cast.
+ */
+export function ofType(...types) {
+    const wanted = new Set(types);
+    return (source) => source.pipe(filter((event) => wanted.has(event.type)));
+}
+/**
+ * Keep only events belonging to one workspace.
+ *
+ * A server-side stream sees every workspace's events, because the in-process
+ * dispatcher is process-wide. This is the filter that makes a per-tenant stream
+ * out of it — and it is *not* an authorization boundary. The caller must already
+ * hold a verified `WorkspaceContext`; see `workspaces.requireContext`.
+ */
+export function inWorkspace(workspaceId) {
+    return filter((value) => value.workspaceId === workspaceId);
+}
+/** Keep only events caused by one actor. */
+export function byActor(actorId) {
+    return filter((value) => value.actorId === actorId);
+}
+/**
+ * Project each event down to its payload.
+ *
+ * The type parameter is inferred from the *source*, not supplied by the caller —
+ * declaring it over the registry and the event key would leave both unbound at
+ * the call site and collapse `data` to `unknown`.
+ */
+export function toData() {
+    return map((event) => event.data);
+}
+//# sourceMappingURL=events.js.map

package/dist/streams/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/streams/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAwD,MAAM,MAAM,CAAC;AACxF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAK7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,UAAU,CACxB,MAAwB;IAExB,OAAO,IAAI,UAAU,CAAe,CAAC,UAAU,EAAE,EAAE;QACjD;;;;WAIG;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAC5B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,MAAM,CACpB,GAAG,KAAQ;IAEX,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,MAAM,EAAE,EAAE,CAChB,MAAM,CAAC,IAAI,CACT,MAAM,CAAC,CAAC,KAAK,EAAsC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAC9E,CAAC;AACN,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,WAAmB;IAEnB,OAAO,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,KAAK,WAAW,CAAC,CAAC;AAC9D,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,OAAO,CACrB,OAAe;IAEf,OAAO,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM;IACpB,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/dist/streams/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Public streams surface: `@digimuza/saas-core/streams`. Server-only.
+ *
+ * RxJS is where *reactive behaviour* lives — filtering, combining, debouncing,
+ * aggregating, coordinating. It is deliberately none of the other things:
+ *
+ * - not the database (a one-shot read stays a promise);
+ * - not the durable job system (a crash loses a reaction, not an event);
+ * - not the realtime transport (that is `@digimuza/saas-core/realtime`).
+ *
+ * ```
+ * event sources → application events → Observable → reactor → application/client
+ * ```
+ *
+ * ## Server-side
+ *
+ * ```ts
+ * import { fromEvents, ofType, inWorkspace } from "@digimuza/saas-core/streams";
+ * import { events } from "@digimuza/saas-core/events";
+ * import { debounceTime, takeUntil } from "rxjs/operators";
+ *
+ * const subscription = fromEvents(events)
+ *   .pipe(
+ *     inWorkspace(context.workspaceId),
+ *     ofType("project.updated"),
+ *     debounceTime(500),
+ *     takeUntil(shutdown$),   // every subscription needs a lifecycle
+ *   )
+ *   .subscribe(reindexProject);
+ * ```
+ *
+ * ## Browser
+ *
+ * `@digimuza/saas-core/streams/client` reads the SSE endpoint instead, and imports
+ * nothing from the server half of this package.
+ *
+ * ## The rule this module exists to respect
+ *
+ * Promises for one-time work, Observables for sequences over time. Nothing here
+ * converts a synchronous or single-shot API into a stream — `getDatabase()` is not
+ * an Observable, and `workspaces.get()` never will be.
+ */
+export { byActor, fromEvents, inWorkspace, ofType, toData, } from "./events.ts";
+export { fromRealtime, type RealtimeStreamOptions } from "./realtime.ts";
+export { latestByKey } from "./state.ts";
+export { buildStreamUrl, fromEventStream, type ClientRealtimeMessage, type EventSourceLike, type EventStreamSourceOptions, type MessageEventLike, } from "./client.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/streams/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,GACP,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC"}

package/dist/streams/index.js

@@ -0,0 +1,47 @@
+/**
+ * Public streams surface: `@digimuza/saas-core/streams`. Server-only.
+ *
+ * RxJS is where *reactive behaviour* lives — filtering, combining, debouncing,
+ * aggregating, coordinating. It is deliberately none of the other things:
+ *
+ * - not the database (a one-shot read stays a promise);
+ * - not the durable job system (a crash loses a reaction, not an event);
+ * - not the realtime transport (that is `@digimuza/saas-core/realtime`).
+ *
+ * ```
+ * event sources → application events → Observable → reactor → application/client
+ * ```
+ *
+ * ## Server-side
+ *
+ * ```ts
+ * import { fromEvents, ofType, inWorkspace } from "@digimuza/saas-core/streams";
+ * import { events } from "@digimuza/saas-core/events";
+ * import { debounceTime, takeUntil } from "rxjs/operators";
+ *
+ * const subscription = fromEvents(events)
+ *   .pipe(
+ *     inWorkspace(context.workspaceId),
+ *     ofType("project.updated"),
+ *     debounceTime(500),
+ *     takeUntil(shutdown$),   // every subscription needs a lifecycle
+ *   )
+ *   .subscribe(reindexProject);
+ * ```
+ *
+ * ## Browser
+ *
+ * `@digimuza/saas-core/streams/client` reads the SSE endpoint instead, and imports
+ * nothing from the server half of this package.
+ *
+ * ## The rule this module exists to respect
+ *
+ * Promises for one-time work, Observables for sequences over time. Nothing here
+ * converts a synchronous or single-shot API into a stream — `getDatabase()` is not
+ * an Observable, and `workspaces.get()` never will be.
+ */
+export { byActor, fromEvents, inWorkspace, ofType, toData, } from "./events.js";
+export { fromRealtime } from "./realtime.js";
+export { latestByKey } from "./state.js";
+export { buildStreamUrl, fromEventStream, } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/streams/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/streams/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,GACP,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAA8B,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EACL,cAAc,EACd,eAAe,GAKhB,MAAM,aAAa,CAAC"}

package/dist/streams/realtime.d.ts

@@ -0,0 +1,27 @@
+import { Observable } from "rxjs";
+import type { RealtimeService } from "../realtime/service.ts";
+import type { RealtimeMessage } from "../realtime/transport.ts";
+export interface RealtimeStreamOptions {
+    /** Resolved from the session. Never from a request body. */
+    readonly userId: string;
+    /** Requested channels. Unauthorized ones are dropped, not thrown on. */
+    readonly channels: readonly string[];
+}
+/**
+ * An Observable of authorized realtime messages.
+ *
+ * The stream a *server* uses to react to delivery — a reactor coordinating
+ * behaviour across tenants, say. A browser should use
+ * `@digimuza/saas-core/streams/client` instead, which reads the SSE endpoint
+ * rather than subscribing to the transport directly.
+ *
+ * ## Authorization happens once, on subscribe
+ *
+ * `realtime.subscribe` verifies channel access before opening anything, so a
+ * subscriber never receives a channel it was not granted. Because that check is
+ * asynchronous and this is a synchronous Observable constructor, a subscriber
+ * that unsubscribes during the check is honoured: the subscription is closed
+ * immediately rather than left open until the next message.
+ */
+export declare function fromRealtime(realtime: RealtimeService, options: RealtimeStreamOptions): Observable<RealtimeMessage>;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/streams/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/streams/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,qBAAqB,GAC7B,UAAU,CAAC,eAAe,CAAC,CAkC7B"}

package/dist/streams/realtime.js

@@ -0,0 +1,50 @@
+import { Observable } from "rxjs";
+/**
+ * An Observable of authorized realtime messages.
+ *
+ * The stream a *server* uses to react to delivery — a reactor coordinating
+ * behaviour across tenants, say. A browser should use
+ * `@digimuza/saas-core/streams/client` instead, which reads the SSE endpoint
+ * rather than subscribing to the transport directly.
+ *
+ * ## Authorization happens once, on subscribe
+ *
+ * `realtime.subscribe` verifies channel access before opening anything, so a
+ * subscriber never receives a channel it was not granted. Because that check is
+ * asynchronous and this is a synchronous Observable constructor, a subscriber
+ * that unsubscribes during the check is honoured: the subscription is closed
+ * immediately rather than left open until the next message.
+ */
+export function fromRealtime(realtime, options) {
+    return new Observable((subscriber) => {
+        let closed = false;
+        let close;
+        void realtime
+            .subscribe({
+            userId: options.userId,
+            channels: options.channels,
+            onMessage: (message) => {
+                subscriber.next(message);
+            },
+        })
+            .then((subscription) => {
+            close = () => subscription.close();
+            /**
+             * Unsubscribed while authorization was in flight. Without this the
+             * transport subscription would stay open with nobody listening, holding a
+             * listener slot for the lifetime of the process.
+             */
+            if (closed) {
+                void subscription.close();
+            }
+        })
+            .catch((error) => {
+            subscriber.error(error);
+        });
+        return () => {
+            closed = true;
+            void close?.();
+        };
+    });
+}
+//# sourceMappingURL=realtime.js.map

package/dist/streams/realtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.js","sourceRoot":"","sources":["../../src/streams/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAYlC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAyB,EACzB,OAA8B;IAE9B,OAAO,IAAI,UAAU,CAAkB,CAAC,UAAU,EAAE,EAAE;QACpD,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,KAAwC,CAAC;QAE7C,KAAK,QAAQ;aACV,SAAS,CAAC;YACT,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;gBACrB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC;SACF,CAAC;aACD,IAAI,CAAC,CAAC,YAAY,EAAE,EAAE;YACrB,KAAK,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;YAEnC;;;;eAIG;YACH,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,YAAY,CAAC,KAAK,EAAE,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEL,OAAO,GAAG,EAAE;YACV,MAAM,GAAG,IAAI,CAAC;YACd,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/streams/state.d.ts

@@ -0,0 +1,26 @@
+import type { Observable } from "rxjs";
+/**
+ * Accumulate a stream into "the latest value per key".
+ *
+ * The one reactive-state shape worth wrapping, because the sharing is easy to get
+ * wrong: without `shareReplay`, every new subscriber re-runs the scan from an
+ * empty map and sees nothing until the next event arrives.
+ *
+ * ```ts
+ * const progress$ = latestByKey(jobEvents$, (event) => event.data.runId);
+ * // Observable<ReadonlyMap<string, JobEvent>> — every run's most recent update.
+ * ```
+ *
+ * `refCount: true` discards the accumulated map when the last subscriber leaves.
+ * Deliberate: a cache outliving its subscribers is a leak, and this is a *view* of
+ * durable data — the `events` table is where state lives if it must survive
+ * anything.
+ *
+ * Everything else is plain RxJS, on purpose. `debounceTime`, `throttleTime`,
+ * `bufferTime`, `scan`, `distinctUntilChanged` — including its
+ * `(comparator, keySelector)` form for comparing a projection — already exist, and
+ * re-exporting them under new names would add vocabulary without adding
+ * behaviour.
+ */
+export declare function latestByKey<T>(source: Observable<T>, keyOf: (value: T) => string): Observable<ReadonlyMap<string, T>>;
+//# sourceMappingURL=state.d.ts.map

package/dist/streams/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/streams/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAC1B,UAAU,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAWpC"}

package/dist/streams/state.js

@@ -0,0 +1,34 @@
+import { scan, shareReplay } from "rxjs/operators";
+/**
+ * Accumulate a stream into "the latest value per key".
+ *
+ * The one reactive-state shape worth wrapping, because the sharing is easy to get
+ * wrong: without `shareReplay`, every new subscriber re-runs the scan from an
+ * empty map and sees nothing until the next event arrives.
+ *
+ * ```ts
+ * const progress$ = latestByKey(jobEvents$, (event) => event.data.runId);
+ * // Observable<ReadonlyMap<string, JobEvent>> — every run's most recent update.
+ * ```
+ *
+ * `refCount: true` discards the accumulated map when the last subscriber leaves.
+ * Deliberate: a cache outliving its subscribers is a leak, and this is a *view* of
+ * durable data — the `events` table is where state lives if it must survive
+ * anything.
+ *
+ * Everything else is plain RxJS, on purpose. `debounceTime`, `throttleTime`,
+ * `bufferTime`, `scan`, `distinctUntilChanged` — including its
+ * `(comparator, keySelector)` form for comparing a projection — already exist, and
+ * re-exporting them under new names would add vocabulary without adding
+ * behaviour.
+ */
+export function latestByKey(source, keyOf) {
+    return source.pipe(scan((state, value) => {
+        // A fresh Map per emission, so a subscriber holding an earlier value is not
+        // mutated underneath it — the usual expectation for a stream of states.
+        const next = new Map(state);
+        next.set(keyOf(value), value);
+        return next;
+    }, new Map()), shareReplay({ bufferSize: 1, refCount: true }));
+}
+//# sourceMappingURL=state.js.map

package/dist/streams/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/streams/state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,WAAW,CACzB,MAAqB,EACrB,KAA2B;IAE3B,OAAO,MAAM,CAAC,IAAI,CAChB,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACpB,4EAA4E;QAC5E,wEAAwE;QACxE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC,EAAE,IAAI,GAAG,EAAa,CAAC,EACxB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC/C,CAAC;AACJ,CAAC"}