refactor: move types and errors out of core

Author: pirhoo

docs/.vitepress/config.mts

@@ -49,6 +49,7 @@ export default defineConfig({
           { text: 'Why Trotsky', link: '/guide/why' },
           { text: 'Features', link: '/guide/features' },
           { text: 'Code of Conduct', link: '/guide/code-of-conduct' },
+          { text: 'Architecture', link: '/guide/architecture' },
           { text: 'FAQ', link: '/guide/faq' },
         ]
       },

lib/config/TrotskyConfig.ts

@@ -0,0 +1,183 @@
+/**
+ * Configuration options for Trotsky instance.
+ *
+ * This module provides configuration interfaces and default values
+ * for customizing Trotsky's behavior.
+ *
+ * @module config
+ */
+
+/**
+ * Logging configuration options.
+ *
+ * @public
+ */
+export interface LoggingConfig {
+  /** Enable or disable logging */
+  enabled: boolean
+  /** Minimum log level to output */
+  level: "debug" | "info" | "warn" | "error"
+  /** Custom logger function (optional) */
+  logger?: (level: string, message: string, meta?: Record<string, unknown>) => void
+}
+
+/**
+ * Pagination configuration options.
+ *
+ * @public
+ */
+export interface PaginationConfig {
+  /** Default page size for paginated requests */
+  defaultLimit: number
+  /** Maximum page size allowed */
+  maxLimit: number
+  /** Enable automatic pagination */
+  autoPaginate: boolean
+}
+
+/**
+ * Retry configuration options.
+ *
+ * @public
+ */
+export interface RetryConfig {
+  /** Enable automatic retries on failure */
+  enabled: boolean
+  /** Maximum number of retry attempts */
+  maxAttempts: number
+  /** Backoff strategy for retries */
+  backoff: "linear" | "exponential"
+  /** Initial delay between retries (milliseconds) */
+  initialDelay: number
+  /** Maximum delay between retries (milliseconds) */
+  maxDelay: number
+  /** HTTP status codes that should trigger a retry */
+  retryableStatusCodes: number[]
+}
+
+/**
+ * Rate limiting configuration options.
+ *
+ * @public
+ */
+export interface RateLimitConfig {
+  /** Enable built-in rate limiting */
+  enabled: boolean
+  /** Maximum requests per minute */
+  requestsPerMinute: number
+  /** Maximum concurrent requests */
+  concurrentRequests: number
+  /** Behavior when rate limit is hit */
+  onLimitReached: "throw" | "queue" | "drop"
+}
+
+/**
+ * Caching configuration options.
+ *
+ * @public
+ */
+export interface CacheConfig {
+  /** Enable caching */
+  enabled: boolean
+  /** Default cache TTL in milliseconds */
+  defaultTTL: number
+  /** Maximum cache size (number of entries) */
+  maxSize: number
+  /** Cache key prefix */
+  keyPrefix: string
+}
+
+/**
+ * Complete Trotsky configuration.
+ *
+ * @public
+ */
+export interface TrotskyConfig {
+  /** Logging configuration */
+  logging: LoggingConfig
+  /** Pagination configuration */
+  pagination: PaginationConfig
+  /** Retry configuration */
+  retry: RetryConfig
+  /** Rate limiting configuration */
+  rateLimit: RateLimitConfig
+  /** Caching configuration */
+  cache: CacheConfig
+}
+
+/**
+ * Partial configuration allowing users to override specific options.
+ *
+ * @public
+ */
+export type PartialTrotskyConfig = {
+  [K in keyof TrotskyConfig]?: Partial<TrotskyConfig[K]>
+}
+
+/**
+ * Default configuration values.
+ *
+ * These values are used when no custom configuration is provided.
+ *
+ * @public
+ */
+export const defaultConfig: TrotskyConfig = {
+  logging: {
+    enabled: false,
+    level: "info"
+  },
+  pagination: {
+    defaultLimit: 50,
+    maxLimit: 100,
+    autoPaginate: true
+  },
+  retry: {
+    enabled: true,
+    maxAttempts: 3,
+    backoff: "exponential",
+    initialDelay: 1000,
+    maxDelay: 30000,
+    retryableStatusCodes: [408, 429, 500, 502, 503, 504]
+  },
+  rateLimit: {
+    enabled: false,
+    requestsPerMinute: 60,
+    concurrentRequests: 10,
+    onLimitReached: "queue"
+  },
+  cache: {
+    enabled: false,
+    defaultTTL: 60000, // 1 minute
+    maxSize: 1000,
+    keyPrefix: "trotsky:"
+  }
+}
+
+/**
+ * Merges partial configuration with default configuration.
+ *
+ * @param config - Partial configuration to merge
+ * @returns Complete configuration with defaults
+ *
+ * @example
+ * ```ts
+ * const config = mergeConfig({
+ *   logging: { enabled: true, level: "debug" }
+ * })
+ * ```
+ *
+ * @public
+ */
+export function mergeConfig (config?: PartialTrotskyConfig): TrotskyConfig {
+  if (!config) {
+    return { ...defaultConfig }
+  }
+
+  return {
+    logging: { ...defaultConfig.logging, ...config.logging },
+    pagination: { ...defaultConfig.pagination, ...config.pagination },
+    retry: { ...defaultConfig.retry, ...config.retry },
+    rateLimit: { ...defaultConfig.rateLimit, ...config.rateLimit },
+    cache: { ...defaultConfig.cache, ...config.cache }
+  }
+}

lib/config/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Central export point for Trotsky configuration.
+ *
+ * @module config
+ * @packageDocumentation
+ */
+
+export type {
+  LoggingConfig,
+  PaginationConfig,
+  RetryConfig,
+  RateLimitConfig,
+  CacheConfig,
+  TrotskyConfig,
+  PartialTrotskyConfig
+} from "./TrotskyConfig"
+
+export {
+  defaultConfig,
+  mergeConfig
+} from "./TrotskyConfig"

lib/errors/AuthenticationError.ts

@@ -0,0 +1,57 @@
+/**
+ * Error class for authentication and authorization failures.
+ *
+ * Thrown when authentication is required but missing, invalid,
+ * or when the user lacks permission for an operation.
+ *
+ * @example
+ * ```ts
+ * throw new AuthenticationError(
+ *   "Authentication required for this operation",
+ *   "AUTH_REQUIRED",
+ *   "StepActorFollow"
+ * )
+ * ```
+ *
+ * @public
+ */
+
+import { TrotskyError } from "./TrotskyError"
+
+export class AuthenticationError extends TrotskyError {
+  /**
+   * Creates a new AuthenticationError.
+   *
+   * @param message - Human-readable error message
+   * @param code - Machine-readable error code
+   * @param step - Optional step name where error occurred
+   * @param cause - Optional underlying error
+   */
+  constructor (
+    message: string,
+    code: string = "AUTH_ERROR",
+    step?: string,
+    cause?: Error
+  ) {
+    super(message, code, step, cause)
+    this.name = "AuthenticationError"
+  }
+}
+
+/**
+ * Common authentication error codes.
+ *
+ * @public
+ */
+export const AuthenticationErrorCode = {
+  /** Authentication is required but not provided */
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  /** Provided credentials are invalid */
+  INVALID_CREDENTIALS: "INVALID_CREDENTIALS",
+  /** Session has expired */
+  SESSION_EXPIRED: "SESSION_EXPIRED",
+  /** User lacks permission for this operation */
+  FORBIDDEN: "FORBIDDEN",
+  /** Agent is not authenticated */
+  NOT_AUTHENTICATED: "NOT_AUTHENTICATED"
+} as const

lib/errors/PaginationError.ts

@@ -0,0 +1,57 @@
+/**
+ * Error class for pagination-related failures.
+ *
+ * Thrown when pagination operations fail, such as invalid cursors,
+ * cursor expiration, or pagination API errors.
+ *
+ * @example
+ * ```ts
+ * throw new PaginationError(
+ *   "Invalid pagination cursor",
+ *   "INVALID_CURSOR",
+ *   "StepActorFollowers"
+ * )
+ * ```
+ *
+ * @public
+ */
+
+import { TrotskyError } from "./TrotskyError"
+
+export class PaginationError extends TrotskyError {
+  /**
+   * Creates a new PaginationError.
+   *
+   * @param message - Human-readable error message
+   * @param code - Machine-readable error code
+   * @param step - Optional step name where error occurred
+   * @param cause - Optional underlying error
+   */
+  constructor (
+    message: string,
+    code: string = "PAGINATION_ERROR",
+    step?: string,
+    cause?: Error
+  ) {
+    super(message, code, step, cause)
+    this.name = "PaginationError"
+  }
+}
+
+/**
+ * Common pagination error codes.
+ *
+ * @public
+ */
+export const PaginationErrorCode = {
+  /** Cursor is invalid or malformed */
+  INVALID_CURSOR: "INVALID_CURSOR",
+  /** Cursor has expired */
+  CURSOR_EXPIRED: "CURSOR_EXPIRED",
+  /** Failed to fetch next page */
+  FETCH_FAILED: "FETCH_FAILED",
+  /** Limit parameter is invalid */
+  INVALID_LIMIT: "INVALID_LIMIT",
+  /** No more pages available */
+  NO_MORE_PAGES: "NO_MORE_PAGES"
+} as const