@digimuza/saas-core 0.0.2

package/dist/notifications/service.d.ts

@@ -0,0 +1,79 @@
+import { isUniqueViolation } from "../db/errors.ts";
+import type { Notification } from "../db/schema/index.ts";
+import type { CoreDatabase } from "../db/types.ts";
+import type { WorkspacesService } from "../workspaces/service.ts";
+export interface CreateNotificationInput {
+    /** The recipient. */
+    readonly userId: string;
+    /**
+     * Tenant this concerns. Verified against membership when given — a
+     * notification about a workspace the recipient cannot see would leak its
+     * existence.
+     */
+    readonly workspaceId?: string | null;
+    readonly type: string;
+    readonly title: string;
+    readonly body?: string;
+    /** Relative, so it survives a domain change. */
+    readonly url?: string;
+    readonly data?: Record<string, unknown>;
+    /**
+     * Deduplication key, scoped to the recipient and type.
+     *
+     * Event-driven creation needs it: an event delivered twice, or a handler
+     * retried, must not produce two identical notifications.
+     */
+    readonly dedupeKey?: string;
+}
+export interface ListNotificationsOptions {
+    /** Only unread. */
+    readonly unreadOnly?: boolean;
+    /** Restrict to one workspace, or to account-level notices with `null`. */
+    readonly workspaceId?: string | null;
+    readonly types?: readonly string[];
+    readonly limit?: number;
+    /** Keyset pagination: notifications strictly older than this. */
+    readonly before?: Date;
+}
+export interface NotificationsService {
+    /**
+     * Create an in-app notification.
+     *
+     * Returns the existing row when `dedupeKey` has already been used, so the call
+     * is safe to retry.
+     */
+    create(input: CreateNotificationInput, tx?: CoreDatabase): Promise<Notification>;
+    /** Create several, skipping any that duplicate an existing dedupe key. */
+    createMany(inputs: readonly CreateNotificationInput[]): Promise<Notification[]>;
+    /**
+     * A user's own notifications, newest first.
+     *
+     * `userId` must come from the session. Every query filters on it, so one user's
+     * notifications can never appear in another's list.
+     */
+    list(userId: string, options?: ListNotificationsOptions): Promise<Notification[]>;
+    countUnread(userId: string, options?: {
+        workspaceId?: string | null;
+    }): Promise<number>;
+    /** Mark specific notifications read. Silently ignores ids the user does not own. */
+    markRead(userId: string, notificationIds: readonly string[]): Promise<number>;
+    markAllRead(userId: string, options?: {
+        workspaceId?: string | null;
+    }): Promise<number>;
+    /** Remove one of the user's own notifications. */
+    remove(userId: string, notificationId: string): Promise<void>;
+}
+export interface NotificationsServiceDeps {
+    readonly db: CoreDatabase;
+    /**
+     * Used to verify the recipient belongs to the workspace a notification names.
+     *
+     * Optional: omit it and workspace membership is not checked, which is only safe
+     * when every caller already holds a verified context.
+     */
+    readonly workspaces?: Pick<WorkspacesService, "resolveContext">;
+    readonly now?: () => Date;
+}
+export declare function createNotificationsService(deps: NotificationsServiceDeps): NotificationsService;
+export { isUniqueViolation };
+//# sourceMappingURL=service.d.ts.map

package/dist/notifications/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/notifications/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACtC,qBAAqB;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,mBAAmB;IACnB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,uBAAuB,EAAE,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEjF,0EAA0E;IAC1E,UAAU,CAAC,MAAM,EAAE,SAAS,uBAAuB,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEhF;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAElF,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExF,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9E,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExF,kDAAkD;IAClD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAChE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAMD,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,wBAAwB,GAC7B,oBAAoB,CAoMtB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/notifications/service.js

@@ -0,0 +1,164 @@
+import { and, desc, eq, inArray, isNull, lt, sql } from "drizzle-orm";
+import { isUniqueViolation } from "../db/errors.js";
+import { notifications } from "../db/schema/index.js";
+import { InvalidInputError, NotFoundError } from "../errors.js";
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+const MAX_TITLE_LENGTH = 200;
+export function createNotificationsService(deps) {
+    const now = deps.now ?? (() => new Date());
+    async function toRow(input) {
+        if (input.title.trim().length === 0) {
+            throw new InvalidInputError("A notification title is required.");
+        }
+        if (input.title.length > MAX_TITLE_LENGTH) {
+            throw new InvalidInputError(`A notification title may not exceed ${MAX_TITLE_LENGTH} characters.`);
+        }
+        const workspaceId = input.workspaceId ?? null;
+        /**
+         * Notifying someone about a workspace they are not in would tell them it
+         * exists — and, through the title, something about what happens in it.
+         */
+        if (workspaceId !== null && deps.workspaces !== undefined) {
+            const context = await deps.workspaces.resolveContext({
+                userId: input.userId,
+                workspaceId,
+            });
+            if (context === undefined) {
+                throw new NotFoundError("Recipient is not a member of that workspace.");
+            }
+        }
+        return {
+            userId: input.userId,
+            workspaceId,
+            type: input.type,
+            title: input.title,
+            body: input.body ?? null,
+            url: input.url ?? null,
+            data: (input.data ?? null),
+            dedupeKey: input.dedupeKey ?? null,
+        };
+    }
+    /** Shared by list, count and mark-all: always narrowed to one recipient. */
+    function scope(userId, workspaceId) {
+        const clauses = [eq(notifications.userId, userId)];
+        if (workspaceId === null) {
+            clauses.push(isNull(notifications.workspaceId));
+        }
+        else if (workspaceId !== undefined) {
+            clauses.push(eq(notifications.workspaceId, workspaceId));
+        }
+        return clauses;
+    }
+    const service = {
+        async create(input, tx) {
+            const row = await toRow(input);
+            const db = tx ?? deps.db;
+            const inserted = await db
+                .insert(notifications)
+                .values(row)
+                /**
+                 * The dedupe index is *partial* (`where dedupe_key is not null`), so the
+                 * conflict target needs a matching predicate — PostgreSQL refuses to
+                 * infer a partial index as the arbiter otherwise.
+                 */
+                .onConflictDoNothing({
+                target: [notifications.userId, notifications.type, notifications.dedupeKey],
+                where: sql `${notifications.dedupeKey} is not null`,
+            })
+                .returning();
+            const created = inserted[0];
+            if (created !== undefined) {
+                return created;
+            }
+            if (input.dedupeKey === undefined) {
+                throw new Error("Failed to create notification.");
+            }
+            // Already created by an earlier delivery; return the same row.
+            const existing = await db
+                .select()
+                .from(notifications)
+                .where(and(eq(notifications.userId, input.userId), eq(notifications.type, input.type), eq(notifications.dedupeKey, input.dedupeKey)))
+                .limit(1);
+            const found = existing[0];
+            if (found === undefined) {
+                throw new Error("Failed to create notification.");
+            }
+            return found;
+        },
+        async createMany(inputs) {
+            if (inputs.length === 0) {
+                return [];
+            }
+            const rows = await Promise.all(inputs.map((input) => toRow(input)));
+            return deps.db
+                .insert(notifications)
+                .values(rows)
+                .onConflictDoNothing({
+                target: [notifications.userId, notifications.type, notifications.dedupeKey],
+                where: sql `${notifications.dedupeKey} is not null`,
+            })
+                .returning();
+        },
+        async list(userId, options = {}) {
+            const clauses = scope(userId, options.workspaceId);
+            if (options.unreadOnly === true) {
+                clauses.push(isNull(notifications.readAt));
+            }
+            if (options.types !== undefined && options.types.length > 0) {
+                clauses.push(inArray(notifications.type, [...options.types]));
+            }
+            if (options.before !== undefined) {
+                clauses.push(lt(notifications.createdAt, options.before));
+            }
+            return deps.db
+                .select()
+                .from(notifications)
+                .where(and(...clauses))
+                // Tie-broken on id so keyset pagination cannot loop on equal timestamps.
+                .orderBy(desc(notifications.createdAt), desc(notifications.id))
+                .limit(Math.min(options.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
+        },
+        async countUnread(userId, options = {}) {
+            const rows = await deps.db
+                .select({ count: sql `count(*)::int` })
+                .from(notifications)
+                .where(and(...scope(userId, options.workspaceId), isNull(notifications.readAt)));
+            return rows[0]?.count ?? 0;
+        },
+        async markRead(userId, notificationIds) {
+            if (notificationIds.length === 0) {
+                return 0;
+            }
+            const updated = await deps.db
+                .update(notifications)
+                .set({ readAt: now(), updatedAt: now() })
+                .where(and(
+            // Scoped to the caller, so an id belonging to someone else matches
+            // nothing rather than raising — which would confirm it exists.
+            eq(notifications.userId, userId), inArray(notifications.id, [...notificationIds]), isNull(notifications.readAt)))
+                .returning({ id: notifications.id });
+            return updated.length;
+        },
+        async markAllRead(userId, options = {}) {
+            const updated = await deps.db
+                .update(notifications)
+                .set({ readAt: now(), updatedAt: now() })
+                .where(and(...scope(userId, options.workspaceId), isNull(notifications.readAt)))
+                .returning({ id: notifications.id });
+            return updated.length;
+        },
+        async remove(userId, notificationId) {
+            const deleted = await deps.db
+                .delete(notifications)
+                .where(and(eq(notifications.userId, userId), eq(notifications.id, notificationId)))
+                .returning({ id: notifications.id });
+            if (deleted.length === 0) {
+                throw new NotFoundError("Notification not found.");
+            }
+        },
+    };
+    return service;
+}
+export { isUniqueViolation };
+//# sourceMappingURL=service.js.map

package/dist/notifications/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/notifications/service.ts"],"names":[],"mappings":"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"}

package/dist/realtime/channels.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A realtime channel.
+ *
+ * Only two kinds exist, and both are scoped to something the server can verify:
+ * a workspace the caller is a member of, or the caller themselves. There is no
+ * global channel and no wildcard — a client that could subscribe to `*` would
+ * receive every tenant's traffic, and no amount of downstream filtering makes
+ * that safe.
+ */
+export type Channel = {
+    readonly kind: "workspace";
+    readonly workspaceId: string;
+} | {
+    readonly kind: "user";
+    readonly userId: string;
+};
+export declare const WORKSPACE_CHANNEL_PREFIX = "workspace:";
+export declare const USER_CHANNEL_PREFIX = "user:";
+/** Longest channel string this module will ever produce. */
+export declare const MAX_CHANNEL_LENGTH: number;
+export declare function workspaceChannel(workspaceId: string): string;
+export declare function userChannel(userId: string): string;
+export declare function formatChannel(channel: Channel): string;
+/**
+ * Parse a channel identifier, or return `undefined` if it is not one.
+ *
+ * Returning `undefined` rather than throwing is deliberate: a subscriber sending
+ * a batch of channels should have the bad ones denied, not the whole request
+ * rejected — a client on a stale deploy would otherwise be unable to connect at
+ * all.
+ */
+export declare function parseChannel(value: string): Channel | undefined;
+/** As {@link parseChannel}, but throws. For server-side callers. */
+export declare function requireChannel(value: string): Channel;
+/** How many channels one subscriber may request. */
+export declare const MAX_CHANNELS_PER_SUBSCRIPTION = 32;
+//# sourceMappingURL=channels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../src/realtime/channels.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,eAAO,MAAM,wBAAwB,eAAe,CAAC;AACrD,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAW3C,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,QAAuC,CAAC;AAEvE,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAItD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAgB/D;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,oDAAoD;AACpD,eAAO,MAAM,6BAA6B,KAAK,CAAC"}

package/dist/realtime/channels.js

@@ -0,0 +1,58 @@
+import { InvalidInputError } from "../errors.js";
+export const WORKSPACE_CHANNEL_PREFIX = "workspace:";
+export const USER_CHANNEL_PREFIX = "user:";
+/**
+ * Channel identifiers embed UUIDs, so the format is checked rather than trusted.
+ *
+ * A client supplies channel names directly, which makes them untrusted input:
+ * without this, `workspace:../../admin` or `workspace:%` would reach the
+ * authorizer and the transport as opaque strings.
+ */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Longest channel string this module will ever produce. */
+export const MAX_CHANNEL_LENGTH = WORKSPACE_CHANNEL_PREFIX.length + 36;
+export function workspaceChannel(workspaceId) {
+    return `${WORKSPACE_CHANNEL_PREFIX}${workspaceId}`;
+}
+export function userChannel(userId) {
+    return `${USER_CHANNEL_PREFIX}${userId}`;
+}
+export function formatChannel(channel) {
+    return channel.kind === "workspace"
+        ? workspaceChannel(channel.workspaceId)
+        : userChannel(channel.userId);
+}
+/**
+ * Parse a channel identifier, or return `undefined` if it is not one.
+ *
+ * Returning `undefined` rather than throwing is deliberate: a subscriber sending
+ * a batch of channels should have the bad ones denied, not the whole request
+ * rejected — a client on a stale deploy would otherwise be unable to connect at
+ * all.
+ */
+export function parseChannel(value) {
+    if (value.length > MAX_CHANNEL_LENGTH) {
+        return undefined;
+    }
+    if (value.startsWith(WORKSPACE_CHANNEL_PREFIX)) {
+        const workspaceId = value.slice(WORKSPACE_CHANNEL_PREFIX.length);
+        return UUID.test(workspaceId) ? { kind: "workspace", workspaceId } : undefined;
+    }
+    if (value.startsWith(USER_CHANNEL_PREFIX)) {
+        const userId = value.slice(USER_CHANNEL_PREFIX.length);
+        return UUID.test(userId) ? { kind: "user", userId } : undefined;
+    }
+    return undefined;
+}
+/** As {@link parseChannel}, but throws. For server-side callers. */
+export function requireChannel(value) {
+    const channel = parseChannel(value);
+    if (channel === undefined) {
+        // The value is echoed because a server-side caller built it themselves.
+        throw new InvalidInputError(`"${value}" is not a valid realtime channel.`);
+    }
+    return channel;
+}
+/** How many channels one subscriber may request. */
+export const MAX_CHANNELS_PER_SUBSCRIPTION = 32;
+//# sourceMappingURL=channels.js.map

package/dist/realtime/channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../src/realtime/channels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAejD,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC;AACrD,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,IAAI,GAAG,4EAA4E,CAAC;AAE1F,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAAwB,CAAC,MAAM,GAAG,EAAE,CAAC;AAEvE,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,GAAG,wBAAwB,GAAG,WAAW,EAAE,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,GAAG,mBAAmB,GAAG,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,OAAO,CAAC,IAAI,KAAK,WAAW;QACjC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,WAAW,CAAC;QACvC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,KAAK,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACtC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,CAAC,wBAAwB,CAAC,EAAE,CAAC;QAC/C,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,wEAAwE;QACxE,MAAM,IAAI,iBAAiB,CAAC,IAAI,KAAK,oCAAoC,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAC"}

package/dist/realtime/index.d.ts

@@ -0,0 +1,19 @@
+import { type RealtimeService } from "./service.ts";
+import type { RealtimeTransport } from "./transport.ts";
+export { formatChannel, MAX_CHANNELS_PER_SUBSCRIPTION, MAX_CHANNEL_LENGTH, parseChannel, requireChannel, USER_CHANNEL_PREFIX, userChannel, WORKSPACE_CHANNEL_PREFIX, workspaceChannel, type Channel, } from "./channels.ts";
+export { createPostgresTransport, decodeMessage, encodeMessage, PG_NOTIFY_CHANNEL, postgresJsNotifyClient, type NotifyCapableClient, type PostgresTransportOptions, } from "./postgres.ts";
+export { createRealtimeService, type AuthorizedChannels, type PublishOptions, type RealtimeService, type RealtimeServiceDeps, type SubscribeInput, } from "./service.ts";
+export { createEventStream, type EventStream, type EventStreamOptions, } from "./sse.ts";
+export type { RealtimeMessage, RealtimeSubscription, RealtimeTransport, } from "./transport.ts";
+/** Replace the default transport. Call before first use. */
+export declare function setDefaultRealtimeTransport(transport: RealtimeTransport | undefined): void;
+/**
+ * Whether an external transport is configured.
+ *
+ * Exposed so an application can decide at boot whether to keep the PostgreSQL
+ * transport or construct its own from `config.realtime`.
+ */
+export declare function hasExternalRealtimeConfig(): boolean;
+/** Default service, bound to the PostgreSQL transport and verified membership. */
+export declare const realtime: RealtimeService;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAwDA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EACL,aAAa,EACb,6BAA6B,EAC7B,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,wBAAwB,EACxB,gBAAgB,EAChB,KAAK,OAAO,GACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAkCxB,4DAA4D;AAC5D,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAOnD;AAED,kFAAkF;AAClF,eAAO,MAAM,QAAQ,EAAE,eAQrB,CAAC"}

package/dist/realtime/index.js

@@ -0,0 +1,118 @@
+/**
+ * Public realtime surface: `@digimuza/saas-core/realtime`. Server-only.
+ *
+ * Realtime **delivers** events to connected clients. It is not the source of
+ * truth: the durable record is the `events` table, and a client that missed a
+ * message re-reads from it. That ordering is the whole design —
+ *
+ * ```
+ * PostgreSQL  →  application events  →  realtime transport  →  browser
+ * ```
+ *
+ * — and it is why a failed delivery never fails the operation that published it.
+ *
+ * ## Wiring
+ *
+ * ```ts
+ * import { events } from "@digimuza/saas-core/events";
+ * import { realtime } from "@digimuza/saas-core/realtime";
+ *
+ * realtime.attach(events);   // once at startup
+ * ```
+ *
+ * ## Serving a stream
+ *
+ * ```ts
+ * // app/api/realtime/route.ts
+ * import { createEventStream } from "@digimuza/saas-core/realtime";
+ *
+ * export async function GET(request: Request) {
+ *   const user = await auth.requireUser();
+ *   const stream = await createEventStream(realtime, {
+ *     userId: user.id,
+ *     channels: new URL(request.url).searchParams.getAll("channel"),
+ *     signal: request.signal,
+ *   });
+ *   return new Response(stream.body, { headers: stream.headers });
+ * }
+ * ```
+ *
+ * ## Authorization
+ *
+ * Channels are named `workspace:<uuid>` and `user:<uuid>`, and there is no
+ * wildcard. A client names the channels it wants, so those names are untrusted:
+ * every one is parsed, then checked — workspace channels against
+ * `workspace_members`, user channels against the session's own id. Unauthorized
+ * channels are dropped, and the refusal never distinguishes "not a member" from
+ * "no such workspace", or channel probing would enumerate tenants.
+ *
+ * Browsers never see `LISTEN`/`NOTIFY`. The server holds the listening connection
+ * and re-emits only what a given subscriber was granted.
+ */
+import { config } from "../config/index.js";
+import { getDatabaseHandle } from "../db/client.js";
+import { getDefaultLogger } from "../logger/default.js";
+import { workspaces } from "../workspaces/index.js";
+import { createPostgresTransport } from "./postgres.js";
+import { createRealtimeService } from "./service.js";
+export { formatChannel, MAX_CHANNELS_PER_SUBSCRIPTION, MAX_CHANNEL_LENGTH, parseChannel, requireChannel, USER_CHANNEL_PREFIX, userChannel, WORKSPACE_CHANNEL_PREFIX, workspaceChannel, } from "./channels.js";
+export { createPostgresTransport, decodeMessage, encodeMessage, PG_NOTIFY_CHANNEL, postgresJsNotifyClient, } from "./postgres.js";
+export { createRealtimeService, } from "./service.js";
+export { createEventStream, } from "./sse.js";
+/**
+ * The default transport: PostgreSQL `LISTEN`/`NOTIFY` over the existing pool.
+ *
+ * Chosen because it adds no infrastructure — the database is already there, and
+ * the spec is explicit about preferring PostgreSQL where PostgreSQL is enough.
+ * `REALTIME_URL` and `REALTIME_API_KEY` exist for a deployment that outgrows it
+ * and swaps in a broker; this transport ignores them.
+ */
+let defaultTransport;
+function getTransport() {
+    if (defaultTransport === undefined) {
+        const handle = getDatabaseHandle();
+        /**
+         * postgres.js exposes `listen` and `notify` on the client itself, so no
+         * separate connection is configured here — the driver already dedicates one
+         * to listening.
+         */
+        const client = handle.client;
+        defaultTransport = createPostgresTransport({
+            client,
+            onError: (error) => {
+                getDefaultLogger().error("realtime transport error", { error });
+            },
+        });
+    }
+    return defaultTransport;
+}
+/** Replace the default transport. Call before first use. */
+export function setDefaultRealtimeTransport(transport) {
+    defaultTransport = transport;
+}
+/**
+ * Whether an external transport is configured.
+ *
+ * Exposed so an application can decide at boot whether to keep the PostgreSQL
+ * transport or construct its own from `config.realtime`.
+ */
+export function hasExternalRealtimeConfig() {
+    try {
+        return config.realtime.url.length > 0;
+    }
+    catch {
+        // Not configured at all, which is the normal case for the default transport.
+        return false;
+    }
+}
+/** Default service, bound to the PostgreSQL transport and verified membership. */
+export const realtime = createRealtimeService({
+    get transport() {
+        return getTransport();
+    },
+    workspaces,
+    onError: (error) => {
+        getDefaultLogger().error("realtime delivery error", { error });
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/realtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAA4B,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,qBAAqB,EAAwB,MAAM,cAAc,CAAC;AAG3E,OAAO,EACL,aAAa,EACb,6BAA6B,EAC7B,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,wBAAwB,EACxB,gBAAgB,GAEjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,sBAAsB,GAGvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,GAMtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,GAGlB,MAAM,UAAU,CAAC;AAQlB;;;;;;;GAOG;AACH,IAAI,gBAA+C,CAAC;AAEpD,SAAS,YAAY;IACnB,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QAEnC;;;;WAIG;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,MAAwC,CAAC;QAE/D,gBAAgB,GAAG,uBAAuB,CAAC;YACzC,MAAM;YACN,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBACjB,gBAAgB,EAAE,CAAC,KAAK,CAAC,0BAA0B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAClE,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,2BAA2B,CAAC,SAAwC;IAClF,gBAAgB,GAAG,SAAS,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;QAC7E,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,QAAQ,GAAoB,qBAAqB,CAAC;IAC7D,IAAI,SAAS;QACX,OAAO,YAAY,EAAE,CAAC;IACxB,CAAC;IACD,UAAU;IACV,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QACjB,gBAAgB,EAAE,CAAC,KAAK,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;CACF,CAAC,CAAC"}

package/dist/realtime/postgres.d.ts

@@ -0,0 +1,48 @@
+import type { RealtimeMessage, RealtimeTransport } from "./transport.ts";
+/**
+ * The single PostgreSQL notification channel every message travels on.
+ *
+ * One PG channel rather than one per application channel, because `LISTEN` is
+ * per-connection and per-name: a workspace-per-channel design would mean
+ * thousands of `LISTEN` statements and constant `LISTEN`/`UNLISTEN` churn as
+ * clients come and go. Instead every server sees every message and filters to the
+ * channels it has authorized subscribers for.
+ *
+ * The trade-off is real: fan-out is O(servers), so at large scale every node
+ * decodes traffic it discards. That is the point at which to swap in a broker —
+ * which is why {@link RealtimeTransport} exists.
+ */
+export declare const PG_NOTIFY_CHANNEL = "saas_core_realtime";
+/** Anything a postgres.js or PGlite handle can do that this transport needs. */
+export interface NotifyCapableClient {
+    listen(channel: string, onNotify: (payload: string) => void): Promise<unknown>;
+    unlisten?(channel: string, onNotify?: (payload: string) => void): Promise<unknown>;
+    /** Parameterised `select pg_notify($1, $2)`. */
+    notify(channel: string, payload: string): Promise<unknown>;
+}
+export interface PostgresTransportOptions {
+    readonly client: NotifyCapableClient;
+    /** Override the notification channel, e.g. to separate environments. */
+    readonly notifyChannel?: string;
+    /** Reported when a payload cannot be delivered at all. */
+    readonly onError?: (error: unknown) => void;
+}
+/** Shrink an over-large message rather than failing the notification. */
+export declare function encodeMessage(message: RealtimeMessage, maxBytes?: number): string;
+export declare function decodeMessage(payload: string): RealtimeMessage | undefined;
+/**
+ * Realtime over PostgreSQL `LISTEN`/`NOTIFY`.
+ *
+ * The default transport because it adds no infrastructure: the database is
+ * already there. Browsers never touch `LISTEN`/`NOTIFY` — the server holds the
+ * listening connection and re-emits only what a given subscriber is authorized
+ * for, over SSE.
+ */
+export declare function createPostgresTransport(options: PostgresTransportOptions): RealtimeTransport;
+/** Adapt a postgres.js `Sql` instance to {@link NotifyCapableClient}. */
+export declare function postgresJsNotifyClient(sql: {
+    listen: (channel: string, onNotify: (value: string) => void) => unknown;
+    unsafe?: unknown;
+    notify?: (channel: string, payload: string) => unknown;
+}): NotifyCapableClient;
+//# sourceMappingURL=postgres.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/realtime/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAwB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE/F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAStD,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAClC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,gDAAgD;IAChD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,SAAoB,GAAG,MAAM,CAQ5F;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAuB1E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CA2F5F;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE;IAC1C,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK,OAAO,CAAC;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CACxD,GAAG,mBAAmB,CAUtB"}