@outfitter/contracts 0.1.0-rc.1

package/dist/handler.d.ts

@@ -0,0 +1,318 @@
+import { TaggedErrorClass } from "better-result";
+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";
+/**
+* Logger interface for handler context.
+* Implementations provided by @outfitter/logging.
+*
+* All log methods accept an optional context object that will be merged
+* with any context inherited from parent loggers created via `child()`.
+*/
+interface Logger {
+	trace(message: string, metadata?: Record<string, unknown>): void;
+	debug(message: string, metadata?: Record<string, unknown>): void;
+	info(message: string, metadata?: Record<string, unknown>): void;
+	warn(message: string, metadata?: Record<string, unknown>): void;
+	error(message: string, metadata?: Record<string, unknown>): void;
+	fatal(message: string, metadata?: Record<string, unknown>): void;
+	/**
+	* Creates a child logger with additional context.
+	*
+	* Context from the child is merged with the parent's context,
+	* with child context taking precedence for duplicate keys.
+	* Child loggers are composable (can create nested children).
+	*
+	* @param context - Additional context to include in all log messages
+	* @returns A new Logger instance with the merged context
+	*
+	* @example
+	* ```typescript
+	* const requestLogger = ctx.logger.child({ requestId: ctx.requestId });
+	* requestLogger.info("Processing request"); // includes requestId
+	*
+	* const opLogger = requestLogger.child({ operation: "create" });
+	* opLogger.debug("Starting"); // includes requestId + operation
+	* ```
+	*/
+	child(context: Record<string, unknown>): Logger;
+}
+/**
+* Resolved configuration interface.
+* Implementations provided by @outfitter/config.
+*/
+interface ResolvedConfig {
+	get<T>(key: string): T | undefined;
+	getRequired<T>(key: string): T;
+}
+/**
+* Handler context - provides cross-cutting concerns without polluting handler signatures.
+*
+* @example
+* ```typescript
+* const handler: Handler<Input, Output, NotFoundError> = async (input, ctx) => {
+*   ctx.logger.debug("Processing request", { requestId: ctx.requestId });
+*   // ... handler logic
+* };
+* ```
+*/
+interface HandlerContext {
+	/** Abort signal for cancellation propagation */
+	signal?: AbortSignal;
+	/** Unique request identifier for tracing (UUIDv7) */
+	requestId: string;
+	/** Structured logger with automatic redaction */
+	logger: Logger;
+	/** Resolved configuration values */
+	config?: ResolvedConfig;
+	/** Workspace root path, if detected */
+	workspaceRoot?: string;
+	/** Current working directory */
+	cwd: string;
+	/** Environment variables (filtered, redacted) */
+	env: Record<string, string | undefined>;
+}
+/**
+* Handler - transport-agnostic domain logic unit.
+*
+* Handlers receive typed input, return Results, and know nothing about
+* transport or output format. CLI and MCP are thin adapters over handlers.
+*
+* @typeParam TInput - Validated input parameters
+* @typeParam TOutput - Success return type
+* @typeParam TError - Error type (must extend OutfitterError)
+*
+* @example
+* ```typescript
+* const getNote: Handler<{ id: string }, Note, NotFoundError> = async (input, ctx) => {
+*   const note = await ctx.db.notes.find(input.id);
+*   if (!note) return Result.err(new NotFoundError("note", input.id));
+*   return Result.ok(note);
+* };
+* ```
+*/
+type Handler<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> = (input: TInput, ctx: HandlerContext) => Promise<Result<TOutput, TError>>;
+/**
+* Synchronous handler variant for operations that don't need async.
+*/
+type SyncHandler<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> = (input: TInput, ctx: HandlerContext) => Result<TOutput, TError>;
+export { SyncHandler, ResolvedConfig, Logger, HandlerContext, Handler };

package/dist/handler.js

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