@porulle/core 0.1.0 → 0.6.0

package/src/interfaces/rest/audit-middleware.ts

@@ -0,0 +1,110 @@
+import type { MiddlewareHandler } from "hono";
+import type { Actor } from "../../auth/types.js";
+import { createHookContext } from "../../kernel/hooks/create-context.js";
+import type { ServiceContainer } from "../../kernel/hooks/types.js";
+import type { PluginDb } from "../../kernel/database/plugin-types.js";
+import type { Kernel } from "../../runtime/kernel-types.js";
+
+/**
+ * Hono context variables a handler can set to override the audit defaults.
+ * Add to your app's Env Variables to get type-safe `c.set(...)` calls.
+ */
+export interface AuditVars {
+  /** Override the derived event name. */
+  auditEvent: string;
+  /** Override the audit payload (defaults to `{}`). */
+  auditPayload: Record<string, unknown>;
+  /** Override the derived entity type. */
+  auditEntityType: string;
+  /** Override the derived entity id. */
+  auditEntityId: string;
+  /** Set to skip the audit write for this request entirely. */
+  auditSkip: boolean;
+}
+
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const UUID_RE_GLOBAL = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+const MUTATING = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+/** First non-`api` path segment, normalized (e.g. `/api/pos/customers/...` → `pos`). */
+function deriveEntityType(path: string): string {
+  const segments = path.split("/").filter(Boolean);
+  const start = segments[0] === "api" ? 1 : 0;
+  return segments[start] ?? "unknown";
+}
+
+/**
+ * Middleware that writes exactly one `commerce_audit_log` row per successful
+ * (2xx) state-changing request, so every porulle app gets audit-by-default
+ * without per-route boilerplate.
+ *
+ * ```ts
+ * app.use("*", auditMiddleware(kernel));
+ * ```
+ *
+ * Handlers may override the derived defaults via context variables
+ * (see {@link AuditVars}):
+ *
+ * ```ts
+ * c.set("auditEvent", "refund.manager_override");
+ * c.set("auditEntityType", "order");
+ * c.set("auditEntityId", orderId);
+ * c.set("auditSkip", true); // opt out
+ * ```
+ *
+ * Behavior:
+ * - GET/HEAD/OPTIONS and non-2xx responses never write a row.
+ * - entityId derivation: handler override → first UUID in the path →
+ *   `data.id` peeked from the JSON response body → `"n/a"`.
+ * - event default: `<verb>:<path-with-uuids-as-:id>`.
+ * - Writes are best-effort — a failed audit write never affects the response.
+ */
+export function auditMiddleware(kernel: Kernel): MiddlewareHandler {
+  return async (c, next) => {
+    await next();
+
+    const method = c.req.method.toUpperCase();
+    if (!MUTATING.has(method)) return;
+
+    const status = c.res.status;
+    if (status < 200 || status >= 300) return;
+
+    if (c.get("auditSkip") === true) return;
+
+    const path = c.req.path;
+    const event =
+      (c.get("auditEvent") as string | undefined) ??
+      `${method.toLowerCase()}:${path.replace(UUID_RE_GLOBAL, ":id")}`;
+    const entityType =
+      (c.get("auditEntityType") as string | undefined) ?? deriveEntityType(path);
+    const payload = (c.get("auditPayload") as Record<string, unknown> | undefined) ?? {};
+
+    let entityId =
+      (c.get("auditEntityId") as string | undefined) ?? path.match(UUID_RE)?.[0];
+    if (!entityId) {
+      // Peek the response body (a clone — the original stream is untouched).
+      try {
+        const body = (await c.res.clone().json()) as { data?: { id?: unknown } };
+        if (typeof body?.data?.id === "string") entityId = body.data.id;
+      } catch {
+        // non-JSON / empty body — fall through to "n/a"
+      }
+    }
+    entityId ??= "n/a";
+
+    try {
+      const requestId = c.get("requestId") as string | undefined;
+      const ctx = createHookContext({
+        actor: (c.get("actor") as Actor | null) ?? null,
+        ...(requestId ? { requestId } : {}),
+        logger: kernel.logger,
+        services: kernel.services as unknown as ServiceContainer,
+        database: { db: kernel.database.db as unknown as PluginDb },
+        origin: "rest",
+      });
+      await kernel.services.audit.record({ entityType, entityId, event, payload, ctx });
+    } catch {
+      // Best-effort: a transient audit-write failure must not bubble to the response.
+    }
+  };
+}

package/src/interfaces/rest/parse-json.ts

@@ -0,0 +1,81 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+
+/**
+ * A single field-level validation failure. Shape is stable across the API
+ * so clients can bind form errors without ad-hoc parsing.
+ */
+export interface ValidationIssue {
+  /** Dotted path to the offending field (e.g. "address.zip"). Empty for whole-body errors. */
+  path: string;
+  /** Human-readable message. */
+  message: string;
+  /** Machine code (zod issue code, or "invalid_json"). */
+  code: string;
+}
+
+/** The error envelope's optional `details` payload. */
+export interface ErrorDetails {
+  issues?: ValidationIssue[];
+  [key: string]: unknown;
+}
+
+/**
+ * Build the uniform error envelope `{ error: { code, message, details? } }`.
+ * `details` is omitted when not provided so existing responses are unchanged.
+ */
+export function err(
+  c: Context,
+  status: 400 | 401 | 403 | 404 | 409 | 422 | 500,
+  code: string,
+  message: string,
+  details?: ErrorDetails,
+): Response {
+  return c.json(
+    { error: { code, message, ...(details ? { details } : {}) } },
+    status,
+  );
+}
+
+/**
+ * Parse and validate a request body against a Zod schema.
+ *
+ * Returns the typed value on success, or a 422 `Response` (the uniform error
+ * envelope, with `details.issues[]` populated from the Zod failure) that the
+ * caller returns as-is. Replaces the unsafe `(await c.req.json()) as T` cast.
+ *
+ * ```ts
+ * const body = await parseJson(c, MyBodySchema);
+ * if (body instanceof Response) return body;
+ * // body is z.infer<typeof MyBodySchema>
+ * ```
+ */
+export async function parseJson<S extends z.ZodType>(
+  c: Context,
+  schema: S,
+): Promise<z.infer<S> | Response> {
+  let raw: unknown;
+  try {
+    raw = await c.req.json();
+  } catch {
+    return err(c, 422, "VALIDATION_FAILED", "Request body must be valid JSON.", {
+      issues: [{ path: "", message: "Request body must be valid JSON.", code: "invalid_json" }],
+    });
+  }
+
+  const result = schema.safeParse(raw);
+  if (!result.success) {
+    const issues: ValidationIssue[] = result.error.issues.map((issue) => ({
+      path: issue.path.map(String).join("."),
+      message: issue.message,
+      code: issue.code,
+    }));
+    const first = issues[0];
+    const message = first
+      ? `${first.path ? `${first.path}: ` : ""}${first.message}`
+      : "Validation failed.";
+    return err(c, 422, "VALIDATION_FAILED", message, { issues });
+  }
+
+  return result.data;
+}

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

@@ -35,6 +35,8 @@ import {
   updateEntityRoute,
   setEntityAttributesRoute,
   createCategoryRoute,
+  archiveCategoryRoute,
+  restoreCategoryRoute,
   updateCategoryRoute,
   createBrandRoute,
   updateBrandRoute,
@@ -280,7 +282,11 @@ export function catalogRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCategoriesRoute, async (c) => {
-    const result = await kernel.services.catalog.listCategories({ actor: c.get("actor"), tx: null, requestId: "" });
+    const includeArchived = c.req.query("includeArchived") === "true";
+    const result = await kernel.services.catalog.listCategories(
+      { actor: c.get("actor"), tx: null, requestId: "" },
+      { includeArchived },
+    );
     if (!result.ok)
       return c.json(
         mapErrorToResponse(result.error),
@@ -289,6 +295,20 @@ export function catalogRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(archiveCategoryRoute, async (c) => {
+    const result = await kernel.services.catalog.archiveCategory(c.req.param("categoryId"), 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(restoreCategoryRoute, async (c) => {
+    const result = await kernel.services.catalog.restoreCategory(c.req.param("categoryId"), 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(createCategoryRoute, async (c) => {
     const result = await kernel.services.catalog.createCategory(

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

@@ -2,12 +2,17 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import {
   listCustomersRoute,
+  createCustomerRoute,
   getCustomerRoute,
   updateCustomerRoute,
   getCustomerOrdersRoute,
   getCustomerAddressesRoute,
+  listInteractionsRoute,
+  createInteractionRoute,
+  updateInteractionRoute,
+  deleteInteractionRoute,
 } from "../schemas/customers.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination, requirePerm } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination, parseInclude, requirePerm } from "../utils.js";
 
 export function customerRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -37,6 +42,14 @@ export function customerRoutes(kernel: Kernel) {
     });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createCustomerRoute, async (c) => {
+    const body = c.req.valid("json");
+    const result = await kernel.services.customers.createWalkIn(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(getCustomerRoute, async (c) => {
     const { id } = c.req.valid("param");
@@ -58,7 +71,10 @@ export function customerRoutes(kernel: Kernel) {
     for (const [k, v] of Object.entries(body)) {
       if (v !== undefined) updates[k] = v;
     }
-    const result = await kernel.services.customers.update(id, updates, actor);
+    const replaceMetadata = c.req.query("metadataReplace") === "true";
+    const result = await kernel.services.customers.update(id, updates, actor, undefined, {
+      replaceMetadata,
+    });
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.json({ data: result.value });
   });
@@ -69,13 +85,22 @@ export function customerRoutes(kernel: Kernel) {
     const actor = c.get("actor");
     const { page, limit } = parsePagination(c.req.query());
     const status = c.req.query("status") || undefined;
+    const includeTotals = parseInclude(c.req.query("include")).has("totals");
 
     const result = await kernel.services.orders.listByCustomer(
       id,
-      { page, limit, ...(status ? { status } : {}) },
+      { page, limit, ...(status ? { status } : {}), ...(includeTotals ? { includeTotals: true } : {}) },
       actor,
     );
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    if (includeTotals) {
+      // Wrapped shape: { data: { items, totals } } (+ pagination meta).
+      return c.json({
+        data: { items: result.value.items, totals: result.value.totals },
+        meta: { pagination: result.value.pagination },
+      });
+    }
+    // Default (back-compat): flat array.
     return c.json({ data: result.value.items, meta: { pagination: result.value.pagination } });
   });
 
@@ -96,5 +121,41 @@ export function customerRoutes(kernel: Kernel) {
     return c.json({ data: addressResult.value });
   });
 
+  // ─── Customer interactions (#3) ──────────────────────────────────────────
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listInteractionsRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const result = await kernel.services.customers.listInteractions(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(createInteractionRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const result = await kernel.services.customers.createInteraction(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(updateInteractionRoute, async (c) => {
+    const { id, iid } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const result = await kernel.services.customers.updateInteraction(id, iid, 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(deleteInteractionRoute, async (c) => {
+    const { id, iid } = c.req.valid("param");
+    const result = await kernel.services.customers.deleteInteraction(id, iid, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: { deleted: true } });
+  });
+
   return router;
 }

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

@@ -51,9 +51,11 @@ export function inventoryRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(inventoryAdjustRoute, async (c) => {
     const body = c.req.valid("json");
-    const result = await kernel.services.inventory.adjust(body, c.get("actor"));
+    const result = await kernel.services.inventory.adjustDetailed(body, c.get("actor"));
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
-    return c.json({ data: result.value });
+    const { level, before, after, delta, movementId } = result.value;
+    // Additive: level fields (back-compat) plus before/after/delta/movementId.
+    return c.json({ data: { ...level, before, after, delta, movementId } });
   });
 
   // @ts-expect-error -- openapi handler union return type

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

@@ -11,6 +11,13 @@ export function mediaRoutes(kernel: Kernel) {
   router.use("/upload", requirePerm("media:write"));
 
   router.post("/upload", async (c) => {
+    // No storage configured (the default no-op adapter) → media is disabled.
+    if (kernel.config.storage?.providerId === "noop") {
+      return c.json({
+        error: { code: "storage_not_supported", message: "Media storage is not configured." },
+      }, 501);
+    }
+
     const body = await c.req.parseBody();
     const file = body.file as File;
 

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, getOrderRoute, getOrderFulfillmentsRoute } from "../schemas/orders.js";
+import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute } from "../schemas/orders.js";
 import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
 
 export function orderRoutes(kernel: Kernel) {
@@ -28,6 +28,26 @@ export function orderRoutes(kernel: Kernel) {
     });
   });
 
+  // Registered before getOrderRoute so "/lookup" isn't matched as an idOrNumber.
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(orderLookupRoute, async (c) => {
+    const q = c.req.query("q") ?? "";
+    const fromRaw = c.req.query("from");
+    const toRaw = c.req.query("to");
+    const opts: { from?: Date; to?: Date } = {};
+    if (fromRaw) {
+      const d = new Date(fromRaw);
+      if (!Number.isNaN(d.getTime())) opts.from = d;
+    }
+    if (toRaw) {
+      const d = new Date(toRaw);
+      if (!Number.isNaN(d.getTime())) opts.to = d;
+    }
+    const result = await kernel.services.orders.lookup(q, opts, 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(getOrderRoute, async (c) => {
     const idOrNumber = c.req.param("idOrNumber");

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

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { rateLimiter } from "hono-rate-limiter";
 import type { Kernel } from "../../../runtime/kernel.js";
-import { createPromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listPromotionsRoute } from "../schemas/promotions.js";
+import { createPromotionRoute, updatePromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listPromotionsRoute } from "../schemas/promotions.js";
 import type { PromotionStatusFilter } from "../../../modules/promotions/service.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
 import { resolveOrgId } from "../../../auth/org.js";
@@ -77,6 +77,27 @@ export function promotionRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // Guard inline (not via router.use("/:id")) because a "/:id" middleware
+  // would also match single-segment routes like POST /validate.
+  router.use("/:id", async (c, next) => {
+    if (c.req.method !== "PATCH") return next();
+    return requirePerm("promotions:manage")(c, next);
+  });
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (200 | 400 | 404 | 422). The route definition
+  // documents the contract; the handler returns dynamic status.
+  router.openapi(updatePromotionRoute, async (c) => {
+    const body = c.req.valid("json");
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+    const result = await kernel.services.promotions.update(orgId, c.req.param("id"), body, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
   router.use("/:id/deactivate", requirePerm("promotions:manage"));
 
   // @ts-expect-error -- openapi() enforces strict response typing but our handler

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

@@ -108,7 +108,12 @@ export const listCategoriesRoute = createRoute({
   method: "get",
   path: "/categories",
   tags: ["Catalog"],
-  summary: "List all categories",
+  summary: "List categories (active by default)",
+  request: {
+    query: z.object({
+      includeArchived: z.string().optional().openapi({ example: "true" }),
+    }),
+  },
   responses: {
     200: { content: { "application/json": { schema: DataResponse } }, description: "Success" },
   },
@@ -342,6 +347,30 @@ export const updateCategoryRoute = createRoute({
   },
 });
 
+export const archiveCategoryRoute = createRoute({
+  method: "post",
+  path: "/categories/{categoryId}/archive",
+  tags: ["Catalog"],
+  summary: "Archive a category (soft delete)",
+  request: { params: CategoryIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Archived" },
+    ...errorResponses,
+  },
+});
+
+export const restoreCategoryRoute = createRoute({
+  method: "post",
+  path: "/categories/{categoryId}/restore",
+  tags: ["Catalog"],
+  summary: "Restore an archived category",
+  request: { params: CategoryIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Restored" },
+    ...errorResponses,
+  },
+});
+
 export const createBrandRoute = createRoute({
   method: "post",
   path: "/brands",

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

@@ -1,6 +1,34 @@
 import { z, createRoute } from "@hono/zod-openapi";
 import { errorResponses } from "./shared.js";
 
+export const CreateCustomerBodySchema = z.object({
+  // Optional: omit for walk-in / POS customers who never log in. A synthetic
+  // anonymous_<uuid> id is generated and metadata.walkIn is set.
+  userId: z.string().optional().openapi({ example: "user_123" }),
+  firstName: z.string().optional().openapi({ example: "Nimali" }),
+  lastName: z.string().optional().openapi({ example: "Perera" }),
+  phone: z.string().optional().openapi({ example: "+94 77 412 6601" }),
+  email: z.string().optional().openapi({ example: "nimali@example.com" }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateCustomerBody");
+
+export const createCustomerRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Customers"],
+  summary: "Create a customer (supports walk-in / userId-less)",
+  request: {
+    body: { content: { "application/json": { schema: CreateCustomerBodySchema } }, required: true },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+      description: "Customer created.",
+    },
+    ...errorResponses,
+  },
+});
+
 export const listCustomersRoute = createRoute({
   method: "get",
   path: "/",
@@ -153,3 +181,74 @@ export const getCustomerAddressesRoute = createRoute({
     ...errorResponses,
   },
 });
+
+// ─── Customer interactions (#3) ──────────────────────────────────────────────
+
+export const InteractionKindEnum = z.enum([
+  "visit", "call", "inquiry", "fitting", "follow_up", "message",
+]);
+
+export const CreateInteractionBodySchema = z.object({
+  kind: InteractionKindEnum.openapi({ example: "visit" }),
+  notes: z.string().min(1).openapi({ example: "Asked about the navy blazer in M." }),
+  relatedEntityId: z.string().uuid().nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateInteractionBody");
+
+export const UpdateInteractionBodySchema = CreateInteractionBodySchema.partial().openapi("UpdateInteractionBody");
+
+const InteractionDataResponse = z.object({ data: z.record(z.string(), z.unknown()) });
+
+export const listInteractionsRoute = createRoute({
+  method: "get",
+  path: "/{id}/interactions",
+  tags: ["Customers"],
+  summary: "List a customer's interactions",
+  request: { params: z.object({ id: z.string().uuid() }) },
+  responses: {
+    200: { content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } }, description: "Interactions" },
+    ...errorResponses,
+  },
+});
+
+export const createInteractionRoute = createRoute({
+  method: "post",
+  path: "/{id}/interactions",
+  tags: ["Customers"],
+  summary: "Log a customer interaction",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+    body: { content: { "application/json": { schema: CreateInteractionBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: InteractionDataResponse } }, description: "Interaction logged" },
+    ...errorResponses,
+  },
+});
+
+export const updateInteractionRoute = createRoute({
+  method: "patch",
+  path: "/{id}/interactions/{iid}",
+  tags: ["Customers"],
+  summary: "Edit a customer interaction",
+  request: {
+    params: z.object({ id: z.string().uuid(), iid: z.string().uuid() }),
+    body: { content: { "application/json": { schema: UpdateInteractionBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: InteractionDataResponse } }, description: "Interaction updated" },
+    ...errorResponses,
+  },
+});
+
+export const deleteInteractionRoute = createRoute({
+  method: "delete",
+  path: "/{id}/interactions/{iid}",
+  tags: ["Customers"],
+  summary: "Delete a customer interaction",
+  request: { params: z.object({ id: z.string().uuid(), iid: z.string().uuid() }) },
+  responses: {
+    200: { content: { "application/json": { schema: z.object({ data: z.object({ deleted: z.literal(true) }) }) } }, description: "Deleted" },
+    ...errorResponses,
+  },
+});

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

@@ -44,6 +44,27 @@ export const listOrdersRoute = createRoute({
   },
 });
 
+export const orderLookupRoute = createRoute({
+  method: "get",
+  path: "/lookup",
+  tags: ["Orders"],
+  summary: "Fuzzy order lookup (receipt-less return / support)",
+  description: "Find orders by order number, customer email/name/phone, or walk-in label. Minimum query length is 3 characters.",
+  request: {
+    query: z.object({
+      q: z.string().optional().openapi({ example: "Perera" }),
+      from: z.string().optional().openapi({ example: "2026-01-01" }),
+      to: z.string().optional().openapi({ example: "2026-12-31" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.object({ items: z.array(z.record(z.string(), z.unknown())), hint: z.string().optional() }) }) } },
+      description: "Lookup results",
+    },
+  },
+});
+
 export const getOrderRoute = createRoute({
   method: "get",
   path: "/{idOrNumber}",