@hadoku/worker-utils 0.0.0-stage → 1.6.20

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+import { Context } from 'hono';
+
+/**
+ * Shared types for worker utilities
+ */
+
+type UserType = string;
+interface AuthContext {
+    userType: UserType;
+    [key: string]: unknown;
+}
+interface AuthConfig<TEnv = any> {
+    /**
+     * Sources to check for authentication credentials (in order of priority)
+     * @example ['header:X-User-Key', 'query:key', 'cookie:auth_token']
+     */
+    sources: string[];
+    /**
+     * Function to resolve userType from the extracted credential
+     * @param credential - The extracted auth credential
+     * @param env - The worker environment bindings
+     * @returns UserType or AuthContext object
+     */
+    resolver: (credential: string | undefined, env: TEnv) => UserType | AuthContext;
+    /**
+     * Variable name to store auth context in Hono context
+     * @default 'authContext'
+     */
+    contextKey?: string;
+    /**
+     * Additional fields to add to auth context
+     */
+    additionalFields?: (c: Context, env: TEnv) => Record<string, any>;
+}
+interface ContextExtractionConfig {
+    /**
+     * Mappings of context field name to sources
+     * @example { userId: ['header:X-User-Id', 'query:userId'], sessionId: ['header:X-Session-Id'] }
+     */
+    fields: Record<string, string[]>;
+    /**
+     * Default values for fields if not found
+     * @example { userId: 'anonymous', boardId: 'main' }
+     */
+    defaults?: Record<string, any>;
+    /**
+     * Transform functions for extracted values
+     * @example { userId: (val) => val?.toLowerCase() }
+     */
+    transforms?: Record<string, (value: string) => any>;
+}
+interface ValidationRule {
+    field: string;
+    required?: boolean;
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    custom?: (value: unknown) => boolean | string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: {
+        field: string;
+        message: string;
+    }[];
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: Record<string, any>;
+}
+interface LoggerConfig {
+    /**
+     * Minimum log level to output
+     * @default 'info'
+     */
+    minLevel?: LogLevel;
+    /**
+     * Include timestamp in logs
+     * @default true
+     */
+    includeTimestamp?: boolean;
+    /**
+     * Prefix for all log messages
+     * @example '[task-api]'
+     */
+    prefix?: string;
+    /**
+     * Custom formatter for log output
+     */
+    formatter?: (entry: LogEntry) => string;
+}
+interface ErrorResponse {
+    error: string;
+    details?: unknown;
+    timestamp?: string;
+}
+interface SuccessResponse<T = any> {
+    data: T;
+    message?: string;
+    timestamp?: string;
+}
+/**
+ * The canonical health status — the SINGLE source of truth for the health
+ * contract. Both the runtime helper `healthCheck()` (responses.ts) and the
+ * OpenAPI schema `createHealthResponseSchema()` (openapi-schemas.ts) reference
+ * this type, so the two can no longer drift apart (they used to: the schema
+ * declared `status: 'healthy'` + a numeric timestamp that healthCheck never
+ * emitted). openapi-schemas.ts guards its `z.enum([...])` against this type
+ * with `satisfies`, so a rename/removal here fails that build.
+ */
+type HealthStatus = 'ok' | 'degraded' | 'error';
+interface HealthCheckResponse {
+    status: HealthStatus;
+    service: string;
+    timestamp: string;
+    version?: string;
+    checks?: Record<string, boolean | string>;
+    /**
+     * What an operator should DO about a non-ok status, ideally the literal
+     * command to run. Surfaced verbatim into the Discord alert by
+     * monitoring-api's worker-health alerter, so "edge_auth: missing" at 2am
+     * does not mean rediscovering the fix.
+     */
+    remediation?: string;
+    /**
+     * Slow-moving numbers worth watching but not worth alerting on — storage
+     * consumed, row counts, percentage of a quota. Reported, never used to
+     * derive `status`.
+     */
+    gauges?: Record<string, number | null>;
+}
+interface CORSConfig {
+    /**
+     * Allowed origins (supports wildcards like 'http://localhost:*')
+     */
+    origins: string[];
+    /**
+     * Allowed HTTP methods
+     * @default ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+     */
+    methods?: string[];
+    /**
+     * Allowed headers
+     */
+    allowedHeaders?: string[];
+    /**
+     * Exposed headers
+     */
+    exposedHeaders?: string[];
+    /**
+     * Allow credentials
+     * @default true
+     */
+    credentials?: boolean;
+    /**
+     * Max age for preflight cache
+     * @default 86400 (24 hours)
+     */
+    maxAge?: number;
+}
+
+export type { AuthConfig, AuthContext, CORSConfig, ContextExtractionConfig, ErrorResponse, HealthCheckResponse, HealthStatus, LogEntry, LogLevel, LoggerConfig, SuccessResponse, UserType, ValidationResult, ValidationRule };

package/dist/validation.d.ts

@@ -0,0 +1,88 @@
+import { ValidationRule, ValidationResult } from './types.js';
+import 'hono';
+
+/**
+ * Validate multiple fields against rules
+ *
+ * @param data - Data object to validate
+ * @param rules - Array of validation rules
+ * @returns Validation result with errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateFields(requestBody, [
+ *   { field: 'id', required: true },
+ *   { field: 'title', required: true, minLength: 1 },
+ *   { field: 'tags', type: 'array' }
+ * ]);
+ *
+ * if (!result.valid) {
+ *   console.log(result.errors);
+ *   // [{ field: 'title', message: 'title must be at least 1 characters' }]
+ * }
+ * ```
+ */
+declare function validateFields(data: Record<string, any>, rules: ValidationRule[]): ValidationResult;
+/**
+ * Returns the name of the first missing or empty-string field, or null.
+ *
+ * Re-added to worker-utils 1.2.1 (matches the original 1.0.0 signature).
+ * Removed in 15c3376 cleanup but @wolffm/task still imports it.
+ */
+declare function requireFields(data: Record<string, any>, fields: string[]): string | null;
+/**
+ * Re-added in 1.2.1. Same surface @wolffm/task imports for ID validation.
+ */
+declare function isNonEmptyString(value: unknown): boolean;
+/**
+ * Common validation rules
+ */
+declare const CommonRules: {
+    /**
+     * ID field (required, non-empty string)
+     */
+    id: () => ValidationRule;
+    /**
+     * Title field (required, 1-500 characters)
+     */
+    title: (options?: {
+        minLength?: number;
+        maxLength?: number;
+    }) => ValidationRule;
+    /**
+     * Email field
+     */
+    email: (required?: boolean) => ValidationRule;
+    /**
+     * URL field
+     */
+    url: (required?: boolean) => ValidationRule;
+    /**
+     * Enum field (value must be in allowed list)
+     */
+    enum: (field: string, allowedValues: unknown[], required?: boolean) => ValidationRule;
+    /**
+     * Array field with optional element validation
+     */
+    array: (field: string, options?: {
+        required?: boolean;
+        minLength?: number;
+        maxLength?: number;
+        elementType?: "string" | "number" | "boolean" | "object";
+    }) => ValidationRule;
+    /**
+     * Number field with optional range validation
+     */
+    number: (field: string, options?: {
+        required?: boolean;
+        min?: number;
+        max?: number;
+        integer?: boolean;
+    }) => ValidationRule;
+    /**
+     * Boolean field
+     */
+    boolean: (field: string, required?: boolean) => ValidationRule;
+};
+
+export { CommonRules, isNonEmptyString, requireFields, validateFields };

package/dist/validation.js

@@ -0,0 +1,172 @@
+// validation.ts
+function validateField(value, rule) {
+  if (rule.required && (value === void 0 || value === null || value === "")) {
+    return `${rule.field} is required`;
+  }
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  if (rule.type) {
+    const actualType = Array.isArray(value) ? "array" : typeof value;
+    if (actualType !== rule.type) {
+      return `${rule.field} must be of type ${rule.type}`;
+    }
+  }
+  if (typeof value === "string") {
+    if (rule.minLength !== void 0 && value.length < rule.minLength) {
+      return `${rule.field} must be at least ${rule.minLength} characters`;
+    }
+    if (rule.maxLength !== void 0 && value.length > rule.maxLength) {
+      return `${rule.field} must be at most ${rule.maxLength} characters`;
+    }
+    if (rule.pattern && !rule.pattern.test(value)) {
+      return `${rule.field} format is invalid`;
+    }
+  }
+  if (rule.custom) {
+    const result = rule.custom(value);
+    if (result !== true && typeof result === "string") {
+      return result;
+    }
+    if (result === false) {
+      return `${rule.field} is invalid`;
+    }
+  }
+  return null;
+}
+function validateFields(data, rules) {
+  const errors = [];
+  for (const rule of rules) {
+    const value = data[rule.field];
+    const error = validateField(value, rule);
+    if (error) {
+      errors.push({ field: rule.field, message: error });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function requireFields(data, fields) {
+  for (const field of fields) {
+    const value = data[field];
+    if (value === void 0 || value === null || typeof value === "string" && value.trim() === "") {
+      return `Missing required field: ${field}`;
+    }
+  }
+  return null;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+var CommonRules = {
+  /**
+   * ID field (required, non-empty string)
+   */
+  id: () => ({
+    field: "id",
+    required: true,
+    type: "string",
+    custom: (val) => typeof val === "string" && val.trim() !== "" || "ID cannot be empty"
+  }),
+  /**
+   * Title field (required, 1-500 characters)
+   */
+  title: (options = {}) => ({
+    field: "title",
+    required: true,
+    type: "string",
+    minLength: options.minLength ?? 1,
+    maxLength: options.maxLength ?? 500,
+    custom: (val) => typeof val === "string" && val.trim() !== "" || "Title cannot be empty"
+  }),
+  /**
+   * Email field
+   */
+  email: (required = false) => ({
+    field: "email",
+    required,
+    type: "string",
+    pattern: /^[\w-.]+@([\w-]+\.)+[\w-]{2,4}$/
+  }),
+  /**
+   * URL field
+   */
+  url: (required = false) => ({
+    field: "url",
+    required,
+    type: "string",
+    pattern: /^https?:\/\/(www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&//=]*)$/
+  }),
+  /**
+   * Enum field (value must be in allowed list)
+   */
+  enum: (field, allowedValues, required = false) => ({
+    field,
+    required,
+    custom: (val) => allowedValues.includes(val) || `${field} must be one of: ${allowedValues.join(", ")}`
+  }),
+  /**
+   * Array field with optional element validation
+   */
+  array: (field, options = {}) => ({
+    field,
+    required: options.required,
+    type: "array",
+    custom: (val) => {
+      if (!Array.isArray(val)) return false;
+      if (options.minLength !== void 0 && val.length < options.minLength) {
+        return `${field} must have at least ${options.minLength} items`;
+      }
+      if (options.maxLength !== void 0 && val.length > options.maxLength) {
+        return `${field} must have at most ${options.maxLength} items`;
+      }
+      if (options.elementType) {
+        const invalidItem = val.find((item) => {
+          const actualType = Array.isArray(item) ? "array" : typeof item;
+          return actualType !== options.elementType;
+        });
+        if (invalidItem !== void 0) {
+          return `All ${field} items must be of type ${options.elementType}`;
+        }
+      }
+      return true;
+    }
+  }),
+  /**
+   * Number field with optional range validation
+   */
+  number: (field, options = {}) => ({
+    field,
+    required: options.required,
+    type: "number",
+    custom: (val) => {
+      if (typeof val !== "number") return false;
+      if (options.integer && !Number.isInteger(val)) {
+        return `${field} must be an integer`;
+      }
+      if (options.min !== void 0 && val < options.min) {
+        return `${field} must be at least ${options.min}`;
+      }
+      if (options.max !== void 0 && val > options.max) {
+        return `${field} must be at most ${options.max}`;
+      }
+      return true;
+    }
+  }),
+  /**
+   * Boolean field
+   */
+  boolean: (field, required = false) => ({
+    field,
+    required,
+    type: "boolean"
+  })
+};
+export {
+  CommonRules,
+  isNonEmptyString,
+  requireFields,
+  validateFields
+};

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@hadoku/worker-utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.6.20",
+  "license": "ISC",
+  "description": "Shared utilities for Cloudflare Workers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WolffM/hadoku_site.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./auth": "./dist/auth.js",
+    "./authPage": "./dist/authPage.js",
+    "./context": "./dist/context.js",
+    "./validation": "./dist/validation.js",
+    "./cors": "./dist/cors.js",
+    "./logging": "./dist/cloudflareWorkerLogger.js",
+    "./responses": "./dist/responses.js",
+    "./types": "./dist/types.js",
+    "./edge-routes": "./dist/edge-routes.js",
+    "./content-level": "./dist/content-level.js",
+    "./identity": "./dist/identity.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@hono/zod-openapi": "^1.1.5",
+    "@wolffm/logger": "npm:@hadoku/logger@^1.4.0"
+  },
+  "peerDependencies": {
+    "hono": "^4.11.4"
+  }
+}