refactor: Add types, errors, config modules and architecture documentation

[pirhoo]

Summary

This PR implements foundational improvements to the Trotsky codebase, adding new organizational modules and comprehensive architecture documentation. These changes establish a solid foundation for future development without breaking any existing functionality.

What's New

1. Type Definitions Module (lib/types/)

• Centralized type definitions for actors, posts, lists, and pagination
• Single source of truth for common types
• Improved type reusability and consistency
• Better TypeScript performance through shared types

2. Custom Error Classes (lib/errors/)

• TrotskyError - Base error class with error codes, step context, and timestamps
• PaginationError - Pagination-specific failures
• AuthenticationError - Auth and permission failures
• RateLimitError - Rate limit handling with retry information
• ValidationError - Input validation failures with detailed context
• Helper functions: isTrotskyError(), fromXRPCError()

3. Configuration System (lib/config/)

• Complete configuration interface for future customization
• Logging, pagination, retry, rate limiting, and caching configs
• Sensible defaults with mergeConfig() helper
• Type-safe configuration options

4. Architecture Documentation (docs/guide/architecture.md)

• Comprehensive guide to Trotsky's internal architecture
• Core concepts and design patterns explained
• Component organization and data flow diagrams
• Extensibility guidelines and best practices
• Contributing guidelines for new developers

Key Benefits

✅ Better Organization - Clear separation of concerns with dedicated modules
✅ Type Safety - Centralized, reusable type definitions
✅ Error Handling - Structured error classes with rich context
✅ Future-Ready - Configuration system ready for advanced features
✅ Developer Experience - Comprehensive architecture documentation
✅ No Breaking Changes - All additions are opt-in and backward compatible

Files Changed

New Modules:

• 5 type definition files (lib/types/)
• 5 error class files (lib/errors/)
• 2 configuration files (lib/config/)
• 1 architecture guide (docs/guide/architecture.md)

Total: 15 new files, 1,413 lines added

Code Examples

Using Type Definitions:

import { ActorParam, PostUri, PaginationParams } from 'trotsky/types'

function processActor(param: ActorParam) {
  // Type-safe actor parameter handling
}

Using Error Classes:

import { ValidationError, PaginationError } from 'trotsky/errors'

try {
  await trotsky.actor('invalid').run()
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Validation failed: ${error.code}`, error.details)
  } else if (error instanceof PaginationError) {
    console.error(`Pagination failed: ${error.code}`)
  }
}

Using Configuration (Future):

import { Trotsky } from 'trotsky'

const trotsky = Trotsky.init(agent, {
  logging: { enabled: true, level: 'debug' },
  rateLimit: { requestsPerMinute: 30 }
})

Testing

• ✅ Build completes successfully
• ✅ All new modules compile to dist/
• ✅ No breaking changes to existing code
• ✅ TypeScript types properly exported

Documentation

• Architecture guide added at docs/guide/architecture.md
• All new code includes comprehensive JSDoc comments
• Type definitions include usage examples
• Error classes documented with error codes

Next Steps

These foundational modules enable future improvements:

1. Integrate error classes into existing error handling
2. Add configuration support to Trotsky.init()
3. Migrate existing inline types to centralized type definitions
4. Implement domain-based directory restructuring (Phase 2)

---

This PR establishes a stronger foundation for Trotsky's continued development while maintaining full backward compatibility.