vibn-api/README.md

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:

bun install

2. Copy environment variables:

cp .env.example .env

3. Fill in your .env file with actual values:

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:

bun run db:generate

5. Run migrations:

bun run db:migrate

6. Seed the database with initial data:

bun run db:seed

Development

Run the development server with hot reload:

bun run dev

The API will be available at http://localhost:3000

Testing

Run tests:

bun test

Database Management

# 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:

bun run build

Build for Cloudflare Workers:

bun run build:cloudflare

Deployment

Cloudflare Workers

1. Install Wrangler CLI:

bun install -g wrangler

2. Login to Cloudflare:

wrangler login

3. Set environment variables:

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:

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