@porulle/core 0.6.0 → 0.8.0

package/dist/modules/tax/service.js

@@ -1,11 +1,53 @@
-import { CommerceValidationError } from "../../kernel/errors.js";
+import { resolveOrgId } from "../../auth/org.js";
+import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors.js";
 import { Err, Ok } from "../../kernel/result.js";
 export class TaxService {
     adapter;
+    repository;
     constructor(deps) {
         this.adapter = deps.adapter;
+        this.repository = deps.repository;
     }
-    async calculate(params) {
+    /**
+     * 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, orgId, ctx) {
+        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 = {};
+                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,
@@ -15,6 +57,123 @@ export class TaxService {
         }
         return this.adapter.calculateTax(params);
     }
+    /** Per-line class-based tax with cart-discount pro-ration (issue #57). */
+    async calculateByClasses(params, classes, ctx) {
+        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 = {};
+        const lines = [];
+        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] ?? {
+                    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, actor, ctx) {
+        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, ctx) {
+        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, patch, actor, ctx) {
+        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, actor, ctx) {
+        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 });
+    }
+    async matchRuntimeRates(orgId, toAddress, ctx) {
+        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) {
         if (!this.adapter)
             return Ok({ transactionId: params.transactionId });
@@ -31,4 +190,70 @@ export class TaxService {
         }
         return Ok(this.adapter);
     }
+    // ── Runtime tax-rate management (issue #45) ────────────────────────────
+    requireRepository() {
+        if (!this.repository) {
+            return Err(new CommerceValidationError("Tax rate persistence is not available."));
+        }
+        return Ok(this.repository);
+    }
+    async createTaxRate(input, actor, ctx) {
+        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, ctx) {
+        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, patch, actor, ctx) {
+        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, actor, ctx) {
+        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/dist/runtime/kernel-modules.d.ts

@@ -179,6 +179,13 @@ export declare const KERNEL_ALL_MODULES: {
             dialect: "pg";
         }>;
     }, import("../index.js").AuditService, Record<string, unknown>>;
+    readonly settings: AppModule<{
+        storeSettings: typeof import("../modules/settings/schema.js").storeSettings;
+    }, import("../modules/settings/service.js").SettingsService, Record<string, never>>;
+    readonly documents: AppModule<{
+        invoiceSequences: typeof import("../modules/documents/schema.js").invoiceSequences;
+        orderDocuments: typeof import("../modules/documents/schema.js").orderDocuments;
+    }, import("../modules/documents/service.js").DocumentsService, Record<string, never>>;
     readonly webhooks: AppModule<{
         webhookEndpoints: import("drizzle-orm/pg-core").PgTableWithColumns<{
             name: "webhook_endpoints";
@@ -1701,10 +1708,16 @@ export declare const KERNEL_ALL_MODULES: {
     readonly search: AppModule<Record<string, never>, import("../modules/search/service.js").SearchService, {
         catalog: import("../modules/catalog/service.js").CatalogServiceImpl;
     }>;
-    readonly shipping: AppModule<Record<string, never>, import("../modules/shipping/service.js").ShippingService, {
+    readonly shipping: AppModule<{
+        shippingZones: typeof import("../modules/shipping/schema.js").shippingZones;
+        shippingRates: typeof import("../modules/shipping/schema.js").shippingRates;
+    }, import("../modules/shipping/service.js").ShippingService, {
         catalog: import("../modules/catalog/service.js").CatalogServiceImpl;
     }>;
-    readonly tax: AppModule<Record<string, never>, import("../modules/tax/service.js").TaxService, Record<string, never>>;
+    readonly tax: AppModule<{
+        taxRates: typeof import("../modules/tax/schema.js").taxRates;
+        taxClasses: typeof import("../modules/tax/schema.js").taxClasses;
+    }, import("../modules/tax/service.js").TaxService, Record<string, never>>;
     readonly payments: AppModule<Record<string, never>, import("../modules/payments/service.js").PaymentsService, Record<string, never>>;
     readonly analytics: AppModule<Record<string, never>, import("../modules/analytics/service.js").AnalyticsService, Record<string, never>>;
 };

package/dist/runtime/kernel-modules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-modules.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAoB3D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBrB,CAAC;AAEX,2FAA2F;AAC3F,wBAAgB,wBAAwB,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAoBpE;AAED,wBAAgB,8BAA8B,IAAI,SAAS,MAAM,EAAE,CAElE"}
+{"version":3,"file":"kernel-modules.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAsB3D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoBrB,CAAC;AAEX,2FAA2F;AAC3F,wBAAgB,wBAAwB,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAoBpE;AAED,wBAAgB,8BAA8B,IAAI,SAAS,MAAM,EAAE,CAElE"}

package/dist/runtime/kernel-modules.js

@@ -4,6 +4,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";
@@ -13,11 +14,14 @@ 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/dist/runtime/kernel-types.d.ts

@@ -16,6 +16,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";
@@ -51,6 +53,8 @@ export interface Kernel {
         tax: TaxService;
         shipping: ShippingService;
         search: SearchService;
+        settings: SettingsService;
+        documents: DocumentsService;
         audit: AuditService;
         compensationFailures: CompensationFailuresRepository;
         email: CommerceConfig["email"];
@@ -59,7 +63,7 @@ export interface Kernel {
     pluginPermissions: PluginPermission[];
     logger: ReturnType<typeof createLogger>;
 }
-export declare const KERNEL_REQUIRED_SERVICE_KEYS: ["catalog", "inventory", "media", "cart", "orders", "payments", "fulfillment", "customers", "webhooks", "analytics", "pricing", "promotions", "tax", "shipping", "search", "audit", "compensationFailures"];
+export declare const KERNEL_REQUIRED_SERVICE_KEYS: ["catalog", "inventory", "media", "cart", "orders", "payments", "fulfillment", "customers", "webhooks", "analytics", "pricing", "promotions", "tax", "shipping", "search", "settings", "documents", "audit", "compensationFailures"];
 export declare function assertKernelServicesReady(services: Partial<Kernel["services"]>): asserts services is Kernel["services"];
 export declare function assertSortedBefore(topo: readonly string[], a: string, b: string): void;
 //# sourceMappingURL=kernel-types.d.ts.map

package/dist/runtime/kernel-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-types.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kernel-types.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/kernel-types.js

@@ -14,6 +14,8 @@ export const KERNEL_REQUIRED_SERVICE_KEYS = [
     "tax",
     "shipping",
     "search",
+    "settings",
+    "documents",
     "audit",
     "compensationFailures",
 ];

package/dist/runtime/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOhD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMzD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItE,KAAK,SAAS,GAAG;IACf,SAAS,EAAE;QACT,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAMvC;AAeD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc;;;;;sBAwVxB,MAAM,UAAU,MAAM;;;;GAgFtD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAOzD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItE,KAAK,SAAS,GAAG;IACf,SAAS,EAAE;QACT,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAMvC;AAeD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc;;;;;sBAuXxB,MAAM,UAAU,MAAM;;;;GAgFtD"}

package/dist/runtime/server.js

@@ -1,11 +1,13 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { cors } from "hono/cors";
 import { csrf } from "hono/csrf";
+import { HTTPException } from "hono/http-exception";
 import { bodyLimit } from "hono/body-limit";
 import { rateLimiter } from "hono-rate-limiter";
 import { createHash } from "node:crypto";
 import { createClientIpResolver } from "./client-ip.js";
 import { authMiddleware } from "../auth/middleware.js";
+import { CommerceCsrfError } from "../kernel/errors.js";
 import { createRestRoutes } from "../interfaces/rest/index.js";
 import { createCustomerPortalRoutes } from "../interfaces/rest/customer-portal.js";
 import { createCommerce } from "./commerce.js";
@@ -138,11 +140,41 @@ export async function createServer(config) {
         maxAge: 86400,
     }));
     // ─── CSRF Protection (F14) ──────────────────────────────────────────
-    app.use("/api/*", csrf({
+    // CSRF defends cookie/session auth, where the browser attaches the credential
+    // ambiently. API-key (x-api-key) and bearer-token requests carry an explicit,
+    // non-ambient credential and are not CSRF-attackable, so the guard is skipped
+    // for them — otherwise a bodyless server-to-server POST (no Origin, no JSON
+    // content-type, e.g. /publish or /archive from the SDK) trips CSRF and 403s
+    // for no security benefit.
+    const csrfGuard = csrf({
         origin: trustedOrigins.length > 0
             ? trustedOrigins
             : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
-    }));
+    });
+    app.use("/api/*", async (c, next) => {
+        const authenticatedByKey = !!c.req.header("x-api-key") ||
+            /^Bearer\s+/i.test(c.req.header("authorization") ?? "");
+        if (authenticatedByKey)
+            return next();
+        // Run only the CSRF origin check here; invoke the real downstream afterwards
+        // so a genuine 403 from a route handler can't be misattributed to CSRF.
+        let passedCsrf = false;
+        try {
+            await csrfGuard(c, async () => {
+                passedCsrf = true;
+            });
+        }
+        catch (err) {
+            if (err instanceof HTTPException && err.status === 403) {
+                throw new CommerceCsrfError("Origin check failed: the request Origin is not in the trusted origins allowlist. " +
+                    "Browser clients must send a trusted Origin; server-to-server callers should authenticate with an API key (x-api-key).");
+            }
+            throw err;
+        }
+        if (!passedCsrf)
+            return;
+        return next();
+    });
     // ─── Body Size Limit (F6) ──────────────────────────────────────────
     // Media uploads (phone photos are 3–8MB) get their own larger limit and are
     // exempt from the global 1MB limit. Everything else stays at 1MB.
@@ -249,7 +281,7 @@ export async function createServer(config) {
     // body-limit stack apply (all are scoped to /api/*).
     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
     const exposeSpec = config.exposeOpenApiSpec ?? !isProd;

package/dist/test-utils/create-plugin-test-app.d.ts

@@ -21,6 +21,7 @@ import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
 import type { CommerceConfig, CommercePlugin } from "../config/types.js";
 import type { Actor } from "../auth/types.js";
 import type { Kernel } from "../runtime/kernel.js";
+import { type AuthInstance } from "../auth/setup.js";
 /**
  * Hono environment type for the test app. Declares the `actor` context
  * variable so c.set("actor", ...) / c.get("actor") are properly typed
@@ -38,6 +39,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;
 }
 /**
  * Creates a fully-wired test application for plugin E2E testing.

package/dist/test-utils/create-plugin-test-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-plugin-test-app.d.ts","sourceRoot":"","sources":["../../src/test-utils/create-plugin-test-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAgBnD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE;QACT,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;KACrB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,GAAG,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC7B,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,EAAE,EAAE,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3D;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,eAAe,GAAE,OAAO,CAAC,cAAc,CAAM,GAC5C,OAAO,CAAC,aAAa,CAAC,CAgFxB"}
+{"version":3,"file":"create-plugin-test-app.d.ts","sourceRoot":"","sources":["../../src/test-utils/create-plugin-test-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAKnD,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAajE;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE;QACT,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;KACrB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,GAAG,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC7B,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,EAAE,EAAE,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,wFAAwF;IACxF,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,eAAe,GAAE,OAAO,CAAC,cAAc,CAAM,GAC5C,OAAO,CAAC,aAAa,CAAC,CAyFxB"}

package/dist/test-utils/create-plugin-test-app.js

@@ -24,6 +24,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 } 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);
 /**
@@ -56,7 +58,10 @@ export async function createPluginTestApp(plugin, configOverrides = {}) {
     // 5. Create OpenAPIHono --- matching production server.ts
     //    Plugin routes register via manifest.ts which calls app.openapi().
     const app = new OpenAPIHono();
-    // 6. Test actor middleware: parse x-test-actor header -> set on context
+    const auth = createAuth(kernel.database, config);
+    // 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) {
@@ -67,9 +72,15 @@ export async function createPluginTestApp(plugin, configOverrides = {}) {
         }
         await next();
     });
-    // 7. Register plugin routes (deferred via config.routes)
+    app.use("*", async (c, next) => {
+        if (c.get("actor"))
+            return next();
+        return authMiddleware(auth, config)(c, next);
+    });
+    // 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;
-    routes?.(app, kernel);
+    routes?.(app, kernel, auth);
     // 8. Error handler matching production server.ts — maps CommerceError
     //    subclasses (CommerceForbiddenError, CommerceNotFoundError, etc.)
     //    to their proper HTTP status codes (403, 404, 409, 422, 503).
@@ -89,5 +100,6 @@ export async function createPluginTestApp(plugin, configOverrides = {}) {
         app,
         kernel,
         db: kernel.database.db,
+        auth,
     };
 }

package/dist/test-utils/rest-api-test-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api-test-utils.d.ts","sourceRoot":"","sources":["../../src/test-utils/rest-api-test-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAOpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,KAAK,SAAS,GAAG;IACf,SAAS,EAAE;QACT,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;KACrB,CAAC;CACH,CAAC;AAiDF;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM,GACtC,OAAO,CAAC;IACT,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACxC,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC,CAqDD;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAEnF;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,KA6BvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,KAS3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,KASzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,WAwBA;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,EACvB,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,qBAYF"}
+{"version":3,"file":"rest-api-test-utils.d.ts","sourceRoot":"","sources":["../../src/test-utils/rest-api-test-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAOpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,KAAK,SAAS,GAAG;IACf,SAAS,EAAE;QACT,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;KACrB,CAAC;CACH,CAAC;AAiDF;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM,GACtC,OAAO,CAAC;IACT,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACxC,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC,CAqDD;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAEnF;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,KAmCvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,KAS3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,KASzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,WAwBA;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,EACvB,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,qBAYF"}

package/dist/test-utils/rest-api-test-utils.js

@@ -133,9 +133,15 @@ export const testActor = {
         "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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -56,8 +56,8 @@
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/auth/setup.ts

@@ -90,6 +90,7 @@ export function createAuth(
             },
           }
         : {}),
+      ...(scope.keyExpiration ? { keyExpiration: scope.keyExpiration } : {}),
     }));
     plugins.push(apiKey(apiKeyConfigs));
   } else if (config.auth?.apiKeys?.enabled) {

package/src/config/defaults.ts

@@ -30,6 +30,11 @@ export const defaultConfig: Partial<CommerceConfig> = {
           "orders:update",
           "cart:create",
           "cart:update",
+          "cart:manage",
+          "shipping:manage",
+          "tax:manage",
+          "settings:manage",
+          "analytics:read",
           "customers:read:self",
           "customers:update:self",
         ],

package/src/config/types.ts

@@ -4,6 +4,7 @@ import type { BeforeHook, AfterHook } from "../kernel/hooks/types.js";
 import type { PaymentAdapter } from "../modules/payments/adapter.js";
 import type { StorageAdapter } from "../modules/media/adapter.js";
 import type { Kernel } from "../runtime/kernel.js";
+import type { AuthInstance } from "../auth/setup.js";
 import type { DatabaseAdapter } from "../kernel/database/adapter.js";
 import type { TaxAdapter } from "../modules/tax/adapter.js";
 import type { SearchAdapter } from "../modules/search/adapter.js";
@@ -102,6 +103,16 @@ export interface ApiKeyScopeDefinition {
     /** Time window in milliseconds. */
     timeWindow: number;
   };
+  /**
+   * Expiry bounds for keys minted under this scope, in DAYS (Better Auth
+   * semantics; fractions allowed — 1/24 = one hour). Better Auth defaults
+   * minExpiresIn to 1 day, which blocks short-lived credentials like
+   * per-shift POS keys (issue #51).
+   */
+  keyExpiration?: {
+    minExpiresIn?: number;
+    maxExpiresIn?: number;
+  };
 }
 
 export interface AuthConfig {
@@ -374,7 +385,12 @@ export interface CommerceConfig {
   hooks?: Record<string, Array<(...args: unknown[]) => unknown>>;
   plugins?: CommercePlugin[];
   middleware?: MiddlewareHandler[];
-  routes?: (app: Hono<any>, kernel: Kernel) => void;
+  /**
+   * Custom route registration. Receives the Better Auth instance as the
+   * third argument so integrations can mint/revoke API keys or call
+   * `auth.api.*` without module-global holder shims.
+   */
+  routes?: (app: Hono<any>, kernel: Kernel, auth?: AuthInstance) => void;
   /** Log level for structured logging. Default: "info". */
   logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace";
   /**

package/src/generated/plugin-capabilities.d.ts

@@ -4,6 +4,7 @@
 export interface PluginCapabilityRegistryShape {
   "appointments": Record<string, unknown>;
   "gift-cards": Record<string, unknown>;
+  "layaway": Record<string, unknown>;
   "loyalty": Record<string, unknown>;
   "marketplace": Record<string, unknown>;
   "notifications": Record<string, unknown>;

package/src/generated/plugin-manifest.ts

@@ -5,6 +5,7 @@
 export const resolvedPluginManifest = [
   { id: "appointments", directory: "plugin-appointments" },
   { id: "gift-cards", directory: "plugin-gift-cards" },
+  { id: "layaway", directory: "plugin-layaway" },
   { id: "loyalty", directory: "plugin-loyalty" },
   { id: "marketplace", directory: "plugin-marketplace" },
   { id: "notifications", directory: "plugin-notifications" },