@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/errors/api.ts

@@ -0,0 +1,305 @@
+/**
+ * API error classes
+ *
+ * Errors thrown when the API returns error responses.
+ * Includes specific error types for common scenarios.
+ */
+
+import { TRPCClientError } from "@trpc/client";
+import { ComplianceError, type ComplianceErrorOptions } from "./base";
+import { ValidationError, type ValidationIssue } from "./validation";
+
+// ===========================
+// API Error Base Class
+// ===========================
+
+/**
+ * Error thrown when the API returns an error response.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.clients.create({ ... });
+ * } catch (error) {
+ *   if (error instanceof APIError) {
+ *     console.log("Status:", error.statusCode);
+ *     console.log("Code:", error.code);
+ *   }
+ * }
+ * ```
+ */
+export class APIError extends ComplianceError {
+  /**
+   * HTTP status code (if available)
+   */
+  public readonly statusCode?: number;
+
+  constructor(
+    message: string,
+    code: string,
+    options?: ComplianceErrorOptions & { statusCode?: number }
+  ) {
+    super(message, code, options);
+    this.name = "APIError";
+    this.statusCode = options?.statusCode;
+  }
+}
+
+// ===========================
+// Specific API Errors
+// ===========================
+
+/**
+ * Resource not found error (404).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.clients.retrieve("invalid-id");
+ * } catch (error) {
+ *   if (error instanceof NotFoundError) {
+ *     console.log(`${error.resourceType} '${error.resourceId}' not found`);
+ *   }
+ * }
+ * ```
+ */
+export class NotFoundError extends APIError {
+  /**
+   * Type of resource that was not found (e.g., "Client", "Transaction")
+   */
+  public readonly resourceType: string;
+
+  /**
+   * ID of the resource that was not found
+   */
+  public readonly resourceId: string;
+
+  constructor(resourceType: string, resourceId: string, requestId?: string) {
+    super(`${resourceType} with ID '${resourceId}' not found`, "NOT_FOUND", {
+      statusCode: 404,
+      requestId,
+      details: { resourceType, resourceId },
+    });
+    this.name = "NotFoundError";
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+  }
+}
+
+/**
+ * Authentication failed error (401).
+ * Thrown when the API key is invalid or missing.
+ */
+export class UnauthorizedError extends APIError {
+  constructor(message = "Invalid or missing API key", requestId?: string) {
+    super(message, "UNAUTHORIZED", { statusCode: 401, requestId });
+    this.name = "UnauthorizedError";
+  }
+}
+
+/**
+ * Permission denied error (403).
+ * Thrown when the API key lacks permission for the operation.
+ *
+ * @example
+ * ```typescript
+ * // Using test API key with live environment
+ * const sdk = new ComplianceSDK({
+ *   apiKey: "sk_test_...",
+ *   environment: "live", // No permission!
+ * });
+ * ```
+ */
+export class ForbiddenError extends APIError {
+  constructor(message = "Permission denied", requestId?: string) {
+    super(message, "FORBIDDEN", { statusCode: 403, requestId });
+    this.name = "ForbiddenError";
+  }
+}
+
+/**
+ * Rate limit exceeded error (429).
+ * Includes retry information when available.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.clients.list();
+ * } catch (error) {
+ *   if (error instanceof RateLimitError) {
+ *     console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+ *     await sleep(error.retryAfter * 1000);
+ *     // Retry...
+ *   }
+ * }
+ * ```
+ */
+export class RateLimitError extends APIError {
+  /**
+   * Seconds to wait before retrying (if provided by API)
+   */
+  public readonly retryAfter?: number;
+
+  constructor(retryAfter?: number, requestId?: string) {
+    const message = retryAfter
+      ? `Rate limit exceeded. Retry after ${retryAfter} seconds`
+      : "Rate limit exceeded";
+    super(message, "RATE_LIMITED", {
+      statusCode: 429,
+      requestId,
+      details: retryAfter ? { retryAfter } : undefined,
+    });
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Server error (5xx).
+ * Indicates an unexpected error on the API server.
+ */
+export class ServerError extends APIError {
+  constructor(message = "Internal server error", requestId?: string) {
+    super(message, "SERVER_ERROR", { statusCode: 500, requestId });
+    this.name = "ServerError";
+  }
+}
+
+/**
+ * Network/connection error.
+ * Thrown when the request fails to reach the server.
+ */
+export class NetworkError extends APIError {
+  constructor(message = "Network error", cause?: Error) {
+    super(message, "NETWORK_ERROR", { cause });
+    this.name = "NetworkError";
+  }
+}
+
+/**
+ * Request timeout error.
+ * Thrown when the request exceeds the configured timeout.
+ */
+export class TimeoutError extends APIError {
+  /**
+   * Timeout duration in milliseconds
+   */
+  public readonly timeout: number;
+
+  constructor(timeout: number, requestId?: string) {
+    super(`Request timed out after ${timeout}ms`, "TIMEOUT", {
+      requestId,
+      details: { timeout },
+    });
+    this.name = "TimeoutError";
+    this.timeout = timeout;
+  }
+}
+
+// ===========================
+// tRPC Error Mapping
+// ===========================
+
+/**
+ * Maps a tRPC client error to an SDK-specific error.
+ *
+ * This function converts tRPC errors into the appropriate
+ * SDK error class for better error handling.
+ *
+ * @param error - tRPC client error
+ * @returns SDK-specific error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await trpcClient.clients.retrieve.query({ id: "..." });
+ * } catch (error) {
+ *   if (isTRPCError(error)) {
+ *     throw mapTRPCError(error);
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mapTRPCError(error: TRPCClientError<any>): ComplianceError {
+  // Extract error data from tRPC response
+  const data = error.data as Record<string, unknown> | undefined;
+  const code = data?.code as string | undefined;
+  const requestId = data?.requestId as string | undefined;
+
+  // Handle specific error codes
+  switch (code) {
+    case "NOT_FOUND":
+      return new NotFoundError(
+        (data?.resourceType as string) ?? "Resource",
+        (data?.resourceId as string) ?? "unknown",
+        requestId
+      );
+
+    case "UNAUTHORIZED":
+      return new UnauthorizedError(error.message, requestId);
+
+    case "FORBIDDEN":
+      return new ForbiddenError(error.message, requestId);
+
+    case "BAD_REQUEST": {
+      // Check for Zod validation errors
+      const zodError = data?.zodError as
+        | { issues?: ValidationIssue[] }
+        | undefined;
+      if (zodError?.issues) {
+        return new ValidationError(zodError.issues, requestId);
+      }
+      return new ValidationError(
+        [{ path: [], message: error.message }],
+        requestId
+      );
+    }
+
+    case "TOO_MANY_REQUESTS":
+      return new RateLimitError(
+        data?.retryAfter as number | undefined,
+        requestId
+      );
+
+    case "INTERNAL_SERVER_ERROR":
+      return new ServerError(error.message, requestId);
+
+    case "TIMEOUT":
+      return new TimeoutError((data?.timeout as number) ?? 30000, requestId);
+
+    default:
+      // Check for network errors
+      if (
+        error.message.includes("fetch failed") ||
+        error.message.includes("network") ||
+        error.message.includes("ECONNREFUSED")
+      ) {
+        return new NetworkError(error.message, error);
+      }
+
+      // Generic API error
+      return new APIError(error.message, code ?? "UNKNOWN_ERROR", {
+        requestId,
+        cause: error,
+      });
+  }
+}
+
+/**
+ * Type guard to check if an error is a specific API error type.
+ *
+ * @param error - Error to check
+ * @param type - Error class to check against
+ * @returns True if error is an instance of the specified type
+ */
+export function isAPIError<T extends typeof APIError>(
+  error: unknown,
+  type?: T
+): error is InstanceType<T> {
+  if (type) {
+    return error instanceof type;
+  }
+  return error instanceof APIError;
+}

package/src/errors/base.ts

@@ -0,0 +1,127 @@
+/**
+ * Base error class for SDK errors
+ *
+ * All SDK errors extend this class, providing consistent
+ * structure for error handling and serialization.
+ */
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Options for creating a ComplianceError
+ */
+export interface ComplianceErrorOptions {
+  /**
+   * Request ID for tracing (from X-Request-ID header)
+   */
+  requestId?: string;
+
+  /**
+   * Additional error details
+   */
+  details?: Record<string, unknown>;
+
+  /**
+   * Original error that caused this error
+   */
+  cause?: Error;
+}
+
+/**
+ * JSON representation of a ComplianceError
+ */
+export interface ComplianceErrorJSON {
+  name: string;
+  code: string;
+  message: string;
+  requestId?: string;
+  details?: Record<string, unknown>;
+}
+
+// ===========================
+// Base Error Class
+// ===========================
+
+/**
+ * Base error class for all SDK errors.
+ *
+ * Provides consistent structure for:
+ * - Error codes for programmatic handling
+ * - Request IDs for debugging
+ * - Additional details
+ * - JSON serialization
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.clients.retrieve("invalid-id");
+ * } catch (error) {
+ *   if (error instanceof ComplianceError) {
+ *     console.log("Error code:", error.code);
+ *     console.log("Request ID:", error.requestId);
+ *     // Send to logging service
+ *     logger.error(error.toJSON());
+ *   }
+ * }
+ * ```
+ */
+export class ComplianceError extends Error {
+  /**
+   * Error code for programmatic handling.
+   * Examples: "VALIDATION_ERROR", "NOT_FOUND", "UNAUTHORIZED"
+   */
+  public readonly code: string;
+
+  /**
+   * Request ID for tracing (from X-Request-ID header).
+   * Useful for debugging with support.
+   */
+  public readonly requestId?: string;
+
+  /**
+   * Additional error details.
+   * Structure varies by error type.
+   */
+  public readonly details?: Record<string, unknown>;
+
+  constructor(message: string, code: string, options?: ComplianceErrorOptions) {
+    super(message, { cause: options?.cause });
+    this.name = "ComplianceError";
+    this.code = code;
+    this.requestId = options?.requestId;
+    this.details = options?.details;
+
+    // Maintain proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  /**
+   * Serializes the error to a JSON-compatible object.
+   * Useful for logging and error reporting.
+   *
+   * @returns JSON representation of the error
+   */
+  toJSON(): ComplianceErrorJSON {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      requestId: this.requestId,
+      details: this.details,
+    };
+  }
+
+  /**
+   * Returns a string suitable for sending to support.
+   * Includes request ID if available.
+   */
+  toSupportInfo(): string {
+    const parts = [`Error: ${this.message}`, `Code: ${this.code}`];
+    if (this.requestId) {
+      parts.push(`Request ID: ${this.requestId}`);
+    }
+    return parts.join("\n");
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,63 @@
+/**
+ * SDK Error Classes
+ *
+ * This module exports all error classes used by the SDK.
+ * All errors extend ComplianceError and provide consistent
+ * structure for error handling and serialization.
+ *
+ * Error Hierarchy:
+ * ```
+ * ComplianceError (base)
+ * ├── ValidationError      # Zod validation failures
+ * ├── APIError             # tRPC/HTTP errors from server
+ * │   ├── NotFoundError
+ * │   ├── UnauthorizedError
+ * │   ├── ForbiddenError
+ * │   ├── RateLimitError
+ * │   ├── ServerError
+ * │   ├── NetworkError
+ * │   └── TimeoutError
+ * └── UploadError          # File upload failures
+ *     ├── FileTooLargeError
+ *     ├── UploadTimeoutError
+ *     ├── InvalidFileTypeError
+ *     ├── UploadAbortedError
+ *     └── UploadUrlExpiredError
+ * ```
+ */
+
+// Base error
+export {
+  ComplianceError,
+  type ComplianceErrorOptions,
+  type ComplianceErrorJSON,
+} from "./base";
+
+// Validation errors
+export { ValidationError, type ValidationIssue } from "./validation";
+
+// API errors
+export {
+  APIError,
+  NotFoundError,
+  UnauthorizedError,
+  ForbiddenError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
+  mapTRPCError,
+  isAPIError,
+} from "./api";
+
+// Upload errors
+export {
+  UploadError,
+  FileTooLargeError,
+  UploadTimeoutError,
+  InvalidFileTypeError,
+  UploadAbortedError,
+  UploadUrlExpiredError,
+  isUploadError,
+  type UploadStage,
+} from "./upload";

package/src/errors/upload.ts

@@ -0,0 +1,204 @@
+/**
+ * Upload error classes
+ *
+ * Errors thrown during file upload operations.
+ */
+
+import { ComplianceError, type ComplianceErrorOptions } from "./base";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Stage of upload where the error occurred
+ */
+export type UploadStage = "request" | "upload" | "confirm";
+
+// ===========================
+// Upload Error Classes
+// ===========================
+
+/**
+ * Error thrown during file upload operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.documents.upload(file, { clientId: "..." });
+ * } catch (error) {
+ *   if (error instanceof UploadError) {
+ *     console.log(`Upload failed at stage: ${error.stage}`);
+ *   }
+ * }
+ * ```
+ */
+export class UploadError extends ComplianceError {
+  /**
+   * Stage of the upload process where the error occurred:
+   * - "request": Failed to request upload URL
+   * - "upload": Failed to upload file to storage
+   * - "confirm": Failed to confirm upload with API
+   */
+  public readonly stage: UploadStage;
+
+  constructor(
+    message: string,
+    stage: UploadStage,
+    options?: ComplianceErrorOptions
+  ) {
+    super(message, "UPLOAD_ERROR", options);
+    this.name = "UploadError";
+    this.stage = stage;
+  }
+}
+
+/**
+ * File exceeds maximum allowed size.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.documents.upload(largeFile, { clientId: "..." });
+ * } catch (error) {
+ *   if (error instanceof FileTooLargeError) {
+ *     console.log(`Max size: ${error.maxSizeFormatted}`);
+ *     console.log(`Your file: ${error.actualSizeFormatted}`);
+ *   }
+ * }
+ * ```
+ */
+export class FileTooLargeError extends UploadError {
+  /**
+   * Maximum allowed file size in bytes
+   */
+  public readonly maxSize: number;
+
+  /**
+   * Actual file size in bytes
+   */
+  public readonly actualSize: number;
+
+  constructor(actualSize: number, maxSize: number) {
+    super(
+      `File size (${formatBytes(actualSize)}) exceeds maximum allowed size (${formatBytes(maxSize)})`,
+      "request",
+      { details: { actualSize, maxSize } }
+    );
+    this.name = "FileTooLargeError";
+    this.maxSize = maxSize;
+    this.actualSize = actualSize;
+  }
+
+  /**
+   * Maximum size formatted for display (e.g., "10 MB")
+   */
+  get maxSizeFormatted(): string {
+    return formatBytes(this.maxSize);
+  }
+
+  /**
+   * Actual size formatted for display (e.g., "15.2 MB")
+   */
+  get actualSizeFormatted(): string {
+    return formatBytes(this.actualSize);
+  }
+}
+
+/**
+ * Upload timed out.
+ */
+export class UploadTimeoutError extends UploadError {
+  /**
+   * Timeout duration in milliseconds
+   */
+  public readonly timeout: number;
+
+  constructor(timeout: number, requestId?: string) {
+    super(`Upload timed out after ${timeout}ms`, "upload", {
+      requestId,
+      details: { timeout },
+    });
+    this.name = "UploadTimeoutError";
+    this.timeout = timeout;
+  }
+}
+
+/**
+ * Invalid file type.
+ */
+export class InvalidFileTypeError extends UploadError {
+  /**
+   * Allowed MIME types
+   */
+  public readonly allowedTypes: string[];
+
+  /**
+   * Actual MIME type of the file
+   */
+  public readonly actualType: string;
+
+  constructor(actualType: string, allowedTypes: string[]) {
+    super(
+      `File type '${actualType}' is not allowed. Allowed types: ${allowedTypes.join(", ")}`,
+      "request",
+      { details: { actualType, allowedTypes } }
+    );
+    this.name = "InvalidFileTypeError";
+    this.actualType = actualType;
+    this.allowedTypes = allowedTypes;
+  }
+}
+
+/**
+ * Upload was aborted.
+ */
+export class UploadAbortedError extends UploadError {
+  constructor(requestId?: string) {
+    super("Upload was aborted", "upload", { requestId });
+    this.name = "UploadAbortedError";
+  }
+}
+
+/**
+ * Upload URL expired before upload completed.
+ */
+export class UploadUrlExpiredError extends UploadError {
+  constructor(requestId?: string) {
+    super(
+      "Upload URL has expired. Please request a new upload URL.",
+      "upload",
+      {
+        requestId,
+      }
+    );
+    this.name = "UploadUrlExpiredError";
+  }
+}
+
+// ===========================
+// Helpers
+// ===========================
+
+/**
+ * Formats bytes into a human-readable string.
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 MB")
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 bytes";
+  if (bytes < 1024) return `${bytes} bytes`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+/**
+ * Type guard to check if an error is an upload error.
+ */
+export function isUploadError(error: unknown): error is UploadError {
+  return error instanceof UploadError;
+}