@cakemail-org/cakemail-cli 1.7.0 → 2.0.0

package/docs/developer/AUTH.md

@@ -0,0 +1,204 @@
+# Authentication Guide
+
+## How Cakemail API Authentication Works
+
+Cakemail uses **OAuth 2.0 Password Grant** for authentication, not traditional API keys.
+
+### Authentication Flow
+
+```
+1. User provides email + password
+2. CLI sends POST /token with credentials (application/x-www-form-urlencoded)
+3. API returns: { access_token, refresh_token, expires_in }
+4. CLI uses access_token for subsequent requests (Bearer token)
+5. When access_token expires (401), CLI uses refresh_token to get new access_token
+6. If refresh fails, CLI re-authenticates with email/password
+```
+
+### Two Ways to Authenticate
+
+#### Option 1: Email + Password (Recommended for CLI)
+
+The CLI automatically handles token management:
+
+```bash
+export CAKEMAIL_EMAIL=your@email.com
+export CAKEMAIL_PASSWORD=your_password
+cakemail campaigns list
+```
+
+**What happens:**
+1. CLI calls `POST /token` with email/password
+2. Receives `access_token` and `refresh_token`
+3. Stores tokens in memory (not persisted)
+4. Uses `access_token` for all API requests
+5. Auto-refreshes when token expires
+
+#### Option 2: Pre-existing Access Token
+
+If you already have an access token (from another OAuth2 flow):
+
+```bash
+export CAKEMAIL_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+cakemail campaigns list
+```
+
+**Note:** This won't auto-refresh since there's no refresh token.
+
+## OAuth2 Token Request Format
+
+The `/token` endpoint requires `application/x-www-form-urlencoded` format:
+
+### Get Initial Token (Password Grant)
+```http
+POST /token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=password&username=user@example.com&password=secret123
+```
+
+Response:
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "def50200a1b2c3d4...",
+  "token_type": "bearer",
+  "expires_in": 3600
+}
+```
+
+### Refresh Token
+```http
+POST /token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token&refresh_token=def50200a1b2c3d4...
+```
+
+Response:
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "def50200e5f6g7h8...",
+  "token_type": "bearer",
+  "expires_in": 3600
+}
+```
+
+## Token Storage
+
+**Currently:** Tokens are stored in memory only (not persisted to disk)
+
+**Pros:**
+- More secure (tokens don't persist after CLI exits)
+- No file permission issues
+
+**Cons:**
+- Must re-authenticate on every CLI invocation
+- Slightly slower first request
+
+### Future: Token Persistence
+
+Could store tokens in `~/.cakemail/credentials.json`:
+
+```json
+{
+  "access_token": "...",
+  "refresh_token": "...",
+  "expires_at": "2025-10-08T20:00:00Z"
+}
+```
+
+This would:
+- Speed up CLI (no re-authentication)
+- Reduce API calls
+- Require secure file permissions (0600)
+
+## Multi-Factor Authentication (MFA)
+
+If account has MFA enabled, the `/token` endpoint returns:
+
+```json
+{
+  "challenge": "mfa-challenge-id-123"
+}
+```
+
+The CLI would need to:
+1. Detect the challenge response
+2. Prompt user for MFA code
+3. Call `POST /token/challenge` with code
+
+**Current Status:** MFA not yet implemented in CLI
+
+## Security Considerations
+
+### ✅ Current Implementation
+- Tokens stored in memory only
+- HTTPS enforced for all requests
+- Automatic token refresh
+- No plaintext tokens in logs
+
+### 🚧 Future Improvements
+- Token persistence with encryption
+- Token expiration checking before requests
+- MFA support
+- Token revocation on logout
+- Secure credential storage (OS keychain)
+
+## Environment Variables
+
+```bash
+# Primary authentication (auto OAuth2)
+CAKEMAIL_EMAIL=your@email.com
+CAKEMAIL_PASSWORD=your_password
+
+# Alternative: Use existing token
+CAKEMAIL_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# Optional: Override API base URL
+CAKEMAIL_API_BASE=https://api.cakemail.dev
+```
+
+## CLI Flags
+
+```bash
+# Override credentials via CLI
+cakemail --email user@example.com --password secret123 campaigns list
+
+# Use access token
+cakemail --access-token eyJhbGci... campaigns list
+
+# Flags take precedence over environment variables
+```
+
+## Debugging Authentication
+
+Enable verbose logging to see auth flow:
+
+```bash
+# Check if credentials are loaded
+cakemail --email test@example.com --password wrong_password campaigns list
+# Error: Authentication failed: ...
+
+# Success
+cakemail --email user@example.com --password correct_password campaigns list
+# (Makes POST /token, then GET /campaigns)
+```
+
+## Comparison: API Keys vs OAuth2 Tokens
+
+| Feature | Traditional API Keys | Cakemail OAuth2 Tokens |
+|---------|---------------------|------------------------|
+| **Format** | Long-lived static key | Short-lived JWT |
+| **Expiration** | Never (or very long) | 1 hour (configurable) |
+| **Refresh** | N/A | Yes, via refresh token |
+| **Scopes** | Often global | user/admin/internal |
+| **Revocation** | Manual | Automatic on refresh |
+| **Security** | Lower (if leaked) | Higher (expires quickly) |
+
+## Summary
+
+**There are NO traditional API keys in Cakemail.** The `CAKEMAIL_ACCESS_TOKEN` env var refers to an OAuth2 access token obtained from the `/token` endpoint.
+
+For CLI usage, **email + password** is the simplest approach - the CLI handles all token management automatically.

package/docs/developer/CONTRIBUTING.md

@@ -0,0 +1,227 @@
+# Contributing to Cakemail CLI
+
+Thank you for your interest in contributing to the Cakemail CLI! This document provides guidelines and instructions for contributing.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm
+- A Cakemail account for testing
+
+### Development Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/cakemail/cakemail-cli.git
+   cd cli
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Set up environment**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your test credentials
+   ```
+
+4. **Build the project**
+   ```bash
+   npm run build
+   ```
+
+5. **Test locally**
+   ```bash
+   npm start -- campaigns list
+   # or
+   node dist/cli.js campaigns list
+   ```
+
+## Development Workflow
+
+### Making Changes
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Write clean, readable code
+   - Follow existing code style and patterns
+   - Add TypeScript types for all new code
+
+3. **Build and test**
+   ```bash
+   npm run build
+   npm start -- <command> <args>
+   ```
+
+4. **Commit your changes**
+   ```bash
+   git add .
+   git commit -m "feat: add your feature description"
+   ```
+
+### Commit Message Guidelines
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `docs:` - Documentation changes
+- `chore:` - Maintenance tasks
+- `refactor:` - Code refactoring
+- `test:` - Test additions or changes
+
+Examples:
+```
+feat: add reports command for campaign analytics
+fix: correct sender confirmation flow
+docs: update README with new examples
+chore: update dependencies to latest versions
+```
+
+## Code Guidelines
+
+### TypeScript
+
+- Use TypeScript for all code
+- Provide types for all function parameters and return values
+- Avoid `any` type when possible
+
+### Code Style
+
+- Use 2 spaces for indentation
+- Use single quotes for strings
+- Add JSDoc comments for complex functions
+- Keep functions small and focused
+
+### Error Handling
+
+- Always handle errors gracefully
+- Provide clear, actionable error messages
+- Exit with appropriate exit codes (1 for errors)
+
+### Output
+
+- Use the `OutputFormatter` for all output
+- Support all three output formats: JSON, table, compact
+- Use `ora` spinners for long-running operations
+
+## Adding New Commands
+
+To add a new command category:
+
+1. **Create command file**: `src/commands/yourcommand.ts`
+
+2. **Follow the pattern**:
+   ```typescript
+   import { Command } from 'commander';
+   import { CakemailClient } from '../client.js';
+   import { OutputFormatter } from '../utils/output.js';
+   import ora from 'ora';
+
+   export function createYourCommand(client: CakemailClient, formatter: OutputFormatter): Command {
+     const cmd = new Command('yourcommand')
+       .description('Description of your command');
+
+     cmd
+       .command('list')
+       .description('List items')
+       .action(async (options) => {
+         const spinner = ora('Fetching...').start();
+         try {
+           const data = await client.sdk.yourService.list(options);
+           spinner.stop();
+           formatter.output(data);
+         } catch (error: any) {
+           spinner.stop();
+           formatter.error(error.message);
+           process.exit(1);
+         }
+       });
+
+     return cmd;
+   }
+   ```
+
+3. **Register in CLI**: Add to `src/cli.ts`
+   ```typescript
+   import { createYourCommand } from './commands/yourcommand.js';
+   // ...
+   program.addCommand(createYourCommand(client, formatter));
+   ```
+
+4. **Update documentation**:
+   - Add command to README.md
+   - Update API_COVERAGE.md
+
+## SDK Integration
+
+The CLI is built on the official [@cakemail-org/cakemail-sdk](https://www.npmjs.com/package/@cakemail-org/cakemail-sdk).
+
+- Always use SDK methods: `client.sdk.serviceName.method()`
+- Follow SDK 2.0 object-based API patterns
+- Wrap request bodies in `requestBody` property
+- Handle SDK errors appropriately
+
+Example:
+```typescript
+// SDK 2.0 pattern
+const data = await client.sdk.senderService.createSender({
+  requestBody: {
+    name: options.name,
+    email: options.email
+  }
+});
+```
+
+## Testing
+
+Currently, the CLI uses manual testing. Before submitting a PR:
+
+1. Test all affected commands
+2. Test with different output formats (`-f json`, `-f table`, `-f compact`)
+3. Test error cases (invalid IDs, missing params, etc.)
+4. Test with both email/password and access token authentication
+
+## Documentation
+
+- Update README.md for user-facing changes
+- Update API_COVERAGE.md for new commands
+- Add JSDoc comments for complex functions
+- Include usage examples in command descriptions
+
+## Pull Request Process
+
+1. **Before submitting**:
+   - Ensure code builds: `npm run build`
+   - Test thoroughly
+   - Update documentation
+   - Write clear commit messages
+
+2. **Submit PR**:
+   - Provide clear description of changes
+   - Reference any related issues
+   - List breaking changes (if any)
+   - Include testing steps
+
+3. **PR Review**:
+   - Address review feedback promptly
+   - Keep commits clean and focused
+   - Squash commits if requested
+
+## Questions or Issues?
+
+- **Bug reports**: Open an issue with reproduction steps
+- **Feature requests**: Open an issue describing the use case
+- **Questions**: Open a discussion or issue
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.