@porulle/core 0.7.0 → 0.8.0

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

@@ -0,0 +1,164 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+// ─── Request Schemas ────────────────────────────────────────────────────────
+
+export const CreateShippingZoneBodySchema = z.object({
+  name: z.string().min(1).openapi({ example: "United States" }),
+  countries: z.array(z.string().min(1)).min(1).openapi({ example: ["US"] }),
+  states: z.array(z.string().min(1)).optional().openapi({ example: ["NY", "NJ"] }),
+  priority: z.number().int().optional(),
+  isActive: z.boolean().optional(),
+}).openapi("CreateShippingZoneRequest");
+
+export const UpdateShippingZoneBodySchema = z.object({
+  name: z.string().min(1).optional(),
+  countries: z.array(z.string().min(1)).min(1).optional(),
+  states: z.array(z.string().min(1)).optional(),
+  priority: z.number().int().optional(),
+  isActive: z.boolean().optional(),
+}).openapi("UpdateShippingZoneRequest");
+
+export const CreateShippingRateBodySchema = z.object({
+  zoneId: z.uuid(),
+  name: z.string().min(1).openapi({ example: "Standard" }),
+  amount: z.number().int().nonnegative().openapi({ example: 1500, description: "Flat cost in minor units" }),
+  currency: z.string().length(3).optional().openapi({ example: "USD" }),
+  minSubtotal: z.number().int().nonnegative().optional(),
+  maxSubtotal: z.number().int().nonnegative().optional(),
+  minWeightGrams: z.number().int().nonnegative().optional(),
+  maxWeightGrams: z.number().int().nonnegative().optional(),
+  freeShippingThreshold: z.number().int().nonnegative().optional().openapi({ example: 10000, description: "Subtotal at or above which shipping is free" }),
+  isActive: z.boolean().optional(),
+}).openapi("CreateShippingRateRequest");
+
+export const UpdateShippingRateBodySchema = z.object({
+  name: z.string().min(1).optional(),
+  amount: z.number().int().nonnegative().optional(),
+  currency: z.string().length(3).optional(),
+  minSubtotal: z.number().int().nonnegative().nullable().optional(),
+  maxSubtotal: z.number().int().nonnegative().nullable().optional(),
+  minWeightGrams: z.number().int().nonnegative().nullable().optional(),
+  maxWeightGrams: z.number().int().nonnegative().nullable().optional(),
+  freeShippingThreshold: z.number().int().nonnegative().nullable().optional(),
+  isActive: z.boolean().optional(),
+}).openapi("UpdateShippingRateRequest");
+
+// ─── Shared ─────────────────────────────────────────────────────────────────
+
+const IdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+const DataResponse = z.object({ data: z.any() }).openapi("ShippingConfigResponse");
+
+// ─── Zone Routes ────────────────────────────────────────────────────────────
+
+export const createShippingZoneRoute = createRoute({
+  method: "post",
+  path: "/zones",
+  tags: ["Shipping"],
+  summary: "Create a shipping zone",
+  request: {
+    body: { content: { "application/json": { schema: CreateShippingZoneBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Zone created." },
+    ...errorResponses,
+  },
+});
+
+export const listShippingZonesRoute = createRoute({
+  method: "get",
+  path: "/zones",
+  tags: ["Shipping"],
+  summary: "List shipping zones",
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Zones" },
+    ...errorResponses,
+  },
+});
+
+export const updateShippingZoneRoute = createRoute({
+  method: "patch",
+  path: "/zones/{id}",
+  tags: ["Shipping"],
+  summary: "Update a shipping zone",
+  request: {
+    params: IdParam,
+    body: { content: { "application/json": { schema: UpdateShippingZoneBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Zone updated." },
+    ...errorResponses,
+  },
+});
+
+export const deleteShippingZoneRoute = createRoute({
+  method: "delete",
+  path: "/zones/{id}",
+  tags: ["Shipping"],
+  summary: "Delete a shipping zone (and its rates)",
+  request: { params: IdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Zone deleted." },
+    ...errorResponses,
+  },
+});
+
+// ─── Rate Routes ────────────────────────────────────────────────────────────
+
+export const createShippingRateRoute = createRoute({
+  method: "post",
+  path: "/rates",
+  tags: ["Shipping"],
+  summary: "Create a shipping rate in a zone",
+  request: {
+    body: { content: { "application/json": { schema: CreateShippingRateBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Rate created." },
+    ...errorResponses,
+  },
+});
+
+export const listShippingRatesRoute = createRoute({
+  method: "get",
+  path: "/rates",
+  tags: ["Shipping"],
+  summary: "List shipping rates",
+  request: {
+    query: z.object({ zoneId: z.string().optional() }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Rates" },
+    ...errorResponses,
+  },
+});
+
+export const updateShippingRateRoute = createRoute({
+  method: "patch",
+  path: "/rates/{id}",
+  tags: ["Shipping"],
+  summary: "Update a shipping rate",
+  request: {
+    params: IdParam,
+    body: { content: { "application/json": { schema: UpdateShippingRateBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Rate updated." },
+    ...errorResponses,
+  },
+});
+
+export const deleteShippingRateRoute = createRoute({
+  method: "delete",
+  path: "/rates/{id}",
+  tags: ["Shipping"],
+  summary: "Delete a shipping rate",
+  request: { params: IdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Rate deleted." },
+    ...errorResponses,
+  },
+});

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/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,18 @@ 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 };
+  }>;
 }
 
 // ─── Plugin Dependency Tracking ──────────────────────────────────────
@@ -193,6 +213,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 +255,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 +275,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/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,
     });
   },
 });