@porulle/core 0.7.0 → 0.9.0

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}",

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

@@ -477,3 +477,56 @@ export const generateVariantsRoute = createRoute({
     ...errorResponses,
   },
 });
+
+// ── One-call variant creation (issue #50) ───────────────────────────────────
+
+export const QuickVariantBodySchema = z.object({
+  options: z.record(z.string().min(1), z.string().min(1)).openapi({
+    example: { color: "Red", size: "M" },
+    description: "Axis name → value. Option types/values are upserted inline.",
+  }),
+  sku: z.string().min(1).optional(),
+  barcode: z.string().min(1).optional(),
+}).openapi("QuickVariantRequest");
+
+export const BulkVariantsBodySchema = z.object({
+  axes: z.array(z.object({
+    name: z.string().min(1),
+    values: z.array(z.string().min(1)).min(1),
+  })).openapi({
+    example: [{ name: "color", values: ["Red", "Blue"] }, { name: "size", values: ["S", "M"] }],
+    description: "Matrix axes; an empty array creates one option-less variant.",
+  }),
+  skuPrefix: z.string().min(1).optional(),
+}).openapi("BulkVariantsRequest");
+
+export const quickVariantRoute = createRoute({
+  method: "post",
+  path: "/entities/{id}/variants/quick",
+  tags: ["Catalog"],
+  summary: "Create one sellable variant in a single call (upserts axes, seeds inventory)",
+  request: {
+    params: EntityIdParam,
+    body: { content: { "application/json": { schema: QuickVariantBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Variant created and inventory seeded." },
+    200: { content: { "application/json": { schema: DataResponse } }, description: "The combination already existed; the existing variant is returned." },
+    ...errorResponses,
+  },
+});
+
+export const bulkVariantsRoute = createRoute({
+  method: "post",
+  path: "/entities/{id}/variants/bulk",
+  tags: ["Catalog"],
+  summary: "Create a variant matrix in a single call (upserts axes, seeds inventory, skips existing)",
+  request: {
+    params: EntityIdParam,
+    body: { content: { "application/json": { schema: BulkVariantsBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Variants created (existing combinations skipped)." },
+    ...errorResponses,
+  },
+});

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

@@ -6,6 +6,10 @@ import { ErrorSchema, errorResponses } from "./shared.js";
 export const CheckoutBodySchema = z.object({
   cartId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
   paymentMethodId: z.string().openapi({ example: "pm_card_visa" }),
+  idempotencyKey: z.string().min(8).max(255).optional().openapi({
+    example: "checkout-8f14e45f-1738312200",
+    description: "Client-supplied retry key. A re-submitted checkout with the same key returns the already-created order without re-authorizing payment (safe offline-queue replay).",
+  }),
   customerId: z.string().optional().openapi({ example: "customer-uuid-or-user-id" }),
   customerGroupIds: z.array(z.string()).optional(),
   currency: z.string().length(3).optional().openapi({ example: "USD" }),

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

@@ -0,0 +1,72 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+const IdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+export const EmailInvoiceBodySchema = z.object({
+  to: z.email().openapi({ example: "customer@example.com" }),
+}).openapi("EmailInvoiceRequest");
+
+const DataResponse = z.object({ data: z.any() }).openapi("DocumentActionResponse");
+
+export const invoicePdfRoute = createRoute({
+  method: "get",
+  path: "/{id}/invoice.pdf",
+  tags: ["Documents"],
+  summary: "Render the order's invoice as PDF (issues a fiscal invoice number on first render)",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "application/pdf": { schema: z.any().openapi({ type: "string", format: "binary" }) } },
+      description: "The rendered PDF invoice.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const invoiceHtmlRoute = createRoute({
+  method: "get",
+  path: "/{id}/invoice.html",
+  tags: ["Documents"],
+  summary: "Render the order's invoice as HTML",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "text/html": { schema: z.string() } },
+      description: "The rendered HTML invoice.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const receiptHtmlRoute = createRoute({
+  method: "get",
+  path: "/{id}/receipt.html",
+  tags: ["Documents"],
+  summary: "Render the order's receipt as HTML",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "text/html": { schema: z.string() } },
+      description: "The rendered HTML receipt.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const emailInvoiceRoute = createRoute({
+  method: "post",
+  path: "/{id}/invoice/email",
+  tags: ["Documents"],
+  summary: "Email the order's invoice via the configured email adapter",
+  request: {
+    params: IdParam,
+    body: { content: { "application/json": { schema: EmailInvoiceBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Invoice emailed." },
+    ...errorResponses,
+  },
+});