@outfitter/contracts 0.4.1 → 0.5.0

package/dist/shared/@outfitter/contracts-x0ppyt7e.d.ts

@@ -0,0 +1,76 @@
+import { ValidationError } from "./contracts-mehpmvwp.js";
+import { Result } from "better-result";
+import { z } from "zod";
+/**
+* Format Zod issues into a human-readable error message.
+*
+* @param issues - Array of Zod validation issues
+* @returns Formatted error message string
+*/
+declare function formatZodIssues(issues: z.ZodIssue[]): string;
+/**
+* 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>;
+/**
+* Parse and validate data against a Zod schema, returning a Result.
+*
+* Wraps Zod's `safeParse` into `Result<T, ValidationError>` where `T` is
+* automatically inferred from the schema — no manual type argument needed.
+*
+* @typeParam TSchema - The Zod schema type (inferred from `schema` argument)
+* @param schema - Zod schema to parse/validate against
+* @param data - Unknown data to parse
+* @returns `Ok<z.infer<TSchema>>` for valid data, `Err<ValidationError>` for invalid data
+*
+* @example
+* ```typescript
+* const UserSchema = z.object({
+*   name: z.string().min(1),
+*   email: z.string().email(),
+* });
+*
+* const result = parseInput(UserSchema, input);
+* // Result<{ name: string; email: string }, ValidationError>
+*
+* if (result.isOk()) {
+*   result.value.name; // string — fully typed, no manual annotation
+* }
+* ```
+*/
+declare function parseInput<TSchema extends z.ZodType>(schema: TSchema, data: unknown): Result<z.infer<TSchema>, ValidationError>;
+export { formatZodIssues, createValidator, validateInput, parseInput };

package/dist/shared/@outfitter/{contracts-0akf2sm6.d.ts → contracts-zma4mscd.d.ts}

@@ -1,4 +1,5 @@
-import { OutfitterError } from "./contracts-3gswmhb1.js";
+import { ProgressCallback } from "./contracts-msxdg52h.js";
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
 import { Logger } from "./contracts-rwzqy9rn.js";
 import { Result } from "better-result";
 /**
@@ -29,6 +30,20 @@ interface HandlerContext {
 	env: Record<string, string | undefined>;
 	/** Structured logger with automatic redaction */
 	logger: Logger;
+	/**
+	* Optional streaming progress callback.
+	*
+	* When provided by a transport adapter, the handler can emit progress
+	* events without knowing which transport consumes them. When `undefined`,
+	* the handler does not stream — it simply returns its final result.
+	*
+	* @example
+	* ```typescript
+	* ctx.progress?.({ type: "start", command: "check", ts: new Date().toISOString() });
+	* ctx.progress?.({ type: "progress", current: 5, total: 10 });
+	* ```
+	*/
+	progress?: ProgressCallback;
 	/** Unique request identifier for tracing (UUIDv7) */
 	requestId: string;
 	/** Abort signal for cancellation propagation */

package/dist/shared/@outfitter/contracts-zsgxsa91.d.ts

@@ -0,0 +1,84 @@
+import { OutfitterError } from "./contracts-7a0xmwbg.js";
+/**
+* An error mapper converts an unknown error into a typed OutfitterError.
+*
+* Return `undefined` if the mapper does not handle this error (pass to next mapper or default).
+*/
+type ErrorMapper = (error: unknown) => OutfitterError | undefined;
+/**
+* Type guard: checks whether `value` is a typed Outfitter error (has a `category` field
+* matching a known {@link ErrorCategory}).
+*/
+declare function isOutfitterError(value: unknown): value is OutfitterError;
+/**
+* Extract a human-readable message from an unknown error value.
+*
+* Handles Error instances, plain strings, objects with a `message` property,
+* and falls back to `"Unknown error"` for everything else.
+*/
+declare function extractMessage(error: unknown): string;
+/**
+* Normalize an unknown error into a typed OutfitterError.
+*
+* - Typed Outfitter errors pass through unchanged (same reference, mapper NOT called).
+* - Untyped errors go through optional mapper.
+* - Without mapper or when mapper returns `undefined`, wraps as {@link InternalError}.
+* - Plain strings are wrapped as InternalError with the string as message.
+*
+* @param error - The unknown error to normalize
+* @param mapper - Optional mapper to convert untyped errors into typed OutfitterErrors
+* @returns A typed OutfitterError
+*
+* @example
+* ```typescript
+* // Typed errors pass through
+* const typed = new ValidationError({ message: "bad input" });
+* wrapError(typed) === typed; // true — same reference
+*
+* // Untyped errors go through mapper
+* const mapper: ErrorMapper = (err) => {
+*   if (err instanceof Error && err.message.includes("ECONNREFUSED")) {
+*     return new NetworkError({ message: err.message });
+*   }
+*   return undefined;
+* };
+* wrapError(new Error("ECONNREFUSED"), mapper); // NetworkError
+*
+* // Unmatched errors become InternalError
+* wrapError(new Error("unknown")); // InternalError
+*
+* // Strings become InternalError with message
+* wrapError("something failed"); // InternalError { message: "something failed" }
+* ```
+*/
+declare function wrapError(error: unknown, mapper?: ErrorMapper): OutfitterError;
+/**
+* Compose multiple error mappers into a single mapper.
+*
+* Mappers run in declared order and short-circuit on the first match
+* (first mapper to return a non-`undefined` value wins).
+*
+* @param mappers - Error mappers to compose
+* @returns A single composed error mapper
+*
+* @example
+* ```typescript
+* const networkMapper: ErrorMapper = (err) => {
+*   if (err instanceof Error && err.message.includes("ECONNREFUSED")) {
+*     return new NetworkError({ message: err.message });
+*   }
+*   return undefined;
+* };
+* const timeoutMapper: ErrorMapper = (err) => {
+*   if (err instanceof Error && err.message.includes("ETIMEDOUT")) {
+*     return TimeoutError.create("request", 5000);
+*   }
+*   return undefined;
+* };
+*
+* const composed = composeMappers(networkMapper, timeoutMapper);
+* wrapError(new Error("ECONNREFUSED"), composed); // NetworkError
+* ```
+*/
+declare function composeMappers(...mappers: ErrorMapper[]): ErrorMapper;
+export { ErrorMapper, isOutfitterError, extractMessage, wrapError, composeMappers };

package/dist/stream.d.ts

@@ -0,0 +1,2 @@
+import { ProgressCallback, StreamEvent, StreamProgressEvent, StreamStartEvent, StreamStepEvent } from "./shared/@outfitter/contracts-msxdg52h.js";
+export { StreamStepEvent, StreamStartEvent, StreamProgressEvent, StreamEvent, ProgressCallback };

package/dist/stream.js

@@ -0,0 +1 @@
+// @bun

package/dist/validation.d.ts

@@ -1,3 +1,7 @@
-import { createValidator, validateInput } from "./shared/@outfitter/contracts-9wtm5nsw.js";
-import "./shared/@outfitter/contracts-3gswmhb1.js";
-export { validateInput, createValidator };
+import { createValidator, formatZodIssues, parseInput, validateInput } from "./shared/@outfitter/contracts-x0ppyt7e.js";
+import "./shared/@outfitter/contracts-7a0xmwbg.js";
+import "./shared/@outfitter/contracts-735ecmbq.js";
+import "./shared/@outfitter/contracts-mehpmvwp.js";
+import "./shared/@outfitter/contracts-qpbv29bg.js";
+import "./shared/@outfitter/contracts-njb2art4.js";
+export { validateInput, parseInput, formatZodIssues, createValidator };

package/dist/validation.js

@@ -1,10 +1,14 @@
 // @bun
 import {
   createValidator,
+  formatZodIssues,
+  parseInput,
   validateInput
-} from "./shared/@outfitter/contracts-0snpmkdt.js";
-import"./shared/@outfitter/contracts-phjhz5q3.js";
+} from "./shared/@outfitter/contracts-hgh47193.js";
+import"./shared/@outfitter/contracts-vhr2ep6b.js";
 export {
   validateInput,
+  parseInput,
+  formatZodIssues,
   createValidator
 };

package/dist/wrap-error.d.ts

@@ -0,0 +1,7 @@
+import { ErrorMapper, composeMappers, extractMessage, isOutfitterError, wrapError } from "./shared/@outfitter/contracts-zsgxsa91.js";
+import "./shared/@outfitter/contracts-7a0xmwbg.js";
+import "./shared/@outfitter/contracts-735ecmbq.js";
+import "./shared/@outfitter/contracts-mehpmvwp.js";
+import "./shared/@outfitter/contracts-qpbv29bg.js";
+import "./shared/@outfitter/contracts-njb2art4.js";
+export { wrapError, isOutfitterError, extractMessage, composeMappers, ErrorMapper };

package/dist/wrap-error.js

@@ -0,0 +1,71 @@
+// @bun
+import {
+  InternalError
+} from "./shared/@outfitter/contracts-vhr2ep6b.js";
+
+// packages/contracts/src/wrap-error.ts
+function isOutfitterError(value) {
+  if (!(value instanceof Error)) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate["category"] === "string" && typeof candidate["message"] === "string" && typeof candidate["_tag"] === "string" && isErrorCategory(candidate["category"]);
+}
+var ERROR_CATEGORIES = new Set([
+  "validation",
+  "not_found",
+  "conflict",
+  "permission",
+  "timeout",
+  "rate_limit",
+  "network",
+  "internal",
+  "auth",
+  "cancelled"
+]);
+function isErrorCategory(value) {
+  return ERROR_CATEGORIES.has(value);
+}
+function extractMessage(error) {
+  if (typeof error === "string") {
+    return error || "Unknown error";
+  }
+  if (error instanceof Error) {
+    return error.message || "Unknown error";
+  }
+  if (error != null && typeof error === "object" && "message" in error) {
+    const msg = error["message"];
+    return typeof msg === "string" && msg ? msg : "Unknown error";
+  }
+  return "Unknown error";
+}
+function wrapError(error, mapper) {
+  if (isOutfitterError(error)) {
+    return error;
+  }
+  if (mapper != null) {
+    const mapped = mapper(error);
+    if (mapped != null) {
+      return mapped;
+    }
+  }
+  const message = extractMessage(error);
+  return new InternalError({ message });
+}
+function composeMappers(...mappers) {
+  return (error) => {
+    for (const mapper of mappers) {
+      const result = mapper(error);
+      if (result != null) {
+        return result;
+      }
+    }
+    return;
+  };
+}
+export {
+  wrapError,
+  isOutfitterError,
+  extractMessage,
+  composeMappers
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/contracts",
   "description": "Result/Error patterns, error taxonomy, and handler contracts for Outfitter",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "files": [
     "dist"
@@ -57,12 +57,24 @@
         "default": "./dist/errors.js"
       }
     },
+    "./from-fetch": {
+      "import": {
+        "types": "./dist/from-fetch.d.ts",
+        "default": "./dist/from-fetch.js"
+      }
+    },
     "./handler": {
       "import": {
         "types": "./dist/handler.d.ts",
         "default": "./dist/handler.js"
       }
     },
+    "./hints": {
+      "import": {
+        "types": "./dist/hints.d.ts",
+        "default": "./dist/hints.js"
+      }
+    },
     "./logging": {
       "import": {
         "types": "./dist/logging.d.ts",
@@ -112,35 +124,29 @@
         "default": "./dist/serialization.js"
       }
     },
+    "./stream": {
+      "import": {
+        "types": "./dist/stream.d.ts",
+        "default": "./dist/stream.js"
+      }
+    },
     "./validation": {
       "import": {
         "types": "./dist/validation.d.ts",
         "default": "./dist/validation.js"
       }
+    },
+    "./wrap-error": {
+      "import": {
+        "types": "./dist/wrap-error.d.ts",
+        "default": "./dist/wrap-error.js"
+      }
     }
   },
-  "sideEffects": false,
-  "scripts": {
-    "build": "cd ../.. && bunup --filter @outfitter/contracts",
-    "lint": "biome lint ./src",
-    "lint:fix": "biome lint --write ./src",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
-  },
-  "dependencies": {
-    "better-result": "^2.5.0",
-    "zod": "^4.3.5"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "typescript": "^5.8.0"
-  },
   "keywords": [
-    "outfitter",
     "contracts",
     "errors",
+    "outfitter",
     "result",
     "typescript"
   ],
@@ -150,7 +156,25 @@
     "url": "https://github.com/outfitter-dev/outfitter.git",
     "directory": "packages/contracts"
   },
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "cd ../.. && bash ./scripts/run-bunup-with-lock.sh bunup --filter @outfitter/contracts",
+    "lint": "oxlint ./src",
+    "lint:fix": "oxlint --fix ./src",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun ../../scripts/check-publish-manifest.ts"
+  },
+  "dependencies": {
+    "better-result": "^2.5.1",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.3"
   }
 }

package/dist/shared/@outfitter/contracts-31penhwa.d.ts

@@ -1,81 +0,0 @@
-import { OutfitterError, SerializedError, ValidationError } from "./contracts-3gswmhb1.js";
-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 { SerializeErrorOptions, serializeError, deserializeError, safeStringify, safeParse };