@kedge/server 0.0.0-stage → 0.9.0

package/src/entity-routes.ts

@@ -0,0 +1,323 @@
+// P0.7's plugin entity routes (docs/proposals/p0.7-tracks-entities.md §4.4,
+// §4.7): per declared entity, a windowed list, a search with classified
+// values in the body, a read, a create, an update and an archive, each with
+// its own zod schemas in the OpenAPI document; and the admin's page
+// metadata. Row scopes are compiled into every batch and re-proved there, so
+// the store authorizes each request itself (`store: true`).
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import { ENTITY_LIMITS, type EntityDefinition, type EntityField, holds, KedgeError, permissionsOf } from "@kedge/core";
+import type { Context } from "hono";
+import { type AdminPermissions, clientOf, type KedgeEnv } from "./access";
+import { jsonBody, ok } from "./http";
+import type { EntityAdmin } from "./types";
+
+const Id = z.string().min(5).max(64);
+const OrderId = z.string().regex(/^ord_[0-9A-Za-z]{10,40}$/);
+
+/** A field's input schema (§4.7): strict, from the current declaration. */
+function inputOf(f: EntityField): z.ZodTypeAny {
+  switch (f.type) {
+    case "string":
+    case "text":
+      return z.string().max(f.max ?? (f.type === "string" ? 1000 : 16000));
+    case "integer":
+    case "datetime":
+      return z.number().int();
+    case "boolean":
+      return z.boolean();
+    case "date":
+      return z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+    case "select":
+      return z.enum(f.options as [string, ...string[]]);
+    case "json":
+      return z.record(z.string(), z.unknown());
+    case "staff":
+    case "location":
+      return z.string().min(1).max(64);
+    case "money":
+      return z.object({ amount: z.number().int(), currency_code: z.string().length(3) });
+  }
+}
+
+/**
+ * A field's response schema (§4.7, codex r2): types only, so a value written
+ * under a widened rule still matches an older Worker's schema, and optional
+ * whenever its class can be projected away.
+ */
+function viewOf(f: EntityField): z.ZodTypeAny {
+  const t =
+    f.type === "integer" || f.type === "datetime"
+      ? z.number().int()
+      : f.type === "boolean"
+        ? z.boolean()
+        : f.type === "json"
+          ? z.record(z.string(), z.unknown())
+          : f.type === "money"
+            ? z.object({ amount: z.number().int(), currency_code: z.string() })
+            : z.string();
+  return t.nullable().optional();
+}
+
+export function entityRoutes(
+  app: OpenAPIHono<KedgeEnv>,
+  perms: AdminPermissions,
+  entities: { store: EntityAdmin; declared: readonly { plugin: string; entity: string; def: EntityDefinition }[] },
+): void {
+  const { store } = entities;
+  const ctx = (c: Context<KedgeEnv>) => c.var.access.ctx;
+  const client = (c: Context<KedgeEnv>) => {
+    const x = clientOf(c);
+    return { idempotencyKey: c.req.header("idempotency-key") ?? null, ip: x.ip, userAgent: x.userAgent };
+  };
+
+  app.openapi(
+    perms.declare(
+      { permission: "entity:meta", store: true },
+      createRoute({
+        method: "get",
+        path: "/admin/meta/entities",
+        responses: ok("The plugin entities the caller may read, as definitions"),
+      }),
+    ),
+    async (c) => c.json(store.metadata(ctx(c)) as object, 200),
+  );
+
+  for (const { plugin, entity, def } of entities.declared) {
+    const base = `/admin/plugins/${plugin}/${entity}`;
+    const p = permissionsOf(plugin, entity, def);
+    const fields = Object.entries(def.fields);
+    const view = z
+      .object({
+        id: z.string(),
+        version: z.number().int(),
+        state: z.enum(["live", "archived"]),
+        order_id: z.string().nullable(),
+        created_at: z.number().int(),
+        updated_at: z.number().int(),
+        created_by: z.string().optional(),
+        updated_by: z.string().optional(),
+        ...Object.fromEntries(fields.map(([n, f]) => [n, viewOf(f)])),
+      })
+      .openapi(`${plugin}_${entity}`);
+    // Strict, as core's parser is: a misspelt field is refused, never dropped
+    // into an empty update that still steps the version (codex code r1).
+    const create = z.object({
+      values: z.strictObject(
+        Object.fromEntries(fields.map(([n, f]) => [n, f.required ? inputOf(f) : inputOf(f).nullable().optional()])),
+      ),
+      order_id: OrderId.nullable().optional(),
+    });
+    const update = z.object({
+      version: z.number().int().min(1),
+      set: z.strictObject(
+        Object.fromEntries(
+          fields.map(([n, f]) => [n, f.required ? inputOf(f).optional() : inputOf(f).nullable().optional()]),
+        ),
+      ),
+    });
+    // Public values only in the URL (P0.5 §5.2): `?<field>=v` (a comma list is `in`), `<field>_from`/`_to`.
+    const query = z.object({
+      sort: z.string().max(64).optional(),
+      state: z.enum(["live", "archived"]).optional(),
+      cursor: z.string().max(2048).optional(),
+      limit: z.coerce.number().int().min(1).max(100).optional(),
+    });
+    // A URL value is text; only a numeric field's operand becomes a number, so
+    // a text field compares as the stored text (`0010` isn't 10, codex code r10).
+    const typed = (field: string, v: string): unknown => {
+      const t = Object.hasOwn(def.fields, field) ? def.fields[field]?.type : undefined;
+      return (t === "integer" || t === "datetime") && v.trim() !== "" && !Number.isNaN(Number(v)) ? Number(v) : v;
+    };
+    const filtersOf = (q: Record<string, string>) => {
+      const out: { field: string; op: string; value: unknown }[] = [];
+      for (const [k, v] of Object.entries(q)) {
+        if (["sort", "state", "cursor", "limit"].includes(k)) continue;
+        // A declared field's own name is never a range: `available_from` is a field (codex code r4).
+        const range = Object.hasOwn(def.fields, k) ? null : /^(.+)_(from|to)$/.exec(k);
+        if (range)
+          out.push({
+            field: range[1] as string,
+            op: range[2] === "from" ? "gte" : "lt",
+            value: typed(range[1] as string, v),
+          });
+        else {
+          const values = v
+            .split(",")
+            .filter(Boolean)
+            .map((x) => typed(k, x));
+          out.push(
+            values.length > 1 ? { field: k, op: "in", value: values } : { field: k, op: "eq", value: typed(k, v) },
+          );
+        }
+      }
+      return out;
+    };
+    const sortOf = (s: string | undefined) =>
+      s
+        ? { field: s.replace(/^-/, ""), direction: s.startsWith("-") ? ("desc" as const) : ("asc" as const) }
+        : undefined;
+
+    app.openapi(
+      perms.declare(
+        { permission: p.read, store: true },
+        createRoute({ method: "get", path: base, request: { query }, responses: ok(`A page of ${def.label}`) }),
+      ),
+      async (c) => {
+        const q = c.req.valid("query");
+        const sort = sortOf(q.sort);
+        return c.json(
+          (await store.list(ctx(c), plugin, entity, {
+            query: { via: "query", filters: filtersOf(c.req.query()), ...(sort ? { sort } : {}) },
+            cursor: q.cursor ?? null,
+            ...(q.limit ? { limit: q.limit } : {}),
+            ...(q.state ? { state: q.state } : {}),
+          })) as object,
+          200,
+        );
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: p.read, store: true, read: true },
+        createRoute({
+          method: "post",
+          path: `${base}/search`,
+          request: jsonBody(
+            z.object({
+              filters: z
+                .array(z.object({ field: z.string(), op: z.enum(["eq", "in", "gte", "lt"]), value: z.unknown() }))
+                .max(16)
+                .optional(),
+              search: z
+                .object({
+                  fields: z.array(z.string()).min(1).max(ENTITY_LIMITS.SEARCH_FIELDS_MAX),
+                  term: z.string().min(1).max(200),
+                })
+                .optional(),
+              sort: z.string().max(64).optional(),
+              state: z.enum(["live", "archived"]).optional(),
+              cursor: z.string().max(2048).optional(),
+              limit: z.number().int().min(1).max(100).optional(),
+            }),
+          ),
+          responses: ok(`A page of ${def.label}, classified values in the body`),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        const sort = sortOf(b.sort);
+        return c.json(
+          (await store.list(ctx(c), plugin, entity, {
+            query: {
+              via: "body",
+              filters: b.filters ?? [],
+              ...(b.search ? { search: b.search } : {}),
+              ...(sort ? { sort } : {}),
+            },
+            cursor: b.cursor ?? null,
+            ...(b.limit ? { limit: b.limit } : {}),
+            ...(b.state ? { state: b.state } : {}),
+          })) as object,
+          200,
+        );
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: p.read, store: true },
+        createRoute({
+          method: "get",
+          path: `${base}/{id}`,
+          request: { params: z.object({ id: Id }) },
+          responses: { 200: { description: `One ${def.label}`, content: { "application/json": { schema: view } } } },
+        }),
+      ),
+      async (c) => {
+        if (!holds(ctx(c).grants, p.read))
+          throw new KedgeError("FORBIDDEN", "You don't have permission for this", { permission: p.read });
+        const row = await store.get(ctx(c), plugin, entity, c.req.valid("param").id);
+        if (!row) throw new KedgeError("NOT_FOUND", "Not found");
+        return c.json(row as never, 200);
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: p.write, store: true },
+        createRoute({
+          method: "post",
+          path: base,
+          request: jsonBody(create),
+          responses: ok(`The new ${def.label}, or a receipt`),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        return c.json(
+          (await store.create(ctx(c), {
+            plugin,
+            entity,
+            values: b.values,
+            orderId: b.order_id ?? null,
+            ...client(c),
+          })) as object,
+          200,
+        );
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: p.write, store: true },
+        createRoute({
+          method: "patch",
+          path: `${base}/{id}`,
+          request: { params: z.object({ id: Id }), ...jsonBody(update) },
+          responses: ok(`The updated ${def.label}, or a receipt`),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        return c.json(
+          (await store.write(ctx(c), {
+            plugin,
+            entity,
+            id: c.req.valid("param").id,
+            version: b.version,
+            set: b.set,
+            ...client(c),
+          })) as object,
+          200,
+        );
+      },
+    );
+
+    app.openapi(
+      perms.declare(
+        { permission: p.write, store: true },
+        createRoute({
+          method: "post",
+          path: `${base}/{id}/archive`,
+          request: { params: z.object({ id: Id }), ...jsonBody(z.object({ version: z.number().int().min(1) })) },
+          responses: ok(`The archived ${def.label}, or a receipt`),
+        }),
+      ),
+      async (c) => {
+        const b = c.req.valid("json");
+        return c.json(
+          (await store.write(ctx(c), {
+            plugin,
+            entity,
+            id: c.req.valid("param").id,
+            version: b.version,
+            archive: true,
+            ...client(c),
+          })) as object,
+          200,
+        );
+      },
+    );
+  }
+}

package/src/events.ts

@@ -0,0 +1,84 @@
+// The event catalog's payload schemas (docs/05 §9; p0.6a §2.1), one per type
+// P0.6a emits or delivers, matching what 0023–0026's triggers and the stores
+// write. Core keeps each type's aggregate and restore-stability
+// (EVENT_CATALOG); this is the shape a subscriber, the SDK and the docs see.
+import { z } from "@hono/zod-openapi";
+import { EVENT_CATALOG, type EventType } from "@kedge/core";
+
+const orderTransition = z.object({ order_id: z.string(), transition_uid: z.string() });
+
+export const EVENT_SCHEMAS = {
+  "order.created": z.object({ id: z.string() }).passthrough(),
+  "order.placed": z
+    .object({
+      id: z.string(),
+      number: z.number().int().nullable(),
+      status: z.string(),
+      currency_code: z.string(),
+      // No email since 0027 (p0.6b §2.6): it is read from the order. Events
+      // written before keep theirs, which `passthrough` lets through.
+      subtotal: z.number().int(),
+      total: z.number().int(),
+      revenue_total: z.number().int().nullable(),
+      deposit_total: z.number().int().nullable(),
+      placed_at: z.number().int().nullable(),
+      lines: z.array(
+        z.object({
+          id: z.string(),
+          variant_id: z.string(),
+          sku: z.string(),
+          title: z.string(),
+          unit_price: z.number().int(),
+          quantity: z.number().int(),
+        }),
+      ),
+    })
+    .passthrough(),
+  "order.expired": orderTransition,
+  "order.canceled": orderTransition,
+  "order.completed": orderTransition,
+  "timer.fired": z.object({
+    timer_id: z.string(),
+    key: z.string(),
+    generation: z.number().int(),
+    revision_id: z.string(),
+  }),
+  "pool.capacity_changed": z.object({ pool_id: z.string() }).passthrough(),
+  "level.availability_changed": z
+    .object({
+      inventory_item_id: z.string(),
+      location_id: z.string(),
+      on_hand: z.number().int(),
+      safety_stock: z.number().int(),
+    })
+    .passthrough(),
+  "capacity.base_negative": z.object({ pool_id: z.string() }).passthrough(),
+  "stock.shortage": z.object({}).passthrough(),
+  // P0.6b (§2.6, §3.2).
+  "webhook_endpoint.disabled": z.object({
+    endpoint_id: z.string(),
+    reason: z.enum(["failing", "staff"]),
+    disabled_at: z.number().int(),
+    generation: z.number().int(),
+  }),
+  "webhook.test": z.object({ endpoint_id: z.string(), sent_at: z.number().int() }),
+  "store_calendar.changed": z.object({ version: z.number().int() }),
+  // P0.7 (§3.9): ids only, never the comment.
+  "track.transitioned": z.object({
+    plugin: z.string(),
+    track: z.string(),
+    aggregate: z.string(),
+    aggregate_id: z.string(),
+    track_state_id: z.string(),
+    from: z.string(),
+    to: z.string(),
+    version: z.number().int(),
+    transition_uid: z.string(),
+  }),
+} satisfies Record<EventType, z.ZodTypeAny>;
+
+/** Every catalog type has a schema, and no schema names a type core doesn't know. */
+export function catalogComplete(): boolean {
+  const core = Object.keys(EVENT_CATALOG).sort();
+  return JSON.stringify(core) === JSON.stringify(Object.keys(EVENT_SCHEMAS).sort());
+}

package/src/http.ts

@@ -0,0 +1,16 @@
+// Route description helpers shared by the route modules.
+import { z } from "@hono/zod-openapi";
+
+const ErrorSchema = z.object({
+  error: z.object({ code: z.string(), message: z.string(), details: z.record(z.string(), z.unknown()).optional() }),
+});
+const errors = { 400: { description: "Invalid request", content: { "application/json": { schema: ErrorSchema } } } };
+
+export const ok = (description: string) => ({
+  200: { description, content: { "application/json": { schema: z.any() } } },
+  ...errors,
+});
+
+export const jsonBody = <T extends z.ZodType>(schema: T) => ({
+  body: { content: { "application/json": { schema } }, required: true },
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createApp } from "./app";
+export type * from "./types";