@porulle/core 0.7.0 → 0.8.0

package/src/modules/tax/service.ts

@@ -1,4 +1,7 @@
-import { CommerceValidationError } from "../../kernel/errors.js";
+import { resolveOrgId } from "../../auth/org.js";
+import type { Actor } from "../../auth/types.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors.js";
 import { Err, Ok, type Result } from "../../kernel/result.js";
 import type {
   TaxAdapter,
@@ -7,19 +10,73 @@ import type {
   TaxReportParams,
   TaxVoidParams,
 } from "./adapter.js";
+import type { TaxClass, TaxRate, TaxRatesRepository } from "./repository/index.js";
 
 interface TaxServiceDeps {
   adapter: TaxAdapter | undefined;
+  repository?: TaxRatesRepository;
 }
 
 export class TaxService {
   private adapter: TaxAdapter | undefined;
+  private repository: TaxRatesRepository | undefined;
 
   constructor(deps: TaxServiceDeps) {
     this.adapter = deps.adapter;
+    this.repository = deps.repository;
   }
 
-  async calculate(params: TaxCalculationParams): Promise<Result<TaxCalculationResult>> {
+  /**
+   * Calculates tax. Resolution order:
+   * 1. Product tax classes (issue #57) — when the org defines active classes,
+   *    each line taxes by its class (variant taxClass beats entity taxClass;
+   *    unclassed lines use the default class or 0), with `orderDiscount`
+   *    pro-rated across lines first. Returns per-line results in `lines`.
+   * 2. Runtime tax rates for the org matching `toAddress` (issue #45) —
+   *    state-specific matches beat country-level; matches at the winning
+   *    specificity are summed (e.g. GST + PST).
+   * 3. The configured tax adapter.
+   * 4. Zero tax.
+   */
+  async calculate(
+    params: TaxCalculationParams,
+    orgId?: string,
+    ctx?: TxContext,
+  ): Promise<Result<TaxCalculationResult>> {
+    if (this.repository && orgId && params.lineItems.length > 0) {
+      const classes = await this.repository.findActiveClasses(orgId, ctx);
+      if (classes.length > 0) {
+        return Ok(await this.calculateByClasses(params, classes, ctx));
+      }
+    }
+
+    if (this.repository && orgId && params.toAddress) {
+      const matched = await this.matchRuntimeRates(orgId, params.toAddress, ctx);
+      if (matched.length > 0) {
+        const taxableAmount = params.lineItems.reduce(
+          (sum, lineItem) =>
+            sum + lineItem.unitPrice * lineItem.quantity - (lineItem.discount ?? 0),
+          0,
+        );
+        let amountToCollect = 0;
+        const breakdown: Record<string, unknown> = {};
+        for (const rate of matched) {
+          const base =
+            taxableAmount + (rate.appliesToShipping ? params.shippingAmount : 0);
+          const amount = Math.max(0, Math.round((base * rate.rateBps) / 10_000));
+          amountToCollect += amount;
+          breakdown[rate.name] = { rateBps: rate.rateBps, amount };
+        }
+        const totalBps = matched.reduce((sum, r) => sum + r.rateBps, 0);
+        return Ok({
+          amountToCollect,
+          taxableAmount,
+          rate: totalBps / 10_000,
+          breakdown,
+        });
+      }
+    }
+
     if (!this.adapter) {
       return Ok({
         amountToCollect: 0,
@@ -34,6 +91,162 @@ export class TaxService {
     return this.adapter.calculateTax(params);
   }
 
+  /** Per-line class-based tax with cart-discount pro-ration (issue #57). */
+  private async calculateByClasses(
+    params: TaxCalculationParams,
+    classes: TaxClass[],
+    ctx?: TxContext,
+  ): Promise<TaxCalculationResult> {
+    const byName = new Map(classes.map((c) => [c.name, c]));
+    const defaultClass = classes.find((c) => c.isDefault) ?? null;
+
+    const { byEntity, byVariant } = await this.repository!.resolveCatalogTaxClasses(
+      params.lineItems.map((li) => ({ entityId: li.entityId, variantId: li.variantId })),
+      ctx,
+    );
+
+    // Pro-rate the cart-level discount across lines by value share; the last
+    // line absorbs the rounding remainder so the sum stays exact.
+    const lineValues = params.lineItems.map(
+      (li) => Math.max(0, li.unitPrice * li.quantity - (li.discount ?? 0)),
+    );
+    const totalValue = lineValues.reduce((sum, v) => sum + v, 0);
+    const orderDiscount = Math.min(params.orderDiscount ?? 0, totalValue);
+    const prorated = lineValues.map((value) =>
+      totalValue > 0 ? Math.round((orderDiscount * value) / totalValue) : 0,
+    );
+    if (lineValues.length > 0) {
+      const drift = orderDiscount - prorated.reduce((sum, v) => sum + v, 0);
+      prorated[prorated.length - 1]! += drift;
+    }
+
+    let amountToCollect = 0;
+    let taxableAmount = 0;
+    const breakdown: Record<string, unknown> = {};
+    const lines: Array<{ id: string; taxClass: string | null; taxAmount: number }> = [];
+
+    for (const [i, lineItem] of params.lineItems.entries()) {
+      const className =
+        (lineItem.variantId ? byVariant.get(lineItem.variantId) : null) ??
+        byEntity.get(lineItem.entityId) ??
+        defaultClass?.name ??
+        null;
+      const taxClass = className ? (byName.get(className) ?? defaultClass) : defaultClass;
+      const base = Math.max(0, lineValues[i]! - prorated[i]!);
+      const taxAmount = taxClass
+        ? Math.max(0, Math.round((base * taxClass.rateBps) / 10_000))
+        : 0;
+      amountToCollect += taxAmount;
+      taxableAmount += base;
+      lines.push({ id: lineItem.id, taxClass: taxClass?.name ?? null, taxAmount });
+      if (taxClass) {
+        const entry = (breakdown[taxClass.name] as { rateBps: number; amount: number }) ?? {
+          rateBps: taxClass.rateBps,
+          amount: 0,
+        };
+        entry.amount += taxAmount;
+        breakdown[taxClass.name] = entry;
+      }
+    }
+
+    return {
+      amountToCollect,
+      taxableAmount,
+      rate: taxableAmount > 0 ? amountToCollect / taxableAmount : 0,
+      breakdown,
+      lines,
+    };
+  }
+
+  // ── Tax class management (issue #57) ─────────────────────────────────────
+
+  async createTaxClass(
+    input: { name: string; rateBps: number; isDefault?: boolean | undefined; isActive?: boolean | undefined },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<TaxClass>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    if (input.rateBps < 0) {
+      return Err(new CommerceValidationError("rateBps must be non-negative."));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    if (input.isDefault) await repo.value.clearDefaultClass(orgId, ctx);
+    const created = await repo.value.createClass(
+      {
+        organizationId: orgId,
+        name: input.name,
+        rateBps: input.rateBps,
+        isDefault: input.isDefault ?? false,
+        isActive: input.isActive ?? true,
+      },
+      ctx,
+    );
+    return Ok(created);
+  }
+
+  async listTaxClasses(actor?: Actor | null, ctx?: TxContext): Promise<Result<TaxClass[]>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    return Ok(await repo.value.findAllClasses(orgId, ctx));
+  }
+
+  async updateTaxClass(
+    id: string,
+    patch: { name?: string | undefined; rateBps?: number | undefined; isDefault?: boolean | undefined; isActive?: boolean | undefined },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<TaxClass>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await repo.value.findClassById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Tax class not found."));
+    if (patch.isDefault) await repo.value.clearDefaultClass(orgId, ctx);
+    const updated = await repo.value.updateClass(
+      id,
+      {
+        ...(patch.name !== undefined ? { name: patch.name } : {}),
+        ...(patch.rateBps !== undefined ? { rateBps: patch.rateBps } : {}),
+        ...(patch.isDefault !== undefined ? { isDefault: patch.isDefault } : {}),
+        ...(patch.isActive !== undefined ? { isActive: patch.isActive } : {}),
+      },
+      ctx,
+    );
+    return Ok(updated!);
+  }
+
+  async deleteTaxClass(id: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<{ deleted: true }>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await repo.value.findClassById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Tax class not found."));
+    await repo.value.deleteClass(id, ctx);
+    return Ok({ deleted: true });
+  }
+
+  private async matchRuntimeRates(
+    orgId: string,
+    toAddress: { country: string; state?: string },
+    ctx?: TxContext,
+  ): Promise<TaxRate[]> {
+    const rates = await this.repository!.findActive(orgId, ctx);
+    if (rates.length === 0) return [];
+    const country = toAddress.country?.toUpperCase();
+    const state = toAddress.state?.toUpperCase();
+
+    const countryMatches = rates.filter(
+      (r) => r.country === "*" || r.country.toUpperCase() === country,
+    );
+    const stateMatches = countryMatches.filter(
+      (r) => r.state != null && state != null && r.state.toUpperCase() === state,
+    );
+    if (stateMatches.length > 0) return stateMatches;
+    return countryMatches.filter((r) => r.state == null);
+  }
+
   async reportTransaction(params: TaxReportParams): Promise<Result<{ transactionId: string }>> {
     if (!this.adapter) return Ok({ transactionId: params.transactionId });
     return this.adapter.reportTransaction(params);
@@ -50,4 +263,102 @@ export class TaxService {
     }
     return Ok(this.adapter);
   }
+
+  // ── Runtime tax-rate management (issue #45) ────────────────────────────
+
+  private requireRepository(): Result<TaxRatesRepository> {
+    if (!this.repository) {
+      return Err(new CommerceValidationError("Tax rate persistence is not available."));
+    }
+    return Ok(this.repository);
+  }
+
+  async createTaxRate(
+    input: {
+      name: string;
+      country: string;
+      state?: string | undefined;
+      rateBps: number;
+      appliesToShipping?: boolean | undefined;
+      priority?: number | undefined;
+      isActive?: boolean | undefined;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<TaxRate>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    if (input.rateBps < 0) {
+      return Err(new CommerceValidationError("rateBps must be non-negative."));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const rate = await repo.value.create(
+      {
+        organizationId: orgId,
+        name: input.name,
+        country: input.country.toUpperCase(),
+        state: input.state?.toUpperCase() ?? null,
+        rateBps: input.rateBps,
+        appliesToShipping: input.appliesToShipping ?? true,
+        priority: input.priority ?? 100,
+        isActive: input.isActive ?? true,
+      },
+      ctx,
+    );
+    return Ok(rate);
+  }
+
+  async listTaxRates(actor?: Actor | null, ctx?: TxContext): Promise<Result<TaxRate[]>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    return Ok(await repo.value.findAll(orgId, ctx));
+  }
+
+  async updateTaxRate(
+    id: string,
+    patch: {
+      name?: string | undefined;
+      country?: string | undefined;
+      state?: string | null | undefined;
+      rateBps?: number | undefined;
+      appliesToShipping?: boolean | undefined;
+      priority?: number | undefined;
+      isActive?: boolean | undefined;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<TaxRate>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await repo.value.findById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Tax rate not found."));
+    const updated = await repo.value.update(
+      id,
+      {
+        ...(patch.name !== undefined ? { name: patch.name } : {}),
+        ...(patch.country !== undefined ? { country: patch.country.toUpperCase() } : {}),
+        ...(patch.state !== undefined ? { state: patch.state?.toUpperCase() ?? null } : {}),
+        ...(patch.rateBps !== undefined ? { rateBps: patch.rateBps } : {}),
+        ...(patch.appliesToShipping !== undefined
+          ? { appliesToShipping: patch.appliesToShipping }
+          : {}),
+        ...(patch.priority !== undefined ? { priority: patch.priority } : {}),
+        ...(patch.isActive !== undefined ? { isActive: patch.isActive } : {}),
+      },
+      ctx,
+    );
+    return Ok(updated!);
+  }
+
+  async deleteTaxRate(id: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<{ deleted: true }>> {
+    const repo = this.requireRepository();
+    if (!repo.ok) return repo;
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await repo.value.findById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Tax rate not found."));
+    await repo.value.delete(id, ctx);
+    return Ok({ deleted: true });
+  }
 }

package/src/runtime/kernel-modules.ts

@@ -5,6 +5,7 @@ import { analyticsModule } from "../modules/analytics/module.js";
 import { cartModule } from "../modules/cart/module.js";
 import { catalogModule } from "../modules/catalog/module.js";
 import { customersModule } from "../modules/customers/index.js";
+import { documentsModule } from "../modules/documents/module.js";
 import { fulfillmentModule } from "../modules/fulfillment/module.js";
 import { inventoryModule } from "../modules/inventory/module.js";
 import { mediaModule } from "../modules/media/index.js";
@@ -14,12 +15,15 @@ import { paymentsModule } from "../modules/payments/module.js";
 import { pricingModule } from "../modules/pricing/index.js";
 import { promotionsModule } from "../modules/promotions/module.js";
 import { searchModule } from "../modules/search/module.js";
+import { settingsModule } from "../modules/settings/module.js";
 import { shippingModule } from "../modules/shipping/module.js";
 import { taxModule } from "../modules/tax/module.js";
 import { webhooksModule } from "../modules/webhooks/index.js";
 
 export const KERNEL_ALL_MODULES = {
   audit: auditModule,
+  settings: settingsModule,
+  documents: documentsModule,
   webhooks: webhooksModule,
   media: mediaModule,
   organization: organizationModule,

package/src/runtime/kernel-types.ts

@@ -19,6 +19,8 @@ import { PromotionService } from "../modules/promotions/service.js";
 import { TaxService } from "../modules/tax/service.js";
 import { ShippingService } from "../modules/shipping/service.js";
 import { SearchService } from "../modules/search/service.js";
+import { SettingsService } from "../modules/settings/service.js";
+import { DocumentsService } from "../modules/documents/service.js";
 import type { AuditService } from "../modules/audit/service.js";
 import { OrganizationService } from "../modules/organization/service.js";
 import { createLogger } from "../utils/logger.js";
@@ -52,6 +54,8 @@ export interface Kernel {
     tax: TaxService;
     shipping: ShippingService;
     search: SearchService;
+    settings: SettingsService;
+    documents: DocumentsService;
     audit: AuditService;
     compensationFailures: CompensationFailuresRepository;
     email: CommerceConfig["email"];
@@ -77,6 +81,8 @@ export const KERNEL_REQUIRED_SERVICE_KEYS = [
   "tax",
   "shipping",
   "search",
+  "settings",
+  "documents",
   "audit",
   "compensationFailures",
 ] as const satisfies Array<keyof Kernel["services"]>;

package/src/runtime/server.ts

@@ -341,7 +341,7 @@ export async function createServer(config: CommerceConfig) {
   app.route("/api/me", createCustomerPortalRoutes(kernel));
 
   if (config.routes) {
-    config.routes(app, kernel);
+    config.routes(app, kernel, auth);
   }
 
   // OpenAPI spec — disabled in production unless explicitly enabled

package/src/test-utils/create-plugin-test-app.ts

@@ -29,6 +29,8 @@ import { buildSchema } from "../kernel/database/migrate.js";
 import { unwrapDb } from "../kernel/database/adapter.js";
 import { ensureDefaultOrg } from "../auth/org.js";
 import { mapErrorToStatus } from "../kernel/error-mapper.js";
+import { createAuth, type AuthInstance } from "../auth/setup.js";
+import { authMiddleware } from "../auth/middleware.js";
 
 // drizzle-kit/api uses CJS internally; createRequire provides ESM compat.
 const require = createRequire(import.meta.url);
@@ -58,6 +60,8 @@ export interface PluginTestApp {
   kernel: Kernel;
   /** Drizzle database instance for direct queries in test assertions. */
   db: PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+  /** The Better Auth instance passed to plugin routes (mint/verify API keys in tests). */
+  auth: AuthInstance;
 }
 
 /**
@@ -105,8 +109,11 @@ export async function createPluginTestApp(
   // 5. Create OpenAPIHono --- matching production server.ts
   //    Plugin routes register via manifest.ts which calls app.openapi().
   const app = new OpenAPIHono<TestAppEnv>();
+  const auth = createAuth(kernel.database, config);
 
-  // 6. Test actor middleware: parse x-test-actor header -> set on context
+  // 6. Test actor middleware: parse x-test-actor header -> set on context.
+  //    Requests without the header fall through to the real auth middleware,
+  //    so API keys minted by plugins (issue #51) authenticate like production.
   app.use("*", async (c, next) => {
     const header = c.req.header("x-test-actor");
     if (header) {
@@ -116,12 +123,17 @@ export async function createPluginTestApp(
     }
     await next();
   });
+  app.use("*", async (c, next) => {
+    if (c.get("actor")) return next();
+    return authMiddleware(auth, config)(c as never, next);
+  });
 
-  // 7. Register plugin routes (deferred via config.routes)
+  // 7. Register plugin routes (deferred via config.routes) — with the auth
+  //    instance, matching server.ts's config.routes(app, kernel, auth).
   const routes = config.routes as
-    | ((app: unknown, kernel: unknown) => void)
+    | ((app: unknown, kernel: unknown, auth?: unknown) => void)
     | undefined;
-  routes?.(app, kernel);
+  routes?.(app, kernel, auth);
 
   // 8. Error handler matching production server.ts — maps CommerceError
   //    subclasses (CommerceForbiddenError, CommerceNotFoundError, etc.)
@@ -149,5 +161,6 @@ export async function createPluginTestApp(
     app,
     kernel,
     db: kernel.database.db as PgDatabase<PgQueryResultHKT, Record<string, unknown>>,
+    auth,
   };
 }

package/src/test-utils/rest-api-test-utils.ts

@@ -166,9 +166,15 @@ export const testActor: Actor = {
     "cart:create",
     "cart:update",
     "cart:read",
+    "cart:manage",
     "customers:update:self",
     "webhooks:manage",
     "pricing:manage",
+    "shipping:manage",
+    "tax:manage",
+    "settings:manage",
+    "analytics:read",
+    "staff:manage",
     "promotions:manage",
     "promotions:read",
     "audit:read",