@unifiedcommerce/core 0.2.0 → 0.2.1

package/src/auth/setup.ts

@@ -0,0 +1,171 @@
+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, jwt, bearer } from "better-auth/plugins";
+import type { CommerceConfig } from "../config/types.js";
+import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import * as authSchema from "./auth-schema.js";
+
+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>;
+    getActiveMemberRole?: (input: { headers: Headers }) => Promise<unknown>;
+    verifyApiKey?: (input: {
+      body: { key: string; permissions?: Record<string, string[]> };
+    }) => Promise<{
+      valid: boolean;
+      error: { message: string; code: string } | null;
+      key: Record<string, unknown> | null;
+    }>;
+    createApiKey?: (input: {
+      body: {
+        name?: string;
+        permissions?: Record<string, string[]>;
+        userId?: string;
+      };
+      headers?: Headers;
+    }) => 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>
+    | ReturnType<typeof jwt>
+    | ReturnType<typeof bearer>
+  > = [
+    organization({
+      // Better Auth's Role includes `authorize` and `statements` fields that
+      // our RoleDefinition doesn't have. Double-cast is required — upstream type gap.
+      roles: (config.auth?.roles ?? {}) as unknown as Record<string, Role | undefined>,
+    }),
+    bearer(),
+    jwt(),
+  ];
+
+  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({
+      // Better Auth's drizzle adapter expects a plain object, not PgDatabase.
+      // Double-cast required — PgDatabase has no index signature.
+      database: drizzleAdapter(db.db as unknown 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 is structurally incompatible with
+    // our simplified AuthInstance interface (upstream generic union vs our narrowed shape).
+    // Double-cast is the accepted pattern — same approach used by PayloadCMS.
+    // @see https://github.com/better-auth/better-auth/discussions
+    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.js";
+import { DEFAULT_ORG_ID } from "./org.js";
+
+/**
+ * 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.js";
+
+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.js";
+import type { CommerceConfig, DefineConfigInput } from "./types.js";
+import { _resetRegisteredPlugins } from "../kernel/plugin/manifest.js";
+
+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,301 @@
+import type { Hono, MiddlewareHandler } from "hono";
+import type { Actor } from "../auth/types.js";
+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 { DatabaseAdapter } from "../kernel/database/adapter.js";
+import type { TaxAdapter } from "../modules/tax/adapter.js";
+import type { SearchAdapter } from "../modules/search/adapter.js";
+import type { JobsAdapter } from "../kernel/jobs/adapter.js";
+import type { TaskDefinition } from "../kernel/jobs/types.js";
+
+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[];
+    /** Tool names to enable even when marked as dangerous */
+    enableDangerousTools?: 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.js";
+   * import { extendedProducts } from "./schema/extended-products.js";
+   *
+   * 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<any>, 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;
+}

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

@@ -0,0 +1,20 @@
+/* eslint-disable */
+// AUTO-GENERATED by scripts/generate-plugin-types.mjs
+
+export interface PluginCapabilityRegistryShape {
+  "appointments": Record<string, unknown>;
+  "cubejs": Record<string, unknown>;
+  "gift-cards": Record<string, unknown>;
+  "loyalty": Record<string, unknown>;
+  "marketplace": Record<string, unknown>;
+  "notifications": Record<string, unknown>;
+  "pos": Record<string, unknown>;
+  "pos-restaurant": Record<string, unknown>;
+  "procurement": Record<string, unknown>;
+  "production": Record<string, unknown>;
+  "reviews": Record<string, unknown>;
+  "scheduled-orders": Record<string, unknown>;
+  "uom": Record<string, unknown>;
+  "warehouse": Record<string, unknown>;
+  "wishlist": Record<string, unknown>;
+}

package/src/generated/plugin-manifest.ts

@@ -0,0 +1,23 @@
+/* eslint-disable */
+// AUTO-GENERATED by scripts/generate-plugin-types.mjs
+// DO NOT EDIT MANUALLY.
+
+export const resolvedPluginManifest = [
+  { id: "appointments", directory: "plugin-appointments" },
+  { id: "cubejs", directory: "plugin-cubejs" },
+  { id: "gift-cards", directory: "plugin-gift-cards" },
+  { id: "loyalty", directory: "plugin-loyalty" },
+  { id: "marketplace", directory: "plugin-marketplace" },
+  { id: "notifications", directory: "plugin-notifications" },
+  { id: "pos", directory: "plugin-pos" },
+  { id: "pos-restaurant", directory: "plugin-pos-restaurant" },
+  { id: "procurement", directory: "plugin-procurement" },
+  { id: "production", directory: "plugin-production" },
+  { id: "reviews", directory: "plugin-reviews" },
+  { id: "scheduled-orders", directory: "plugin-scheduled-orders" },
+  { id: "uom", directory: "plugin-uom" },
+  { id: "warehouse", directory: "plugin-warehouse" },
+  { id: "wishlist", directory: "plugin-wishlist" },
+] as const;
+
+export type ResolvedPluginId = (typeof resolvedPluginManifest)[number]["id"];