240 lines
5.1 KiB
Markdown
240 lines
5.1 KiB
Markdown
# TalkCody Agent Marketplace API
|
|
|
|
The backend API service for TalkCody Agent Marketplace, built with Hono, Bun, and Drizzle ORM.
|
|
|
|
## Tech Stack
|
|
|
|
- **Runtime**: Bun
|
|
- **Framework**: Hono
|
|
- **Database**: Neon (Serverless PostgreSQL)
|
|
- **ORM**: Drizzle
|
|
- **Authentication**: @hono/oauth-providers (GitHub, Google)
|
|
- **Validation**: Zod
|
|
- **JWT**: jose
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Bun >= 1.0.0
|
|
- Neon PostgreSQL database (free tier available)
|
|
- GitHub OAuth App credentials
|
|
- Google OAuth App credentials
|
|
|
|
### Setup
|
|
|
|
1. Install dependencies:
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
2. Copy environment variables:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. Fill in your `.env` file with actual values:
|
|
|
|
```env
|
|
DATABASE_URL=postgresql://user:password@host:5432/database
|
|
JWT_SECRET=your-secure-random-string
|
|
GITHUB_CLIENT_ID=your-github-app-id
|
|
GITHUB_CLIENT_SECRET=your-github-app-secret
|
|
GOOGLE_CLIENT_ID=your-google-app-id
|
|
GOOGLE_CLIENT_SECRET=your-google-app-secret
|
|
# Optional: explicit callback URL registered in Google Console
|
|
# Example: https://api.talkcody.com/api/auth/google
|
|
GOOGLE_REDIRECT_URI=
|
|
```
|
|
|
|
4. Generate database migrations:
|
|
|
|
```bash
|
|
bun run db:generate
|
|
```
|
|
|
|
5. Run migrations:
|
|
|
|
```bash
|
|
bun run db:migrate
|
|
```
|
|
|
|
6. Seed the database with initial data:
|
|
|
|
```bash
|
|
bun run db:seed
|
|
```
|
|
|
|
### Development
|
|
|
|
Run the development server with hot reload:
|
|
|
|
```bash
|
|
bun run dev
|
|
```
|
|
|
|
The API will be available at `http://localhost:3000`
|
|
|
|
### Testing
|
|
|
|
Run tests:
|
|
|
|
```bash
|
|
bun test
|
|
```
|
|
|
|
### Database Management
|
|
|
|
```bash
|
|
# Generate migrations from schema changes
|
|
bun run db:generate
|
|
|
|
# Run migrations
|
|
bun run db:migrate
|
|
|
|
# Push schema changes directly (dev only)
|
|
bun run db:push
|
|
|
|
# Open Drizzle Studio (database GUI)
|
|
bun run db:studio
|
|
|
|
# Seed database with initial data
|
|
bun run db:seed
|
|
```
|
|
|
|
### Building for Production
|
|
|
|
Build for Bun runtime:
|
|
|
|
```bash
|
|
bun run build
|
|
```
|
|
|
|
Build for Cloudflare Workers:
|
|
|
|
```bash
|
|
bun run build:cloudflare
|
|
```
|
|
|
|
### Deployment
|
|
|
|
#### Cloudflare Workers
|
|
|
|
1. Install Wrangler CLI:
|
|
|
|
```bash
|
|
bun install -g wrangler
|
|
```
|
|
|
|
2. Login to Cloudflare:
|
|
|
|
```bash
|
|
wrangler login
|
|
```
|
|
|
|
3. Set environment variables:
|
|
|
|
```bash
|
|
wrangler secret put DATABASE_URL
|
|
wrangler secret put JWT_SECRET
|
|
wrangler secret put GITHUB_CLIENT_ID
|
|
wrangler secret put GITHUB_CLIENT_SECRET
|
|
wrangler secret put GOOGLE_CLIENT_ID
|
|
wrangler secret put GOOGLE_CLIENT_SECRET
|
|
```
|
|
|
|
4. Deploy:
|
|
|
|
```bash
|
|
bun run deploy
|
|
```
|
|
|
|
#### Other Platforms (Railway, Fly.io, etc.)
|
|
|
|
Use the standard Bun deployment process for your platform.
|
|
|
|
## API Endpoints
|
|
|
|
### Health Check
|
|
|
|
- `GET /health` - Health check and database status
|
|
|
|
### Authentication
|
|
|
|
- `GET /api/auth/github` - GitHub OAuth
|
|
- `GET /api/auth/github/callback` - GitHub OAuth callback
|
|
- `GET /api/auth/google` - Google OAuth
|
|
- `GET /api/auth/google/callback` - Google OAuth callback
|
|
- `GET /api/auth/me` - Get current user (requires auth)
|
|
- `POST /api/auth/logout` - Logout
|
|
|
|
### Marketplace (Public)
|
|
|
|
- `GET /api/marketplace/agents` - List agents (with filters)
|
|
- `GET /api/marketplace/agents/featured` - Featured agents
|
|
- `GET /api/marketplace/agents/:slug` - Agent details
|
|
- `GET /api/marketplace/agents/:slug/versions` - Agent versions
|
|
- `GET /api/marketplace/agents/:slug/versions/:version` - Version details
|
|
- `POST /api/marketplace/agents/:slug/download` - Track download
|
|
- `POST /api/marketplace/agents/:slug/install` - Track install
|
|
- `GET /api/marketplace/categories` - List categories
|
|
- `GET /api/marketplace/tags` - List tags
|
|
- `GET /api/marketplace/collections` - List collections
|
|
- `GET /api/marketplace/collections/:slug` - Collection details
|
|
|
|
### Agents (Requires Auth)
|
|
|
|
- `POST /api/agents` - Publish new agent
|
|
- `PUT /api/agents/:slug` - Update agent
|
|
- `DELETE /api/agents/:slug` - Delete agent
|
|
- `POST /api/agents/:slug/versions` - Publish new version
|
|
|
|
### Users (Requires Auth)
|
|
|
|
- `GET /api/users/me/agents` - Get my agents
|
|
- `GET /api/users/me/stats` - Get my statistics
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
apps/api/
|
|
├── src/
|
|
│ ├── index.ts # Main application entry
|
|
│ ├── db/
|
|
│ │ ├── schema.ts # Database schema
|
|
│ │ ├── client.ts # Database connection
|
|
│ │ ├── migrate.ts # Migration script
|
|
│ │ ├── seed.ts # Seed script
|
|
│ │ └── migrations/ # Migration files
|
|
│ ├── routes/ # API routes
|
|
│ │ ├── auth.ts
|
|
│ │ ├── marketplace.ts
|
|
│ │ ├── agents.ts
|
|
│ │ └── users.ts
|
|
│ ├── services/ # Business logic
|
|
│ │ ├── agent-service.ts
|
|
│ │ ├── user-service.ts
|
|
│ │ ├── auth-service.ts
|
|
│ │ └── stats-service.ts
|
|
│ ├── middlewares/ # Middleware
|
|
│ │ ├── auth.ts
|
|
│ │ └── error-handler.ts
|
|
│ ├── lib/ # Utilities
|
|
│ │ ├── jwt.ts
|
|
│ │ └── utils.ts
|
|
│ └── types/ # Type definitions
|
|
│ ├── env.ts
|
|
│ └── context.ts
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── drizzle.config.ts
|
|
├── wrangler.toml
|
|
└── README.md
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|