@porulle/core 0.7.0 → 0.8.0

package/dist/interfaces/rest/schemas/tax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tax.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/schemas/tax.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAe,MAAM,mBAAmB,CAAC;AAGnD,eAAO,MAAM,uBAAuB;;;;;;;;iBAQF,CAAC;AAEnC,eAAO,MAAM,uBAAuB;;;;;;;;iBAQF,CAAC;AAQnC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAY7B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAS5B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAa7B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAU7B,CAAC;AAIH,eAAO,MAAM,wBAAwB;;;;;iBAKF,CAAC;AAEpC,eAAO,MAAM,wBAAwB;;;;;iBAKF,CAAC;AAIpC,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAU9B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAS9B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAa9B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAU9B,CAAC"}

package/dist/interfaces/rest/schemas/tax.js

@@ -0,0 +1,132 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+export const CreateTaxRateBodySchema = z.object({
+    name: z.string().min(1).openapi({ example: "NY sales tax" }),
+    country: z.string().min(1).openapi({ example: "US", description: "ISO 3166-1 alpha-2; \"*\" matches any country" }),
+    state: z.string().min(1).optional().openapi({ example: "NY" }),
+    rateBps: z.number().int().nonnegative().openapi({ example: 500, description: "Basis points: 500 = 5%" }),
+    appliesToShipping: z.boolean().optional(),
+    priority: z.number().int().optional(),
+    isActive: z.boolean().optional(),
+}).openapi("CreateTaxRateRequest");
+export const UpdateTaxRateBodySchema = z.object({
+    name: z.string().min(1).optional(),
+    country: z.string().min(1).optional(),
+    state: z.string().min(1).nullable().optional(),
+    rateBps: z.number().int().nonnegative().optional(),
+    appliesToShipping: z.boolean().optional(),
+    priority: z.number().int().optional(),
+    isActive: z.boolean().optional(),
+}).openapi("UpdateTaxRateRequest");
+const IdParam = z.object({
+    id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+const DataResponse = z.object({ data: z.any() }).openapi("TaxConfigResponse");
+export const createTaxRateRoute = createRoute({
+    method: "post",
+    path: "/rates",
+    tags: ["Tax"],
+    summary: "Create a tax rate",
+    request: {
+        body: { content: { "application/json": { schema: CreateTaxRateBodySchema } }, required: true },
+    },
+    responses: {
+        201: { content: { "application/json": { schema: DataResponse } }, description: "Tax rate created." },
+        ...errorResponses,
+    },
+});
+export const listTaxRatesRoute = createRoute({
+    method: "get",
+    path: "/rates",
+    tags: ["Tax"],
+    summary: "List tax rates",
+    responses: {
+        200: { content: { "application/json": { schema: DataResponse } }, description: "Tax rates" },
+        ...errorResponses,
+    },
+});
+export const updateTaxRateRoute = createRoute({
+    method: "patch",
+    path: "/rates/{id}",
+    tags: ["Tax"],
+    summary: "Update a tax rate",
+    request: {
+        params: IdParam,
+        body: { content: { "application/json": { schema: UpdateTaxRateBodySchema } }, required: true },
+    },
+    responses: {
+        200: { content: { "application/json": { schema: DataResponse } }, description: "Tax rate updated." },
+        ...errorResponses,
+    },
+});
+export const deleteTaxRateRoute = createRoute({
+    method: "delete",
+    path: "/rates/{id}",
+    tags: ["Tax"],
+    summary: "Delete a tax rate",
+    request: { params: IdParam },
+    responses: {
+        200: { content: { "application/json": { schema: DataResponse } }, description: "Tax rate deleted." },
+        ...errorResponses,
+    },
+});
+// ── Product tax classes (issue #57) ─────────────────────────────────────────
+export const CreateTaxClassBodySchema = z.object({
+    name: z.string().min(1).regex(/^[a-z][a-z0-9_-]*$/, "lowercase slug (e.g. standard, zero)"),
+    rateBps: z.number().int().nonnegative().openapi({ example: 1800, description: "Basis points: 1800 = 18%" }),
+    isDefault: z.boolean().optional().openapi({ description: "Lines with no taxClass use the default class." }),
+    isActive: z.boolean().optional(),
+}).openapi("CreateTaxClassRequest");
+export const UpdateTaxClassBodySchema = z.object({
+    name: z.string().min(1).regex(/^[a-z][a-z0-9_-]*$/).optional(),
+    rateBps: z.number().int().nonnegative().optional(),
+    isDefault: z.boolean().optional(),
+    isActive: z.boolean().optional(),
+}).openapi("UpdateTaxClassRequest");
+const ClassIdParam = z.object({ id: z.uuid() });
+export const createTaxClassRoute = createRoute({
+    method: "post",
+    path: "/classes",
+    tags: ["Tax"],
+    summary: "Create a product tax class",
+    request: { body: { content: { "application/json": { schema: CreateTaxClassBodySchema } }, required: true } },
+    responses: {
+        201: { content: { "application/json": { schema: DataResponse } }, description: "Tax class created." },
+        ...errorResponses,
+    },
+});
+export const listTaxClassesRoute = createRoute({
+    method: "get",
+    path: "/classes",
+    tags: ["Tax"],
+    summary: "List product tax classes",
+    responses: {
+        200: { content: { "application/json": { schema: DataResponse } }, description: "Tax classes." },
+        ...errorResponses,
+    },
+});
+export const updateTaxClassRoute = createRoute({
+    method: "patch",
+    path: "/classes/{id}",
+    tags: ["Tax"],
+    summary: "Update a product tax class",
+    request: {
+        params: ClassIdParam,
+        body: { content: { "application/json": { schema: UpdateTaxClassBodySchema } }, required: true },
+    },
+    responses: {
+        200: { content: { "application/json": { schema: DataResponse } }, description: "Tax class updated." },
+        ...errorResponses,
+    },
+});
+export const deleteTaxClassRoute = createRoute({
+    method: "delete",
+    path: "/classes/{id}",
+    tags: ["Tax"],
+    summary: "Delete a product tax class",
+    request: { params: ClassIdParam },
+    responses: {
+        200: { content: { "application/json": { schema: DataResponse } }, description: "Tax class deleted." },
+        ...errorResponses,
+    },
+});

package/dist/kernel/database/schema.d.ts

@@ -20,6 +20,10 @@ export * from "../../modules/promotions/schema.js";
 export * from "../../modules/media/schema.js";
 export * from "../../modules/webhooks/schema.js";
 export * from "../../modules/fulfillment/schema.js";
+export * from "../../modules/shipping/schema.js";
+export * from "../../modules/tax/schema.js";
+export * from "../../modules/settings/schema.js";
+export * from "../../modules/documents/schema.js";
 export * from "../jobs/schema.js";
 export * from "../compensation/schema.js";
 export * from "../../modules/audit/schema.js";

package/dist/kernel/database/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,cAAc,2BAA2B,CAAC;AAG1C,cAAc,iCAAiC,CAAC;AAGhD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,8BAA8B,CAAC;AAG7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mCAAmC,CAAC;AAGlD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,iCAAiC,CAAC;AAGhD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,+BAA+B,CAAC;AAG9C,cAAc,kCAAkC,CAAC;AAGjD,cAAc,qCAAqC,CAAC;AAGpD,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,cAAc,2BAA2B,CAAC;AAG1C,cAAc,iCAAiC,CAAC;AAGhD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,8BAA8B,CAAC;AAG7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mCAAmC,CAAC;AAGlD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,iCAAiC,CAAC;AAGhD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,+BAA+B,CAAC;AAG9C,cAAc,kCAAkC,CAAC;AAGjD,cAAc,qCAAqC,CAAC;AAGpD,cAAc,kCAAkC,CAAC;AAGjD,cAAc,6BAA6B,CAAC;AAG5C,cAAc,kCAAkC,CAAC;AAGjD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,+BAA+B,CAAC"}

package/dist/kernel/database/schema.js

@@ -31,6 +31,14 @@ export * from "../../modules/media/schema.js";
 export * from "../../modules/webhooks/schema.js";
 // Fulfillment module
 export * from "../../modules/fulfillment/schema.js";
+// Shipping module (runtime zones & rates)
+export * from "../../modules/shipping/schema.js";
+// Tax module (runtime tax rates)
+export * from "../../modules/tax/schema.js";
+// Settings module (org-scoped runtime settings)
+export * from "../../modules/settings/schema.js";
+// Documents module (fiscal sequences + issued documents)
+export * from "../../modules/documents/schema.js";
 // Jobs (kernel)
 export * from "../jobs/schema.js";
 // Compensation failures (kernel)

package/dist/kernel/hooks/types.d.ts

@@ -1,7 +1,7 @@
 import type { Actor } from "../../auth/types.js";
 import type { JobsAdapter } from "../jobs/adapter.js";
 import type { PluginDb } from "../database/plugin-types.js";
-export type HookOperation = "create" | "update" | "delete" | "read" | "list" | "statusChange" | "addItem" | "removeItem" | "custom";
+export type HookOperation = "create" | "update" | "delete" | "read" | "list" | "statusChange" | "addItem" | "removeItem" | "recover" | "custom";
 export interface Logger {
     info(message: string, data?: unknown): void;
     warn(message: string, data?: unknown): void;

package/dist/kernel/hooks/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,cAAc,GACd,SAAS,GACT,YAAY,GACZ,QAAQ,CAAC;AAEb,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,UAAU,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;AAE7B,MAAM,MAAM,SAAS,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,cAAc,GACd,SAAS,GACT,YAAY,GACZ,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,UAAU,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;AAE7B,MAAM,MAAM,SAAS,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC"}

package/dist/kernel/plugin/manifest.d.ts

@@ -41,6 +41,14 @@ export interface PluginContext {
         transaction<T>(fn: (tx: PluginDb) => Promise<T>): Promise<T>;
     };
     logger: PluginLogger;
+    /**
+     * The Better Auth instance (issue #51) — lets plugins mint/revoke
+     * credentials (e.g. per-shift API keys from a POS PIN login). Present when
+     * routes are mounted by createServer; may be absent in bare-kernel setups,
+     * so plugins must degrade gracefully. Typed loosely to avoid coupling every
+     * plugin to Better Auth's generics — cast to the narrow surface you use.
+     */
+    auth?: unknown;
 }
 export type { PluginPermission };
 export interface CommercePluginManifest {
@@ -68,6 +76,21 @@ export interface CommercePluginManifest {
     hooks?: () => PluginHookRegistration[];
     routes?: (ctx: PluginContext) => PluginRouteRegistration[];
     analyticsModels?: () => unknown[];
+    /**
+     * Named API-key scopes this plugin mints credentials under (issue #51),
+     * merged into `config.auth.apiKeyScopes`. User-defined scopes with the
+     * same name win.
+     */
+    apiKeyScopes?: () => Record<string, {
+        prefix?: string;
+        description?: string;
+        permissions?: Record<string, string[]>;
+        /** Expiry bounds in DAYS (fractions allowed — 1/24 = one hour). */
+        keyExpiration?: {
+            minExpiresIn?: number;
+            maxExpiresIn?: number;
+        };
+    }>;
 }
 export declare const _registeredPlugins: Set<string>;
 /** @internal — called by defineConfig() before applying plugins */

package/dist/kernel/plugin/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAS5D,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAI/B,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAAE,GAC1E;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CAC1C;AAID,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE;QACR,0EAA0E;QAC1E,EAAE,EAAE,QAAQ,CAAC;QACb;;;WAGG;QACH,QAAQ,EAAE,QAAQ,CAAC;QACnB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KAC9D,CAAC;IACF,MAAM,EAAE,YAAY,CAAC;CACtB;AAqDD,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,sBAAsB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,uBAAuB,EAAE,CAAC;IAC3D,eAAe,CAAC,EAAE,MAAM,OAAO,EAAE,CAAC;CACnC;AAKD,eAAO,MAAM,kBAAkB,aAAoB,CAAC;AAEpD,mEAAmE;AACnE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,GAC/B,cAAc,CAkJhB"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/manifest.ts"],"names":[],"mappings":"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"}

package/dist/kernel/plugin/manifest.js

@@ -83,6 +83,20 @@ export function defineCommercePlugin(manifest) {
                 pluginPermissions: [...(result.pluginPermissions ?? []), ...withPlugin],
             };
         }
+        // 0. API-key scopes — merge into auth.apiKeyScopes (user config wins)
+        if (manifest.apiKeyScopes) {
+            const scopes = manifest.apiKeyScopes();
+            result = {
+                ...result,
+                auth: {
+                    ...(result.auth ?? {}),
+                    apiKeyScopes: {
+                        ...scopes,
+                        ...(result.auth?.apiKeyScopes ?? {}),
+                    },
+                },
+            };
+        }
         // 1. Schema — push into customSchemas for kernel to register
         if (manifest.schema) {
             const schemas = manifest.schema();
@@ -108,8 +122,8 @@ export function defineCommercePlugin(manifest) {
             const pluginRoutes = manifest.routes;
             result = {
                 ...result,
-                routes: (app, kernel) => {
-                    existingRoutes?.(app, kernel);
+                routes: (app, kernel, auth) => {
+                    existingRoutes?.(app, kernel, auth);
                     const k = kernel;
                     // Narrow DatabaseAdapter<unknown> → PluginContext.database once here.
                     // All plugin code receives typed PluginDb — no casts downstream.
@@ -118,6 +132,7 @@ export function defineCommercePlugin(manifest) {
                         services: k.services,
                         database: buildPluginContextDatabase(k.database.db, k.database.transaction, k.config, k.logger),
                         logger: k.logger,
+                        ...(auth !== undefined ? { auth } : {}),
                     });
                     for (const route of regs) {
                         // ── Error boundary: wrap handler with plugin context ──

package/dist/modules/analytics/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../src/modules/analytics/module.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,eAAO,MAAM,eAAe,mHAiB1B,CAAC"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../src/modules/analytics/module.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,eAAO,MAAM,eAAe,mHAyB1B,CAAC"}

package/dist/modules/analytics/module.js

@@ -1,6 +1,7 @@
 import { defineModule } from "../../kernel/module/index.js";
 import { DrizzleAnalyticsAdapter } from "./drizzle-adapter.js";
 import { BUILTIN_ANALYTICS_MODELS } from "./models.js";
+import { RetailReportsEngine } from "./reports.js";
 import { AnalyticsService } from "./service.js";
 export const analyticsModule = defineModule({
     id: "analytics",
@@ -10,9 +11,14 @@ export const analyticsModule = defineModule({
         for (const model of BUILTIN_ANALYTICS_MODELS) {
             adapter.registerModel(model);
         }
+        // Settings is resolved lazily from the shared service container — the
+        // settings module may instantiate after analytics.
+        const services = deps.services;
+        const reports = new RetailReportsEngine(deps.db.db, (orgId, group) => services.settings.read(orgId, group));
         return new AnalyticsService({
             adapter,
             config: deps.config,
+            reports,
         });
     },
 });

package/dist/modules/analytics/reports.d.ts

@@ -0,0 +1,58 @@
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { type Result } from "../../kernel/result.js";
+/**
+ * Canned retail reports (issue #48).
+ *
+ * Parameterized SQL over core tables, org-scoped, with all calendar math done
+ * by Postgres in the store's timezone (settings.general.timezone, default
+ * UTC). Range reports include a prior period of equal length with deltas.
+ */
+export interface ReportParams {
+    /** Local calendar date (YYYY-MM-DD) for single-day reports. Default: today in store tz. */
+    date?: string;
+    /** Local range start (YYYY-MM-DD, inclusive). Default: first of current month in store tz. */
+    from?: string;
+    /** Local range end (YYYY-MM-DD, inclusive). Default: today in store tz. */
+    to?: string;
+}
+export declare const RETAIL_REPORTS: readonly [{
+    readonly name: "daily-journal";
+    readonly description: "Per-day sales journal: order rows + summary with prior-day deltas.";
+}, {
+    readonly name: "tax-summary";
+    readonly description: "Tax collected over a range, bucketed per local day, with prior-period deltas.";
+}, {
+    readonly name: "inventory-aging";
+    readonly description: "On-hand stock bucketed by days since last restock (0-30/31-60/61-90/90+).";
+}, {
+    readonly name: "sell-through";
+    readonly description: "Units sold in the range vs current on-hand, per entity.";
+}, {
+    readonly name: "reorder-needed";
+    readonly description: "Inventory rows at or below their reorder threshold.";
+}, {
+    readonly name: "staff-sales";
+    readonly description: "Orders and revenue grouped by orders.metadata.staffId.";
+}];
+export type RetailReportName = (typeof RETAIL_REPORTS)[number]["name"];
+type SettingsReader = (orgId: string, group: string) => Promise<Record<string, unknown>>;
+export declare class RetailReportsEngine {
+    private readonly db;
+    private readonly readSettings;
+    constructor(db: DrizzleDatabase, readSettings: SettingsReader);
+    run(name: string, params: ReportParams, orgId: string): Promise<Result<Record<string, unknown>>>;
+    private timezoneFor;
+    private rangeOrDefault;
+    private rows;
+    private journalSummary;
+    private dailyJournal;
+    private taxSummary;
+    private inventoryAging;
+    private sellThrough;
+    private reorderNeeded;
+    private staffSales;
+}
+/** Today's local calendar date (YYYY-MM-DD) in an IANA timezone. */
+export declare function localToday(tz: string): string;
+export {};
+//# sourceMappingURL=reports.d.ts.map

package/dist/modules/analytics/reports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.d.ts","sourceRoot":"","sources":["../../../src/modules/analytics/reports.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAE3E,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;EAOjB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAMvE,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAWzF,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBADZ,EAAE,EAAE,eAAe,EACnB,YAAY,EAAE,cAAc;IAGzC,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;YAoC7B,WAAW;IAKzB,OAAO,CAAC,cAAc;YAKR,IAAI;YAcJ,cAAc;YAqBd,YAAY;YAyBZ,UAAU;YA8BV,cAAc;YA4Bd,WAAW;YA4BX,aAAa;YAmBb,UAAU;CAezB;AAID,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/modules/analytics/reports.js

@@ -0,0 +1,249 @@
+import { sql } from "drizzle-orm";
+import { CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok } from "../../kernel/result.js";
+export const RETAIL_REPORTS = [
+    { name: "daily-journal", description: "Per-day sales journal: order rows + summary with prior-day deltas." },
+    { name: "tax-summary", description: "Tax collected over a range, bucketed per local day, with prior-period deltas." },
+    { name: "inventory-aging", description: "On-hand stock bucketed by days since last restock (0-30/31-60/61-90/90+)." },
+    { name: "sell-through", description: "Units sold in the range vs current on-hand, per entity." },
+    { name: "reorder-needed", description: "Inventory rows at or below their reorder threshold." },
+    { name: "staff-sales", description: "Orders and revenue grouped by orders.metadata.staffId." },
+];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// Orders excluded from financial reports.
+const EXCLUDED_STATUSES = ["cancelled", "voided"];
+export class RetailReportsEngine {
+    db;
+    readSettings;
+    constructor(db, readSettings) {
+        this.db = db;
+        this.readSettings = readSettings;
+    }
+    async run(name, params, orgId) {
+        for (const value of [params.date, params.from, params.to]) {
+            if (value !== undefined && !DATE_RE.test(value)) {
+                return Err(new CommerceValidationError("Dates must be YYYY-MM-DD."));
+            }
+        }
+        const tz = await this.timezoneFor(orgId);
+        switch (name) {
+            case "daily-journal":
+                return Ok(await this.dailyJournal(orgId, tz, params.date ?? localToday(tz)));
+            case "tax-summary": {
+                const [from, to] = this.rangeOrDefault(params, tz);
+                return Ok(await this.taxSummary(orgId, tz, from, to));
+            }
+            case "inventory-aging":
+                return Ok(await this.inventoryAging(orgId));
+            case "sell-through": {
+                const [from, to] = this.rangeOrDefault(params, tz);
+                return Ok(await this.sellThrough(orgId, tz, from, to));
+            }
+            case "reorder-needed":
+                return Ok(await this.reorderNeeded(orgId));
+            case "staff-sales": {
+                const [from, to] = this.rangeOrDefault(params, tz);
+                return Ok(await this.staffSales(orgId, tz, from, to));
+            }
+            default:
+                return Err(new CommerceValidationError(`Unknown report "${name}". Available: ${RETAIL_REPORTS.map((r) => r.name).join(", ")}.`));
+        }
+    }
+    async timezoneFor(orgId) {
+        const general = await this.readSettings(orgId, "general");
+        return typeof general.timezone === "string" ? general.timezone : "UTC";
+    }
+    rangeOrDefault(params, tz) {
+        const today = localToday(tz);
+        return [params.from ?? `${today.slice(0, 8)}01`, params.to ?? today];
+    }
+    async rows(query) {
+        const result = await this.db.execute(query);
+        const raw = Array.isArray(result)
+            ? result
+            : (result.rows ?? []);
+        return raw.map((row) => {
+            const mapped = {};
+            for (const [key, value] of Object.entries(row)) {
+                mapped[key] = typeof value === "bigint" ? Number(value) : value;
+            }
+            return mapped;
+        });
+    }
+    async journalSummary(orgId, tz, from, to) {
+        const rows = await this.rows(sql `
+      SELECT count(*)::int AS "orderCount",
+             COALESCE(sum(grand_total), 0)::int AS "grossSales",
+             COALESCE(sum(subtotal), 0)::int AS "subtotal",
+             COALESCE(sum(discount_total), 0)::int AS "discounts",
+             COALESCE(sum(tax_total), 0)::int AS "tax",
+             COALESCE(sum(shipping_total), 0)::int AS "shipping"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql `${s}`), sql `, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+    `);
+        return rows[0];
+    }
+    async dailyJournal(orgId, tz, date) {
+        const summary = await this.journalSummary(orgId, tz, date, date);
+        const previousDate = shiftDate(date, -1);
+        const previous = await this.journalSummary(orgId, tz, previousDate, previousDate);
+        const orders = await this.rows(sql `
+      SELECT order_number AS "orderNumber", status, currency,
+             grand_total AS "grandTotal", tax_total AS "tax",
+             discount_total AS "discounts", placed_at AS "placedAt"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql `${s}`), sql `, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date = ${date}::date
+      ORDER BY placed_at ASC
+    `);
+        return {
+            report: "daily-journal",
+            timezone: tz,
+            date,
+            summary,
+            previous,
+            delta: deltas(summary, previous),
+            orders,
+        };
+    }
+    async taxSummary(orgId, tz, from, to) {
+        const days = await this.rows(sql `
+      SELECT to_char((placed_at AT TIME ZONE ${tz})::date, 'YYYY-MM-DD') AS "day",
+             count(*)::int AS "orderCount",
+             COALESCE(sum(tax_total), 0)::int AS "tax",
+             COALESCE(sum(grand_total), 0)::int AS "gross"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql `${s}`), sql `, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+      GROUP BY 1
+      ORDER BY 1
+    `);
+        const totals = await this.journalSummary(orgId, tz, from, to);
+        const lengthDays = daysBetween(from, to) + 1;
+        const prevFrom = shiftDate(from, -lengthDays);
+        const prevTo = shiftDate(to, -lengthDays);
+        const previous = await this.journalSummary(orgId, tz, prevFrom, prevTo);
+        return {
+            report: "tax-summary",
+            timezone: tz,
+            from,
+            to,
+            totals,
+            previous: { from: prevFrom, to: prevTo, ...previous },
+            delta: deltas(totals, previous),
+            days,
+        };
+    }
+    async inventoryAging(orgId) {
+        const rows = await this.rows(sql `
+      SELECT il.entity_id AS "entityId", il.variant_id AS "variantId",
+             e.slug AS "slug",
+             il.quantity_on_hand AS "quantityOnHand",
+             il.quantity_reserved AS "quantityReserved",
+             GREATEST(0, EXTRACT(day FROM now() - COALESCE(il.last_restocked_at, il.updated_at)))::int AS "ageDays"
+      FROM inventory_levels il
+      LEFT JOIN sellable_entities e ON e.id = il.entity_id
+      WHERE il.organization_id = ${orgId} AND il.quantity_on_hand > 0
+      ORDER BY "ageDays" DESC
+    `);
+        const buckets = [
+            { bucket: "0-30", min: 0, max: 30 },
+            { bucket: "31-60", min: 31, max: 60 },
+            { bucket: "61-90", min: 61, max: 90 },
+            { bucket: "90+", min: 91, max: Infinity },
+        ].map(({ bucket, min, max }) => {
+            const inBucket = rows.filter((r) => r.ageDays >= min && r.ageDays <= max);
+            return {
+                bucket,
+                skuCount: inBucket.length,
+                quantityOnHand: inBucket.reduce((sum, r) => sum + r.quantityOnHand, 0),
+            };
+        });
+        return { report: "inventory-aging", buckets, rows };
+    }
+    async sellThrough(orgId, tz, from, to) {
+        const rows = await this.rows(sql `
+      SELECT li.entity_id AS "entityId",
+             min(li.title) AS "title",
+             sum(li.quantity)::int AS "unitsSold",
+             COALESCE((SELECT sum(quantity_on_hand)::int FROM inventory_levels il
+                       WHERE il.entity_id = li.entity_id AND il.organization_id = ${orgId}), 0) AS "onHand"
+      FROM order_line_items li
+      JOIN orders o ON o.id = li.order_id
+      WHERE o.organization_id = ${orgId}
+        AND o.status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql `${s}`), sql `, `)})
+        AND (o.placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+      GROUP BY li.entity_id
+      ORDER BY "unitsSold" DESC
+    `);
+        return {
+            report: "sell-through",
+            timezone: tz,
+            from,
+            to,
+            rows: rows.map((r) => {
+                const sold = r.unitsSold;
+                const onHand = r.onHand;
+                return { ...r, sellThroughRate: sold + onHand > 0 ? sold / (sold + onHand) : 0 };
+            }),
+        };
+    }
+    async reorderNeeded(orgId) {
+        const rows = await this.rows(sql `
+      SELECT il.entity_id AS "entityId", il.variant_id AS "variantId",
+             il.warehouse_id AS "warehouseId", e.slug AS "slug",
+             il.quantity_on_hand AS "quantityOnHand",
+             il.quantity_reserved AS "quantityReserved",
+             (il.quantity_on_hand - il.quantity_reserved) AS "available",
+             il.reorder_threshold AS "reorderThreshold",
+             il.reorder_quantity AS "reorderQuantity"
+      FROM inventory_levels il
+      LEFT JOIN sellable_entities e ON e.id = il.entity_id
+      WHERE il.organization_id = ${orgId}
+        AND il.reorder_threshold IS NOT NULL
+        AND (il.quantity_on_hand - il.quantity_reserved) <= il.reorder_threshold
+      ORDER BY "available" ASC
+    `);
+        return { report: "reorder-needed", rows };
+    }
+    async staffSales(orgId, tz, from, to) {
+        const rows = await this.rows(sql `
+      SELECT COALESCE(metadata->>'staffId', 'unattributed') AS "staffId",
+             count(*)::int AS "orderCount",
+             COALESCE(sum(grand_total), 0)::int AS "revenue",
+             COALESCE(sum(discount_total), 0)::int AS "discounts"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql `${s}`), sql `, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+      GROUP BY 1
+      ORDER BY "revenue" DESC
+    `);
+        return { report: "staff-sales", timezone: tz, from, to, rows };
+    }
+}
+// ── Pure date helpers (calendar dates, no time component) ──────────────────
+/** Today's local calendar date (YYYY-MM-DD) in an IANA timezone. */
+export function localToday(tz) {
+    return new Intl.DateTimeFormat("en-CA", { timeZone: tz }).format(new Date());
+}
+function shiftDate(date, days) {
+    const d = new Date(`${date}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + days);
+    return d.toISOString().slice(0, 10);
+}
+function daysBetween(from, to) {
+    const ms = new Date(`${to}T00:00:00Z`).getTime() - new Date(`${from}T00:00:00Z`).getTime();
+    return Math.round(ms / 86_400_000);
+}
+function deltas(current, previous) {
+    const out = {};
+    for (const key of Object.keys(current)) {
+        out[key] = (current[key] ?? 0) - (previous[key] ?? 0);
+    }
+    return out;
+}

package/dist/modules/analytics/service.d.ts

@@ -7,11 +7,14 @@
  */
 import type { CommerceConfig } from "../../config/types.js";
 import { type Result } from "../../kernel/result.js";
+import type { Actor } from "../../auth/types.js";
+import type { ReportParams, RetailReportsEngine } from "./reports.js";
 import type { AnalyticsAdapter, AnalyticsMeta, AnalyticsQueryParams, AnalyticsQueryResult, AnalyticsScope } from "./types.js";
 export type { AnalyticsTimeDimension, AnalyticsFilter, AnalyticsQueryParams, AnalyticsModelDefinition, AnalyticsMeta, } from "./types.js";
 export interface AnalyticsServiceDeps {
     adapter: AnalyticsAdapter;
     config: CommerceConfig;
+    reports?: RetailReportsEngine;
 }
 export declare class AnalyticsService {
     private deps;
@@ -33,6 +36,13 @@ export declare class AnalyticsService {
      */
     query(params: AnalyticsQueryParams, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>>;
     getDashboard(name: string, scope: AnalyticsScope): Promise<Result<AnalyticsQueryResult>>;
+    /** The canned retail reports pack (issue #48). */
+    listReports(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Runs a canned retail report (issue #48), org-scoped to the actor. */
+    getReport(name: string, params: ReportParams, actor?: Actor | null): Promise<Result<Record<string, unknown>>>;
     getMeta(): Promise<Result<AnalyticsMeta>>;
     meta(): Promise<Result<{
         measures: string[];