@sudobility/types 1.9.55 → 1.9.56

package/README.md

@@ -1,310 +1,74 @@
-# @johnqh/types
+# @sudobility/types
 
-[![npm version](https://badge.fury.io/js/@johnqh%2Ftypes.svg)](https://badge.fury.io/js/@johnqh%2Ftypes)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Comprehensive TypeScript type definitions and utilities for Web3 email applications. Zero runtime dependencies, dual module support (ESM + CommonJS).
 
-**Comprehensive TypeScript type definitions and utilities for Web3 email applications.**
-
-## 🚀 Overview
-
-This package provides a complete type-safe foundation for Web3 email applications, featuring:
-
-- **267 comprehensive tests** ensuring type reliability
-- **Zero runtime dependencies** for optimal performance
-- **Dual module support** (ESM + CommonJS)
-- **Complete TypeScript coverage** with strict type checking
-- **AI-friendly documentation** for enhanced development experience
-
-## 📦 Features
-
-### Core Type System
-- **Business Logic Types**: Email, User, WalletData, MailBox interfaces
-- **Blockchain Types**: Multi-chain support (Ethereum, Solana, Polygon, etc.)
-- **API Types**: Complete request/response type definitions
-- **Infrastructure Types**: Analytics, navigation, network client abstractions
-- **Utility Types**: `Optional<T>`, `Result<T, E>`, `ValidationResult<T>`
-
-### Utilities & Helpers
-- **Address Validation**: EVM, Solana, ENS, SNS address validation
-- **Blockchain Utilities**: Network configuration, chain detection, event helpers
-- **Formatting**: Date, currency, string formatting utilities
-- **Validation**: Type guards, schema validation, Web3 username validation
-- **URL Management**: Type-safe URL parameter handling
-
-### Development Features
-- **Tree Shakeable**: Import only what you need
-- **Framework Agnostic**: Works with React, Vue, Node.js, React Native
-- **Zero Config**: Ready to use out of the box
-- **Type-Safe**: Complete IntelliSense support
-
-## 🛠 Installation
+## Installation
 
 ```bash
-npm install @johnqh/types
+bun install @sudobility/types
 ```
 
-## 📖 Usage Examples
-
-### Basic Types
-```typescript
-import {
-  Email,
-  User,
-  WalletUserData,
-  AuthStatus,
-  ChainType,
-  Optional
-} from '@johnqh/types';
-
-// Email handling
-const email: Email = {
-  from: 'sender@example.com',
-  to: 'recipient@example.com',
-  subject: 'Web3 Email',
-  body: 'Hello from the blockchain!',
-  id: 'msg_123',
-  timestamp: Date.now(),
-  read: false
-};
+No peer dependencies required.
 
-// User management with optional fields
-const user: WalletUserData = {
-  walletAddress: '0x742d35Cc6634C0532925a3b8D2C36B7f12345678',
-  chainType: ChainType.EVM,
-  emails: [email],
-  folders: []
-};
+## Usage
 
-// Optional type usage
-const maybeUser: Optional<User> = null; // T | undefined | null
-```
+### Core Utility Types
 
-### Blockchain Integration
 ```typescript
-import {
-  Message,
-  TransactionResult,
-  MessageType,
-  isEvmAddress,
-  isSolanaAddress
-} from '@johnqh/types';
+import { Optional, Result, ValidationResult, BaseResponse, PaginatedResponse } from '@sudobility/types';
 
-// Multi-chain message
-const message: Message = {
-  from: '0x742d35Cc6634C0532925a3b8D2C36B7f12345678',
-  to: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
-  subject: 'Cross-chain message',
-  body: 'EVM to Solana communication',
-  timestamp: Date.now(),
-  txHash: '0x123abc...',
-  messageType: MessageType.PRIORITY
-};
+const maybeUser: Optional<User> = null;  // T | undefined | null
 
-// Address validation
-const evmValid = isEvmAddress('0x742d35Cc6634C0532925a3b8D2C36B7f12345678'); // true
-const solanaValid = isSolanaAddress('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'); // true
+function doWork(): Result<Data> {
+  if (ok) return { success: true, data: result };
+  return { success: false, error: { type: 'ValidationError', message: '...' } };
+}
 ```
 
-### API Integration
-```typescript
-import {
-  ApiResponse,
-  ValidationResult,
-  IndexerApiResponse,
-  Result
-} from '@johnqh/types';
-
-// Type-safe API responses
-const apiResponse: ApiResponse<User> = {
-  success: true,
-  data: user,
-  timestamp: new Date().toISOString()
-};
-
-// Result pattern for error handling
-const validateUser = (data: unknown): Result<User> => {
-  // Validation logic...
-  return { success: true, data: user as User };
-};
-```
+### Blockchain Types
 
-### Utilities
 ```typescript
-import {
-  formatWalletAddress,
-  parseEmailAddress,
-  createMultiChainId,
-  Web3UsernameValidator
-} from '@johnqh/types';
-
-// Address formatting
-const formatted = formatWalletAddress('0x742d35Cc6634C0532925a3b8D2C36B7f12345678');
-// Result: "0x742d...5678"
-
-// Email parsing
-const parsed = parseEmailAddress('user@domain.eth');
-// Result: { address: 'user', domain: 'domain.eth', type: AddressType.ENSName }
-
-// Multi-chain ID generation
-const id = createMultiChainId(1, '0x123...', 0);
-// Result: "1-0x123...-0"
-
-// Web3 username validation
-const validation = Web3UsernameValidator.validate('vitalik.eth');
-// Result: { name: 'vitalik.eth', address: null, chainType: ChainType.EVM }
-```
-
-## 🏗 Project Structure
-
-```
-src/
-├── types/                    # Type definitions by domain
-│   ├── indexer/             # Indexer API request/response types
-│   ├── blockchain/          # Web3 and blockchain types
-│   ├── business/            # Core business logic types
-│   ├── common.ts            # Shared utility types (Optional<T>, Result<T>)
-│   ├── config/              # Configuration types
-│   └── infrastructure/      # Infrastructure abstractions
-├── utils/                   # Pure utility functions
-│   ├── auth/                # Authentication utilities
-│   ├── blockchain/          # Blockchain utilities
-│   ├── constants/           # Shared constants
-│   ├── formatting/          # Formatting utilities
-│   ├── logging/             # Logging utilities
-│   ├── url/                 # URL utilities
-│   └── validation/          # Validation utilities
-├── wildduck-requests.ts     # WildDuck email server types
-└── index.ts                 # Main exports
-```
-
-## 🧪 Development
-
-### Available Scripts
-```bash
-# Development
-npm run build          # Build both ESM and CommonJS
-npm run dev            # Watch mode development
-npm test               # Run all 267 tests
-npm run test:watch     # Watch mode testing
-npm run test:coverage  # Generate coverage report
+import { isEvmAddress, isSolanaAddress, formatWalletAddress, ChainType } from '@sudobility/types';
 
-# Quality Assurance
-npm run lint           # ESLint checking
-npm run lint:fix       # Fix linting issues
-npm run format         # Format with Prettier
-npm run typecheck      # TypeScript type checking
-npm run verify         # Complete verification pipeline
-
-# AI Development Tools
-npm run ai:analyze     # Analyze type structure
-npm run ai:validate    # Validate exports
-npm run ai:docs        # Generate AI documentation
+isEvmAddress('0x742d35Cc6634C0532925a3b8D2C36B7f12345678');  // true
+isSolanaAddress('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM');  // true
+formatWalletAddress('0x742d35Cc6634C0532925a3b8D2C36B7f12345678');  // "0x742d...5678"
 ```
 
-### Quality Standards
-- **100% TypeScript**: Strict mode enabled with comprehensive coverage
-- **267 Tests**: Complete test suite with Vitest
-- **Zero Lint Errors**: ESLint v9 with flat config
-- **Perfect Formatting**: Prettier integration
-- **Dual Module Support**: ESM + CommonJS builds
-
-## 🤖 AI Development Optimization
-
-This project is optimized for AI-assisted development with:
-
-### Enhanced Documentation
-- **Comprehensive JSDoc comments** on all public APIs
-- **Usage examples** for common patterns
-- **Type relationships** clearly documented
-- **Change logs** with migration guides
-
-### AI-Friendly Patterns
-- **Consistent naming conventions** across all types
-- **Semantic type organization** by domain
-- **Clear export patterns** with barrel exports
-- **Utility type composition** for complex scenarios
-
-### Development Support
-- **CLAUDE.md** with project-specific instructions
-- **TYPE_CHANGES.md** documenting all type evolution
-- **AI analysis scripts** for type validation
-- **Comprehensive test coverage** for validation
-
-## 📚 Key Type Categories
-
-### Core Business Types
-- `Email`, `User`, `WalletUserData` - Core application entities
-- `MailBox`, `Folder` - Email organization structures
-- `AuthStatus`, `ConnectionState` - Authentication states
-
-### Blockchain Types
-- `Message`, `PreparedMessage` - Multi-chain messaging
-- `TransactionResult`, `TransactionStatus` - Transaction handling
-- `NetworkConfig`, `DeploymentAddresses` - Network configuration
-
-### Utility Types
-- `Optional<T>` - Null/undefined safe typing
-- `Result<T, E>` - Error handling patterns
-- `ValidationResult<T>` - Validation patterns
-- `PaginatedResponse<T>` - API pagination
+### Enums
 
-### Infrastructure Types
-- `AnalyticsService` - Analytics abstraction
-- `NetworkClient` - HTTP client interface
-- `UINavigationService` - Navigation abstraction
+Key enums: `AuthStatus`, `Chain` (60+ chains), `ChainType`, `ConnectionState`, `Theme`, `EmailAction`, `RequestStatus`, `WalletType`, `EntityType`, `EntityRole`, and more.
 
-## 🔧 Configuration
+### Import Paths
 
-### TypeScript Config
-The package is built with strict TypeScript settings:
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true
-  }
-}
-```
-
-### Import Patterns
 ```typescript
-// Main exports
-import { Email, User, Optional } from '@johnqh/types';
-
-// Specific modules (tree-shakeable)
-import { ChainType } from '@johnqh/types/enums';
-import { ValidationResponse } from '@johnqh/types/indexer';
-
-// Utilities
-import { formatWalletAddress } from '@johnqh/types/utils';
+import { ... } from '@sudobility/types';        // Full library
+import { ... } from '@sudobility/types/api';     // Indexer response types
+import { ... } from '@sudobility/types/enums';   // Business enums only
 ```
 
-## 🔄 Recent Updates (v1.6.2)
+## Development
 
-- ✅ **Optional<T> Consistency**: Standardized optional type usage
-- ✅ **Enhanced Type Safety**: Replaced `any` with `unknown` throughout
-- ✅ **Improved Documentation**: Comprehensive JSDoc coverage
-- ✅ **Better AI Support**: Enhanced for AI-assisted development
-- ✅ **Performance**: Zero runtime dependencies maintained
-
-## 🤝 Contributing
-
-This project follows strict quality standards:
-
-1. **All types must have JSDoc documentation**
-2. **Comprehensive tests required for utilities**
-3. **Zero external runtime dependencies**
-4. **Backward compatibility maintained**
-5. **AI-friendly code patterns**
-
-## 📄 License
+```bash
+bun install
+bun run build          # Build dual ESM + CJS output
+bun run dev            # Watch mode
+bun test               # Run tests (Vitest)
+bun run typecheck      # TypeScript check
+bun run lint           # ESLint (flat config)
+bun run format         # Prettier
+bun run verify         # Full pipeline: typecheck + lint + test + build
+```
 
-MIT © Sudobility
+## Key Exports
 
----
+- **Types**: `Optional<T>`, `Result<T,E>`, `ValidationResult<T>`, `BaseResponse<T>`, `PaginatedResponse<T>`, `UnifiedError`
+- **Enums**: `AuthStatus`, `Chain`, `ChainType`, `ConnectionState`, `Theme`, `EmailAction`, `WalletType`, `EntityType`, `EntityRole`, and more
+- **Validators**: `isEvmAddress`, `isSolanaAddress`, `isENSName`, `isSNSName`, `Web3UsernameValidator`, `validateAddress`, `validateAmount`, type guards
+- **Formatters**: `formatWalletAddress`, `formatUSDC`, `formatEmailDate`, `formatRelativeTime`, `formatBytes`, `truncate`, `capitalize`, and more
+- **Async Helpers**: `safeAsync`, `withLoadingState`, `safeParallel`, `withTimeout`, `withCache`, `debounceAsync`
+- **Infrastructure**: `NetworkClient`, `AnalyticsService`, `UINavigationService`
 
-**Built with ❤️ for the Web3 email revolution**
+## License
 
-*This package powers the type-safe foundation for Web3-native email platforms.*
+BUSL-1.1