@unifiedcommerce/core 0.0.1

package/dist/types/commerce-types.d.ts

@@ -0,0 +1,34 @@
+import type { sellableEntities } from "../modules/catalog/schema";
+import type { orders } from "../modules/orders/schema";
+import type { carts } from "../modules/cart/schema";
+import type { customers } from "../modules/customers/schema";
+import type { inventoryLevels } from "../modules/inventory/schema";
+/**
+ * Central type map for all commerce entities.
+ *
+ * Plugins can augment this interface via TypeScript module augmentation:
+ *
+ * ```typescript
+ * declare module "@unifiedcommerce/core" {
+ *   interface CommerceModuleTypes {
+ *     LoyaltyPoints: {
+ *       id: string;
+ *       customerId: string;
+ *       points: number;
+ *       tier: "bronze" | "silver" | "gold";
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * This enables plugin types to be referenced without importing
+ * internal schema modules.
+ */
+export interface CommerceModuleTypes {
+    Product: typeof sellableEntities.$inferSelect;
+    Order: typeof orders.$inferSelect;
+    Cart: typeof carts.$inferSelect;
+    Customer: typeof customers.$inferSelect;
+    InventoryLevel: typeof inventoryLevels.$inferSelect;
+}
+//# sourceMappingURL=commerce-types.d.ts.map

package/dist/types/commerce-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce-types.d.ts","sourceRoot":"","sources":["../../src/types/commerce-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,gBAAgB,CAAC,YAAY,CAAC;IAC9C,KAAK,EAAE,OAAO,MAAM,CAAC,YAAY,CAAC;IAClC,IAAI,EAAE,OAAO,KAAK,CAAC,YAAY,CAAC;IAChC,QAAQ,EAAE,OAAO,SAAS,CAAC,YAAY,CAAC;IACxC,cAAc,EAAE,OAAO,eAAe,CAAC,YAAY,CAAC;CACrD"}

package/dist/types/commerce-types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/id.d.ts

@@ -0,0 +1,2 @@
+export declare function makeId(): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/utils/id.js

@@ -0,0 +1,3 @@
+export function makeId() {
+    return crypto.randomUUID();
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,3 @@
+import type { Logger } from "../kernel/hooks/types";
+export declare function createLogger(scope: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAelD"}

package/dist/utils/logger.js

@@ -0,0 +1,16 @@
+export function createLogger(scope) {
+    return {
+        info(message, data) {
+            // eslint-disable-next-line no-console
+            console.info(`[${scope}] ${message}`, data ?? "");
+        },
+        warn(message, data) {
+            // eslint-disable-next-line no-console
+            console.warn(`[${scope}] ${message}`, data ?? "");
+        },
+        error(message, data) {
+            // eslint-disable-next-line no-console
+            console.error(`[${scope}] ${message}`, data ?? "");
+        },
+    };
+}

package/dist/utils/pagination.d.ts

@@ -0,0 +1,11 @@
+export interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+export declare function paginate<T>(items: T[], page: number, limit: number): {
+    items: T[];
+    pagination: Pagination;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAc3G"}

package/dist/utils/pagination.js

@@ -0,0 +1,15 @@
+export function paginate(items, page, limit) {
+    const safeLimit = Math.max(1, limit);
+    const safePage = Math.max(1, page);
+    const start = (safePage - 1) * safeLimit;
+    const sliced = items.slice(start, start + safeLimit);
+    return {
+        items: sliced,
+        pagination: {
+            page: safePage,
+            limit: safeLimit,
+            total: items.length,
+            totalPages: Math.max(1, Math.ceil(items.length / safeLimit)),
+        },
+    };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@unifiedcommerce/core",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/kernel/database/schema.d.ts",
+      "default": "./dist/kernel/database/schema.js"
+    },
+    "./auth-schema": {
+      "types": "./dist/auth/auth-schema.d.ts",
+      "default": "./dist/auth/auth-schema.js"
+    },
+    "./schema-utils": {
+      "types": "./dist/kernel/schema/extra-columns.d.ts",
+      "default": "./dist/kernel/schema/extra-columns.js"
+    }
+  },
+  "scripts": {
+    "generate:plugins": "node ./scripts/generate-plugin-types.mjs",
+    "check:store-guard": "node ./scripts/check-store-guard.mjs",
+    "build": "npm run generate:plugins && npm run check:store-guard && tsc -p tsconfig.build.json",
+    "check-types": "npm run generate:plugins && npm run check:store-guard && tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@better-auth/drizzle-adapter": "^1.3.8",
+    "@hono/swagger-ui": "^0.6.1",
+    "@hono/zod-openapi": "^1.2.2",
+    "better-auth": "^1.3.8",
+    "drizzle-orm": "^0.45.1",
+    "drizzle-zod": "^0.8.3",
+    "hono": "^4.9.8",
+    "hono-rate-limiter": "^0.5.3",
+    "pino": "^10.3.1",
+    "zod": "^4.1.11"
+  },
+  "devDependencies": {
+    "@better-auth/api-key": "^1.5.4",
+    "@electric-sql/pglite": "^0.3.15",
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "drizzle-kit": "^0.31.9",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ]
+}

package/src/adapters/console-email.ts

@@ -0,0 +1,43 @@
+/**
+ * Development email adapter that logs emails to the console.
+ *
+ * Zero dependencies. Use this during local development to see email
+ * content in the terminal without configuring Resend or an SMTP server.
+ *
+ * @example
+ * ```typescript
+ * import { consoleEmailAdapter } from "@unifiedcommerce/core";
+ *
+ * export default defineConfig({
+ *   email: consoleEmailAdapter(),
+ * });
+ * ```
+ */
+export function consoleEmailAdapter(): {
+  send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void>;
+} {
+  return {
+    async send(input) {
+      const divider = "=".repeat(60);
+      const lines = [
+        "",
+        divider,
+        `  EMAIL: ${input.template}`,
+        divider,
+        `  To:       ${input.to}`,
+        `  Template: ${input.template}`,
+      ];
+
+      if (input.data && Object.keys(input.data).length > 0) {
+        lines.push(`  Data:`);
+        for (const [key, value] of Object.entries(input.data)) {
+          lines.push(`    ${key}: ${JSON.stringify(value)}`);
+        }
+      }
+
+      lines.push(divider, "");
+
+      console.log(lines.join("\n"));
+    },
+  };
+}

package/src/auth/access.ts

@@ -0,0 +1,187 @@
+import type { Actor } from "./types";
+
+/**
+ * A WhereClause is a plain object representing database filter conditions.
+ * The shape mirrors what services and repositories can accept to narrow queries.
+ *
+ * Example: { customerId: "abc-123" } narrows results to that customer's records.
+ * Composite: { or: [{ customerId: "x" }, { organizationId: "y" }] }
+ */
+export type WhereClause = Record<string, unknown>;
+
+/**
+ * AccessResult: the return value of an access function.
+ *
+ * - `true`: full access, no filter needed
+ * - `false`: no access at all
+ * - `WhereClause`: partial access — the caller should apply this as a query filter
+ */
+export type AccessResult = boolean | WhereClause;
+
+/**
+ * AccessContext carries everything an access function needs to make a decision.
+ *
+ * - `actor`: the authenticated user/api-key/null (anonymous)
+ * - `data`: the document being accessed (for document-level checks)
+ * - `id`: the document ID (when data isn't loaded yet)
+ */
+export interface AccessContext<TData = unknown> {
+  actor: Actor | null;
+  data?: TData;
+  id?: string;
+  req?: Request;
+}
+
+/**
+ * An AccessFn evaluates access for a given context.
+ * Returns boolean (full/no access) or WhereClause (filtered access).
+ */
+export type AccessFn<TData = unknown> = (
+  ctx: AccessContext<TData>,
+) => AccessResult | Promise<AccessResult>;
+
+/**
+ * Combines multiple WhereClause objects with a logical operator.
+ * If there's only one clause, returns it directly (no unnecessary nesting).
+ */
+function combineWhere(
+  queries: WhereClause[],
+  operator: "and" | "or",
+): WhereClause {
+  if (queries.length === 1) return queries[0]!;
+  return { [operator]: queries };
+}
+
+/**
+ * Composes access functions with OR semantics.
+ *
+ * - If ANY function returns `true`, grants full access immediately (short-circuit).
+ * - If one or more return WhereClause, combines them with OR.
+ * - If ALL return `false`, denies access.
+ *
+ * Example:
+ * ```typescript
+ * const orderReadAccess = accessOR(isAdmin, isDocumentOwner("customerId"))
+ * // Admins see all orders; customers see only their own
+ * ```
+ */
+export const accessOR = <TData = unknown>(
+  ...fns: Array<AccessFn<TData>>
+): AccessFn<TData> => {
+  return async (ctx) => {
+    const queries: WhereClause[] = [];
+    for (const fn of fns) {
+      const result = await fn(ctx);
+      if (result === true) return true;
+      if (result && typeof result === "object") queries.push(result);
+    }
+    if (queries.length > 0) return combineWhere(queries, "or");
+    return false;
+  };
+};
+
+/**
+ * Composes access functions with AND semantics.
+ *
+ * - If ANY function returns `false`, denies access immediately (short-circuit).
+ * - If one or more return WhereClause, combines them with AND.
+ * - If ALL return `true`, grants full access.
+ *
+ * Example:
+ * ```typescript
+ * const restrictedAccess = accessAND(isAuthenticated, isDocumentOwner("customerId"))
+ * // Must be logged in AND own the document
+ * ```
+ */
+export const accessAND = <TData = unknown>(
+  ...fns: Array<AccessFn<TData>>
+): AccessFn<TData> => {
+  return async (ctx) => {
+    const queries: WhereClause[] = [];
+    for (const fn of fns) {
+      const result = await fn(ctx);
+      if (result === false) return false;
+      if (result !== true && result && typeof result === "object") {
+        queries.push(result);
+      }
+    }
+    if (queries.length > 0) return combineWhere(queries, "and");
+    return true;
+  };
+};
+
+/**
+ * Switches between two access functions based on a condition.
+ *
+ * Example:
+ * ```typescript
+ * const accessByRole = conditional(
+ *   ({ actor }) => actor?.role === "vendor",
+ *   isDocumentOwner("vendorId"),
+ *   isAdmin,
+ * )
+ * ```
+ */
+export const conditional = <TData = unknown>(
+  condition: ((ctx: AccessContext<TData>) => boolean) | boolean,
+  accessFn: AccessFn<TData>,
+  fallback: AccessFn<TData> = () => false,
+): AccessFn<TData> => {
+  return async (ctx) => {
+    const applies =
+      typeof condition === "function" ? condition(ctx) : condition;
+    return applies ? accessFn(ctx) : fallback(ctx);
+  };
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Built-in access functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Grants access if the actor has admin or owner role (wildcard permissions).
+ */
+export const isAdmin: AccessFn = ({ actor }) => {
+  if (!actor) return false;
+  return actor.permissions.includes("*:*");
+};
+
+/**
+ * Grants access if the actor is authenticated (any role).
+ */
+export const isAuthenticated: AccessFn = ({ actor }) => {
+  return actor != null;
+};
+
+/**
+ * Returns a WhereClause that filters to documents owned by the actor.
+ * The ownerField is the column name that holds the owner's user ID.
+ *
+ * For document-level checks (when data is provided), returns true/false.
+ * For list-level checks (when data is not provided), returns a WhereClause.
+ */
+export const isDocumentOwner = (
+  ownerField = "customerId",
+): AccessFn => {
+  return ({ actor, data }) => {
+    if (!actor) return false;
+
+    // Document-level check: compare directly
+    if (data) {
+      return (data as Record<string, unknown>)[ownerField] === actor.userId;
+    }
+
+    // List-level check: return a filter clause
+    return { [ownerField]: actor.userId };
+  };
+};
+
+/**
+ * Grants access to everyone, including anonymous users.
+ */
+export const publicAccess: AccessFn = () => true;
+
+/**
+ * Denies access to everyone.
+ */
+export const denyAll: AccessFn = () => false;

package/src/auth/auth-schema.ts

@@ -0,0 +1,131 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  boolean,
+  integer,
+} from "drizzle-orm/pg-core";
+
+export const user = pgTable("user", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
+  emailVerified: boolean("email_verified").default(false).notNull(),
+  image: text("image"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .defaultNow()
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+  vendorId: text("vendor_id"),
+  posOperatorPin: text("pos_operator_pin"),
+});
+
+export const session = pgTable("session", {
+  id: text("id").primaryKey(),
+  expiresAt: timestamp("expires_at").notNull(),
+  token: text("token").notNull().unique(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  activeOrganizationId: text("active_organization_id"),
+});
+
+export const account = pgTable("account", {
+  id: text("id").primaryKey(),
+  accountId: text("account_id").notNull(),
+  providerId: text("provider_id").notNull(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  accessToken: text("access_token"),
+  refreshToken: text("refresh_token"),
+  idToken: text("id_token"),
+  accessTokenExpiresAt: timestamp("access_token_expires_at"),
+  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+  scope: text("scope"),
+  password: text("password"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+});
+
+export const verification = pgTable("verification", {
+  id: text("id").primaryKey(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .defaultNow()
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+});
+
+export const organization = pgTable("organization", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  slug: text("slug").notNull().unique(),
+  logo: text("logo"),
+  createdAt: timestamp("created_at").notNull(),
+  metadata: text("metadata"),
+});
+
+export const member = pgTable("member", {
+  id: text("id").primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  role: text("role").default("member").notNull(),
+  createdAt: timestamp("created_at").notNull(),
+});
+
+export const invitation = pgTable("invitation", {
+  id: text("id").primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  email: text("email").notNull(),
+  role: text("role"),
+  status: text("status").default("pending").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  inviterId: text("inviter_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+});
+
+export const apikey = pgTable("apikey", {
+  id: text("id").primaryKey(),
+  configId: text("config_id").default("default").notNull(),
+  name: text("name"),
+  start: text("start"),
+  referenceId: text("reference_id").notNull(),
+  prefix: text("prefix"),
+  key: text("key").notNull(),
+  refillInterval: integer("refill_interval"),
+  refillAmount: integer("refill_amount"),
+  lastRefillAt: timestamp("last_refill_at"),
+  enabled: boolean("enabled").default(true),
+  rateLimitEnabled: boolean("rate_limit_enabled").default(true),
+  rateLimitTimeWindow: integer("rate_limit_time_window").default(86400000),
+  rateLimitMax: integer("rate_limit_max").default(10),
+  requestCount: integer("request_count").default(0),
+  remaining: integer("remaining"),
+  lastRequest: timestamp("last_request"),
+  expiresAt: timestamp("expires_at"),
+  createdAt: timestamp("created_at").notNull(),
+  updatedAt: timestamp("updated_at").notNull(),
+  permissions: text("permissions"),
+  metadata: text("metadata"),
+});

package/src/auth/middleware.ts

@@ -0,0 +1,115 @@
+import { timingSafeEqual } from "node:crypto";
+import type { MiddlewareHandler } from "hono";
+import type { AuthSessionLike, CommerceConfig } from "../config/types";
+import type { Actor } from "./types";
+import type { AuthInstance } from "./setup";
+import { DEFAULT_ORG_ID } from "./org";
+
+function resolvePermissions(
+  session: AuthSessionLike,
+  config: CommerceConfig,
+): string[] {
+  const role = session.session.activeOrganizationRole;
+  if (!role) {
+    return (
+      config.auth?.customerPermissions ?? [
+        "catalog:read",
+        "cart:create",
+        "cart:read",
+        "cart:update",
+        "orders:create",
+        "orders:read:own",
+        "customers:read:self",
+        "customers:update:self",
+      ]
+    );
+  }
+  const roleConfig = config.auth?.roles?.[role];
+  return roleConfig ? roleConfig.permissions : [];
+}
+
+export function authMiddleware(
+  auth: AuthInstance,
+  config: CommerceConfig,
+): MiddlewareHandler {
+  return async (c, next) => {
+    const session = (await auth.api.getSession({
+      headers: c.req.raw.headers,
+    })) as AuthSessionLike | null;
+
+    if (session) {
+      c.set("actor", {
+        type: "user",
+        userId: session.user.id,
+        email: session.user.email ?? null,
+        name: session.user.name ?? "User",
+        vendorId: session.user.vendorId ?? null,
+        organizationId: session.session.activeOrganizationId ?? null,
+        role: session.session.activeOrganizationRole ?? "customer",
+        permissions: resolvePermissions(session, config),
+      } satisfies Actor);
+      await next();
+      return;
+    }
+
+    // Extract API key from headers
+    const apiKeyHeader =
+      c.req.header("x-api-key") ??
+      c.req.header("authorization")?.replace("Bearer ", "");
+
+    if (
+      apiKeyHeader &&
+      config.auth?.apiKeys?.enabled &&
+      auth.api.verifyApiKey
+    ) {
+      try {
+        const keyResult = await auth.api.verifyApiKey({ key: apiKeyHeader });
+        if (keyResult) {
+          c.set("actor", {
+            type: "api_key",
+            userId: keyResult.userId,
+            email: null,
+            name: keyResult.name ?? "API Key",
+            vendorId: null,
+            organizationId: (keyResult as Record<string, unknown>).organizationId as string ?? DEFAULT_ORG_ID,
+            role: "api_key",
+            permissions:
+              keyResult.permissions ??
+              config.auth?.apiKeys?.defaultPermissions ??
+              [],
+          } satisfies Actor);
+          await next();
+          return;
+        }
+      } catch {
+        // ignore invalid key
+      }
+    }
+
+    // Config-driven dev key (OFF by default, must be explicitly enabled)
+    if (
+      !c.get("actor") &&
+      apiKeyHeader &&
+      config.auth?.enableDevKey &&
+      config.auth.devKey &&
+      apiKeyHeader.length === config.auth.devKey.length &&
+      timingSafeEqual(Buffer.from(apiKeyHeader), Buffer.from(config.auth.devKey))
+    ) {
+      c.set("actor", {
+        type: "api_key",
+        userId: "dev-staff",
+        email: "dev@local",
+        name: "Dev Admin (dev key)",
+        vendorId: null,
+        organizationId: DEFAULT_ORG_ID,
+        role: "owner",
+        permissions: ["*:*"],
+      } satisfies Actor);
+    }
+
+    if (!c.get("actor")) {
+      c.set("actor", null);
+    }
+    await next();
+  };
+}