@porulle/core 0.7.0 → 0.8.0

package/src/hooks/checkout.ts

@@ -359,28 +359,40 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
       currency: string;
       customerId?: string;
       shippingAmount: number;
+      orderDiscount?: number;
       fromAddress?: ShippingAddress;
       toAddress?: ShippingAddress;
       lineItems: Array<{
         id: string;
         entityId: string;
+        variantId?: string;
         description: string;
         quantity: number;
         unitPrice: number;
         discount?: number;
       }>;
-    }): Promise<
-      | { ok: true; value: { amountToCollect: number } }
+    }, orgId?: string): Promise<
+      | { ok: true; value: { amountToCollect: number; lines?: Array<{ id: string; taxClass: string | null; taxAmount: number }> } }
       | { ok: false; error: Error }
     >;
   };
 
+  // Cart-level discount not already attributed to lines — pro-rated across
+  // lines before class-based tax (issue #57).
+  const lineDiscounts = data.lineItems.reduce(
+    (sum, lineItem) => sum + (lineItem.discountAmount ?? 0),
+    0,
+  );
+  const orderDiscount = Math.max(0, data.discountTotal - lineDiscounts);
+
   const calculated = await tax.calculate({
     currency: data.currency,
     shippingAmount: data.shippingTotal,
+    orderDiscount,
     lineItems: data.lineItems.map((lineItem) => ({
       id: lineItem.id ?? `${lineItem.entityId}:${lineItem.variantId ?? "_"}`,
       entityId: lineItem.entityId,
+      ...(lineItem.variantId !== undefined ? { variantId: lineItem.variantId } : {}),
       description: lineItem.title ?? lineItem.entityId,
       quantity: lineItem.quantity,
       unitPrice: lineItem.resolvedUnitPrice ?? 0,
@@ -392,7 +404,7 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
     ...(data.shippingAddress !== undefined
       ? { toAddress: data.shippingAddress }
       : {}),
-  });
+  }, resolveOrgId(context.actor ?? null));
 
   if (!calculated.ok) {
     throw new CommerceValidationError(
@@ -400,6 +412,14 @@ export const calculateTax: BeforeHook<CheckoutData> = async ({
     );
   }
 
+  // Product tax classes return per-line results — store them so the order's
+  // line items carry taxAmount (issue #57). Lines arrive in request order.
+  if (calculated.value.lines) {
+    for (const [i, line] of calculated.value.lines.entries()) {
+      if (data.lineItems[i]) data.lineItems[i]!.taxAmount = line.taxAmount;
+    }
+  }
+
   data.taxTotal = Math.max(0, Math.round(calculated.value.amountToCollect));
   recalculateTotals(data);
   return data;
@@ -421,6 +441,7 @@ export const calculateShipping: BeforeHook<CheckoutData> = async ({
       currency: string;
       address?: ShippingAddress;
       isFreeShipping?: boolean;
+      orgId?: string;
     }): Promise<
       | {
           ok: true;
@@ -441,6 +462,7 @@ export const calculateShipping: BeforeHook<CheckoutData> = async ({
     })),
     subtotalAfterDiscount: Math.max(0, data.subtotal - data.discountTotal),
     currency: data.currency,
+    orgId: resolveOrgId(context.actor ?? null),
     ...(data.shippingAddress !== undefined
       ? { address: data.shippingAddress }
       : {}),

package/src/index.ts

@@ -15,6 +15,7 @@ export type {
 } from "./kernel/plugin/manifest.js";
 
 export { router } from "./interfaces/rest/router.js";
+export { requirePerm } from "./interfaces/rest/utils.js";
 export { webhookRouter, type WebhookRouterResult } from "./interfaces/rest/webhook-router.js";
 export { isPrivateUrl, isPrivateIp } from "./modules/webhooks/ssrf-guard.js";
 export { createServer } from "./runtime/server.js";

package/src/interfaces/rest/index.ts

@@ -4,6 +4,7 @@ import { sql } from "drizzle-orm";
 import type { Kernel } from "../../runtime/kernel.js";
 import type { AppEnv } from "./utils.js";
 import { mapErrorToResponse } from "../../kernel/error-mapper.js";
+import { analyticsRoutes } from "./routes/analytics.js";
 import { catalogRoutes } from "./routes/catalog.js";
 import { inventoryRoutes } from "./routes/inventory.js";
 import { mediaRoutes } from "./routes/media.js";
@@ -19,7 +20,12 @@ import { auditRoutes } from "./routes/audit.js";
 import { adminJobRoutes } from "./routes/admin-jobs.js";
 import { compensationFailureAdminRoutes } from "./routes/admin/compensation-failures.js";
 import { adminPermissionsRoutes } from "./routes/admin/permissions.js";
+import { adminStaffRoutes } from "./routes/admin/staff.js";
 import { customerRoutes } from "./routes/customers.js";
+import { documentRoutes } from "./routes/documents.js";
+import { settingsRoutes } from "./routes/settings.js";
+import { shippingRoutes } from "./routes/shipping.js";
+import { taxRoutes } from "./routes/tax.js";
 export function createRestRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>({
     // Standardize Zod validation error responses across all routes
@@ -72,9 +78,14 @@ export function createRestRoutes(kernel: Kernel) {
   router.route("/carts", cartRoutes(kernel));
   router.route("/checkout", checkoutRoutes(kernel));
   router.route("/orders", orderRoutes(kernel));
+  router.route("/orders", documentRoutes(kernel));
   router.route("/payments", paymentRoutes(kernel));
   router.route("/webhooks", webhookRoutes(kernel));
   router.route("/pricing", pricingRoutes(kernel));
+  router.route("/shipping", shippingRoutes(kernel));
+  router.route("/tax", taxRoutes(kernel));
+  router.route("/settings", settingsRoutes(kernel));
+  router.route("/analytics", analyticsRoutes(kernel));
   router.route("/promotions", promotionRoutes(kernel));
   router.route("/search", searchRoutes(kernel));
   router.route("/customers", customerRoutes(kernel));
@@ -82,6 +93,7 @@ export function createRestRoutes(kernel: Kernel) {
   router.route("/admin", adminJobRoutes(kernel));
   router.route("/admin", compensationFailureAdminRoutes(kernel));
   router.route("/admin", adminPermissionsRoutes(kernel));
+  router.route("/admin", adminStaffRoutes(kernel));
 
   // API Reference (Scalar) — disabled in production unless config.exposeOpenApiSpec is true
   const exposeSpec = kernel.config.exposeOpenApiSpec ?? (process.env.NODE_ENV !== "production");

package/src/interfaces/rest/routes/admin/staff.ts

@@ -0,0 +1,218 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { eq, and } from "drizzle-orm";
+import type { Kernel } from "../../../../runtime/kernel.js";
+import type { CommerceConfig } from "../../../../config/types.js";
+import type { DrizzleDatabase } from "../../../../kernel/database/drizzle-db.js";
+import { member, user, invitation } from "../../../../auth/auth-schema.js";
+import { resolveOrgId } from "../../../../auth/org.js";
+import { makeId } from "../../../../utils/id.js";
+import {
+  listStaffRoute,
+  createStaffRoute,
+  inviteStaffRoute,
+  listStaffInvitationsRoute,
+  listStaffRolesRoute,
+  updateStaffRoleRoute,
+  revokeStaffRoute,
+} from "../../schemas/admin-staff.js";
+import { type AppEnv, requirePerm } from "../../utils.js";
+
+/**
+ * Admin staff / RBAC surface (issue #46).
+ *
+ * Surfaces the Better Auth `member` table as first-class admin REST:
+ * list staff, add an existing user with a role, invite by email, change
+ * role, revoke — plus the role → permission mapping roles resolve to.
+ */
+export function adminStaffRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+  const db = kernel.database.db as DrizzleDatabase;
+  const config = kernel.config as CommerceConfig;
+
+  router.use("/staff", requirePerm("staff:manage"));
+  router.use("/staff/:id", requirePerm("staff:manage"));
+  router.use("/staff/invitations", requirePerm("staff:manage"));
+  router.use("/staff/roles", requirePerm("staff:manage"));
+
+  function validRoles(): Set<string> {
+    return new Set([
+      ...Object.keys(config.auth?.roles ?? {}),
+      "owner",
+      "admin",
+      "member",
+    ]);
+  }
+
+  function invalidRole(c: { json: (d: unknown, s: number) => unknown }, role: string) {
+    return c.json(
+      {
+        error: {
+          code: "VALIDATION_FAILED",
+          message: `Unknown role "${role}". Valid roles: ${[...validRoles()].join(", ")}.`,
+        },
+      },
+      422,
+    );
+  }
+
+  async function countOwners(orgId: string): Promise<number> {
+    const rows = await db
+      .select({ id: member.id })
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.role, "owner")));
+    return rows.length;
+  }
+
+  router.openapi(listStaffRoute, async (c) => {
+    const orgId = resolveOrgId(c.get("actor"));
+    const rows = await db
+      .select({
+        id: member.id,
+        userId: member.userId,
+        role: member.role,
+        createdAt: member.createdAt,
+        email: user.email,
+        name: user.name,
+      })
+      .from(member)
+      .leftJoin(user, eq(member.userId, user.id))
+      .where(eq(member.organizationId, orgId));
+    return c.json({ data: rows });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createStaffRoute, async (c) => {
+    const body = c.req.valid("json") as { userId: string; role: string };
+    const orgId = resolveOrgId(c.get("actor"));
+
+    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+
+    const users = await db.select().from(user).where(eq(user.id, body.userId));
+    if (users.length === 0) {
+      return c.json({ error: { code: "NOT_FOUND", message: "User not found." } }, 404);
+    }
+
+    const existing = await db
+      .select({ id: member.id })
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.userId, body.userId)));
+    if (existing.length > 0) {
+      return c.json(
+        { error: { code: "VALIDATION_FAILED", message: "User is already a member of this organization." } },
+        422,
+      );
+    }
+
+    const rows = await db
+      .insert(member)
+      .values({
+        id: makeId(),
+        organizationId: orgId,
+        userId: body.userId,
+        role: body.role,
+        createdAt: new Date(),
+      })
+      .returning();
+    return c.json({ data: rows[0] }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(inviteStaffRoute, async (c) => {
+    const body = c.req.valid("json") as { email: string; role: string };
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+
+    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+
+    const rows = await db
+      .insert(invitation)
+      .values({
+        id: makeId(),
+        organizationId: orgId,
+        email: body.email,
+        role: body.role,
+        status: "pending",
+        expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+        inviterId: actor!.userId,
+      })
+      .returning();
+    return c.json({ data: rows[0] }, 201);
+  });
+
+  router.openapi(listStaffInvitationsRoute, async (c) => {
+    const orgId = resolveOrgId(c.get("actor"));
+    const rows = await db
+      .select()
+      .from(invitation)
+      .where(and(eq(invitation.organizationId, orgId), eq(invitation.status, "pending")));
+    return c.json({ data: rows });
+  });
+
+  router.openapi(listStaffRolesRoute, async (c) => {
+    const roles = config.auth?.roles ?? {};
+    const data = Object.entries(roles).map(([role, def]) => ({
+      role,
+      permissions: def.permissions,
+    }));
+    return c.json({ data });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateStaffRoleRoute, async (c) => {
+    const body = c.req.valid("json") as { role: string };
+    const orgId = resolveOrgId(c.get("actor"));
+    const id = c.req.param("id");
+
+    if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+
+    const rows = await db
+      .select()
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
+    const target = rows[0];
+    if (!target) {
+      return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
+    }
+
+    if (target.role === "owner" && body.role !== "owner" && (await countOwners(orgId)) <= 1) {
+      return c.json(
+        { error: { code: "VALIDATION_FAILED", message: "Cannot demote the organization's last owner." } },
+        422,
+      );
+    }
+
+    const updated = await db
+      .update(member)
+      .set({ role: body.role })
+      .where(eq(member.id, id))
+      .returning();
+    return c.json({ data: updated[0] });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(revokeStaffRoute, async (c) => {
+    const orgId = resolveOrgId(c.get("actor"));
+    const id = c.req.param("id");
+
+    const rows = await db
+      .select()
+      .from(member)
+      .where(and(eq(member.organizationId, orgId), eq(member.id, id)));
+    const target = rows[0];
+    if (!target) {
+      return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
+    }
+
+    if (target.role === "owner" && (await countOwners(orgId)) <= 1) {
+      return c.json(
+        { error: { code: "VALIDATION_FAILED", message: "Cannot revoke the organization's last owner." } },
+        422,
+      );
+    }
+
+    await db.delete(member).where(eq(member.id, id));
+    return c.json({ data: { deleted: true } });
+  });
+
+  return router;
+}

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

@@ -0,0 +1,33 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { getReportRoute, listReportsRoute } from "../schemas/analytics.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+export function analyticsRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/reports", requirePerm("analytics:read"));
+  router.use("/reports/:name", requirePerm("analytics:read"));
+
+  router.openapi(listReportsRoute, (c) => {
+    return c.json({ data: kernel.services.analytics.listReports() });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(getReportRoute, async (c) => {
+    const { date, from, to } = c.req.valid("query");
+    const result = await kernel.services.analytics.getReport(
+      c.req.param("name"),
+      {
+        ...(date !== undefined ? { date } : {}),
+        ...(from !== undefined ? { from } : {}),
+        ...(to !== undefined ? { to } : {}),
+      },
+      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/carts.ts

@@ -1,8 +1,8 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import type { CreateCartInput, AddCartItemInput } from "../../../modules/cart/schemas.js";
-import { createCartRoute, addCartItemRoute, updateCartItemQuantityRoute, getCartRoute, removeCartItemRoute } from "../schemas/carts.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+import { createCartRoute, addCartItemRoute, updateCartItemQuantityRoute, getCartRoute, removeCartItemRoute, listCartsRoute, recoverCartRoute } from "../schemas/carts.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
 
 export function cartRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -21,6 +21,56 @@ export function cartRoutes(kernel: Kernel) {
     return c.json({ data: result.value }, 201);
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listCartsRoute, async (c) => {
+    const actor = c.get("actor");
+    const pagination = parsePagination(c.req.query());
+    const status = c.req.query("status");
+    const olderThanRaw = c.req.query("olderThan");
+    const hasCustomerRaw = c.req.query("hasCustomer");
+
+    let olderThan: Date | undefined;
+    if (olderThanRaw) {
+      const d = new Date(olderThanRaw);
+      if (Number.isNaN(d.getTime())) {
+        return c.json({ error: { code: "VALIDATION_FAILED", message: "olderThan must be an ISO timestamp." } }, 422);
+      }
+      olderThan = d;
+    }
+
+    const result = await kernel.services.cart.list(
+      {
+        page: pagination.page,
+        limit: pagination.limit,
+        ...(status !== undefined ? { status } : {}),
+        ...(olderThan !== undefined ? { olderThan } : {}),
+        ...(hasCustomerRaw === "true" ? { hasCustomer: true } : {}),
+        ...(hasCustomerRaw === "false" ? { hasCustomer: false } : {}),
+      },
+      actor,
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({
+      data: result.value.items,
+      meta: { pagination: result.value.pagination },
+    });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(recoverCartRoute, async (c) => {
+    const result = await kernel.services.cart.recover(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(getCartRoute, async (c) => {
     const actor = c.get("actor");

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

@@ -44,6 +44,8 @@ import {
   createOptionValueRoute,
   createVariantRoute,
   generateVariantsRoute,
+  quickVariantRoute,
+  bulkVariantsRoute,
 } from "../schemas/catalog.js";
 import {
   type AppEnv,
@@ -508,6 +510,38 @@ export function catalogRoutes(kernel: Kernel) {
     return c.json({ data: result.value }, 201);
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(quickVariantRoute, async (c) => {
+    const body = c.req.valid("json") as { options: Record<string, string>; sku?: string; barcode?: string };
+    const result = await kernel.services.catalog.quickCreateVariant(
+      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 }, result.value.created ? 201 : 200);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(bulkVariantsRoute, async (c) => {
+    const body = c.req.valid("json") as { axes: Array<{ name: string; values: string[] }>; skuPrefix?: string };
+    const result = await kernel.services.catalog.bulkCreateVariants(
+      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(generateVariantsRoute, async (c) => {
     const body = c.req.valid("json") as VariantGenerationStrategy;

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

@@ -34,6 +34,20 @@ export function checkoutRoutes(kernel: Kernel) {
     const body = c.req.valid("json");
 
     const actor = c.get("actor");
+
+    // Idempotent replay: a re-submitted checkout (offline POS queue, network
+    // retry) returns the already-created order BEFORE the pipeline runs — no
+    // double payment authorization, no duplicate order.
+    if (body.idempotencyKey) {
+      const replay = await kernel.services.orders.getByIdempotencyKey(
+        body.idempotencyKey,
+        actor,
+      );
+      if (replay.ok && replay.value) {
+        return c.json({ data: replay.value }, 201);
+      }
+    }
+
     const checkoutData: CheckoutData = {
       checkoutId: makeId(),
       cartId: body.cartId,
@@ -149,6 +163,9 @@ export function checkoutRoutes(kernel: Kernel) {
       }
 
       const orderPayload = {
+        ...(body.idempotencyKey !== undefined
+          ? { idempotencyKey: body.idempotencyKey }
+          : {}),
         currency: processed.currency,
         subtotal: processed.subtotal,
         taxTotal: processed.taxTotal,
@@ -177,6 +194,11 @@ export function checkoutRoutes(kernel: Kernel) {
             quantity: lineItem.quantity,
             unitPrice: lineItem.resolvedUnitPrice ?? 0,
             totalPrice: lineItem.resolvedTotal ?? 0,
+            // Per-line tax from product tax classes (issue #57)
+            taxAmount: lineItem.taxAmount ?? 0,
+            ...(lineItem.discountAmount !== undefined
+              ? { discountAmount: lineItem.discountAmount }
+              : {}),
           };
           return lineItem.variantId !== undefined
             ? { ...payload, variantId: lineItem.variantId }

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

@@ -0,0 +1,61 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import {
+  emailInvoiceRoute,
+  invoiceHtmlRoute,
+  invoicePdfRoute,
+  receiptHtmlRoute,
+} from "../schemas/documents.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+
+/**
+ * Order document rendering (issue #47). Mounted under /orders. Access
+ * control rides on OrderService.getById (orders:read, or orders:read:own
+ * for the order's customer), so no extra scope is needed here.
+ */
+export function documentRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.openapi(invoicePdfRoute, async (c) => {
+    const result = await kernel.services.documents.renderInvoicePdf(
+      c.req.param("id"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.body(result.value.pdf.slice().buffer as ArrayBuffer, 200, {
+      "content-type": "application/pdf",
+      "content-disposition": `inline; filename="invoice-${result.value.invoiceNumber}.pdf"`,
+    });
+  });
+
+  router.openapi(invoiceHtmlRoute, async (c) => {
+    const result = await kernel.services.documents.renderInvoiceHtml(
+      c.req.param("id"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.html(result.value.html);
+  });
+
+  router.openapi(receiptHtmlRoute, async (c) => {
+    const result = await kernel.services.documents.renderReceiptHtml(
+      c.req.param("id"),
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.html(result.value.html);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(emailInvoiceRoute, async (c) => {
+    const result = await kernel.services.documents.emailInvoice(
+      c.req.param("id"),
+      c.req.valid("json").to,
+      c.get("actor"),
+    );
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}