@outfitter/contracts 0.1.0-rc.1

package/dist/serialization.d.ts

@@ -0,0 +1,313 @@
+import { TaggedErrorClass } from "better-result";
+/**
+* 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";
+/**
+* Serialized error format for JSON transport.
+*/
+interface SerializedError {
+	_tag: string;
+	category: ErrorCategory;
+	message: string;
+	context?: Record<string, unknown>;
+}
+declare const ValidationErrorBase: TaggedErrorClass<"ValidationError", {
+	message: string;
+	field?: string;
+}>;
+declare const AssertionErrorBase: TaggedErrorClass<"AssertionError", {
+	message: string;
+}>;
+declare const NotFoundErrorBase: TaggedErrorClass<"NotFoundError", {
+	message: string;
+	resourceType: string;
+	resourceId: string;
+}>;
+declare const ConflictErrorBase: TaggedErrorClass<"ConflictError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const PermissionErrorBase: TaggedErrorClass<"PermissionError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const TimeoutErrorBase: TaggedErrorClass<"TimeoutError", {
+	message: string;
+	operation: string;
+	timeoutMs: number;
+}>;
+declare const RateLimitErrorBase: TaggedErrorClass<"RateLimitError", {
+	message: string;
+	retryAfterSeconds?: number;
+}>;
+declare const NetworkErrorBase: TaggedErrorClass<"NetworkError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const InternalErrorBase: TaggedErrorClass<"InternalError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const AuthErrorBase: TaggedErrorClass<"AuthError", {
+	message: string;
+	reason?: "missing" | "invalid" | "expired";
+}>;
+declare const CancelledErrorBase: TaggedErrorClass<"CancelledError", {
+	message: string;
+}>;
+/**
+* Input validation failed.
+*
+* @example
+* ```typescript
+* new ValidationError({ message: "Email format invalid", field: "email" });
+* ```
+*/
+declare class ValidationError extends ValidationErrorBase {
+	readonly category: "validation";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Assertion failed (invariant violation).
+*
+* Used by assertion utilities that return Result types instead of throwing.
+* AssertionError indicates a programming bug — an invariant that should
+* never be violated was broken. These are internal errors, not user input
+* validation failures.
+*
+* **Category rationale**: Uses `internal` (not `validation`) because:
+* - Assertions check **invariants** (programmer assumptions), not user input
+* - A failed assertion means "this should be impossible if the code is correct"
+* - User-facing validation uses {@link ValidationError} with helpful field info
+* - HTTP 500 is correct: this is a server bug, not a client mistake
+*
+* @example
+* ```typescript
+* // In domain logic after validation has passed
+* const result = assertDefined(cachedValue, "Cache should always have value after init");
+* if (result.isErr()) {
+*   return result; // Propagate as internal error
+* }
+* ```
+*
+* @see ValidationError - For user input validation failures (HTTP 400)
+*/
+declare class AssertionError extends AssertionErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Requested resource not found.
+*
+* @example
+* ```typescript
+* new NotFoundError({ message: "note not found: abc123", resourceType: "note", resourceId: "abc123" });
+* ```
+*/
+declare class NotFoundError extends NotFoundErrorBase {
+	readonly category: "not_found";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* State conflict (optimistic locking, concurrent modification).
+*
+* @example
+* ```typescript
+* new ConflictError({ message: "Resource was modified by another process" });
+* ```
+*/
+declare class ConflictError extends ConflictErrorBase {
+	readonly category: "conflict";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authorization denied.
+*
+* @example
+* ```typescript
+* new PermissionError({ message: "Cannot delete read-only resource" });
+* ```
+*/
+declare class PermissionError extends PermissionErrorBase {
+	readonly category: "permission";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation timed out.
+*
+* @example
+* ```typescript
+* new TimeoutError({ message: "Database query timed out after 5000ms", operation: "Database query", timeoutMs: 5000 });
+* ```
+*/
+declare class TimeoutError extends TimeoutErrorBase {
+	readonly category: "timeout";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Rate limit exceeded.
+*
+* @example
+* ```typescript
+* new RateLimitError({ message: "Rate limit exceeded, retry after 60s", retryAfterSeconds: 60 });
+* ```
+*/
+declare class RateLimitError extends RateLimitErrorBase {
+	readonly category: "rate_limit";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Network/transport failure.
+*
+* @example
+* ```typescript
+* new NetworkError({ message: "Connection refused to api.example.com" });
+* ```
+*/
+declare class NetworkError extends NetworkErrorBase {
+	readonly category: "network";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Unexpected internal error.
+*
+* @example
+* ```typescript
+* new InternalError({ message: "Unexpected state in processor" });
+* ```
+*/
+declare class InternalError extends InternalErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authentication failed (missing or invalid credentials).
+*
+* @example
+* ```typescript
+* new AuthError({ message: "Invalid API key", reason: "invalid" });
+* ```
+*/
+declare class AuthError extends AuthErrorBase {
+	readonly category: "auth";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation cancelled by user or signal.
+*
+* @example
+* ```typescript
+* new CancelledError({ message: "Operation cancelled by user" });
+* ```
+*/
+declare class CancelledError extends CancelledErrorBase {
+	readonly category: "cancelled";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Union type of all concrete error class instances.
+*/
+type AnyKitError = InstanceType<typeof ValidationError> | InstanceType<typeof AssertionError> | InstanceType<typeof NotFoundError> | InstanceType<typeof ConflictError> | InstanceType<typeof PermissionError> | InstanceType<typeof TimeoutError> | InstanceType<typeof RateLimitError> | InstanceType<typeof NetworkError> | InstanceType<typeof InternalError> | InstanceType<typeof AuthError> | InstanceType<typeof CancelledError>;
+/**
+* Type alias for backwards compatibility with handler signatures.
+* Use AnyKitError for the union type.
+*/
+type OutfitterError = AnyKitError;
+import { Result } from "better-result";
+import { z } from "zod";
+/**
+* Options for error serialization.
+*/
+interface SerializeErrorOptions {
+	/** Include stack trace (default: false in production, true in development) */
+	includeStack?: boolean;
+}
+/**
+* Serialize a OutfitterError to JSON-safe format.
+*
+* Strips stack traces in production, preserves in development.
+* Automatically redacts sensitive values from context.
+*
+* @param error - The error to serialize
+* @param options - Serialization options
+* @returns JSON-safe serialized error
+*
+* @example
+* ```typescript
+* const serialized = serializeError(new NotFoundError("note", "abc123"));
+* // { _tag: "NotFoundError", category: "not_found", message: "note not found: abc123", context: { resourceType: "note", resourceId: "abc123" } }
+* ```
+*/
+declare function serializeError(error: OutfitterError, options?: SerializeErrorOptions): SerializedError;
+/**
+* Deserialize error from JSON (e.g., from MCP response).
+*
+* Returns a typed OutfitterError subclass based on _tag.
+*
+* @param data - Serialized error data
+* @returns Reconstructed OutfitterError instance
+*
+* @example
+* ```typescript
+* const error = deserializeError(jsonData);
+* if (error._tag === "NotFoundError") {
+*   // TypeScript knows error.resourceType exists
+* }
+* ```
+*/
+declare function deserializeError(data: SerializedError): OutfitterError;
+/**
+* Safely stringify any value to JSON.
+*
+* Handles circular references, BigInt, and other non-JSON-safe values.
+* Applies redaction to sensitive values.
+*
+* @param value - Value to stringify
+* @param space - Indentation (default: undefined for compact)
+* @returns JSON string
+*
+* @example
+* ```typescript
+* const json = safeStringify({ apiKey: "sk-secret", data: "safe" });
+* // '{"apiKey":"[REDACTED]","data":"safe"}'
+* ```
+*/
+declare function safeStringify(value: unknown, space?: number): string;
+/**
+* Safely parse JSON string with optional schema validation.
+*
+* Returns Result instead of throwing on invalid JSON.
+*
+* @typeParam T - Expected parsed type (or unknown if no schema)
+* @param json - JSON string to parse
+* @param schema - Optional Zod schema for validation
+* @returns Result with parsed value or ValidationError
+*
+* @example
+* ```typescript
+* const result = safeParse<Config>('{"port": 3000}', ConfigSchema);
+* if (result.isOk()) {
+*   const config = result.unwrap();
+* }
+* ```
+*/
+declare function safeParse<T = unknown>(json: string, schema?: z.ZodType<T>): Result<T, ValidationError>;
+export { serializeError, safeStringify, safeParse, deserializeError, SerializeErrorOptions };

package/dist/serialization.js

@@ -0,0 +1,270 @@
+// @bun
+import {
+  DEFAULT_PATTERNS,
+  DEFAULT_SENSITIVE_KEYS,
+  createRedactor
+} from "./redactor.js";
+import {
+  AuthError,
+  CancelledError,
+  ConflictError,
+  InternalError,
+  NetworkError,
+  NotFoundError,
+  PermissionError,
+  RateLimitError,
+  TimeoutError,
+  ValidationError
+} from "./errors.js";
+
+// packages/contracts/src/serialization.ts
+import { Result } from "better-result";
+var errorRegistry = {
+  ValidationError,
+  NotFoundError,
+  ConflictError,
+  PermissionError,
+  TimeoutError,
+  RateLimitError,
+  NetworkError,
+  InternalError,
+  AuthError,
+  CancelledError
+};
+function isValidErrorTag(tag) {
+  return tag in errorRegistry;
+}
+function extractContext(error) {
+  const context = {};
+  switch (error._tag) {
+    case "ValidationError": {
+      const ve = error;
+      if (ve.field !== undefined) {
+        context["field"] = ve.field;
+      }
+      break;
+    }
+    case "NotFoundError": {
+      const nfe = error;
+      context["resourceType"] = nfe.resourceType;
+      context["resourceId"] = nfe.resourceId;
+      break;
+    }
+    case "TimeoutError": {
+      const te = error;
+      context["operation"] = te.operation;
+      context["timeoutMs"] = te.timeoutMs;
+      break;
+    }
+    case "RateLimitError": {
+      const rle = error;
+      if (rle.retryAfterSeconds !== undefined) {
+        context["retryAfterSeconds"] = rle.retryAfterSeconds;
+      }
+      break;
+    }
+    case "AuthError": {
+      const ae = error;
+      if (ae.reason !== undefined) {
+        context["reason"] = ae.reason;
+      }
+      break;
+    }
+    case "ConflictError":
+    case "PermissionError":
+    case "NetworkError":
+    case "InternalError": {
+      const ce = error;
+      if (ce.context !== undefined) {
+        Object.assign(context, ce.context);
+      }
+      break;
+    }
+    default:
+      break;
+  }
+  return Object.keys(context).length > 0 ? context : undefined;
+}
+function serializeError(error, options) {
+  const isProduction = process.env["NODE_ENV"] === "production";
+  const includeStack = options?.includeStack ?? !isProduction;
+  const context = extractContext(error);
+  const serialized = {
+    _tag: error._tag,
+    category: error.category,
+    message: error.message
+  };
+  if (context !== undefined) {
+    serialized.context = context;
+  }
+  if (includeStack && error.stack !== undefined) {
+    if (serialized.context === undefined) {
+      serialized.context = {};
+    }
+    serialized.context["stack"] = error.stack;
+  }
+  return serialized;
+}
+function deserializeError(data) {
+  const tag = data._tag;
+  if (!isValidErrorTag(tag)) {
+    const props = {
+      message: data.message
+    };
+    if (data.context !== undefined) {
+      props.context = data.context;
+    }
+    return new InternalError(props);
+  }
+  const context = data.context ?? {};
+  switch (tag) {
+    case "ValidationError": {
+      const props = {
+        message: data.message
+      };
+      const field = context["field"];
+      if (field !== undefined) {
+        props.field = field;
+      }
+      return new ValidationError(props);
+    }
+    case "NotFoundError":
+      return new NotFoundError({
+        message: data.message,
+        resourceType: context["resourceType"] ?? "unknown",
+        resourceId: context["resourceId"] ?? "unknown"
+      });
+    case "ConflictError": {
+      const props = {
+        message: data.message
+      };
+      if (Object.keys(context).length > 0) {
+        props.context = context;
+      }
+      return new ConflictError(props);
+    }
+    case "PermissionError": {
+      const props = {
+        message: data.message
+      };
+      if (Object.keys(context).length > 0) {
+        props.context = context;
+      }
+      return new PermissionError(props);
+    }
+    case "TimeoutError":
+      return new TimeoutError({
+        message: data.message,
+        operation: context["operation"] ?? "unknown",
+        timeoutMs: context["timeoutMs"] ?? 0
+      });
+    case "RateLimitError": {
+      const props = {
+        message: data.message
+      };
+      const retryAfter = context["retryAfterSeconds"];
+      if (retryAfter !== undefined) {
+        props.retryAfterSeconds = retryAfter;
+      }
+      return new RateLimitError(props);
+    }
+    case "NetworkError": {
+      const props = {
+        message: data.message
+      };
+      if (Object.keys(context).length > 0) {
+        props.context = context;
+      }
+      return new NetworkError(props);
+    }
+    case "InternalError": {
+      const props = {
+        message: data.message
+      };
+      if (Object.keys(context).length > 0) {
+        props.context = context;
+      }
+      return new InternalError(props);
+    }
+    case "AuthError": {
+      const props = {
+        message: data.message
+      };
+      const reason = context["reason"];
+      if (reason !== undefined) {
+        props.reason = reason;
+      }
+      return new AuthError(props);
+    }
+    case "CancelledError":
+      return new CancelledError({
+        message: data.message
+      });
+    default: {
+      const props = {
+        message: data.message
+      };
+      if (Object.keys(context).length > 0) {
+        props.context = context;
+      }
+      return new InternalError(props);
+    }
+  }
+}
+function safeStringify(value, space) {
+  const seen = new WeakSet;
+  const redactor = createRedactor({
+    patterns: [...DEFAULT_PATTERNS],
+    keys: [...DEFAULT_SENSITIVE_KEYS]
+  });
+  const replacer = (key, val) => {
+    if (typeof val === "bigint") {
+      return val.toString();
+    }
+    if (typeof val === "object" && val !== null) {
+      if (seen.has(val)) {
+        return "[Circular]";
+      }
+      seen.add(val);
+    }
+    if (key !== "" && redactor.isSensitiveKey(key) && val !== null && val !== undefined) {
+      return "[REDACTED]";
+    }
+    if (typeof val === "string") {
+      return redactor.redactString(val);
+    }
+    return val;
+  };
+  return JSON.stringify(value, replacer, space);
+}
+function safeParse(json, schema) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : "Unknown parse error";
+    return Result.err(new ValidationError({
+      message: `JSON parse error: ${errorMessage}`
+    }));
+  }
+  if (schema === undefined) {
+    return Result.ok(parsed);
+  }
+  const parseResult = schema.safeParse(parsed);
+  if (parseResult.success) {
+    return Result.ok(parseResult.data);
+  }
+  const issues = parseResult.error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    return `${path}: ${issue.message}`;
+  }).join("; ");
+  return Result.err(new ValidationError({
+    message: `Schema validation failed: ${issues}`
+  }));
+}
+export {
+  serializeError,
+  safeStringify,
+  safeParse,
+  deserializeError
+};

package/dist/validation.d.ts

@@ -0,0 +1,59 @@
+import { TaggedErrorClass } from "better-result";
+declare const ValidationErrorBase: TaggedErrorClass<"ValidationError", {
+	message: string;
+	field?: string;
+}>;
+/**
+* Input validation failed.
+*
+* @example
+* ```typescript
+* new ValidationError({ message: "Email format invalid", field: "email" });
+* ```
+*/
+declare class ValidationError extends ValidationErrorBase {
+	readonly category: "validation";
+	exitCode(): number;
+	statusCode(): number;
+}
+import { Result } from "better-result";
+import { z } from "zod";
+/**
+* Create a validator function from a Zod schema.
+*
+* @typeParam T - The validated output type
+* @param schema - Zod schema to validate against
+* @returns A function that validates input and returns Result
+*
+* @example
+* ```typescript
+* const NoteSchema = z.object({
+*   id: z.string().uuid(),
+*   title: z.string().min(1),
+* });
+*
+* const validateNote = createValidator(NoteSchema);
+* const result = validateNote(input); // Result<Note, ValidationError>
+* ```
+*/
+declare function createValidator<T>(schema: z.ZodType<T>): (input: unknown) => Result<T, ValidationError>;
+/**
+* Validate input against a Zod schema.
+*
+* Standardized wrapper for Zod schemas that returns Result instead of throwing.
+*
+* @typeParam T - The validated output type
+* @param schema - Zod schema to validate against
+* @param input - Unknown input to validate
+* @returns Result with validated data or ValidationError
+*
+* @example
+* ```typescript
+* const result = validateInput(NoteSchema, userInput);
+* if (result.isErr()) {
+*   console.error(result.unwrapErr().message);
+* }
+* ```
+*/
+declare function validateInput<T>(schema: z.ZodType<T>, input: unknown): Result<T, ValidationError>;
+export { validateInput, createValidator };

package/dist/validation.js

@@ -0,0 +1,42 @@
+// @bun
+import {
+  ValidationError
+} from "./errors.js";
+
+// packages/contracts/src/validation.ts
+import { Result } from "better-result";
+function formatZodIssues(issues) {
+  return issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    return `${path}: ${issue.message}`;
+  }).join("; ");
+}
+function extractField(issues) {
+  const firstIssue = issues[0];
+  if (firstIssue && firstIssue.path.length > 0) {
+    return firstIssue.path.join(".");
+  }
+  return;
+}
+function createValidator(schema) {
+  return (input) => {
+    return validateInput(schema, input);
+  };
+}
+function validateInput(schema, input) {
+  const parseResult = schema.safeParse(input);
+  if (parseResult.success) {
+    return Result.ok(parseResult.data);
+  }
+  const message = formatZodIssues(parseResult.error.issues);
+  const field = extractField(parseResult.error.issues);
+  const errorProps = { message };
+  if (field !== undefined) {
+    errorProps.field = field;
+  }
+  return Result.err(new ValidationError(errorProps));
+}
+export {
+  validateInput,
+  createValidator
+};