@outfitter/contracts 0.1.0-rc.1

package/dist/index.js

@@ -0,0 +1,137 @@
+// @bun
+import {
+  createValidator,
+  validateInput
+} from "./validation.js";
+import {
+  ACTION_SURFACES,
+  DEFAULT_REGISTRY_SURFACES,
+  createActionRegistry,
+  defineAction
+} from "./actions.js";
+import {
+  getBackoffDelay,
+  isRecoverable,
+  isRetryable,
+  shouldRetry
+} from "./recovery.js";
+import {
+  assertDefined,
+  assertMatches,
+  assertNonEmpty,
+  isNonEmptyArray
+} from "./assert/index.js";
+import"./result/index.js";
+import {
+  combine2,
+  combine3,
+  orElse,
+  unwrapOrElse
+} from "./result/utilities.js";
+import {
+  toEnvelope,
+  toHttpResponse
+} from "./envelope.js";
+import {
+  retry,
+  withTimeout
+} from "./resilience.js";
+import {
+  deserializeError,
+  safeParse,
+  safeStringify,
+  serializeError
+} from "./serialization.js";
+import {
+  DEFAULT_PATTERNS,
+  DEFAULT_SENSITIVE_KEYS,
+  createRedactor
+} from "./redactor.js";
+import {
+  AssertionError,
+  AuthError,
+  CancelledError,
+  ConflictError,
+  InternalError,
+  NetworkError,
+  NotFoundError,
+  PermissionError,
+  RateLimitError,
+  TimeoutError,
+  ValidationError,
+  exitCodeMap,
+  getExitCode,
+  getStatusCode,
+  statusCodeMap
+} from "./errors.js";
+import {
+  createContext,
+  generateRequestId
+} from "./context.js";
+import {
+  ACTION_CAPABILITIES,
+  CAPABILITY_SURFACES,
+  DEFAULT_ACTION_SURFACES,
+  capability,
+  capabilityAll,
+  getActionsForSurface
+} from "./capabilities.js";
+
+// packages/contracts/src/index.ts
+import { Result, TaggedError } from "better-result";
+export {
+  withTimeout,
+  validateInput,
+  unwrapOrElse,
+  toHttpResponse,
+  toEnvelope,
+  statusCodeMap,
+  shouldRetry,
+  serializeError,
+  safeStringify,
+  safeParse,
+  retry,
+  orElse,
+  isRetryable,
+  isRecoverable,
+  isNonEmptyArray,
+  getStatusCode,
+  getExitCode,
+  getBackoffDelay,
+  getActionsForSurface,
+  generateRequestId,
+  exitCodeMap,
+  deserializeError,
+  defineAction,
+  createValidator,
+  createRedactor,
+  createContext,
+  createActionRegistry,
+  combine3,
+  combine2,
+  capabilityAll,
+  capability,
+  assertNonEmpty,
+  assertMatches,
+  assertDefined,
+  ValidationError,
+  TimeoutError,
+  TaggedError,
+  Result,
+  RateLimitError,
+  PermissionError,
+  NotFoundError,
+  NetworkError,
+  InternalError,
+  DEFAULT_SENSITIVE_KEYS,
+  DEFAULT_REGISTRY_SURFACES,
+  DEFAULT_PATTERNS,
+  DEFAULT_ACTION_SURFACES,
+  ConflictError,
+  CancelledError,
+  CAPABILITY_SURFACES,
+  AuthError,
+  AssertionError,
+  ACTION_SURFACES,
+  ACTION_CAPABILITIES
+};

package/dist/recovery.d.ts

@@ -0,0 +1,150 @@
+/**
+* Error categories for classification, exit codes, and HTTP status mapping.
+*
+* Used for:
+* - CLI exit code determination
+* - HTTP status code mapping
+* - Error grouping in logs and metrics
+* - Client retry decisions (transient vs permanent)
+*/
+type ErrorCategory = "validation" | "not_found" | "conflict" | "permission" | "timeout" | "rate_limit" | "network" | "internal" | "auth" | "cancelled";
+/**
+* Backoff strategy configuration options
+*/
+interface BackoffOptions {
+	/** Base delay in milliseconds (default: 100) */
+	baseDelayMs?: number;
+	/** Maximum delay cap in milliseconds (default: 30000) */
+	maxDelayMs?: number;
+	/** Backoff strategy (default: "exponential") */
+	strategy?: "linear" | "exponential" | "constant";
+	/** Whether to add jitter to prevent thundering herd (default: true) */
+	useJitter?: boolean;
+}
+/**
+* Determines if an error is potentially recoverable.
+*
+* Recoverable errors might succeed on retry or with user intervention.
+* This includes transient failures (network, timeout), rate limiting,
+* and optimistic lock conflicts.
+*
+* @param error - Error object with category property
+* @returns True if the error might be recoverable
+*
+* @example
+* ```typescript
+* import { isRecoverable, NetworkError } from '@outfitter/contracts';
+*
+* const networkError = new NetworkError({ message: "Connection refused" });
+* console.log(isRecoverable(networkError)); // true
+*
+* const validationError = new ValidationError({ message: "Invalid input" });
+* console.log(isRecoverable(validationError)); // false
+* ```
+*/
+declare const isRecoverable: (error: {
+	readonly category: ErrorCategory;
+}) => boolean;
+/**
+* Determines if an error should trigger automatic retry.
+*
+* More restrictive than isRecoverable - only transient failures that
+* are good candidates for immediate retry without user intervention.
+*
+* Retryable categories:
+* - network: Connection issues may be temporary
+* - timeout: May succeed with another attempt
+*
+* NOT retryable (even though recoverable):
+* - rate_limit: Should respect retryAfterSeconds header
+* - conflict: May need user to resolve the conflict
+*
+* @param error - Error object with category property
+* @returns True if the operation should be automatically retried
+*
+* @example
+* ```typescript
+* import { isRetryable, TimeoutError } from '@outfitter/contracts';
+*
+* const timeout = new TimeoutError({
+*   message: "Operation timed out",
+*   operation: "fetch",
+*   timeoutMs: 5000,
+* });
+* console.log(isRetryable(timeout)); // true
+*
+* const rateLimitError = new RateLimitError({ message: "Rate limit exceeded" });
+* console.log(isRetryable(rateLimitError)); // false (use retryAfterSeconds)
+* ```
+*/
+declare const isRetryable: (error: {
+	readonly category: ErrorCategory;
+}) => boolean;
+/**
+* Calculate appropriate backoff delay for retry.
+*
+* Supports three strategies:
+* - exponential (default): delay = baseDelayMs * 2^attempt
+* - linear: delay = baseDelayMs * (attempt + 1)
+* - constant: delay = baseDelayMs
+*
+* By default, adds jitter (+/-10%) to prevent thundering herd problems
+* when multiple clients retry simultaneously.
+*
+* @param attempt - The attempt number (0-indexed)
+* @param options - Backoff configuration options
+* @returns Delay in milliseconds before next retry
+*
+* @example
+* ```typescript
+* import { getBackoffDelay } from '@outfitter/contracts';
+*
+* // Exponential backoff (default): 100ms, 200ms, 400ms, 800ms...
+* const delay = getBackoffDelay(2); // ~400ms (with jitter)
+*
+* // Linear backoff: 100ms, 200ms, 300ms...
+* const linearDelay = getBackoffDelay(2, { strategy: "linear" }); // ~300ms
+*
+* // Constant delay: 500ms, 500ms, 500ms...
+* const constantDelay = getBackoffDelay(2, {
+*   strategy: "constant",
+*   baseDelayMs: 500,
+* }); // ~500ms
+*
+* // No jitter for deterministic timing
+* const exactDelay = getBackoffDelay(2, { useJitter: false }); // exactly 400ms
+* ```
+*/
+declare const getBackoffDelay: (attempt: number, options?: BackoffOptions) => number;
+/**
+* Convenience function combining retryability check with attempt limit.
+*
+* Returns true only if:
+* 1. The error is retryable (network or timeout)
+* 2. We haven't exceeded maxAttempts
+*
+* @param error - Error object with category property
+* @param attempt - Current attempt number (0-indexed)
+* @param maxAttempts - Maximum number of retry attempts (default: 3)
+* @returns True if the operation should be retried
+*
+* @example
+* ```typescript
+* import { shouldRetry, NetworkError } from '@outfitter/contracts';
+*
+* const error = new NetworkError({ message: "Connection timeout" });
+*
+* // First attempt failed
+* console.log(shouldRetry(error, 0)); // true (will retry)
+*
+* // Fourth attempt failed (exceeded default max of 3)
+* console.log(shouldRetry(error, 3)); // false (no more retries)
+*
+* // Custom max attempts
+* console.log(shouldRetry(error, 4, 5)); // true (under custom limit)
+* ```
+*/
+declare const shouldRetry: (error: {
+	readonly category: ErrorCategory;
+}, attempt: number, maxAttempts?: number) => boolean;
+export { shouldRetry, isRetryable, isRecoverable, getBackoffDelay, BackoffOptions };

package/dist/recovery.js

@@ -0,0 +1,56 @@
+// @bun
+// packages/contracts/src/recovery.ts
+var RECOVERABLE_CATEGORIES = [
+  "network",
+  "timeout",
+  "rate_limit",
+  "conflict"
+];
+var RETRYABLE_CATEGORIES = ["network", "timeout"];
+var isRecoverable = (error) => {
+  return RECOVERABLE_CATEGORIES.includes(error.category);
+};
+var isRetryable = (error) => {
+  return RETRYABLE_CATEGORIES.includes(error.category);
+};
+var getBackoffDelay = (attempt, options = {}) => {
+  const {
+    baseDelayMs = 100,
+    maxDelayMs = 30000,
+    strategy = "exponential",
+    useJitter = true
+  } = options;
+  let delay;
+  switch (strategy) {
+    case "constant": {
+      delay = baseDelayMs;
+      break;
+    }
+    case "linear": {
+      delay = baseDelayMs * (attempt + 1);
+      break;
+    }
+    default: {
+      delay = baseDelayMs * 2 ** attempt;
+    }
+  }
+  delay = Math.min(delay, maxDelayMs);
+  if (useJitter) {
+    const jitterFactor = 0.1;
+    const jitter = delay * jitterFactor * (Math.random() * 2 - 1);
+    delay = Math.round(delay + jitter);
+  }
+  return Math.min(delay, maxDelayMs);
+};
+var shouldRetry = (error, attempt, maxAttempts = 3) => {
+  if (attempt >= maxAttempts) {
+    return false;
+  }
+  return isRetryable(error);
+};
+export {
+  shouldRetry,
+  isRetryable,
+  isRecoverable,
+  getBackoffDelay
+};

package/dist/redactor.d.ts

@@ -0,0 +1,100 @@
+/**
+* Configuration for creating a redactor.
+*/
+interface RedactorConfig {
+	/** Regex patterns to match and redact */
+	patterns: RegExp[];
+	/** Object keys whose values should always be redacted */
+	keys: string[];
+	/** Replacement string (default: "[REDACTED]") */
+	replacement?: string;
+	/** Whether to redact recursively in nested objects (default: true) */
+	deep?: boolean;
+}
+/**
+* Redaction event for audit logging.
+*/
+interface RedactionEvent {
+	/** Type of redaction applied */
+	redactedBy: "pattern" | "key";
+	/** Identifier of the pattern/key that matched */
+	matcher: string;
+	/** Location in the object path (e.g., "config.auth.apiKey") */
+	path: string;
+}
+/**
+* Callback for redaction events.
+*/
+type RedactionCallback = (event: RedactionEvent) => void;
+/**
+* Redactor - sensitive data scrubbing for logs, errors, and output.
+*
+* Applied automatically by @outfitter/logging. Manual application
+* required when building custom output or error context.
+*
+* @example
+* ```typescript
+* const redactor = createRedactor({
+*   patterns: [
+*     /Bearer [A-Za-z0-9-_]+/g,           // Auth headers
+*     /sk-[A-Za-z0-9]{48}/g,              // OpenAI keys
+*     /ghp_[A-Za-z0-9]{36}/g,             // GitHub PATs
+*     /password[:=]\s*["']?[^"'\s]+/gi,   // Password fields
+*   ],
+*   keys: ["apiKey", "secret", "token", "password", "credential"],
+*   replacement: "[REDACTED]",
+* });
+*
+* const safeLog = redactor.redact(sensitiveObject);
+* ```
+*/
+interface Redactor {
+	/** Redact sensitive values from an object (deep) */
+	redact<T>(value: T): T;
+	/** Redact sensitive values from a string */
+	redactString(value: string): string;
+	/** Check if a key name is sensitive */
+	isSensitiveKey(key: string): boolean;
+	/** Add a pattern at runtime */
+	addPattern(pattern: RegExp): void;
+	/** Add a sensitive key at runtime */
+	addSensitiveKey(key: string): void;
+}
+/**
+* Default patterns for common secrets.
+*
+* Covers:
+* - API keys (OpenAI, Anthropic, GitHub, etc.)
+* - Auth headers (Bearer tokens)
+* - Connection strings (database URLs)
+* - Password fields in various formats
+*/
+declare const DEFAULT_PATTERNS: RegExp[];
+/**
+* Default sensitive key names.
+*
+* Object keys matching these (case-insensitive) will have their values redacted.
+*/
+declare const DEFAULT_SENSITIVE_KEYS: string[];
+/**
+* Create a redactor instance with the given configuration.
+*
+* @param config - Redactor configuration
+* @returns Configured Redactor instance
+*
+* @example
+* ```typescript
+* const redactor = createRedactor({
+*   patterns: [...DEFAULT_PATTERNS],
+*   keys: [...DEFAULT_SENSITIVE_KEYS],
+* });
+*
+* const safe = redactor.redact({
+*   user: "alice",
+*   apiKey: "sk-abc123...",
+* });
+* // { user: "alice", apiKey: "[REDACTED]" }
+* ```
+*/
+declare function createRedactor(config: RedactorConfig): Redactor;
+export { createRedactor, RedactorConfig, Redactor, RedactionEvent, RedactionCallback, DEFAULT_SENSITIVE_KEYS, DEFAULT_PATTERNS };

package/dist/redactor.js

@@ -0,0 +1,111 @@
+// @bun
+// packages/contracts/src/redactor.ts
+var DEFAULT_PATTERNS = [
+  /Bearer [A-Za-z0-9-_.]+/g,
+  /Basic [A-Za-z0-9+/=]+/g,
+  /sk-[A-Za-z0-9]{32,}/g,
+  /sk-ant-[A-Za-z0-9-_]{32,}/g,
+  /ghp_[A-Za-z0-9]{36,}/g,
+  /gho_[A-Za-z0-9]{36}/g,
+  /ghu_[A-Za-z0-9]{36}/g,
+  /ghs_[A-Za-z0-9]{36}/g,
+  /ghr_[A-Za-z0-9]{36}/g,
+  /github_pat_[A-Za-z0-9_]{22,}/g,
+  /AKIA[A-Z0-9]{16}/g,
+  /xox[baprs]-[A-Za-z0-9-]+/g,
+  /-----BEGIN [A-Z ]+ KEY-----/g,
+  /password[:=]\s*["']?[^"'\s]+/gi,
+  /secret[:=]\s*["']?[^"'\s]+/gi,
+  /(?:postgres|mysql|mongodb|redis):\/\/[^@\s]+@[^\s]+/g
+];
+var DEFAULT_SENSITIVE_KEYS = [
+  "apiKey",
+  "api_key",
+  "apikey",
+  "secret",
+  "secretKey",
+  "secret_key",
+  "token",
+  "accessToken",
+  "access_token",
+  "refreshToken",
+  "refresh_token",
+  "password",
+  "passwd",
+  "credential",
+  "credentials",
+  "private",
+  "privateKey",
+  "private_key",
+  "authorization",
+  "auth"
+];
+function createRedactor(config) {
+  const replacement = config.replacement ?? "[REDACTED]";
+  const deep = config.deep ?? true;
+  const patterns = [...config.patterns];
+  const sensitiveKeys = new Set(config.keys.map((k) => k.toLowerCase()));
+  function isSensitiveKey(key) {
+    return sensitiveKeys.has(key.toLowerCase());
+  }
+  function redactString(value) {
+    let result = value;
+    for (const pattern of patterns) {
+      const regex = new RegExp(pattern.source, pattern.flags);
+      result = result.replace(regex, replacement);
+    }
+    return result;
+  }
+  function redact(value) {
+    return redactValue(value, deep);
+  }
+  function redactValue(value, deepMode) {
+    if (value === null || value === undefined) {
+      return value;
+    }
+    if (typeof value === "string") {
+      return redactString(value);
+    }
+    if (Array.isArray(value)) {
+      if (!deepMode) {
+        return value;
+      }
+      return value.map((item) => redactValue(item, deepMode));
+    }
+    if (typeof value === "object") {
+      if (!deepMode) {
+        return value;
+      }
+      const result = {};
+      for (const [key, val] of Object.entries(value)) {
+        if (isSensitiveKey(key) && val !== null && val !== undefined) {
+          result[key] = replacement;
+        } else if (typeof val === "string") {
+          result[key] = redactString(val);
+        } else {
+          result[key] = redactValue(val, deepMode);
+        }
+      }
+      return result;
+    }
+    return value;
+  }
+  function addPattern(pattern) {
+    patterns.push(pattern);
+  }
+  function addSensitiveKey(key) {
+    sensitiveKeys.add(key.toLowerCase());
+  }
+  return {
+    redact,
+    redactString,
+    isSensitiveKey,
+    addPattern,
+    addSensitiveKey
+  };
+}
+export {
+  createRedactor,
+  DEFAULT_SENSITIVE_KEYS,
+  DEFAULT_PATTERNS
+};