@artu-ai/compliance-sdk 0.0.6 → 0.2.0

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;
+}

package/src/errors/validation.ts

@@ -0,0 +1,163 @@
+/**
+ * Validation error class
+ *
+ * Thrown when input validation fails, either client-side (Zod)
+ * or server-side (API validation).
+ */
+
+import type { ZodError } from "zod";
+import { ComplianceError } from "./base";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * A single validation issue
+ */
+export interface ValidationIssue {
+  /**
+   * Path to the field that failed validation.
+   * Example: ["addresses", "0", "postalCode"]
+   */
+  path: PropertyKey[];
+
+  /**
+   * Human-readable error message
+   */
+  message: string;
+
+  /**
+   * Validation rule that failed (optional)
+   */
+  code?: string;
+}
+
+// ===========================
+// Validation Error Class
+// ===========================
+
+/**
+ * Error thrown when input validation fails.
+ *
+ * Contains structured information about which fields failed
+ * and why, making it easy to display errors in forms.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.clients.create({ name: "" });
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     error.issues.forEach((issue) => {
+ *       console.log(`${issue.path.join(".")}: ${issue.message}`);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class ValidationError extends ComplianceError {
+  /**
+   * List of validation issues
+   */
+  public readonly issues: ValidationIssue[];
+
+  constructor(issues: ValidationIssue[], requestId?: string) {
+    const message = ValidationError.formatMessage(issues);
+    super(message, "VALIDATION_ERROR", {
+      requestId,
+      details: { issues },
+    });
+    this.name = "ValidationError";
+    this.issues = issues;
+  }
+
+  /**
+   * Creates a ValidationError from a Zod error.
+   *
+   * @param error - Zod validation error
+   * @param requestId - Optional request ID for tracing
+   * @returns ValidationError with formatted issues
+   */
+  static fromZodError(error: ZodError, requestId?: string): ValidationError {
+    const issues: ValidationIssue[] = error.issues.map((issue) => ({
+      path: issue.path,
+      message: issue.message,
+      code: issue.code,
+    }));
+    return new ValidationError(issues, requestId);
+  }
+
+  /**
+   * Gets validation errors for a specific field path.
+   *
+   * @param path - Field path (e.g., "name" or "addresses.0.city")
+   * @returns Array of error messages for the field
+   *
+   * @example
+   * ```typescript
+   * const nameErrors = error.getFieldErrors("name");
+   * // ["Name is required", "Name must be at least 2 characters"]
+   * ```
+   */
+  getFieldErrors(path: string): string[] {
+    const pathParts = path.split(".");
+    return this.issues
+      .filter((issue) => {
+        if (issue.path.length !== pathParts.length) return false;
+        return pathParts.every((part, i) => String(issue.path[i]) === part);
+      })
+      .map((issue) => issue.message);
+  }
+
+  /**
+   * Checks if a specific field has validation errors.
+   *
+   * @param path - Field path to check
+   * @returns True if the field has errors
+   */
+  hasFieldError(path: string): boolean {
+    return this.getFieldErrors(path).length > 0;
+  }
+
+  /**
+   * Gets a flat object of field paths to error messages.
+   * Useful for form libraries.
+   *
+   * @returns Object mapping field paths to error messages
+   *
+   * @example
+   * ```typescript
+   * const fieldErrors = error.toFieldErrors();
+   * // { "name": "Name is required", "email": "Invalid email" }
+   * ```
+   */
+  toFieldErrors(): Record<string, string> {
+    const errors: Record<string, string> = {};
+    for (const issue of this.issues) {
+      const path = issue.path.join(".");
+      // Only keep first error per field
+      if (!errors[path]) {
+        errors[path] = issue.message;
+      }
+    }
+    return errors;
+  }
+
+  /**
+   * Formats the validation issues into a human-readable message.
+   */
+  private static formatMessage(issues: ValidationIssue[]): string {
+    if (issues.length === 0) {
+      return "Validation failed";
+    }
+    if (issues.length === 1) {
+      const [issue] = issues;
+      if (issue) {
+        const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `Validation failed: ${path}${issue.message}`;
+      }
+    }
+    return `Validation failed with ${issues.length} errors`;
+  }
+}

package/src/exports/base.ts

@@ -0,0 +1,139 @@
+/**
+ * Base exports shared across all entry points
+ *
+ * @internal - Not meant for direct import by users
+ */
+
+// ===========================
+// Errors
+// ===========================
+
+export {
+  ComplianceError,
+  type ComplianceErrorOptions,
+  type ComplianceErrorJSON,
+  ValidationError,
+  type ValidationIssue,
+  APIError,
+  NotFoundError,
+  UnauthorizedError,
+  ForbiddenError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
+  UploadError,
+  FileTooLargeError,
+  UploadTimeoutError,
+  InvalidFileTypeError,
+  UploadAbortedError,
+  UploadUrlExpiredError,
+  mapTRPCError,
+  isAPIError,
+  isUploadError,
+  type UploadStage,
+} from "../errors";
+
+// ===========================
+// Utilities
+// ===========================
+
+export {
+  collectAll,
+  collectUpTo,
+  getFirst,
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  contains,
+  startsWith,
+  endsWith,
+  equals,
+  notEquals,
+  oneOf,
+  notOneOf,
+  dateRange,
+  after,
+  before,
+  onOrAfter,
+  onOrBefore,
+  numberRange,
+  greaterThan,
+  lessThan,
+  atLeast,
+  atMost,
+  isTrue,
+  isFalse,
+  isNull,
+  isNotNull,
+  type Environment,
+} from "../utils";
+
+// ===========================
+// Session Types (for SDK.session() method)
+// ===========================
+
+export type {
+  SDKSessionOptions,
+  SDKSessionOptionsWithReturnTo,
+  SessionResult,
+  SessionResultWithRedirect,
+  SessionResultWithoutRedirect,
+  SessionResultAuthenticated,
+  SessionResultUnauthenticatedWithRedirect,
+  SessionResultUnauthenticatedNoRedirect,
+  SessionInfo,
+} from "../utils";
+
+// ===========================
+// Base Models (non-scoped entities)
+// ===========================
+
+export {
+  Address,
+  type AddressData,
+  ContactMethod,
+  type ContactMethodData,
+  Document,
+  type DocumentData,
+} from "../models";
+
+// ===========================
+// Base Resources (non-scoped entities)
+// ===========================
+
+export {
+  AddressesResource,
+  ContactMethodsResource,
+  DocumentsResource,
+} from "../resources";
+
+// ===========================
+// Shared Types from Shared Package
+// ===========================
+
+export type {
+  // Address types (non-scoped)
+  CreateAddressInput,
+  UpdateAddressInput,
+  // Contact method types (non-scoped)
+  CreateContactMethodInput,
+  UpdateContactMethodInput,
+  // Document types (non-scoped)
+  CreateDocumentInput,
+  UpdateDocumentInput,
+  // Pagination
+  PaginationInput,
+  PaginatedResponse,
+  PaginationMeta,
+  ListOptions,
+  IterateOptions,
+  // Filters
+  ClientFilter,
+  TransactionFilter,
+  DocumentFilter,
+  BankAccountFilter,
+  // API error responses
+  APIError as APIErrorResponse,
+  APIValidationError as APIValidationErrorResponse,
+  BatchResult,
+} from "@artu-ai/shared";