collectlie/docs/README.md

TypeScript SDK for Collectlie - flexible data collection platform with custom types, schema validation, and Supabase backend integration

# Collectlie Documentation

Ultra-minimal TypeScript SDK for flexible user submission platform with Supabase backend integration.

## 📚 Documentation Overview

| Document | Description |
|----------|-------------|
| **[Getting Started](./getting-started.md)** | Installation, setup, and first submission |
| **[API Reference](./api-reference.md)** | Complete API documentation and interfaces |
| **[Testing Guide](./testing.md)** | Testing strategies and setup instructions |
| **[Development Guide](./development.md)** | Architecture and contribution guidelines |

## 🚀 Quick Navigation

### Core Features
- 🎯 **Ultra-minimal**: Only one method - `submit()`
- 🌐 **Universal**: Works in React, vanilla JS, Node.js, any JavaScript environment
- 🔒 **Secure**: Built-in API key authentication with environment variable support
- 🎛️ **Headless**: You control the UI, we handle the data submission
- ⚡ **TypeScript First**: Full type safety and excellent developer experience

### Examples by Framework

| Framework | Guide | Live Example |
|-----------|-------|--------------|
| **[Vanilla JavaScript](./examples/vanilla-js.md)** | HTML forms, CDN usage | [→ Code](./examples/vanilla-js.md#complete-example) |
| **[React](./examples/react.md)** | Hooks, components, state management | [→ Code](./examples/react.md#feedback-form-component) |
| **[Node.js](./examples/nodejs.md)** | Server-side submissions, API integration | [→ Code](./examples/nodejs.md#basic-server-submission) |
| **[TypeScript](./examples/typescript.md)** | Type safety, custom interfaces | [→ Code](./examples/typescript.md#custom-submission-types) |

### Advanced Topics

| Topic | Description |
|-------|-------------|
| **[Error Handling](./advanced/error-handling.md)** | Comprehensive error handling strategies |
| **[Configuration](./advanced/configuration.md)** | Advanced SDK configuration options |
| **[Best Practices](./advanced/best-practices.md)** | Production patterns and recommendations |

## 🎯 Quick Start

```bash
npm install collectlie
```

```javascript
import { Collectlie } from 'collectlie';

const sdk = new Collectlie();

await sdk.submit({
  type: 'issue',
  title: 'Bug Report',
  content: 'Found a bug in the checkout process'
});
```

**[→ Full Getting Started Guide](./getting-started.md)**

## 🔧 Environment Setup

```bash
# .env file
COLLECTLIE_PROJECT_ID=your_project_id_here
COLLECTLIE_API_KEY=proj_your_api_key_here
```

The SDK automatically detects environment variables across different platforms:
- **Node.js**: `COLLECTLIE_*`
- **Vite**: `VITE_COLLECTLIE_*`  
- **React**: `REACT_APP_COLLECTLIE_*`
- **Next.js**: `NEXT_PUBLIC_COLLECTLIE_*`

## 📖 API Overview

### Collectlie Class

The ultra-minimal SDK has only one method:

```typescript
class Collectlie {
  constructor(config?: CollectlieConfig)
  
  // The only method - submit user data
  async submit(data: SubmissionData): Promise<SubmissionApiResponse>
}
```

**[→ Complete API Reference](./api-reference.md)**

## 🏗️ Architecture

```
src/
├── core/
│   ├── Collectlie.ts    # Main SDK class (only submit method)
│   ├── http-client.ts      # HTTP wrapper with retry logic
│   └── utils.ts           # Validation and utilities
├── types/
│   ├── feedback.ts        # Core submission data types
│   ├── api.ts            # API response types
│   └── config.ts         # SDK configuration types
└── index.ts              # Package exports
```

**[→ Development Guide](./development.md)**

## 🧪 Testing

```bash
# Run the simple test runner
node test-runner.js

# Run Jest test suite
npm test

# Test with real API
npm run test:real
```

**[→ Testing Guide](./testing.md)**

## 🌐 Platform Support

- **Browsers**: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
- **Node.js**: 16+ (ES2020+ support)
- **Frameworks**: React, Vue, Angular, Svelte, vanilla JS
- **Bundlers**: Webpack, Vite, Rollup, Parcel
- **Environments**: Web, Node.js, Electron, React Native

## 📦 Bundle Sizes

- **Ultra-minimal SDK**: ~3KB gzipped
- **Zero dependencies** in production builds

## 🆘 Support

- [GitHub Issues](https://github.com/collectlie/collectlie/issues)
- Check your `.env` file setup
- Verify API key starts with `proj_`
- Ensure project ID is correct

## 📄 License

MIT

---

**Need help?** Start with the **[Getting Started Guide](./getting-started.md)** or jump to the **[API Reference](./api-reference.md)** for detailed documentation.