@mariachi/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+
+interface Logger {
+    info(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+    error(obj: Record<string, unknown>, msg?: string): void;
+    debug(obj: Record<string, unknown>, msg?: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+interface Context {
+    traceId: string;
+    userId: string | null;
+    tenantId: string | null;
+    scopes: string[];
+    identityType: string;
+    apiKeyId?: string;
+    sessionId?: string;
+    logger: Logger;
+    server?: string;
+}
+declare function createContext(overrides: Partial<Context> & {
+    logger: Logger;
+}): Context;
+
+declare class MariachiError extends Error {
+    readonly code: string;
+    readonly metadata?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, metadata?: Record<string, unknown> | undefined);
+}
+declare class ConfigError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class DatabaseError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class CacheError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class AuthError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class CommunicationError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class BillingError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class StorageError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class NotificationError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class SearchError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class EventsError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class JobsError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class RateLimitError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class TenancyError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class AuditError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class AIError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class IntegrationError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare class LifecycleError extends MariachiError {
+    constructor(code: string, message: string, metadata?: Record<string, unknown>);
+}
+declare function errorToHttpStatus(error: MariachiError): number;
+
+type Handler<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> = (ctx: Context, input: z.infer<TInput>) => Promise<z.infer<TOutput>>;
+type Middleware = (ctx: Context, next: () => Promise<void>) => Promise<void>;
+interface HandlerRegistration<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+    schema: {
+        input: TInput;
+        output: TOutput;
+    };
+    handler: Handler<TInput, TOutput>;
+    middleware?: Middleware[];
+}
+interface PaginationParams {
+    page: number;
+    pageSize: number;
+}
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+interface SortParams {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+interface Entity {
+    id: string;
+}
+interface BaseEntity extends Entity {
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+interface TenantEntity extends BaseEntity {
+    tenantId: string;
+}
+
+type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E>(error: E): Result<never, E>;
+declare function unwrap<T, E>(result: Result<T, E>): T;
+declare function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T;
+declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+declare function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+declare function tryCatch<T>(fn: () => Promise<T>): Promise<Result<T, Error>>;
+
+interface Container {
+    register<T>(key: string | symbol, instance: T): void;
+    resolve<T>(key: string | symbol): T;
+    has(key: string | symbol): boolean;
+    clear(): void;
+}
+declare function createContainer(): Container;
+declare const KEYS: {
+    readonly Config: symbol;
+    readonly Logger: symbol;
+    readonly Tracer: symbol;
+    readonly Metrics: symbol;
+    readonly Database: symbol;
+    readonly Cache: symbol;
+    readonly EventBus: symbol;
+    readonly JobQueue: symbol;
+    readonly Auth: symbol;
+    readonly Authorization: symbol;
+    readonly Storage: symbol;
+    readonly Notifications: symbol;
+    readonly Billing: symbol;
+    readonly Search: symbol;
+    readonly AI: symbol;
+    readonly Communication: symbol;
+    readonly Lifecycle: symbol;
+    readonly RateLimit: symbol;
+    readonly Audit: symbol;
+    readonly Tenancy: symbol;
+    readonly Realtime: symbol;
+};
+declare function getContainer(): Container;
+
+interface Span {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: 'ok' | 'error', message?: string): void;
+    end(): void;
+}
+interface TracerAdapter {
+    startSpan(name: string, attributes?: Record<string, string>): Span;
+    withSpan<T>(name: string, fn: (span: Span) => Promise<T>): Promise<T>;
+}
+interface MetricsAdapter {
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    timing(name: string, value: number, tags?: Record<string, string>): void;
+}
+interface Instrumentable {
+    readonly logger: Logger;
+    readonly tracer?: TracerAdapter;
+    readonly metrics?: MetricsAdapter;
+}
+declare function withSpan<T>(tracer: TracerAdapter | undefined, name: string, attributes: Record<string, string | number | boolean>, fn: (span?: Span) => Promise<T>): Promise<T>;
+declare function timed<T>(metrics: MetricsAdapter | undefined, metricName: string, tags?: Record<string, string>): {
+    end: (success: boolean) => void;
+    wrap: (fn: () => Promise<T>) => Promise<T>;
+};
+
+interface RetryConfig {
+    attempts: number;
+    backoff: 'exponential' | 'linear' | 'fixed';
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: boolean;
+    retryOn?: (error: Error) => boolean;
+}
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+declare function retry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T>;
+
+interface Disposable {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isHealthy(): Promise<boolean>;
+}
+
+export { AIError, AuditError, AuthError, type BaseEntity, BillingError, CacheError, CommunicationError, ConfigError, type Container, type Context, DEFAULT_RETRY_CONFIG, DatabaseError, type Disposable, type Entity, EventsError, type Handler, type HandlerRegistration, type Instrumentable, IntegrationError, JobsError, KEYS, LifecycleError, type Logger, MariachiError, type MetricsAdapter, type Middleware, NotificationError, type PaginatedResult, type PaginationParams, RateLimitError, type Result, type RetryConfig, SearchError, type SortParams, type Span, StorageError, TenancyError, type TenantEntity, type TracerAdapter, createContainer, createContext, err, errorToHttpStatus, flatMap, getContainer, map, mapErr, ok, retry, timed, tryCatch, unwrap, unwrapOr, withSpan };

package/dist/index.js

@@ -0,0 +1,362 @@
+// src/context.ts
+function createContext(overrides) {
+  return {
+    traceId: overrides.traceId ?? crypto.randomUUID(),
+    userId: overrides.userId ?? null,
+    tenantId: overrides.tenantId ?? null,
+    scopes: overrides.scopes ?? [],
+    identityType: overrides.identityType ?? "anonymous",
+    apiKeyId: overrides.apiKeyId,
+    sessionId: overrides.sessionId,
+    logger: overrides.logger,
+    server: overrides.server
+  };
+}
+
+// src/errors.ts
+var MariachiError = class extends Error {
+  constructor(code, message, metadata) {
+    super(message);
+    this.code = code;
+    this.metadata = metadata;
+    this.name = "MariachiError";
+  }
+};
+var ConfigError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "ConfigError";
+  }
+};
+var DatabaseError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "DatabaseError";
+  }
+};
+var CacheError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "CacheError";
+  }
+};
+var AuthError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "AuthError";
+  }
+};
+var CommunicationError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "CommunicationError";
+  }
+};
+var BillingError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "BillingError";
+  }
+};
+var StorageError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "StorageError";
+  }
+};
+var NotificationError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "NotificationError";
+  }
+};
+var SearchError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "SearchError";
+  }
+};
+var EventsError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "EventsError";
+  }
+};
+var JobsError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "JobsError";
+  }
+};
+var RateLimitError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "RateLimitError";
+  }
+};
+var TenancyError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "TenancyError";
+  }
+};
+var AuditError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "AuditError";
+  }
+};
+var AIError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "AIError";
+  }
+};
+var IntegrationError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "IntegrationError";
+  }
+};
+var LifecycleError = class extends MariachiError {
+  constructor(code, message, metadata) {
+    super(code, message, metadata);
+    this.name = "LifecycleError";
+  }
+};
+var ERROR_CODE_TO_HTTP = {
+  "auth/unauthorized": 401,
+  "auth/forbidden": 403,
+  "auth/token-expired": 401,
+  "auth/invalid-token": 401,
+  "auth/invalid-api-key": 401,
+  "rate-limit/exceeded": 429,
+  "not-found": 404,
+  "validation/invalid-input": 400,
+  "billing/payment-failed": 402,
+  "conflict": 409
+};
+function errorToHttpStatus(error) {
+  for (const [prefix, status] of Object.entries(ERROR_CODE_TO_HTTP)) {
+    if (error.code === prefix || error.code.startsWith(`${prefix}/`)) {
+      return status;
+    }
+  }
+  return 500;
+}
+
+// src/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function unwrap(result) {
+  if (result.ok) return result.value;
+  throw result.error;
+}
+function unwrapOr(result, fallback) {
+  if (result.ok) return result.value;
+  return fallback;
+}
+function map(result, fn) {
+  if (result.ok) return ok(fn(result.value));
+  return result;
+}
+function mapErr(result, fn) {
+  if (!result.ok) return err(fn(result.error));
+  return result;
+}
+function flatMap(result, fn) {
+  if (result.ok) return fn(result.value);
+  return result;
+}
+async function tryCatch(fn) {
+  try {
+    return ok(await fn());
+  } catch (error) {
+    return err(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
+// src/container.ts
+function createContainer() {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    register(key, instance) {
+      store.set(key, instance);
+    },
+    resolve(key) {
+      const instance = store.get(key);
+      if (instance === void 0) {
+        throw new Error(`Container: no registration found for key "${String(key)}"`);
+      }
+      return instance;
+    },
+    has(key) {
+      return store.has(key);
+    },
+    clear() {
+      store.clear();
+    }
+  };
+}
+var KEYS = {
+  Config: /* @__PURE__ */ Symbol.for("mariachi.config"),
+  Logger: /* @__PURE__ */ Symbol.for("mariachi.logger"),
+  Tracer: /* @__PURE__ */ Symbol.for("mariachi.tracer"),
+  Metrics: /* @__PURE__ */ Symbol.for("mariachi.metrics"),
+  Database: /* @__PURE__ */ Symbol.for("mariachi.database"),
+  Cache: /* @__PURE__ */ Symbol.for("mariachi.cache"),
+  EventBus: /* @__PURE__ */ Symbol.for("mariachi.eventbus"),
+  JobQueue: /* @__PURE__ */ Symbol.for("mariachi.jobqueue"),
+  Auth: /* @__PURE__ */ Symbol.for("mariachi.auth"),
+  Authorization: /* @__PURE__ */ Symbol.for("mariachi.authorization"),
+  Storage: /* @__PURE__ */ Symbol.for("mariachi.storage"),
+  Notifications: /* @__PURE__ */ Symbol.for("mariachi.notifications"),
+  Billing: /* @__PURE__ */ Symbol.for("mariachi.billing"),
+  Search: /* @__PURE__ */ Symbol.for("mariachi.search"),
+  AI: /* @__PURE__ */ Symbol.for("mariachi.ai"),
+  Communication: /* @__PURE__ */ Symbol.for("mariachi.communication"),
+  Lifecycle: /* @__PURE__ */ Symbol.for("mariachi.lifecycle"),
+  RateLimit: /* @__PURE__ */ Symbol.for("mariachi.ratelimit"),
+  Audit: /* @__PURE__ */ Symbol.for("mariachi.audit"),
+  Tenancy: /* @__PURE__ */ Symbol.for("mariachi.tenancy"),
+  Realtime: /* @__PURE__ */ Symbol.for("mariachi.realtime")
+};
+var globalContainer = createContainer();
+function getContainer() {
+  return globalContainer;
+}
+
+// src/instrumentable.ts
+async function withSpan(tracer, name, attributes, fn) {
+  if (!tracer) return fn(void 0);
+  return tracer.withSpan(name, async (span) => {
+    for (const [k, v] of Object.entries(attributes)) {
+      span.setAttribute(k, v);
+    }
+    try {
+      const result = await fn(span);
+      span.setStatus("ok");
+      return result;
+    } catch (error) {
+      span.setStatus("error", error.message);
+      throw error;
+    }
+  });
+}
+function timed(metrics, metricName, tags) {
+  const start = performance.now();
+  return {
+    end(success) {
+      const durationMs = performance.now() - start;
+      metrics?.timing(metricName, durationMs, tags);
+      metrics?.increment(`${metricName}.count`, 1, tags);
+      if (!success) metrics?.increment(`${metricName}.error`, 1, tags);
+    },
+    async wrap(fn) {
+      try {
+        const result = await fn();
+        const durationMs = performance.now() - start;
+        metrics?.timing(metricName, durationMs, tags);
+        metrics?.increment(`${metricName}.count`, 1, tags);
+        return result;
+      } catch (error) {
+        const durationMs = performance.now() - start;
+        metrics?.timing(metricName, durationMs, tags);
+        metrics?.increment(`${metricName}.count`, 1, tags);
+        metrics?.increment(`${metricName}.error`, 1, tags);
+        throw error;
+      }
+    }
+  };
+}
+
+// src/retry.ts
+var DEFAULT_RETRY_CONFIG = {
+  attempts: 3,
+  backoff: "exponential",
+  baseDelayMs: 200,
+  maxDelayMs: 1e4,
+  jitter: true
+};
+function computeDelay(config, attempt) {
+  let delay;
+  switch (config.backoff) {
+    case "exponential":
+      delay = config.baseDelayMs * Math.pow(2, attempt);
+      break;
+    case "linear":
+      delay = config.baseDelayMs * (attempt + 1);
+      break;
+    case "fixed":
+      delay = config.baseDelayMs;
+      break;
+  }
+  delay = Math.min(delay, config.maxDelayMs);
+  if (config.jitter) {
+    delay = delay * (0.5 + Math.random() * 0.5);
+  }
+  return delay;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retry(fn, config = {}) {
+  const resolved = { ...DEFAULT_RETRY_CONFIG, ...config };
+  let lastError;
+  for (let attempt = 0; attempt < resolved.attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (resolved.retryOn && !resolved.retryOn(lastError)) {
+        throw lastError;
+      }
+      if (attempt < resolved.attempts - 1) {
+        await sleep(computeDelay(resolved, attempt));
+      }
+    }
+  }
+  throw lastError;
+}
+export {
+  AIError,
+  AuditError,
+  AuthError,
+  BillingError,
+  CacheError,
+  CommunicationError,
+  ConfigError,
+  DEFAULT_RETRY_CONFIG,
+  DatabaseError,
+  EventsError,
+  IntegrationError,
+  JobsError,
+  KEYS,
+  LifecycleError,
+  MariachiError,
+  NotificationError,
+  RateLimitError,
+  SearchError,
+  StorageError,
+  TenancyError,
+  createContainer,
+  createContext,
+  err,
+  errorToHttpStatus,
+  flatMap,
+  getContainer,
+  map,
+  mapErr,
+  ok,
+  retry,
+  timed,
+  tryCatch,
+  unwrap,
+  unwrapOr,
+  withSpan
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts","../src/errors.ts","../src/result.ts","../src/container.ts","../src/instrumentable.ts","../src/retry.ts"],"sourcesContent":["export interface Logger {\n  info(obj: Record<string, unknown>, msg?: string): void;\n  warn(obj: Record<string, unknown>, msg?: string): void;\n  error(obj: Record<string, unknown>, msg?: string): void;\n  debug(obj: Record<string, unknown>, msg?: string): void;\n  child(bindings: Record<string, unknown>): Logger;\n}\n\nexport interface Context {\n  traceId: string;\n  userId: string | null;\n  tenantId: string | null;\n  scopes: string[];\n  identityType: string;\n  apiKeyId?: string;\n  sessionId?: string;\n  logger: Logger;\n  server?: string;\n}\n\nexport function createContext(overrides: Partial<Context> & { logger: Logger }): Context {\n  return {\n    traceId: overrides.traceId ?? crypto.randomUUID(),\n    userId: overrides.userId ?? null,\n    tenantId: overrides.tenantId ?? null,\n    scopes: overrides.scopes ?? [],\n    identityType: overrides.identityType ?? 'anonymous',\n    apiKeyId: overrides.apiKeyId,\n    sessionId: overrides.sessionId,\n    logger: overrides.logger,\n    server: overrides.server,\n  };\n}\n","export class MariachiError extends Error {\n  constructor(\n    public readonly code: string,\n    message: string,\n    public readonly metadata?: Record<string, unknown>,\n  ) {\n    super(message);\n    this.name = 'MariachiError';\n  }\n}\n\nexport class ConfigError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'ConfigError';\n  }\n}\n\nexport class DatabaseError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'DatabaseError';\n  }\n}\n\nexport class CacheError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'CacheError';\n  }\n}\n\nexport class AuthError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'AuthError';\n  }\n}\n\nexport class CommunicationError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'CommunicationError';\n  }\n}\n\nexport class BillingError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'BillingError';\n  }\n}\n\nexport class StorageError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'StorageError';\n  }\n}\n\nexport class NotificationError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'NotificationError';\n  }\n}\n\nexport class SearchError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'SearchError';\n  }\n}\n\nexport class EventsError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'EventsError';\n  }\n}\n\nexport class JobsError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'JobsError';\n  }\n}\n\nexport class RateLimitError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'RateLimitError';\n  }\n}\n\nexport class TenancyError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'TenancyError';\n  }\n}\n\nexport class AuditError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'AuditError';\n  }\n}\n\nexport class AIError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'AIError';\n  }\n}\n\nexport class IntegrationError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'IntegrationError';\n  }\n}\n\nexport class LifecycleError extends MariachiError {\n  constructor(code: string, message: string, metadata?: Record<string, unknown>) {\n    super(code, message, metadata);\n    this.name = 'LifecycleError';\n  }\n}\n\nconst ERROR_CODE_TO_HTTP: Record<string, number> = {\n  'auth/unauthorized': 401,\n  'auth/forbidden': 403,\n  'auth/token-expired': 401,\n  'auth/invalid-token': 401,\n  'auth/invalid-api-key': 401,\n  'rate-limit/exceeded': 429,\n  'not-found': 404,\n  'validation/invalid-input': 400,\n  'billing/payment-failed': 402,\n  'conflict': 409,\n};\n\nexport function errorToHttpStatus(error: MariachiError): number {\n  for (const [prefix, status] of Object.entries(ERROR_CODE_TO_HTTP)) {\n    if (error.code === prefix || error.code.startsWith(`${prefix}/`)) {\n      return status;\n    }\n  }\n  return 500;\n}\n","export type Result<T, E = Error> =\n  | { ok: true; value: T }\n  | { ok: false; error: E };\n\nexport function ok<T>(value: T): Result<T, never> {\n  return { ok: true, value };\n}\n\nexport function err<E>(error: E): Result<never, E> {\n  return { ok: false, error };\n}\n\nexport function unwrap<T, E>(result: Result<T, E>): T {\n  if (result.ok) return result.value;\n  throw result.error;\n}\n\nexport function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T {\n  if (result.ok) return result.value;\n  return fallback;\n}\n\nexport function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> {\n  if (result.ok) return ok(fn(result.value));\n  return result;\n}\n\nexport function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> {\n  if (!result.ok) return err(fn(result.error));\n  return result;\n}\n\nexport function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E> {\n  if (result.ok) return fn(result.value);\n  return result;\n}\n\nexport async function tryCatch<T>(fn: () => Promise<T>): Promise<Result<T, Error>> {\n  try {\n    return ok(await fn());\n  } catch (error) {\n    return err(error instanceof Error ? error : new Error(String(error)));\n  }\n}\n","const registry = new Map<string | symbol, unknown>();\n\nexport interface Container {\n  register<T>(key: string | symbol, instance: T): void;\n  resolve<T>(key: string | symbol): T;\n  has(key: string | symbol): boolean;\n  clear(): void;\n}\n\nexport function createContainer(): Container {\n  const store = new Map<string | symbol, unknown>();\n\n  return {\n    register<T>(key: string | symbol, instance: T): void {\n      store.set(key, instance);\n    },\n\n    resolve<T>(key: string | symbol): T {\n      const instance = store.get(key);\n      if (instance === undefined) {\n        throw new Error(`Container: no registration found for key \"${String(key)}\"`);\n      }\n      return instance as T;\n    },\n\n    has(key: string | symbol): boolean {\n      return store.has(key);\n    },\n\n    clear(): void {\n      store.clear();\n    },\n  };\n}\n\nexport const KEYS = {\n  Config: Symbol.for('mariachi.config'),\n  Logger: Symbol.for('mariachi.logger'),\n  Tracer: Symbol.for('mariachi.tracer'),\n  Metrics: Symbol.for('mariachi.metrics'),\n  Database: Symbol.for('mariachi.database'),\n  Cache: Symbol.for('mariachi.cache'),\n  EventBus: Symbol.for('mariachi.eventbus'),\n  JobQueue: Symbol.for('mariachi.jobqueue'),\n  Auth: Symbol.for('mariachi.auth'),\n  Authorization: Symbol.for('mariachi.authorization'),\n  Storage: Symbol.for('mariachi.storage'),\n  Notifications: Symbol.for('mariachi.notifications'),\n  Billing: Symbol.for('mariachi.billing'),\n  Search: Symbol.for('mariachi.search'),\n  AI: Symbol.for('mariachi.ai'),\n  Communication: Symbol.for('mariachi.communication'),\n  Lifecycle: Symbol.for('mariachi.lifecycle'),\n  RateLimit: Symbol.for('mariachi.ratelimit'),\n  Audit: Symbol.for('mariachi.audit'),\n  Tenancy: Symbol.for('mariachi.tenancy'),\n  Realtime: Symbol.for('mariachi.realtime'),\n} as const;\n\nconst globalContainer = createContainer();\n\nexport function getContainer(): Container {\n  return globalContainer;\n}\n","import type { Logger } from './context';\n\nexport interface Span {\n  setAttribute(key: string, value: string | number | boolean): void;\n  setStatus(status: 'ok' | 'error', message?: string): void;\n  end(): void;\n}\n\nexport interface TracerAdapter {\n  startSpan(name: string, attributes?: Record<string, string>): Span;\n  withSpan<T>(name: string, fn: (span: Span) => Promise<T>): Promise<T>;\n}\n\nexport interface MetricsAdapter {\n  increment(name: string, value?: number, tags?: Record<string, string>): void;\n  gauge(name: string, value: number, tags?: Record<string, string>): void;\n  histogram(name: string, value: number, tags?: Record<string, string>): void;\n  timing(name: string, value: number, tags?: Record<string, string>): void;\n}\n\nexport interface Instrumentable {\n  readonly logger: Logger;\n  readonly tracer?: TracerAdapter;\n  readonly metrics?: MetricsAdapter;\n}\n\nexport async function withSpan<T>(\n  tracer: TracerAdapter | undefined,\n  name: string,\n  attributes: Record<string, string | number | boolean>,\n  fn: (span?: Span) => Promise<T>,\n): Promise<T> {\n  if (!tracer) return fn(undefined);\n  return tracer.withSpan(name, async (span) => {\n    for (const [k, v] of Object.entries(attributes)) {\n      span.setAttribute(k, v);\n    }\n    try {\n      const result = await fn(span);\n      span.setStatus('ok');\n      return result;\n    } catch (error) {\n      span.setStatus('error', (error as Error).message);\n      throw error;\n    }\n  });\n}\n\nexport function timed<T>(\n  metrics: MetricsAdapter | undefined,\n  metricName: string,\n  tags?: Record<string, string>,\n): { end: (success: boolean) => void; wrap: (fn: () => Promise<T>) => Promise<T> } {\n  const start = performance.now();\n  return {\n    end(success: boolean) {\n      const durationMs = performance.now() - start;\n      metrics?.timing(metricName, durationMs, tags);\n      metrics?.increment(`${metricName}.count`, 1, tags);\n      if (!success) metrics?.increment(`${metricName}.error`, 1, tags);\n    },\n    async wrap(fn: () => Promise<T>): Promise<T> {\n      try {\n        const result = await fn();\n        const durationMs = performance.now() - start;\n        metrics?.timing(metricName, durationMs, tags);\n        metrics?.increment(`${metricName}.count`, 1, tags);\n        return result;\n      } catch (error) {\n        const durationMs = performance.now() - start;\n        metrics?.timing(metricName, durationMs, tags);\n        metrics?.increment(`${metricName}.count`, 1, tags);\n        metrics?.increment(`${metricName}.error`, 1, tags);\n        throw error;\n      }\n    },\n  };\n}\n","export interface RetryConfig {\n  attempts: number;\n  backoff: 'exponential' | 'linear' | 'fixed';\n  baseDelayMs: number;\n  maxDelayMs: number;\n  jitter: boolean;\n  retryOn?: (error: Error) => boolean;\n}\n\nexport const DEFAULT_RETRY_CONFIG: RetryConfig = {\n  attempts: 3,\n  backoff: 'exponential',\n  baseDelayMs: 200,\n  maxDelayMs: 10_000,\n  jitter: true,\n};\n\nfunction computeDelay(config: RetryConfig, attempt: number): number {\n  let delay: number;\n  switch (config.backoff) {\n    case 'exponential':\n      delay = config.baseDelayMs * Math.pow(2, attempt);\n      break;\n    case 'linear':\n      delay = config.baseDelayMs * (attempt + 1);\n      break;\n    case 'fixed':\n      delay = config.baseDelayMs;\n      break;\n  }\n  delay = Math.min(delay, config.maxDelayMs);\n  if (config.jitter) {\n    delay = delay * (0.5 + Math.random() * 0.5);\n  }\n  return delay;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nexport async function retry<T>(\n  fn: () => Promise<T>,\n  config: Partial<RetryConfig> = {},\n): Promise<T> {\n  const resolved: RetryConfig = { ...DEFAULT_RETRY_CONFIG, ...config };\n  let lastError: Error | undefined;\n\n  for (let attempt = 0; attempt < resolved.attempts; attempt++) {\n    try {\n      return await fn();\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n      if (resolved.retryOn && !resolved.retryOn(lastError)) {\n        throw lastError;\n      }\n      if (attempt < resolved.attempts - 1) {\n        await sleep(computeDelay(resolved, attempt));\n      }\n    }\n  }\n\n  throw lastError;\n}\n"],"mappings":"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","names":[]}

package/docs/adr/001-adapter-pattern.md

@@ -0,0 +1,42 @@
+# ADR 001: Adapter Pattern for External Dependencies
+
+## Status
+
+Accepted
+
+## Context
+
+The framework integrates with many external systems: databases (PostgreSQL), caches (Redis), message queues (BullMQ), payment providers (Stripe), search engines (Typesense), AI providers (OpenAI), and others. Direct use of vendor SDKs creates:
+
+- **Vendor lock-in** — Switching providers requires large refactors.
+- **Testing friction** — Real services are slow and brittle in tests.
+- **Configuration sprawl** — Each vendor has different setup patterns.
+
+## Decision
+
+All external dependencies are placed behind adapters. Each package exposes:
+
+1. A **common interface** (e.g., `CacheClient`, `SearchClient`).
+2. A **factory function** (e.g., `createCache`, `createSearch`) that selects the implementation from config.
+3. **Multiple implementations** — at least one production adapter (Redis, Stripe, etc.) and one in-memory adapter for tests.
+
+Config drives the choice:
+
+```ts
+createCache({ adapter: 'redis', url: '...' });  // production
+createCache({ adapter: 'memory' });              // tests
+```
+
+## Consequences
+
+**Positive:**
+
+- Full portability: swap Redis for another cache without changing application code.
+- Tests run fast with in-memory adapters; no external services required.
+- Consistent configuration pattern across packages.
+
+**Negative:**
+
+- More code: each adapter is a thin wrapper around the vendor SDK.
+- New adapters require implementing the full interface.
+- Some vendor-specific features may not map cleanly to the abstraction.