@kedge/server 0.0.0-stage → 0.9.0

package/src/units/store.order.view.ts

@@ -0,0 +1,9 @@
+// kedge unit store.order.view (docs/proposals/p0.8-cli-agent-kit.md §7): the
+// JSON of GET /store/orders/{id}. Its input is already projected for its
+// reader (field classes, custom-field scopes); what it returns must be an
+// object with the same id. Eject it with `kedge eject store.order.view --reason "<why>"`.
+import type { StoreOrder, ViewOutput } from "@kedge/plugin-sdk";
+
+export default function orderView(order: StoreOrder): ViewOutput {
+  return { ...order };
+}

package/src/units/store.product.view.ts

@@ -0,0 +1,9 @@
+// kedge unit store.product.view (docs/proposals/p0.8-cli-agent-kit.md §7): the
+// JSON of GET /store/products/{handle}. Its input is what any shopper may see;
+// what it returns must be an object with the same id. Eject it with
+// `kedge eject store.product.view --reason "<why>"`.
+import type { StoreProduct, ViewOutput } from "@kedge/plugin-sdk";
+
+export default function productView(product: StoreProduct): ViewOutput {
+  return { ...product };
+}

package/src/webhook-routes.ts

@@ -0,0 +1,362 @@
+// P0.6b's staff routes (docs/proposals/p0.6b-webhooks-calendar-preview.md §2.9,
+// §3.1): webhook endpoints, their delivery log, replay and test, and the
+// business calendar. Creating, rotating, replaying and testing are commands
+// with their own envelope (`own: true`): a retry answers the id or secret
+// it made. The store re-proves every grant rule inside its batch.
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import { holdsUnscoped, KedgeError, readableWebhookTypes, WEBHOOK_LIMITS } from "@kedge/core";
+import type { Context } from "hono";
+import { type AdminPermissions, clientOf, type KedgeEnv } from "./access";
+import { jsonBody, ok } from "./http";
+import type { AdminRequest, AdminStore, CalendarAdmin, PreviewCaptures, WebhookLog } from "./types";
+
+const EndpointId = z.string().regex(/^whe_[0-9A-Za-z]{10,40}$/);
+const DeliveryId = z.string().min(5).max(200);
+const Events = z.array(z.string().min(3).max(64)).min(1).max(WEBHOOK_LIMITS.EVENTS_PER_ENDPOINT_MAX);
+const Grants = z.array(z.string().min(3).max(128)).min(1).max(128);
+const Day = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+
+export function webhookRoutes(
+  app: OpenAPIHono<KedgeEnv>,
+  perms: AdminPermissions,
+  deps: {
+    admin?: AdminStore;
+    webhooks?: WebhookLog;
+    calendar?: CalendarAdmin;
+    previewCaptures?: PreviewCaptures;
+    now: () => number;
+  },
+): void {
+  const ctx = (c: Context<KedgeEnv>) => c.var.access.ctx;
+  const req = (c: Context<KedgeEnv>): AdminRequest => {
+    const client = clientOf(c);
+    return { idempotencyKey: c.req.header("idempotency-key") ?? null, ip: client.ip, userAgent: client.userAgent };
+  };
+  /** A command that makes something or hands a secret out requires its key (docs/06). */
+  const keyed = (c: Context<KedgeEnv>): AdminRequest => {
+    const r = req(c);
+    if (!r.idempotencyKey || new TextEncoder().encode(r.idempotencyKey).length > 255)
+      throw new KedgeError("BAD_REQUEST", "An Idempotency-Key header (1 to 255 bytes) is required", {
+        requirement: "idempotency_key",
+      });
+    return r;
+  };
+  const once = (c: Context) => c.header("cache-control", "no-store");
+  const { admin, webhooks, calendar, previewCaptures } = deps;
+
+  if (admin) {
+    app.openapi(
+      perms.declare(
+        { permission: "webhook:write", own: true },
+        createRoute({
+          method: "post",
+          path: "/admin/webhooks/endpoints",
+          request: jsonBody(
+            z.object({
+              url: z.string().min(9).max(2048),
+              events: Events,
+              grants: Grants,
+              description: z.string().max(200).nullable().optional(),
+            }),
+          ),
+          responses: ok("The endpoint and its signing secret, shown once"),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        once(c);
+        return c.json(
+          await admin.createWebhookEndpoint(
+            ctx(c),
+            { url: b.url, events: b.events, grants: b.grants, description: b.description ?? null },
+            keyed(c),
+          ),
+          200,
+        );
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        "webhook:read",
+        createRoute({
+          method: "get",
+          path: "/admin/webhooks/endpoints",
+          request: {
+            query: z.object({
+              status: z.enum(["active", "disabled"]).default("active"),
+              after: EndpointId.optional(),
+              limit: z.coerce.number().int().min(1).max(100).default(50),
+            }),
+          },
+          responses: ok("One page of endpoints in one status, by id; never a secret"),
+        }),
+      ),
+      async (c) => {
+        const q = c.req.valid("query");
+        return c.json(
+          await admin.webhookEndpoints(ctx(c), { status: q.status, after: q.after ?? null, limit: q.limit }),
+          200,
+        );
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: "webhook:write", own: true },
+        createRoute({
+          method: "patch",
+          path: "/admin/webhooks/endpoints/{id}",
+          request: {
+            params: z.object({ id: EndpointId }),
+            ...jsonBody(
+              z.object({
+                url: z.string().min(9).max(2048).optional(),
+                events: Events.optional(),
+                grants: Grants.optional(),
+                description: z.string().max(200).nullable().optional(),
+              }),
+            ),
+          },
+          responses: ok("The endpoint's new generation"),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        return c.json(
+          await admin.updateWebhookEndpoint(
+            ctx(c),
+            c.req.valid("param").id,
+            {
+              ...(b.url !== undefined ? { url: b.url } : {}),
+              ...(b.events !== undefined ? { events: b.events } : {}),
+              ...(b.grants !== undefined ? { grants: b.grants } : {}),
+              ...(b.description !== undefined ? { description: b.description } : {}),
+            },
+            req(c),
+          ),
+          200,
+        );
+      },
+    );
+
+    for (const action of ["disable", "enable", "delete"] as const) {
+      app.openapi(
+        perms.declare(
+          { permission: "webhook:write", own: true },
+          createRoute({
+            method: action === "delete" ? "delete" : "post",
+            path: action === "delete" ? "/admin/webhooks/endpoints/{id}" : `/admin/webhooks/endpoints/{id}/${action}`,
+            request: { params: z.object({ id: EndpointId }) },
+            responses: ok(`The endpoint, ${action}d`),
+          }),
+        ),
+        async (c) => {
+          const id = c.req.valid("param").id;
+          await admin.setWebhookEndpointStatus(ctx(c), id, action, req(c));
+          return c.json(
+            { id, status: action === "enable" ? "active" : action === "disable" ? "disabled" : "deleted" },
+            200,
+          );
+        },
+      );
+    }
+
+    app.openapi(
+      perms.declare(
+        { permission: "webhook:write", own: true },
+        createRoute({
+          method: "post",
+          path: "/admin/webhooks/endpoints/{id}/rotate-secret",
+          request: { params: z.object({ id: EndpointId }) },
+          responses: ok("The new current secret, shown once; the one it replaces signs for 24 hours more"),
+        }),
+      ),
+      async (c) => {
+        once(c);
+        return c.json(await admin.rotateWebhookSecret(ctx(c), c.req.valid("param").id, keyed(c)), 200);
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: "webhook:write", own: true },
+        createRoute({
+          method: "post",
+          path: "/admin/webhooks/endpoints/{id}/test",
+          request: { params: z.object({ id: EndpointId }) },
+          responses: ok("The test delivery's id"),
+        }),
+      ),
+      async (c) =>
+        c.json({ delivery_id: (await admin.testWebhookEndpoint(ctx(c), c.req.valid("param").id, keyed(c))).id }, 200),
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: "webhook:write", own: true },
+        createRoute({
+          method: "post",
+          path: "/admin/webhooks/deliveries/{id}/replay",
+          request: { params: z.object({ id: DeliveryId }) },
+          responses: ok("The replay's delivery id; a retry answers the same"),
+        }),
+      ),
+      async (c) =>
+        c.json({ delivery_id: (await admin.replayWebhookDelivery(ctx(c), c.req.valid("param").id, keyed(c))).id }, 200),
+    );
+  }
+
+  if (webhooks) {
+    app.openapi(
+      perms.declare(
+        "webhook:read",
+        createRoute({
+          method: "get",
+          path: "/admin/webhooks/deliveries",
+          request: {
+            query: z.object({
+              endpoint: EndpointId.optional(),
+              state: z.enum(["pending", "finalizing", "done", "failed"]).optional(),
+              after: z.coerce.number().int().min(0).default(0),
+              limit: z.coerce.number().int().min(1).max(100).default(50),
+            }),
+          },
+          responses: ok("Deliveries with their attempts: status, code, body hash and size, never a body"),
+        }),
+      ),
+      async (c) => {
+        const q = c.req.valid("query");
+        return c.json(
+          await webhooks.log({
+            // Only the types the reader may read unscoped (§2.9), each a bounded seek.
+            types: readableWebhookTypes(ctx(c).grants),
+            ...(q.endpoint !== undefined ? { endpoint: q.endpoint } : {}),
+            ...(q.state !== undefined ? { state: q.state } : {}),
+            after: q.after,
+            limit: q.limit,
+          }),
+          200,
+        );
+      },
+    );
+  }
+
+  if (previewCaptures) {
+    // A capture holds a whole envelope, so its reader needs everything its
+    // content could need (codex r3); a sign-in code or invite link is a
+    // credential, shown only to a strong Owner (codex r11).
+    const NEEDS = ["settings:read", "order:read", "capacity:read", "webhook:read", "field:pii", "field:financial"];
+    app.openapi(
+      perms.declare(
+        "settings:read",
+        createRoute({
+          method: "get",
+          path: "/admin/preview/captures",
+          request: {
+            query: z.object({
+              port: z.string().min(1).max(64).optional(),
+              after: z.coerce.number().int().min(0).default(0),
+              limit: z.coerce.number().int().min(1).max(100).default(50),
+            }),
+          },
+          responses: ok("A preview's captured calls, webhooks and authentication emails"),
+        }),
+      ),
+      async (c) => {
+        const access = ctx(c);
+        const missing = NEEDS.filter((p) => !holdsUnscoped(access.grants, p));
+        if (missing.length)
+          throw new KedgeError("FORBIDDEN", "Reading captures needs every permission their content could need", {
+            missing,
+          });
+        const q = c.req.valid("query");
+        const rows = await previewCaptures.list({
+          ...(q.port !== undefined ? { port: q.port } : {}),
+          after: q.after,
+          limit: q.limit,
+        });
+        if (rows === null) throw new KedgeError("NOT_FOUND", "Captures exist only in a preview");
+        const p = access.principal;
+        const strongOwner = p.kind === "staff" && p.strong && holdsUnscoped(access.grants, "owner:manage");
+        return c.json(
+          {
+            captures: rows.map((r) =>
+              r.kind === "call" || r.kind === "webhook" || strongOwner
+                ? r
+                : { ...r, envelope: { redacted: true }, result: null },
+            ),
+          },
+          200,
+        );
+      },
+    );
+  }
+
+  if (calendar) {
+    app.openapi(
+      perms.declare(
+        "settings:read",
+        createRoute({
+          method: "get",
+          path: "/admin/settings/calendar",
+          responses: ok("Working days, the cutoff, and the holidays of the calendar's window"),
+        }),
+      ),
+      async (c) => c.json((await calendar.get(deps.now())) as Record<string, unknown>, 200),
+    );
+    app.openapi(
+      perms.declare(
+        "settings:write",
+        createRoute({
+          method: "put",
+          path: "/admin/settings/calendar",
+          request: jsonBody(
+            z.object({
+              working_days: z.number().int().min(1).max(127),
+              cutoff_minutes: z.number().int().min(0).max(1439).nullable(),
+            }),
+          ),
+          responses: ok("The calendar"),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        await calendar.set({ workingDays: b.working_days, cutoffMinutes: b.cutoff_minutes });
+        return c.json((await calendar.get(deps.now())) as Record<string, unknown>, 200);
+      },
+    );
+    app.openapi(
+      perms.declare(
+        "settings:write",
+        createRoute({
+          method: "put",
+          path: "/admin/settings/calendar/holidays/{day}",
+          request: { params: z.object({ day: Day }), ...jsonBody(z.object({ name: z.string().min(1).max(80) })) },
+          responses: ok("The holiday"),
+        }),
+      ),
+      async (c) => {
+        const day = c.req.valid("param").day;
+        await calendar.putHoliday(day, c.req.valid("json").name);
+        return c.json({ day }, 200);
+      },
+    );
+    app.openapi(
+      perms.declare(
+        "settings:write",
+        createRoute({
+          method: "delete",
+          path: "/admin/settings/calendar/holidays/{day}",
+          request: { params: z.object({ day: Day }) },
+          responses: ok("The holiday, removed"),
+        }),
+      ),
+      async (c) => {
+        const day = c.req.valid("param").day;
+        await calendar.deleteHoliday(day);
+        return c.json({ day, removed: true }, 200);
+      },
+    );
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.