@mp-lb/mdkit 0.3.2 → 0.3.3

package/src/transport/fastify.ts

@@ -0,0 +1,57 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { createMdKitHttpHandlers } from "./http";
+import type { MdKitTransportStore } from "./store";
+
+export type RegisterMdKitFastifyOptions = {
+  prefix?: string;
+  store: MdKitTransportStore;
+};
+
+const send = async (
+  reply: FastifyReply,
+  response: Promise<{ body: unknown; status: number }>,
+) => {
+  const { body, status } = await response;
+  return reply.status(status).send(body);
+};
+
+const toRequest = (request: FastifyRequest) => ({
+  body: request.body,
+  params: request.params as Record<string, unknown>,
+  query: request.query as Record<string, unknown>,
+});
+
+/**
+ * Registers the mdkit REST endpoints on a Fastify app under `prefix`, backed by
+ * a transport store (typically from `createMdKitBackend`).
+ */
+export const registerMdKitFastify = async (
+  app: FastifyInstance,
+  { prefix = "", store }: RegisterMdKitFastifyOptions,
+) => {
+  const handlers = createMdKitHttpHandlers(store);
+
+  app.get(`${prefix}/documents`, (request, reply) =>
+    send(reply, handlers.readDocument(toRequest(request))),
+  );
+
+  app.put(`${prefix}/documents`, (request, reply) =>
+    send(reply, handlers.writeDocument(toRequest(request))),
+  );
+
+  app.post(`${prefix}/documents/resync`, (request, reply) =>
+    send(reply, handlers.resyncDocument(toRequest(request))),
+  );
+
+  app.get(`${prefix}/versions`, (request, reply) =>
+    send(reply, handlers.listDocumentVersions(toRequest(request))),
+  );
+
+  app.get(`${prefix}/versions/:versionId`, (request, reply) =>
+    send(reply, handlers.readDocumentVersion(toRequest(request))),
+  );
+
+  app.post(`${prefix}/versions/:versionId/restore`, (request, reply) =>
+    send(reply, handlers.restoreDocumentVersion(toRequest(request))),
+  );
+};

package/src/transport/http.ts

@@ -0,0 +1,126 @@
+import type {
+  MdKitDocumentVersionToken,
+  MdKitDocumentWriteInput,
+} from "../document/documentTypes";
+import type {
+  MdKitRestoreDocumentVersionInput,
+  MdKitTransportStore,
+} from "./store";
+
+export type MdKitHttpRequest = {
+  body?: unknown;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+};
+
+export type MdKitHttpResponse<T = unknown> = {
+  body: T;
+  status: number;
+};
+
+export type MdKitHttpHandlers = ReturnType<typeof createMdKitHttpHandlers>;
+
+const readString = (
+  source: Record<string, unknown> | undefined,
+  key: string,
+): string => {
+  const value = source?.[key];
+
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Missing mdkit ${key}`);
+  }
+
+  return value;
+};
+
+const readVersionToken = (value: unknown): MdKitDocumentVersionToken => {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number"
+  ) {
+    return value;
+  }
+
+  throw new Error("Invalid mdkit baseVersion");
+};
+
+const readWriteInput = (request: MdKitHttpRequest): MdKitDocumentWriteInput => {
+  const body = request.body as Record<string, unknown> | null | undefined;
+
+  if (!body || typeof body !== "object") {
+    throw new Error("Missing mdkit write body");
+  }
+
+  const content = body.content;
+
+  if (typeof content !== "string") {
+    throw new Error("Invalid mdkit content");
+  }
+
+  return {
+    baseVersion: readVersionToken(body.baseVersion),
+    content,
+    documentId: readString(request.query, "documentId"),
+    force: body.force === true,
+  };
+};
+
+const notFound = (message: string): MdKitHttpResponse<{ error: string }> => ({
+  body: { error: message },
+  status: 404,
+});
+
+export const createMdKitHttpHandlers = (store: MdKitTransportStore) => ({
+  readDocument: async (request: MdKitHttpRequest) => ({
+    body: await store.readDocument(readString(request.query, "documentId")),
+    status: 200,
+  }),
+  writeDocument: async (request: MdKitHttpRequest) => {
+    const body = await store.writeDocument(readWriteInput(request));
+
+    return {
+      body,
+      status: "conflict" in body ? 409 : 200,
+    };
+  },
+  resyncDocument: async (request: MdKitHttpRequest) => ({
+    body: await (store.resyncDocument ?? store.readDocument)(
+      readString(request.query, "documentId"),
+    ),
+    status: 200,
+  }),
+  listDocumentVersions: async (request: MdKitHttpRequest) => ({
+    body: {
+      versions: await (store.listDocumentVersions?.(
+        readString(request.query, "documentId"),
+      ) ?? []),
+    },
+    status: 200,
+  }),
+  readDocumentVersion: async (request: MdKitHttpRequest) => {
+    const version = await store.readDocumentVersion?.({
+      documentId: readString(request.query, "documentId"),
+      versionId: readString(request.params, "versionId"),
+    });
+
+    return version
+      ? ({ body: version, status: 200 } as const)
+      : notFound("Version not found");
+  },
+  restoreDocumentVersion: async (request: MdKitHttpRequest) => {
+    if (!store.restoreDocumentVersion) {
+      return notFound("Version restore is not supported");
+    }
+
+    const input: MdKitRestoreDocumentVersionInput = {
+      documentId: readString(request.query, "documentId"),
+      versionId: readString(request.params, "versionId"),
+    };
+
+    return {
+      body: await store.restoreDocumentVersion(input),
+      status: 200,
+    };
+  },
+});

package/src/transport/index.ts

@@ -0,0 +1,12 @@
+export { createMdKitHttpHandlers } from "./http";
+export { createMdKitRestAdapter } from "./rest";
+export type {
+  MdKitHttpHandlers,
+  MdKitHttpRequest,
+  MdKitHttpResponse,
+} from "./http";
+export type { CreateMdKitRestAdapterOptions } from "./rest";
+export type {
+  MdKitRestoreDocumentVersionInput,
+  MdKitTransportStore,
+} from "./store";

package/src/transport/rest.ts

@@ -0,0 +1,80 @@
+import type {
+  MdKitDocumentAdapter,
+  MdKitDocumentVersionSummary,
+} from "../document/documentTypes";
+
+export type CreateMdKitRestAdapterOptions = {
+  baseUrl: string;
+  fetch?: typeof fetch;
+};
+
+const trimTrailingSlash = (value: string) => value.replace(/\/+$/, "");
+
+const documentQuery = (documentId: string) =>
+  `documentId=${encodeURIComponent(documentId)}`;
+
+const readJson = async <T>(response: Response): Promise<T> => {
+  const body = (await response.json()) as T;
+
+  if (!response.ok && response.status !== 409) {
+    throw new Error(`MdKit REST request failed: ${response.status}`);
+  }
+
+  return body;
+};
+
+/**
+ * Builds an {@link MdKitDocumentAdapter} that talks to the mdkit REST endpoint
+ * shape. Restore is not part of the adapter contract, so REST restore needs a
+ * separate call from application code.
+ */
+export const createMdKitRestAdapter = ({
+  baseUrl,
+  fetch: fetchImpl = fetch,
+}: CreateMdKitRestAdapterOptions): MdKitDocumentAdapter => {
+  const url = trimTrailingSlash(baseUrl);
+
+  return {
+    readDocument: async (documentId) =>
+      readJson(
+        await fetchImpl(`${url}/documents?${documentQuery(documentId)}`),
+      ),
+    writeDocument: async (input) =>
+      readJson(
+        await fetchImpl(`${url}/documents?${documentQuery(input.documentId)}`, {
+          body: JSON.stringify(input),
+          headers: { "Content-Type": "application/json" },
+          method: "PUT",
+        }),
+      ),
+    resyncDocument: async (documentId) =>
+      readJson(
+        await fetchImpl(
+          `${url}/documents/resync?${documentQuery(documentId)}`,
+          {
+            method: "POST",
+          },
+        ),
+      ),
+    listDocumentVersions: async (documentId) => {
+      const body = await readJson<{ versions: MdKitDocumentVersionSummary[] }>(
+        await fetchImpl(`${url}/versions?${documentQuery(documentId)}`),
+      );
+
+      return body.versions;
+    },
+    readDocumentVersion: async ({ documentId, versionId }) => {
+      const response = await fetchImpl(
+        `${url}/versions/${encodeURIComponent(versionId)}?${documentQuery(
+          documentId,
+        )}`,
+      );
+
+      if (response.status === 404) {
+        return null;
+      }
+
+      return readJson(response);
+    },
+  };
+};

package/src/transport/store.ts

@@ -0,0 +1,45 @@
+import type {
+  MdKitDocumentSnapshot,
+  MdKitDocumentVersionDetail,
+  MdKitDocumentVersionSummary,
+  MdKitDocumentWriteInput,
+  MdKitDocumentWriteResult,
+} from "../document/documentTypes";
+
+export type MdKitTransportStore = {
+  readDocument(
+    documentId: string,
+  ): Promise<MdKitDocumentSnapshot> | MdKitDocumentSnapshot;
+  writeDocument(
+    input: MdKitDocumentWriteInput,
+  ): Promise<MdKitDocumentWriteResult> | MdKitDocumentWriteResult;
+  resyncDocument?(
+    documentId: string,
+  ): Promise<MdKitDocumentSnapshot> | MdKitDocumentSnapshot;
+  listDocumentVersions?(
+    documentId: string,
+  ): Promise<MdKitDocumentVersionSummary[]> | MdKitDocumentVersionSummary[];
+  readDocumentVersion?(input: {
+    documentId: string;
+    versionId: string;
+  }):
+    | Promise<MdKitDocumentVersionDetail | null>
+    | MdKitDocumentVersionDetail
+    | null;
+  restoreDocumentVersion?(input: {
+    documentId: string;
+    versionId: string;
+  }): Promise<MdKitDocumentWriteResult> | MdKitDocumentWriteResult;
+  readCollaborationState?(
+    documentName: string,
+  ): Promise<Uint8Array | null> | Uint8Array | null;
+  writeCollaborationState?(
+    documentName: string,
+    state: Uint8Array,
+  ): Promise<void> | void;
+};
+
+export type MdKitRestoreDocumentVersionInput = {
+  documentId: string;
+  versionId: string;
+};

package/src/transport/trpcClient.ts

@@ -0,0 +1,90 @@
+import { createTRPCProxyClient, httpBatchLink } from "@trpc/client";
+import type {
+  MdKitDocumentAdapter,
+  MdKitDocumentSnapshot,
+  MdKitDocumentVersionDetail,
+  MdKitDocumentVersionSummary,
+  MdKitDocumentWriteInput,
+  MdKitDocumentWriteResult,
+} from "../document/documentTypes";
+import type { MdKitTrpcRouter } from "./trpcServer";
+
+export type CreateMdKitTrpcClientAdapterOptions = {
+  url: string;
+};
+
+type MdKitTrpcQuery<Input, Output> = {
+  query(input: Input): Promise<Output>;
+};
+
+type MdKitTrpcMutation<Input, Output> = {
+  mutate(input: Input): Promise<Output>;
+};
+
+type MdKitDocumentInput = {
+  documentId: string;
+};
+
+type MdKitVersionInput = {
+  documentId: string;
+  versionId: string;
+};
+
+export type MdKitTrpcClient = {
+  listDocumentVersions: MdKitTrpcQuery<
+    MdKitDocumentInput,
+    { versions: MdKitDocumentVersionSummary[] }
+  >;
+  readDocument: MdKitTrpcQuery<MdKitDocumentInput, MdKitDocumentSnapshot>;
+  readDocumentVersion: MdKitTrpcQuery<
+    MdKitVersionInput,
+    MdKitDocumentVersionDetail | null
+  >;
+  resyncDocument: MdKitTrpcMutation<MdKitDocumentInput, MdKitDocumentSnapshot>;
+  writeDocument: MdKitTrpcMutation<
+    MdKitDocumentWriteInput,
+    MdKitDocumentWriteResult
+  >;
+};
+
+export type CreateMdKitTrpcAdapterOptions = {
+  client: MdKitTrpcClient;
+};
+
+/**
+ * Turns an mdkit tRPC client (standalone or a nested sub-client of your app
+ * router) into an {@link MdKitDocumentAdapter} for the document hooks.
+ */
+export const createMdKitTrpcAdapter = ({
+  client,
+}: CreateMdKitTrpcAdapterOptions): MdKitDocumentAdapter => ({
+  listDocumentVersions: async (documentId) => {
+    const body = await client.listDocumentVersions.query({ documentId });
+    return body.versions;
+  },
+  readDocument: (documentId) => client.readDocument.query({ documentId }),
+  readDocumentVersion: (input) => client.readDocumentVersion.query(input),
+  resyncDocument: (documentId) => client.resyncDocument.mutate({ documentId }),
+  writeDocument: (input) => client.writeDocument.mutate(input),
+});
+
+/**
+ * Creates a typed tRPC proxy client for the mdkit router at `url`.
+ */
+export const createMdKitTrpcClient = ({
+  url,
+}: CreateMdKitTrpcClientAdapterOptions) =>
+  createTRPCProxyClient<MdKitTrpcRouter>({
+    links: [
+      httpBatchLink({
+        url,
+      }),
+    ],
+  });
+
+export const createMdKitTrpcClientAdapter = ({
+  url,
+}: CreateMdKitTrpcClientAdapterOptions) =>
+  createMdKitTrpcAdapter({
+    client: createMdKitTrpcClient({ url }),
+  });

package/src/transport/trpcServer.ts

@@ -0,0 +1,66 @@
+import { initTRPC } from "@trpc/server";
+import { z } from "zod";
+import type { MdKitTransportStore } from "./store";
+
+const t = initTRPC.create();
+
+const documentInput = z.object({
+  documentId: z.string(),
+});
+
+const versionInput = z.object({
+  documentId: z.string(),
+  versionId: z.string(),
+});
+
+const versionToken = z.union([z.string(), z.number()]).nullable();
+
+const writeInput = z.object({
+  baseVersion: versionToken,
+  content: z.string(),
+  documentId: z.string(),
+  force: z.boolean().optional(),
+});
+
+/**
+ * Builds a tRPC router exposing document read/write/resync, checkpoint
+ * list/read, and restore over a transport store (typically from
+ * `createMdKitBackend`). Mount it standalone or nested in an app router.
+ */
+export const createMdKitTrpcRouter = (store: MdKitTransportStore) =>
+  t.router({
+    listDocumentVersions: t.procedure
+      .input(documentInput)
+      .query(async ({ input }) => ({
+        versions: await (store.listDocumentVersions?.(input.documentId) ?? []),
+      })),
+    readDocument: t.procedure
+      .input(documentInput)
+      .query(({ input }) => store.readDocument(input.documentId)),
+    readDocumentVersion: t.procedure.input(versionInput).query(
+      ({ input }) =>
+        store.readDocumentVersion?.({
+          documentId: input.documentId,
+          versionId: input.versionId,
+        }) ?? null,
+    ),
+    resyncDocument: t.procedure
+      .input(documentInput)
+      .mutation(({ input }) =>
+        (store.resyncDocument ?? store.readDocument)(input.documentId),
+      ),
+    restoreDocumentVersion: t.procedure
+      .input(versionInput)
+      .mutation(({ input }) => {
+        if (!store.restoreDocumentVersion) {
+          throw new Error("Version restore is not supported");
+        }
+
+        return store.restoreDocumentVersion(input);
+      }),
+    writeDocument: t.procedure
+      .input(writeInput)
+      .mutation(({ input }) => store.writeDocument(input)),
+  });
+
+export type MdKitTrpcRouter = ReturnType<typeof createMdKitTrpcRouter>;

package/src/trpc/client.ts

@@ -0,0 +1,11 @@
+export {
+  createMdKitTrpcAdapter,
+  createMdKitTrpcClient,
+  createMdKitTrpcClientAdapter,
+} from "../transport/trpcClient";
+export type {
+  CreateMdKitTrpcAdapterOptions,
+  CreateMdKitTrpcClientAdapterOptions,
+  MdKitTrpcClient,
+} from "../transport/trpcClient";
+export type { MdKitTrpcRouter } from "../transport/trpcServer";

package/src/trpc/server.ts

@@ -0,0 +1,12 @@
+export { createMdKitBackend } from "../transport/backend";
+export { createMdKitTrpcRouter } from "../transport/trpcServer";
+export type {
+  CreateMdKitBackendOptions,
+  MdKitBackendStore,
+  MdKitCreateCheckpointInput,
+} from "../transport/backend";
+export type { MdKitTrpcRouter } from "../transport/trpcServer";
+export type {
+  MdKitRestoreDocumentVersionInput,
+  MdKitTransportStore,
+} from "../transport/store";

package/src/trpc.ts

@@ -0,0 +1,11 @@
+export {
+  createMdKitTrpcAdapter,
+  createMdKitTrpcClient,
+  createMdKitTrpcClientAdapter,
+} from "./transport/trpcClient";
+export type {
+  CreateMdKitTrpcAdapterOptions,
+  CreateMdKitTrpcClientAdapterOptions,
+  MdKitTrpcClient,
+} from "./transport/trpcClient";
+export type { MdKitTrpcRouter } from "./transport/trpcServer";

package/src/ui/joinClassNames.ts

@@ -0,0 +1,3 @@
+export const joinClassNames = (
+  ...values: Array<string | false | null | undefined>
+) => values.filter(Boolean).join(" ");

package/src/versioning/VersionHistoryPanel.tsx

@@ -0,0 +1,146 @@
+import { useState } from "react";
+import type { MdKitDocumentVersionDetail } from "../document/documentTypes";
+import type { MdKitDocumentVersionsController } from "./useMdKitDocumentVersions";
+import { joinClassNames } from "../ui/joinClassNames";
+
+export type VersionHistoryPanelProps = {
+  className?: string;
+  controller: MdKitDocumentVersionsController;
+  onRestoreVersion?: (
+    version: MdKitDocumentVersionDetail,
+  ) => Promise<void> | void;
+  title?: string;
+};
+
+const getVersionLabel = (
+  version: Pick<MdKitDocumentVersionDetail, "id" | "label" | "version">,
+) => {
+  if (version.label) {
+    return version.label;
+  }
+
+  if (version.version != null) {
+    return `Version ${String(version.version)}`;
+  }
+
+  return version.id.slice(0, 8);
+};
+
+/**
+ * Renders checkpoint history from {@link useMdKitDocumentVersions} and invokes
+ * the host's restore handler for a chosen checkpoint.
+ */
+export const VersionHistoryPanel = ({
+  className,
+  controller,
+  onRestoreVersion,
+  title = "Version history",
+}: VersionHistoryPanelProps) => {
+  const [isRestoring, setIsRestoring] = useState(false);
+
+  const restoreSelectedVersion = async () => {
+    if (!controller.selectedVersion || !onRestoreVersion) {
+      return;
+    }
+
+    setIsRestoring(true);
+
+    try {
+      await onRestoreVersion(controller.selectedVersion);
+    } finally {
+      setIsRestoring(false);
+    }
+  };
+
+  return (
+    <aside className={joinClassNames("mp-lb-mdkit-version-history-panel", className)}>
+      <div className="mp-lb-mdkit-version-history-header">
+        <div>
+          <h2 className="mp-lb-mdkit-version-history-title">{title}</h2>
+          <p className="mp-lb-mdkit-version-history-subtitle">
+            Browse saved revisions and restore one when you need it.
+          </p>
+        </div>
+      </div>
+      {!controller.hasVersioning ? (
+        <div className="mp-lb-mdkit-version-history-empty">
+          This adapter does not expose version history.
+        </div>
+      ) : null}
+      {controller.error ? (
+        <div className="mp-lb-mdkit-version-history-error">{controller.error}</div>
+      ) : null}
+      {controller.hasVersioning ? (
+        <div className="mp-lb-mdkit-version-history-layout">
+          <div className="mp-lb-mdkit-version-history-list" role="list">
+            {controller.versions.length === 0 ? (
+              <div className="mp-lb-mdkit-version-history-empty">
+                No revisions have been recorded for this document yet.
+              </div>
+            ) : (
+              controller.versions.map((version) => (
+                <button
+                  key={version.id}
+                  type="button"
+                  className={joinClassNames(
+                    "mp-lb-mdkit-version-history-item",
+                    controller.selectedVersionId === version.id &&
+                      "mp-lb-mdkit-version-history-item-active",
+                  )}
+                  onClick={() => void controller.openVersion(version.id)}
+                >
+                  <span className="mp-lb-mdkit-version-history-item-title">
+                    {getVersionLabel(version)}
+                  </span>
+                  <span className="mp-lb-mdkit-version-history-item-meta">
+                    {new Date(version.createdAt).toLocaleString()}
+                  </span>
+                </button>
+              ))
+            )}
+          </div>
+          <div className="mp-lb-mdkit-version-history-preview">
+            {controller.selectedVersion ? (
+              <>
+                <div className="mp-lb-mdkit-version-history-preview-header">
+                  <div>
+                    <h3 className="mp-lb-mdkit-version-history-preview-title">
+                      {getVersionLabel(controller.selectedVersion)}
+                    </h3>
+                    <p className="mp-lb-mdkit-version-history-item-meta">
+                      {new Date(
+                        controller.selectedVersion.createdAt,
+                      ).toLocaleString()}
+                    </p>
+                  </div>
+                  {onRestoreVersion ? (
+                    <button
+                      type="button"
+                      className="mp-lb-mdkit-panel-primary-action"
+                      disabled={isRestoring}
+                      onClick={() => void restoreSelectedVersion()}
+                    >
+                      {isRestoring ? "Restoring..." : "Restore"}
+                    </button>
+                  ) : null}
+                </div>
+                <pre className="mp-lb-mdkit-version-history-code">
+                  {controller.selectedVersion.content}
+                </pre>
+              </>
+            ) : (
+              <div className="mp-lb-mdkit-version-history-empty">
+                Select a saved revision to preview it here.
+              </div>
+            )}
+          </div>
+        </div>
+      ) : null}
+      {controller.isLoading ? (
+        <div className="mp-lb-mdkit-version-history-meta">
+          Loading version data...
+        </div>
+      ) : null}
+    </aside>
+  );
+};