feat: add export functionality for web API with demo script
- Add export API endpoint POST /web/v1/accounts/export - Support two export modes: text (data strings) and object (full account objects) - Automatically set account status to 'exported' during export - Add comprehensive demo script that uploads, exports and verifies functionality - Update API documentation with export endpoint details - Add TypeScript types for export functionality 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
91
CLAUDE.md
Normal file
91
CLAUDE.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
# Development
|
||||
npm run dev # Start development server with tsx watch
|
||||
npm run build # Compile TypeScript to JavaScript
|
||||
npm start # Run the production build
|
||||
|
||||
# Database Operations
|
||||
npm run db:create # Create database if it doesn't exist
|
||||
npm run db:generate # Generate Drizzle migration files
|
||||
npm run db:migrate # Run database migrations
|
||||
npm run db:studio # Open Drizzle Studio (database management UI)
|
||||
npm run db:setup # One-command database setup (create + migrate)
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
This is a lightweight account management platform built with TypeScript, Fastify, and PostgreSQL. The system uses a **single table design** with the `accounts` table storing all account data.
|
||||
|
||||
### Core Design Principles
|
||||
- **Single Table Architecture**: All account data stored in one `accounts` table with proper indexing
|
||||
- **Dual API Design**: Separate optimized APIs for automation scripts (`/s/v1/`) and web management (`/web/v1/`)
|
||||
- **Concurrent Safety**: Account locking mechanism prevents simultaneous access to the same account
|
||||
- **Background Jobs**: Automatic cleanup of stale locks via scheduled tasks
|
||||
|
||||
### Key Components
|
||||
|
||||
**Database Layer** (`src/db/`):
|
||||
- `schema.ts`: Single accounts table with unique constraints on platform+customId
|
||||
- `index.ts`: PostgreSQL connection using Drizzle ORM
|
||||
|
||||
**Core Business Logic** (`src/core/AccountService.ts`):
|
||||
- Account acquisition with automatic locking
|
||||
- Status management and batch operations
|
||||
- Statistics generation and stale lock cleanup
|
||||
- All database operations are transactional where needed
|
||||
|
||||
**API Routes**:
|
||||
- `src/api/v1/script/actions.ts`: Lightweight script API for automation
|
||||
- `src/api/v1/web/accounts.ts`: Full-featured web management API
|
||||
- `src/api/v1/web/stats.ts`: Statistics and analytics endpoints
|
||||
|
||||
**Background Jobs** (`src/jobs/staleLockCleanup.ts`):
|
||||
- Automatic cleanup of accounts locked longer than `LOCK_TIMEOUT_MINUTES`
|
||||
|
||||
### Database Schema
|
||||
|
||||
The `accounts` table structure:
|
||||
- `id`: Primary key (serial)
|
||||
- `ownerId`: Account owner identifier
|
||||
- `platform`: Platform name (e.g., "twitter", "facebook")
|
||||
- `customId`: Custom identifier for the account
|
||||
- `data`: JSON data storage for account information
|
||||
- `status`: Current status ("available", "locked", "failed", etc.)
|
||||
- `notes`: Optional notes field
|
||||
- `lockedAt`: Timestamp when account was locked
|
||||
- Unique constraint: `platform + customId`
|
||||
- Indexes on: `ownerId + status`, `platform + ownerId`
|
||||
|
||||
### API Patterns
|
||||
|
||||
**Script API** (`/s/v1/{ownerId}/`): GET-based, optimized for automation
|
||||
- `GET /acquire?platform=X&count=N` - Get and lock accounts
|
||||
- `GET /update/{accountId}/{status}?notes=X` - Update account status
|
||||
- `POST /upload` - Bulk upload/update accounts
|
||||
|
||||
**Web API** (`/web/v1/`): POST-based with rich payloads
|
||||
- `POST /accounts/list` - Complex filtering, pagination, sorting
|
||||
- `POST /accounts/delete-batch` - Bulk delete operations
|
||||
- `POST /accounts/update-batch` - Bulk update operations
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
Required environment variables (see `.env.example`):
|
||||
- `DATABASE_URL`: PostgreSQL connection string
|
||||
- `PORT`: Server port (default: 3000)
|
||||
- `NODE_ENV`: Environment mode
|
||||
- `LOCK_TIMEOUT_MINUTES`: Lock timeout duration (default: 5 minutes)
|
||||
|
||||
### Development Notes
|
||||
|
||||
- The application uses Fastify with full CORS enabled
|
||||
- Graceful shutdown handling for SIGTERM/SIGINT
|
||||
- Structured logging with different levels for dev/prod
|
||||
- Health check endpoint at `/health`
|
||||
- All API responses use standardized format from `lib/apiResponse.ts`
|
||||
Reference in New Issue
Block a user