@porulle/core 0.7.0 → 0.8.0

package/src/interfaces/rest/routes/orders.ts

@@ -1,6 +1,6 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
-import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute, createOrderRoute, refundOrderRoute, captureOrderRoute } from "../schemas/orders.js";
+import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute, createOrderRoute, refundOrderRoute, captureOrderRoute, createOrderFulfillmentRoute, addOrderLineItemRoute, updateOrderLineItemRoute, removeOrderLineItemRoute, refundOrderLinesRoute, undoOrderRefundRoute, listOrderRefundsRoute, refundCapStatusRoute, createOrderNoteRoute, listOrderNotesRoute, deleteOrderNoteRoute, orderTimelineRoute } from "../schemas/orders.js";
 import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
 import type { CreateOrderInput } from "../../../modules/orders/service.js";
 
@@ -82,6 +82,80 @@ export function orderRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // ── Notes + activity timeline (issue #56) ──────────────────────────
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createOrderNoteRoute, async (c) => {
+    const body = c.req.valid("json") as { body: string; pinned?: boolean };
+    const result = await kernel.services.orders.addNote(c.req.param("id"), body, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listOrderNotesRoute, async (c) => {
+    const result = await kernel.services.orders.listNotes(c.req.param("id"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteOrderNoteRoute, async (c) => {
+    const result = await kernel.services.orders.deleteNote(
+      c.req.param("id"),
+      c.req.param("noteId"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(orderTimelineRoute, async (c) => {
+    const result = await kernel.services.orders.timeline(c.req.param("id"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // ── Line-level refunds (issue #52) ─────────────────────────────────
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(refundCapStatusRoute, async (c) => {
+    const result = await kernel.services.orders.refundCapStatus(c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(refundOrderLinesRoute, async (c) => {
+    const body = c.req.valid("json") as { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string };
+    const result = await kernel.services.orders.refundLines(
+      c.req.param("id"),
+      body,
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(undoOrderRefundRoute, async (c) => {
+    const result = await kernel.services.orders.undoRefund(
+      c.req.param("id"),
+      c.req.param("refundId"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listOrderRefundsRoute, async (c) => {
+    const result = await kernel.services.orders.listRefunds(c.req.param("id"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(captureOrderRoute, async (c) => {
     const body = c.req.valid("json") as { amount?: number } | undefined;
@@ -94,6 +168,42 @@ export function orderRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(addOrderLineItemRoute, async (c) => {
+    const body = c.req.valid("json");
+    const result = await kernel.services.orders.addLineItem(
+      c.req.param("id"),
+      body,
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateOrderLineItemRoute, async (c) => {
+    const body = c.req.valid("json");
+    const result = await kernel.services.orders.updateOrderLineItem(
+      c.req.param("id"),
+      c.req.param("lineItemId"),
+      body,
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(removeOrderLineItemRoute, async (c) => {
+    const result = await kernel.services.orders.removeLineItem(
+      c.req.param("id"),
+      c.req.param("lineItemId"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
   // @ts-expect-error -- openapi() enforces strict response typing but our handler
   // returns union responses (200 | 400 | 404). The route definition documents the
   // contract; the handler returns dynamic status.
@@ -112,6 +222,32 @@ export function orderRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createOrderFulfillmentRoute, async (c) => {
+    const actor = c.get("actor");
+    const orderId = c.req.param("id");
+
+    // Verify the order exists and the actor has access before recording
+    const orderResult = await kernel.services.orders.getById(orderId, actor);
+    if (!orderResult.ok) return c.json(mapErrorToResponse(orderResult.error), mapErrorToStatus(orderResult.error));
+
+    const body = c.req.valid("json") as {
+      lineItems: Array<{ orderLineItemId: string; quantity: number }>;
+      carrier?: string;
+      trackingNumber?: string;
+      trackingUrl?: string;
+      type?: string;
+      status?: string;
+      metadata?: Record<string, unknown>;
+    };
+    const result = await kernel.services.fulfillment.createFulfillment(
+      { ...body, orderId: orderResult.value.id },
+      actor,
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getOrderFulfillmentsRoute, async (c) => {
     const orderId = c.req.param("id");

package/src/interfaces/rest/routes/pricing.ts

@@ -4,7 +4,7 @@ import { CommerceValidationError } from "../../../kernel/errors.js";
 import type { DrizzleDatabase } from "../../../kernel/database/drizzle-db.js";
 import { CatalogRepository } from "../../../modules/catalog/repository/index.js";
 import type { Kernel } from "../../../runtime/kernel.js";
-import { setBasePriceRoute, createModifierRoute, listPricesRoute } from "../schemas/pricing.js";
+import { setBasePriceRoute, createModifierRoute, listPricesRoute, listModifiersRoute, updateModifierRoute, deleteModifierRoute } from "../schemas/pricing.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
 
 export function pricingRoutes(kernel: Kernel) {
@@ -45,6 +45,49 @@ export function pricingRoutes(kernel: Kernel) {
   });
 
   router.use("/modifiers", requirePerm("pricing:manage"));
+  router.use("/modifiers/:id", requirePerm("pricing:manage"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listModifiersRoute, async (c) => {
+    const actor = c.get("actor");
+    const entityId = c.req.query("entityId");
+    const currency = c.req.query("currency");
+    const active = c.req.query("active");
+
+    const result = await kernel.services.pricing.listModifiers({
+      ...(entityId !== undefined ? { entityId } : {}),
+      ...(currency !== undefined ? { currency } : {}),
+      ...(active === "true" ? { active: true } : {}),
+    }, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateModifierRoute, async (c) => {
+    const actor = c.get("actor");
+    const result = await kernel.services.pricing.updateModifier(
+      c.req.param("id"),
+      c.req.valid("json"),
+      actor,
+    );
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteModifierRoute, async (c) => {
+    const actor = c.get("actor");
+    const result = await kernel.services.pricing.deleteModifier(c.req.param("id"), actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
 
   // @ts-expect-error -- openapi() enforces strict response typing but our handler
   // returns union responses (201 | 400 | 422). The route definition documents the

package/src/interfaces/rest/routes/settings.ts

@@ -0,0 +1,61 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import {
+  KNOWN_GROUP_SCHEMAS,
+  getAllSettingsRoute,
+  getSettingsGroupRoute,
+  patchSettingsGroupRoute,
+} from "../schemas/settings.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+export function settingsRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/", requirePerm("settings:manage"));
+  router.use("/:group", requirePerm("settings:manage"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(getAllSettingsRoute, async (c) => {
+    const result = await kernel.services.settings.getAll(c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(getSettingsGroupRoute, async (c) => {
+    const result = await kernel.services.settings.getGroup(c.req.param("group"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(patchSettingsGroupRoute, async (c) => {
+    const group = c.req.param("group");
+    const body = c.req.valid("json");
+
+    // Known groups get typed validation; unknown groups accept any object.
+    const groupSchema = KNOWN_GROUP_SCHEMAS[group];
+    if (groupSchema) {
+      const parsed = groupSchema.safeParse(body);
+      if (!parsed.success) {
+        const isProd = process.env.NODE_ENV === "production";
+        return c.json({
+          error: {
+            code: "VALIDATION_FAILED",
+            message: isProd
+              ? "Invalid input."
+              : parsed.error.issues
+                  .map((i) => `${i.path.join(".")}: ${i.message}`)
+                  .join("; "),
+          },
+        }, 422);
+      }
+    }
+
+    const result = await kernel.services.settings.updateGroup(group, body, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/shipping.ts

@@ -0,0 +1,92 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import {
+  createShippingZoneRoute,
+  listShippingZonesRoute,
+  updateShippingZoneRoute,
+  deleteShippingZoneRoute,
+  createShippingRateRoute,
+  listShippingRatesRoute,
+  updateShippingRateRoute,
+  deleteShippingRateRoute,
+} from "../schemas/shipping.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+export function shippingRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/zones", requirePerm("shipping:manage"));
+  router.use("/zones/:id", requirePerm("shipping:manage"));
+  router.use("/rates", requirePerm("shipping:manage"));
+  router.use("/rates/:id", requirePerm("shipping:manage"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createShippingZoneRoute, async (c) => {
+    const result = await kernel.services.shipping.createZone(c.req.valid("json"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listShippingZonesRoute, async (c) => {
+    const result = await kernel.services.shipping.listZones(c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateShippingZoneRoute, async (c) => {
+    const result = await kernel.services.shipping.updateZone(
+      c.req.param("id"),
+      c.req.valid("json"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteShippingZoneRoute, async (c) => {
+    const result = await kernel.services.shipping.deleteZone(c.req.param("id"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createShippingRateRoute, async (c) => {
+    const result = await kernel.services.shipping.createRate(c.req.valid("json"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listShippingRatesRoute, async (c) => {
+    const zoneId = c.req.query("zoneId");
+    const result = await kernel.services.shipping.listRates(
+      zoneId !== undefined ? { zoneId } : undefined,
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateShippingRateRoute, async (c) => {
+    const result = await kernel.services.shipping.updateRate(
+      c.req.param("id"),
+      c.req.valid("json"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteShippingRateRoute, async (c) => {
+    const result = await kernel.services.shipping.deleteRate(c.req.param("id"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/tax.ts

@@ -0,0 +1,90 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import {
+  createTaxRateRoute,
+  listTaxRatesRoute,
+  updateTaxRateRoute,
+  deleteTaxRateRoute,
+  createTaxClassRoute,
+  listTaxClassesRoute,
+  updateTaxClassRoute,
+  deleteTaxClassRoute,
+} from "../schemas/tax.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+export function taxRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/rates", requirePerm("tax:manage"));
+  router.use("/rates/:id", requirePerm("tax:manage"));
+  router.use("/classes", requirePerm("tax:manage"));
+  router.use("/classes/:id", requirePerm("tax:manage"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createTaxRateRoute, async (c) => {
+    const result = await kernel.services.tax.createTaxRate(c.req.valid("json"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listTaxRatesRoute, async (c) => {
+    const result = await kernel.services.tax.listTaxRates(c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateTaxRateRoute, async (c) => {
+    const result = await kernel.services.tax.updateTaxRate(
+      c.req.param("id"),
+      c.req.valid("json"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteTaxRateRoute, async (c) => {
+    const result = await kernel.services.tax.deleteTaxRate(c.req.param("id"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // ── Product tax classes (issue #57) ───────────────────────────────
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createTaxClassRoute, async (c) => {
+    const result = await kernel.services.tax.createTaxClass(c.req.valid("json"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listTaxClassesRoute, async (c) => {
+    const result = await kernel.services.tax.listTaxClasses(c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateTaxClassRoute, async (c) => {
+    const result = await kernel.services.tax.updateTaxClass(
+      c.req.param("id"),
+      c.req.valid("json"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteTaxClassRoute, async (c) => {
+    const result = await kernel.services.tax.deleteTaxClass(c.req.param("id"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}

package/src/interfaces/rest/schemas/admin-staff.ts

@@ -0,0 +1,110 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+export const CreateStaffBodySchema = z.object({
+  userId: z.string().min(1).openapi({ example: "user_abc123", description: "Better Auth user id of an existing user" }),
+  role: z.string().min(1).openapi({ example: "manager" }),
+}).openapi("CreateStaffRequest");
+
+export const InviteStaffBodySchema = z.object({
+  email: z.email().openapi({ example: "newhire@example.com" }),
+  role: z.string().min(1).openapi({ example: "manager" }),
+}).openapi("InviteStaffRequest");
+
+export const UpdateStaffRoleBodySchema = z.object({
+  role: z.string().min(1).openapi({ example: "admin" }),
+}).openapi("UpdateStaffRoleRequest");
+
+const MemberIdParam = z.object({
+  id: z.string().min(1).openapi({ example: "mem_abc123" }),
+});
+
+const DataResponse = z.object({ data: z.any() }).openapi("AdminStaffResponse");
+
+export const listStaffRoute = createRoute({
+  method: "get",
+  path: "/staff",
+  tags: ["Admin"],
+  summary: "List staff members with their roles",
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Staff members" },
+    ...errorResponses,
+  },
+});
+
+export const createStaffRoute = createRoute({
+  method: "post",
+  path: "/staff",
+  tags: ["Admin"],
+  summary: "Add an existing user as a staff member with a role",
+  request: {
+    body: { content: { "application/json": { schema: CreateStaffBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Staff member created." },
+    ...errorResponses,
+  },
+});
+
+export const inviteStaffRoute = createRoute({
+  method: "post",
+  path: "/staff/invitations",
+  tags: ["Admin"],
+  summary: "Invite a teammate by email with a role",
+  request: {
+    body: { content: { "application/json": { schema: InviteStaffBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Invitation created." },
+    ...errorResponses,
+  },
+});
+
+export const listStaffInvitationsRoute = createRoute({
+  method: "get",
+  path: "/staff/invitations",
+  tags: ["Admin"],
+  summary: "List pending staff invitations",
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Invitations" },
+    ...errorResponses,
+  },
+});
+
+export const listStaffRolesRoute = createRoute({
+  method: "get",
+  path: "/staff/roles",
+  tags: ["Admin"],
+  summary: "Role → permission mapping staff roles resolve to",
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Roles" },
+    ...errorResponses,
+  },
+});
+
+export const updateStaffRoleRoute = createRoute({
+  method: "patch",
+  path: "/staff/{id}",
+  tags: ["Admin"],
+  summary: "Change a staff member's role",
+  request: {
+    params: MemberIdParam,
+    body: { content: { "application/json": { schema: UpdateStaffRoleBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Role updated." },
+    ...errorResponses,
+  },
+});
+
+export const revokeStaffRoute = createRoute({
+  method: "delete",
+  path: "/staff/{id}",
+  tags: ["Admin"],
+  summary: "Revoke a staff member's membership",
+  request: { params: MemberIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Membership revoked." },
+    ...errorResponses,
+  },
+});

package/src/interfaces/rest/schemas/analytics.ts

@@ -0,0 +1,39 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+const ReportParamsSchema = z.object({
+  name: z.string().regex(/^[a-z][a-z0-9-]*$/).openapi({ example: "daily-journal" }),
+});
+
+const ReportQuerySchema = z.object({
+  date: z.string().regex(DATE).optional().openapi({ description: "Local calendar date (single-day reports)." }),
+  from: z.string().regex(DATE).optional().openapi({ description: "Local range start, inclusive." }),
+  to: z.string().regex(DATE).optional().openapi({ description: "Local range end, inclusive." }),
+});
+
+const DataResponse = z.object({ data: z.any() }).openapi("AnalyticsReportResponse");
+
+export const listReportsRoute = createRoute({
+  method: "get",
+  path: "/reports",
+  tags: ["Analytics"],
+  summary: "List the canned retail reports",
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Available reports." },
+    ...errorResponses,
+  },
+});
+
+export const getReportRoute = createRoute({
+  method: "get",
+  path: "/reports/{name}",
+  tags: ["Analytics"],
+  summary: "Run a canned retail report (calendar math in the store's timezone)",
+  request: { params: ReportParamsSchema, query: ReportQuerySchema },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Report result." },
+    ...errorResponses,
+  },
+});

package/src/interfaces/rest/schemas/carts.ts

@@ -26,6 +26,46 @@ const CartItemParams = z.object({
 
 // ─── Route Definitions ──────────────────────────────────────────────────────
 
+export const listCartsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Carts"],
+  summary: "List carts (admin) — abandoned-checkout recovery filters",
+  description: "Lists carts with status/olderThan/hasCustomer filters and pagination. Includes shopper identity (cart email + linked customer email). Requires cart:manage.",
+  request: {
+    query: z.object({
+      status: z.enum(["active", "checking_out", "merged", "checked_out", "abandoned"]).optional(),
+      olderThan: z.string().optional().openapi({ example: "2026-06-30T00:00:00Z", description: "Only carts not updated since this ISO timestamp" }),
+      hasCustomer: z.string().optional().openapi({ example: "true" }),
+      page: z.string().optional(),
+      limit: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: CartResponse } },
+      description: "Carts",
+    },
+    ...errorResponses,
+  },
+});
+
+export const recoverCartRoute = createRoute({
+  method: "post",
+  path: "/{id}/recover",
+  tags: ["Carts"],
+  summary: "Recover an abandoned cart (admin)",
+  description: "Reactivates the cart, extends its expiry, and returns a resume secret suitable for a recovery email's resume/checkout link. Fires the cart.afterRecover hook. Requires cart:manage.",
+  request: { params: CartIdParam },
+  responses: {
+    200: {
+      content: { "application/json": { schema: CartResponse } },
+      description: "Recovery payload (cartId, secret, expiresAt, shopper identity).",
+    },
+    ...errorResponses,
+  },
+});
+
 export const getCartRoute = createRoute({
   method: "get",
   path: "/{id}",