@hadoku/worker-utils 0.0.0-stage → 1.6.20

package/dist/openapi-schemas.d.ts

@@ -0,0 +1,157 @@
+import { z } from '@hono/zod-openapi';
+
+/**
+ * Shared OpenAPI Zod Schemas
+ *
+ * Common schemas used across multiple worker APIs for consistent error handling,
+ * health checks, and response formats.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorResponseSchema, createHealthResponseSchema } from '../util/openapi-schemas';
+ *
+ * // Use generic error schema
+ * const route = createRoute({
+ *   responses: {
+ *     400: { content: { 'application/json': { schema: ErrorResponseSchema } } }
+ *   }
+ * });
+ *
+ * // Create service-specific health schema
+ * const HealthSchema = createHealthResponseSchema('my-api');
+ * ```
+ */
+
+/**
+ * Standard error response with success: false pattern
+ * Used by: oss-recon-api
+ */
+declare const ErrorResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Alternative error response without success field
+ * Used by: task-api, prompt-api
+ */
+declare const SimpleErrorResponseSchema: z.ZodObject<{
+    error: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Detailed error response with success pattern
+ * Used by: prompt-api
+ */
+declare const DetailedErrorResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Rate limit / throttle error response
+ * Used by: task-api
+ */
+declare const ThrottleErrorResponseSchema: z.ZodObject<{
+    error: z.ZodLiteral<"Rate limit exceeded">;
+    message: z.ZodString;
+    retryAfter: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Create a service-specific health response schema
+ *
+ * @param serviceName - The name of the service (e.g., 'task-api', 'prompt-api')
+ * @param options - Optional configuration for additional checks
+ * @returns Zod schema for health response
+ *
+ * @example
+ * ```typescript
+ * const HealthSchema = createHealthResponseSchema('task-api', { includeChecks: true });
+ * ```
+ */
+declare function createHealthResponseSchema<T extends string>(serviceName: T, options?: {
+    includeChecks?: boolean;
+}): z.ZodObject<{
+    status: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        degraded: "degraded";
+    }>;
+    timestamp: z.ZodString;
+    service: z.ZodLiteral<T>;
+}, z.core.$strip>;
+/**
+ * Health response with success wrapper pattern
+ * Used by: oss-recon-api
+ *
+ * NOTE: these two services live in external @wolffm packages that still emit
+ * the legacy `status: 'healthy'` convention (and a {success,data} envelope),
+ * so this schema intentionally does NOT use HEALTH_STATUSES. Migrate those
+ * packages to healthCheck() to fold them onto the canonical contract.
+ */
+declare function createWrappedHealthResponseSchema<T extends string>(serviceName: T): z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        status: z.ZodLiteral<"healthy">;
+        service: z.ZodLiteral<T>;
+        timestamp: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Create a success response wrapper schema
+ * Used by: prompt-api, oss-recon-api
+ *
+ * @example
+ * ```typescript
+ * const UserResponseSchema = createSuccessResponseSchema(
+ *   z.object({ user: UserSchema })
+ * ).openapi('UserResponse');
+ * ```
+ */
+declare function createSuccessResponseSchema<T extends z.ZodTypeAny>(dataSchema: T): z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: T;
+}, z.core.$strip>;
+/**
+ * Create a delete confirmation response schema
+ *
+ * @example
+ * ```typescript
+ * const DeleteBoardResponseSchema = createDeleteResponseSchema('boardId', 'work-board');
+ * ```
+ */
+declare function createDeleteResponseSchema(idField?: string, example?: string): z.ZodObject<{
+    [x: string]: z.ZodString | z.ZodLiteral<true>;
+    deleted: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/**
+ * Zod validation error response
+ * Matches the defaultHook error format used in OpenAPIHono
+ */
+declare const ValidationErrorResponseSchema: z.ZodObject<{
+    error: z.ZodLiteral<"Validation Error">;
+    message: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Pre-built health schemas for known services
+ * Import these directly if you don't need customization
+ */
+declare const TaskApiHealthResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        degraded: "degraded";
+    }>;
+    timestamp: z.ZodString;
+    service: z.ZodLiteral<"task-api-adapter">;
+}, z.core.$strip>;
+declare const PromptApiHealthResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        degraded: "degraded";
+    }>;
+    timestamp: z.ZodString;
+    service: z.ZodLiteral<"prompt-api">;
+}, z.core.$strip>;
+
+export { DetailedErrorResponseSchema, ErrorResponseSchema, PromptApiHealthResponseSchema, SimpleErrorResponseSchema, TaskApiHealthResponseSchema, ThrottleErrorResponseSchema, ValidationErrorResponseSchema, createDeleteResponseSchema, createHealthResponseSchema, createSuccessResponseSchema, createWrappedHealthResponseSchema };

package/dist/openapi-schemas.js

@@ -0,0 +1,79 @@
+// openapi-schemas.ts
+import { z } from "@hono/zod-openapi";
+var HEALTH_STATUS_VALUES = ["ok", "degraded", "error"];
+var ErrorResponseSchema = z.object({
+  success: z.literal(false),
+  error: z.string().openapi({ example: "Bad Request" })
+}).openapi("ErrorResponse");
+var SimpleErrorResponseSchema = z.object({
+  error: z.string().openapi({ example: "Bad Request" }),
+  message: z.string().optional().openapi({ example: "Missing required field: title" })
+}).openapi("SimpleErrorResponse");
+var DetailedErrorResponseSchema = z.object({
+  success: z.literal(false),
+  error: z.string().openapi({ example: "Validation Error" }),
+  message: z.string().openapi({ example: "Invalid input data" })
+}).openapi("DetailedErrorResponse");
+var ThrottleErrorResponseSchema = z.object({
+  error: z.literal("Rate limit exceeded"),
+  message: z.string().openapi({ example: "Too many requests" }),
+  retryAfter: z.number().openapi({ example: 60 })
+}).openapi("ThrottleErrorResponse");
+function createHealthResponseSchema(serviceName, options) {
+  const baseSchema = z.object({
+    status: z.enum(HEALTH_STATUS_VALUES).openapi({ example: "ok" }),
+    timestamp: z.string().openapi({ example: "2024-01-15T10:30:00.000Z" }),
+    service: z.literal(serviceName)
+  });
+  if (options?.includeChecks) {
+    return baseSchema.extend({
+      checks: z.object({
+        kv: z.boolean().openapi({ example: true })
+      })
+    }).openapi(`${serviceName}HealthResponse`);
+  }
+  return baseSchema.openapi(`${serviceName}HealthResponse`);
+}
+function createWrappedHealthResponseSchema(serviceName) {
+  return z.object({
+    success: z.literal(true),
+    data: z.object({
+      status: z.literal("healthy"),
+      service: z.literal(serviceName),
+      timestamp: z.string().openapi({ example: "2024-01-15T10:30:00.000Z" })
+    })
+  }).openapi(`${serviceName}HealthResponse`);
+}
+function createSuccessResponseSchema(dataSchema) {
+  return z.object({
+    success: z.literal(true),
+    data: dataSchema
+  });
+}
+function createDeleteResponseSchema(idField = "id", example = "01HXYZ123ABC") {
+  return z.object({
+    deleted: z.literal(true),
+    [idField]: z.string().openapi({ example })
+  }).openapi("DeleteResponse");
+}
+var ValidationErrorResponseSchema = z.object({
+  error: z.literal("Validation Error"),
+  message: z.string().openapi({ example: "id: Required, title: String must contain at least 1 character(s)" })
+}).openapi("ValidationErrorResponse");
+var TaskApiHealthResponseSchema = createHealthResponseSchema("task-api-adapter", {
+  includeChecks: true
+});
+var PromptApiHealthResponseSchema = createHealthResponseSchema("prompt-api");
+export {
+  DetailedErrorResponseSchema,
+  ErrorResponseSchema,
+  PromptApiHealthResponseSchema,
+  SimpleErrorResponseSchema,
+  TaskApiHealthResponseSchema,
+  ThrottleErrorResponseSchema,
+  ValidationErrorResponseSchema,
+  createDeleteResponseSchema,
+  createHealthResponseSchema,
+  createSuccessResponseSchema,
+  createWrappedHealthResponseSchema
+};

package/dist/rate-limit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Sliding window rate limiting using Cloudflare KV
+ *
+ * Generic implementation that accepts configuration per-consumer.
+ * Each worker provides its own limits via RateLimitConfig.
+ */
+interface RateLimitConfig {
+    /** Maximum requests allowed per window */
+    maxRequests: number;
+    /** Window duration in seconds */
+    windowSeconds: number;
+    /** KV TTL in seconds (should be >= windowSeconds) */
+    kvTtlSeconds: number;
+    /** KV key prefix (default: 'rate-limit') */
+    keyPrefix?: string;
+}
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+    reason?: string;
+}
+/**
+ * Check if an identifier (IP, user key, etc.) is rate limited
+ */
+declare function checkRateLimit(kv: KVNamespace, identifier: string, config: RateLimitConfig): Promise<RateLimitResult>;
+/**
+ * Record a request for rate limiting.
+ * Call after checkRateLimit returns allowed: true.
+ */
+declare function recordRequest(kv: KVNamespace, identifier: string, config: RateLimitConfig): Promise<void>;
+/**
+ * Reset rate limit for an identifier (admin function)
+ */
+declare function resetRateLimit(kv: KVNamespace, identifier: string, config?: {
+    keyPrefix?: string;
+}): Promise<void>;
+
+export { type RateLimitConfig, type RateLimitResult, checkRateLimit, recordRequest, resetRateLimit };

package/dist/rate-limit.js

@@ -0,0 +1,59 @@
+// rate-limit.ts
+async function checkRateLimit(kv, identifier, config) {
+  const prefix = config.keyPrefix ?? "rate-limit";
+  const key = `${prefix}:${identifier}`;
+  const windowMs = config.windowSeconds * 1e3;
+  const now = Date.now();
+  const existingData = await kv.get(key, "text");
+  const existing = existingData ? JSON.parse(existingData) : null;
+  if (!existing || now - existing.windowStart >= windowMs) {
+    return {
+      allowed: true,
+      remaining: config.maxRequests - 1,
+      resetAt: now + windowMs
+    };
+  }
+  if (existing.count >= config.maxRequests) {
+    const resetAt = existing.windowStart + windowMs;
+    const timeRemaining = resetAt - now;
+    const display = timeRemaining >= 12e4 ? `${Math.ceil(timeRemaining / 6e4)} minute(s)` : `${Math.ceil(timeRemaining / 1e3)} second(s)`;
+    return {
+      allowed: false,
+      remaining: 0,
+      resetAt,
+      reason: `Rate limit exceeded. Try again in ${display}.`
+    };
+  }
+  return {
+    allowed: true,
+    remaining: config.maxRequests - existing.count - 1,
+    resetAt: existing.windowStart + windowMs
+  };
+}
+async function recordRequest(kv, identifier, config) {
+  const prefix = config.keyPrefix ?? "rate-limit";
+  const key = `${prefix}:${identifier}`;
+  const windowMs = config.windowSeconds * 1e3;
+  const now = Date.now();
+  const existingData = await kv.get(key, "text");
+  const existing = existingData ? JSON.parse(existingData) : null;
+  let entry;
+  if (!existing || now - existing.windowStart >= windowMs) {
+    entry = { count: 1, windowStart: now };
+  } else {
+    entry = { count: existing.count + 1, windowStart: existing.windowStart };
+  }
+  await kv.put(key, JSON.stringify(entry), {
+    expirationTtl: config.kvTtlSeconds
+  });
+}
+async function resetRateLimit(kv, identifier, config) {
+  const prefix = config?.keyPrefix ?? "rate-limit";
+  const key = `${prefix}:${identifier}`;
+  await kv.delete(key);
+}
+export {
+  checkRateLimit,
+  recordRequest,
+  resetRateLimit
+};

package/dist/responses.d.ts

@@ -0,0 +1,159 @@
+import { Context } from 'hono';
+import { HealthStatus } from './types.js';
+
+/**
+ * Standard response helpers for Cloudflare Workers
+ *
+ * Consistent response formatting for:
+ * - Success responses
+ * - Error responses
+ * - Health checks
+ * - Not found responses
+ * - Validation errors
+ *
+ * @example
+ * ```typescript
+ * import { ok, created, badRequest, notFound, healthCheck } from '../util';
+ *
+ * // Success response
+ * return ok(c, { tasks: [...] });
+ *
+ * // Created with custom message
+ * return created(c, { task }, 'Task created successfully');
+ *
+ * // Error response
+ * return badRequest(c, 'Invalid input');
+ *
+ * // Health check
+ * return healthCheck(c, 'task-api', { kv: true, db: false });
+ * ```
+ */
+
+/**
+ * Send a success response (200)
+ *
+ * @param c - Hono context
+ * @param data - Response data
+ * @param message - Optional success message
+ * @returns JSON response
+ *
+ * @example
+ * ```typescript
+ * return ok(c, { tasks: [...] });
+ * return ok(c, { count: 10 }, 'Retrieved successfully');
+ * ```
+ */
+declare function ok<T = any>(c: Context, data: T, message?: string): Response;
+/**
+ * Send a created response (201)
+ *
+ * @param c - Hono context
+ * @param data - Created resource data
+ * @param message - Optional success message
+ * @returns JSON response
+ *
+ * @example
+ * ```typescript
+ * return created(c, { task: {...} });
+ * return created(c, { id: '123' }, 'Task created successfully');
+ * ```
+ */
+declare function created<T = any>(c: Context, data: T, message?: string): Response;
+/**
+ * Send a bad request error (400)
+ *
+ * @param c - Hono context
+ * @param error - Error message
+ * @param details - Additional error details
+ * @returns JSON response
+ *
+ * @example
+ * ```typescript
+ * return badRequest(c, 'Missing required field: id');
+ * return badRequest(c, 'Validation failed', { errors: [...] });
+ * ```
+ */
+declare function badRequest(c: Context, error: string, details?: unknown): Response;
+/**
+ * Send a not found error (404)
+ *
+ * @param c - Hono context
+ * @param resource - Resource type that wasn't found
+ * @returns JSON response
+ *
+ * @example
+ * ```typescript
+ * return notFound(c, 'Task');
+ * return notFound(c, 'Board');
+ * ```
+ */
+declare function notFound(c: Context, resource?: string): Response;
+/**
+ * Send an internal server error (500)
+ *
+ * @param c - Hono context
+ * @param message - Error message
+ * @param details - Additional error details (omit in production)
+ * @returns JSON response
+ *
+ * @example
+ * ```typescript
+ * return serverError(c, 'Failed to process request');
+ * return serverError(c, 'Database error', { error: err.message });
+ * ```
+ */
+declare function serverError(c: Context, message?: string, details?: unknown): Response;
+/**
+ * Send validation errors (400)
+ *
+ * @param c - Hono context
+ * @param errors - Array of validation errors
+ * @param message - Optional error message
+ * @returns JSON response
+ *
+ * @example
+ * ```typescript
+ * const validation = validateFields(body, rules);
+ * if (!validation.valid) {
+ *   return validationError(c, validation.errors);
+ * }
+ * ```
+ */
+declare function validationError(c: Context, errors: {
+    field: string;
+    message: string;
+}[], message?: string): Response;
+/**
+ * Send a health check response
+ *
+ * @param c - Hono context
+ * @param serviceName - Name of the service
+ * @param checks - Optional health check results
+ * @param options - Additional options
+ * @returns JSON response
+ *
+ * @example
+ * ```typescript
+ * // Simple health check
+ * return healthCheck(c, 'task-api');
+ *
+ * // With dependency checks
+ * return healthCheck(c, 'task-api', {
+ *   kv: await checkKV(),
+ *   api: await checkAPI()
+ * });
+ *
+ * // Degraded status
+ * return healthCheck(c, 'task-api', { kv: false }, {
+ *   status: 'degraded'
+ * });
+ * ```
+ */
+declare function healthCheck(c: Context, serviceName: string, checks?: Record<string, boolean | string>, options?: {
+    status?: HealthStatus;
+    version?: string;
+    remediation?: string;
+    gauges?: Record<string, number | null>;
+}): Response;
+
+export { badRequest, created, healthCheck, notFound, ok, serverError, validationError };

package/dist/responses.js

@@ -0,0 +1,80 @@
+// responses.ts
+function ok(c, data, message) {
+  const response = {
+    data,
+    ...message && { message },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return c.json(response, 200);
+}
+function created(c, data, message) {
+  const response = {
+    data,
+    message: message || "Resource created successfully",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return c.json(response, 201);
+}
+function badRequest(c, error, details) {
+  const response = {
+    error,
+    ...details !== void 0 ? { details } : {},
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return c.json(response, 400);
+}
+function notFound(c, resource = "Resource") {
+  const response = {
+    error: `${resource} not found`,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return c.json(response, 404);
+}
+function serverError(c, message = "Internal server error", details) {
+  const response = {
+    error: message,
+    ...details !== void 0 ? { details } : {},
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return c.json(response, 500);
+}
+function validationError(c, errors, message = "Validation failed") {
+  const response = {
+    error: message,
+    details: { errors },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return c.json(response, 400);
+}
+function healthCheck(c, serviceName, checks, options = {}) {
+  let status = options.status || "ok";
+  if (checks && !options.status) {
+    const hasFailures = Object.values(checks).some((v) => v === false);
+    const allFailed = Object.values(checks).every((v) => v === false);
+    if (allFailed) {
+      status = "error";
+    } else if (hasFailures) {
+      status = "degraded";
+    }
+  }
+  const response = {
+    status,
+    service: serviceName,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...options.version && { version: options.version },
+    ...checks && { checks },
+    ...options.remediation && { remediation: options.remediation },
+    ...options.gauges && { gauges: options.gauges }
+  };
+  const statusCode = status === "ok" ? 200 : 503;
+  return c.json(response, statusCode);
+}
+export {
+  badRequest,
+  created,
+  healthCheck,
+  notFound,
+  ok,
+  serverError,
+  validationError
+};