@kedge/server 0.0.0-stage → 0.10.0

package/src/capacity-routes.ts

@@ -0,0 +1,440 @@
+// P0.4's routes (p0.4-dated-capacity.md §6, dated-capacity.md §7): store
+// availability, and the admin's capacity commands and views. Every command
+// that adds a fact takes an Idempotency-Key, scoped to the caller and the
+// operation (docs/06); the store replays a retry's stored result.
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import { actorOf, KedgeError, parseLocalDate } from "@kedge/core";
+import type { Context } from "hono";
+import type { AdminPermissions, KedgeEnv } from "./access";
+import { jsonBody, ok } from "./http";
+import type { AppDeps } from "./types";
+
+const ID = z.string().min(1).max(64);
+const Instant = z.iso.datetime({ offset: true }).transform((v) => Date.parse(v));
+const ORDER_ID = /^ord_[0-9A-HJKMNP-TV-Z]{26}$/;
+
+export function capacityRoutes(app: OpenAPIHono<KedgeEnv>, deps: AppDeps, perms: AdminPermissions): void {
+  const { capacity, availability } = deps;
+  const clock = deps.clock;
+  /** A command's retry scope is its caller (p0.5 §8): the staff member or key the request resolved. */
+  const who = (c: Context<KedgeEnv>) => ({
+    principal: actorOf(c.var.access.ctx.principal),
+    key: c.req.header("idempotency-key") ?? null,
+  });
+
+  if (availability) {
+    app.openapi(
+      createRoute({
+        method: "get",
+        path: "/store/availability",
+        request: {
+          query: z.object({
+            variant: ID,
+            kind: z.string().min(1).max(64).optional(),
+            from: Instant,
+            to: Instant.optional(),
+            days: z.coerce.number().int().min(1).max(62).optional(),
+            location: ID.optional(),
+          }),
+        },
+        responses: ok("Units bookable over a period, or per day"),
+      }),
+      async (c) => {
+        const q = c.req.valid("query");
+        if ((q.to === undefined) === (q.days === undefined))
+          throw new KedgeError("BAD_REQUEST", "Give either to or days");
+        const periods =
+          q.days !== undefined ? availability.days(q.from, q.days) : [{ start: q.from, end: q.to as number }];
+        const out = await availability.available({
+          variantId: q.variant,
+          ...(q.kind ? { kind: q.kind } : {}),
+          periods,
+          ...(q.location ? { locationId: q.location } : {}),
+          now: clock.now(),
+        });
+        return c.json(
+          {
+            variant_id: q.variant,
+            kind: out.kind,
+            location_id: q.location ?? null,
+            periods: out.periods.map((p) => ({
+              start: new Date(p.start).toISOString(),
+              end: new Date(p.end).toISOString(),
+              available: p.available,
+            })),
+          },
+          200,
+        );
+      },
+    );
+  }
+
+  if (!capacity) return;
+  const PoolParam = z.object({ id: ID });
+
+  app.openapi(
+    perms.declare(
+      "capacity:read",
+      createRoute({
+        method: "get",
+        path: "/admin/capacity/pools",
+        request: { query: z.object({ inventory_item_id: ID.optional(), kind: z.string().max(64).optional() }) },
+        responses: ok("Pools"),
+      }),
+    ),
+    async (c) => {
+      const q = c.req.valid("query");
+      return c.json(
+        {
+          pools: await capacity.pools({
+            ...(q.inventory_item_id ? { inventoryItemId: q.inventory_item_id } : {}),
+            ...(q.kind ? { kind: q.kind } : {}),
+          }),
+        },
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/pools",
+        request: jsonBody(
+          z.object({
+            kind: z.string().min(1).max(64),
+            inventory_item_id: ID.nullable().optional(),
+            location_id: ID.nullable().optional(),
+            bucket_minutes: z.number().int(),
+            max_span: z.number().int(),
+            initial_base: z.number().int(),
+          }),
+        ),
+        responses: ok("The new pool"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        await capacity.createPool(who(c), {
+          kind: b.kind,
+          inventoryItemId: b.inventory_item_id ?? null,
+          locationId: b.location_id ?? null,
+          bucketMinutes: b.bucket_minutes,
+          maxSpan: b.max_span,
+          initialBase: b.initial_base,
+        }),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:read",
+      createRoute({
+        method: "get",
+        path: "/admin/capacity/pools/{id}/availability",
+        request: { params: PoolParam, query: z.object({ from: z.coerce.number().int(), to: z.coerce.number().int() }) },
+        responses: ok("Capacity, held and free per bucket, with the active holds"),
+      }),
+    ),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      const { from, to } = c.req.valid("query");
+      const view = await capacity.poolAvailability(id, from, to);
+      return c.json({ ...(view as object), holds: await capacity.holdsOn(id, from, to) }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/pools/{id}/base-changes",
+        request: {
+          params: PoolParam,
+          ...jsonBody(
+            z.object({
+              delta: z.number().int(),
+              origin: z.enum(["physical", "scheduled"]),
+              date: z.string().optional(),
+              reason: z.string().min(1).max(500),
+            }),
+          ),
+        },
+        responses: ok("The base change and the bucket it takes effect from"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      if (b.origin === "scheduled" && !b.date) throw new KedgeError("BAD_REQUEST", "A scheduled change needs a date");
+      return c.json(
+        await capacity.changeBase(who(c), c.req.valid("param").id, {
+          delta: b.delta,
+          origin: b.origin,
+          ...(b.date ? { date: parseLocalDate(b.date) } : {}),
+          reason: b.reason,
+        }),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:write",
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/base-changes/{id}/cancel",
+        request: { params: PoolParam },
+        responses: ok("Canceled"),
+      }),
+    ),
+    async (c) => {
+      await capacity.cancelBaseChange(c.req.valid("param").id);
+      return c.json({ canceled: true }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/pools/{id}/adjustments",
+        request: {
+          params: PoolParam,
+          ...jsonBody(
+            z.object({ start: Instant, end: Instant, delta: z.number().int(), reason: z.string().min(1).max(500) }),
+          ),
+        },
+        responses: ok("The adjustment"),
+      }),
+    ),
+    async (c) => c.json(await capacity.adjust(who(c), c.req.valid("param").id, c.req.valid("json")), 200),
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:write",
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/adjustments/{id}/cancel",
+        request: { params: PoolParam },
+        responses: ok("Canceled"),
+      }),
+    ),
+    async (c) => {
+      await capacity.cancelAdjustment(c.req.valid("param").id);
+      return c.json({ canceled: true }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:write", own: true },
+      createRoute({
+        method: "put",
+        path: "/admin/capacity/pools/{id}/ceilings/{slot}",
+        request: {
+          params: z.object({ id: ID, slot: z.coerce.number().int().min(0) }),
+          ...jsonBody(z.object({ ceiling: z.number().int().nullable() })),
+        },
+        responses: ok("The weekly ceiling"),
+      }),
+    ),
+    async (c) => {
+      const { id, slot } = c.req.valid("param");
+      return c.json(
+        await capacity.setCeiling(who(c), id, { slotOfWeek: slot, ceiling: c.req.valid("json").ceiling }),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:write",
+      createRoute({
+        method: "put",
+        path: "/admin/capacity/buffers",
+        request: jsonBody(
+          z.object({
+            kind: z.string().min(1).max(64),
+            pool_kind: z.string().min(1).max(64),
+            before: z.number().int(),
+            after: z.number().int(),
+          }),
+        ),
+        responses: ok("The buffer"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      await capacity.setBuffer({ kind: b.kind, poolKind: b.pool_kind, before: b.before, after: b.after });
+      return c.json(b, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/pools/{id}/holds",
+        request: {
+          params: PoolParam,
+          ...jsonBody(
+            z.object({
+              kind: z.enum(["block", "maintenance", "import"]),
+              start: Instant,
+              end: Instant,
+              qty: z.number().int(),
+            }),
+          ),
+        },
+        responses: ok("The hold"),
+      }),
+    ),
+    async (c) => c.json(await capacity.hold(who(c), c.req.valid("param").id, c.req.valid("json")), 200),
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:write",
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/holds/{id}/release",
+        request: { params: PoolParam },
+        responses: ok("Released"),
+      }),
+    ),
+    async (c) => {
+      await capacity.releaseHold(c.req.valid("param").id);
+      return c.json({ released: true }, 200);
+    },
+  );
+  const Mapping = z.object({ mapping: z.string().min(1).max(64), key: z.string().min(1).max(255), pool_id: ID });
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/scope-mappings",
+        request: jsonBody(Mapping),
+        responses: ok("Mapped"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(await capacity.mapScope(who(c), { mapping: b.mapping, key: b.key, poolId: b.pool_id }), 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:write",
+      createRoute({
+        method: "delete",
+        path: "/admin/capacity/scope-mappings",
+        request: jsonBody(Mapping),
+        responses: ok("Unmapped"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      await capacity.unmapScope({ mapping: b.mapping, key: b.key, poolId: b.pool_id });
+      return c.json({ unmapped: true }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:convert", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/inventory-items/{id}/conversion",
+        request: {
+          params: PoolParam,
+          ...jsonBody(
+            z.object({
+              to: z.enum(["count", "dated", "none"]),
+              bucket_minutes: z.number().int().optional(),
+              max_span: z.number().int().optional(),
+              reason: z.string().min(1).max(500),
+            }),
+          ),
+        },
+        responses: ok("The converted item and its new pools"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        await capacity.convert(who(c), c.req.valid("param").id, {
+          to: b.to,
+          ...(b.bucket_minutes !== undefined ? { bucketMinutes: b.bucket_minutes } : {}),
+          ...(b.max_span !== undefined ? { maxSpan: b.max_span } : {}),
+          reason: b.reason,
+        }),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "capacity:write", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/capacity/pools/{id}/replace",
+        request: {
+          params: PoolParam,
+          ...jsonBody(
+            z.object({
+              bucket_minutes: z.number().int(),
+              max_span: z.number().int(),
+              reason: z.string().min(1).max(500),
+            }),
+          ),
+        },
+        responses: ok("The replacement pool"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        await capacity.replacePool(who(c), c.req.valid("param").id, {
+          bucketMinutes: b.bucket_minutes,
+          maxSpan: b.max_span,
+          reason: b.reason,
+        }),
+        200,
+      );
+    },
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:read",
+      createRoute({ method: "get", path: "/admin/capacity/shortages", responses: ok("Shortages now") }),
+    ),
+    async (c) => c.json(await capacity.shortages(), 200),
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:read",
+      createRoute({
+        method: "get",
+        path: "/admin/capacity/negative-bases",
+        responses: ok("Negative bases to reconcile"),
+      }),
+    ),
+    async (c) => c.json({ steps: await capacity.negativeBases() }, 200),
+  );
+  app.openapi(
+    perms.declare(
+      "capacity:write",
+      createRoute({
+        method: "post",
+        path: "/admin/orders/{id}/not-reopenable",
+        request: { params: z.object({ id: z.string().regex(ORDER_ID) }) },
+        responses: ok("The order can no longer be placed"),
+      }),
+    ),
+    async (c) => {
+      await capacity.markNotReopenable(c.req.valid("param").id);
+      return c.json({ reopenable: false }, 200);
+    },
+  );
+}