@unifiedcommerce/core 0.0.1

package/src/auth/org.ts

@@ -0,0 +1,41 @@
+import { OrganizationService } from "../modules/organization/service";
+
+/**
+ * Deterministic ID for the default organization.
+ * Auto-created on kernel boot / test setup for single-tenant deployments.
+ */
+export const DEFAULT_ORG_ID = "org_default";
+
+/**
+ * Extracts the organization ID from an actor.
+ * Falls back to the default org when the actor is null or has no org set.
+ */
+export function resolveOrgId(actor: unknown): string {
+  if (actor != null && typeof actor === "object" && "organizationId" in actor) {
+    const orgId = (actor as { organizationId: unknown }).organizationId;
+    if (typeof orgId === "string") return orgId;
+  }
+  return DEFAULT_ORG_ID;
+}
+
+/**
+ * Ensures the default organization row exists in the database.
+ * Idempotent — safe to call multiple times (no-ops if the row exists).
+ *
+ * Uses OrganizationService which creates both the org row and
+ * (when auth is available) a member record for the creator.
+ *
+ * Accepts `unknown` so callers never need casts — the function
+ * handles the Drizzle type narrowing internally.
+ */
+export async function ensureDefaultOrg(
+  db: unknown,
+  storeName = "Default Store",
+): Promise<void> {
+  const orgService = new OrganizationService(db);
+  await orgService.create({
+    id: DEFAULT_ORG_ID,
+    name: storeName,
+    slug: "default",
+  });
+}

package/src/auth/permissions.ts

@@ -0,0 +1,28 @@
+import { CommerceForbiddenError } from "../kernel/errors";
+import type { Actor } from "./types";
+
+export function assertPermission(actor: Actor | null, required: string): void {
+  if (!actor) {
+    throw new CommerceForbiddenError("Authentication required.");
+  }
+
+  if (actor.permissions.includes("*:*")) return;
+
+  const [resource] = required.split(":");
+  if (resource && actor.permissions.includes(`${resource}:*`)) return;
+  if (actor.permissions.includes(required)) return;
+
+  throw new CommerceForbiddenError(
+    `Permission "${required}" is required. Your role "${actor.role}" does not include this permission.`,
+  );
+}
+
+export function assertOwnership(actor: Actor | null, resourceOwnerId: string | null): void {
+  if (!actor) {
+    throw new CommerceForbiddenError("Authentication required.");
+  }
+  if (actor.permissions.includes("*:*")) return;
+  if (actor.userId !== resourceOwnerId) {
+    throw new CommerceForbiddenError("You do not have access to this resource.");
+  }
+}

package/src/auth/setup.ts

@@ -0,0 +1,160 @@
+import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+import { betterAuth } from "better-auth";
+import type { Role } from "better-auth/plugins/access";
+import { apiKey } from "@better-auth/api-key";
+import { organization, twoFactor, phoneNumber } from "better-auth/plugins";
+import type { CommerceConfig } from "../config/types";
+import type { DatabaseAdapter } from "../kernel/database/adapter";
+import * as authSchema from "./auth-schema";
+
+type BetterAuthDbProvider = "pg" | "mysql" | "sqlite";
+
+function resolveAuthDbProvider(provider: string): BetterAuthDbProvider {
+  if (
+    provider === "postgres" ||
+    provider === "postgresql" ||
+    provider === "pg"
+  ) {
+    return "pg";
+  }
+  if (provider === "mysql") {
+    return "mysql";
+  }
+  if (provider === "sqlite") {
+    return "sqlite";
+  }
+  throw new Error(
+    `Unsupported auth database provider "${provider}". Expected one of: postgres, mysql, sqlite.`,
+  );
+}
+
+interface AuthEmailPayload {
+  user: {
+    email: string;
+    name: string | null;
+  };
+  url: string;
+}
+
+export interface AuthInstance {
+  handler(request: Request): Promise<Response>;
+  api: {
+    getSession(input: { headers: Headers }): Promise<unknown>;
+    verifyApiKey?: (input: { key: string }) => Promise<{
+      userId: string;
+      name?: string | null;
+      permissions?: string[];
+    } | null>;
+    createApiKey?: (input: {
+      userId: string;
+      name?: string;
+      permissions?: string[];
+    }) => Promise<{ key: string; id: string }>;
+    /** Allow access to other Better Auth API methods added by plugins */
+    [key: string]: unknown;
+  };
+  options?: Record<string, unknown>;
+  $context?: Promise<unknown>;
+}
+
+export function createAuth(
+  db: DatabaseAdapter,
+  config: CommerceConfig,
+): AuthInstance {
+  const plugins: Array<
+    | ReturnType<typeof organization>
+    | ReturnType<typeof twoFactor>
+    | ReturnType<typeof apiKey>
+    | ReturnType<typeof phoneNumber>
+  > = [
+    organization({
+      roles: (config.auth?.roles ?? {}) as unknown as Record<
+        string,
+        Role | undefined
+      >,
+    }),
+  ];
+
+  if (config.auth?.twoFactor?.enabled) {
+    plugins.push(twoFactor({ issuer: config.storeName ?? "UnifiedCommerce" }));
+  }
+
+  if (config.auth?.apiKeys?.enabled) {
+    plugins.push(apiKey());
+  }
+
+  if (config.auth?.phoneAuth) {
+    plugins.push(phoneNumber({
+      sendOTP: config.auth.phoneAuth.sendOTP,
+      verifyOTP: config.auth.phoneAuth.verifyOTP,
+      otpLength: config.auth.phoneAuth.otpLength ?? 6,
+      expiresIn: config.auth.phoneAuth.expiresIn ?? 300,
+      signUpOnVerification: config.auth.phoneAuth.signUpOnVerification ?? {
+        getTempEmail: (phone: string) => `${phone.replace(/\+/g, "")}@phone.local`,
+      },
+    }));
+  }
+
+  // API key support can be attached via external plugin package in newer better-auth versions.
+
+  try {
+    const auth = betterAuth({
+      database: drizzleAdapter(db.db as Record<string, unknown>, {
+        provider: resolveAuthDbProvider(db.provider),
+        schema: authSchema,
+      }),
+      trustedOrigins: config.auth?.trustedOrigins ?? [],
+      emailAndPassword: {
+        enabled: true,
+        requireEmailVerification: config.auth?.requireEmailVerification ?? true,
+        sendResetPassword: async ({ user, url }: AuthEmailPayload) => {
+          if (!config.email) return;
+          await config.email.send({
+            template: "password-reset",
+            to: user.email,
+            data: { resetUrl: url, userName: user.name },
+          });
+        },
+        sendVerificationEmail: async ({ user, url }: AuthEmailPayload) => {
+          if (!config.email) return;
+          await config.email.send({
+            template: "email-verification",
+            to: user.email,
+            data: { verifyUrl: url, userName: user.name },
+          });
+        },
+      },
+      socialProviders: config.auth?.socialProviders ?? {},
+      session: {
+        expiresIn: config.auth?.sessionDuration ?? 60 * 60 * 24 * 7,
+        updateAge: 60 * 60 * 24,
+        cookieCache: {
+          enabled: true,
+          maxAge: 60 * 5,  // 5 minute cookie cache for performance
+        },
+      },
+      advanced: {
+        cookiePrefix: "uc",
+        useSecureCookies: process.env.NODE_ENV === "production",
+      },
+      plugins,
+      user: {
+        additionalFields: {
+          vendorId: { type: "string", required: false },
+          posOperatorPin: { type: "string", required: false },
+        },
+      },
+    });
+    // Better Auth's plugin-extended return type doesn't structurally overlap
+    // with our simplified AuthInstance interface (e.g., verifyApiKey expects
+    // { body: { key } } internally but we expose { key } for ergonomics).
+    // The double-cast is intentional and unavoidable without forking the types.
+    return auth as unknown as AuthInstance;
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? error.message
+        : "Unknown better-auth initialization error.";
+    throw new Error(`Failed to initialize authentication: ${message}`);
+  }
+}

package/src/auth/system-actor.ts

@@ -0,0 +1,19 @@
+import type { Actor } from "./types";
+import { DEFAULT_ORG_ID } from "./org";
+
+/**
+ * Creates a system actor for internal operations (webhooks, jobs, compensation chains).
+ * System actors have full permissions and are scoped to a specific organization.
+ */
+export function createSystemActor(orgId: string = DEFAULT_ORG_ID): Actor {
+  return {
+    type: "api_key",
+    userId: "system:internal",
+    email: null,
+    name: "System",
+    vendorId: null,
+    organizationId: orgId,
+    role: "system",
+    permissions: ["*:*"],
+  };
+}

package/src/auth/types.ts

@@ -0,0 +1,10 @@
+export interface Actor {
+  type: "user" | "api_key";
+  userId: string;
+  email: string | null;
+  name: string;
+  vendorId: string | null;
+  organizationId: string | null;
+  role: string;
+  permissions: string[];
+}

package/src/config/defaults.ts

@@ -0,0 +1,82 @@
+import type { CommerceConfig } from "./types";
+
+export const defaultConfig: Partial<CommerceConfig> = {
+  version: "0.0.1",
+  auth: {
+    requireEmailVerification: true,
+    sessionDuration: 60 * 60 * 24 * 7,
+    twoFactor: { enabled: false },
+    apiKeys: { enabled: false },
+    posPin: { enabled: false },
+    roles: {
+      owner: { permissions: ["*:*"] },
+      admin: { permissions: ["*:*"] },
+      manager: {
+        permissions: [
+          "catalog:create",
+          "catalog:update",
+          "catalog:delete",
+          "catalog:read",
+          "inventory:read",
+          "inventory:adjust",
+          "orders:read",
+          "orders:update",
+          "cart:create",
+          "cart:update",
+          "customers:read:self",
+          "customers:update:self",
+        ],
+      },
+      customer: {
+        permissions: [
+          "catalog:read",
+          "cart:create",
+          "cart:read",
+          "cart:update",
+          "orders:create",
+          "orders:read:own",
+          "customers:read:self",
+          "customers:update:self",
+        ],
+      },
+    },
+    customerPermissions: [
+      "catalog:read",
+      "cart:create",
+      "cart:read",
+      "cart:update",
+      "orders:create",
+      "orders:read:own",
+      "customers:read:self",
+      "customers:update:self",
+    ],
+  },
+  cart: {
+    ttlMinutes: 60 * 24 * 7,
+    hooks: {},
+  },
+  checkout: {
+    hooks: {
+      beforeCreate: [],
+      afterCreate: [],
+    },
+  },
+  orders: {
+    hooks: {
+      beforeCreate: [],
+      afterCreate: [],
+      beforeStatusChange: [],
+      afterStatusChange: [],
+      beforeDelete: [],
+    },
+  },
+  inventory: {
+    hooks: {
+      afterAdjust: [],
+    },
+  },
+  mcp: {
+    enabled: true,
+    capabilities: ["catalog:read", "orders:read", "inventory:read"],
+  },
+};

package/src/config/define-config.ts

@@ -0,0 +1,53 @@
+import { defaultConfig } from "./defaults";
+import type { CommerceConfig, DefineConfigInput } from "./types";
+import { _resetRegisteredPlugins } from "../kernel/plugin/manifest";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function merge<T extends object>(base: T, next: Partial<T>): T {
+  const output: Record<string, unknown> = {
+    ...(base as Record<string, unknown>),
+  };
+  for (const [key, value] of Object.entries(next as Record<string, unknown>)) {
+    if (value === undefined) continue;
+    const baseValue = output[key];
+    if (
+      isRecord(value) &&
+      isRecord(baseValue)
+    ) {
+      output[key] = merge(baseValue, value);
+    } else {
+      output[key] = value;
+    }
+  }
+  return output as T;
+}
+
+/**
+ * Builds the final CommerceConfig by:
+ * 1. Merging user input with defaults
+ * 2. Applying all plugins (each is a config transform function)
+ * 3. Freezing the result to prevent runtime mutation
+ */
+export async function defineConfig(
+  input: DefineConfigInput,
+): Promise<CommerceConfig> {
+  let config = merge(defaultConfig as CommerceConfig, input);
+
+  // Merge top-level `schema` into `customSchemas` before plugins run
+  if (config.schema?.length) {
+    config = {
+      ...config,
+      customSchemas: [...(config.customSchemas ?? []), ...config.schema],
+    };
+  }
+
+  _resetRegisteredPlugins();
+  for (const plugin of config.plugins ?? []) {
+    config = await plugin(config);
+  }
+
+  return Object.freeze(config);
+}

package/src/config/types.ts

@@ -0,0 +1,299 @@
+import type { Hono, MiddlewareHandler } from "hono";
+import type { Actor } from "../auth/types";
+import type { BeforeHook, AfterHook } from "../kernel/hooks/types";
+import type { PaymentAdapter } from "../modules/payments/adapter";
+import type { StorageAdapter } from "../modules/media/adapter";
+import type { DatabaseAdapter } from "../kernel/database/adapter";
+import type { TaxAdapter } from "../modules/tax/adapter";
+import type { SearchAdapter } from "../modules/search/adapter";
+import type { JobsAdapter } from "../kernel/jobs/adapter";
+import type { TaskDefinition } from "../kernel/jobs/types";
+
+export interface RoleDefinition {
+  permissions: string[];
+}
+
+export type FieldType = "text" | "number" | "boolean" | "date" | "json" | "relation" | "select";
+
+export interface EntityFieldDefinition {
+  name: string;
+  type: FieldType;
+  unit?: string;
+  schema?: unknown;
+  target?: string;
+  options?: string[];
+}
+
+export interface EntityVariantConfig {
+  enabled: boolean;
+  optionTypes?: string[];
+}
+
+export interface EntityHooks {
+  beforeCreate?: BeforeHook<unknown>[];
+  afterCreate?: AfterHook<unknown>[];
+  beforeUpdate?: BeforeHook<unknown>[];
+  afterUpdate?: AfterHook<unknown>[];
+  beforeDelete?: BeforeHook<unknown>[];
+  afterDelete?: AfterHook<unknown>[];
+  beforeRead?: BeforeHook<unknown>[];
+  afterRead?: AfterHook<unknown>[];
+  beforeList?: BeforeHook<unknown>[];
+  afterList?: AfterHook<unknown>[];
+}
+
+export interface EntityConfig {
+  fields: EntityFieldDefinition[];
+  variants: EntityVariantConfig;
+  fulfillment: string;
+  hooks?: EntityHooks;
+}
+
+export interface AuthConfig {
+  requireEmailVerification?: boolean;
+  sessionDuration?: number;
+  socialProviders?: Record<string, { clientId: string; clientSecret: string }>;
+  twoFactor?: { enabled: boolean; requiredForRoles?: string[] };
+  apiKeys?: {
+    enabled: boolean;
+    /** Default permissions for API keys that don't specify their own. */
+    defaultPermissions?: string[];
+  };
+  posPin?: { enabled: boolean };
+  roles?: Record<string, RoleDefinition>;
+  customerPermissions?: string[];
+  /** Origins allowed for CSRF protection (Better Auth `trustedOrigins`). */
+  trustedOrigins?: string[];
+  /** Enable a config-driven dev API key. OFF by default. Only for local development. */
+  enableDevKey?: boolean;
+  /** Custom dev key value. Must be set alongside enableDevKey. */
+  devKey?: string;
+  /**
+   * Phone number OTP authentication via Better Auth's phoneNumber plugin.
+   * When configured, users can sign in/up with phone + OTP instead of email/password.
+   * You provide the SMS delivery callback; Better Auth handles OTP generation,
+   * storage, expiry, brute force protection, and session creation.
+   */
+  phoneAuth?: {
+    /** Send OTP to the phone number. Implement with Twilio, AWS SNS, or any SMS gateway. */
+    sendOTP: (params: { phoneNumber: string; code: string }, ctx: unknown) => void | Promise<void>;
+    /** Optional custom OTP verification (e.g., Twilio Verify). Overrides internal logic. */
+    verifyOTP?: (params: { phoneNumber: string; code: string }, ctx: unknown) => boolean | Promise<boolean>;
+    /** OTP length. Default: 6. */
+    otpLength?: number;
+    /** OTP expiry in seconds. Default: 300 (5 minutes). */
+    expiresIn?: number;
+    /** Auto-create user on first OTP verification. Default: generates temp email from phone. */
+    signUpOnVerification?: {
+      getTempEmail: (phoneNumber: string) => string;
+      getTempName?: (phoneNumber: string) => string;
+    };
+  };
+}
+
+export interface CartConfig {
+  ttlMinutes?: number;
+  hooks?: {
+    beforeAddItem?: BeforeHook<unknown>[];
+    afterAddItem?: AfterHook<unknown>[];
+    beforeRemoveItem?: BeforeHook<unknown>[];
+    afterRemoveItem?: AfterHook<unknown>[];
+    beforeUpdateQuantity?: BeforeHook<unknown>[];
+    afterUpdateQuantity?: AfterHook<unknown>[];
+  };
+}
+
+export interface CheckoutConfig {
+  hooks?: {
+    beforeCreate?: BeforeHook<unknown>[];
+    afterCreate?: AfterHook<unknown>[];
+  };
+}
+
+export interface OrdersConfig {
+  hooks?: {
+    beforeCreate?: BeforeHook<unknown>[];
+    afterCreate?: AfterHook<unknown>[];
+    beforeStatusChange?: BeforeHook<unknown>[];
+    afterStatusChange?: AfterHook<unknown>[];
+    afterGet?: AfterHook<unknown>[];
+    beforeDelete?: BeforeHook<unknown>[];
+  };
+  /**
+   * Extend the order state machine with custom transitions.
+   * New states (e.g., "payment_initiated", "shipped", "delivered", "defaulted")
+   * are added to the default machine. Existing transitions are preserved.
+   * See extendOrderStateMachine() for the merge logic.
+   */
+  customTransitions?: Record<string, string[]>;
+}
+
+export interface InventoryConfig {
+  hooks?: {
+    afterAdjust?: AfterHook<unknown>[];
+  };
+}
+
+export interface ShippingConfig {
+  type: "flat" | "weight_based";
+  flatRate: number;
+  freeShippingThreshold?: number;
+  brackets: Array<{ upToGrams: number; cost: number }>;
+  fallbackCost: number;
+}
+
+export interface TaxConfig {
+  adapter?: TaxAdapter;
+  defaultFromAddress?: {
+    country: string;
+    postalCode: string;
+    state?: string;
+    city?: string;
+    line1?: string;
+  };
+}
+
+export interface AnalyticsConfig {
+  customSchemaPath?: string;
+  models?: unknown[];
+}
+
+export interface SearchConfig {
+  adapter?: SearchAdapter;
+  defaultFacets?: string[];
+}
+
+export interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  handler: (params: unknown) => Promise<unknown>;
+}
+
+export interface MCPResource {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+  handler: () => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+}
+
+/**
+ * A CommercePlugin is a config transform function (PayloadCMS pattern).
+ * Receives the current config, returns the modified config.
+ * All plugins — simple or complex — are just functions.
+ *
+ * Use `defineCommercePlugin()` for a structured way to build plugins,
+ * or write a raw transform function for full control.
+ */
+export type CommercePlugin = (
+  config: CommerceConfig,
+) => CommerceConfig | Promise<CommerceConfig>;
+
+export interface CommerceConfig {
+  storeName?: string;
+  version?: string;
+  database: {
+    provider: "postgresql";
+    options?: Record<string, unknown>;
+  };
+  databaseAdapter?: DatabaseAdapter;
+  auth?: AuthConfig;
+  entities?: Record<string, EntityConfig>;
+  cart?: CartConfig;
+  checkout?: CheckoutConfig;
+  orders?: OrdersConfig;
+  inventory?: InventoryConfig;
+  shipping?: ShippingConfig;
+  payments?: PaymentAdapter[];
+  storage?: StorageAdapter;
+  email?: {
+    send(input: {
+      template: string;
+      to: string;
+      data?: Record<string, unknown>;
+    }): Promise<void>;
+  };
+  tax?: TaxConfig;
+  analytics?: AnalyticsConfig;
+  search?: SearchConfig;
+  mcp?: {
+    enabled?: boolean;
+    capabilities?: string[];
+  };
+  jobs?: {
+    adapter?: JobsAdapter;
+    tasks?: TaskDefinition[];
+    autorun?: {
+      enabled: boolean;
+      intervalMs?: number;
+    };
+  };
+  /**
+   * Additional Drizzle table definitions — new tables or extended core tables.
+   * Each entry is an object of `{ exportName: pgTable(...) }`.
+   *
+   * These are merged with core schema by `buildSchema(config)` and must also
+   * be listed in the app's `drizzle.config.ts` for `db:push` / `db:generate`.
+   *
+   * Plugins push into this array automatically via `defineCommercePlugin({ schema })`.
+   * Apps can also add entries directly — no plugin wrapper needed:
+   *
+   * ```ts
+   * import { reviewsTable } from "./schema/reviews";
+   * import { extendedProducts } from "./schema/extended-products";
+   *
+   * defineConfig({
+   *   schema: [
+   *     { reviewsTable },
+   *     { extendedProducts },
+   *   ],
+   *   // ...
+   * });
+   * ```
+   */
+  schema?: Array<Record<string, unknown>>;
+  /** @internal Merged from `schema` + plugin schemas. Use `schema` instead. */
+  customSchemas?: Array<Record<string, unknown>>;
+  hooks?: Record<string, Array<(...args: unknown[]) => unknown>>;
+  plugins?: CommercePlugin[];
+  middleware?: MiddlewareHandler[];
+  routes?: (app: Hono, kernel: unknown) => void;
+  mcpTools?: (kernel: unknown) => MCPTool[];
+  /** Log level for structured logging. Default: "info". */
+  logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace";
+  /**
+   * Expose the OpenAPI spec (`/api/doc`) and Swagger UI (`/api/reference`).
+   * Default: `true` in development, `false` in production.
+   */
+  exposeOpenApiSpec?: boolean;
+  /** Rate limiting overrides. */
+  rateLimits?: {
+    /** Requests per minute for general API. Default: 100. */
+    api?: number;
+    /** Requests per minute for auth endpoints. Default: 10. */
+    auth?: number;
+    /** Requests per minute for checkout. Default: 5. */
+    checkout?: number;
+  };
+}
+
+export interface DefineConfigInput extends CommerceConfig {}
+
+export interface AuthSessionLike {
+  user: {
+    id: string;
+    email?: string | null;
+    name?: string | null;
+    vendorId?: string | null;
+  };
+  session: {
+    activeOrganizationId?: string | null;
+    activeOrganizationRole?: string | null;
+  };
+}
+
+export interface KernelFactoryContext {
+  config: CommerceConfig;
+  actor: Actor | null;
+}