@gridframe/server 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# @gridframe/server
+
+Framework-neutral server helpers for API-managed Gridframe Dashboards.
+
+```ts
+import { createDashboardHandlers } from "@gridframe/server";
+
+const handlers = createDashboardHandlers({
+  repository,
+  cardLibrary,
+  defaultDashboard: ({ userId }) => dashboardSeedFor(userId),
+  resolveCardData: async ({ card }) => loadCardData(card),
+});
+```
+
+The handlers use the standard Fetch `Request`/`Response` APIs, so framework adapters only need to extract route params and pass the request through.
+
+## Next.js route handler
+
+```ts
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ userId: string }> },
+) {
+  const { userId } = await context.params;
+  return handlers.bootstrap(request, { userId });
+}
+```
+
+## Express route
+
+```ts
+app.post("/api/gridframe/users/:userId/dashboards/bootstrap", async (req, res) => {
+  const request = new Request(req.protocol + "://" + req.get("host") + req.originalUrl, {
+    method: req.method,
+    headers: req.headers as HeadersInit,
+    body: JSON.stringify(req.body),
+  });
+  const response = await handlers.bootstrap(request, { userId: req.params.userId });
+  res.status(response.status).set(Object.fromEntries(response.headers)).send(await response.text());
+});
+```
+
+## TanStack Start or Vite-style server
+
+```ts
+export async function handle({ request, params }) {
+  return handlers.bootstrap(request, { userId: params.userId });
+}
+```
+
+Host applications own authorization. The `userId` passed to handlers is an application identity key and must not be trusted without the host app checking access.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@gridframe/server",
+  "version": "1.0.0",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^4.1.10",
+    "@gridframe/eslint-config": "0.0.0",
+    "@gridframe/typescript-config": "0.0.0"
+  },
+  "dependencies": {
+    "@gridframe/core": "^1.0.0"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run src",
+    "check-types": "tsc --noEmit"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,480 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type {
+  DashboardCardLayout,
+  PanelCardDataResponse,
+} from "@gridframe/core";
+
+import {
+  DashboardInvalidLibraryItemError,
+  DashboardNotFoundError,
+  DashboardRevisionConflictError,
+  createDashboardHandlers,
+  type CardLibraryTemplate,
+  type DashboardBootstrap,
+  type DashboardRepository,
+  type DashboardSeed,
+  type PersistedDashboard,
+  type PersistedDashboardCard,
+} from ".";
+
+const templates = [
+  {
+    key: "revenue",
+    name: "Revenue",
+    description: "Revenue metric",
+    visualization: "metric",
+    defaultLayout: { width: 1, height: 2 },
+    deeplinkLabel: "View revenue",
+  },
+  {
+    key: "orders",
+    name: "Orders",
+    visualization: "bar",
+    defaultLayout: { width: 3, height: 4 },
+  },
+] satisfies CardLibraryTemplate[];
+
+const defaultDashboard = {
+  title: "Operations overview",
+  description: "Seeded dashboard",
+  footer: { text: "Example footer" },
+  cards: [
+    { libraryItemKey: "revenue", layout: { x: 0, y: 0, width: 1, height: 2 } },
+  ],
+} satisfies DashboardSeed;
+
+describe("createDashboardHandlers", () => {
+  let repository: MemoryDashboardRepository;
+  let resolverResult: PanelCardDataResponse;
+
+  beforeEach(() => {
+    repository = new MemoryDashboardRepository();
+    resolverResult = {
+      status: "success",
+      data: {
+        visualization: "metric",
+        value: 42,
+        label: "Revenue",
+      },
+    };
+  });
+
+  function handlers() {
+    return createDashboardHandlers({
+      repository,
+      cardLibrary: templates,
+      defaultDashboard: () => defaultDashboard,
+      resolveCardData: () => Promise.resolve(resolverResult),
+    });
+  }
+
+  it("bootstraps a default Dashboard when the user has none", async () => {
+    const response = await handlers().bootstrap(
+      jsonRequest({}),
+      { userId: "user-1" },
+    );
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      dashboards: [{ title: "Operations overview", isDefault: true }],
+      dashboard: {
+        revision: "1",
+        config: {
+          title: "Operations overview",
+          cards: [
+            {
+              name: "Revenue",
+              visualization: "metric",
+              query:
+                "/api/gridframe/users/user-1/dashboards/dashboard-1/cards/card-1/data",
+              deeplink: {
+                href:
+                  "/gridframe/users/user-1/dashboards/dashboard-1/cards/card-1",
+                label: "View revenue",
+              },
+            },
+          ],
+        },
+      },
+    });
+  });
+
+  it("returns not found when an explicit Dashboard is missing", async () => {
+    await handlers().bootstrap(jsonRequest({}), { userId: "user-1" });
+
+    const response = await handlers().bootstrap(
+      jsonRequest({ dashboardId: "missing" }),
+      { userId: "user-1" },
+    );
+
+    expect(response.status).toBe(404);
+    await expect(response.json()).resolves.toEqual({
+      error: { code: "DASHBOARD_NOT_FOUND", message: "Dashboard not found" },
+    });
+  });
+
+  it("persists a complete valid layout", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().updateLayout(
+      jsonRequest({
+        revision: String(dashboard.revision),
+        cards: [{ id: "card-1", x: 1, y: 0, width: 1, height: 2 }],
+      }),
+      { userId: "user-1", dashboardId: dashboard.id },
+    );
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      revision: "2",
+      config: { cards: [{ id: "card-1", layout: { x: 1 } }] },
+    });
+  });
+
+  it("rejects layouts that do not contain exactly the Dashboard Cards", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().updateLayout(
+      jsonRequest({ revision: String(dashboard.revision), cards: [] }),
+      { userId: "user-1", dashboardId: dashboard.id },
+    );
+
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      error: {
+        code: "INVALID_REQUEST",
+        message: "Invalid Dashboard layout",
+      },
+    });
+  });
+
+  it("returns a revision conflict when a mutation uses a stale revision", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().updateCard(
+      jsonRequest({ revision: "99", name: "Updated" }),
+      { userId: "user-1", dashboardId: dashboard.id, cardId: "card-1" },
+    );
+
+    expect(response.status).toBe(409);
+    await expect(response.json()).resolves.toEqual({
+      error: {
+        code: "REVISION_CONFLICT",
+        message: "Dashboard was changed by another request",
+      },
+    });
+  });
+
+  it("lists Card library templates with installed state", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().listCardLibrary(new Request("http://x"), {
+      userId: "user-1",
+      dashboardId: dashboard.id,
+    });
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual({
+      items: [
+        {
+          key: "revenue",
+          name: "Revenue",
+          description: "Revenue metric",
+          visualization: "metric",
+          defaultLayout: { width: 1, height: 2 },
+          addedCardId: "card-1",
+        },
+        {
+          key: "orders",
+          name: "Orders",
+          visualization: "bar",
+          defaultLayout: { width: 3, height: 4 },
+        },
+      ],
+    });
+  });
+
+  it("adds a Card library item at the first available layout", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().addCard(
+      jsonRequest({
+        revision: String(dashboard.revision),
+        libraryItemKey: "orders",
+      }),
+      { userId: "user-1", dashboardId: dashboard.id },
+    );
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      dashboard: {
+        revision: "2",
+        config: {
+          cards: [
+            { id: "card-1" },
+            { id: "card-2", layout: { x: 1, y: 0, width: 3, height: 4 } },
+          ],
+        },
+      },
+      cardLibrary: {
+        items: [
+          { key: "revenue", addedCardId: "card-1" },
+          { key: "orders", addedCardId: "card-2" },
+        ],
+      },
+    });
+  });
+
+  it("rejects duplicate Card library items", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().addCard(
+      jsonRequest({
+        revision: String(dashboard.revision),
+        libraryItemKey: "revenue",
+      }),
+      { userId: "user-1", dashboardId: dashboard.id },
+    );
+
+    expect(response.status).toBe(409);
+    await expect(response.json()).resolves.toEqual({
+      error: {
+        code: "CARD_ALREADY_ADDED",
+        message: "Card is already on this Dashboard",
+      },
+    });
+  });
+
+  it("removes the final Card and returns an empty Dashboard", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().removeCard(
+      jsonRequest({ revision: String(dashboard.revision) }),
+      { userId: "user-1", dashboardId: dashboard.id, cardId: "card-1" },
+    );
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      dashboard: { revision: "2", config: { cards: [] } },
+      cardLibrary: {
+        items: [{ key: "revenue" }, { key: "orders" }],
+      },
+    });
+  });
+
+  it("returns validated Card data from the consumer resolver", async () => {
+    const dashboard = await seedDashboard();
+
+    const response = await handlers().fetchCardData(
+      new Request("http://example.test/data"),
+      { userId: "user-1", dashboardId: dashboard.id, cardId: "card-1" },
+    );
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual(resolverResult);
+  });
+
+  it("rejects invalid Card data resolver output", async () => {
+    const dashboard = await seedDashboard();
+    resolverResult = { status: "success", data: undefined } as never;
+
+    const response = await handlers().fetchCardData(
+      new Request("http://example.test/data"),
+      { userId: "user-1", dashboardId: dashboard.id, cardId: "card-1" },
+    );
+
+    expect(response.status).toBe(502);
+    await expect(response.json()).resolves.toEqual({
+      error: {
+        code: "CARD_QUERY_FAILED",
+        message: "Card data could not be loaded",
+      },
+    });
+  });
+
+  async function seedDashboard() {
+    const response = await handlers().bootstrap(
+      jsonRequest({}),
+      { userId: "user-1" },
+    );
+    expect(response.status).toBe(200);
+    return repository.loadDashboard("user-1", "dashboard-1");
+  }
+});
+
+function jsonRequest(body: unknown) {
+  return new Request("http://example.test", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+class MemoryDashboardRepository implements DashboardRepository {
+  private readonly dashboards = new Map<string, PersistedDashboard>();
+  private cardSequence = 1;
+  private dashboardSequence = 1;
+
+  async bootstrap(
+    ownerUserId: string,
+    dashboardId: string | undefined,
+    seed: DashboardSeed,
+    cardLibrary: readonly CardLibraryTemplate[],
+  ): Promise<DashboardBootstrap> {
+    const owned = this.listOwnedDashboards(ownerUserId);
+    let dashboard = dashboardId
+      ? this.dashboards.get(dashboardId)
+      : owned.find((item) => item.isDefault);
+
+    if (!dashboard && !dashboardId) {
+      dashboard = this.createSeededDashboard(ownerUserId, seed, cardLibrary);
+    }
+
+    if (!dashboard || dashboard.ownerUserId !== ownerUserId) {
+      throw new DashboardNotFoundError();
+    }
+
+    return {
+      dashboards: this.listOwnedDashboards(ownerUserId).map((item) => ({
+        id: item.id,
+        title: item.title,
+        isDefault: item.isDefault,
+      })),
+      dashboard,
+    };
+  }
+
+  async loadDashboard(ownerUserId: string, dashboardId: string) {
+    const dashboard = this.dashboards.get(dashboardId);
+    if (!dashboard || dashboard.ownerUserId !== ownerUserId) {
+      throw new DashboardNotFoundError();
+    }
+    return dashboard;
+  }
+
+  async updateLayout(
+    ownerUserId: string,
+    dashboardId: string,
+    revision: number,
+    cards: Array<{ id: string } & DashboardCardLayout>,
+  ) {
+    const dashboard = await this.loadDashboard(ownerUserId, dashboardId);
+    this.assertRevision(dashboard, revision);
+    dashboard.revision += 1;
+    dashboard.cards = dashboard.cards.map((card) => ({
+      ...card,
+      layout: cards.find((item) => item.id === card.id) ?? card.layout,
+    }));
+    return dashboard;
+  }
+
+  async updateCardName(
+    ownerUserId: string,
+    dashboardId: string,
+    cardId: string,
+    revision: number,
+    name: string,
+  ) {
+    const dashboard = await this.loadDashboard(ownerUserId, dashboardId);
+    this.assertRevision(dashboard, revision);
+    const card = dashboard.cards.find((item) => item.id === cardId);
+    if (!card) throw new DashboardNotFoundError();
+    card.name = name;
+    dashboard.revision += 1;
+    return dashboard;
+  }
+
+  async addCard(
+    ownerUserId: string,
+    dashboardId: string,
+    revision: number,
+    card: Omit<PersistedDashboardCard, "id" | "dashboardId" | "sortOrder">,
+  ) {
+    const dashboard = await this.loadDashboard(ownerUserId, dashboardId);
+    this.assertRevision(dashboard, revision);
+    const created = {
+      ...card,
+      id: `card-${this.cardSequence++}`,
+      dashboardId,
+      sortOrder: dashboard.cards.length,
+    };
+    dashboard.cards.push(created);
+    dashboard.revision += 1;
+    return dashboard;
+  }
+
+  async removeCard(
+    ownerUserId: string,
+    dashboardId: string,
+    cardId: string,
+    revision: number,
+  ) {
+    const dashboard = await this.loadDashboard(ownerUserId, dashboardId);
+    this.assertRevision(dashboard, revision);
+    if (!dashboard.cards.some((card) => card.id === cardId)) {
+      throw new DashboardNotFoundError();
+    }
+    dashboard.cards = dashboard.cards.filter((card) => card.id !== cardId);
+    dashboard.revision += 1;
+    return dashboard;
+  }
+
+  async findOwnedCard(
+    ownerUserId: string,
+    dashboardId: string,
+    cardId: string,
+  ) {
+    return (await this.loadDashboard(ownerUserId, dashboardId)).cards.find(
+      (card) => card.id === cardId,
+    );
+  }
+
+  private createSeededDashboard(
+    ownerUserId: string,
+    seed: DashboardSeed,
+    cardLibrary: readonly CardLibraryTemplate[],
+  ) {
+    const dashboardId = `dashboard-${this.dashboardSequence++}`;
+    const dashboard: PersistedDashboard = {
+      id: dashboardId,
+      ownerUserId,
+      title: seed.title,
+      description: seed.description,
+      footer: seed.footer,
+      isDefault: true,
+      revision: 1,
+      cards: seed.cards.map((seedCard, index) => {
+        const template = cardLibrary.find(
+          (item) => item.key === seedCard.libraryItemKey,
+        );
+        if (!template) throw new DashboardInvalidLibraryItemError();
+        return {
+          id: `card-${this.cardSequence++}`,
+          dashboardId,
+          libraryItemKey: template.key,
+          name: template.name,
+          visualization: template.visualization,
+          deeplink: template.deeplinkLabel
+            ? { label: template.deeplinkLabel }
+            : undefined,
+          layout: seedCard.layout ?? { x: 0, y: index * 4, ...template.defaultLayout },
+          sortOrder: index,
+        };
+      }),
+    };
+    this.dashboards.set(dashboard.id, dashboard);
+    return dashboard;
+  }
+
+  private listOwnedDashboards(ownerUserId: string) {
+    return [...this.dashboards.values()].filter(
+      (dashboard) => dashboard.ownerUserId === ownerUserId,
+    );
+  }
+
+  private assertRevision(dashboard: PersistedDashboard, revision: number) {
+    if (dashboard.revision !== revision) {
+      throw new DashboardRevisionConflictError();
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,710 @@
+import {
+  AddDashboardCardRequestSchema,
+  CardLibraryResponseSchema,
+  DashboardApiErrorSchema,
+  DashboardBootstrapRequestSchema,
+  DashboardDocumentSchema,
+  DASHBOARD_GRID_COLUMNS,
+  PanelCardDataResponseSchema,
+  RemoveDashboardCardRequestSchema,
+  UpdateDashboardCardRequestSchema,
+  UpdateDashboardLayoutRequestSchema,
+  type CardDeeplinkConfig,
+  type CardLibraryItem,
+  type DashboardApiError,
+  type DashboardBootstrapResponse,
+  type DashboardCardLayout,
+  type DashboardFooterConfig,
+  type DashboardLayoutItem,
+  type DashboardSummary,
+  type PanelCardDataResponse,
+  type VisualizationType,
+} from "@gridframe/core";
+import { validateDashboardLayout } from "@gridframe/core";
+
+type MaybePromise<T> = T | Promise<T>;
+
+type CardLibraryTemplate = {
+  key: string;
+  name: string;
+  description?: string;
+  visualization: VisualizationType;
+  defaultLayout: {
+    width: number;
+    height: number;
+  };
+  deeplinkLabel?: string;
+};
+
+type DashboardSeedCard = {
+  libraryItemKey: string;
+  layout?: DashboardCardLayout;
+};
+
+type DashboardSeed = {
+  title: string;
+  description?: string;
+  footer?: DashboardFooterConfig;
+  cards: DashboardSeedCard[];
+};
+
+type PersistedDashboardCard = {
+  id: string;
+  dashboardId: string;
+  libraryItemKey?: string;
+  name: string;
+  visualization: VisualizationType;
+  deeplink?: Omit<CardDeeplinkConfig, "href">;
+  layout: DashboardCardLayout;
+  sortOrder: number;
+};
+
+type PersistedDashboard = {
+  id: string;
+  ownerUserId: string;
+  title: string;
+  description?: string;
+  footer?: DashboardFooterConfig;
+  isDefault: boolean;
+  revision: number;
+  cards: PersistedDashboardCard[];
+};
+
+type DashboardBootstrap = {
+  dashboards: DashboardSummary[];
+  dashboard: PersistedDashboard;
+};
+
+type DashboardCardCreate = Omit<
+  PersistedDashboardCard,
+  "id" | "dashboardId" | "sortOrder"
+>;
+
+interface DashboardRepository {
+  bootstrap(
+    ownerUserId: string,
+    dashboardId: string | undefined,
+    seed: DashboardSeed,
+    cardLibrary: readonly CardLibraryTemplate[],
+  ): MaybePromise<DashboardBootstrap>;
+  loadDashboard(
+    ownerUserId: string,
+    dashboardId: string,
+  ): MaybePromise<PersistedDashboard>;
+  updateLayout(
+    ownerUserId: string,
+    dashboardId: string,
+    revision: number,
+    cards: DashboardLayoutItem[],
+  ): MaybePromise<PersistedDashboard>;
+  updateCardName(
+    ownerUserId: string,
+    dashboardId: string,
+    cardId: string,
+    revision: number,
+    name: string,
+  ): MaybePromise<PersistedDashboard>;
+  addCard(
+    ownerUserId: string,
+    dashboardId: string,
+    revision: number,
+    card: DashboardCardCreate,
+  ): MaybePromise<PersistedDashboard>;
+  removeCard(
+    ownerUserId: string,
+    dashboardId: string,
+    cardId: string,
+    revision: number,
+  ): MaybePromise<PersistedDashboard>;
+  findOwnedCard(
+    ownerUserId: string,
+    dashboardId: string,
+    cardId: string,
+  ): MaybePromise<PersistedDashboardCard | undefined>;
+}
+
+type DashboardHandlerOptions = {
+  repository: DashboardRepository;
+  cardLibrary:
+    | readonly CardLibraryTemplate[]
+    | ((context: DashboardContext) => MaybePromise<readonly CardLibraryTemplate[]>);
+  defaultDashboard: (context: DashboardContext) => MaybePromise<DashboardSeed>;
+  resolveCardData: (
+    input: CardDataResolverInput,
+  ) => MaybePromise<PanelCardDataResponse>;
+  urls?: DashboardUrlOptions;
+};
+
+type DashboardUrlOptions = {
+  apiBasePath?: string;
+  dashboardBasePath?: string;
+};
+
+type DashboardContext = {
+  userId: string;
+};
+
+type DashboardIdentity = DashboardContext & {
+  dashboardId: string;
+};
+
+type CardIdentity = DashboardIdentity & {
+  cardId: string;
+};
+
+type CardDataResolverInput = CardIdentity & {
+  card: PersistedDashboardCard;
+  request: Request;
+};
+
+class DashboardNotFoundError extends Error {
+  constructor() {
+    super("Dashboard not found");
+    this.name = "DashboardNotFoundError";
+  }
+}
+
+class DashboardRevisionConflictError extends Error {
+  constructor() {
+    super("Dashboard revision conflict");
+    this.name = "DashboardRevisionConflictError";
+  }
+}
+
+class DashboardInvalidLayoutError extends Error {
+  constructor(readonly errors: string[]) {
+    super(errors.join("; "));
+    this.name = "DashboardInvalidLayoutError";
+  }
+}
+
+class DashboardCardAlreadyAddedError extends Error {
+  constructor() {
+    super("Card is already on this Dashboard");
+    this.name = "DashboardCardAlreadyAddedError";
+  }
+}
+
+class DashboardInvalidLibraryItemError extends Error {
+  constructor() {
+    super("Unknown Card library item");
+    this.name = "DashboardInvalidLibraryItemError";
+  }
+}
+
+function createDashboardHandlers(options: DashboardHandlerOptions) {
+  const urls = {
+    apiBasePath: options.urls?.apiBasePath ?? "/api/gridframe",
+    dashboardBasePath: options.urls?.dashboardBasePath ?? "/gridframe",
+  };
+
+  return {
+    bootstrap: async (request: Request, context: DashboardContext) => {
+      const parsedRequest = DashboardBootstrapRequestSchema.safeParse(
+        await readJson(request),
+      );
+
+      if (!parsedRequest.success || !isIdentitySegment(context.userId)) {
+        return errorResponse(
+          400,
+          "INVALID_REQUEST",
+          "Invalid bootstrap request",
+        );
+      }
+
+      try {
+        const [seed, cardLibrary] = await Promise.all([
+          options.defaultDashboard(context),
+          resolveCardLibrary(options.cardLibrary, context),
+        ]);
+        const result = await options.repository.bootstrap(
+          context.userId,
+          parsedRequest.data.dashboardId,
+          seed,
+          cardLibrary,
+        );
+
+        return Response.json(serializeDashboardBootstrap(result, urls));
+      } catch (error) {
+        if (error instanceof DashboardNotFoundError) {
+          return errorResponse(
+            404,
+            "DASHBOARD_NOT_FOUND",
+            "Dashboard not found",
+          );
+        }
+        if (error instanceof DashboardInvalidLibraryItemError) {
+          return errorResponse(
+            400,
+            "INVALID_REQUEST",
+            "Unknown Card library item",
+          );
+        }
+
+        return errorResponse(
+          500,
+          "DASHBOARD_LOAD_FAILED",
+          "Dashboard could not be loaded",
+        );
+      }
+    },
+
+    updateLayout: async (request: Request, identity: DashboardIdentity) => {
+      const parsed = UpdateDashboardLayoutRequestSchema.safeParse(
+        await readJson(request),
+      );
+      const revision = parsed.success
+        ? parseRevision(parsed.data.revision)
+        : undefined;
+
+      if (!parsed.success || revision === undefined || !isDashboard(identity)) {
+        return errorResponse(
+          400,
+          "INVALID_REQUEST",
+          "Invalid Dashboard layout request",
+        );
+      }
+
+      try {
+        const dashboard = await options.repository.loadDashboard(
+          identity.userId,
+          identity.dashboardId,
+        );
+        const validation = validateDashboardLayout(
+          parsed.data.cards,
+          dashboard.cards.map((card) => card.id),
+        );
+
+        if (!validation.valid) {
+          throw new DashboardInvalidLayoutError(validation.errors);
+        }
+
+        const updated = await options.repository.updateLayout(
+          identity.userId,
+          identity.dashboardId,
+          revision,
+          parsed.data.cards,
+        );
+
+        return Response.json(serializeDashboardDocument(updated, urls));
+      } catch (error) {
+        return mutationError(error, "Invalid Dashboard layout");
+      }
+    },
+
+    updateCard: async (request: Request, identity: CardIdentity) => {
+      const parsed = UpdateDashboardCardRequestSchema.safeParse(
+        await readJson(request),
+      );
+      const revision = parsed.success
+        ? parseRevision(parsed.data.revision)
+        : undefined;
+      const name = parsed.success ? parsed.data.name.trim() : "";
+
+      if (
+        !parsed.success ||
+        revision === undefined ||
+        !name ||
+        !isCard(identity)
+      ) {
+        return errorResponse(
+          400,
+          "INVALID_REQUEST",
+          "Invalid Card update request",
+        );
+      }
+
+      try {
+        const updated = await options.repository.updateCardName(
+          identity.userId,
+          identity.dashboardId,
+          identity.cardId,
+          revision,
+          name,
+        );
+
+        return Response.json(serializeDashboardDocument(updated, urls));
+      } catch (error) {
+        return mutationError(error, "Invalid Card update request");
+      }
+    },
+
+    listCardLibrary: async (_request: Request, identity: DashboardIdentity) => {
+      if (!isDashboard(identity)) {
+        return errorResponse(
+          400,
+          "INVALID_REQUEST",
+          "Invalid Card library request",
+        );
+      }
+
+      try {
+        const [dashboard, cardLibrary] = await Promise.all([
+          options.repository.loadDashboard(identity.userId, identity.dashboardId),
+          resolveCardLibrary(options.cardLibrary, identity),
+        ]);
+
+        return Response.json(buildCardLibraryResponse(dashboard, cardLibrary));
+      } catch (error) {
+        return libraryError(error);
+      }
+    },
+
+    addCard: async (request: Request, identity: DashboardIdentity) => {
+      const parsed = AddDashboardCardRequestSchema.safeParse(
+        await readJson(request),
+      );
+      const revision = parsed.success
+        ? parseRevision(parsed.data.revision)
+        : undefined;
+
+      if (!parsed.success || revision === undefined || !isDashboard(identity)) {
+        return errorResponse(400, "INVALID_REQUEST", "Invalid Card add request");
+      }
+
+      try {
+        const [dashboard, cardLibrary] = await Promise.all([
+          options.repository.loadDashboard(identity.userId, identity.dashboardId),
+          resolveCardLibrary(options.cardLibrary, identity),
+        ]);
+        const template = cardLibrary.find(
+          (item) => item.key === parsed.data.libraryItemKey,
+        );
+
+        if (!template) {
+          throw new DashboardInvalidLibraryItemError();
+        }
+        if (
+          dashboard.cards.some(
+            (card) => card.libraryItemKey === parsed.data.libraryItemKey,
+          )
+        ) {
+          throw new DashboardCardAlreadyAddedError();
+        }
+
+        const updated = await options.repository.addCard(
+          identity.userId,
+          identity.dashboardId,
+          revision,
+          {
+            libraryItemKey: template.key,
+            name: template.name,
+            visualization: template.visualization,
+            deeplink: template.deeplinkLabel
+              ? { label: template.deeplinkLabel }
+              : undefined,
+            layout: firstAvailableLayout(dashboard.cards, template.defaultLayout),
+          },
+        );
+
+        return Response.json({
+          dashboard: serializeDashboardDocument(updated, urls),
+          cardLibrary: buildCardLibraryResponse(updated, cardLibrary),
+        });
+      } catch (error) {
+        return libraryError(error);
+      }
+    },
+
+    removeCard: async (request: Request, identity: CardIdentity) => {
+      const parsed = RemoveDashboardCardRequestSchema.safeParse(
+        await readJson(request),
+      );
+      const revision = parsed.success
+        ? parseRevision(parsed.data.revision)
+        : undefined;
+
+      if (!parsed.success || revision === undefined || !isCard(identity)) {
+        return errorResponse(
+          400,
+          "INVALID_REQUEST",
+          "Invalid Card remove request",
+        );
+      }
+
+      try {
+        const cardLibrary = await resolveCardLibrary(
+          options.cardLibrary,
+          identity,
+        );
+        const updated = await options.repository.removeCard(
+          identity.userId,
+          identity.dashboardId,
+          identity.cardId,
+          revision,
+        );
+
+        return Response.json({
+          dashboard: serializeDashboardDocument(updated, urls),
+          cardLibrary: buildCardLibraryResponse(updated, cardLibrary),
+        });
+      } catch (error) {
+        return libraryError(error);
+      }
+    },
+
+    fetchCardData: async (request: Request, identity: CardIdentity) => {
+      if (!isCard(identity)) {
+        return errorResponse(400, "INVALID_REQUEST", "Invalid Card data request");
+      }
+
+      try {
+        const card = await options.repository.findOwnedCard(
+          identity.userId,
+          identity.dashboardId,
+          identity.cardId,
+        );
+
+        if (!card) {
+          return errorResponse(
+            404,
+            "DASHBOARD_CARD_NOT_FOUND",
+            "Dashboard Card not found",
+          );
+        }
+
+        const result = await options.resolveCardData({
+          ...identity,
+          card,
+          request,
+        });
+        const parsed = PanelCardDataResponseSchema.safeParse(result);
+
+        if (!parsed.success) {
+          return cardQueryFailed();
+        }
+
+        return Response.json(parsed.data);
+      } catch {
+        return cardQueryFailed();
+      }
+    },
+  };
+}
+
+function serializeDashboardBootstrap(
+  result: DashboardBootstrap,
+  urls: Required<DashboardUrlOptions>,
+): DashboardBootstrapResponse {
+  return {
+    dashboards: result.dashboards,
+    dashboard: serializeDashboardDocument(result.dashboard, urls),
+  };
+}
+
+function serializeDashboardDocument(
+  dashboard: PersistedDashboard,
+  urls: Required<DashboardUrlOptions>,
+) {
+  const ownerId = encodeURIComponent(dashboard.ownerUserId);
+  const dashboardId = encodeURIComponent(dashboard.id);
+
+  return DashboardDocumentSchema.parse({
+    id: dashboard.id,
+    revision: String(dashboard.revision),
+    config: {
+      title: dashboard.title,
+      description: dashboard.description,
+      footer: dashboard.footer,
+      cards: dashboard.cards.map((card) => {
+        const cardId = encodeURIComponent(card.id);
+
+        return {
+          id: card.id,
+          name: card.name,
+          visualization: card.visualization,
+          query:
+            `${urls.apiBasePath}/users/${ownerId}` +
+            `/dashboards/${dashboardId}/cards/${cardId}/data`,
+          deeplink: card.deeplink
+            ? {
+                href:
+                  `${urls.dashboardBasePath}/users/${ownerId}` +
+                  `/dashboards/${dashboardId}/cards/${cardId}`,
+                label: card.deeplink.label,
+              }
+            : undefined,
+          layout: card.layout,
+        };
+      }),
+    },
+  });
+}
+
+function buildCardLibraryResponse(
+  dashboard: PersistedDashboard,
+  cardLibrary: readonly CardLibraryTemplate[],
+) {
+  const installed = new Map(
+    dashboard.cards.map((card) => [card.libraryItemKey, card.id]),
+  );
+
+  return CardLibraryResponseSchema.parse({
+    items: cardLibrary.map(
+      (template): CardLibraryItem => ({
+        key: template.key,
+        name: template.name,
+        description: template.description,
+        visualization: template.visualization,
+        defaultLayout: template.defaultLayout,
+        addedCardId: installed.get(template.key),
+      }),
+    ),
+  });
+}
+
+function firstAvailableLayout(
+  cards: readonly PersistedDashboardCard[],
+  size: { width: number; height: number },
+): DashboardCardLayout {
+  if (size.width > DASHBOARD_GRID_COLUMNS) {
+    throw new DashboardInvalidLayoutError([
+      `Card width ${size.width} exceeds the ${DASHBOARD_GRID_COLUMNS}-column grid`,
+    ]);
+  }
+  for (let y = 0; ; y += 1) {
+    for (let x = 0; x + size.width <= DASHBOARD_GRID_COLUMNS; x += 1) {
+      const candidate = { x, y, ...size };
+      if (!cards.some((card) => layoutsOverlap(candidate, card.layout))) {
+        return candidate;
+      }
+    }
+  }
+}
+
+function layoutsOverlap(a: DashboardCardLayout, b: DashboardCardLayout) {
+  return (
+    a.x < b.x + b.width &&
+    a.x + a.width > b.x &&
+    a.y < b.y + b.height &&
+    a.y + a.height > b.y
+  );
+}
+
+async function resolveCardLibrary(
+  cardLibrary: DashboardHandlerOptions["cardLibrary"],
+  context: DashboardContext,
+) {
+  return typeof cardLibrary === "function"
+    ? cardLibrary(context)
+    : cardLibrary;
+}
+
+function mutationError(error: unknown, invalidMessage: string) {
+  if (error instanceof DashboardRevisionConflictError) {
+    return errorResponse(
+      409,
+      "REVISION_CONFLICT",
+      "Dashboard was changed by another request",
+    );
+  }
+  if (error instanceof DashboardNotFoundError) {
+    return errorResponse(404, "DASHBOARD_NOT_FOUND", "Dashboard not found");
+  }
+  if (error instanceof DashboardInvalidLayoutError) {
+    return errorResponse(400, "INVALID_REQUEST", invalidMessage);
+  }
+  return errorResponse(
+    500,
+    "DASHBOARD_LOAD_FAILED",
+    "Dashboard could not be updated",
+  );
+}
+
+function libraryError(error: unknown) {
+  if (error instanceof DashboardRevisionConflictError) {
+    return errorResponse(
+      409,
+      "REVISION_CONFLICT",
+      "Dashboard was changed by another request",
+    );
+  }
+  if (error instanceof DashboardCardAlreadyAddedError) {
+    return errorResponse(
+      409,
+      "CARD_ALREADY_ADDED",
+      "Card is already on this Dashboard",
+    );
+  }
+  if (error instanceof DashboardInvalidLibraryItemError) {
+    return errorResponse(400, "INVALID_REQUEST", "Unknown Card library item");
+  }
+  if (error instanceof DashboardNotFoundError) {
+    return errorResponse(404, "DASHBOARD_NOT_FOUND", "Dashboard not found");
+  }
+  return errorResponse(
+    500,
+    "DASHBOARD_LOAD_FAILED",
+    "Dashboard could not be updated",
+  );
+}
+
+function errorResponse(
+  status: number,
+  code: DashboardApiError["error"]["code"],
+  message: string,
+) {
+  return Response.json(
+    DashboardApiErrorSchema.parse({ error: { code, message } }),
+    { status },
+  );
+}
+
+async function readJson(request: Request): Promise<unknown> {
+  try {
+    return await request.json();
+  } catch {
+    return undefined;
+  }
+}
+
+function parseRevision(revision: string) {
+  if (!/^[1-9]\d*$/.test(revision)) {
+    return undefined;
+  }
+  const value = Number(revision);
+  return Number.isSafeInteger(value) ? value : undefined;
+}
+
+function isDashboard(identity: DashboardIdentity) {
+  return (
+    isIdentitySegment(identity.userId) &&
+    isIdentitySegment(identity.dashboardId)
+  );
+}
+
+function isCard(identity: CardIdentity) {
+  return isDashboard(identity) && isIdentitySegment(identity.cardId);
+}
+
+function isIdentitySegment(value: string) {
+  return value.trim().length > 0 && value.length <= 256;
+}
+
+function cardQueryFailed() {
+  return errorResponse(
+    502,
+    "CARD_QUERY_FAILED",
+    "Card data could not be loaded",
+  );
+}
+
+export {
+  DashboardCardAlreadyAddedError,
+  DashboardInvalidLayoutError,
+  DashboardInvalidLibraryItemError,
+  DashboardNotFoundError,
+  DashboardRevisionConflictError,
+  createDashboardHandlers,
+};
+export type {
+  CardDataResolverInput,
+  CardLibraryTemplate,
+  DashboardBootstrap,
+  DashboardHandlerOptions,
+  DashboardRepository,
+  DashboardSeed,
+  DashboardSeedCard,
+  PersistedDashboard,
+  PersistedDashboardCard,
+};