deesse 0.2.7 → 0.2.9

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC;QACzC,QAAQ,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;QAC5C,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,gBAAgB,EAAE,CAAC;KAC7B,CAAC,CAAC,CAAC,CAAC;IACL,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAc3D"}

package/dist/server.js

@@ -0,0 +1,17 @@
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+export function createDeesse(config) {
+    const auth = betterAuth({
+        database: drizzleAdapter(config.database, {
+            provider: "pg",
+        }),
+        baseURL: config.auth.baseURL,
+        secret: config.secret,
+        plugins: config.auth.plugins,
+    });
+    return {
+        auth,
+        database: config.database,
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAY9D,MAAM,UAAU,YAAY,CAAC,MAAsB;IACjD,MAAM,IAAI,GAAG,UAAU,CAAC;QACtB,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,QAAQ,EAAE;YACxC,QAAQ,EAAE,IAAI;SACf,CAAC;QACF,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO;QAC5B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO;KAC7B,CAAC,CAAC;IAEH,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deesse",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -19,6 +19,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@better-auth/drizzle-adapter": "^1.0.0",
+    "better-auth": "^1.0.0",
     "drizzle-orm": "^0.38.0",
     "lucide-react": "^0.468.0",
     "pg": "^8.13.0",

package/src/cache.ts

@@ -0,0 +1,81 @@
+// Generic cache utility with immutable state
+
+export type CacheState<T> = {
+  instances: Map<string, T>;
+  promises: Map<string, Promise<T>>;
+};
+
+export const emptyCache = <T>(): CacheState<T> => ({
+  instances: new Map(),
+  promises: new Map(),
+});
+
+export const setCacheInstance = <T>(state: CacheState<T>, key: string, instance: T): CacheState<T> => ({
+  instances: new Map(state.instances).set(key, instance),
+  promises: (() => {
+    const m = new Map(state.promises);
+    m.delete(key);
+    return m;
+  })(),
+});
+
+export const setCachePromise = <T>(state: CacheState<T>, key: string, promise: Promise<T>): CacheState<T> => ({
+  instances: state.instances,
+  promises: new Map(state.promises).set(key, promise),
+});
+
+export const getCacheEntry = <T>(state: CacheState<T>, key: string): T | Promise<T> | undefined => {
+  const instance = state.instances.get(key);
+  if (instance !== undefined) return instance;
+  return state.promises.get(key);
+};
+
+export const removeCachePromise = <T>(state: CacheState<T>, key: string): CacheState<T> => ({
+  instances: state.instances,
+  promises: (() => {
+    const m = new Map(state.promises);
+    m.delete(key);
+    return m;
+  })(),
+});
+
+export type CreateCache = <T, Options>(
+  createInstance: (options: Options) => Promise<T>
+) => {
+  get(key: string, options: Options): Promise<T>;
+  getState(): Readonly<CacheState<T>>;
+  clear(): void;
+};
+
+export const createCache: CreateCache = <T, Options>(
+  createInstance: (options: Options) => Promise<T>
+) => {
+  let state: CacheState<T> = emptyCache<T>();
+
+  return {
+    async get(key: string, options: Options): Promise<T> {
+      const cached = getCacheEntry(state, key);
+      if (cached !== undefined) return cached as T;
+
+      const promise = createInstance(options);
+      state = setCachePromise(state, key, promise);
+
+      try {
+        const instance = await promise;
+        state = setCacheInstance(state, key, instance);
+        return instance;
+      } catch (err) {
+        state = removeCachePromise(state, key);
+        throw err;
+      }
+    },
+
+    getState(): Readonly<CacheState<T>> {
+      return state;
+    },
+
+    clear(): void {
+      state = emptyCache<T>();
+    },
+  };
+};

package/src/client.ts

@@ -0,0 +1,39 @@
+import { createAuthClient } from "better-auth/react";
+import type {
+  AuthClient,
+  BetterAuthClientOptions,
+} from "better-auth/client";
+
+export interface DeesseClientOptions {
+  auth: BetterAuthClientOptions;
+}
+
+export interface DeesseClient {
+  auth: AuthClient<BetterAuthClientOptions>;
+}
+
+/**
+ * Creates a type-safe authentication client.
+ * Wraps better-auth's createAuthClient with a simpler API.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "deesse";
+ *
+ * export const client = createClient({
+ *   auth: {
+ *     baseURL: "/api/auth",
+ *   },
+ * });
+ *
+ * // In a component:
+ * const { data, isPending } = client.auth.useSession();
+ * ```
+ */
+export function createClient(
+  options: DeesseClientOptions,
+): DeesseClient {
+  const auth = createAuthClient(options.auth) as unknown as AuthClient<BetterAuthClientOptions>;
+
+  return { auth };
+}

package/src/config/define.ts

@@ -1,13 +1,39 @@
 import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import type { BetterAuthPlugin } from 'better-auth';
 import type { Plugin } from './plugin';
 import type { PageTree } from './page';
+import { admin } from 'better-auth/plugins';
 
 export type Config = {
+  name?: string;
   database: PostgresJsDatabase;
   plugins?: Plugin[];
   pages?: PageTree[];
+  secret: string;
+  auth: {
+    baseURL: string;
+  };
 };
 
-export function defineConfig(config: Config) {
-  return config;
+/**
+ * Internal config type used at runtime - includes admin plugin
+ */
+export type InternalConfig = Config & {
+  auth: {
+    baseURL: string;
+    plugins: BetterAuthPlugin[];
+  };
+};
+
+export function defineConfig(config: Config): InternalConfig {
+  // Always include admin plugin - user cannot remove it
+  const authPlugins: BetterAuthPlugin[] = [admin()];
+
+  return {
+    ...config,
+    auth: {
+      ...config.auth,
+      plugins: authPlugins,
+    },
+  } as InternalConfig;
 }

package/src/config/index.ts

@@ -1,5 +1,5 @@
 export { defineConfig } from "./define";
-export type { Config } from "./define";
+export type { Config, InternalConfig } from "./define";
 export { plugin } from "./plugin";
 export type { Plugin } from "./plugin";
 export { page, section } from "./page";

package/src/config/page.ts

@@ -13,6 +13,7 @@ export type Section = {
   type: "section";
   name: string;
   slug: string;
+  bottom?: boolean;
   children: PageTree[];
 };
 
@@ -40,12 +41,14 @@ export function page(config: {
 export function section(config: {
   name: string;
   slug?: string;
+  bottom?: boolean;
   children: PageTree[];
 }): Section {
   return {
     type: "section",
     name: config.name,
     slug: config.slug ?? toSlug(config.name),
+    bottom: config.bottom,
     children: config.children,
   };
 }

package/src/index.ts

@@ -1,7 +1,11 @@
 // @deessejs/deesse core package
 
+import type { InternalConfig } from "./config/define";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { createDeesse, type Deesse } from "./server";
+
 export { defineConfig } from "./config";
-export type { Config } from "./config";
+export type { Config, InternalConfig } from "./config";
 export { plugin } from "./config";
 export type { Plugin } from "./config";
 export { page, section } from "./config";
@@ -9,3 +13,135 @@ export type { Page, Section, PageTree } from "./config";
 
 export { z } from "zod";
 export type { ZodSchema } from "zod";
+
+export type { Deesse } from "./server";
+
+export { createClient } from "./client";
+export type { DeesseClient, DeesseClientOptions } from "./client";
+
+export { isDatabaseEmpty, requireDatabaseNotEmpty, validateAdminEmail } from "./lib/admin";
+export type { EmailValidationOptions } from "./lib/admin";
+export { isPublicEmailDomain, isAllowedAdminEmail, getAllowedDomains, validateAdminEmailDomain, PUBLIC_EMAIL_DOMAINS } from "./lib/validation";
+
+/**
+ * Symbol-based global storage for Deesse instance.
+ * Using Symbol.for ensures uniqueness across the process.
+ */
+const DEESSE_GLOBAL_KEY = Symbol.for("@deessejs/core.instance");
+
+interface GlobalDeesseCache {
+  instance: Deesse | undefined;
+  config: InternalConfig | undefined;
+  pool: unknown | undefined;
+}
+
+function getGlobalCache(): GlobalDeesseCache {
+  const g = global as typeof global & {
+    [DEESSE_GLOBAL_KEY]?: GlobalDeesseCache;
+  };
+  if (!g[DEESSE_GLOBAL_KEY]) {
+    g[DEESSE_GLOBAL_KEY] = {
+      instance: undefined,
+      config: undefined,
+      pool: undefined,
+    };
+  }
+  return g[DEESSE_GLOBAL_KEY]!;
+}
+
+/**
+ * Deep equality check for config comparison.
+ * Required because config objects are recreated on HMR.
+ */
+function isConfigEqual(a: InternalConfig, b: InternalConfig): boolean {
+  if (a.secret !== b.secret) return false;
+  if (a.name !== b.name) return false;
+  if (a.auth.baseURL !== b.auth.baseURL) return false;
+  return true;
+}
+
+/**
+ * Extract pool reference from database.
+ * For pg Pool passed to drizzle-orm/node-postgres, the pool is stored in $client.
+ */
+function extractPool(db: PostgresJsDatabase): unknown {
+  return (db as unknown as { $client?: unknown }).$client;
+}
+
+/**
+ * Get the Deesse singleton instance.
+ * Cached on global to persist across HMR.
+ */
+export const getDeesse = async (
+  config: InternalConfig
+): Promise<Deesse> => {
+  const cache = getGlobalCache();
+
+  // Case 1: Instance exists and config is semantically equal
+  if (cache.instance && cache.config && isConfigEqual(cache.config, config)) {
+    return cache.instance;
+  }
+
+  // Case 2: Instance exists but config changed - hot reload
+  // IMPORTANT: Don't close the pool! cache.instance still uses the old pool.
+  // The new config's pool will be garbage collected when the HMR module reference is dropped.
+  if (
+    cache.instance &&
+    cache.config &&
+    !isConfigEqual(cache.config, config)
+  ) {
+    console.info("[deesse] Config changed, performing hot reload...");
+    cache.config = config;
+    return cache.instance;
+  }
+
+  // Case 3: No instance exists - create one
+  const instance = createDeesse(config);
+  cache.pool = extractPool(instance.database);
+  cache.instance = instance;
+  cache.config = config;
+
+  return instance;
+};
+
+/**
+ * Clear the Deesse singleton cache.
+ * Primarily useful for testing.
+ */
+export const clearDeesseCache = (): void => {
+  const cache = getGlobalCache();
+  cache.instance = undefined;
+  cache.config = undefined;
+  cache.pool = undefined;
+};
+
+/**
+ * Graceful shutdown - call this on process exit.
+ * Ensures all database connections are properly closed.
+ */
+export const shutdownDeesse = async (): Promise<void> => {
+  const cache = getGlobalCache();
+
+  if (cache.pool) {
+    console.info("[deesse] Closing database pool...");
+    const pool = cache.pool as { end?: () => Promise<void> };
+    if (pool && typeof pool.end === "function") {
+      await pool.end();
+    }
+    cache.pool = undefined;
+  }
+
+  cache.instance = undefined;
+  cache.config = undefined;
+};
+
+// Register graceful shutdown hooks
+if (process.env["NODE_ENV"] !== "test") {
+  const shutdown = () => {
+    shutdownDeesse()
+      .catch(console.error)
+      .finally(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}

package/src/lib/admin.ts

@@ -0,0 +1,68 @@
+import type { Auth } from "better-auth";
+
+/**
+ * Check if the database has any users.
+ * Returns true if the database is empty (no users).
+ */
+export async function isDatabaseEmpty(auth: Auth): Promise<boolean> {
+  try {
+    const result = await (auth.api as any).listUsers({ limit: 1 });
+    return !result?.users || result.users.length === 0;
+  } catch {
+    // If listUsers fails, assume not empty (safer default)
+    return false;
+  }
+}
+
+/**
+ * Require that the database is NOT empty.
+ * Throws if no users exist.
+ */
+export async function requireDatabaseNotEmpty(auth: Auth): Promise<void> {
+  if (await isDatabaseEmpty(auth)) {
+    throw new Error(
+      "Database is empty. Cannot proceed with this operation. " +
+      "Use the First Admin Setup page to create the initial admin account."
+    );
+  }
+}
+
+export interface EmailValidationOptions {
+  allowedDomains?: string[];
+  blockedDomains?: string[];
+  requireOrganization?: boolean;
+}
+
+/**
+ * Validate an admin email against configured rules.
+ */
+export function validateAdminEmail(
+  email: string,
+  options: EmailValidationOptions = {}
+): { valid: boolean; error?: string } {
+  const domain = email.split('@')[1]?.toLowerCase();
+
+  if (!domain) {
+    return { valid: false, error: "Invalid email format" };
+  }
+
+  // Check blocked domains
+  if (options.blockedDomains?.includes(domain)) {
+    return { valid: false, error: `Email domain ${domain} is blocked` };
+  }
+
+  // Check allowed domains (if specified)
+  if (options.allowedDomains?.length && !options.allowedDomains.includes(domain)) {
+    return { valid: false, error: `Email must be from: ${options.allowedDomains.join(', ')}` };
+  }
+
+  // Require organization (no public email domains)
+  if (options.requireOrganization) {
+    const PUBLIC_DOMAINS = ['gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com'];
+    if (PUBLIC_DOMAINS.includes(domain)) {
+      return { valid: false, error: "Personal email domains are not allowed. Use an organizational email." };
+    }
+  }
+
+  return { valid: true };
+}

package/src/lib/validation.ts

@@ -0,0 +1,89 @@
+/**
+ * Email validation utilities for admin email enforcement
+ */
+
+export const PUBLIC_EMAIL_DOMAINS = [
+  'gmail.com',
+  'yahoo.com',
+  'hotmail.com',
+  'outlook.com',
+  'icloud.com',
+  'mail.com',
+  'aol.com',
+  'protonmail.com',
+  'zoho.com',
+  'yandex.com',
+  'gmx.com',
+] as const;
+
+export type PublicEmailDomain = (typeof PUBLIC_EMAIL_DOMAINS)[number];
+
+/**
+ * Check if an email uses a public email domain
+ */
+export function isPublicEmailDomain(email: string): boolean {
+  const domain = email.split('@')[1]?.toLowerCase();
+  return PUBLIC_EMAIL_DOMAINS.includes(domain as PublicEmailDomain);
+}
+
+/**
+ * Get allowed domains from ADMIN_ALLOWED_DOMAINS environment variable.
+ * Returns empty array if not configured (no restrictions).
+ */
+export function getAllowedDomains(): string[] {
+  const envValue = process.env['ADMIN_ALLOWED_DOMAINS'];
+  if (!envValue) return [];
+  return envValue
+    .split(',')
+    .map((d) => d.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * Check if an email is from an allowed domain.
+ * If no allowed domains are configured, all domains are allowed.
+ */
+export function isAllowedAdminEmail(email: string): boolean {
+  const allowed = getAllowedDomains();
+  if (!allowed.length) return true; // No restriction configured
+  const domain = email.split('@')[1]?.toLowerCase();
+  return allowed.includes(domain);
+}
+
+/**
+ * Validate admin email against organizational requirements.
+ * Returns an error message if validation fails.
+ */
+export function validateAdminEmailDomain(
+  email: string
+): { valid: true } | { valid: false; code: string; message: string; suggestion?: string } {
+  // Check if email is from a public domain (warning level, not blocking)
+  const isPublic = isPublicEmailDomain(email);
+  const allowed = getAllowedDomains();
+
+  // If allowed domains are configured, enforce them strictly
+  if (allowed.length > 0) {
+    const domain = email.split('@')[1]?.toLowerCase();
+    if (!allowed.includes(domain)) {
+      return {
+        valid: false,
+        code: 'INVALID_EMAIL_DOMAIN',
+        message: `Admin email must be from an allowed domain. Allowed: ${allowed.join(', ')}`,
+        suggestion: 'Set ADMIN_ALLOWED_DOMAINS environment variable to configure allowed email domains',
+      };
+    }
+  }
+
+  // If email is from a public domain, return warning info (but allow through)
+  if (isPublic && allowed.length === 0) {
+    const domain = email.split('@')[1]?.toLowerCase();
+    return {
+      valid: false,
+      code: 'PUBLIC_EMAIL_DOMAIN',
+      message: `${email} is a public email domain. Admin accounts should use organizational email addresses.`,
+      suggestion: `Set ADMIN_ALLOWED_DOMAINS environment variable to restrict to organizational domains only (e.g., ADMIN_ALLOWED_DOMAINS=${domain})`,
+    };
+  }
+
+  return { valid: true };
+}

package/src/server.ts

@@ -0,0 +1,31 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { BetterAuthPlugin } from "better-auth";
+import type { InternalConfig } from "./config/define";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+
+export type Deesse = {
+  auth: Awaited<ReturnType<typeof betterAuth<{
+    database: ReturnType<typeof drizzleAdapter>;
+    baseURL: string;
+    secret: string;
+    plugins: BetterAuthPlugin[];
+  }>>>;
+  database: PostgresJsDatabase;
+};
+
+export function createDeesse(config: InternalConfig): Deesse {
+  const auth = betterAuth({
+    database: drizzleAdapter(config.database, {
+      provider: "pg",
+    }),
+    baseURL: config.auth.baseURL,
+    secret: config.secret,
+    plugins: config.auth.plugins,
+  });
+
+  return {
+    auth,
+    database: config.database,
+  };
+}

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "composite": false,
     "module": "ESNext",
     "moduleResolution": "bundler",
     "outDir": "./dist",