@batterai/strapi-plugin-canvas 0.1.0

package/src/server/services/document-service.ts

@@ -0,0 +1,162 @@
+import type { EditorShellBootstrap } from "@batterai/editor-shell";
+
+type ContentType = EditorShellBootstrap["contentTypes"][number];
+type FieldSchema = ContentType["fields"][number];
+type ValueType = FieldSchema["valueType"];
+
+export type BoundCollectionConfig = Record<string, string>;
+export type CollectionReadMode = "draft" | "published";
+
+const INTERNAL_API_UIDS = new Set([
+  "api::canvas-page.canvas-page",
+  "api::canvas-site.canvas-site",
+  "api::battery-media-asset.battery-media-asset",
+]);
+
+type StrapiContentType = {
+  kind?: string;
+  info?: { displayName?: string; pluralName?: string; singularName?: string };
+  attributes?: Record<string, Record<string, unknown>>;
+};
+
+export function createDocumentService(
+  strapi: any,
+  boundCollections: BoundCollectionConfig = {},
+  discoverCollections = true,
+) {
+  function collectionBindings(): Record<string, string> {
+    if (!discoverCollections) return { ...boundCollections };
+    const bindings: Record<string, string> = {};
+    const explicitlyBoundUids = new Set(Object.values(boundCollections));
+    for (const [uid, schema] of Object.entries((strapi.contentTypes ?? {}) as Record<string, StrapiContentType>)) {
+      if (!uid.startsWith("api::") || INTERNAL_API_UIDS.has(uid) || explicitlyBoundUids.has(uid)) continue;
+      if (schema.kind !== "collectionType") continue;
+      const key = schema.info?.pluralName ?? schema.info?.singularName ?? uid.slice("api::".length).split(".")[0]!;
+      bindings[key] = uid;
+    }
+    return { ...bindings, ...boundCollections };
+  }
+
+  function schemaFor(uid: string): StrapiContentType | undefined {
+    return (strapi.contentTypes ?? {})[uid] as StrapiContentType | undefined;
+  }
+
+  function collectionKeyForUid(uid: string, bindings: Record<string, string>): string | undefined {
+    return Object.entries(bindings).find(([, candidate]) => candidate === uid)?.[0];
+  }
+
+  return {
+    collectionNames(): string[] {
+      return Object.keys(collectionBindings());
+    },
+    listContentTypes(): ContentType[] {
+      const bindings = collectionBindings();
+      return Object.entries(bindings).map(([key, uid]) => {
+        const schema = schemaFor(uid);
+        const fields = Object.entries(schema?.attributes ?? {}).map(([name, attribute]) =>
+          fieldSchema(name, attribute, bindings, collectionKeyForUid),
+        );
+        return {
+          id: key as never,
+          name: schema?.info?.displayName ?? schema?.info?.pluralName ?? key,
+          fields,
+        };
+      });
+    },
+    async listCollection(collection: string, options: { status?: CollectionReadMode } = {}): Promise<unknown[]> {
+      const uid = collectionBindings()[collection];
+      if (!uid) return [];
+      const documents = strapi.documents?.(uid);
+      if (documents?.findMany) {
+        return normalizeItems(await documents.findMany({ status: options.status ?? "draft", limit: 100, populate: "*" }));
+      }
+      return normalizeItems(await strapi.entityService.findMany(uid, { limit: 100, populate: "*" }));
+    },
+    async saveCollection(collection: string, items: unknown[]): Promise<void> {
+      const uid = collectionBindings()[collection];
+      if (!uid) return;
+      const documents = strapi.documents?.(uid);
+      if (!documents?.update) return;
+      const schema = schemaFor(uid);
+      for (const item of items) {
+        if (!item || typeof item !== "object") continue;
+        const documentId = (item as { documentId?: unknown; id?: unknown }).documentId;
+        if (typeof documentId !== "string") continue;
+        await documents.update({
+          documentId,
+          status: "draft",
+          data: strapiDataForItem(item as Record<string, unknown>, schema),
+        });
+      }
+    },
+  };
+}
+
+function normalizeItems(items: unknown): unknown[] {
+  if (!Array.isArray(items)) return [];
+  return items.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+    const record = item as Record<string, unknown>;
+    const identity = record.documentId ?? record.id;
+    return identity === undefined ? record : { ...record, id: String(identity) };
+  });
+}
+
+function strapiDataForItem(item: Record<string, unknown>, schema: StrapiContentType | undefined): Record<string, unknown> {
+  const data: Record<string, unknown> = {};
+  const attributes = schema?.attributes ?? {};
+  for (const [name, attribute] of Object.entries(attributes)) {
+    if (!isWritableAttribute(name, attribute) || !(name in item)) continue;
+    data[name] = strapiValueForAttribute(item[name], attribute);
+  }
+  return data;
+}
+
+function isWritableAttribute(name: string, attribute: Record<string, unknown>): boolean {
+  if (attribute.private === true || attribute.writable === false) return false;
+  if (attribute.unstable_virtual === true) return false;
+  if (["id", "documentId", "createdAt", "updatedAt", "publishedAt", "createdBy", "updatedBy", "localizations"].includes(name)) {
+    return false;
+  }
+  return true;
+}
+
+function strapiValueForAttribute(value: unknown, attribute: Record<string, unknown>): unknown {
+  if (!Array.isArray(value)) return value;
+  const type = typeof attribute.type === "string" ? attribute.type : "json";
+  if (["text", "richtext", "blocks"].includes(type)) return value.filter((entry) => typeof entry === "string").join("\n\n");
+  if (["string", "email", "uid", "enumeration", "password"].includes(type)) return value.filter((entry) => typeof entry === "string").join("\n");
+  return value;
+}
+
+function fieldSchema(
+  name: string,
+  attribute: Record<string, unknown>,
+  bindings: Record<string, string>,
+  collectionKeyForUid: (uid: string, bindings: Record<string, string>) => string | undefined,
+): FieldSchema {
+  const type = typeof attribute.type === "string" ? attribute.type : "json";
+  const relation = typeof attribute.relation === "string" ? attribute.relation : "";
+  const target = typeof attribute.target === "string" ? attribute.target : undefined;
+  const isMany = relation.toLowerCase().includes("many") && !relation.toLowerCase().startsWith("manytoone");
+  const valueType: ValueType = type === "relation" ? "reference"
+    : type === "media" ? "media"
+      : ["integer", "biginteger", "float", "decimal"].includes(type) ? "number"
+        : type === "boolean" ? "boolean"
+          : ["date", "datetime", "time", "timestamp"].includes(type) ? "date"
+            : ["richtext", "blocks"].includes(type) ? "richtext"
+              : ["string", "text", "email", "uid", "enumeration", "password"].includes(type) ? "string"
+                : "json";
+  return {
+    name: name as never,
+    label: name,
+    valueType,
+    cardinality: (isMany || attribute.multiple === true || attribute.repeatable === true) ? "many" : "one",
+    ...(type === "relation" ? { isReference: true } : {}),
+    ...(target && collectionKeyForUid(target, bindings)
+      ? { refType: collectionKeyForUid(target, bindings) as never }
+      : {}),
+    ...(attribute.localized === true ? { localized: true } : {}),
+    ...(attribute.default !== undefined ? { defaultValue: attribute.default } : {}),
+  };
+}

package/src/server/services/index.ts

@@ -0,0 +1,41 @@
+import { createDocumentService } from "./document-service";
+import { createDocumentCommandService } from "./document-command-service";
+import { createPageDocStore, createStrapiPageDocRepository } from "./page-doc-store";
+import { createSiteStore } from "./site-store";
+import { createStrapiCollaborationService } from "./collaboration-service";
+
+export default {
+  collaboration({ strapi }: { strapi: any }) {
+    return createStrapiCollaborationService(strapi);
+  },
+  documentCommand({ strapi }: { strapi: any }) {
+    return createDocumentCommandService(strapi);
+  },
+  pageDocStore({ strapi }: { strapi: any }) {
+    return createPageDocStore(createStrapiPageDocRepository(strapi));
+  },
+  siteStore({ strapi }: { strapi: any }) {
+    const config = strapi.config.get("plugin::canvas") ?? {};
+    return createSiteStore(strapi, config.seedLibrary);
+  },
+  documentService({ strapi }: { strapi: any }) {
+    const config = strapi.config.get("plugin::canvas") ?? {};
+    return createDocumentService(strapi, config.boundCollections ?? {}, config.discoverCollections ?? true);
+  },
+};
+
+export {
+  CanvasPageConflict,
+  CanvasPageValidationError,
+  createPageDocStore,
+  createStrapiPageDocRepository,
+  documentVersion,
+  makeCanvasPageDocument,
+} from "./page-doc-store";
+export {
+  createDocumentCommandService,
+  strapiCanvasConcurrency,
+  type CanvasDocumentCommandTransaction,
+  type CanvasDocumentCommandTransactionRunner,
+} from "./document-command-service";
+export { CanvasSiteConflict, createSiteStore, defaultHomePage, defaultSiteDocument } from "./site-store";

package/src/server/services/page-doc-store.ts

@@ -0,0 +1,348 @@
+import { randomUUID } from "node:crypto";
+import { CANVAS_PAGE_UID } from "../../constants";
+
+export type CanvasPageDocument<Page = unknown> = {
+  kind: "canvas-editor-page";
+  docVersion: number;
+  page: Page;
+  staged?: {
+    page: Page;
+    stagedAt: string;
+    sourceDocVersion: number;
+  };
+  published?: {
+    page: Page;
+    publishedAt: string;
+    sourceDocVersion: number;
+  };
+  updatedAt: string;
+};
+
+export type CanvasPageRow<Page = unknown> = {
+  id?: string | number;
+  documentId?: string;
+  pageKey: string;
+  docVersion: number;
+  latestVersion?: string | null;
+  document: CanvasPageDocument<Page>;
+};
+
+export class CanvasPageConflict extends Error {
+  readonly status = 409;
+
+  constructor(
+    readonly pageKey: string,
+    readonly expectedDocVersion: number,
+    readonly actualDocVersion: number | undefined,
+  ) {
+    super(`Canvas page conflict for ${pageKey}: expected ${expectedDocVersion}, got ${actualDocVersion ?? "missing"}`);
+    this.name = "CanvasPageConflict";
+  }
+}
+
+export class CanvasPageValidationError extends Error {
+  readonly status = 400;
+}
+
+export type PageDocRepository<Page = unknown> = {
+  list: () => Promise<CanvasPageRow<Page>[]>;
+  findByPageKey: (pageKey: string) => Promise<CanvasPageRow<Page> | undefined>;
+  insert: (row: CanvasPageRow<Page>) => Promise<CanvasPageRow<Page>>;
+  updateIfVersion: (
+    pageKey: string,
+    expectedDocVersion: number,
+    patch: Pick<CanvasPageRow<Page>, "docVersion" | "latestVersion" | "document">,
+  ) => Promise<number>;
+  deleteIfVersion: (pageKey: string, expectedDocVersion: number) => Promise<number>;
+};
+
+export function documentVersion(document: unknown): number {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return 0;
+  const version = (document as { docVersion?: unknown }).docVersion;
+  return typeof version === "number" && Number.isInteger(version) && version >= 0 ? version : 0;
+}
+
+export function latestVersion(document: unknown): string | null {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return null;
+  const version = (document as { latestVersion?: unknown }).latestVersion;
+  return typeof version === "string" ? version : null;
+}
+
+export function makeCanvasPageDocument<Page>(
+  page: Page,
+  expectedDocVersion: number,
+  now = new Date(),
+  published?: CanvasPageDocument<Page>["published"],
+  staged?: CanvasPageDocument<Page>["staged"],
+): CanvasPageDocument<Page> {
+  if (!Number.isInteger(expectedDocVersion) || expectedDocVersion < 0) {
+    throw new CanvasPageValidationError("expectedDocVersion must be a non-negative integer.");
+  }
+  return {
+    kind: "canvas-editor-page",
+    docVersion: expectedDocVersion + 1,
+    page,
+    ...(staged ? { staged } : {}),
+    ...(published ? { published } : {}),
+    updatedAt: now.toISOString(),
+  };
+}
+
+export function createPageDocStore<Page = unknown>(
+  repository: PageDocRepository<Page>,
+  options: { now?: () => Date; createDocumentId?: () => string } = {},
+) {
+  const now = options.now ?? (() => new Date());
+  const createDocumentId = options.createDocumentId ?? randomUUID;
+
+  return {
+    async list(): Promise<CanvasPageRow<Page>[]> {
+      return repository.list();
+    },
+    async read(pageKey: string): Promise<CanvasPageRow<Page> | undefined> {
+      return repository.findByPageKey(pageKey);
+    },
+    async save(pageKey: string, page: Page, expectedDocVersion: number): Promise<CanvasPageRow<Page>> {
+      const existing = await repository.findByPageKey(pageKey);
+      const actualDocVersion = existing?.docVersion ?? documentVersion(existing?.document);
+      if (existing && actualDocVersion !== expectedDocVersion) {
+        throw new CanvasPageConflict(pageKey, expectedDocVersion, actualDocVersion);
+      }
+      const document = makeCanvasPageDocument(
+        page,
+        expectedDocVersion,
+        now(),
+        existing?.document.published,
+        existing?.document.staged,
+      );
+      const patch = {
+        docVersion: document.docVersion,
+        latestVersion: latestVersion(page) ?? document.updatedAt,
+        document,
+      };
+      if (!existing) {
+        if (expectedDocVersion !== 0) {
+          throw new CanvasPageConflict(pageKey, expectedDocVersion, undefined);
+        }
+        try {
+          return await repository.insert({
+            pageKey,
+            documentId: createDocumentId(),
+            ...patch,
+          });
+        } catch (error) {
+          if (isUniqueError(error)) throw new CanvasPageConflict(pageKey, expectedDocVersion, undefined);
+          throw error;
+        }
+      }
+      const affected = await repository.updateIfVersion(pageKey, expectedDocVersion, patch);
+      if (affected !== 1) throw new CanvasPageConflict(pageKey, expectedDocVersion, undefined);
+      return {
+        ...existing,
+        ...patch,
+      };
+    },
+    async remove(pageKey: string, expectedDocVersion: number): Promise<void> {
+      const existing = await repository.findByPageKey(pageKey);
+      const actualDocVersion = existing?.docVersion ?? documentVersion(existing?.document);
+      if (!existing || actualDocVersion !== expectedDocVersion) {
+        throw new CanvasPageConflict(pageKey, expectedDocVersion, existing ? actualDocVersion : undefined);
+      }
+      const affected = await repository.deleteIfVersion(pageKey, expectedDocVersion);
+      if (affected !== 1) throw new CanvasPageConflict(pageKey, expectedDocVersion, actualDocVersion);
+    },
+    async publish(
+      pageKey: string,
+      expectedDocVersion: number,
+      publishedAt?: Date,
+    ): Promise<CanvasPageRow<Page>> {
+      const existing = await repository.findByPageKey(pageKey);
+      const actualDocVersion = existing?.docVersion ?? documentVersion(existing?.document);
+      if (!existing || actualDocVersion !== expectedDocVersion) {
+        throw new CanvasPageConflict(pageKey, expectedDocVersion, existing ? actualDocVersion : undefined);
+      }
+      const timestamp = (publishedAt ?? now()).toISOString();
+      const document: CanvasPageDocument<Page> = {
+        ...existing.document,
+        docVersion: expectedDocVersion + 1,
+        updatedAt: timestamp,
+        published: {
+          page: existing.document.page,
+          publishedAt: timestamp,
+          sourceDocVersion: expectedDocVersion,
+        },
+      };
+      const patch = {
+        docVersion: document.docVersion,
+        latestVersion: timestamp,
+        document,
+      };
+      const affected = await repository.updateIfVersion(pageKey, expectedDocVersion, patch);
+      if (affected !== 1) throw new CanvasPageConflict(pageKey, expectedDocVersion, actualDocVersion);
+      return { ...existing, ...patch };
+    },
+    async stage(pageKey: string, expectedDocVersion: number): Promise<CanvasPageRow<Page>> {
+      const existing = await repository.findByPageKey(pageKey);
+      const actualDocVersion = existing?.docVersion ?? documentVersion(existing?.document);
+      if (!existing || actualDocVersion !== expectedDocVersion) {
+        throw new CanvasPageConflict(pageKey, expectedDocVersion, existing ? actualDocVersion : undefined);
+      }
+      const timestamp = now().toISOString();
+      const document: CanvasPageDocument<Page> = {
+        ...existing.document,
+        docVersion: expectedDocVersion + 1,
+        updatedAt: timestamp,
+        staged: {
+          page: structuredClone(existing.document.page),
+          stagedAt: timestamp,
+          sourceDocVersion: expectedDocVersion,
+        },
+      };
+      const patch = { docVersion: document.docVersion, latestVersion: timestamp, document };
+      const affected = await repository.updateIfVersion(pageKey, expectedDocVersion, patch);
+      if (affected !== 1) throw new CanvasPageConflict(pageKey, expectedDocVersion, actualDocVersion);
+      return { ...existing, ...patch };
+    },
+    async unstage(pageKey: string, expectedDocVersion: number): Promise<CanvasPageRow<Page>> {
+      const existing = await repository.findByPageKey(pageKey);
+      const actualDocVersion = existing?.docVersion ?? documentVersion(existing?.document);
+      if (!existing || actualDocVersion !== expectedDocVersion) {
+        throw new CanvasPageConflict(pageKey, expectedDocVersion, existing ? actualDocVersion : undefined);
+      }
+      const timestamp = now().toISOString();
+      const { staged: _staged, ...rest } = existing.document;
+      const document: CanvasPageDocument<Page> = {
+        ...rest,
+        docVersion: expectedDocVersion + 1,
+        updatedAt: timestamp,
+      };
+      const patch = { docVersion: document.docVersion, latestVersion: timestamp, document };
+      const affected = await repository.updateIfVersion(pageKey, expectedDocVersion, patch);
+      if (affected !== 1) throw new CanvasPageConflict(pageKey, expectedDocVersion, actualDocVersion);
+      return { ...existing, ...patch };
+    },
+    async publishStaged(
+      pageKey: string,
+      expectedDocVersion: number,
+      publishedAt?: Date,
+    ): Promise<CanvasPageRow<Page>> {
+      const existing = await repository.findByPageKey(pageKey);
+      const actualDocVersion = existing?.docVersion ?? documentVersion(existing?.document);
+      if (!existing || actualDocVersion !== expectedDocVersion) {
+        throw new CanvasPageConflict(pageKey, expectedDocVersion, existing ? actualDocVersion : undefined);
+      }
+      if (!existing.document.staged) {
+        throw new CanvasPageValidationError(`Canvas page ${pageKey} has no staged revision.`);
+      }
+      const timestamp = (publishedAt ?? now()).toISOString();
+      const { staged, ...rest } = existing.document;
+      const document: CanvasPageDocument<Page> = {
+        ...rest,
+        docVersion: expectedDocVersion + 1,
+        updatedAt: timestamp,
+        published: {
+          page: structuredClone(staged.page),
+          publishedAt: timestamp,
+          sourceDocVersion: staged.sourceDocVersion,
+        },
+      };
+      const patch = { docVersion: document.docVersion, latestVersion: timestamp, document };
+      const affected = await repository.updateIfVersion(pageKey, expectedDocVersion, patch);
+      if (affected !== 1) throw new CanvasPageConflict(pageKey, expectedDocVersion, actualDocVersion);
+      return { ...existing, ...patch };
+    },
+  };
+}
+
+function isUniqueError(error: unknown): boolean {
+  const text = String(error instanceof Error ? error.message : error);
+  return /unique|duplicate|constraint/i.test(text);
+}
+
+export function createStrapiPageDocRepository<Page = unknown>(
+  strapi: any,
+  transaction?: ((tableName: string) => any),
+): PageDocRepository<Page> {
+  const metadata = strapi.db.metadata.get(CANVAS_PAGE_UID);
+  const tableName = metadata.tableName;
+  const columns = {
+    documentId: columnName(metadata, "documentId", "document_id"),
+    pageKey: columnName(metadata, "pageKey", "page_key"),
+    docVersion: columnName(metadata, "docVersion", "doc_version"),
+    latestVersion: columnName(metadata, "latestVersion", "latest_version"),
+    document: columnName(metadata, "document", "document"),
+    createdAt: columnName(metadata, "createdAt", "created_at"),
+    updatedAt: columnName(metadata, "updatedAt", "updated_at"),
+  };
+
+  function table() {
+    return transaction ? transaction(tableName) : strapi.db.connection(tableName);
+  }
+
+  function toRow(row: Record<string, unknown> | undefined): CanvasPageRow<Page> | undefined {
+    if (!row) return undefined;
+    return {
+      id: row.id as string | number | undefined,
+      documentId: row[columns.documentId] as string | undefined,
+      pageKey: String(row[columns.pageKey]),
+      docVersion: Number(row[columns.docVersion] ?? 0),
+      latestVersion: row[columns.latestVersion] as string | null | undefined,
+      document: parseJson(row[columns.document]) as CanvasPageDocument<Page>,
+    };
+  }
+
+  return {
+    async list() {
+      const rows = await table().select("*");
+      return rows.map((row: Record<string, unknown>) => toRow(row)!);
+    },
+    async findByPageKey(pageKey) {
+      const row = await table().where({ [columns.pageKey]: pageKey }).first();
+      return toRow(row);
+    },
+    async insert(row) {
+      const timestamp = new Date().toISOString();
+      await table().insert({
+        [columns.documentId]: row.documentId ?? randomUUID(),
+        [columns.pageKey]: row.pageKey,
+        [columns.docVersion]: row.docVersion,
+        [columns.latestVersion]: row.latestVersion ?? null,
+        [columns.document]: JSON.stringify(row.document),
+        [columns.createdAt]: timestamp,
+        [columns.updatedAt]: timestamp,
+      });
+      return (await this.findByPageKey(row.pageKey)) ?? row;
+    },
+    async updateIfVersion(pageKey, expectedDocVersion, patch) {
+      const timestamp = new Date().toISOString();
+      const result = await table()
+        .where({ [columns.pageKey]: pageKey, [columns.docVersion]: expectedDocVersion })
+        .update({
+          [columns.docVersion]: patch.docVersion,
+          [columns.latestVersion]: patch.latestVersion ?? null,
+          [columns.document]: JSON.stringify(patch.document),
+          [columns.updatedAt]: timestamp,
+        });
+      return Number(result);
+    },
+    async deleteIfVersion(pageKey, expectedDocVersion) {
+      const result = await table()
+        .where({ [columns.pageKey]: pageKey, [columns.docVersion]: expectedDocVersion })
+        .delete();
+      return Number(result);
+    },
+  };
+}
+
+function columnName(metadata: any, attribute: string, fallback: string): string {
+  return metadata?.attributes?.[attribute]?.columnName ?? fallback;
+}
+
+function parseJson(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}