@vobase/core 0.10.0 → 0.11.0

package/src/app.ts

@@ -0,0 +1,178 @@
+import { Hono } from 'hono';
+
+import { contextMiddleware } from './ctx';
+import { createDatabase } from './db/client';
+import { createHttpClient, type HttpClientOptions } from './infra/http-client';
+import { errorHandler } from './infra/errors';
+import { createWorker } from './infra/job';
+import { logger } from './infra/logger';
+import { createMcpHandler } from './mcp/server';
+import { createAuditModule } from './modules/audit';
+import { createAuthModule, optionalSessionMiddleware, type AuthModuleConfig } from './modules/auth';
+import { createCredentialsModule } from './modules/credentials';
+import { createNotifyModule, type NotifyModuleConfig } from './modules/notify';
+import type { NotifyService } from './modules/notify/service';
+import { createSequencesModule } from './modules/sequences';
+import { createStorageModule, type StorageModuleConfig } from './modules/storage';
+import type { StorageService } from './modules/storage/service';
+import type { VobaseModule } from './module';
+import { createScheduler } from './infra/queue';
+import { createThrowProxy } from './infra/throw-proxy';
+import { createWebhookRoutes, type WebhookConfig } from './infra/webhooks';
+
+const DEFAULT_QUEUE_DB_PATH = '/data/bunqueue.db';
+const LOCAL_QUEUE_DB_PATH = './data/bunqueue.db';
+
+function deriveQueueDbPath(databasePath: string): string {
+  if (databasePath !== ':memory:' && databasePath.endsWith('.db')) {
+    return databasePath.replace(/\.db$/, '-queue.db');
+  }
+
+  return DEFAULT_QUEUE_DB_PATH;
+}
+
+async function createSchedulerWithFallback(queueDbPath: string) {
+  try {
+    return {
+      scheduler: await createScheduler({ dbPath: queueDbPath }),
+      effectiveQueueDbPath: queueDbPath,
+    };
+  } catch (error) {
+    if (queueDbPath !== DEFAULT_QUEUE_DB_PATH) {
+      throw error;
+    }
+
+    logger.warn('Falling back to local queue database path', {
+      queueDbPath,
+      fallbackQueueDbPath: LOCAL_QUEUE_DB_PATH,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    return {
+      scheduler: await createScheduler({ dbPath: LOCAL_QUEUE_DB_PATH }),
+      effectiveQueueDbPath: LOCAL_QUEUE_DB_PATH,
+    };
+  }
+}
+
+export interface CreateAppConfig {
+  modules: VobaseModule[];
+  database: string;
+  storage?: StorageModuleConfig;
+  notify?: NotifyModuleConfig;
+  http?: HttpClientOptions;
+  webhooks?: Record<string, WebhookConfig>;
+  mcp?: { enabled?: boolean };
+  trustedOrigins?: string[];
+  auth?: Omit<AuthModuleConfig, 'trustedOrigins'>;
+  /** Enable the credentials module (encrypted credential store). Default: false */
+  credentials?: { enabled: boolean };
+}
+
+export async function createApp(config: CreateAppConfig) {
+  const db = createDatabase(config.database);
+
+  const queueDbPath = deriveQueueDbPath(config.database);
+  const { scheduler, effectiveQueueDbPath } =
+    await createSchedulerWithFallback(queueDbPath);
+
+  const http = createHttpClient(config.http);
+
+  // === Auth Module (always active) ===
+  const authMod = createAuthModule(db, {
+    ...config.auth,
+    trustedOrigins: config.trustedOrigins,
+  });
+  const authAdapter = authMod.adapter;
+
+  // === Storage Module (config-driven) ===
+  let storageMod: ReturnType<typeof createStorageModule> | undefined;
+  let storageService: StorageService;
+  if (config.storage) {
+    storageMod = createStorageModule(db, config.storage);
+    storageService = storageMod.service;
+  } else {
+    storageService = createThrowProxy<StorageService>('storage');
+  }
+
+  // === Notify Module (config-driven) ===
+  let notifyMod: ReturnType<typeof createNotifyModule> | undefined;
+  let notifyService: NotifyService;
+  if (config.notify) {
+    notifyMod = createNotifyModule(db, config.notify);
+    notifyService = notifyMod.service;
+  } else {
+    notifyService = createThrowProxy<NotifyService>('notify');
+  }
+
+  // === Built-in Module Init ===
+  const initCtx = { db, scheduler, http, storage: storageService, notify: notifyService };
+
+  const auditMod = createAuditModule();
+  auditMod.init?.(initCtx);
+
+  const seqMod = createSequencesModule();
+  seqMod.init?.(initCtx);
+
+  let credMod: VobaseModule | undefined;
+  if (config.credentials?.enabled) {
+    credMod = createCredentialsModule();
+    credMod.init?.(initCtx);
+  }
+
+  // === Base app with middleware ===
+  const base = new Hono();
+  base.onError(errorHandler);
+  base.use('*', contextMiddleware({ db, scheduler, storage: storageService, notify: notifyService, http }));
+  base.use('/api/*', optionalSessionMiddleware(authAdapter));
+  base.on(['POST', 'GET'], '/api/auth/*', (c) => authAdapter.handler(c.req.raw));
+
+  // Mount via chaining to preserve route types for hc<AppType>
+  const app = base
+    .get('/health', (c) => c.json({ status: 'ok', uptime: process.uptime() }));
+
+  // === Storage routes ===
+  if (storageMod) {
+    (app as Hono).route('/api/storage', storageMod.routes);
+  }
+
+  // === User Modules ===
+  const userModules = config.modules;
+  for (const mod of userModules) {
+    mod.init?.(initCtx);
+    (app as Hono).route(`/api/${mod.name}`, mod.routes);
+  }
+
+  // === Webhooks ===
+  if (config.webhooks && Object.keys(config.webhooks).length > 0) {
+    const webhookRouter = createWebhookRoutes(config.webhooks, { db, scheduler });
+    (app as Hono).route('', webhookRouter);
+  }
+
+  // === MCP + Jobs ===
+  const builtInModules: VobaseModule[] = [authMod, auditMod, seqMod];
+  if (storageMod) builtInModules.push(storageMod);
+  if (notifyMod) builtInModules.push(notifyMod);
+  if (credMod) builtInModules.push(credMod);
+  const allModules = [...builtInModules, ...userModules];
+
+  if (config.mcp?.enabled) {
+    const mcpHandler = createMcpHandler({
+      db,
+      modules: allModules,
+      verifyApiKey: authMod.verifyApiKey,
+      organizationEnabled: authMod.organizationEnabled,
+    });
+    (app as Hono).all('/mcp', async (c) => {
+      const response = await mcpHandler(c.req.raw);
+      return response;
+    });
+  }
+
+  const allJobs = allModules.flatMap((module) => module.jobs ?? []);
+  if (allJobs.length > 0) {
+    await createWorker(allJobs, { dbPath: effectiveQueueDbPath });
+  }
+
+  return app;
+}

package/src/audit.test.ts

@@ -0,0 +1,126 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { drizzle } from 'drizzle-orm/bun-sqlite';
+
+import type { VobaseDb } from './db';
+import { trackChanges } from './modules/audit/track-changes';
+import * as schema from './modules/audit/schema';
+
+interface AuditRow {
+  tableName: string;
+  recordId: string;
+  oldData: string | null;
+  newData: string | null;
+  changedBy: string | null;
+}
+
+describe('trackChanges()', () => {
+  let sqlite: Database;
+  let db: VobaseDb;
+
+  beforeEach(() => {
+    sqlite = new Database(':memory:');
+    sqlite.run('PRAGMA journal_mode=WAL');
+    sqlite.exec(`
+      CREATE TABLE _record_audits (
+        id TEXT PRIMARY KEY,
+        table_name TEXT NOT NULL,
+        record_id TEXT NOT NULL,
+        old_data TEXT,
+        new_data TEXT,
+        changed_by TEXT,
+        created_at INTEGER NOT NULL
+      )
+    `);
+
+    db = drizzle({ client: sqlite, schema }) as unknown as VobaseDb;
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  function getRows(): AuditRow[] {
+    return sqlite
+      .prepare(
+        `
+          SELECT
+            table_name AS tableName,
+            record_id AS recordId,
+            old_data AS oldData,
+            new_data AS newData,
+            changed_by AS changedBy
+          FROM _record_audits
+          ORDER BY rowid ASC
+        `,
+      )
+      .all() as AuditRow[];
+  }
+
+  it('stores full new data for create events', () => {
+    trackChanges(
+      db,
+      'invoices',
+      'inv_1',
+      null,
+      { status: 'draft', total: 100 },
+      'user_1',
+    );
+
+    const rows = getRows();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toEqual({
+      tableName: 'invoices',
+      recordId: 'inv_1',
+      oldData: null,
+      newData: JSON.stringify({ status: 'draft', total: 100 }),
+      changedBy: 'user_1',
+    });
+  });
+
+  it('stores only changed fields for update events', () => {
+    trackChanges(
+      db,
+      'invoices',
+      'inv_2',
+      { status: 'draft', total: 100, note: 'A' },
+      { status: 'sent', total: 100, note: 'B' },
+      'user_2',
+    );
+
+    const rows = getRows();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.oldData).toBe(
+      JSON.stringify({ status: 'draft', note: 'A' }),
+    );
+    expect(rows[0]?.newData).toBe(
+      JSON.stringify({ status: 'sent', note: 'B' }),
+    );
+    expect(rows[0]?.changedBy).toBe('user_2');
+  });
+
+  it('stores full old data for delete events', () => {
+    trackChanges(db, 'invoices', 'inv_3', { status: 'void', total: 20 }, null);
+
+    const rows = getRows();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.oldData).toBe(
+      JSON.stringify({ status: 'void', total: 20 }),
+    );
+    expect(rows[0]?.newData).toBeNull();
+    expect(rows[0]?.changedBy).toBeNull();
+  });
+
+  it('does not store an audit row when values are unchanged', () => {
+    trackChanges(
+      db,
+      'invoices',
+      'inv_4',
+      { status: 'draft', total: 100 },
+      { status: 'draft', total: 100 },
+      'user_3',
+    );
+
+    expect(getRows()).toHaveLength(0);
+  });
+});

package/src/auth.test.ts

@@ -0,0 +1,74 @@
+import type { Database } from 'bun:sqlite';
+import { describe, expect, it, mock } from 'bun:test';
+import type { Context, Next } from 'hono';
+
+import type { AuthAdapter, AuthSession } from './contracts/auth';
+import { createAuthModule } from './modules/auth';
+import { sessionMiddleware, optionalSessionMiddleware } from './modules/auth/middleware';
+import { createDatabase, type VobaseDb } from './db';
+import { VobaseError } from './infra/errors';
+
+type DbWithClient = VobaseDb & { $client: Database };
+
+function createMockContext() {
+  const values = new Map<string, unknown>();
+
+  return {
+    req: {
+      raw: {
+        headers: new Headers(),
+      },
+    },
+    set: (key: string, value: unknown) => {
+      values.set(key, value);
+    },
+    get: (key: string) => values.get(key),
+  } as unknown as Context;
+}
+
+function createMockAdapter(getSession: () => Promise<AuthSession | null>): AuthAdapter {
+  return {
+    getSession,
+    handler: async () => new Response('ok'),
+  };
+}
+
+describe('createAuthModule', () => {
+  it('returns a module with adapter having handler and getSession', () => {
+    const db = createDatabase(':memory:') as DbWithClient;
+    const authMod = createAuthModule(db);
+
+    expect(authMod).toHaveProperty('adapter');
+    expect(authMod.adapter).toHaveProperty('handler');
+    expect(authMod.adapter).toHaveProperty('getSession');
+    expect(authMod.name).toBe('_auth');
+
+    db.$client.close();
+  });
+});
+
+describe('session middleware', () => {
+  it('sessionMiddleware throws unauthorized when no session exists', async () => {
+    const adapter = createMockAdapter(async () => null);
+    const c = createMockContext();
+
+    await expect(
+      sessionMiddleware(adapter)(c, async () => {}),
+    ).rejects.toBeInstanceOf(VobaseError);
+
+    await expect(
+      sessionMiddleware(adapter)(c, async () => {}),
+    ).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+  });
+
+  it('optionalSessionMiddleware sets user to null and continues', async () => {
+    const next = mock(async () => {}) as unknown as Next;
+    const adapter = createMockAdapter(async () => null);
+    const c = createMockContext();
+
+    await optionalSessionMiddleware(adapter)(c, next);
+
+    expect(c.get('user')).toBeNull();
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

package/src/contracts/auth.ts

@@ -0,0 +1,37 @@
+/**
+ * Core contract for authentication. The auth adapter translates an incoming
+ * request into a user identity. Core uses this in the session middleware
+ * to populate ctx.user. The built-in auth module implements this via
+ * better-auth; users can swap in their own implementation.
+ */
+export interface AuthAdapter {
+  /**
+   * Extract user identity from a request. Returns null if unauthenticated.
+   * Must not throw — return null for invalid/expired sessions.
+   */
+  getSession(headers: Headers): Promise<AuthSession | null>;
+
+  /**
+   * The raw request handler for auth routes (sign-in, sign-up, etc.)
+   * Mounted at /api/auth/* by the auth module.
+   */
+  handler: (request: Request) => Promise<Response>;
+}
+
+export interface AuthSession {
+  user: AuthUser;
+  session: {
+    id: string;
+    expiresAt: Date;
+    token: string;
+  };
+}
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  name: string;
+  role: string;
+  /** Set when the user has an active organization (better-auth organization plugin) */
+  activeOrganizationId?: string;
+}

package/{dist/contracts/module.d.ts → src/contracts/module.ts}

@@ -3,15 +3,15 @@ import type { HttpClient } from '../infra/http-client';
 import type { NotifyService } from '../modules/notify/service';
 import type { StorageService } from '../modules/storage/service';
 import type { Scheduler } from '../infra/queue';
+
 /**
  * Context passed to a module's `init` hook during app boot.
  * Provides access to core infrastructure services.
  */
 export interface ModuleInitContext {
-    db: VobaseDb;
-    scheduler: Scheduler;
-    storage: StorageService;
-    http: HttpClient;
-    notify: NotifyService;
+  db: VobaseDb;
+  scheduler: Scheduler;
+  storage: StorageService;
+  http: HttpClient;
+  notify: NotifyService;
 }
-//# sourceMappingURL=module.d.ts.map

package/src/contracts/notify.ts

@@ -0,0 +1,47 @@
+/**
+ * Provider interfaces for the notify module. Each channel (email, WhatsApp)
+ * has its own provider interface with channel-specific options.
+ */
+export interface EmailProvider {
+  send(message: EmailMessage): Promise<EmailResult>;
+}
+
+export interface EmailMessage {
+  to: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  from?: string; // overrides default from in config
+  cc?: string[];
+  bcc?: string[];
+  replyTo?: string;
+  attachments?: EmailAttachment[];
+}
+
+export interface EmailAttachment {
+  filename: string;
+  content: Buffer | Uint8Array;
+  contentType?: string;
+}
+
+export interface EmailResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}
+
+export interface WhatsAppProvider {
+  send(message: WhatsAppMessage): Promise<WhatsAppResult>;
+}
+
+export interface WhatsAppMessage {
+  to: string; // E.164 phone number
+  template?: { name: string; language: string; parameters?: string[] };
+  text?: string;
+}
+
+export interface WhatsAppResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}

package/src/contracts/permissions.ts

@@ -0,0 +1,10 @@
+export interface Permission {
+  resource: string;
+  actions: string[];
+}
+
+export interface OrganizationContext {
+  organizationId: string;
+  role: string;
+  permissions?: Permission[];
+}

package/src/contracts/storage.ts

@@ -0,0 +1,61 @@
+/**
+ * Provider interface for storage backends. Each provider implements
+ * the physical operations; the storage module handles bucket resolution,
+ * metadata tracking, and access control on top.
+ */
+export interface StorageProvider {
+  upload(fullKey: string, data: Buffer | Uint8Array, opts?: UploadOptions): Promise<void>;
+  download(fullKey: string): Promise<Uint8Array>;
+  delete(fullKey: string): Promise<void>;
+  exists(fullKey: string): Promise<boolean>;
+  presign(fullKey: string, opts: PresignOptions): string;
+  list(prefix: string, opts?: ListOptions): Promise<StorageListResult>;
+}
+
+export interface UploadOptions {
+  contentType?: string;
+  metadata?: Record<string, string>;
+  /** Max upload size in bytes. Enforced server-side for direct uploads. */
+  maxSize?: number;
+}
+
+export interface PresignOptions {
+  expiresIn?: number; // seconds, default 3600
+  method?: 'GET' | 'PUT'; // default 'GET'
+}
+
+export interface ListOptions {
+  cursor?: string;
+  limit?: number; // default 100
+}
+
+export interface StorageListResult {
+  objects: StorageObjectInfo[];
+  cursor?: string; // undefined = no more results
+}
+
+export interface StorageObjectInfo {
+  key: string;
+  size: number;
+  contentType: string;
+  lastModified: Date;
+}
+
+/** Local filesystem provider */
+export interface LocalProviderConfig {
+  type: 'local';
+  basePath: string; // e.g. './data/files'
+  baseUrl?: string; // for presign proxy URLs, default '/api/storage'
+}
+
+/** S3-compatible provider (AWS, R2, MinIO) using Bun native S3 */
+export interface S3ProviderConfig {
+  type: 's3';
+  bucket: string;
+  region?: string;
+  endpoint?: string; // for R2, MinIO
+  accessKeyId: string;
+  secretAccessKey: string;
+}
+
+export type StorageProviderConfig = LocalProviderConfig | S3ProviderConfig;