@hadoku/worker-utils 0.0.0-stage → 1.6.20

package/dist/cloudflareWorkerLogger.d.ts

@@ -0,0 +1,71 @@
+import { Context } from 'hono';
+import { WorkerLogger } from '@wolffm/logger/worker';
+import { LoggerConfig, LogLevel } from './types.js';
+
+/**
+ * Worker logging surface — thin adapter that maps the legacy
+ * `@wolffm/worker-utils/logging` API onto `@wolffm/logger/worker`.
+ *
+ * The actual logger implementation (level filtering, stdout/stderr routing,
+ * service tag, event() convention, optional telemetry sink) lives in
+ * @wolffm/logger. This file preserves the existing call-site surface so the
+ * 21 worker import sites in this repo don't all need to change in one PR:
+ *
+ *   createLogger({ prefix: '[task-api]' })
+ *   logRequest('GET', '/path', ctx)
+ *   logError('POST', '/path', err)
+ *   createRequestLogger('POST', '/path', baseCtx)
+ *   loggerMiddleware({ prefix: '[task-api]' })
+ *
+ * keep working byte-identically. The only behavior change is that lines
+ * now carry a [service] tag from the shared logger (the prefix you pass
+ * here is the service name).
+ *
+ * Stateless utilities below (formatError, startTimer, redactFields,
+ * SENSITIVE_FIELDS) are not "logger implementation" — they're convenience
+ * formatters that any caller can use independent of the logger. Kept here
+ * unchanged.
+ */
+
+/**
+ * Create a worker logger. Adapter signature preserved for the existing
+ * `createLogger({prefix, minLevel, ...})` consumers; internally just builds
+ * a @wolffm/logger/worker instance.
+ */
+declare function createLogger(config?: LoggerConfig): WorkerLogger;
+/**
+ * Log HTTP request. Maps to the shared logger; preserved verbatim signature.
+ */
+declare function logRequest(method: string, path: string, context?: Record<string, any>, level?: LogLevel): void;
+/**
+ * Log error for HTTP request. Same signature; flattens Error.stack into the
+ * context object so it survives the structured log payload.
+ */
+declare function logError(method: string, path: string, error: string | Error, context?: Record<string, any>): void;
+/**
+ * Create request-scoped logger that includes method and path in every line.
+ * Wraps a child of the shared logger with the request prefix baked in.
+ */
+declare function createRequestLogger(method: string, path: string, baseContext?: Record<string, any>): {
+    debug: (message: string, context?: Record<string, any>) => void;
+    info: (message: string, context?: Record<string, any>) => void;
+    warn: (message: string, context?: Record<string, any>) => void;
+    error: (message: string, context?: Record<string, any>) => void;
+};
+/**
+ * Hono middleware: stash a logger in the context under the given key.
+ */
+declare function loggerMiddleware(config?: LoggerConfig, contextKey?: string): (c: Context, next: () => Promise<void>) => Promise<void>;
+/** Format an Error for safe inclusion in a log context. */
+declare function formatError(error: Error | string): Record<string, any>;
+/** Wall-clock timer for ad-hoc duration logging. */
+declare function startTimer(): {
+    end: (message: string, context?: Record<string, any>) => number;
+    elapsed: () => number;
+};
+/** Redact sensitive fields from an object before logging it. */
+declare function redactFields(obj: Record<string, any>, fields: string[]): Record<string, any>;
+/** Common field names to pass to `redactFields`. */
+declare const SENSITIVE_FIELDS: string[];
+
+export { SENSITIVE_FIELDS, createLogger, createRequestLogger, formatError, logError, logRequest, loggerMiddleware, redactFields, startTimer };

package/dist/cloudflareWorkerLogger.js

@@ -0,0 +1,94 @@
+// cloudflareWorkerLogger.ts
+import { createWorkerLogger } from "@wolffm/logger/worker";
+function deriveService(prefix) {
+  if (!prefix) return "worker";
+  const trimmed = prefix.trim();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function createLogger(config = {}) {
+  return createWorkerLogger({
+    service: deriveService(config.prefix),
+    minLevel: config.minLevel ?? "info"
+  });
+}
+var defaultLogger = createWorkerLogger({ service: "worker" });
+function logRequest(method, path, context, level = "info") {
+  defaultLogger[level](`[${method} ${path}]`, context);
+}
+function logError(method, path, error, context) {
+  const message = error instanceof Error ? error.message : error;
+  const ctx = { ...context ?? {} };
+  if (error instanceof Error && error.stack) ctx.stack = error.stack;
+  defaultLogger.error(`[${method} ${path}] ${message}`, ctx);
+}
+function createRequestLogger(method, path, baseContext = {}) {
+  const scoped = defaultLogger.child(`${method} ${path}`);
+  const merge = (extra) => ({ ...baseContext, ...extra ?? {} });
+  return {
+    debug: (message, context) => scoped.debug(message, merge(context)),
+    info: (message, context) => scoped.info(message, merge(context)),
+    warn: (message, context) => scoped.warn(message, merge(context)),
+    error: (message, context) => scoped.error(message, merge(context))
+  };
+}
+function loggerMiddleware(config = {}, contextKey = "logger") {
+  return async (c, next) => {
+    const logger = createLogger(config);
+    c.set(contextKey, logger);
+    await next();
+  };
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message, stack: error.stack };
+  }
+  return { error: String(error) };
+}
+function startTimer() {
+  const start = Date.now();
+  return {
+    end: (message, context) => {
+      const duration = Date.now() - start;
+      defaultLogger.info(`${message} (duration: ${duration}ms)`, context);
+      return duration;
+    },
+    elapsed: () => Date.now() - start
+  };
+}
+function redactFields(obj, fields) {
+  const redacted = { ...obj };
+  for (const field of fields) {
+    if (field in redacted) redacted[field] = "[REDACTED]";
+  }
+  return redacted;
+}
+var SENSITIVE_FIELDS = [
+  "password",
+  "apiKey",
+  "api_key",
+  "token",
+  "accessToken",
+  "access_token",
+  "refreshToken",
+  "refresh_token",
+  "secret",
+  "privateKey",
+  "private_key",
+  "authorization",
+  "cookie",
+  "session"
+];
+export {
+  SENSITIVE_FIELDS,
+  createLogger,
+  createRequestLogger,
+  formatError,
+  logError,
+  logRequest,
+  loggerMiddleware,
+  redactFields,
+  startTimer
+};

package/dist/content-level.d.ts

@@ -0,0 +1,52 @@
+export { Tier } from './auth.js';
+import 'hono';
+import './types.js';
+
+/**
+ * Global content-visibility level — the shared policy table.
+ *
+ * The LEVEL itself is a property of the person, stored once as prefs-api's D1
+ * `users.content_visibility_level` column (global, not app-namespaced, because
+ * it follows the user across every content app). This module holds only the
+ * policy that derives from tier: the floor, and each tier's ceiling.
+ *
+ * WHY IT LIVES HERE AND NOT IN EITHER WORKER
+ * ------------------------------------------
+ * Three places need it and they must agree:
+ *   - prefs-api  — enforces the ceiling on `PUT /api/v1/content-level` (400s
+ *                  anything above it).
+ *   - edge-router — resolves the level for `X-Hadoku-Content-Level`, and now
+ *                  reports both level and ceiling from `/session/whoami`.
+ *   - the client — renders one pill segment per ceiling step.
+ *
+ * A second copy of the ceiling is a live bug, not just duplication: whoami
+ * would advertise a ceiling the PUT refuses, so the UI renders a segment that
+ * 400s when clicked. `DEFAULT_CONTENT_LEVEL` was already duplicated between
+ * the two workers ("matches the prefs-api users column default") — this folds
+ * that copy in too.
+ */
+
+/** Floor, and the fail-safe answer everywhere: the public-safe level.
+ *  Matches the DEFAULT on prefs-api's `users.content_visibility_level`. */
+declare const DEFAULT_CONTENT_LEVEL = 1;
+/**
+ * Ceiling per tier. A tier ABSENT here gets `DEFAULT_CONTENT_LEVEL` — which is
+ * the fail-closed reading, and the correct one for `public`: an anonymous
+ * caller has no control to render and no level to raise.
+ *
+ * `wife` is deliberately 3, matching service/friend rather than admin: it is
+ * an AUTH elevation, and the level-4 ceiling stays an operator-only decision.
+ */
+declare const MAX_CONTENT_LEVEL_BY_TIER: Record<'admin' | 'wife' | 'service' | 'friend' | 'member', number>;
+/**
+ * Ceiling for a tier NAME, fail-closed on anything unrecognised.
+ *
+ * Takes the raw string rather than a narrowed union on purpose: callers get
+ * the tier from the edge as a header or a registry row, and an old bundle that
+ * predates a newly-added tier must clamp to the floor rather than widen — the
+ * same fail-closed property TIER_RANK has. Reading TIER_RANK here keeps the
+ * two tables' notion of "is this even a tier" from drifting apart.
+ */
+declare function maxContentLevelForTier(tier: string | undefined | null): number;
+
+export { DEFAULT_CONTENT_LEVEL, MAX_CONTENT_LEVEL_BY_TIER, maxContentLevelForTier };

package/dist/content-level.js

@@ -0,0 +1,28 @@
+// auth.ts
+var TIER_RANK = {
+  public: 0,
+  member: 1,
+  friend: 2,
+  service: 3,
+  wife: 4,
+  admin: 5
+};
+
+// content-level.ts
+var DEFAULT_CONTENT_LEVEL = 1;
+var MAX_CONTENT_LEVEL_BY_TIER = {
+  admin: 4,
+  wife: 3,
+  service: 3,
+  friend: 3,
+  member: 3
+};
+function maxContentLevelForTier(tier) {
+  if (!tier || TIER_RANK[tier] === void 0) return DEFAULT_CONTENT_LEVEL;
+  return MAX_CONTENT_LEVEL_BY_TIER[tier] ?? DEFAULT_CONTENT_LEVEL;
+}
+export {
+  DEFAULT_CONTENT_LEVEL,
+  MAX_CONTENT_LEVEL_BY_TIER,
+  maxContentLevelForTier
+};

package/dist/context.d.ts

@@ -0,0 +1,110 @@
+import { Context } from 'hono';
+import { ContextExtractionConfig } from './types.js';
+
+/**
+ * Context extraction utilities for Cloudflare Workers
+ *
+ * Generic helpers to extract common request context (userId, sessionId, etc.)
+ * from headers, query parameters, or request body.
+ *
+ * @example
+ * ```typescript
+ * // Extract multiple fields at once
+ * const context = extractContext(c, {
+ *   fields: {
+ *     userId: ['header:X-User-Id', 'query:userId'],
+ *     sessionId: ['header:X-Session-Id'],
+ *     boardId: ['query:boardId', 'body:boardId']
+ *   },
+ *   defaults: { boardId: 'main', userId: 'anonymous' }
+ * });
+ * // Result: { userId: '123', sessionId: 'abc', boardId: 'main' }
+ *
+ * // Extract single field with fallbacks
+ * const userId = extractField(c, ['header:X-User-Id', 'query:userId'], 'anonymous');
+ * ```
+ */
+
+/**
+ * Extract a single field from multiple sources (in priority order)
+ *
+ * @param c - Hono context
+ * @param sources - Array of sources to check (e.g., ['header:X-User-Id', 'query:userId'])
+ * @param defaultValue - Default value if not found in any source
+ * @param transform - Optional transform function
+ * @returns Extracted value or default
+ *
+ * @example
+ * ```typescript
+ * const userId = extractField(c, ['header:X-User-Id', 'query:userId'], 'public');
+ * const boardId = extractField(c, ['query:boardId', 'body:boardId'], 'main');
+ * const email = extractField(
+ *   c,
+ *   ['header:X-User-Email', 'body:email'],
+ *   undefined,
+ *   (val) => val?.toLowerCase()
+ * );
+ * ```
+ */
+declare function extractField<T = string>(c: Context, sources: string[], defaultValue?: T, transform?: (value: string) => T): T | undefined;
+/**
+ * Extract multiple fields from request based on configuration
+ *
+ * @param c - Hono context
+ * @param config - Extraction configuration
+ * @returns Object with extracted fields
+ *
+ * @example
+ * ```typescript
+ * const context = extractContext(c, {
+ *   fields: {
+ *     userId: ['header:X-User-Id', 'query:userId'],
+ *     sessionId: ['header:X-Session-Id'],
+ *     boardId: ['query:boardId', 'body:boardId'],
+ *     limit: ['query:limit']
+ *   },
+ *   defaults: {
+ *     boardId: 'main',
+ *     userId: 'public',
+ *     limit: 100
+ *   },
+ *   transforms: {
+ *     userId: (val) => val?.toLowerCase(),
+ *     limit: (val) => parseInt(val, 10)
+ *   }
+ * });
+ * ```
+ */
+declare function extractContext<T extends Record<string, any>>(c: Context, config: ContextExtractionConfig): T;
+/**
+ * Parse a request body as JSON, returning a fallback on parse failure.
+ *
+ * Re-added to worker-utils 1.2.1 after consumers (notably @wolffm/task) kept
+ * importing it past the 15c3376 cleanup that removed it. Keeping the original
+ * 1.0.0 signature so consumer call sites need no changes.
+ */
+declare function parseBody<T = any>(c: Context, fallback?: T): Promise<T>;
+/**
+ * Helper to get request metadata (IP, user-agent, etc.)
+ *
+ * @param c - Hono context
+ * @returns Request metadata object
+ *
+ * @example
+ * ```typescript
+ * const metadata = getRequestMetadata(c);
+ * // { ip: '1.2.3.4', userAgent: 'Mozilla/5.0...', country: 'US', ... }
+ * ```
+ */
+declare function getRequestMetadata(c: Context): {
+    ip: string | undefined;
+    userAgent: string | undefined;
+    country: string | undefined;
+    city: string | undefined;
+    region: string | undefined;
+    timezone: string | undefined;
+    colo: string | undefined;
+    requestId: string;
+};
+
+export { extractContext, extractField, getRequestMetadata, parseBody };

package/dist/context.js

@@ -0,0 +1,75 @@
+// context.ts
+function extractField(c, sources, defaultValue, transform) {
+  for (const source of sources) {
+    const [type, key] = source.split(":");
+    let value;
+    switch (type.toLowerCase()) {
+      case "header":
+        value = c.req.header(key);
+        break;
+      case "query":
+        value = c.req.query(key);
+        break;
+      case "body":
+        value = void 0;
+        break;
+      case "param":
+        value = c.req.param(key);
+        break;
+      case "cookie": {
+        const cookieHeader = c.req.header("Cookie");
+        if (cookieHeader) {
+          const cookies = Object.fromEntries(
+            cookieHeader.split(";").map((cookie) => {
+              const [k, v] = cookie.trim().split("=");
+              return [k, v];
+            })
+          );
+          value = cookies[key];
+        }
+        break;
+      }
+      default:
+        continue;
+    }
+    if (value !== void 0 && value !== null && value !== "") {
+      return transform ? transform(value) : value;
+    }
+  }
+  return defaultValue;
+}
+function extractContext(c, config) {
+  const result = {};
+  for (const [fieldName, sources] of Object.entries(config.fields)) {
+    const defaultValue = config.defaults?.[fieldName];
+    const transform = config.transforms?.[fieldName];
+    result[fieldName] = extractField(c, sources, defaultValue, transform);
+  }
+  return result;
+}
+async function parseBody(c, fallback = {}) {
+  try {
+    return await c.req.json();
+  } catch {
+    return fallback;
+  }
+}
+function getRequestMetadata(c) {
+  const cf = c.req.raw.cf;
+  return {
+    ip: c.req.header("CF-Connecting-IP") || c.req.header("X-Forwarded-For"),
+    userAgent: c.req.header("User-Agent"),
+    country: cf?.country,
+    city: cf?.city,
+    region: cf?.region,
+    timezone: cf?.timezone,
+    colo: cf?.colo,
+    requestId: c.req.header("CF-Ray") || crypto.randomUUID()
+  };
+}
+export {
+  extractContext,
+  extractField,
+  getRequestMetadata,
+  parseBody
+};

package/dist/cors.d.ts

@@ -0,0 +1,123 @@
+import * as hono from 'hono';
+import { CORSConfig } from './types.js';
+
+/**
+ * Default CORS origins for Hadoku services
+ */
+declare const DEFAULT_HADOKU_ORIGINS: string[];
+/**
+ * Check if origin matches pattern (supports wildcards)
+ *
+ * @param origin - Origin to check
+ * @param pattern - Pattern to match against (supports * wildcards)
+ * @returns True if origin matches pattern
+ *
+ * @example
+ * ```typescript
+ * matchOrigin('http://localhost:3000', 'http://localhost:*') // true
+ * matchOrigin('https://api.hadoku.me', 'https://*.hadoku.me') // true
+ * matchOrigin('https://evil.com', 'https://hadoku.me') // false
+ * ```
+ */
+declare function matchOrigin(origin: string, pattern: string): boolean;
+/**
+ * Check if origin is allowed based on config
+ *
+ * @param origin - Origin to check
+ * @param allowedOrigins - Array of allowed origin patterns
+ * @returns True if origin is allowed
+ */
+declare function isOriginAllowed(origin: string, allowedOrigins: string[]): boolean;
+/**
+ * Create CORS middleware with configuration
+ *
+ * @param config - CORS configuration
+ * @returns Hono CORS middleware
+ *
+ * @example
+ * ```typescript
+ * const corsMiddleware = createCorsMiddleware({
+ *   origins: ['https://hadoku.me', 'http://localhost:*'],
+ *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
+ *   credentials: true
+ * });
+ *
+ * app.use('*', corsMiddleware);
+ * ```
+ */
+declare function createCorsMiddleware(config: CORSConfig): hono.MiddlewareHandler;
+/**
+ * Create CORS middleware with Hadoku defaults
+ *
+ * @param additionalOrigins - Additional origins to allow
+ * @returns Hono CORS middleware
+ *
+ * @example
+ * ```typescript
+ * // Use Hadoku defaults
+ * app.use('*', createHadokuCors());
+ *
+ * // Add custom origins
+ * app.use('*', createHadokuCors(['https://custom-domain.com']));
+ * ```
+ */
+declare function createHadokuCors(additionalOrigins?: string[]): hono.MiddlewareHandler;
+/**
+ * Preset CORS configurations for common scenarios
+ */
+declare const CORSPresets: {
+    /**
+     * Development - Allow all localhost origins
+     */
+    development: {
+        origins: string[];
+        credentials: boolean;
+    };
+    /**
+     * Production - Strict origin checking
+     */
+    production: (domains: string[]) => {
+        origins: string[];
+        credentials: boolean;
+        maxAge: number;
+    };
+    /**
+     * Public API - Allow all origins (no credentials)
+     */
+    publicApi: {
+        origins: string[];
+        credentials: boolean;
+    };
+    /**
+     * Hadoku standard - Production + development origins
+     */
+    hadoku: {
+        origins: string[];
+        credentials: boolean;
+        maxAge: number;
+    };
+};
+/**
+ * Helper to add custom CORS headers manually
+ * (use when you need more control than middleware provides)
+ *
+ * @param origin - Request origin
+ * @param allowedOrigins - Allowed origin patterns
+ * @returns Headers object
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/data', (c) => {
+ *   const origin = c.req.header('Origin');
+ *   const corsHeaders = getCorsHeaders(origin, ['https://hadoku.me']);
+ *
+ *   return c.json({ data: '...' }, { headers: corsHeaders });
+ * });
+ * ```
+ */
+declare function getCorsHeaders(origin: string | undefined, allowedOrigins: string[], options?: {
+    credentials?: boolean;
+    exposedHeaders?: string[];
+}): Record<string, string>;
+
+export { CORSPresets, DEFAULT_HADOKU_ORIGINS, createCorsMiddleware, createHadokuCors, getCorsHeaders, isOriginAllowed, matchOrigin };

package/dist/cors.js

@@ -0,0 +1,113 @@
+// cors.ts
+import { cors } from "hono/cors";
+
+// edge-routes.ts
+var EDGE_BASE = "https://hadoku.me";
+var MGMT_BASE = `${EDGE_BASE}/mgmt`;
+var MONITORING_BASE = `${EDGE_BASE}/health`;
+var SCRAPER_BASE = `${EDGE_BASE}/scraper`;
+var CONTACT_BASE = `${EDGE_BASE}/contact`;
+var RESUME_BASE = `${EDGE_BASE}/resume`;
+var DISPATCH_BASE = `${EDGE_BASE}/dispatch`;
+var PREFS_BASE = `${EDGE_BASE}/prefs`;
+var JOBPLATFORM_BASE = `${EDGE_BASE}/jobplatform`;
+
+// cors.ts
+var DEFAULT_HADOKU_ORIGINS = [
+  EDGE_BASE,
+  "https://task-api.hadoku.me",
+  "http://localhost:*"
+];
+function matchOrigin(origin, pattern) {
+  if (origin === pattern) return true;
+  if (pattern.includes("*")) {
+    const regexPattern = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(origin);
+  }
+  return false;
+}
+function isOriginAllowed(origin, allowedOrigins) {
+  return allowedOrigins.some((pattern) => matchOrigin(origin, pattern));
+}
+function createCorsMiddleware(config) {
+  const {
+    origins,
+    methods = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allowedHeaders,
+    exposedHeaders,
+    credentials = true,
+    maxAge = 86400
+  } = config;
+  return cors({
+    origin: (origin) => {
+      if (!origin) return origins[0];
+      return isOriginAllowed(origin, origins) ? origin : origins[0];
+    },
+    allowMethods: methods,
+    allowHeaders: allowedHeaders,
+    exposeHeaders: exposedHeaders,
+    credentials,
+    maxAge
+  });
+}
+function createHadokuCors(additionalOrigins = []) {
+  return createCorsMiddleware({
+    origins: [...DEFAULT_HADOKU_ORIGINS, ...additionalOrigins],
+    credentials: true
+  });
+}
+var CORSPresets = {
+  /**
+   * Development - Allow all localhost origins
+   */
+  development: {
+    origins: ["http://localhost:*", "http://127.0.0.1:*"],
+    credentials: true
+  },
+  /**
+   * Production - Strict origin checking
+   */
+  production: (domains) => ({
+    origins: domains,
+    credentials: true,
+    maxAge: 86400
+  }),
+  /**
+   * Public API - Allow all origins (no credentials)
+   */
+  publicApi: {
+    origins: ["*"],
+    credentials: false
+  },
+  /**
+   * Hadoku standard - Production + development origins
+   */
+  hadoku: {
+    origins: DEFAULT_HADOKU_ORIGINS,
+    credentials: true,
+    maxAge: 86400
+  }
+};
+function getCorsHeaders(origin, allowedOrigins, options = {}) {
+  const headers = {};
+  if (origin && isOriginAllowed(origin, allowedOrigins)) {
+    headers["Access-Control-Allow-Origin"] = origin;
+    if (options.credentials !== false) {
+      headers["Access-Control-Allow-Credentials"] = "true";
+    }
+    if (options.exposedHeaders && options.exposedHeaders.length > 0) {
+      headers["Access-Control-Expose-Headers"] = options.exposedHeaders.join(", ");
+    }
+  }
+  return headers;
+}
+export {
+  CORSPresets,
+  DEFAULT_HADOKU_ORIGINS,
+  createCorsMiddleware,
+  createHadokuCors,
+  getCorsHeaders,
+  isOriginAllowed,
+  matchOrigin
+};