@unifiedcommerce/core 0.0.4 → 0.1.1

package/src/auth/org.ts

@@ -1,41 +0,0 @@
-import { OrganizationService } from "../modules/organization/service.js";
-
-/**
- * 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

@@ -1,28 +0,0 @@
-import { CommerceForbiddenError } from "../kernel/errors.js";
-import type { Actor } from "./types.js";
-
-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

@@ -1,165 +0,0 @@
-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.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>
-  > = [
-    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. The double-cast bridges the
-    // generic plugin union with our narrowed AuthInstance shape.
-    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

@@ -1,19 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

@@ -1,299 +0,0 @@
-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[];
-  };
-  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, 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;
-}