Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,180 @@
import { describe, expect, it } from "vitest";
import {
REALTIME_EVENT_NAMES,
isRealtimeEvent,
serializeRealtimeComment,
serializeRealtimeEvent,
subscribeToRealtime,
validateRealtimeEvent,
type NotificationStreamItem,
type RealtimeMessageEvent,
} from "./index.js";
const item: NotificationStreamItem = {
id: "delivery_boundary_1",
cursor: "2026-05-08T20:00:00.000Z:delivery_boundary_1",
tenantId: "tenant_1",
userId: "user_1",
channel: "IN_APP",
category: "billing",
messageKey: "invoice.ready",
status: "PENDING",
attemptsMade: 0,
createdAt: "2026-05-08T19:59:00.000Z",
updatedAt: "2026-05-08T20:00:00.000Z",
sentAt: null,
readAt: null,
};
const baseEvent = {
cursor: item.cursor,
requestId: "req_boundary_1",
tenantId: "tenant_1",
userId: "user_1",
};
class FakeEventSource {
static instances: FakeEventSource[] = [];
onopen: (() => void) | null = null;
onmessage: ((event: RealtimeMessageEvent) => void) | null = null;
onerror: ((event: unknown) => void) | null = null;
closed = false;
constructor(readonly url: string | URL) {
FakeEventSource.instances.push(this);
}
emitMessage(data: unknown): void {
this.onmessage?.({ data: typeof data === "string" ? data : JSON.stringify(data) });
}
close(): void {
this.closed = true;
}
}
describe("public realtime package boundary", () => {
it("subscribes to notification updates through the entrypoint with redacted invalid diagnostics", () => {
FakeEventSource.instances = [];
const updates: NotificationStreamItem[] = [];
const diagnostics: unknown[] = [];
const subscriber = subscribeToRealtime({
url: "/api/notifications/stream",
EventSource: FakeEventSource,
reconnect: { enabled: false },
onUpdate: (event) => updates.push(event.item),
onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
});
const source = FakeEventSource.instances[0];
expect(source?.url).toBe("/api/notifications/stream");
expect(subscriber.currentSource).toBe(source);
source.emitMessage({ ...baseEvent, event: REALTIME_EVENT_NAMES.notificationUpdate, item });
source.emitMessage({ ...baseEvent, event: REALTIME_EVENT_NAMES.notificationUpdate, item: { ...item, providerPayload: "token=secret" } });
expect(updates).toEqual([item]);
expect(diagnostics).toEqual([
{
phase: "validation",
message: "notification item contains secret-like key: [redacted]",
eventName: REALTIME_EVENT_NAMES.notificationUpdate,
cursor: item.cursor,
requestId: "req_boundary_1",
},
]);
expect(JSON.stringify(diagnostics)).not.toMatch(/providerPayload|token=secret|authorization|Bearer/i);
subscriber.close();
expect(source.closed).toBe(true);
});
it("validates snapshot, update, error, and keepalive events from the entrypoint", () => {
expect(
validateRealtimeEvent({
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationSnapshot,
items: [item],
}),
).toEqual({
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationSnapshot,
items: [item],
});
expect(
validateRealtimeEvent({
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationUpdate,
item,
}),
).toEqual({
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationUpdate,
item,
});
expect(validateRealtimeEvent({ ...baseEvent, event: REALTIME_EVENT_NAMES.keepalive })).toEqual({ ...baseEvent, event: REALTIME_EVENT_NAMES.keepalive });
expect(validateRealtimeEvent({ ...baseEvent, event: REALTIME_EVENT_NAMES.error, code: "STREAM_FAILED", message: "Notification stream failed." })).toEqual({
...baseEvent,
event: REALTIME_EVENT_NAMES.error,
code: "STREAM_FAILED",
message: "Notification stream failed.",
});
});
it("publishes deterministic SSE frames through exported server APIs", () => {
const snapshotFrame = serializeRealtimeEvent({
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationSnapshot,
items: [item],
});
expect(snapshotFrame).toBe(
`id: ${item.cursor}\nevent: notification.snapshot\ndata: {"event":"notification.snapshot","cursor":"${item.cursor}","requestId":"req_boundary_1","tenantId":"tenant_1","userId":"user_1","items":[{"id":"delivery_boundary_1","cursor":"${item.cursor}","tenantId":"tenant_1","userId":"user_1","channel":"IN_APP","category":"billing","messageKey":"invoice.ready","status":"PENDING","attemptsMade":0,"createdAt":"2026-05-08T19:59:00.000Z","updatedAt":"2026-05-08T20:00:00.000Z","sentAt":null,"readAt":null}]}\n\n`,
);
expect(
serializeRealtimeEvent(
{
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationUpdate,
item: { ...item, status: "SENT", attemptsMade: 1, sentAt: "2026-05-08T20:01:00.000Z" },
},
{ retry: 3000 },
),
).toContain("retry: 3000\nid: 2026-05-08T20:00:00.000Z:delivery_boundary_1\nevent: notification.update\n");
expect(serializeRealtimeComment("keepalive req_boundary_1")).toBe(": keepalive req_boundary_1\n\n");
expect(serializeRealtimeEvent({ ...baseEvent, event: REALTIME_EVENT_NAMES.keepalive })).toContain("event: keepalive\n");
expect(serializeRealtimeEvent({ ...baseEvent, event: REALTIME_EVENT_NAMES.error, code: "STREAM_FAILED", message: "Notification stream failed." })).toContain(
'event: error\ndata: {"event":"error"',
);
});
it("rejects secret-bearing public inputs and keeps diagnostics redacted", () => {
expect(isRealtimeEvent({ ...baseEvent, event: REALTIME_EVENT_NAMES.notificationUpdate, item: { ...item, providerPayload: "token=secret" } })).toBe(false);
expect(() =>
serializeRealtimeEvent({
...baseEvent,
event: REALTIME_EVENT_NAMES.error,
code: "STREAM_FAILED",
message: "Notification stream failed.",
authorizationHeader: "Bearer secret",
}),
).toThrow(/secret-like key/);
const frame = serializeRealtimeEvent({
...baseEvent,
event: REALTIME_EVENT_NAMES.error,
code: "STREAM_FAILED",
message: "Notification stream failed.",
});
expect(frame).not.toMatch(/token|authorization|providerPayload|Bearer secret/i);
});
});
@@ -0,0 +1,292 @@
import { describe, expect, it, vi } from "vitest";
import { REALTIME_EVENT_NAMES, type NotificationStreamItem } from "./events.js";
import {
subscribeToRealtime,
type RealtimeEventSourceLike,
type RealtimeMessageEvent,
type RealtimeReconnectScheduler,
type RealtimeSubscriberDiagnostic,
type RealtimeSubscriberOptions,
} from "./client.js";
const item: NotificationStreamItem = {
id: "delivery_client_1",
cursor: "2026-05-08T20:00:00.000Z:delivery_client_1",
tenantId: "tenant_1",
userId: "user_1",
channel: "IN_APP",
category: "billing",
messageKey: "invoice.ready",
status: "SENT",
attemptsMade: 1,
createdAt: "2026-05-08T19:59:00.000Z",
updatedAt: "2026-05-08T20:00:00.000Z",
sentAt: "2026-05-08T20:00:00.000Z",
readAt: null,
};
const baseEvent = {
cursor: item.cursor,
requestId: "req_client_1",
tenantId: "tenant_1",
userId: "user_1",
};
class FakeScheduler implements RealtimeReconnectScheduler {
private nextHandle = 1;
readonly timers = new Map<number, () => void>();
readonly delays: number[] = [];
readonly cleared: number[] = [];
setTimeout(callback: () => void, delayMs: number): number {
const handle = this.nextHandle;
this.nextHandle += 1;
this.timers.set(handle, callback);
this.delays.push(delayMs);
return handle;
}
clearTimeout(handle: unknown): void {
if (typeof handle === "number") {
this.cleared.push(handle);
this.timers.delete(handle);
}
}
runNext(): void {
const [handle, callback] = [...this.timers.entries()][0] ?? [];
if (handle === undefined || callback === undefined) {
throw new Error("No pending reconnect timer.");
}
this.timers.delete(handle);
callback();
}
}
class FakeEventSource implements RealtimeEventSourceLike {
static instances: FakeEventSource[] = [];
readonly listeners = new Map<string, Array<(event: RealtimeMessageEvent) => void>>();
onopen: (() => void) | null = null;
onmessage: ((event: RealtimeMessageEvent) => void) | null = null;
onerror: ((event: unknown) => void) | null = null;
closed = false;
constructor(readonly url: string | URL) {
FakeEventSource.instances.push(this);
}
open(): void {
this.onopen?.();
}
emit(data: unknown): void {
this.onmessage?.({ data: typeof data === "string" ? data : JSON.stringify(data) });
}
emitNamed(type: string, data: unknown): void {
const message = { data: typeof data === "string" ? data : JSON.stringify(data), type };
for (const listener of this.listeners.get(type) ?? []) {
listener(message);
}
}
addEventListener(type: string, listener: (event: RealtimeMessageEvent) => void): void {
const listeners = this.listeners.get(type) ?? [];
listeners.push(listener);
this.listeners.set(type, listeners);
}
fail(): void {
this.onerror?.({});
}
close(): void {
this.closed = true;
}
}
function createSubscriber(overrides: Partial<RealtimeSubscriberOptions> = {}) {
FakeEventSource.instances = [];
const diagnostics: RealtimeSubscriberDiagnostic[] = [];
const statuses: string[] = [];
const subscriber = subscribeToRealtime({
...overrides,
url: overrides.url ?? "https://example.test/stream",
EventSource: overrides.EventSource ?? FakeEventSource,
onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
onStatus: (status) => statuses.push(status),
});
const source = FakeEventSource.instances[0];
return { diagnostics, source, statuses, subscriber };
}
function createScheduledSubscriber(options: Partial<RealtimeSubscriberOptions> = {}) {
const scheduler = new FakeScheduler();
const result = createSubscriber({
...options,
reconnect: { baseDelayMs: 100, maxDelayMs: 250, maxRetries: 3, ...options.reconnect, scheduler },
});
return { ...result, scheduler };
}
describe("realtime client subscriber", () => {
it("creates one EventSource instance and dispatches typed realtime events", () => {
const onSnapshot = vi.fn();
const onUpdate = vi.fn();
const onKeepalive = vi.fn();
const onError = vi.fn();
const { diagnostics, source, statuses } = createSubscriber({ onSnapshot, onUpdate, onKeepalive, onError });
source.open();
source.emitNamed(REALTIME_EVENT_NAMES.notificationSnapshot, { ...baseEvent, event: REALTIME_EVENT_NAMES.notificationSnapshot, items: [item] });
source.emitNamed(REALTIME_EVENT_NAMES.notificationUpdate, { ...baseEvent, event: REALTIME_EVENT_NAMES.notificationUpdate, item });
source.emitNamed(REALTIME_EVENT_NAMES.keepalive, { ...baseEvent, event: REALTIME_EVENT_NAMES.keepalive });
source.emitNamed(REALTIME_EVENT_NAMES.error, { ...baseEvent, event: REALTIME_EVENT_NAMES.error, code: "STREAM_FAILED", message: "Notification stream failed." });
expect(FakeEventSource.instances).toHaveLength(1);
expect([...source.listeners.keys()]).toEqual([
REALTIME_EVENT_NAMES.notificationSnapshot,
REALTIME_EVENT_NAMES.notificationUpdate,
REALTIME_EVENT_NAMES.keepalive,
REALTIME_EVENT_NAMES.error,
]);
expect(statuses).toEqual(["connecting", "open"]);
expect(onSnapshot).toHaveBeenCalledWith({ ...baseEvent, event: REALTIME_EVENT_NAMES.notificationSnapshot, items: [item] });
expect(onUpdate).toHaveBeenCalledWith({ ...baseEvent, event: REALTIME_EVENT_NAMES.notificationUpdate, item });
expect(onKeepalive).toHaveBeenCalledWith({ ...baseEvent, event: REALTIME_EVENT_NAMES.keepalive });
expect(onError).toHaveBeenCalledWith({ ...baseEvent, event: REALTIME_EVENT_NAMES.error, code: "STREAM_FAILED", message: "Notification stream failed." });
expect(diagnostics).toEqual([]);
});
it("reports malformed JSON and validation failures with redacted diagnostics", () => {
const { diagnostics, source } = createSubscriber();
source.emit("{not-json");
source.emit({ ...baseEvent, event: "notification.unknown", authorizationHeader: "Bearer secret-token" });
source.emit({ ...baseEvent, event: REALTIME_EVENT_NAMES.notificationUpdate, item: { ...item, providerPayload: "super-secret-token" } });
expect(diagnostics).toEqual([
{ phase: "parse", message: expect.stringContaining("[redacted]") },
{
phase: "validation",
message: "event must be a supported realtime event name",
eventName: "notification.unknown",
cursor: item.cursor,
requestId: "req_client_1",
},
{
phase: "validation",
message: "notification item contains secret-like key: [redacted]",
eventName: REALTIME_EVENT_NAMES.notificationUpdate,
cursor: item.cursor,
requestId: "req_client_1",
},
]);
expect(JSON.stringify(diagnostics)).not.toMatch(/secret-token|super-secret-token|Bearer/i);
});
it("reports EventSource and callback exceptions without exposing stack traces", () => {
const onUpdate = vi.fn(() => {
throw new Error("callback leaked token=abc123");
});
const { diagnostics, source } = createSubscriber({ reconnect: { enabled: false }, onUpdate });
source.fail();
source.emit({ ...baseEvent, event: REALTIME_EVENT_NAMES.notificationUpdate, item });
expect(diagnostics).toEqual([
{ phase: "eventsource", message: "EventSource reported an error." },
{
phase: "callback",
message: "callback leaked token=abc123",
eventName: REALTIME_EVENT_NAMES.notificationUpdate,
cursor: item.cursor,
requestId: "req_client_1",
},
]);
expect(JSON.stringify(diagnostics)).not.toContain("Error:");
});
it("closes explicitly once and ignores later messages or duplicate close calls", () => {
const onKeepalive = vi.fn();
const { source, statuses, subscriber } = createSubscriber({ onKeepalive });
subscriber.close();
subscriber.close();
source.open();
source.fail();
source.emit({ ...baseEvent, event: REALTIME_EVENT_NAMES.keepalive });
expect(source.closed).toBe(true);
expect(statuses).toEqual(["connecting", "closed"]);
expect(onKeepalive).not.toHaveBeenCalled();
});
it("schedules deterministic capped reconnects and replaces failed sources", () => {
const { diagnostics, scheduler, source, statuses } = createScheduledSubscriber();
source.fail();
expect(source.closed).toBe(true);
expect(scheduler.delays).toEqual([100]);
expect(scheduler.timers.size).toBe(1);
expect(FakeEventSource.instances).toHaveLength(1);
expect(statuses).toEqual(["connecting", "reconnecting"]);
expect(diagnostics).toContainEqual({ phase: "reconnect", message: "Realtime reconnect scheduled.", retryAttempt: 1, delayMs: 100 });
scheduler.runNext();
const retrySource = FakeEventSource.instances[1];
expect(FakeEventSource.instances).toHaveLength(2);
expect(retrySource.closed).toBe(false);
expect(statuses).toEqual(["connecting", "reconnecting", "connecting"]);
});
it("stops reconnecting after maxRetries is reached", () => {
const { diagnostics, scheduler, source, statuses } = createScheduledSubscriber({ reconnect: { baseDelayMs: 50, maxDelayMs: 75, maxRetries: 2 } });
source.fail();
scheduler.runNext();
FakeEventSource.instances[1].fail();
scheduler.runNext();
FakeEventSource.instances[2].fail();
expect(FakeEventSource.instances).toHaveLength(3);
expect(scheduler.delays).toEqual([50, 75]);
expect(scheduler.timers.size).toBe(0);
expect(diagnostics).toContainEqual({ phase: "reconnect", message: "Realtime reconnect retry limit reached.", retryAttempt: 2 });
expect(statuses.at(-1)).toBe("closed");
});
it("resets retry attempts after a successful open", () => {
const { diagnostics, scheduler, source } = createScheduledSubscriber({ reconnect: { baseDelayMs: 100, maxDelayMs: 1_000, maxRetries: 3 } });
source.fail();
scheduler.runNext();
FakeEventSource.instances[1].open();
FakeEventSource.instances[1].fail();
expect(scheduler.delays).toEqual([100, 100]);
expect(diagnostics).toContainEqual({ phase: "reconnect", message: "Realtime reconnect scheduled.", retryAttempt: 1, delayMs: 100 });
});
it("cancels pending reconnects and prevents future sources after explicit close", () => {
const { scheduler, source, statuses, subscriber } = createScheduledSubscriber();
source.fail();
subscriber.close();
expect(source.closed).toBe(true);
expect(scheduler.timers.size).toBe(0);
expect(scheduler.cleared).toEqual([1]);
expect(statuses).toEqual(["connecting", "reconnecting", "closed"]);
expect(() => scheduler.runNext()).toThrow("No pending reconnect timer.");
expect(FakeEventSource.instances).toHaveLength(1);
});
});
@@ -0,0 +1,320 @@
import { REALTIME_EVENT_NAMES, validateRealtimeEvent, type KeepaliveEvent, type NotificationSnapshotEvent, type NotificationUpdateEvent, type RealtimeErrorEvent } from "./events.js";
export type RealtimeSubscriberStatus = "connecting" | "open" | "reconnecting" | "closed";
export type RealtimeSubscriberDiagnostic = {
phase: "parse" | "validation" | "callback" | "eventsource" | "reconnect";
message: string;
eventName?: string;
cursor?: string;
requestId?: string;
retryAttempt?: number;
delayMs?: number;
};
export type RealtimeMessageEvent = {
data: string;
type?: string;
};
export type RealtimeEventSourceLike = {
onopen: (() => void) | null;
onmessage: ((event: RealtimeMessageEvent) => void) | null;
onerror: ((event: unknown) => void) | null;
addEventListener?: (type: string, listener: (event: RealtimeMessageEvent) => void) => void;
close: () => void;
};
export type RealtimeEventSourceConstructor = new (url: string | URL) => RealtimeEventSourceLike;
export type RealtimeReconnectScheduler = {
setTimeout: (callback: () => void, delayMs: number) => unknown;
clearTimeout: (handle: unknown) => void;
};
export type RealtimeReconnectOptions = {
enabled?: boolean;
baseDelayMs?: number;
maxDelayMs?: number;
maxRetries?: number;
scheduler?: RealtimeReconnectScheduler;
};
export type RealtimeSubscriberOptions = {
url: string | URL;
EventSource?: RealtimeEventSourceConstructor;
reconnect?: RealtimeReconnectOptions;
onStatus?: (status: RealtimeSubscriberStatus) => void;
onDiagnostic?: (diagnostic: RealtimeSubscriberDiagnostic) => void;
onSnapshot?: (event: NotificationSnapshotEvent) => void;
onUpdate?: (event: NotificationUpdateEvent) => void;
onKeepalive?: (event: KeepaliveEvent) => void;
onError?: (event: RealtimeErrorEvent) => void;
};
export type RealtimeSubscriber = {
readonly source: RealtimeEventSourceLike;
readonly currentSource: RealtimeEventSourceLike;
close: () => void;
};
type ParsedEventShape = {
event?: unknown;
cursor?: unknown;
requestId?: unknown;
};
const MAX_DIAGNOSTIC_MESSAGE_LENGTH = 160;
const DEFAULT_RECONNECT_BASE_DELAY_MS = 1_000;
const DEFAULT_RECONNECT_MAX_DELAY_MS = 30_000;
const DEFAULT_RECONNECT_MAX_RETRIES = 5;
export function subscribeToRealtime(options: RealtimeSubscriberOptions): RealtimeSubscriber {
const EventSourceConstructor = options.EventSource ?? getGlobalEventSource();
const reconnect = normalizeReconnectOptions(options.reconnect);
let closed = false;
let retryAttempts = 0;
let reconnectTimer: unknown;
let source = connect();
function connect(): RealtimeEventSourceLike {
clearReconnectTimer();
const nextSource = new EventSourceConstructor(options.url);
emitStatus(options, "connecting");
nextSource.onopen = () => {
if (!closed) {
retryAttempts = 0;
emitStatus(options, "open");
}
};
nextSource.onmessage = (message) => {
if (!closed) {
handleMessage(options, message);
}
};
registerNamedRealtimeEventListeners(nextSource, options, () => closed);
nextSource.onerror = () => {
if (!closed) {
handleEventSourceError(nextSource);
}
};
return nextSource;
}
function handleEventSourceError(failedSource: RealtimeEventSourceLike): void {
emitDiagnostic(options, { phase: "eventsource", message: "EventSource reported an error." });
failedSource.close();
if (!reconnect.enabled) {
emitStatus(options, "closed");
return;
}
if (retryAttempts >= reconnect.maxRetries) {
emitDiagnostic(options, {
phase: "reconnect",
message: "Realtime reconnect retry limit reached.",
retryAttempt: retryAttempts,
});
emitStatus(options, "closed");
return;
}
retryAttempts += 1;
const delayMs = reconnectDelay(retryAttempts, reconnect.baseDelayMs, reconnect.maxDelayMs);
emitDiagnostic(options, {
phase: "reconnect",
message: "Realtime reconnect scheduled.",
retryAttempt: retryAttempts,
delayMs,
});
emitStatus(options, "reconnecting");
reconnectTimer = reconnect.scheduler.setTimeout(() => {
reconnectTimer = undefined;
if (!closed) {
source = connect();
}
}, delayMs);
}
function clearReconnectTimer(): void {
if (reconnectTimer !== undefined) {
reconnect.scheduler.clearTimeout(reconnectTimer);
reconnectTimer = undefined;
}
}
return {
get source() {
return source;
},
get currentSource() {
return source;
},
close: () => {
if (closed) {
return;
}
closed = true;
clearReconnectTimer();
source.close();
emitStatus(options, "closed");
},
};
}
function registerNamedRealtimeEventListeners(
source: RealtimeEventSourceLike,
options: RealtimeSubscriberOptions,
isClosed: () => boolean
): void {
if (typeof source.addEventListener !== "function") {
return;
}
for (const eventName of Object.values(REALTIME_EVENT_NAMES)) {
source.addEventListener(eventName, (message) => {
if (!isClosed()) {
handleMessage(options, message);
}
});
}
}
type NormalizedRealtimeReconnectOptions = Required<RealtimeReconnectOptions>;
function normalizeReconnectOptions(options: RealtimeReconnectOptions | undefined): NormalizedRealtimeReconnectOptions {
const baseDelayMs = normalizePositiveInteger(options?.baseDelayMs, DEFAULT_RECONNECT_BASE_DELAY_MS);
return {
enabled: options?.enabled ?? true,
baseDelayMs,
maxDelayMs: Math.max(baseDelayMs, normalizePositiveInteger(options?.maxDelayMs, DEFAULT_RECONNECT_MAX_DELAY_MS)),
maxRetries: normalizeNonNegativeInteger(options?.maxRetries, DEFAULT_RECONNECT_MAX_RETRIES),
scheduler: options?.scheduler ?? globalReconnectScheduler,
};
}
function reconnectDelay(retryAttempt: number, baseDelayMs: number, maxDelayMs: number): number {
return Math.min(maxDelayMs, baseDelayMs * 2 ** (retryAttempt - 1));
}
function normalizePositiveInteger(value: number | undefined, fallback: number): number {
return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
}
function normalizeNonNegativeInteger(value: number | undefined, fallback: number): number {
return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
}
const globalReconnectScheduler: RealtimeReconnectScheduler = {
setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
clearTimeout: (handle) => globalThis.clearTimeout(handle as ReturnType<typeof globalThis.setTimeout>),
};
function handleMessage(options: RealtimeSubscriberOptions, message: RealtimeMessageEvent): void {
let parsed: unknown;
try {
parsed = JSON.parse(message.data);
} catch {
emitDiagnostic(options, { phase: "parse", message: "Malformed realtime event JSON: [redacted]" });
return;
}
try {
const event = validateRealtimeEvent(parsed);
switch (event.event) {
case REALTIME_EVENT_NAMES.notificationSnapshot:
invokeCallback(options, "onSnapshot", event);
return;
case REALTIME_EVENT_NAMES.notificationUpdate:
invokeCallback(options, "onUpdate", event);
return;
case REALTIME_EVENT_NAMES.keepalive:
invokeCallback(options, "onKeepalive", event);
return;
case REALTIME_EVENT_NAMES.error:
invokeCallback(options, "onError", event);
return;
}
} catch (error) {
emitDiagnostic(options, {
...extractDiagnosticContext(parsed),
phase: "validation",
message: redactedErrorMessage(error),
});
}
}
function invokeCallback<Event>(options: RealtimeSubscriberOptions, key: keyof RealtimeSubscriberOptions, event: Event): void {
const callback = options[key];
if (typeof callback !== "function") {
return;
}
try {
(callback as (event: Event) => void)(event);
} catch (error) {
emitDiagnostic(options, {
...extractDiagnosticContext(event),
phase: "callback",
message: redactedErrorMessage(error),
});
}
}
function emitStatus(options: RealtimeSubscriberOptions, status: RealtimeSubscriberStatus): void {
options.onStatus?.(status);
}
function emitDiagnostic(options: RealtimeSubscriberOptions, diagnostic: RealtimeSubscriberDiagnostic): void {
options.onDiagnostic?.(diagnostic);
}
function extractDiagnosticContext(input: unknown): Pick<RealtimeSubscriberDiagnostic, "eventName" | "cursor" | "requestId"> {
if (!isRecord(input)) {
return {};
}
const event = input as ParsedEventShape;
return {
eventName: typeof event.event === "string" ? event.event : undefined,
cursor: typeof event.cursor === "string" ? event.cursor : undefined,
requestId: typeof event.requestId === "string" ? event.requestId : undefined,
};
}
function redactedErrorMessage(error: unknown): string {
if (!(error instanceof Error)) {
return "Realtime subscriber rejected an invalid event.";
}
return error.message.replace(/: .+$/u, ": [redacted]").slice(0, MAX_DIAGNOSTIC_MESSAGE_LENGTH);
}
function getGlobalEventSource(): RealtimeEventSourceConstructor {
const constructor = globalThis.EventSource as RealtimeEventSourceConstructor | undefined;
if (constructor === undefined) {
throw new Error("EventSource is not available; provide an EventSource option.");
}
return constructor;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
@@ -0,0 +1,146 @@
import { describe, expect, it } from "vitest";
import { REALTIME_EVENT_NAMES, isRealtimeEvent, validateRealtimeEvent, type NotificationStreamItem } from "./events.js";
const item: NotificationStreamItem = {
id: "delivery_1",
cursor: "2026-05-08T20:00:00.000Z:delivery_1",
tenantId: "tenant_1",
userId: "user_1",
channel: "IN_APP",
category: "billing",
messageKey: "invoice.ready",
status: "SENT",
attemptsMade: 1,
createdAt: "2026-05-08T19:59:00.000Z",
updatedAt: "2026-05-08T20:00:00.000Z",
sentAt: "2026-05-08T20:00:00.000Z",
readAt: null,
};
describe("realtime event contract", () => {
it("accepts and normalizes a public notification snapshot", () => {
expect(
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationSnapshot,
cursor: "2026-05-08T20:00:00.000Z:delivery_1",
requestId: "req_1",
tenantId: "tenant_1",
userId: "user_1",
items: [item],
}),
).toEqual({
event: REALTIME_EVENT_NAMES.notificationSnapshot,
cursor: "2026-05-08T20:00:00.000Z:delivery_1",
requestId: "req_1",
tenantId: "tenant_1",
userId: "user_1",
items: [item],
});
});
it("accepts update, keepalive, and redacted error envelopes", () => {
expect(
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationUpdate,
cursor: item.cursor,
requestId: "req_skipped",
item: { ...item, status: "SKIPPED", attemptsMade: 0, sentAt: null },
}),
).toMatchObject({ event: REALTIME_EVENT_NAMES.notificationUpdate, item: expect.objectContaining({ status: "SKIPPED" }) });
expect(
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationUpdate,
cursor: item.cursor,
requestId: "req_2",
item,
}),
).toMatchObject({ event: REALTIME_EVENT_NAMES.notificationUpdate, item });
expect(
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.keepalive,
cursor: item.cursor,
requestId: "req_3",
}),
).toEqual({ event: REALTIME_EVENT_NAMES.keepalive, cursor: item.cursor, requestId: "req_3" });
expect(
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.error,
cursor: item.cursor,
requestId: "req_4",
code: "STREAM_FAILED",
message: "Notification stream failed.",
}),
).toEqual({
event: REALTIME_EVENT_NAMES.error,
cursor: item.cursor,
requestId: "req_4",
code: "STREAM_FAILED",
message: "Notification stream failed.",
});
});
it("rejects invalid event names and malformed identifiers", () => {
expect(() => validateRealtimeEvent({ event: "notification", cursor: item.cursor, requestId: "req_1", items: [] })).toThrow(
/supported realtime event name/,
);
expect(() => validateRealtimeEvent({ event: REALTIME_EVENT_NAMES.keepalive, cursor: 123, requestId: "req_1" })).toThrow(/cursor/);
expect(() => validateRealtimeEvent({ event: REALTIME_EVENT_NAMES.keepalive, cursor: item.cursor, requestId: "" })).toThrow(/requestId/);
expect(isRealtimeEvent({ event: "notification", cursor: item.cursor, requestId: "req_1" })).toBe(false);
});
it("rejects malformed items and unsupported public fields", () => {
expect(() =>
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationSnapshot,
cursor: item.cursor,
requestId: "req_1",
items: [{ ...item, channel: "EMAIL" }],
}),
).toThrow(/IN_APP/);
expect(() =>
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationSnapshot,
cursor: item.cursor,
requestId: "req_1",
items: [{ ...item, status: "DELIVERED" }],
}),
).toThrow(/supported notification status/);
expect(() =>
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationSnapshot,
cursor: item.cursor,
requestId: "req_1",
items: [{ ...item, providerMessageId: "provider_1" }],
}),
).toThrow(/secret-like key/);
});
it("rejects metadata leakage attempts on envelopes and error diagnostics", () => {
expect(() =>
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.notificationUpdate,
cursor: item.cursor,
requestId: "req_1",
item,
authorizationHeader: "Bearer token",
}),
).toThrow(/secret-like key/);
expect(() =>
validateRealtimeEvent({
event: REALTIME_EVENT_NAMES.error,
cursor: item.cursor,
requestId: "req_1",
code: "STREAM_FAILED",
message: "Notification stream failed.",
stack: "Error: provider token abc",
}),
).toThrow(/secret-like key/);
});
});
@@ -0,0 +1,237 @@
export const REALTIME_EVENT_NAMES = {
notificationSnapshot: "notification.snapshot",
notificationUpdate: "notification.update",
keepalive: "keepalive",
error: "error",
} as const;
export type RealtimeEventName = (typeof REALTIME_EVENT_NAMES)[keyof typeof REALTIME_EVENT_NAMES];
export type NotificationDeliveryStatus = "PENDING" | "SENT" | "FAILED" | "SKIPPED" | "READ";
export type NotificationChannel = "IN_APP";
export type NotificationStreamCursor = string;
export type NotificationStreamItem = {
id: string;
cursor: NotificationStreamCursor;
tenantId?: string | null;
userId?: string | null;
channel: NotificationChannel;
category: string;
messageKey: string;
status: NotificationDeliveryStatus;
attemptsMade: number;
createdAt: string;
updatedAt: string;
sentAt?: string | null;
readAt?: string | null;
};
export type RealtimeEventBase = {
event: RealtimeEventName;
cursor: string;
requestId: string;
tenantId?: string | null;
userId?: string | null;
};
export type NotificationSnapshotEvent = RealtimeEventBase & {
event: typeof REALTIME_EVENT_NAMES.notificationSnapshot;
items: NotificationStreamItem[];
};
export type NotificationUpdateEvent = RealtimeEventBase & {
event: typeof REALTIME_EVENT_NAMES.notificationUpdate;
item: NotificationStreamItem;
};
export type KeepaliveEvent = RealtimeEventBase & {
event: typeof REALTIME_EVENT_NAMES.keepalive;
};
export type RealtimeErrorEvent = RealtimeEventBase & {
event: typeof REALTIME_EVENT_NAMES.error;
code: string;
message: string;
};
export type RealtimeEvent = NotificationSnapshotEvent | NotificationUpdateEvent | KeepaliveEvent | RealtimeErrorEvent;
const REALTIME_EVENT_NAME_VALUES = new Set<RealtimeEventName>(Object.values(REALTIME_EVENT_NAMES));
const NOTIFICATION_STATUSES = new Set<NotificationDeliveryStatus>(["PENDING", "SENT", "FAILED", "SKIPPED", "READ"]);
const SECRET_KEY_PATTERN = /authorization|cookie|password|secret|token|api[-_]?key|payload|provider|exception|stack|header|body|metadata/i;
const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
const MAX_STRING_LENGTH = 500;
const MAX_ITEMS_PER_EVENT = 100;
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
function assertAllowedKeys(value: Record<string, unknown>, allowedKeys: ReadonlySet<string>, label: string): void {
for (const key of Object.keys(value)) {
if (SECRET_KEY_PATTERN.test(key)) {
throw new Error(`${label} contains secret-like key: ${key}`);
}
if (!allowedKeys.has(key)) {
throw new Error(`${label} contains unsupported key: ${key}`);
}
}
}
function normalizeRequiredString(value: unknown, label: string): string {
if (typeof value !== "string") {
throw new Error(`${label} must be a string`);
}
const normalized = value.trim();
if (!normalized) {
throw new Error(`${label} must not be empty`);
}
if (normalized.length > MAX_STRING_LENGTH) {
throw new Error(`${label} is too long`);
}
return normalized;
}
function normalizeOptionalString(value: unknown, label: string): string | null | undefined {
if (value === undefined) {
return undefined;
}
if (value === null) {
return null;
}
return normalizeRequiredString(value, label);
}
function normalizeOptionalIsoDate(value: unknown, label: string): string | null | undefined {
if (value === undefined) {
return undefined;
}
if (value === null) {
return null;
}
const normalized = normalizeRequiredString(value, label);
if (!ISO_DATE_PATTERN.test(normalized) || Number.isNaN(Date.parse(normalized))) {
throw new Error(`${label} must be an ISO timestamp`);
}
return normalized;
}
function normalizeStatus(value: unknown): NotificationDeliveryStatus {
if (typeof value !== "string" || !NOTIFICATION_STATUSES.has(value as NotificationDeliveryStatus)) {
throw new Error("item.status must be a supported notification status");
}
return value as NotificationDeliveryStatus;
}
function normalizeAttemptsMade(value: unknown): number {
if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
throw new Error("item.attemptsMade must be a non-negative integer");
}
return value;
}
function normalizeItem(value: unknown): NotificationStreamItem {
if (!isRecord(value)) {
throw new Error("notification item must be an object");
}
assertAllowedKeys(
value,
new Set(["id", "cursor", "tenantId", "userId", "channel", "category", "messageKey", "status", "attemptsMade", "createdAt", "updatedAt", "sentAt", "readAt"]),
"notification item",
);
if (value.channel !== "IN_APP") {
throw new Error("item.channel must be IN_APP");
}
return {
id: normalizeRequiredString(value.id, "item.id"),
cursor: normalizeRequiredString(value.cursor, "item.cursor"),
tenantId: normalizeOptionalString(value.tenantId, "item.tenantId") ?? null,
userId: normalizeOptionalString(value.userId, "item.userId") ?? null,
channel: "IN_APP",
category: normalizeRequiredString(value.category, "item.category"),
messageKey: normalizeRequiredString(value.messageKey, "item.messageKey"),
status: normalizeStatus(value.status),
attemptsMade: normalizeAttemptsMade(value.attemptsMade),
createdAt: normalizeOptionalIsoDate(value.createdAt, "item.createdAt") ?? "",
updatedAt: normalizeOptionalIsoDate(value.updatedAt, "item.updatedAt") ?? "",
sentAt: normalizeOptionalIsoDate(value.sentAt, "item.sentAt") ?? null,
readAt: normalizeOptionalIsoDate(value.readAt, "item.readAt") ?? null,
};
}
function normalizeBase(value: Record<string, unknown>): RealtimeEventBase {
const event = value.event;
if (typeof event !== "string" || !REALTIME_EVENT_NAME_VALUES.has(event as RealtimeEventName)) {
throw new Error("event must be a supported realtime event name");
}
return {
event: event as RealtimeEventName,
cursor: normalizeRequiredString(value.cursor, "cursor"),
requestId: normalizeRequiredString(value.requestId, "requestId"),
tenantId: normalizeOptionalString(value.tenantId, "tenantId"),
userId: normalizeOptionalString(value.userId, "userId"),
};
}
export function validateRealtimeEvent(input: unknown): RealtimeEvent {
if (!isRecord(input)) {
throw new Error("realtime event must be an object");
}
const base = normalizeBase(input);
switch (base.event) {
case REALTIME_EVENT_NAMES.notificationSnapshot: {
assertAllowedKeys(input, new Set(["event", "cursor", "requestId", "tenantId", "userId", "items"]), "snapshot event");
if (!Array.isArray(input.items)) {
throw new Error("snapshot event items must be an array");
}
if (input.items.length > MAX_ITEMS_PER_EVENT) {
throw new Error("snapshot event contains too many items");
}
return { ...base, event: REALTIME_EVENT_NAMES.notificationSnapshot, items: input.items.map(normalizeItem) };
}
case REALTIME_EVENT_NAMES.notificationUpdate:
assertAllowedKeys(input, new Set(["event", "cursor", "requestId", "tenantId", "userId", "item"]), "update event");
return { ...base, event: REALTIME_EVENT_NAMES.notificationUpdate, item: normalizeItem(input.item) };
case REALTIME_EVENT_NAMES.keepalive:
assertAllowedKeys(input, new Set(["event", "cursor", "requestId", "tenantId", "userId"]), "keepalive event");
return { ...base, event: REALTIME_EVENT_NAMES.keepalive };
case REALTIME_EVENT_NAMES.error:
assertAllowedKeys(input, new Set(["event", "cursor", "requestId", "tenantId", "userId", "code", "message"]), "error event");
return {
...base,
event: REALTIME_EVENT_NAMES.error,
code: normalizeRequiredString(input.code, "code"),
message: normalizeRequiredString(input.message, "message"),
};
}
}
export function isRealtimeEvent(input: unknown): input is RealtimeEvent {
try {
validateRealtimeEvent(input);
return true;
} catch {
return false;
}
}
@@ -0,0 +1,90 @@
import { describe, expect, it } from "vitest";
import { REALTIME_EVENT_NAMES, type NotificationStreamItem } from "./events.js";
import {
assertNotificationEventInAppScope,
assertNotificationItemInAppScope,
normalizeNotificationStreamScope,
redactNotificationGuardDiagnostic,
} from "./guards.js";
const item: NotificationStreamItem = {
id: "delivery_guard_1",
cursor: "2026-05-08T20:00:00.000Z:delivery_guard_1",
tenantId: "tenant_1",
userId: "user_1",
channel: "IN_APP",
category: "billing",
messageKey: "invoice.ready",
status: "SENT",
attemptsMade: 1,
createdAt: "2026-05-08T19:59:00.000Z",
updatedAt: "2026-05-08T20:00:00.000Z",
sentAt: "2026-05-08T20:00:00.000Z",
readAt: null,
};
const scope = { tenantId: "tenant_1", userId: "user_1" };
describe("notification stream guards", () => {
it("normalizes trimmed valid stream scope", () => {
expect(normalizeNotificationStreamScope({ tenantId: " tenant_1 ", userId: " user_1 ", afterCursor: " cursor_1 " })).toEqual({
tenantId: "tenant_1",
userId: "user_1",
afterCursor: "cursor_1",
});
});
it("rejects missing or blank tenant and user scope", () => {
expect(() => normalizeNotificationStreamScope({ userId: "user_1" })).toThrow(/tenantId is required/);
expect(() => normalizeNotificationStreamScope({ tenantId: " ", userId: "user_1" })).toThrow(/tenantId must not be empty/);
expect(() => normalizeNotificationStreamScope({ tenantId: "tenant_1" })).toThrow(/userId is required/);
expect(() => normalizeNotificationStreamScope({ tenantId: "tenant_1", userId: "\t" })).toThrow(/userId must not be empty/);
});
it("rejects non-IN_APP notification items", () => {
expect(() => assertNotificationItemInAppScope({ ...item, channel: "EMAIL" as "IN_APP" }, scope)).toThrow(/IN_APP/);
});
it("rejects tenant and user mismatches between stream scope and items", () => {
expect(() => assertNotificationItemInAppScope({ ...item, tenantId: "tenant_2" }, scope)).toThrow(/item\.tenantId/);
expect(() => assertNotificationItemInAppScope({ ...item, userId: "user_2" }, scope)).toThrow(/item\.userId/);
});
it("rejects tenant and user mismatches between stream scope and events", () => {
expect(() =>
assertNotificationEventInAppScope(
{
event: REALTIME_EVENT_NAMES.notificationSnapshot,
cursor: item.cursor,
requestId: "req_guard_1",
tenantId: "tenant_2",
userId: "user_1",
items: [item],
},
scope,
),
).toThrow(/event\.tenantId/);
expect(() =>
assertNotificationEventInAppScope(
{
event: REALTIME_EVENT_NAMES.notificationUpdate,
cursor: item.cursor,
requestId: "req_guard_2",
tenantId: "tenant_1",
userId: "user_1",
item: { ...item, userId: "user_2" },
},
scope,
),
).toThrow(/item\.userId/);
});
it("redacts secret-like guard diagnostic text", () => {
const diagnostic = redactNotificationGuardDiagnostic(new Error("provider payload token=secret Bearer abc123 should not leak"));
expect(diagnostic).toContain("[redacted]");
expect(diagnostic).not.toMatch(/provider|payload|token=secret|Bearer abc123/i);
});
});
@@ -0,0 +1,98 @@
import { type NotificationStreamItem, type NotificationChannel, type RealtimeEvent } from "./events.js";
export type NotificationStreamScope = {
tenantId: string;
userId: string;
afterCursor?: string;
};
export type NotificationStreamScopeInput = {
tenantId?: unknown;
userId?: unknown;
afterCursor?: unknown;
};
const MAX_SCOPE_VALUE_LENGTH = 500;
const SECRET_VALUE_PATTERN = /bearer\s+[a-z0-9._~+\-/]+=*|api[-_]?key\s*[:=]\s*\S+|token\s*[:=]\s*\S+|password\s*[:=]\s*\S+|secret\s*[:=]\s*\S+|authorization\s*[:=]\s*\S+|provider|metadata|payload|exception|stack/gi;
export function normalizeNotificationStreamScope(input: NotificationStreamScopeInput): NotificationStreamScope {
const tenantId = normalizeRequiredScopeString(input.tenantId, "tenantId");
const userId = normalizeRequiredScopeString(input.userId, "userId");
const afterCursor = normalizeOptionalScopeString(input.afterCursor, "afterCursor");
return afterCursor === undefined ? { tenantId, userId } : { tenantId, userId, afterCursor };
}
export function assertNotificationItemInAppScope(item: NotificationStreamItem, scope: NotificationStreamScope): void {
assertInAppChannel(item.channel);
assertScopeValueMatches(item.tenantId, scope.tenantId, "item.tenantId");
assertScopeValueMatches(item.userId, scope.userId, "item.userId");
}
export function assertNotificationEventInAppScope(event: RealtimeEvent, scope: NotificationStreamScope): void {
assertScopeValueMatches(event.tenantId, scope.tenantId, "event.tenantId");
assertScopeValueMatches(event.userId, scope.userId, "event.userId");
switch (event.event) {
case "notification.snapshot":
for (const item of event.items) {
assertNotificationItemInAppScope(item, scope);
}
return;
case "notification.update":
assertNotificationItemInAppScope(event.item, scope);
return;
case "keepalive":
case "error":
return;
}
}
export function redactNotificationGuardDiagnostic(value: unknown): string {
const message = value instanceof Error ? value.message : String(value);
return message.replace(SECRET_VALUE_PATTERN, "[redacted]").replace(/: .+$/u, ": [redacted]").slice(0, 160);
}
function normalizeRequiredScopeString(value: unknown, label: string): string {
const normalized = normalizeOptionalScopeString(value, label);
if (normalized === undefined) {
throw new Error(`${label} is required`);
}
return normalized;
}
function normalizeOptionalScopeString(value: unknown, label: string): string | undefined {
if (value === undefined || value === null) {
return undefined;
}
if (typeof value !== "string") {
throw new Error(`${label} must be a string`);
}
const normalized = value.trim();
if (!normalized) {
throw new Error(`${label} must not be empty`);
}
if (normalized.length > MAX_SCOPE_VALUE_LENGTH) {
throw new Error(`${label} is too long`);
}
return normalized;
}
function assertInAppChannel(channel: NotificationChannel): void {
if (channel !== "IN_APP") {
throw new Error("item.channel must be IN_APP");
}
}
function assertScopeValueMatches(actual: string | null | undefined, expected: string, label: string): void {
if (actual !== expected) {
throw new Error(`${label} does not match notification stream scope`);
}
}
@@ -0,0 +1,12 @@
import { describe, expect, it } from "vitest";
describe("@toolctrl/realtime public entrypoint", () => {
it("exports realtime event contract bindings", async () => {
const entrypoint = await import("./index.js");
expect(entrypoint.REALTIME_EVENT_NAMES.notificationSnapshot).toBe("notification.snapshot");
expect(entrypoint.validateRealtimeEvent).toBeTypeOf("function");
expect(entrypoint.isRealtimeEvent).toBeTypeOf("function");
expect(entrypoint.subscribeToRealtime).toBeTypeOf("function");
});
});
@@ -0,0 +1,4 @@
export * from "./client.js";
export * from "./events.js";
export * from "./guards.js";
export * from "./server.js";
@@ -0,0 +1,115 @@
import { describe, expect, it } from "vitest";
import { REALTIME_EVENT_NAMES, type NotificationStreamItem } from "./events.js";
import { serializeRealtimeComment, serializeRealtimeEvent } from "./server.js";
const item: NotificationStreamItem = {
id: "delivery_1",
cursor: "2026-05-08T20:00:00.000Z:delivery_1",
tenantId: "tenant_1",
userId: "user_1",
channel: "IN_APP",
category: "billing",
messageKey: "invoice.ready",
status: "SENT",
attemptsMade: 1,
createdAt: "2026-05-08T19:59:00.000Z",
updatedAt: "2026-05-08T20:00:00.000Z",
sentAt: "2026-05-08T20:00:00.000Z",
readAt: null,
};
const baseEvent = {
cursor: item.cursor,
requestId: "req_1",
tenantId: "tenant_1",
userId: "user_1",
};
describe("SSE realtime serialization", () => {
it("serializes deterministic snapshot frames with cursor ids", () => {
expect(
serializeRealtimeEvent({
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationSnapshot,
items: [item],
}),
).toBe(
`id: ${item.cursor}\nevent: notification.snapshot\ndata: {"event":"notification.snapshot","cursor":"${item.cursor}","requestId":"req_1","tenantId":"tenant_1","userId":"user_1","items":[{"id":"delivery_1","cursor":"${item.cursor}","tenantId":"tenant_1","userId":"user_1","channel":"IN_APP","category":"billing","messageKey":"invoice.ready","status":"SENT","attemptsMade":1,"createdAt":"2026-05-08T19:59:00.000Z","updatedAt":"2026-05-08T20:00:00.000Z","sentAt":"2026-05-08T20:00:00.000Z","readAt":null}]}\n\n`,
);
});
it("serializes updates with retry hints before event data", () => {
expect(
serializeRealtimeEvent(
{
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationUpdate,
item,
},
{ retry: 5000 },
),
).toBe(
`retry: 5000\nid: ${item.cursor}\nevent: notification.update\ndata: {"event":"notification.update","cursor":"${item.cursor}","requestId":"req_1","tenantId":"tenant_1","userId":"user_1","item":{"id":"delivery_1","cursor":"${item.cursor}","tenantId":"tenant_1","userId":"user_1","channel":"IN_APP","category":"billing","messageKey":"invoice.ready","status":"SENT","attemptsMade":1,"createdAt":"2026-05-08T19:59:00.000Z","updatedAt":"2026-05-08T20:00:00.000Z","sentAt":"2026-05-08T20:00:00.000Z","readAt":null}}\n\n`,
);
});
it("serializes keepalive comments and keepalive events", () => {
expect(serializeRealtimeComment("keepalive req_1")).toBe(": keepalive req_1\n\n");
expect(
serializeRealtimeEvent({
event: REALTIME_EVENT_NAMES.keepalive,
cursor: item.cursor,
requestId: "req_keepalive",
}),
).toBe(`id: ${item.cursor}\nevent: keepalive\ndata: {"event":"keepalive","cursor":"${item.cursor}","requestId":"req_keepalive"}\n\n`);
});
it("serializes redacted error diagnostics without secret material", () => {
const frame = serializeRealtimeEvent({
event: REALTIME_EVENT_NAMES.error,
cursor: item.cursor,
requestId: "req_error",
code: "STREAM_FAILED",
message: "Notification stream failed.",
});
expect(frame).toBe(
`id: ${item.cursor}\nevent: error\ndata: {"event":"error","cursor":"${item.cursor}","requestId":"req_error","code":"STREAM_FAILED","message":"Notification stream failed."}\n\n`,
);
expect(frame).not.toContain("token");
expect(frame).not.toContain("authorization");
});
it("fails validation before serializing invalid events and secret-like fields", () => {
expect(() =>
serializeRealtimeEvent({
...baseEvent,
event: REALTIME_EVENT_NAMES.notificationSnapshot,
items: [{ ...item, providerPayload: "token=secret" }],
}),
).toThrow(/secret-like key/);
expect(() =>
serializeRealtimeEvent({
event: REALTIME_EVENT_NAMES.error,
cursor: item.cursor,
requestId: "req_error",
code: "STREAM_FAILED",
message: "Notification stream failed.",
authorizationHeader: "Bearer secret",
}),
).toThrow(/secret-like key/);
});
it("rejects invalid retry hints and newline injection", () => {
expect(() => serializeRealtimeEvent({ event: REALTIME_EVENT_NAMES.keepalive, cursor: item.cursor, requestId: "req_1" }, { retry: -1 })).toThrow(
/retry/,
);
expect(() => serializeRealtimeComment("keepalive\nevent: error")).toThrow(/newline/);
expect(() => serializeRealtimeEvent({ event: REALTIME_EVENT_NAMES.keepalive, cursor: `${item.cursor}\nevent: error`, requestId: "req_1" })).toThrow(
/newline/,
);
});
});
@@ -0,0 +1,43 @@
import { validateRealtimeEvent, type RealtimeEvent } from "./events.js";
export type RealtimeSseSerializeOptions = {
retry?: number;
};
export function serializeRealtimeComment(comment: string): string {
const sanitizedComment = sanitizeSseLine(comment, "comment");
return `: ${sanitizedComment}\n\n`;
}
export function serializeRealtimeEvent(input: unknown, options: RealtimeSseSerializeOptions = {}): string {
const event = validateRealtimeEvent(input);
const retryLine = serializeRetry(options.retry);
const data = JSON.stringify(toSerializableRealtimeEvent(event));
return `${retryLine}id: ${sanitizeSseLine(event.cursor, "cursor")}\nevent: ${event.event}\ndata: ${data}\n\n`;
}
function serializeRetry(retry: number | undefined): string {
if (retry === undefined) {
return "";
}
if (!Number.isInteger(retry) || retry < 0) {
throw new Error("retry must be a non-negative integer");
}
return `retry: ${retry}\n`;
}
function sanitizeSseLine(value: string, label: string): string {
if (value.includes("\n") || value.includes("\r")) {
throw new Error(`${label} must not contain newline characters`);
}
return value;
}
function toSerializableRealtimeEvent(event: RealtimeEvent): RealtimeEvent {
return event;
}