@actuate-media/cms-core 0.20.0 → 0.22.0

package/dist/realtime/index.js

@@ -0,0 +1,18 @@
+/**
+ * Realtime collaboration surface for `@actuate-media/cms-core`.
+ *
+ * - `createRealtimeGateway` — transport-agnostic gateway that owns rooms,
+ *   debounces persistence, and reaps idle documents. Consumers wrap their
+ *   server's socket primitive in a `WebSocketLike` adapter and feed it via
+ *   `gateway.handleConnection(socket, req)`.
+ * - `createPrismaDocumentPersistence` — Prisma-backed implementation of
+ *   `DocumentPersistence` against the `DocumentCRDT` table.
+ *
+ * See `packages/realtime/README.md` for the protocol details and
+ * `docs/roadmap-status.md` for the Phase 3 slice plan.
+ */
+export { createRealtimeGateway, } from './gateway.js';
+export { createPrismaDocumentPersistence, } from './persistence.js';
+export { createComment, deleteComment, listComments, normaliseBody, parseAnchor, reopenComment, resolveComment, toCommentDTO, updateComment, DEFAULT_COMMENT_LIST_PAGE_SIZE, MAX_COMMENT_BODY_LENGTH, MAX_COMMENT_LIST_PAGE_SIZE, } from './comments.js';
+export { createNotification, excerptForNotification, extractMentionedUserIds, isNotificationKind, listForUser as listNotificationsForUser, markAllRead as markAllNotificationsRead, markRead as markNotificationRead, toNotificationDTO, unreadCount as notificationsUnreadCount, DEFAULT_NOTIFICATION_LIST_PAGE_SIZE, MAX_NOTIFICATION_LIST_PAGE_SIZE, } from './notifications.js';
+//# 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;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,qBAAqB,GAMtB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,+BAA+B,GAGhC,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,aAAa,EACb,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,8BAA8B,EAC9B,uBAAuB,EACvB,0BAA0B,GAU3B,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,IAAI,wBAAwB,EACvC,WAAW,IAAI,wBAAwB,EACvC,QAAQ,IAAI,oBAAoB,EAChC,iBAAiB,EACjB,WAAW,IAAI,wBAAwB,EACvC,mCAAmC,EACnC,+BAA+B,GAUhC,MAAM,oBAAoB,CAAA"}

package/dist/realtime/notifications.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Per-user notifications driven by collaboration events.
+ *
+ * Owns the pure notification logic: kind discriminator, payload validation,
+ * permission gates, and a storage-agnostic CRUD surface. The HTTP layer
+ * (in `api/handlers.ts`) is a thin wrapper that handles auth + JSON
+ * envelope; the comments hook layer (slice 6, `notification-triggers.ts`)
+ * calls these helpers when a comment lifecycle event fires.
+ *
+ * Storage shape — see `packages/cms-core/prisma/cms-schema.prisma`, model
+ * `DocumentNotification`. We require only a minimal Prisma surface so the
+ * helpers can be tested against an in-memory fake.
+ *
+ * ## Discriminated payloads
+ *
+ * The `payload` Json column varies by `kind`. The TypeScript types here
+ * are the source of truth for each variant; the service helpers narrow
+ * by `kind` so callers can't accidentally insert a malformed payload.
+ *
+ * ## Mentions
+ *
+ * Slice 6 ships a deliberately simple mention parser: `@<userId>` tokens
+ * in a comment body trigger a `comment_mention` notification. A richer
+ * `@username` parser that resolves against the user table is a Phase 4
+ * follow-up — the storage shape already supports it.
+ */
+/** Hard cap on returned notifications per `listForUser` call. */
+export declare const MAX_NOTIFICATION_LIST_PAGE_SIZE = 200;
+/** Default page size when the caller does not request one. */
+export declare const DEFAULT_NOTIFICATION_LIST_PAGE_SIZE = 50;
+/**
+ * Notification kind discriminator. New variants extend the `Payload`
+ * union — never replace existing kinds, because old rows live forever
+ * in the table.
+ */
+export type NotificationKind = 'comment_reply' | 'comment_resolved' | 'comment_mention';
+export interface CommentReplyPayload {
+    /** User who replied. */
+    actorId: string | null;
+    actorName: string | null;
+    /** First 120 chars of the reply body, for the bell preview. */
+    excerpt: string;
+}
+export interface CommentResolvedPayload {
+    actorId: string | null;
+    actorName: string | null;
+    /** Excerpt of the resolved root comment, so the bell can show context. */
+    rootExcerpt: string;
+}
+export interface CommentMentionPayload {
+    actorId: string | null;
+    actorName: string | null;
+    /** Excerpt of the body that mentioned the recipient. */
+    excerpt: string;
+}
+export type NotificationPayload = ({
+    kind: 'comment_reply';
+} & CommentReplyPayload) | ({
+    kind: 'comment_resolved';
+} & CommentResolvedPayload) | ({
+    kind: 'comment_mention';
+} & CommentMentionPayload);
+/** Public REST shape. Mirrors the row plus the discriminated payload. */
+export interface NotificationDTO {
+    id: string;
+    userId: string;
+    kind: NotificationKind;
+    documentId: string | null;
+    commentId: string | null;
+    payload: NotificationPayload;
+    readAt: string | null;
+    createdAt: string;
+}
+export interface CreateNotificationInput {
+    userId: string;
+    documentId?: string | null;
+    commentId?: string | null;
+    payload: NotificationPayload;
+}
+export interface ListNotificationsFilter {
+    userId: string;
+    /** Default: false. When true, returns read + unread notifications. */
+    includeRead?: boolean;
+    /** Default: DEFAULT_NOTIFICATION_LIST_PAGE_SIZE. Hard upper bound applied. */
+    pageSize?: number;
+}
+export type NotificationsError = {
+    code: 'validation';
+    message: string;
+} | {
+    code: 'forbidden';
+    message: string;
+} | {
+    code: 'not_found';
+    message: string;
+};
+export type NotificationsResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: NotificationsError;
+};
+/**
+ * Minimal subset of Prisma's notification delegate we depend on. Keeping
+ * this narrow lets the unit tests use a fake implementation that holds
+ * rows in an array — no schema generation required.
+ */
+export interface DocumentNotificationRow {
+    id: string;
+    userId: string;
+    kind: string;
+    documentId: string | null;
+    commentId: string | null;
+    payload: unknown;
+    readAt: Date | null;
+    createdAt: Date;
+}
+export interface NotificationsDB {
+    documentNotification: {
+        create(args: {
+            data: Omit<DocumentNotificationRow, 'id' | 'createdAt' | 'readAt'> & {
+                readAt?: Date | null;
+            };
+        }): Promise<DocumentNotificationRow>;
+        findUnique(args: {
+            where: {
+                id: string;
+            };
+        }): Promise<DocumentNotificationRow | null>;
+        findMany(args: {
+            where: {
+                userId: string;
+                readAt?: null | {
+                    not: null;
+                };
+            };
+            orderBy?: {
+                createdAt: 'desc' | 'asc';
+            };
+            take?: number;
+        }): Promise<DocumentNotificationRow[]>;
+        update(args: {
+            where: {
+                id: string;
+            };
+            data: {
+                readAt?: Date | null;
+            };
+        }): Promise<DocumentNotificationRow>;
+        updateMany(args: {
+            where: {
+                userId: string;
+                readAt?: null;
+            };
+            data: {
+                readAt: Date;
+            };
+        }): Promise<{
+            count: number;
+        }>;
+        count(args: {
+            where: {
+                userId: string;
+                readAt: null;
+            };
+        }): Promise<number>;
+    };
+}
+export declare function toNotificationDTO(row: DocumentNotificationRow): NotificationDTO;
+export declare function isNotificationKind(value: unknown): value is NotificationKind;
+/**
+ * Insert a new notification. The payload's `kind` field is the source
+ * of truth; `kind` on the DB row is derived from it so callers can't
+ * drift them apart.
+ */
+export declare function createNotification(db: NotificationsDB, input: CreateNotificationInput): Promise<NotificationsResult<NotificationDTO>>;
+/**
+ * List notifications for a user, newest first. By default returns only
+ * unread; pass `includeRead: true` for the full feed (the bell dropdown
+ * uses both depending on the tab the user is on).
+ */
+export declare function listForUser(db: NotificationsDB, filter: ListNotificationsFilter): Promise<NotificationsResult<NotificationDTO[]>>;
+/** Count unread notifications for the bell badge. */
+export declare function unreadCount(db: NotificationsDB, userId: string): Promise<NotificationsResult<number>>;
+/** Mark a single notification read (idempotent). */
+export declare function markRead(db: NotificationsDB, id: string, actor: {
+    userId: string;
+}): Promise<NotificationsResult<NotificationDTO>>;
+/** Mark every unread notification for the user as read. */
+export declare function markAllRead(db: NotificationsDB, userId: string): Promise<NotificationsResult<{
+    count: number;
+}>>;
+/**
+ * Cheap excerpt builder for notification payloads. Markdown is kept as-is;
+ * we just trim whitespace and clip to 120 chars so the bell can render
+ * a single-line preview.
+ */
+export declare function excerptForNotification(body: string, max?: number): string;
+/**
+ * Extract `@<userId>` mentions from a comment body. We intentionally
+ * match the *user id* form here (`@user_abc123`) — a slice-7 follow-up
+ * can wire up `@username` resolution against the User table.
+ *
+ * Returns a deduplicated array of mentioned user ids; the caller filters
+ * out the actor before issuing notifications.
+ */
+export declare function extractMentionedUserIds(body: string): string[];
+//# sourceMappingURL=notifications.d.ts.map

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

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

package/dist/realtime/notifications.js

@@ -0,0 +1,209 @@
+/**
+ * Per-user notifications driven by collaboration events.
+ *
+ * Owns the pure notification logic: kind discriminator, payload validation,
+ * permission gates, and a storage-agnostic CRUD surface. The HTTP layer
+ * (in `api/handlers.ts`) is a thin wrapper that handles auth + JSON
+ * envelope; the comments hook layer (slice 6, `notification-triggers.ts`)
+ * calls these helpers when a comment lifecycle event fires.
+ *
+ * Storage shape — see `packages/cms-core/prisma/cms-schema.prisma`, model
+ * `DocumentNotification`. We require only a minimal Prisma surface so the
+ * helpers can be tested against an in-memory fake.
+ *
+ * ## Discriminated payloads
+ *
+ * The `payload` Json column varies by `kind`. The TypeScript types here
+ * are the source of truth for each variant; the service helpers narrow
+ * by `kind` so callers can't accidentally insert a malformed payload.
+ *
+ * ## Mentions
+ *
+ * Slice 6 ships a deliberately simple mention parser: `@<userId>` tokens
+ * in a comment body trigger a `comment_mention` notification. A richer
+ * `@username` parser that resolves against the user table is a Phase 4
+ * follow-up — the storage shape already supports it.
+ */
+/** Hard cap on returned notifications per `listForUser` call. */
+export const MAX_NOTIFICATION_LIST_PAGE_SIZE = 200;
+/** Default page size when the caller does not request one. */
+export const DEFAULT_NOTIFICATION_LIST_PAGE_SIZE = 50;
+export function toNotificationDTO(row) {
+    // The payload comes back as `unknown` from Prisma's Json column; we
+    // re-tag it with the `kind` discriminator so the DTO is strictly typed
+    // on the way out. Storage-level validation in `createNotification`
+    // guarantees the payload matches the kind.
+    const payload = {
+        kind: row.kind,
+        ...(row.payload ?? {}),
+    };
+    return {
+        id: row.id,
+        userId: row.userId,
+        kind: row.kind,
+        documentId: row.documentId,
+        commentId: row.commentId,
+        payload,
+        readAt: row.readAt ? row.readAt.toISOString() : null,
+        createdAt: row.createdAt.toISOString(),
+    };
+}
+const KIND_GUARDS = {
+    comment_reply: true,
+    comment_resolved: true,
+    comment_mention: true,
+};
+export function isNotificationKind(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(KIND_GUARDS, value);
+}
+function validatePayload(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return { code: 'validation', message: 'payload must be an object' };
+    }
+    if (!isNotificationKind(payload.kind)) {
+        return { code: 'validation', message: `unknown kind "${String(payload.kind)}"` };
+    }
+    if (payload.kind === 'comment_reply' || payload.kind === 'comment_mention') {
+        if (typeof payload.excerpt !== 'string') {
+            return { code: 'validation', message: 'excerpt is required' };
+        }
+    }
+    if (payload.kind === 'comment_resolved') {
+        if (typeof payload.rootExcerpt !== 'string') {
+            return { code: 'validation', message: 'rootExcerpt is required' };
+        }
+    }
+    return null;
+}
+/**
+ * Insert a new notification. The payload's `kind` field is the source
+ * of truth; `kind` on the DB row is derived from it so callers can't
+ * drift them apart.
+ */
+export async function createNotification(db, input) {
+    if (!input.userId || typeof input.userId !== 'string') {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const validationError = validatePayload(input.payload);
+    if (validationError)
+        return { ok: false, error: validationError };
+    // Strip the kind tag from the stored JSON — it's already in the
+    // dedicated column.
+    const { kind, ...rest } = input.payload;
+    const row = await db.documentNotification.create({
+        data: {
+            userId: input.userId,
+            kind,
+            documentId: input.documentId ?? null,
+            commentId: input.commentId ?? null,
+            payload: rest,
+            readAt: null,
+        },
+    });
+    return { ok: true, value: toNotificationDTO(row) };
+}
+/** Resolve a notification by id, only if it belongs to `userId`. */
+async function loadOwned(db, id, userId) {
+    const row = await db.documentNotification.findUnique({ where: { id } });
+    if (!row)
+        return { ok: false, error: { code: 'not_found', message: 'Notification not found' } };
+    if (row.userId !== userId) {
+        return { ok: false, error: { code: 'forbidden', message: 'Not your notification' } };
+    }
+    return { ok: true, value: row };
+}
+/**
+ * List notifications for a user, newest first. By default returns only
+ * unread; pass `includeRead: true` for the full feed (the bell dropdown
+ * uses both depending on the tab the user is on).
+ */
+export async function listForUser(db, filter) {
+    if (!filter.userId) {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const take = clampPageSize(filter.pageSize);
+    const where = { userId: filter.userId };
+    if (!filter.includeRead)
+        where.readAt = null;
+    const rows = await db.documentNotification.findMany({
+        where,
+        orderBy: { createdAt: 'desc' },
+        take,
+    });
+    return { ok: true, value: rows.map(toNotificationDTO) };
+}
+/** Count unread notifications for the bell badge. */
+export async function unreadCount(db, userId) {
+    if (!userId) {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const count = await db.documentNotification.count({
+        where: { userId, readAt: null },
+    });
+    return { ok: true, value: count };
+}
+/** Mark a single notification read (idempotent). */
+export async function markRead(db, id, actor) {
+    if (!id) {
+        return { ok: false, error: { code: 'validation', message: 'id is required' } };
+    }
+    const loaded = await loadOwned(db, id, actor.userId);
+    if (!loaded.ok)
+        return loaded;
+    if (loaded.value.readAt) {
+        return { ok: true, value: toNotificationDTO(loaded.value) };
+    }
+    const updated = await db.documentNotification.update({
+        where: { id },
+        data: { readAt: new Date() },
+    });
+    return { ok: true, value: toNotificationDTO(updated) };
+}
+/** Mark every unread notification for the user as read. */
+export async function markAllRead(db, userId) {
+    if (!userId) {
+        return { ok: false, error: { code: 'validation', message: 'userId is required' } };
+    }
+    const out = await db.documentNotification.updateMany({
+        where: { userId, readAt: null },
+        data: { readAt: new Date() },
+    });
+    return { ok: true, value: { count: out.count } };
+}
+function clampPageSize(requested) {
+    if (typeof requested !== 'number' || !Number.isFinite(requested) || requested <= 0) {
+        return DEFAULT_NOTIFICATION_LIST_PAGE_SIZE;
+    }
+    return Math.min(Math.max(1, Math.floor(requested)), MAX_NOTIFICATION_LIST_PAGE_SIZE);
+}
+/**
+ * Cheap excerpt builder for notification payloads. Markdown is kept as-is;
+ * we just trim whitespace and clip to 120 chars so the bell can render
+ * a single-line preview.
+ */
+export function excerptForNotification(body, max = 120) {
+    const cleaned = body.replace(/\s+/g, ' ').trim();
+    if (cleaned.length <= max)
+        return cleaned;
+    return `${cleaned.slice(0, max - 1)}…`;
+}
+/**
+ * Extract `@<userId>` mentions from a comment body. We intentionally
+ * match the *user id* form here (`@user_abc123`) — a slice-7 follow-up
+ * can wire up `@username` resolution against the User table.
+ *
+ * Returns a deduplicated array of mentioned user ids; the caller filters
+ * out the actor before issuing notifications.
+ */
+export function extractMentionedUserIds(body) {
+    if (typeof body !== 'string' || body.length === 0)
+        return [];
+    const seen = new Set();
+    const re = /@([a-zA-Z0-9_-]{3,64})\b/g;
+    let match;
+    while ((match = re.exec(body)) !== null) {
+        seen.add(match[1]);
+    }
+    return Array.from(seen);
+}
+//# sourceMappingURL=notifications.js.map

package/dist/realtime/notifications.js.map

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

package/dist/realtime/persistence.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Prisma-backed `DocumentPersistence` for `@actuate-media/realtime`.
+ *
+ * Reads and writes the `DocumentCRDT` table (see
+ * `prisma/cms-schema.prisma`). The adapter is intentionally narrow — it only
+ * implements the two methods declared by the realtime package, so it can be
+ * swapped for an S3 / Redis / Postgres-LO adapter without touching the
+ * gateway code.
+ *
+ * The `save` path also keeps the `stateVector` column in sync so future
+ * versions of the gateway can answer `SyncStep1` without ever booting a
+ * `Y.Doc` (a future optimisation for hot-path late joins).
+ */
+import type { DocumentPersistence } from '@actuate-media/realtime';
+/** Minimal subset of the Prisma client the persistence adapter needs. */
+export interface PrismaDocumentCRDTClient {
+    documentCRDT: {
+        findUnique(args: {
+            where: {
+                documentId: string;
+            };
+            select?: {
+                state?: boolean;
+                stateVector?: boolean;
+                version?: boolean;
+            };
+        }): Promise<{
+            state: Uint8Array;
+            stateVector?: Uint8Array;
+            version?: number;
+        } | null>;
+        upsert(args: {
+            where: {
+                documentId: string;
+            };
+            create: {
+                documentId: string;
+                state: Uint8Array;
+                stateVector: Uint8Array;
+                version: number;
+                lastUpdatedById?: string | null;
+            };
+            update: {
+                state: Uint8Array;
+                stateVector: Uint8Array;
+                version: {
+                    increment: number;
+                };
+                lastUpdatedById?: string | null;
+            };
+        }): Promise<{
+            documentId: string;
+            version: number;
+        }>;
+    };
+}
+export interface PrismaDocumentPersistenceOptions {
+    /**
+     * Optional default editor id used for `lastUpdatedById` when the gateway
+     * does not supply one. In production the gateway derives this from the
+     * authenticated session per save.
+     */
+    lastUpdatedById?: string | null;
+}
+/**
+ * Create a `DocumentPersistence` backed by a `DocumentCRDT` Prisma table.
+ *
+ * The returned object satisfies the realtime package's contract so it can
+ * be passed straight to `bindPersistence(room, persistence)`.
+ */
+export declare function createPrismaDocumentPersistence(db: PrismaDocumentCRDTClient, options?: PrismaDocumentPersistenceOptions): DocumentPersistence;
+//# sourceMappingURL=persistence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/realtime/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAGlE,yEAAyE;AACzE,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE;QACZ,UAAU,CAAC,IAAI,EAAE;YACf,KAAK,EAAE;gBAAE,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;YAC7B,MAAM,CAAC,EAAE;gBAAE,KAAK,CAAC,EAAE,OAAO,CAAC;gBAAC,WAAW,CAAC,EAAE,OAAO,CAAC;gBAAC,OAAO,CAAC,EAAE,OAAO,CAAA;aAAE,CAAA;SACvE,GAAG,OAAO,CAAC;YAAE,KAAK,EAAE,UAAU,CAAC;YAAC,WAAW,CAAC,EAAE,UAAU,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC,CAAA;QACrF,MAAM,CAAC,IAAI,EAAE;YACX,KAAK,EAAE;gBAAE,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;YAC7B,MAAM,EAAE;gBACN,UAAU,EAAE,MAAM,CAAA;gBAClB,KAAK,EAAE,UAAU,CAAA;gBACjB,WAAW,EAAE,UAAU,CAAA;gBACvB,OAAO,EAAE,MAAM,CAAA;gBACf,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;aAChC,CAAA;YACD,MAAM,EAAE;gBACN,KAAK,EAAE,UAAU,CAAA;gBACjB,WAAW,EAAE,UAAU,CAAA;gBACvB,OAAO,EAAE;oBAAE,SAAS,EAAE,MAAM,CAAA;iBAAE,CAAA;gBAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;aAChC,CAAA;SACF,GAAG,OAAO,CAAC;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACrD,CAAA;CACF;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,wBAAwB,EAC5B,OAAO,GAAE,gCAAqC,GAC7C,mBAAmB,CAwCrB"}

package/dist/realtime/persistence.js

@@ -0,0 +1,53 @@
+import * as Y from 'yjs';
+/**
+ * Create a `DocumentPersistence` backed by a `DocumentCRDT` Prisma table.
+ *
+ * The returned object satisfies the realtime package's contract so it can
+ * be passed straight to `bindPersistence(room, persistence)`.
+ */
+export function createPrismaDocumentPersistence(db, options = {}) {
+    return {
+        async load(documentId) {
+            const row = await db.documentCRDT.findUnique({
+                where: { documentId },
+                select: { state: true },
+            });
+            if (!row)
+                return null;
+            // Defensive copy: callers may mutate the buffer once we return it
+            // (Prisma typically gives back a fresh Uint8Array, but we don't want
+            // to rely on internal guarantees here).
+            return copyBytes(row.state);
+        },
+        async save(documentId, state) {
+            // Compute the new state vector from the encoded state. Cheap — Yjs
+            // decodes the update structure but skips construction of clients.
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, state);
+            const stateVector = Y.encodeStateVector(doc);
+            doc.destroy();
+            await db.documentCRDT.upsert({
+                where: { documentId },
+                create: {
+                    documentId,
+                    state: copyBytes(state),
+                    stateVector,
+                    version: 1,
+                    lastUpdatedById: options.lastUpdatedById ?? null,
+                },
+                update: {
+                    state: copyBytes(state),
+                    stateVector,
+                    version: { increment: 1 },
+                    lastUpdatedById: options.lastUpdatedById ?? null,
+                },
+            });
+        },
+    };
+}
+function copyBytes(src) {
+    const dst = new Uint8Array(src.length);
+    dst.set(src);
+    return dst;
+}
+//# sourceMappingURL=persistence.js.map

package/dist/realtime/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/realtime/persistence.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAqCxB;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAC7C,EAA4B,EAC5B,UAA4C,EAAE;IAE9C,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,UAAU;YACnB,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC;gBAC3C,KAAK,EAAE,EAAE,UAAU,EAAE;gBACrB,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;aACxB,CAAC,CAAA;YACF,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAA;YACrB,kEAAkE;YAClE,qEAAqE;YACrE,wCAAwC;YACxC,OAAO,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC7B,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK;YAC1B,mEAAmE;YACnE,kEAAkE;YAClE,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,CAAA;YACvB,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACzB,MAAM,WAAW,GAAG,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAA;YAC5C,GAAG,CAAC,OAAO,EAAE,CAAA;YAEb,MAAM,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC;gBAC3B,KAAK,EAAE,EAAE,UAAU,EAAE;gBACrB,MAAM,EAAE;oBACN,UAAU;oBACV,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC;oBACvB,WAAW;oBACX,OAAO,EAAE,CAAC;oBACV,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,IAAI;iBACjD;gBACD,MAAM,EAAE;oBACN,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC;oBACvB,WAAW;oBACX,OAAO,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE;oBACzB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,IAAI;iBACjD;aACF,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,SAAS,CAAC,GAAe;IAChC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACtC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACZ,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cms-core",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/actuate-media/actuatecms.git",
@@ -59,6 +59,11 @@
       "import": "./dist/page-builder/index.js",
       "default": "./dist/page-builder/index.js"
     },
+    "./realtime": {
+      "types": "./dist/realtime/index.d.ts",
+      "import": "./dist/realtime/index.js",
+      "default": "./dist/realtime/index.js"
+    },
     "./generated/client": {
       "types": "./generated/client.d.ts",
       "import": "./generated/client.js",
@@ -74,18 +79,22 @@
     "graphql-yoga": "^5.19.0",
     "jose": "^6.0.0",
     "pg": "^8.20.0",
-    "sanitize-html": "^2.17.3",
+    "sanitize-html": "^2.17.4",
     "sharp": "^0.34.5",
-    "zod": "^3.23.0"
+    "yjs": "^13.6.0",
+    "zod": "^3.23.0",
+    "@actuate-media/realtime": "0.1.0"
   },
   "devDependencies": {
     "@types/sanitize-html": "^2.16.1",
     "@types/sharp": "^0.32.0",
+    "@types/ws": "^8.5.10",
     "dotenv": "^17.3.1",
     "prisma": "^7.8.0",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "ws": "^8.18.0"
   },
   "files": [
     "dist",