@porulle/core 0.7.0 → 0.8.0

package/src/modules/shipping/service.ts

@@ -1,16 +1,26 @@
 import type { CommerceConfig } from "../../config/types.js";
-import { Ok, type Result } from "../../kernel/result.js";
+import { resolveOrgId } from "../../auth/org.js";
+import type { Actor } from "../../auth/types.js";
+import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
 import type { CatalogRepository } from "../catalog/repository/index.js";
 import {
   calculateShippingCost,
+  computeShippableWeightGrams,
   type ShippingAddress,
   type ShippingLineItem,
 } from "./calculator.js";
+import type {
+  ShippingConfigRepository,
+  ShippingZone,
+  ShippingRate,
+} from "./repository/index.js";
 
 interface ShippingServiceDeps {
   config: CommerceConfig;
   catalogRepository: CatalogRepository;
+  repository: ShippingConfigRepository;
 }
 
 export interface CalculateShippingInput {
@@ -19,6 +29,8 @@ export interface CalculateShippingInput {
   currency: string;
   address?: ShippingAddress;
   isFreeShipping?: boolean;
+  /** When set, runtime shipping zones for this org take precedence over code config. */
+  orgId?: string;
 }
 
 export class ShippingService {
@@ -34,6 +46,16 @@ export class ShippingService {
   ): Promise<
     Result<{ amount: number; strategy: string; weightGrams: number }>
   > {
+    // Runtime zones (issue #45) take precedence when they exist and the
+    // destination is known; the code-config strategy remains the fallback.
+    if (!input.isFreeShipping && input.orgId && input.address) {
+      const zoneResult = await this.calculateFromZones(
+        input as CalculateShippingInput & { orgId: string; address: ShippingAddress },
+        ctx,
+      );
+      if (zoneResult) return Ok(zoneResult);
+    }
+
     const result = await calculateShippingCost(
       this.deps.config,
       this.catalogRepo,
@@ -48,4 +70,241 @@ export class ShippingService {
     );
     return Ok(result);
   }
+
+  private zoneMatches(zone: ShippingZone, address: ShippingAddress): boolean {
+    const country = address.country?.toUpperCase();
+    const countries = zone.countries.map((c) => c.toUpperCase());
+    if (!countries.includes("*") && (!country || !countries.includes(country))) {
+      return false;
+    }
+    if (zone.states.length > 0) {
+      const state = address.state?.toUpperCase();
+      if (!state || !zone.states.map((s) => s.toUpperCase()).includes(state)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private async calculateFromZones(
+    input: CalculateShippingInput & { orgId: string; address: ShippingAddress },
+    ctx?: TxContext,
+  ): Promise<{ amount: number; strategy: string; weightGrams: number } | null> {
+    const zones = await this.deps.repository.findActiveZones(input.orgId, ctx);
+    if (zones.length === 0) return null;
+
+    let weightGrams: number | null = null;
+    for (const zone of zones) {
+      if (!this.zoneMatches(zone, input.address)) continue;
+      const rates = (
+        await this.deps.repository.findActiveRatesByZoneId(zone.id, ctx)
+      ).filter((rate) => rate.currency === input.currency);
+
+      for (const rate of rates) {
+        const sub = input.subtotalAfterDiscount;
+        if (rate.minSubtotal != null && sub < rate.minSubtotal) continue;
+        if (rate.maxSubtotal != null && sub > rate.maxSubtotal) continue;
+        if (rate.minWeightGrams != null || rate.maxWeightGrams != null) {
+          weightGrams ??= await computeShippableWeightGrams(
+            this.deps.config,
+            this.catalogRepo,
+            input.lineItems,
+            ctx,
+          );
+          if (rate.minWeightGrams != null && weightGrams < rate.minWeightGrams) continue;
+          if (rate.maxWeightGrams != null && weightGrams > rate.maxWeightGrams) continue;
+        }
+        if (rate.freeShippingThreshold != null && sub >= rate.freeShippingThreshold) {
+          return {
+            amount: 0,
+            strategy: `zone:${zone.name}:free_shipping`,
+            weightGrams: weightGrams ?? 0,
+          };
+        }
+        return {
+          amount: Math.max(0, Math.round(rate.amount)),
+          strategy: `zone:${zone.name}:${rate.name}`,
+          weightGrams: weightGrams ?? 0,
+        };
+      }
+    }
+    return null;
+  }
+
+  // ── Runtime zone & rate management (issue #45) ─────────────────────────
+
+  async createZone(
+    input: {
+      name: string;
+      countries: string[];
+      states?: string[] | undefined;
+      priority?: number | undefined;
+      isActive?: boolean | undefined;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<ShippingZone>> {
+    if (input.countries.length === 0) {
+      return Err(new CommerceValidationError("A shipping zone requires at least one country (\"*\" matches any)."));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const zone = await this.deps.repository.createZone(
+      {
+        organizationId: orgId,
+        name: input.name,
+        countries: input.countries.map((c) => c.toUpperCase()),
+        states: (input.states ?? []).map((s) => s.toUpperCase()),
+        priority: input.priority ?? 100,
+        isActive: input.isActive ?? true,
+      },
+      ctx,
+    );
+    return Ok(zone);
+  }
+
+  async listZones(actor?: Actor | null, ctx?: TxContext): Promise<Result<ShippingZone[]>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    return Ok(await this.deps.repository.findZones(orgId, ctx));
+  }
+
+  async updateZone(
+    id: string,
+    patch: {
+      name?: string | undefined;
+      countries?: string[] | undefined;
+      states?: string[] | undefined;
+      priority?: number | undefined;
+      isActive?: boolean | undefined;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<ShippingZone>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.deps.repository.findZoneById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Shipping zone not found."));
+    const updated = await this.deps.repository.updateZone(
+      id,
+      {
+        ...(patch.name !== undefined ? { name: patch.name } : {}),
+        ...(patch.countries !== undefined
+          ? { countries: patch.countries.map((c) => c.toUpperCase()) }
+          : {}),
+        ...(patch.states !== undefined
+          ? { states: patch.states.map((s) => s.toUpperCase()) }
+          : {}),
+        ...(patch.priority !== undefined ? { priority: patch.priority } : {}),
+        ...(patch.isActive !== undefined ? { isActive: patch.isActive } : {}),
+      },
+      ctx,
+    );
+    return Ok(updated!);
+  }
+
+  async deleteZone(id: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<{ deleted: true }>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.deps.repository.findZoneById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Shipping zone not found."));
+    await this.deps.repository.deleteZone(id, ctx);
+    return Ok({ deleted: true });
+  }
+
+  async createRate(
+    input: {
+      zoneId: string;
+      name: string;
+      amount: number;
+      currency?: string | undefined;
+      minSubtotal?: number | undefined;
+      maxSubtotal?: number | undefined;
+      minWeightGrams?: number | undefined;
+      maxWeightGrams?: number | undefined;
+      freeShippingThreshold?: number | undefined;
+      isActive?: boolean | undefined;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<ShippingRate>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const zone = await this.deps.repository.findZoneById(orgId, input.zoneId, ctx);
+    if (!zone) return Err(new CommerceNotFoundError("Shipping zone not found."));
+    const rate = await this.deps.repository.createRate(
+      {
+        organizationId: orgId,
+        zoneId: input.zoneId,
+        name: input.name,
+        amount: input.amount,
+        currency: input.currency ?? "USD",
+        minSubtotal: input.minSubtotal ?? null,
+        maxSubtotal: input.maxSubtotal ?? null,
+        minWeightGrams: input.minWeightGrams ?? null,
+        maxWeightGrams: input.maxWeightGrams ?? null,
+        freeShippingThreshold: input.freeShippingThreshold ?? null,
+        isActive: input.isActive ?? true,
+      },
+      ctx,
+    );
+    return Ok(rate);
+  }
+
+  async listRates(
+    filter?: { zoneId?: string },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<ShippingRate[]>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    return Ok(
+      await this.deps.repository.findRates(
+        orgId,
+        filter?.zoneId !== undefined ? { zoneId: filter.zoneId } : undefined,
+        ctx,
+      ),
+    );
+  }
+
+  async updateRate(
+    id: string,
+    patch: {
+      name?: string | undefined;
+      amount?: number | undefined;
+      currency?: string | undefined;
+      minSubtotal?: number | null | undefined;
+      maxSubtotal?: number | null | undefined;
+      minWeightGrams?: number | null | undefined;
+      maxWeightGrams?: number | null | undefined;
+      freeShippingThreshold?: number | null | undefined;
+      isActive?: boolean | undefined;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<ShippingRate>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.deps.repository.findRateById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Shipping rate not found."));
+    const updated = await this.deps.repository.updateRate(
+      id,
+      {
+        ...(patch.name !== undefined ? { name: patch.name } : {}),
+        ...(patch.amount !== undefined ? { amount: patch.amount } : {}),
+        ...(patch.currency !== undefined ? { currency: patch.currency } : {}),
+        ...(patch.minSubtotal !== undefined ? { minSubtotal: patch.minSubtotal } : {}),
+        ...(patch.maxSubtotal !== undefined ? { maxSubtotal: patch.maxSubtotal } : {}),
+        ...(patch.minWeightGrams !== undefined ? { minWeightGrams: patch.minWeightGrams } : {}),
+        ...(patch.maxWeightGrams !== undefined ? { maxWeightGrams: patch.maxWeightGrams } : {}),
+        ...(patch.freeShippingThreshold !== undefined
+          ? { freeShippingThreshold: patch.freeShippingThreshold }
+          : {}),
+        ...(patch.isActive !== undefined ? { isActive: patch.isActive } : {}),
+      },
+      ctx,
+    );
+    return Ok(updated!);
+  }
+
+  async deleteRate(id: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<{ deleted: true }>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.deps.repository.findRateById(orgId, id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Shipping rate not found."));
+    await this.deps.repository.deleteRate(id, ctx);
+    return Ok({ deleted: true });
+  }
 }

package/src/modules/tax/adapter.ts

@@ -11,6 +11,8 @@ export interface TaxAddress {
 export interface TaxLineItem {
   id: string;
   entityId: string;
+  /** Variant reference — a variant-level taxClass overrides the entity's (issue #57). */
+  variantId?: string;
   description: string;
   quantity: number;
   unitPrice: number;
@@ -25,6 +27,11 @@ export interface TaxCalculationParams {
   fromAddress?: TaxAddress;
   toAddress?: TaxAddress;
   shippingAmount: number;
+  /**
+   * Cart-level discount not already reflected in per-line `discount` —
+   * pro-rated across lines before class-based tax (issue #57).
+   */
+  orderDiscount?: number;
   lineItems: TaxLineItem[];
 }
 
@@ -33,6 +40,8 @@ export interface TaxCalculationResult {
   taxableAmount: number;
   rate: number;
   breakdown?: Record<string, unknown>;
+  /** Per-line results when product tax classes computed the tax (issue #57). */
+  lines?: Array<{ id: string; taxClass: string | null; taxAmount: number }>;
 }
 
 export interface TaxReportParams {

package/src/modules/tax/module.ts

@@ -1,16 +1,20 @@
 import type { CommerceConfig } from "../../config/types.js";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
 import { defineModule } from "../../kernel/module/index.js";
+import { TaxRatesRepository } from "./repository/index.js";
+import { taxClasses, taxRates } from "./schema.js";
 import { TaxService } from "./service.js";
 
 export const taxModule = defineModule<
-  Record<string, never>,
+  { taxRates: typeof taxRates; taxClasses: typeof taxClasses },
   TaxService,
   Record<string, never>
 >({
   id: "tax",
-  schema: () => ({}),
+  schema: () => ({ taxRates, taxClasses }),
   service: (deps) =>
     new TaxService({
       adapter: (deps.config as CommerceConfig).tax?.adapter,
+      repository: new TaxRatesRepository(deps.db.db as DrizzleDatabase),
     }),
 });

package/src/modules/tax/repository/index.ts

@@ -1,5 +1,172 @@
+import { eq, and, asc, inArray } from "drizzle-orm";
 import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db.js";
+import { sellableEntities, variants } from "../../catalog/schema.js";
+import { taxClasses, taxRates } from "../schema.js";
 
-export interface TaxRepository {
-  ping(ctx: TxContext): Promise<void>;
+export type TaxRate = typeof taxRates.$inferSelect;
+export type TaxRateInsert = typeof taxRates.$inferInsert;
+export type TaxClass = typeof taxClasses.$inferSelect;
+export type TaxClassInsert = typeof taxClasses.$inferInsert;
+
+/**
+ * Persistence for runtime tax rates (issue #45).
+ */
+export class TaxRatesRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  async findById(orgId: string, id: string, ctx?: TxContext): Promise<TaxRate | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(taxRates)
+      .where(and(eq(taxRates.organizationId, orgId), eq(taxRates.id, id)));
+    return rows[0];
+  }
+
+  async findAll(orgId: string, ctx?: TxContext): Promise<TaxRate[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(taxRates)
+      .where(eq(taxRates.organizationId, orgId))
+      .orderBy(asc(taxRates.priority));
+  }
+
+  async findActive(orgId: string, ctx?: TxContext): Promise<TaxRate[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(taxRates)
+      .where(and(eq(taxRates.organizationId, orgId), eq(taxRates.isActive, true)))
+      .orderBy(asc(taxRates.priority));
+  }
+
+  async create(data: TaxRateInsert, ctx?: TxContext): Promise<TaxRate> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(taxRates).values(data).returning();
+    return rows[0]!;
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<TaxRateInsert, "id" | "organizationId">>,
+    ctx?: TxContext,
+  ): Promise<TaxRate | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(taxRates)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(taxRates.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async delete(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const rows = await db.delete(taxRates).where(eq(taxRates.id, id)).returning();
+    return rows.length > 0;
+  }
+
+  // ── Product tax classes (issue #57) ─────────────────────────────────────
+
+  async findActiveClasses(orgId: string, ctx?: TxContext): Promise<TaxClass[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(taxClasses)
+      .where(and(eq(taxClasses.organizationId, orgId), eq(taxClasses.isActive, true)))
+      .orderBy(asc(taxClasses.name));
+  }
+
+  async findAllClasses(orgId: string, ctx?: TxContext): Promise<TaxClass[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(taxClasses)
+      .where(eq(taxClasses.organizationId, orgId))
+      .orderBy(asc(taxClasses.name));
+  }
+
+  async findClassById(orgId: string, id: string, ctx?: TxContext): Promise<TaxClass | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(taxClasses)
+      .where(and(eq(taxClasses.organizationId, orgId), eq(taxClasses.id, id)));
+    return rows[0];
+  }
+
+  async createClass(data: TaxClassInsert, ctx?: TxContext): Promise<TaxClass> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(taxClasses).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateClass(
+    id: string,
+    data: Partial<Omit<TaxClassInsert, "id" | "organizationId">>,
+    ctx?: TxContext,
+  ): Promise<TaxClass | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(taxClasses)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(taxClasses.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteClass(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const rows = await db.delete(taxClasses).where(eq(taxClasses.id, id)).returning();
+    return rows.length > 0;
+  }
+
+  async clearDefaultClass(orgId: string, ctx?: TxContext): Promise<void> {
+    const db = this.getDb(ctx);
+    await db
+      .update(taxClasses)
+      .set({ isDefault: false, updatedAt: new Date() })
+      .where(and(eq(taxClasses.organizationId, orgId), eq(taxClasses.isDefault, true)));
+  }
+
+  /**
+   * Resolves the taxClass for catalog references: variant.taxClass overrides
+   * entity.taxClass. Returns maps keyed by id so callers can pick
+   * variant-first.
+   */
+  async resolveCatalogTaxClasses(
+    refs: Array<{ entityId: string; variantId?: string | undefined }>,
+    ctx?: TxContext,
+  ): Promise<{ byEntity: Map<string, string | null>; byVariant: Map<string, string | null> }> {
+    const db = this.getDb(ctx);
+    const entityIds = [...new Set(refs.map((r) => r.entityId))];
+    const variantIds = [...new Set(refs.flatMap((r) => (r.variantId ? [r.variantId] : [])))];
+
+    const byEntity = new Map<string, string | null>();
+    const byVariant = new Map<string, string | null>();
+    if (entityIds.length > 0) {
+      const rows = await db
+        .select({ id: sellableEntities.id, taxClass: sellableEntities.taxClass })
+        .from(sellableEntities)
+        .where(inArray(sellableEntities.id, entityIds));
+      for (const row of rows) byEntity.set(row.id, row.taxClass);
+    }
+    if (variantIds.length > 0) {
+      const rows = await db
+        .select({ id: variants.id, taxClass: variants.taxClass })
+        .from(variants)
+        .where(inArray(variants.id, variantIds));
+      for (const row of rows) byVariant.set(row.id, row.taxClass);
+    }
+    return { byEntity, byVariant };
+  }
 }

package/src/modules/tax/schema.ts

@@ -0,0 +1,57 @@
+import { boolean, index, integer, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+
+/**
+ * Product tax classes (issue #57) — standard / reduced / zero-rated etc.
+ * Sellable entities and variants reference a class by name (`taxClass`
+ * column); checkout computes per-line tax from the class rate, with cart
+ * discounts pro-rated across lines first. Lines with no class use the org's
+ * default class (isDefault). When classes exist for an org they take
+ * precedence over region rates and the adapter for line taxation.
+ */
+export const taxClasses = pgTable("tax_classes", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  // Basis points: 1000 = 10%
+  rateBps: integer("rate_bps").notNull(),
+  isDefault: boolean("is_default").notNull().default(false),
+  isActive: boolean("is_active").notNull().default(true),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgNameUnique: uniqueIndex("tax_classes_org_name_unique").on(table.organizationId, table.name),
+}));
+
+/**
+ * Runtime tax rates (issue #45).
+ *
+ * Per-region rates in basis points (500 = 5%). When rates exist for an
+ * organization and the calculation has a destination address, they take
+ * precedence over the configured tax adapter, which remains the fallback.
+ * State-specific matches beat country-level matches; multiple matches at
+ * the same specificity are summed (e.g. GST + PST).
+ */
+export const taxRates = pgTable("tax_rates", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  // ISO 3166-1 alpha-2, uppercase. "*" matches any country.
+  country: text("country").notNull(),
+  // Optional state/province code; null = the whole country.
+  state: text("state"),
+  // Basis points: 500 = 5%, 875 = 8.75%
+  rateBps: integer("rate_bps").notNull(),
+  appliesToShipping: boolean("applies_to_shipping").notNull().default(true),
+  priority: integer("priority").notNull().default(100),
+  isActive: boolean("is_active").notNull().default(true),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_tax_rates_org").on(table.organizationId),
+  countryIdx: index("idx_tax_rates_country").on(table.country, table.state),
+}));