@frockbot/plugin-bot-template 0.0.0 → 0.1.1

package/src/backend.test.ts

@@ -0,0 +1,326 @@
+import { describe, expect, it } from "bun:test";
+import {
+  createBotTemplateBackendContribution,
+  type BotTemplateGatewayHostV1,
+  type PublishedTemplateV1,
+} from "./backend.ts";
+import type {
+  TemplateCommandV1,
+  TemplateImportRecordV1,
+  TemplateShareListViewV1,
+  TemplateShareReceiptV1,
+} from "./shared.ts";
+
+const SHARE_ID = `user-1.${"a".repeat(32)}`;
+const HASH = "b".repeat(64);
+const DOCUMENT = '{"schemaVersion":1}';
+
+function share(visibility: "private" | "link" | "public" = "link") {
+  return {
+    schemaVersion: 1 as const,
+    shareId: SHARE_ID,
+    hash: HASH,
+    botId: "budget",
+    visibility,
+    createdAt: "2026-08-31T00:00:00.000Z",
+  };
+}
+
+function host(
+  overrides: Partial<BotTemplateGatewayHostV1> = {},
+): BotTemplateGatewayHostV1 & { commands: TemplateCommandV1[] } {
+  const commands: TemplateCommandV1[] = [];
+  return {
+    commands,
+    listTemplateShares: (): Promise<TemplateShareListViewV1> =>
+      Promise.resolve({ schemaVersion: 1, shares: [share()] }),
+    executeTemplateCommand: (
+      _userId: string,
+      command: TemplateCommandV1,
+    ): Promise<TemplateShareReceiptV1> => {
+      commands.push(command);
+      return Promise.resolve({
+        schemaVersion: 1,
+        commandId: command.commandId,
+        status: "applied",
+        share: share(),
+      });
+    },
+    readPublishedTemplate: (): Promise<PublishedTemplateV1 | undefined> =>
+      Promise.resolve({
+        hash: HASH,
+        visibility: "link",
+        document: DOCUMENT,
+      }),
+    listTemplateImports: () =>
+      Promise.resolve({ schemaVersion: 1 as const, imports: [] }),
+    executeTemplateImport: (
+      _userId: string,
+      command: TemplateCommandV1,
+    ): Promise<TemplateImportRecordV1> => {
+      commands.push(command);
+      return Promise.resolve({
+        schemaVersion: 1,
+        importId: "import-1",
+        shareId: SHARE_ID,
+        hash: HASH,
+        botId: "budget-abc123456789",
+        status: "planned",
+        botName: "Budget",
+        packages: [],
+        connections: [],
+        skills: [],
+        routines: [],
+        steps: [{ key: "bot/create", kind: "bot/create", status: "pending" }],
+        createdAt: "2026-09-01T00:00:00.000Z",
+        updatedAt: "2026-09-01T00:00:00.000Z",
+      });
+    },
+    ...overrides,
+  };
+}
+
+function get(
+  path: string,
+  headers: Record<string, string> = {},
+): [Request, URL] {
+  const url = new URL(`https://bot.frockbot.com${path}`);
+  return [new Request(url, { headers }), url];
+}
+
+describe("the public template route", () => {
+  it("serves a published blob with its content hash as the etag", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const [request, url] = get(`/templates/v1/${SHARE_ID}`);
+    const response = await contribution.publicRoute(request, url, {
+      client: "browser",
+    });
+    expect(response?.status).toBe(200);
+    expect(response?.headers.get("etag")).toBe(`"${HASH}"`);
+    expect(response?.headers.get("cache-control")).toContain("private");
+    expect(await response?.text()).toBe(DOCUMENT);
+  });
+
+  it("answers 304 to a matching etag", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const [request, url] = get(`/templates/v1/${SHARE_ID}`, {
+      "if-none-match": `"${HASH}"`,
+    });
+    const response = await contribution.publicRoute(request, url, {
+      client: "browser",
+    });
+    expect(response?.status).toBe(304);
+  });
+
+  it("answers 404 for a private, revoked or missing share alike", async () => {
+    const contribution = createBotTemplateBackendContribution(
+      host({ readPublishedTemplate: () => Promise.resolve(undefined) }),
+    );
+    const [request, url] = get(`/templates/v1/${SHARE_ID}`);
+    const response = await contribution.publicRoute(request, url, {
+      client: "browser",
+    });
+    expect(response?.status).toBe(404);
+    expect(await response?.text()).not.toContain("private");
+  });
+
+  it("answers 404 for a malformed share id rather than 400", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const [request, url] = get("/templates/v1/not-a-share");
+    const response = await contribution.publicRoute(request, url, {
+      client: "browser",
+    });
+    expect(response?.status).toBe(404);
+  });
+
+  it("ignores a path it does not own", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const [request, url] = get("/api/settings");
+    expect(
+      await contribution.publicRoute(request, url, { client: "browser" }),
+    ).toBeUndefined();
+  });
+
+  it("refuses a write on the public route", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const url = new URL(`https://bot.frockbot.com/templates/v1/${SHARE_ID}`);
+    const response = await contribution.publicRoute(
+      new Request(url, { method: "POST" }),
+      url,
+      { client: "browser" },
+    );
+    expect(response?.status).toBe(405);
+  });
+});
+
+describe("the authenticated share route", () => {
+  it("lists this User's shares", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const [request, url] = get("/api/bot-templates");
+    const response = await contribution.route(request, url, {
+      userId: "user-1",
+      client: "browser",
+    });
+    expect(response?.status).toBe(200);
+    expect(await response?.json()).toEqual({
+      schemaVersion: 1,
+      shares: [share()],
+    });
+  });
+
+  it("refuses an anonymous caller", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const [request, url] = get("/api/bot-templates");
+    const response = await contribution.route(request, url, {
+      client: "browser",
+    });
+    expect(response?.status).toBe(401);
+  });
+
+  it("carries a decoded command to the authority", async () => {
+    const dependencies = host();
+    const contribution = createBotTemplateBackendContribution(dependencies);
+    const url = new URL("https://bot.frockbot.com/api/bot-templates");
+    const response = await contribution.route(
+      new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "template/set-visibility",
+          commandId: "visibility-1",
+          shareId: SHARE_ID,
+          visibility: "link",
+        }),
+      }),
+      url,
+      { userId: "user-1", client: "browser" },
+    );
+    expect(response?.status).toBe(200);
+    expect(dependencies.commands).toEqual([
+      {
+        schemaVersion: 1,
+        type: "template/set-visibility",
+        commandId: "visibility-1",
+        shareId: SHARE_ID,
+        visibility: "link",
+      },
+    ]);
+  });
+
+  it("refuses a command with an unknown field", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const url = new URL("https://bot.frockbot.com/api/bot-templates");
+    const response = await contribution.route(
+      new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "template/stage",
+          commandId: "stage-1",
+          botId: "budget",
+          visibility: "public",
+        }),
+      }),
+      url,
+      { userId: "user-1", client: "browser" },
+    );
+    expect(response?.status).toBe(400);
+  });
+
+  it("answers 404 when the authority does not know the share", async () => {
+    const contribution = createBotTemplateBackendContribution(
+      host({
+        executeTemplateCommand: () => {
+          const error = new Error("template share was not found");
+          error.name = "TemplateShareNotFoundError";
+          return Promise.reject(error);
+        },
+      }),
+    );
+    const url = new URL("https://bot.frockbot.com/api/bot-templates");
+    const response = await contribution.route(
+      new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "template/revoke",
+          commandId: "revoke-1",
+          shareId: SHARE_ID,
+        }),
+      }),
+      url,
+      { userId: "user-1", client: "browser" },
+    );
+    expect(response?.status).toBe(404);
+  });
+});
+
+describe("the import route", () => {
+  it("plans an import and returns the review card", async () => {
+    const dependencies = host();
+    const contribution = createBotTemplateBackendContribution(dependencies);
+    const url = new URL("https://bot.frockbot.com/api/bot-template-imports");
+    const response = await contribution.route(
+      new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "template/plan-import",
+          commandId: "import-1",
+          shareId: SHARE_ID,
+        }),
+      }),
+      url,
+      { userId: "user-b", client: "browser" },
+    );
+    expect(response?.status).toBe(200);
+    expect(await response?.json()).toMatchObject({ status: "planned" });
+    expect(dependencies.commands[0]).toMatchObject({
+      type: "template/plan-import",
+    });
+  });
+
+  it("refuses a share command on the import route", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const url = new URL("https://bot.frockbot.com/api/bot-template-imports");
+    const response = await contribution.route(
+      new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "template/revoke",
+          commandId: "revoke-1",
+          shareId: SHARE_ID,
+        }),
+      }),
+      url,
+      { userId: "user-b", client: "browser" },
+    );
+    expect(response?.status).toBe(400);
+  });
+
+  it("refuses an import command on the share route", async () => {
+    const contribution = createBotTemplateBackendContribution(host());
+    const url = new URL("https://bot.frockbot.com/api/bot-templates");
+    const response = await contribution.route(
+      new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          type: "template/apply-import",
+          commandId: "apply-1",
+          importId: "import-1",
+        }),
+      }),
+      url,
+      { userId: "user-b", client: "browser" },
+    );
+    expect(response?.status).toBe(400);
+  });
+});

package/src/backend.ts

@@ -0,0 +1,262 @@
+// The Bot Template gateway Contribution.
+//
+//   GET  /api/bot-templates          this User's shares
+//   POST /api/bot-templates          one template command
+//   GET  /templates/v1/:shareId      the published blob, unauthenticated
+//
+// The last one is the only unauthenticated route in this Package, and it is
+// unauthenticated on purpose: a `link` share is a capability URL, and asking
+// the recipient to hold an account first would make it something else. It is
+// served through the gateway's `publicRoute` seam, which runs before identity,
+// and it answers a `private` or revoked share exactly as it answers one that
+// never existed — 404, with no body — so the route cannot be probed.
+//
+// The gateway owns no state here. It carries each request to the User Durable
+// Object that is the authority for that User's shares, and the share id names
+// which one that is.
+import type { Plugin } from "cordis";
+import {
+  decodeTemplateContentHashV1,
+  parseTemplateShareIdV1,
+  TemplateDecodeError,
+  type TemplateVisibilityV1,
+} from "@frockbot/template-core";
+import {
+  decodeTemplateCommandV1,
+  decodeTemplateImportListViewV1,
+  decodeTemplateImportRecordV1,
+  decodeTemplateShareListViewV1,
+  decodeTemplateShareReceiptV1,
+  type TemplateCommandV1,
+  type TemplateImportListViewV1,
+  type TemplateImportRecordV1,
+  type TemplateShareListViewV1,
+  type TemplateShareReceiptV1,
+} from "./shared.js";
+
+export interface PublishedTemplateV1 {
+  hash: string;
+  visibility: TemplateVisibilityV1;
+  document: string;
+}
+
+export interface BotTemplateGatewayHostV1 {
+  listTemplateShares(userId: string): Promise<TemplateShareListViewV1>;
+  executeTemplateCommand(
+    userId: string,
+    command: TemplateCommandV1,
+  ): Promise<TemplateShareReceiptV1>;
+  /** `undefined` for a share that is missing, private, or revoked, alike. */
+  readPublishedTemplate(
+    shareId: string,
+  ): Promise<PublishedTemplateV1 | undefined>;
+  listTemplateImports(userId: string): Promise<TemplateImportListViewV1>;
+  executeTemplateImport(
+    userId: string,
+    command: TemplateCommandV1,
+  ): Promise<TemplateImportRecordV1>;
+}
+
+export interface BotTemplateBackendRouteContribution {
+  packageId: string;
+  publicRoute(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+}
+
+const SHARES_PATH = "/api/bot-templates";
+const IMPORTS_PATH = "/api/bot-template-imports";
+const PUBLIC_PREFIX = "/templates/v1/";
+
+function jsonError(status: number, message: string): Response {
+  return Response.json({ error: message }, { status });
+}
+
+function notFound(): Response {
+  return jsonError(404, "template share was not found");
+}
+
+function isDecodeError(error: unknown): boolean {
+  return (
+    error instanceof TemplateDecodeError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "TemplateDecodeError")
+  );
+}
+
+function isMissing(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error.name === "TemplateShareNotFoundError" ||
+      error.name === "BotNotFoundError")
+  );
+}
+
+function errorResponse(error: unknown): Response {
+  if (isMissing(error)) return notFound();
+  if (isDecodeError(error)) {
+    return jsonError(
+      400,
+      error instanceof Error ? error.message : "template request is invalid",
+    );
+  }
+  return jsonError(
+    500,
+    error instanceof Error ? error.message : "template request failed",
+  );
+}
+
+/**
+ * The blob is content-addressed and immutable, so a matched `etag` is the whole
+ * answer: the same hash can only ever be the same bytes. Revocation still
+ * bites, because the share record is read before the cache header is ever
+ * considered.
+ */
+function templateResponse(
+  request: Request,
+  found: PublishedTemplateV1,
+): Response {
+  const etag = `"${decodeTemplateContentHashV1(found.hash)}"`;
+  const headers = {
+    "content-type": "application/json; charset=utf-8",
+    // Never `public`: revoking a share must not leave copies in a shared cache.
+    "cache-control": "private, max-age=300, must-revalidate",
+    etag,
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "no-referrer",
+  };
+  if (request.headers.get("if-none-match") === etag) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(found.document, { headers });
+}
+
+export function createBotTemplateBackendContribution(
+  host: BotTemplateGatewayHostV1,
+): BotTemplateBackendRouteContribution {
+  return {
+    packageId: "bot-template",
+
+    async publicRoute(request, url) {
+      if (!url.pathname.startsWith(PUBLIC_PREFIX)) return undefined;
+      if (request.method !== "GET" && request.method !== "HEAD") {
+        return jsonError(405, "method not allowed");
+      }
+      if ([...url.searchParams.keys()].length > 0) {
+        return jsonError(400, "the template route takes no query parameters");
+      }
+      let shareId: string;
+      try {
+        shareId = decodeURIComponent(url.pathname.slice(PUBLIC_PREFIX.length));
+        parseTemplateShareIdV1(shareId);
+      } catch {
+        // A malformed share id is indistinguishable from a missing one to the
+        // caller, so it gets the same answer.
+        return notFound();
+      }
+      try {
+        const found = await host.readPublishedTemplate(shareId);
+        if (!found) return notFound();
+        return templateResponse(request, found);
+      } catch (error) {
+        if (isMissing(error) || isDecodeError(error)) return notFound();
+        return jsonError(
+          502,
+          error instanceof Error ? error.message : "template read failed",
+        );
+      }
+    },
+
+    async route(request, url, context) {
+      if (url.pathname !== SHARES_PATH && url.pathname !== IMPORTS_PATH) {
+        return undefined;
+      }
+      if (!context.userId) return jsonError(401, "authentication required");
+      if ([...url.searchParams.keys()].length > 0) {
+        return jsonError(400, "the template route takes no query parameters");
+      }
+      if (url.pathname === IMPORTS_PATH) {
+        try {
+          if (request.method === "GET") {
+            return Response.json(
+              decodeTemplateImportListViewV1(
+                await host.listTemplateImports(context.userId),
+              ),
+            );
+          }
+          if (request.method !== "POST") {
+            return jsonError(405, "method not allowed");
+          }
+          const command = decodeTemplateCommandV1(await request.json());
+          if (
+            command.type !== "template/plan-import" &&
+            command.type !== "template/apply-import"
+          ) {
+            return jsonError(
+              400,
+              "the import route takes an import command only",
+            );
+          }
+          return Response.json(
+            decodeTemplateImportRecordV1(
+              await host.executeTemplateImport(context.userId, command),
+            ),
+          );
+        } catch (error) {
+          return errorResponse(error);
+        }
+      }
+      try {
+        if (request.method === "GET") {
+          return Response.json(
+            decodeTemplateShareListViewV1(
+              await host.listTemplateShares(context.userId),
+            ),
+          );
+        }
+        if (request.method !== "POST") {
+          return jsonError(405, "method not allowed");
+        }
+        const command = decodeTemplateCommandV1(await request.json());
+        if (
+          command.type === "template/plan-import" ||
+          command.type === "template/apply-import"
+        ) {
+          return jsonError(
+            400,
+            "an import command belongs on the import route",
+          );
+        }
+        return Response.json(
+          decodeTemplateShareReceiptV1(
+            await host.executeTemplateCommand(context.userId, command),
+          ),
+        );
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  };
+}
+
+export namespace createBotTemplateBackendContribution {
+  export function plugin(
+    host: BotTemplateGatewayHostV1,
+    lifecycle: {
+      mount(value: BotTemplateBackendRouteContribution): () => void;
+    },
+  ): Plugin {
+    return () => lifecycle.mount(createBotTemplateBackendContribution(host));
+  }
+}