@porulle/core 0.7.0 → 0.9.0

package/src/interfaces/rest/schemas/tax.ts

@@ -0,0 +1,148 @@
+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/src/kernel/database/schema.ts

@@ -43,6 +43,18 @@ 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";
 

package/src/kernel/database/scoped-db.ts

@@ -3,7 +3,8 @@
  *
  * Wraps a Drizzle PgDatabase instance so that INSERT operations on
  * org-scoped tables automatically include the actor's organizationId,
- * and SELECT ... FROM org-scoped tables constrain rows to that organization.
+ * and SELECT / UPDATE / DELETE against org-scoped tables constrain rows to
+ * that organization — including when the caller supplies no WHERE clause.
  *
  * Plugin route handlers receive this scoped db via PluginContext.database.db
  * (organization resolved per operation from AsyncLocalStorage when used from
@@ -30,6 +31,33 @@ function tableHasOrganizationId(table: unknown): boolean {
   }
 }
 
+/**
+ * Pre-apply the org predicate to a WHERE-able builder (UPDATE/DELETE) and wrap
+ * its `.where()` so a caller-supplied condition is AND-ed with the org filter
+ * rather than replacing it. Pre-applying `orgEq` immediately means a builder
+ * executed with NO caller `.where()` (e.g. `update(t).set(...)`) is still
+ * constrained to the org — it can never touch another tenant's rows.
+ */
+function scopeWhereBuilder(
+  builder: { where: (c: SQL | undefined) => unknown },
+  orgEq: SQL,
+): unknown {
+  const scoped = builder.where(orgEq);
+  return new Proxy(scoped as Record<string, unknown>, {
+    get(st, sp, sr) {
+      const sv = Reflect.get(st, sp, sr);
+      if (sp === "where" && typeof sv === "function") {
+        return (condition?: unknown, ...wRest: unknown[]) => {
+          const c = condition as SQL | undefined;
+          const merged = c ? and(orgEq, c) : orgEq;
+          return (sv as (...a: unknown[]) => unknown).call(st, merged, ...wRest);
+        };
+      }
+      return typeof sv === "function" ? sv.bind(st) : sv;
+    },
+  });
+}
+
 export function createScopedDb<TDb>(rawDb: TDb, orgSource: ScopedOrganizationId): TDb {
   if (!rawDb || typeof rawDb !== "object") return rawDb;
 
@@ -106,6 +134,47 @@ export function createScopedDb<TDb>(rawDb: TDb, orgSource: ScopedOrganizationId)
         };
       }
 
+      if (prop === "update" && typeof value === "function") {
+        return (table: PgTable) => {
+          const builder = value.call(target, table);
+          if (!tableHasOrganizationId(table)) return builder;
+          const orgCol = getTableColumns(table).organizationId;
+          if (!orgCol) return builder;
+          const orgEq = eq(orgCol, resolveOrganizationId(orgSource));
+          // The org filter lives after `.set()`, so wrap `.set()` and scope the
+          // resulting WHERE-able builder.
+          return new Proxy(builder as Record<string, unknown>, {
+            get(t, p, r) {
+              const v = Reflect.get(t, p, r);
+              if (p === "set" && typeof v === "function") {
+                return (data: unknown) => {
+                  const setBuilder = (v as (...a: unknown[]) => unknown).call(t, data);
+                  return scopeWhereBuilder(
+                    setBuilder as { where: (c: SQL | undefined) => unknown },
+                    orgEq,
+                  );
+                };
+              }
+              return typeof v === "function" ? v.bind(t) : v;
+            },
+          });
+        };
+      }
+
+      if (prop === "delete" && typeof value === "function") {
+        return (table: PgTable) => {
+          const builder = value.call(target, table);
+          if (!tableHasOrganizationId(table)) return builder;
+          const orgCol = getTableColumns(table).organizationId;
+          if (!orgCol) return builder;
+          const orgEq = eq(orgCol, resolveOrganizationId(orgSource));
+          return scopeWhereBuilder(
+            builder as { where: (c: SQL | undefined) => unknown },
+            orgEq,
+          );
+        };
+      }
+
       return typeof value === "function" ? value.bind(target) : value;
     },
   }) as TDb;

package/src/kernel/hooks/types.ts

@@ -11,6 +11,7 @@ export type HookOperation =
   | "statusChange"
   | "addItem"
   | "removeItem"
+  | "recover"
   | "custom";
 
 export interface Logger {

package/src/kernel/plugin/manifest.ts

@@ -59,6 +59,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;
 }
 
 const UNSCOPED_WARN_COOLDOWN_MS = 60_000;
@@ -139,6 +147,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 };
+    /** Better Auth ownership model for keys minted under this scope. */
+    references?: "user" | "organization";
+    enableMetadata?: boolean;
+  }>;
 }
 
 // ─── Plugin Dependency Tracking ──────────────────────────────────────
@@ -193,6 +216,21 @@ export function defineCommercePlugin(
       };
     }
 
+    // 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 ?? {}),
+          },
+        },
+      } as CommerceConfig;
+    }
+
     // 1. Schema — push into customSchemas for kernel to register
     if (manifest.schema) {
       const schemas = manifest.schema();
@@ -220,8 +258,8 @@ export function defineCommercePlugin(
       const pluginRoutes = manifest.routes;
       result = {
         ...result,
-        routes: (app: Hono, kernel: Kernel) => {
-          existingRoutes?.(app, kernel);
+        routes: (app: Hono, kernel: Kernel, auth?: unknown) => {
+          existingRoutes?.(app, kernel, auth as never);
           const k = kernel as {
             config: CommerceConfig;
             services: Record<string, unknown>;
@@ -240,6 +278,7 @@ export function defineCommercePlugin(
               k.logger,
             ),
             logger: k.logger,
+            ...(auth !== undefined ? { auth } : {}),
           });
           for (const route of regs) {
             // ── Error boundary: wrap handler with plugin context ──

package/src/modules/analytics/drizzle-adapter.ts

@@ -216,6 +216,17 @@ export class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
       }
     }
 
+    // Validate that requested time dimensions exist in the cube
+    for (const td of params.timeDimensions ?? []) {
+      const shortName = td.dimension.split(".")[1];
+      if (shortName && !cube.dimensions[shortName]) {
+        const available = Object.keys(cube.dimensions).map((d) => `${cubeName}.${d}`).join(", ");
+        return Err(new CommerceValidationError(
+          `Unknown time dimension: "${td.dimension}". Available dimensions for ${cubeName}: ${available}`,
+        ));
+      }
+    }
+
     try {
       const rows = await this.executeQuery(cube, params, scope);
       return Ok({
@@ -330,14 +341,17 @@ export class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
       const shortName = dim.split(".")[1]!;
       const dimDef = cube.dimensions[shortName];
       if (!dimDef) continue;
-      selectParts.push(sql.raw(`${dimDef.sql} AS "${dim}"`));
+      const alias = `${cube.name}.${shortName}`;
+      selectParts.push(sql.raw(`${dimDef.sql} AS "${alias}"`));
       groupByParts.push(sql.raw(dimDef.sql));
     }
 
     // Time dimensions → SELECT + GROUP BY + WHERE (dateRange)
     for (const td of params.timeDimensions ?? []) {
+      const shortName = td.dimension.split(".")[1]!;
       const selectExpr = compileTimeDimensionSelect(cube, td);
-      selectParts.push(sql`${selectExpr} AS ${sql.raw(`"${td.dimension}"`)}`);
+      const alias = `${cube.name}.${shortName}`;
+      selectParts.push(sql`${selectExpr} AS ${sql.raw(`"${alias}"`)}`);
       groupByParts.push(selectExpr);
 
       // Date range filter
@@ -357,7 +371,9 @@ export class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
 
     // Measures → SELECT
     for (const measure of params.measures) {
-      selectParts.push(sql`${compileMeasure(cube, measure)} AS ${sql.raw(`"${measure}"`)}`);
+      const shortName = measure.split(".")[1]!;
+      const alias = `${cube.name}.${shortName}`;
+      selectParts.push(sql`${compileMeasure(cube, measure)} AS ${sql.raw(`"${alias}"`)}`);
     }
 
     // If no select parts (shouldn't happen with validation), bail

package/src/modules/analytics/module.ts

@@ -1,8 +1,10 @@
 import type { CommerceConfig } from "../../config/types.js";
 import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
 import { defineModule } from "../../kernel/module/index.js";
+import type { SettingsService } from "../settings/service.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<
@@ -17,9 +19,17 @@ 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 as Record<string, unknown>;
+    const reports = new RetailReportsEngine(
+      deps.db.db as DrizzleDatabase,
+      (orgId, group) => (services.settings as SettingsService).read(orgId, group),
+    );
     return new AnalyticsService({
       adapter,
       config: deps.config as CommerceConfig,
+      reports,
     });
   },
 });