collectlie

# Development Guide This guide provides technical details for contributors and developers working on the collectlie. ## Project Overview This is an ultra-minimal TypeScript SDK package for user submission platform. The SDK has only one method - `submit()` - and is designed to be universal, working in React, vanilla JavaScript, Node.js, and any JavaScript environment with a headless approach where developers control the UI. ## Architecture The codebase follows a modular architecture with clear separation of concerns: ### Core SDK Layer (`src/core/`) - **`Collectlie.ts`** - Main SDK class with single method: `submit()` - **`http-client.ts`** - HTTP wrapper with structured error handling - **`utils.ts`** - Validation, data enrichment, and utility functions ### Type System (`src/types/`) - **`feedback.ts`** - Core submission data types and legacy feedback interfaces - **`api.ts`** - API response types and pagination interfaces - **`config.ts`** - SDK configuration and request types ### Package Exports (`src/index.ts`) - Main entry point exporting `Collectlie` and submission types - Legacy exports for backward compatibility ## Build System The package uses Rollup to generate multiple output formats: - **CJS**: `dist/index.js` - CommonJS for Node.js - **ESM**: `dist/index.esm.js` - ES modules for modern bundlers - **UMD**: `dist/index.umd.js` - Universal module for CDN usage TypeScript definitions are generated for all outputs with source maps. ## Development Commands ### Build and Development ```bash # Build all package formats (required after code changes) npm run build # Build in watch mode for active development npm run dev # Run TypeScript compiler without emitting files npm run type-check ``` ### Quality Assurance ```bash # Run Jest test suite npm run test # Run tests in watch mode npm run test:watch # Lint TypeScript files npm run lint # Auto-fix linting issues npm run lint:fix ``` ### Local Testing Setup ```bash # In SDK directory npm link # In target project npm link collectlie ``` ## Key Implementation Details ### HTTP Client Built with fetch API and Supabase client, includes: - Structured error handling - Smart routing: Supabase client for JSON, fetch for files - Works in both browser and Node.js environments ### Type Safety - All API endpoints expect specific interfaces - Client-side data validation before transmission - Comprehensive TypeScript definitions for consumers - Full type coverage for all public APIs ### Package Structure Uses package.json exports field to provide clean import paths: - `collectlie` - Core SDK ### Configuration SDK accepts configurable: - Validation options - Environment variable detection ### Environment Variable Detection The SDK automatically detects credentials from environment variables with priority: 1. **Universal variables** (recommended): - `COLLECTLIE_PROJECT_ID` - `COLLECTLIE_API_KEY` 2. **Framework-specific fallbacks**: - React: `REACT_APP_COLLECTLIE_*` - Next.js: `NEXT_PUBLIC_COLLECTLIE_*` - Vite: `VITE_COLLECTLIE_*` ### Browser Compatibility The SDK includes safe environment detection: ```typescript try { if (typeof process !== 'undefined' && process?.env) { // Node.js environment variables } } catch { // Browser environment - process not defined } ``` ### Response Format The SDK preserves backend response format: ```typescript // Backend returns: { success: boolean, data: any, message?: string } // SDK returns this directly to maintain consistency return data as ApiResponse<T>; ``` ## Testing Notes ### Test Structure ``` tests/ ├── __mocks__/ # HTTP fetch mocking utilities ├── __fixtures__/ # Predefined test data sets ├── utils/ # Test helper utilities ├── config.test.ts # Configuration validation tests ├── submit.test.ts # Core submit() method tests ├── validation.test.ts # Data validation tests ├── http.test.ts # HTTP client tests ├── extensibility.test.ts # Future feature tests ├── integration.test.ts # End-to-end tests └── setup.ts # Jest setup and global mocks ``` ### Jest Configuration The package includes Jest configuration with: - jsdom environment for testing DOM APIs - Global fetch mocking - TypeScript compilation - Source map support ### Test Commands ```bash # Run all tests npm test # Run tests in watch mode npm run test:watch # Generate coverage report npm run test:coverage # Run real API tests (requires .env setup) npm run test:real ``` ## Release Process 1. **Version Update**: Update version in `package.json` 2. **Build**: Run `npm run build` to generate dist files 3. **Test**: Run `npm test` to ensure all tests pass 4. **Type Check**: Run `npm run type-check` to verify TypeScript 5. **Lint**: Run `npm run lint` to check code style 6. **Publish**: Run `npm publish` to release ### Pre-publish Checklist - [ ] All tests passing (`npm test`) - [ ] TypeScript compiles without errors (`npm run type-check`) - [ ] No linting issues (`npm run lint`) - [ ] Documentation updated - [ ] Version number incremented - [ ] Dist files generated (`npm run build`) ## Contributing Guidelines ### Code Style - Use TypeScript for all new code - Follow existing naming conventions - Add JSDoc comments for public APIs - Include unit tests for new functionality ### Pull Request Process 1. Fork the repository 2. Create feature branch from `main` 3. Write tests for new functionality 4. Ensure all tests pass 5. Update documentation if needed 6. Submit pull request with clear description ### Architecture Principles 1. **Ultra-minimal**: Keep the SDK focused on core functionality 2. **Universal**: Ensure compatibility across all JavaScript environments 3. **Type-safe**: Maintain comprehensive TypeScript coverage 4. **Zero dependencies**: Avoid external dependencies in production builds 5. **Error resilient**: Provide clear error messages and graceful failure modes ## File Structure Deep Dive ``` src/ ├── core/ │ ├── Collectlie.ts # Main SDK class │ │ ├── constructor() # Initialize with config │ │ └── submit() # Single submission method │ ├── http-client.ts # HTTP abstraction layer │ │ ├── HttpClient # Main HTTP client class │ │ ├── makeRequest() # Core request method │ │ ├── submitWithFiles() # File upload handling │ │ └── submitSubmission() # Supabase integration │ └── utils.ts # Utility functions │ ├── getEnvironmentVariables() # Env var detection │ ├── validateSubmissionData() # Data validation │ ├── gatherBrowserInfo() # Browser data helper │ ├── gatherDeviceInfo() # Device data helper │ ├── gatherPerformanceInfo() # Performance data helper │ └── sanitizeMetadata() # Metadata cleanup ├── types/ │ ├── feedback.ts # Core data interfaces │ ├── api.ts # API response types │ └── config.ts # Configuration types └── index.ts # Package entry point ``` ## Performance Considerations ### Bundle Size Optimization - Tree-shaking friendly exports - No external dependencies in production - Minimal API surface area - Optimized TypeScript compilation ### Runtime Performance - Lazy initialization where possible - Efficient error handling - Minimal memory footprint - Fast startup time ## Security Considerations ### API Key Handling - Environment variable detection - No API keys in client-side bundles (when using env vars) - Secure transmission over HTTPS - Clear error messages without exposing sensitive data ### Data Validation - No client-side validation (maximum user freedom) - Server-side validation at API level - Sanitization of custom fields - Protection against XSS in metadata ## Troubleshooting ### Common Development Issues **Build Failures** ```bash # Clear build cache rm -rf dist/ npm run build ``` **TypeScript Errors** ```bash # Check types without building npm run type-check ``` **Test Failures** ```bash # Run tests with verbose output npm test -- --verbose ``` ### Environment Issues **Environment Variables Not Detected** - Check your bundler's environment variable patterns - Verify `.env` file location - Ensure proper variable naming (e.g., `VITE_*` for Vite) **API Connection Issues** - Verify API key format (must start with `proj_`) - Check project ID is correct - Ensure network connectivity - Review rate limiting settings ## Future Development ### Planned Features - Enhanced error reporting - Additional validation options - Performance monitoring hooks - Extended TypeScript utilities ### Architecture Evolution The SDK maintains backward compatibility while evolving: - New features added as optional parameters - Breaking changes only in major versions - Deprecation warnings for removed features - Clear migration guides for version upgrades When making changes, always run `npm run build` before testing in linked projects, as the dist files are what get consumed by other applications.