@distilled.cloud/core 0.0.0-john

package/src/errors.ts

@@ -0,0 +1,178 @@
+/**
+ * Common error types shared across SDKs.
+ *
+ * Each SDK defines its own provider-specific errors (e.g., Unauthorized, NotFound)
+ * using the category system. This module provides base error types and utilities
+ * that are used across all SDKs.
+ */
+import * as Schema from "effect/Schema";
+import * as Category from "./category.ts";
+
+// ============================================================================
+// Common HTTP Status Error Classes
+// ============================================================================
+
+/**
+ * Unauthorized - Authentication failure (401).
+ */
+export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
+  "Unauthorized",
+  { message: Schema.String },
+).pipe(Category.withAuthError) {}
+
+/**
+ * Forbidden - Access denied (403).
+ */
+export class Forbidden extends Schema.TaggedErrorClass<Forbidden>()(
+  "Forbidden",
+  { message: Schema.String },
+).pipe(Category.withAuthError) {}
+
+/**
+ * NotFound - Resource not found (404).
+ */
+export class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+  message: Schema.String,
+}).pipe(Category.withNotFoundError) {}
+
+/**
+ * BadRequest - Invalid request (400).
+ */
+export class BadRequest extends Schema.TaggedErrorClass<BadRequest>()(
+  "BadRequest",
+  { message: Schema.String },
+).pipe(Category.withBadRequestError) {}
+
+/**
+ * Conflict - Resource conflict (409).
+ */
+export class Conflict extends Schema.TaggedErrorClass<Conflict>()("Conflict", {
+  message: Schema.String,
+}).pipe(Category.withConflictError) {}
+
+/**
+ * UnprocessableEntity - Validation error (422).
+ */
+export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEntity>()(
+  "UnprocessableEntity",
+  { message: Schema.String },
+).pipe(Category.withBadRequestError) {}
+
+/**
+ * TooManyRequests - Rate limited (429).
+ */
+export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
+  "TooManyRequests",
+  { message: Schema.String },
+).pipe(
+  Category.withThrottlingError,
+  Category.withRetryable({ throttling: true }),
+) {}
+
+/**
+ * Locked - Resource locked (423).
+ */
+export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
+  message: Schema.String,
+}).pipe(Category.withLockedError, Category.withRetryable()) {}
+
+/**
+ * InternalServerError - Server error (500).
+ */
+export class InternalServerError extends Schema.TaggedErrorClass<InternalServerError>()(
+  "InternalServerError",
+  { message: Schema.String },
+).pipe(Category.withServerError, Category.withRetryable()) {}
+
+/**
+ * BadGateway - Bad gateway (502).
+ */
+export class BadGateway extends Schema.TaggedErrorClass<BadGateway>()(
+  "BadGateway",
+  { message: Schema.String },
+).pipe(Category.withServerError, Category.withRetryable()) {}
+
+/**
+ * ServiceUnavailable - Service unavailable (503).
+ */
+export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailable>()(
+  "ServiceUnavailable",
+  { message: Schema.String },
+).pipe(Category.withServerError, Category.withRetryable()) {}
+
+/**
+ * GatewayTimeout - Gateway timeout (504).
+ */
+export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
+  "GatewayTimeout",
+  { message: Schema.String },
+).pipe(Category.withServerError, Category.withRetryable()) {}
+
+/**
+ * Configuration error - missing or invalid configuration.
+ */
+export class ConfigError extends Schema.TaggedErrorClass<ConfigError>()(
+  "ConfigError",
+  { message: Schema.String },
+).pipe(Category.withConfigurationError) {}
+
+// ============================================================================
+// Error Maps
+// ============================================================================
+
+/**
+ * Mapping from HTTP status codes to common error classes.
+ */
+export const HTTP_STATUS_MAP = {
+  400: BadRequest,
+  401: Unauthorized,
+  403: Forbidden,
+  404: NotFound,
+  409: Conflict,
+  422: UnprocessableEntity,
+  423: Locked,
+  429: TooManyRequests,
+  500: InternalServerError,
+  502: BadGateway,
+  503: ServiceUnavailable,
+  504: GatewayTimeout,
+} as const;
+
+/**
+ * HTTP status codes that are considered "default" errors (always present).
+ * These are excluded from per-operation error types since they're handled globally.
+ */
+export const DEFAULT_ERROR_STATUSES = new Set([401, 429, 500, 502, 503, 504]);
+
+/**
+ * All common API error classes.
+ */
+export const API_ERRORS = [
+  Unauthorized,
+  Forbidden,
+  NotFound,
+  BadRequest,
+  Conflict,
+  UnprocessableEntity,
+  TooManyRequests,
+  Locked,
+  InternalServerError,
+  BadGateway,
+  ServiceUnavailable,
+  GatewayTimeout,
+] as const;
+
+/**
+ * Default errors that apply to ALL operations.
+ * These are infrastructure-level errors that can occur regardless of the operation.
+ */
+export const DEFAULT_ERRORS = [
+  Unauthorized,
+  TooManyRequests,
+  InternalServerError,
+  BadGateway,
+  ServiceUnavailable,
+  GatewayTimeout,
+] as const;
+
+export type DefaultErrors = InstanceType<(typeof DEFAULT_ERRORS)[number]>;

package/src/json-patch.ts

@@ -0,0 +1,261 @@
+/**
+ * JSON Patch (RFC 6902) Implementation
+ *
+ * Provides a unified spec patching system for all SDKs.
+ * Patches are applied to OpenAPI/Discovery/Smithy specs before code generation
+ * to add error types, fix nullable fields, mark sensitive data, etc.
+ *
+ * @example
+ * ```ts
+ * import { applyAllPatches } from "@distilled.cloud/core/json-patch";
+ *
+ * const spec = JSON.parse(fs.readFileSync("openapi.json", "utf-8"));
+ * const { applied, errors } = applyAllPatches(spec, "./patches");
+ * ```
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface JsonPatchOperation {
+  op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+  path: string;
+  value?: unknown;
+  from?: string;
+}
+
+export type JsonPatch = JsonPatchOperation[];
+
+export interface PatchFile {
+  description: string;
+  patches: JsonPatch;
+}
+
+// ============================================================================
+// JSON Pointer (RFC 6901)
+// ============================================================================
+
+/**
+ * Parse a JSON Pointer (RFC 6901) path into segments.
+ */
+export function parseJsonPointer(pointer: string): string[] {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) {
+    throw new Error(`Invalid JSON Pointer: ${pointer}`);
+  }
+  return pointer
+    .slice(1)
+    .split("/")
+    .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+/**
+ * Get a value at a JSON Pointer path.
+ */
+export function getValueAtPath(obj: unknown, pointer: string): unknown {
+  const segments = parseJsonPointer(pointer);
+  let current: unknown = obj;
+
+  for (const segment of segments) {
+    if (current === null || typeof current !== "object") {
+      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+    }
+    if (Array.isArray(current)) {
+      const index = segment === "-" ? current.length : parseInt(segment, 10);
+      current = current[index];
+    } else {
+      current = (current as Record<string, unknown>)[segment];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Set a value at a JSON Pointer path.
+ */
+export function setValueAtPath(
+  obj: unknown,
+  pointer: string,
+  value: unknown,
+): void {
+  const segments = parseJsonPointer(pointer);
+  if (segments.length === 0) {
+    throw new Error("Cannot set value at root path");
+  }
+
+  let current: unknown = obj;
+
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i]!;
+    if (current === null || typeof current !== "object") {
+      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+    }
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      current = current[index];
+    } else {
+      current = (current as Record<string, unknown>)[segment];
+    }
+  }
+
+  const lastSegment = segments[segments.length - 1]!;
+  if (current === null || typeof current !== "object") {
+    throw new Error(
+      `Cannot set value at path ${pointer}: parent is not an object`,
+    );
+  }
+
+  if (Array.isArray(current)) {
+    const index =
+      lastSegment === "-" ? current.length : parseInt(lastSegment, 10);
+    if (lastSegment === "-") {
+      current.push(value);
+    } else {
+      current[index] = value;
+    }
+  } else {
+    (current as Record<string, unknown>)[lastSegment] = value;
+  }
+}
+
+/**
+ * Remove a value at a JSON Pointer path.
+ */
+export function removeValueAtPath(obj: unknown, pointer: string): void {
+  const segments = parseJsonPointer(pointer);
+  if (segments.length === 0) {
+    throw new Error("Cannot remove root");
+  }
+
+  let current: unknown = obj;
+
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i]!;
+    if (current === null || typeof current !== "object") {
+      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+    }
+    if (Array.isArray(current)) {
+      current = current[parseInt(segment, 10)];
+    } else {
+      current = (current as Record<string, unknown>)[segment];
+    }
+  }
+
+  const lastSegment = segments[segments.length - 1]!;
+  if (current === null || typeof current !== "object") {
+    throw new Error(
+      `Cannot remove at path ${pointer}: parent is not an object`,
+    );
+  }
+
+  if (Array.isArray(current)) {
+    current.splice(parseInt(lastSegment, 10), 1);
+  } else {
+    delete (current as Record<string, unknown>)[lastSegment];
+  }
+}
+
+// ============================================================================
+// Patch Operations
+// ============================================================================
+
+/**
+ * Apply a single JSON Patch operation.
+ */
+export function applyOperation(
+  obj: unknown,
+  operation: JsonPatchOperation,
+): void {
+  switch (operation.op) {
+    case "add":
+      setValueAtPath(obj, operation.path, operation.value);
+      break;
+    case "remove":
+      removeValueAtPath(obj, operation.path);
+      break;
+    case "replace":
+      // For replace, the path must exist
+      getValueAtPath(obj, operation.path); // throws if doesn't exist
+      setValueAtPath(obj, operation.path, operation.value);
+      break;
+    case "move": {
+      if (!operation.from) throw new Error("move operation requires 'from'");
+      const moveValue = getValueAtPath(obj, operation.from);
+      removeValueAtPath(obj, operation.from);
+      setValueAtPath(obj, operation.path, moveValue);
+      break;
+    }
+    case "copy": {
+      if (!operation.from) throw new Error("copy operation requires 'from'");
+      const copyValue = getValueAtPath(obj, operation.from);
+      setValueAtPath(
+        obj,
+        operation.path,
+        JSON.parse(JSON.stringify(copyValue)),
+      );
+      break;
+    }
+    case "test": {
+      const testValue = getValueAtPath(obj, operation.path);
+      if (JSON.stringify(testValue) !== JSON.stringify(operation.value)) {
+        throw new Error(
+          `Test operation failed at ${operation.path}: expected ${JSON.stringify(operation.value)}, got ${JSON.stringify(testValue)}`,
+        );
+      }
+      break;
+    }
+    default:
+      throw new Error(`Unknown operation: ${(operation as { op: string }).op}`);
+  }
+}
+
+/**
+ * Apply a JSON Patch to an object (mutates in place).
+ */
+export function applyPatch(obj: unknown, patch: JsonPatch): void {
+  for (const operation of patch) {
+    applyOperation(obj, operation);
+  }
+}
+
+/**
+ * Load and apply all patches from a directory.
+ * Finds all *.patch.json files and applies them.
+ */
+export function applyAllPatches(
+  spec: unknown,
+  patchDir: string,
+): { applied: string[]; errors: string[] } {
+  const applied: string[] = [];
+  const errors: string[] = [];
+
+  if (!fs.existsSync(patchDir)) {
+    return { applied, errors };
+  }
+
+  // Find all .patch.json files
+  const files = fs
+    .readdirSync(patchDir)
+    .filter((f) => f.endsWith(".patch.json"))
+    .sort(); // Sort for deterministic application order
+
+  for (const file of files) {
+    const filePath = path.join(patchDir, file);
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      const patchFile: PatchFile = JSON.parse(content);
+      applyPatch(spec, patchFile.patches);
+      applied.push(`${file}: ${patchFile.description}`);
+    } catch (error) {
+      errors.push(
+        `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  return { applied, errors };
+}