@outfitter/contracts 0.1.0-rc.1

package/dist/envelope.js

@@ -0,0 +1,56 @@
+// @bun
+import {
+  serializeError
+} from "./serialization.js";
+import"./redactor.js";
+import {
+  statusCodeMap
+} from "./errors.js";
+import {
+  generateRequestId
+} from "./context.js";
+
+// packages/contracts/src/envelope.ts
+function buildMeta(overrides) {
+  const meta = {
+    requestId: overrides?.requestId ?? generateRequestId(),
+    timestamp: new Date().toISOString()
+  };
+  if (overrides?.durationMs !== undefined) {
+    meta.durationMs = overrides.durationMs;
+  }
+  return meta;
+}
+function toEnvelope(result, meta) {
+  const envelopeMeta = buildMeta(meta);
+  if (result.isOk()) {
+    return {
+      ok: true,
+      data: result.value,
+      meta: envelopeMeta
+    };
+  }
+  return {
+    ok: false,
+    error: serializeError(result.error),
+    meta: envelopeMeta
+  };
+}
+function toHttpResponse(result) {
+  const envelope = toEnvelope(result);
+  if (envelope.ok) {
+    return {
+      status: 200,
+      body: envelope
+    };
+  }
+  const status = statusCodeMap[envelope.error.category];
+  return {
+    status,
+    body: envelope
+  };
+}
+export {
+  toHttpResponse,
+  toEnvelope
+};

package/dist/errors.d.ts

@@ -0,0 +1,261 @@
+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";
+/**
+* Maps error category to CLI exit code.
+* Non-zero exit indicates error; specific values for script automation.
+*/
+declare const exitCodeMap: Record<ErrorCategory, number>;
+/**
+* Maps error category to HTTP status code.
+* Used by MCP servers and API responses.
+*/
+declare const statusCodeMap: Record<ErrorCategory, number>;
+/**
+* Serialized error format for JSON transport.
+*/
+interface SerializedError {
+	_tag: string;
+	category: ErrorCategory;
+	message: string;
+	context?: Record<string, unknown>;
+}
+/**
+* Base interface for OutfitterError properties.
+* All concrete error classes must include these fields.
+*/
+interface KitErrorProps {
+	message: string;
+	category: ErrorCategory;
+	context?: Record<string, unknown>;
+}
+/**
+* Get CLI exit code for an error category.
+*/
+declare function getExitCode(category: ErrorCategory): number;
+/**
+* Get HTTP status code for an error category.
+*/
+declare function getStatusCode(category: ErrorCategory): number;
+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;
+export { statusCodeMap, getStatusCode, getExitCode, exitCodeMap, ValidationError, TimeoutError, SerializedError, RateLimitError, PermissionError, OutfitterError, NotFoundError, NetworkError, KitErrorProps, InternalError, ErrorCategory, ConflictError, CancelledError, AuthError, AssertionError, AnyKitError };

package/dist/errors.js

@@ -0,0 +1,171 @@
+// @bun
+// packages/contracts/src/errors.ts
+import { TaggedError } from "better-result";
+var exitCodeMap = {
+  validation: 1,
+  not_found: 2,
+  conflict: 3,
+  permission: 4,
+  timeout: 5,
+  rate_limit: 6,
+  network: 7,
+  internal: 8,
+  auth: 9,
+  cancelled: 130
+};
+var statusCodeMap = {
+  validation: 400,
+  not_found: 404,
+  conflict: 409,
+  permission: 403,
+  timeout: 504,
+  rate_limit: 429,
+  network: 502,
+  internal: 500,
+  auth: 401,
+  cancelled: 499
+};
+function getExitCode(category) {
+  return exitCodeMap[category];
+}
+function getStatusCode(category) {
+  return statusCodeMap[category];
+}
+var ValidationErrorBase = TaggedError("ValidationError")();
+var AssertionErrorBase = TaggedError("AssertionError")();
+var NotFoundErrorBase = TaggedError("NotFoundError")();
+var ConflictErrorBase = TaggedError("ConflictError")();
+var PermissionErrorBase = TaggedError("PermissionError")();
+var TimeoutErrorBase = TaggedError("TimeoutError")();
+var RateLimitErrorBase = TaggedError("RateLimitError")();
+var NetworkErrorBase = TaggedError("NetworkError")();
+var InternalErrorBase = TaggedError("InternalError")();
+var AuthErrorBase = TaggedError("AuthError")();
+var CancelledErrorBase = TaggedError("CancelledError")();
+
+class ValidationError extends ValidationErrorBase {
+  category = "validation";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class AssertionError extends AssertionErrorBase {
+  category = "internal";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class NotFoundError extends NotFoundErrorBase {
+  category = "not_found";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class ConflictError extends ConflictErrorBase {
+  category = "conflict";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class PermissionError extends PermissionErrorBase {
+  category = "permission";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class TimeoutError extends TimeoutErrorBase {
+  category = "timeout";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class RateLimitError extends RateLimitErrorBase {
+  category = "rate_limit";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class NetworkError extends NetworkErrorBase {
+  category = "network";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class InternalError extends InternalErrorBase {
+  category = "internal";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class AuthError extends AuthErrorBase {
+  category = "auth";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+
+class CancelledError extends CancelledErrorBase {
+  category = "cancelled";
+  exitCode() {
+    return getExitCode(this.category);
+  }
+  statusCode() {
+    return getStatusCode(this.category);
+  }
+}
+export {
+  statusCodeMap,
+  getStatusCode,
+  getExitCode,
+  exitCodeMap,
+  ValidationError,
+  TimeoutError,
+  RateLimitError,
+  PermissionError,
+  NotFoundError,
+  NetworkError,
+  InternalError,
+  ConflictError,
+  CancelledError,
+  AuthError,
+  AssertionError
+};