@geenius/tools 0.1.0 → 0.3.0

package/packages/env/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @geenius/tools-env — Environment variable validation and management\n *\n * Provides schema-based environment variable validation using Zod.\n * Validates at runtime and provides type-safe access to env vars.\n */\n\nimport { z, ZodSchema } from 'zod/v4'\n\n/**\n * Environment variable schema definition\n */\nexport type EnvSchema = Record<string, ZodSchema>\n\n/**\n * Configuration for environment validation\n */\nexport interface EnvConfig {\n  /** Whether to throw on validation error (default: true) */\n  throw?: boolean\n  /** Prefix to add to all env var names (e.g., 'REACT_APP_') */\n  prefix?: string\n  /** Default values for optional variables */\n  defaults?: Record<string, unknown>\n}\n\n/**\n * Validates environment variables against a Zod schema\n *\n * @param schema Zod schema defining expected environment variables\n * @param config Validation configuration options\n * @returns Validated environment variables as typed object\n * @throws Error if validation fails and throw option is true\n *\n * @example\n * ```ts\n * const envSchema = {\n *   DATABASE_URL: z.string().url(),\n *   API_KEY: z.string(),\n *   DEBUG: z.enum(['true', 'false']).optional(),\n * }\n *\n * const env = validateEnv(envSchema, { throw: true })\n * // env is now { DATABASE_URL: string, API_KEY: string, DEBUG?: string }\n * ```\n */\nexport function validateEnv<T extends EnvSchema>(\n  schema: T,\n  config: EnvConfig = {}\n): Partial<{ [K in keyof T]: unknown }> {\n  const { prefix = '', defaults = {}, throw: shouldThrow = true } = config\n\n  const envVars: Record<string, unknown> = {}\n\n  // Collect env variables with prefix\n  for (const key of Object.keys(schema)) {\n    const prefixedKey = prefix ? `${prefix}${key}` : key\n    const value = process.env[prefixedKey] ?? defaults[key]\n\n    if (value !== undefined) {\n      envVars[key] = value\n    }\n  }\n\n  // Validate using zod\n  const schemaObj = z.object(schema as Record<string, ZodSchema>)\n  const result = schemaObj.safeParse(envVars)\n\n  if (!result.success) {\n    const errors = result.error.issues\n      .map((e) => `${e.path.join('.')}: ${e.message}`)\n      .join(', ')\n\n    const message = `Environment validation failed: ${errors}`\n\n    if (shouldThrow) {\n      throw new Error(message)\n    }\n\n    console.error(message)\n    return {}\n  }\n\n  return result.data as Partial<{ [K in keyof T]: unknown }>\n}\n\n/**\n * Creates a reusable environment validator\n *\n * @param schema Zod schema\n * @param config Default configuration\n * @returns Validator function\n *\n * @example\n * ```ts\n * const validator = createEnvValidator(\n *   { DATABASE_URL: z.string().url() },\n *   { throw: true }\n * )\n * const env = validator()\n * ```\n */\nexport function createEnvValidator<T extends EnvSchema>(\n  schema: T,\n  config: EnvConfig = {}\n) {\n  return () => validateEnv(schema, config)\n}\n\n/**\n * Gets a single environment variable with optional validation\n *\n * @param key Environment variable key\n * @param schema Optional Zod schema for validation\n * @param defaultValue Default value if not found\n * @returns Environment variable value or default\n *\n * @example\n * ```ts\n * const apiKey = getEnv('API_KEY', z.string().min(1))\n * ```\n */\nexport function getEnv<T = string>(\n  key: string,\n  schema?: ZodSchema,\n  defaultValue?: T\n): T | undefined {\n  const value = process.env[key] ?? defaultValue\n\n  if (!value) return undefined\n\n  if (schema) {\n    const result = schema.safeParse(value)\n    if (!result.success) {\n      throw new Error(`Invalid env var ${key}: ${result.error.message}`)\n    }\n    return result.data as T\n  }\n\n  return value as T\n}\n\n/**\n * Checks if environment variable exists and is set\n *\n * @param key Variable name\n * @returns True if variable exists\n */\nexport function hasEnv(key: string): boolean {\n  return key in process.env\n}\n\n/**\n * Gets multiple environment variables at once\n *\n * @param keys List of environment variable keys\n * @returns Object with available values\n *\n * @example\n * ```ts\n * const { API_KEY, DEBUG } = getEnvs(['API_KEY', 'DEBUG'])\n * ```\n */\nexport function getEnvs(keys: string[]): Record<string, string | undefined> {\n  return keys.reduce(\n    (acc, key) => {\n      acc[key] = process.env[key]\n      return acc\n    },\n    {} as Record<string, string | undefined>\n  )\n}\n\n/**\n * Asserts that all required environment variables are set\n *\n * @param requiredKeys List of required variable names\n * @throws Error if any required variable is missing\n *\n * @example\n * ```ts\n * requireEnv(['DATABASE_URL', 'API_KEY'])\n * ```\n */\nexport function requireEnv(requiredKeys: string[]): void {\n  const missing = requiredKeys.filter((key) => !(key in process.env))\n\n  if (missing.length > 0) {\n    throw new Error(\n      `Missing required environment variables: ${missing.join(', ')}`\n    )\n  }\n}\n\n/**\n * Parses environment variable as JSON\n *\n * @param key Environment variable key\n * @param defaultValue Default object if parsing fails\n * @returns Parsed JSON object\n *\n * @example\n * ```ts\n * const config = parseEnvJson('APP_CONFIG', { theme: 'light' })\n * ```\n */\nexport function parseEnvJson<T = unknown>(\n  key: string,\n  defaultValue?: T\n): T | undefined {\n  const value = process.env[key]\n\n  if (!value) return defaultValue\n\n  try {\n    return JSON.parse(value) as T\n  } catch {\n    console.warn(`Failed to parse ${key} as JSON`)\n    return defaultValue\n  }\n}\n\n/**\n * Parses environment variable as boolean\n *\n * @param key Environment variable key\n * @param defaultValue Default value\n * @returns Boolean value\n *\n * @example\n * ```ts\n * const debug = parseEnvBool('DEBUG', false)\n * ```\n */\nexport function parseEnvBool(key: string, defaultValue = false): boolean {\n  const value = process.env[key]\n\n  if (!value) return defaultValue\n\n  return ['true', '1', 'yes', 'on'].includes(value.toLowerCase())\n}\n\n/**\n * Parses environment variable as number\n *\n * @param key Environment variable key\n * @param defaultValue Default value\n * @returns Numeric value\n *\n * @example\n * ```ts\n * const port = parseEnvNumber('PORT', 3000)\n * ```\n */\nexport function parseEnvNumber(key: string, defaultValue = 0): number {\n  const value = process.env[key]\n\n  if (!value) return defaultValue\n\n  const num = Number(value)\n  return isNaN(num) ? defaultValue : num\n}\n\nexport type { ZodSchema } from 'zod/v4'\n"],"mappings":";AAOA,SAAS,SAAoB;AAuCtB,SAAS,YACd,QACA,SAAoB,CAAC,GACiB;AACtC,QAAM,EAAE,SAAS,IAAI,WAAW,CAAC,GAAG,OAAO,cAAc,KAAK,IAAI;AAElE,QAAM,UAAmC,CAAC;AAG1C,aAAW,OAAO,OAAO,KAAK,MAAM,GAAG;AACrC,UAAM,cAAc,SAAS,GAAG,MAAM,GAAG,GAAG,KAAK;AACjD,UAAM,QAAQ,QAAQ,IAAI,WAAW,KAAK,SAAS,GAAG;AAEtD,QAAI,UAAU,QAAW;AACvB,cAAQ,GAAG,IAAI;AAAA,IACjB;AAAA,EACF;AAGA,QAAM,YAAY,EAAE,OAAO,MAAmC;AAC9D,QAAM,SAAS,UAAU,UAAU,OAAO;AAE1C,MAAI,CAAC,OAAO,SAAS;AACnB,UAAM,SAAS,OAAO,MAAM,OACzB,IAAI,CAAC,MAAM,GAAG,EAAE,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAC9C,KAAK,IAAI;AAEZ,UAAM,UAAU,kCAAkC,MAAM;AAExD,QAAI,aAAa;AACf,YAAM,IAAI,MAAM,OAAO;AAAA,IACzB;AAEA,YAAQ,MAAM,OAAO;AACrB,WAAO,CAAC;AAAA,EACV;AAEA,SAAO,OAAO;AAChB;AAkBO,SAAS,mBACd,QACA,SAAoB,CAAC,GACrB;AACA,SAAO,MAAM,YAAY,QAAQ,MAAM;AACzC;AAeO,SAAS,OACd,KACA,QACA,cACe;AACf,QAAM,QAAQ,QAAQ,IAAI,GAAG,KAAK;AAElC,MAAI,CAAC,MAAO,QAAO;AAEnB,MAAI,QAAQ;AACV,UAAM,SAAS,OAAO,UAAU,KAAK;AACrC,QAAI,CAAC,OAAO,SAAS;AACnB,YAAM,IAAI,MAAM,mBAAmB,GAAG,KAAK,OAAO,MAAM,OAAO,EAAE;AAAA,IACnE;AACA,WAAO,OAAO;AAAA,EAChB;AAEA,SAAO;AACT;AAQO,SAAS,OAAO,KAAsB;AAC3C,SAAO,OAAO,QAAQ;AACxB;AAaO,SAAS,QAAQ,MAAoD;AAC1E,SAAO,KAAK;AAAA,IACV,CAAC,KAAK,QAAQ;AACZ,UAAI,GAAG,IAAI,QAAQ,IAAI,GAAG;AAC1B,aAAO;AAAA,IACT;AAAA,IACA,CAAC;AAAA,EACH;AACF;AAaO,SAAS,WAAW,cAA8B;AACvD,QAAM,UAAU,aAAa,OAAO,CAAC,QAAQ,EAAE,OAAO,QAAQ,IAAI;AAElE,MAAI,QAAQ,SAAS,GAAG;AACtB,UAAM,IAAI;AAAA,MACR,2CAA2C,QAAQ,KAAK,IAAI,CAAC;AAAA,IAC/D;AAAA,EACF;AACF;AAcO,SAAS,aACd,KACA,cACe;AACf,QAAM,QAAQ,QAAQ,IAAI,GAAG;AAE7B,MAAI,CAAC,MAAO,QAAO;AAEnB,MAAI;AACF,WAAO,KAAK,MAAM,KAAK;AAAA,EACzB,QAAQ;AACN,YAAQ,KAAK,mBAAmB,GAAG,UAAU;AAC7C,WAAO;AAAA,EACT;AACF;AAcO,SAAS,aAAa,KAAa,eAAe,OAAgB;AACvE,QAAM,QAAQ,QAAQ,IAAI,GAAG;AAE7B,MAAI,CAAC,MAAO,QAAO;AAEnB,SAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,EAAE,SAAS,MAAM,YAAY,CAAC;AAChE;AAcO,SAAS,eAAe,KAAa,eAAe,GAAW;AACpE,QAAM,QAAQ,QAAQ,IAAI,GAAG;AAE7B,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,MAAM,OAAO,KAAK;AACxB,SAAO,MAAM,GAAG,IAAI,eAAe;AACrC;","names":[]}

package/packages/errors/dist/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @geenius/tools-errors — Structured error handling
+ *
+ * Provides a hierarchy of typed errors for different error scenarios.
+ * Enables consistent error handling and formatting across the Geenius ecosystem.
+ */
+/**
+ * Error codes for different error types
+ */
+declare enum ErrorCode {
+    UNKNOWN = "UNKNOWN",
+    VALIDATION = "VALIDATION",
+    NOT_FOUND = "NOT_FOUND",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    CONFLICT = "CONFLICT",
+    INTERNAL = "INTERNAL",
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    SESSION_EXPIRED = "SESSION_EXPIRED",
+    MFA_REQUIRED = "MFA_REQUIRED",
+    INVALID_TOKEN = "INVALID_TOKEN",
+    DATABASE_ERROR = "DATABASE_ERROR",
+    CONSTRAINT_VIOLATION = "CONSTRAINT_VIOLATION",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT = "TIMEOUT",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    MISSING_CONFIG = "MISSING_CONFIG"
+}
+/**
+ * Base Geenius error with structured information
+ */
+interface GeeniusErrorOptions {
+    /** Error code for classification */
+    code?: ErrorCode;
+    /** User-friendly message */
+    message: string;
+    /** Technical details */
+    cause?: Error | unknown;
+    /** HTTP status code equivalent */
+    statusCode?: number;
+    /** Contextual data */
+    context?: Record<string, unknown>;
+    /** Whether error should be logged */
+    log?: boolean;
+}
+/**
+ * Structured error class for Geenius packages
+ *
+ * @example
+ * ```ts
+ * throw new GeeniusError({
+ *   code: ErrorCode.VALIDATION,
+ *   message: 'Invalid email format',
+ *   statusCode: 400,
+ *   context: { field: 'email' }
+ * })
+ * ```
+ */
+declare class GeeniusError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode: number;
+    readonly context: Record<string, unknown>;
+    readonly cause?: Error | unknown;
+    readonly log: boolean;
+    constructor(options: GeeniusErrorOptions);
+    /**
+     * Gets HTTP status code for error code
+     */
+    private getDefaultStatusCode;
+    /**
+     * Converts error to JSON for serialization
+     */
+    toJSON(): {
+        cause?: Record<string, unknown> | undefined;
+        name: string;
+        code: ErrorCode;
+        message: string;
+        statusCode: number;
+        context: Record<string, unknown>;
+    };
+    /**
+     * Converts error to string representation
+     */
+    toString(): string;
+}
+/**
+ * Validation error for form/input validation failures
+ *
+ * @example
+ * ```ts
+ * throw new ValidationError({
+ *   message: 'Invalid input',
+ *   context: { errors: { email: 'Invalid format' } }
+ * })
+ * ```
+ */
+declare class ValidationError extends GeeniusError {
+    constructor(options: Omit<GeeniusErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Authentication error
+ */
+declare class AuthError extends GeeniusError {
+    constructor(options: Omit<GeeniusErrorOptions, 'statusCode'>);
+}
+/**
+ * Not found error
+ */
+declare class NotFoundError extends GeeniusError {
+    constructor(options: Omit<GeeniusErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Conflict error (e.g., duplicate key)
+ */
+declare class ConflictError extends GeeniusError {
+    constructor(options: Omit<GeeniusErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Formats any error into structured format
+ *
+ * @param error Error to format
+ * @returns Formatted error object
+ */
+declare function formatError(error: unknown): Record<string, unknown>;
+/**
+ * Type guard to check if error is GeeniusError
+ *
+ * @param error Error to check
+ * @returns True if error is GeeniusError
+ */
+declare function isGeeniusError(error: unknown): error is GeeniusError;
+/**
+ * Type guard to check if error is a specific error code
+ *
+ * @param error Error to check
+ * @param code Error code to match
+ * @returns True if error has specified code
+ */
+declare function isErrorCode(error: unknown, code: ErrorCode): boolean;
+/**
+ * Wraps a promise to catch and transform errors
+ *
+ * @param promise Promise to wrap
+ * @param handler Error transformation function
+ * @returns Promise with transformed errors
+ *
+ * @example
+ * ```ts
+ * const result = await catchError(
+ *   fetchApi(),
+ *   (err) => new GeeniusError({
+ *     code: ErrorCode.NETWORK_ERROR,
+ *     message: 'API request failed',
+ *     cause: err
+ *   })
+ * )
+ * ```
+ */
+declare function catchError<T>(promise: Promise<T>, handler: (error: unknown) => Error): Promise<T>;
+/**
+ * Creates a safe function that handles errors
+ *
+ * @param fn Function to wrap
+ * @param handler Error transformation
+ * @returns Safe version of function
+ *
+ * @example
+ * ```ts
+ * const safeOp = makeSafe(
+ *   (id: string) => db.user.find(id),
+ *   (err) => new NotFoundError({ message: 'User not found', cause: err })
+ * )
+ * ```
+ */
+declare function makeSafe<T extends (...args: any[]) => any>(fn: T, handler: (error: unknown) => Error): T;
+
+export { AuthError, ConflictError, ErrorCode, GeeniusError, type GeeniusErrorOptions, NotFoundError, ValidationError, catchError, formatError, isErrorCode, isGeeniusError, makeSafe };

package/packages/errors/dist/index.js

@@ -0,0 +1,187 @@
+// src/index.ts
+var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
+  ErrorCode2["UNKNOWN"] = "UNKNOWN";
+  ErrorCode2["VALIDATION"] = "VALIDATION";
+  ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
+  ErrorCode2["UNAUTHORIZED"] = "UNAUTHORIZED";
+  ErrorCode2["FORBIDDEN"] = "FORBIDDEN";
+  ErrorCode2["CONFLICT"] = "CONFLICT";
+  ErrorCode2["INTERNAL"] = "INTERNAL";
+  ErrorCode2["INVALID_CREDENTIALS"] = "INVALID_CREDENTIALS";
+  ErrorCode2["SESSION_EXPIRED"] = "SESSION_EXPIRED";
+  ErrorCode2["MFA_REQUIRED"] = "MFA_REQUIRED";
+  ErrorCode2["INVALID_TOKEN"] = "INVALID_TOKEN";
+  ErrorCode2["DATABASE_ERROR"] = "DATABASE_ERROR";
+  ErrorCode2["CONSTRAINT_VIOLATION"] = "CONSTRAINT_VIOLATION";
+  ErrorCode2["NETWORK_ERROR"] = "NETWORK_ERROR";
+  ErrorCode2["TIMEOUT"] = "TIMEOUT";
+  ErrorCode2["INVALID_CONFIG"] = "INVALID_CONFIG";
+  ErrorCode2["MISSING_CONFIG"] = "MISSING_CONFIG";
+  return ErrorCode2;
+})(ErrorCode || {});
+var GeeniusError = class _GeeniusError extends Error {
+  code;
+  statusCode;
+  context;
+  cause;
+  log;
+  constructor(options) {
+    super(options.message);
+    this.name = "GeeniusError";
+    this.code = options.code ?? "UNKNOWN" /* UNKNOWN */;
+    this.statusCode = options.statusCode ?? this.getDefaultStatusCode(this.code);
+    this.context = options.context ?? {};
+    this.cause = options.cause;
+    this.log = options.log !== false;
+    Object.setPrototypeOf(this, _GeeniusError.prototype);
+  }
+  /**
+   * Gets HTTP status code for error code
+   */
+  getDefaultStatusCode(code) {
+    const statusMap = {
+      ["UNKNOWN" /* UNKNOWN */]: 500,
+      ["VALIDATION" /* VALIDATION */]: 400,
+      ["NOT_FOUND" /* NOT_FOUND */]: 404,
+      ["UNAUTHORIZED" /* UNAUTHORIZED */]: 401,
+      ["FORBIDDEN" /* FORBIDDEN */]: 403,
+      ["CONFLICT" /* CONFLICT */]: 409,
+      ["INTERNAL" /* INTERNAL */]: 500,
+      ["INVALID_CREDENTIALS" /* INVALID_CREDENTIALS */]: 401,
+      ["SESSION_EXPIRED" /* SESSION_EXPIRED */]: 401,
+      ["MFA_REQUIRED" /* MFA_REQUIRED */]: 403,
+      ["INVALID_TOKEN" /* INVALID_TOKEN */]: 401,
+      ["DATABASE_ERROR" /* DATABASE_ERROR */]: 500,
+      ["CONSTRAINT_VIOLATION" /* CONSTRAINT_VIOLATION */]: 409,
+      ["NETWORK_ERROR" /* NETWORK_ERROR */]: 502,
+      ["TIMEOUT" /* TIMEOUT */]: 504,
+      ["INVALID_CONFIG" /* INVALID_CONFIG */]: 500,
+      ["MISSING_CONFIG" /* MISSING_CONFIG */]: 500
+    };
+    return statusMap[code];
+  }
+  /**
+   * Converts error to JSON for serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      context: this.context,
+      ...this.cause ? { cause: formatError(this.cause) } : {}
+    };
+  }
+  /**
+   * Converts error to string representation
+   */
+  toString() {
+    return `${this.name} [${this.code}]: ${this.message}`;
+  }
+};
+var ValidationError = class _ValidationError extends GeeniusError {
+  constructor(options) {
+    super({
+      ...options,
+      code: "VALIDATION" /* VALIDATION */,
+      statusCode: 400
+    });
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var AuthError = class _AuthError extends GeeniusError {
+  constructor(options) {
+    super({
+      ...options,
+      code: options.code ?? "INVALID_CREDENTIALS" /* INVALID_CREDENTIALS */,
+      statusCode: 401
+    });
+    this.name = "AuthError";
+    Object.setPrototypeOf(this, _AuthError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends GeeniusError {
+  constructor(options) {
+    super({
+      ...options,
+      code: "NOT_FOUND" /* NOT_FOUND */,
+      statusCode: 404
+    });
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+var ConflictError = class _ConflictError extends GeeniusError {
+  constructor(options) {
+    super({
+      ...options,
+      code: "CONFLICT" /* CONFLICT */,
+      statusCode: 409
+    });
+    this.name = "ConflictError";
+    Object.setPrototypeOf(this, _ConflictError.prototype);
+  }
+};
+function formatError(error) {
+  if (error instanceof GeeniusError) {
+    return error.toJSON();
+  }
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+  }
+  if (typeof error === "string") {
+    return { message: error };
+  }
+  if (typeof error === "object" && error !== null) {
+    return error;
+  }
+  return { message: String(error) };
+}
+function isGeeniusError(error) {
+  return error instanceof GeeniusError;
+}
+function isErrorCode(error, code) {
+  return isGeeniusError(error) && error.code === code;
+}
+async function catchError(promise, handler) {
+  try {
+    return await promise;
+  } catch (error) {
+    throw handler(error);
+  }
+}
+function makeSafe(fn, handler) {
+  return ((...args) => {
+    try {
+      const result = fn(...args);
+      if (result instanceof Promise) {
+        return result.catch((err) => {
+          throw handler(err);
+        });
+      }
+      return result;
+    } catch (error) {
+      throw handler(error);
+    }
+  });
+}
+export {
+  AuthError,
+  ConflictError,
+  ErrorCode,
+  GeeniusError,
+  NotFoundError,
+  ValidationError,
+  catchError,
+  formatError,
+  isErrorCode,
+  isGeeniusError,
+  makeSafe
+};
+//# sourceMappingURL=index.js.map

package/packages/errors/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @geenius/tools-errors — Structured error handling\n *\n * Provides a hierarchy of typed errors for different error scenarios.\n * Enables consistent error handling and formatting across the Geenius ecosystem.\n */\n\n/**\n * Error codes for different error types\n */\nexport enum ErrorCode {\n  // Generic\n  UNKNOWN = 'UNKNOWN',\n  VALIDATION = 'VALIDATION',\n  NOT_FOUND = 'NOT_FOUND',\n  UNAUTHORIZED = 'UNAUTHORIZED',\n  FORBIDDEN = 'FORBIDDEN',\n  CONFLICT = 'CONFLICT',\n  INTERNAL = 'INTERNAL',\n\n  // Auth-specific\n  INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',\n  SESSION_EXPIRED = 'SESSION_EXPIRED',\n  MFA_REQUIRED = 'MFA_REQUIRED',\n  INVALID_TOKEN = 'INVALID_TOKEN',\n\n  // Database\n  DATABASE_ERROR = 'DATABASE_ERROR',\n  CONSTRAINT_VIOLATION = 'CONSTRAINT_VIOLATION',\n\n  // Network\n  NETWORK_ERROR = 'NETWORK_ERROR',\n  TIMEOUT = 'TIMEOUT',\n\n  // Configuration\n  INVALID_CONFIG = 'INVALID_CONFIG',\n  MISSING_CONFIG = 'MISSING_CONFIG',\n}\n\n/**\n * Base Geenius error with structured information\n */\nexport interface GeeniusErrorOptions {\n  /** Error code for classification */\n  code?: ErrorCode\n  /** User-friendly message */\n  message: string\n  /** Technical details */\n  cause?: Error | unknown\n  /** HTTP status code equivalent */\n  statusCode?: number\n  /** Contextual data */\n  context?: Record<string, unknown>\n  /** Whether error should be logged */\n  log?: boolean\n}\n\n/**\n * Structured error class for Geenius packages\n *\n * @example\n * ```ts\n * throw new GeeniusError({\n *   code: ErrorCode.VALIDATION,\n *   message: 'Invalid email format',\n *   statusCode: 400,\n *   context: { field: 'email' }\n * })\n * ```\n */\nexport class GeeniusError extends Error {\n  readonly code: ErrorCode\n  readonly statusCode: number\n  readonly context: Record<string, unknown>\n  readonly cause?: Error | unknown\n  readonly log: boolean\n\n  constructor(options: GeeniusErrorOptions) {\n    super(options.message)\n    this.name = 'GeeniusError'\n    this.code = options.code ?? ErrorCode.UNKNOWN\n    this.statusCode = options.statusCode ?? this.getDefaultStatusCode(this.code)\n    this.context = options.context ?? {}\n    this.cause = options.cause\n    this.log = options.log !== false\n\n    // Maintain proper prototype chain\n    Object.setPrototypeOf(this, GeeniusError.prototype)\n  }\n\n  /**\n   * Gets HTTP status code for error code\n   */\n  private getDefaultStatusCode(code: ErrorCode): number {\n    const statusMap: Record<ErrorCode, number> = {\n      [ErrorCode.UNKNOWN]: 500,\n      [ErrorCode.VALIDATION]: 400,\n      [ErrorCode.NOT_FOUND]: 404,\n      [ErrorCode.UNAUTHORIZED]: 401,\n      [ErrorCode.FORBIDDEN]: 403,\n      [ErrorCode.CONFLICT]: 409,\n      [ErrorCode.INTERNAL]: 500,\n      [ErrorCode.INVALID_CREDENTIALS]: 401,\n      [ErrorCode.SESSION_EXPIRED]: 401,\n      [ErrorCode.MFA_REQUIRED]: 403,\n      [ErrorCode.INVALID_TOKEN]: 401,\n      [ErrorCode.DATABASE_ERROR]: 500,\n      [ErrorCode.CONSTRAINT_VIOLATION]: 409,\n      [ErrorCode.NETWORK_ERROR]: 502,\n      [ErrorCode.TIMEOUT]: 504,\n      [ErrorCode.INVALID_CONFIG]: 500,\n      [ErrorCode.MISSING_CONFIG]: 500,\n    }\n    return statusMap[code]\n  }\n\n  /**\n   * Converts error to JSON for serialization\n   */\n  toJSON() {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      statusCode: this.statusCode,\n      context: this.context,\n      ...(this.cause ? { cause: formatError(this.cause) } : {}),\n    }\n  }\n\n  /**\n   * Converts error to string representation\n   */\n  toString(): string {\n    return `${this.name} [${this.code}]: ${this.message}`\n  }\n}\n\n/**\n * Validation error for form/input validation failures\n *\n * @example\n * ```ts\n * throw new ValidationError({\n *   message: 'Invalid input',\n *   context: { errors: { email: 'Invalid format' } }\n * })\n * ```\n */\nexport class ValidationError extends GeeniusError {\n  constructor(options: Omit<GeeniusErrorOptions, 'code' | 'statusCode'>) {\n    super({\n      ...options,\n      code: ErrorCode.VALIDATION,\n      statusCode: 400,\n    })\n    this.name = 'ValidationError'\n    Object.setPrototypeOf(this, ValidationError.prototype)\n  }\n}\n\n/**\n * Authentication error\n */\nexport class AuthError extends GeeniusError {\n  constructor(options: Omit<GeeniusErrorOptions, 'statusCode'>) {\n    super({\n      ...options,\n      code: options.code ?? ErrorCode.INVALID_CREDENTIALS,\n      statusCode: 401,\n    })\n    this.name = 'AuthError'\n    Object.setPrototypeOf(this, AuthError.prototype)\n  }\n}\n\n/**\n * Not found error\n */\nexport class NotFoundError extends GeeniusError {\n  constructor(options: Omit<GeeniusErrorOptions, 'code' | 'statusCode'>) {\n    super({\n      ...options,\n      code: ErrorCode.NOT_FOUND,\n      statusCode: 404,\n    })\n    this.name = 'NotFoundError'\n    Object.setPrototypeOf(this, NotFoundError.prototype)\n  }\n}\n\n/**\n * Conflict error (e.g., duplicate key)\n */\nexport class ConflictError extends GeeniusError {\n  constructor(options: Omit<GeeniusErrorOptions, 'code' | 'statusCode'>) {\n    super({\n      ...options,\n      code: ErrorCode.CONFLICT,\n      statusCode: 409,\n    })\n    this.name = 'ConflictError'\n    Object.setPrototypeOf(this, ConflictError.prototype)\n  }\n}\n\n/**\n * Formats any error into structured format\n *\n * @param error Error to format\n * @returns Formatted error object\n */\nexport function formatError(error: unknown): Record<string, unknown> {\n  if (error instanceof GeeniusError) {\n    return error.toJSON()\n  }\n\n  if (error instanceof Error) {\n    return {\n      name: error.name,\n      message: error.message,\n      stack: error.stack,\n    }\n  }\n\n  if (typeof error === 'string') {\n    return { message: error }\n  }\n\n  if (typeof error === 'object' && error !== null) {\n    return error as Record<string, unknown>\n  }\n\n  return { message: String(error) }\n}\n\n/**\n * Type guard to check if error is GeeniusError\n *\n * @param error Error to check\n * @returns True if error is GeeniusError\n */\nexport function isGeeniusError(error: unknown): error is GeeniusError {\n  return error instanceof GeeniusError\n}\n\n/**\n * Type guard to check if error is a specific error code\n *\n * @param error Error to check\n * @param code Error code to match\n * @returns True if error has specified code\n */\nexport function isErrorCode(error: unknown, code: ErrorCode): boolean {\n  return isGeeniusError(error) && error.code === code\n}\n\n/**\n * Wraps a promise to catch and transform errors\n *\n * @param promise Promise to wrap\n * @param handler Error transformation function\n * @returns Promise with transformed errors\n *\n * @example\n * ```ts\n * const result = await catchError(\n *   fetchApi(),\n *   (err) => new GeeniusError({\n *     code: ErrorCode.NETWORK_ERROR,\n *     message: 'API request failed',\n *     cause: err\n *   })\n * )\n * ```\n */\nexport async function catchError<T>(\n  promise: Promise<T>,\n  handler: (error: unknown) => Error\n): Promise<T> {\n  try {\n    return await promise\n  } catch (error) {\n    throw handler(error)\n  }\n}\n\n/**\n * Creates a safe function that handles errors\n *\n * @param fn Function to wrap\n * @param handler Error transformation\n * @returns Safe version of function\n *\n * @example\n * ```ts\n * const safeOp = makeSafe(\n *   (id: string) => db.user.find(id),\n *   (err) => new NotFoundError({ message: 'User not found', cause: err })\n * )\n * ```\n */\nexport function makeSafe<T extends (...args: any[]) => any>(\n  fn: T,\n  handler: (error: unknown) => Error\n): T {\n  return ((...args: any[]) => {\n    try {\n      const result = fn(...args)\n      if (result instanceof Promise) {\n        return result.catch((err: unknown) => {\n          throw handler(err)\n        })\n      }\n      return result\n    } catch (error) {\n      throw handler(error)\n    }\n  }) as T\n}\n"],"mappings":"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","names":["ErrorCode"]}

package/packages/errors/react/README.md

@@ -1 +1 @@
-# ✦ @geenius-tools/errors-react\n\n> React error handling UI — boundaries, displays, analytics dashboard, hooks & utilities\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add @geenius-tools/errors-react\n```\n\n## Usage\n\n```typescript\nimport { init } from '@geenius-tools/errors-react';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n
+# ✦ @geenius/tools-errors-react\n\n> React error handling UI — boundaries, displays, analytics dashboard, hooks & utilities\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add @geenius/tools-errors-react\n```\n\n## Usage\n\n```typescript\nimport { init } from '@geenius/tools-errors-react';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n

package/packages/errors/solidjs/README.md

@@ -1 +1 @@
-# ✦ @geenius-tools/errors-solidjs\n\n> SolidJS error handling UI — boundaries, displays, hooks & utilities\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add @geenius-tools/errors-solidjs\n```\n\n## Usage\n\n```typescript\nimport { init } from '@geenius-tools/errors-solidjs';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n
+# ✦ @geenius/tools-errors-solidjs\n\n> SolidJS error handling UI — boundaries, displays, hooks & utilities\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add @geenius/tools-errors-solidjs\n```\n\n## Usage\n\n```typescript\nimport { init } from '@geenius/tools-errors-solidjs';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n

package/packages/logger/dist/index.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @geenius/tools-logger — Structured logging
+ *
+ * Provides structured logging with levels, formatting, and contextual data.
+ * Suitable for both client and server environments.
+ */
+/**
+ * Log levels in order of severity
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    FATAL = 4
+}
+/**
+ * Log entry structure
+ */
+interface LogEntry {
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Contextual data */
+    context?: Record<string, unknown>;
+    /** Error object if applicable */
+    error?: Error | unknown;
+    /** Timestamp */
+    timestamp: Date;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Log formatter function
+ */
+type LogFormatter = (entry: LogEntry) => string;
+/**
+ * Logger transport (where logs go)
+ */
+interface LogTransport {
+    /** Log handler function */
+    log(entry: LogEntry): void | Promise<void>;
+}
+/**
+ * Logger configuration
+ */
+interface LoggerConfig {
+    /** Minimum log level to output (default: INFO) */
+    level?: LogLevel;
+    /** Custom formatter (default: pretty print) */
+    formatter?: LogFormatter;
+    /** Log transports */
+    transports?: LogTransport[];
+    /** Whether to include timestamps (default: true) */
+    timestamps?: boolean;
+    /** Whether to include source location (default: false) */
+    sourceLocation?: boolean;
+}
+/**
+ * Structured logger with context and levels
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger({ level: LogLevel.DEBUG })
+ *
+ * logger.info('User signed in', { userId: '123' })
+ * logger.error('Database error', { error })
+ * logger.debug('Cache hit', { key: 'user:123' })
+ * ```
+ */
+declare class Logger {
+    private level;
+    private formatter;
+    private transports;
+    private timestamps;
+    private sourceLocation;
+    private context;
+    constructor(config?: LoggerConfig);
+    /**
+     * Logs with debug level
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Logs with info level
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Logs with warn level
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Logs with error level
+     */
+    error(message: string, error?: Error | unknown, context?: Record<string, unknown>): void;
+    /**
+     * Logs with fatal level
+     */
+    fatal(message: string, error?: Error | unknown, context?: Record<string, unknown>): void;
+    /**
+     * Core logging method
+     */
+    private log;
+    /**
+     * Sets context for all subsequent logs
+     */
+    setContext(key: string, value: unknown): this;
+    /**
+     * Gets current context
+     */
+    getContext(): Record<string, unknown>;
+    /**
+     * Clears context
+     */
+    clearContext(): this;
+    /**
+     * Creates a child logger with inherited context
+     */
+    child(context: Record<string, unknown>): Logger;
+    /**
+     * Gets source location from stack trace
+     */
+    private getSourceLocation;
+}
+/**
+ * Console transport for logging to stdout/stderr
+ */
+declare const consoleTransport: LogTransport;
+/**
+ * Creates a new logger instance
+ *
+ * @param config Logger configuration
+ * @returns Configured logger
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger({
+ *   level: LogLevel.DEBUG,
+ *   timestamps: true
+ * })
+ * ```
+ */
+declare function createLogger(config?: LoggerConfig): Logger;
+/**
+ * Gets or creates global logger
+ *
+ * @param config Configuration for initial creation
+ * @returns Global logger instance
+ */
+declare function getGlobalLogger(config?: LoggerConfig): Logger;
+/**
+ * Resets global logger (for testing)
+ */
+declare function resetGlobalLogger(): void;
+/**
+ * Memory transport for testing and analysis
+ */
+declare class MemoryTransport implements LogTransport {
+    private entries;
+    log(entry: LogEntry): void;
+    /** Gets all logged entries */
+    getEntries(): LogEntry[];
+    /** Gets entries by level */
+    getByLevel(level: LogLevel): LogEntry[];
+    /** Clears all entries */
+    clear(): void;
+    /** Gets count of entries */
+    size(): number;
+}
+
+export { type LogEntry, type LogFormatter, LogLevel, type LogTransport, Logger, type LoggerConfig, MemoryTransport, consoleTransport, createLogger, getGlobalLogger, resetGlobalLogger };