Best Auction Cloud API

Cloudflare Workers API for Best Auction Minecraft Plugin - provides real-time auction data synchronization and REST API access.

Features

• 🔐 Secure Authentication - JWT + API token based authentication
• 📊 Real-time Event Processing - Receive auction events from Minecraft servers
• 🔄 Data Synchronization - Bulk sync auction and bid data
• 🌐 REST API - Public API for accessing auction data
• ⚡ High Performance - Built on Cloudflare Workers Edge
• 📈 Analytics - Server statistics and event tracking

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• POST /api/auth/validate - Validate API token
• POST /api/auth/tokens - Create API token
• GET /api/auth/tokens - List user tokens
• DELETE /api/auth/tokens/:id - Delete token

Events (Protected)

• POST /api/events - Receive auction event
• GET /api/events - Get events
• GET /api/events/:serverId - Get server events
• GET /api/events/stats - Get event statistics

Event Data Schemas

ITEM_LISTED Event Data

Required fields for ITEM_LISTED events:

{
  "seller_uuid": "string (UUID format)",
  "seller_name": "string (1-16 chars)",
  "item_name": "string",
  "item_type": "string",
  "quantity": "integer (positive)",
  "start_price": "integer (positive)",
  "buyout_price": "integer (positive, optional)",
  "created_at": "string (ISO datetime)",
  "expires_at": "string (ISO datetime)"
}

Synchronization (Protected)

• POST /api/sync - Batch sync auction data

Public API

• GET /api/auctions - Get auctions
• GET /api/auctions/:serverId - Get server auctions
• GET /api/auctions/:serverId/:auctionId - Get specific auction
• GET /api/servers - Get all servers
• GET /api/servers/:serverId/stats - Get server stats
• GET /api/stats - Get global statistics

Setup

Prerequisites

• Node.js 18+
• Cloudflare account
• Wrangler CLI

Installation

1. Clone and install dependencies:

   cd /Users/masafumi_t/Develop/work/minecraft/projects/best_auction_cloud
   npm install

2. Configure Cloudflare D1 Database:

   # Create database
   wrangler d1 create best-auction-db
   
   # Update wrangler.toml with database ID
   # Copy the database ID to wrangler.toml
   
   # Run migrations
   wrangler d1 migrations apply best-auction-db --local
   wrangler d1 migrations apply best-auction-db

3. Set environment variables:

   # Set JWT secret
   wrangler secret put JWT_SECRET
   
   # Set other environment variables in wrangler.toml

4. Deploy:

   # Development
   npm run dev
   
   # Production
   npm run deploy

Configuration

Environment Variables

• JWT_SECRET - Secret for JWT token signing
• ENVIRONMENT - Environment (development/production)
• CORS_ORIGINS - Allowed CORS origins (comma-separated)
• RATE_LIMIT_REQUESTS - Rate limit per window
• RATE_LIMIT_WINDOW - Rate limit window in seconds

Database Schema

The API uses Cloudflare D1 (SQLite) with the following tables:

• users - User accounts
• api_tokens - API authentication tokens
• auction_events - Real-time auction events
• auctions - Current auction state
• bids - Auction bids
• servers - Server tracking

Authentication Flow

For Web Applications (Dashboard)

1. Register/Login with email and password
2. Receive JWT token
3. Create API tokens for servers
4. Use API tokens for server authentication

For Minecraft Servers

1. Get API token from web dashboard
2. Configure token in plugin config
3. Plugin uses token for all API requests

Usage Examples

Register User

curl -X POST https://your-worker.your-domain.workers.dev/api/auth/register \\
  -H "Content-Type: application/json" \\
  -d '{
    "username": "myuser",
    "email": "[email protected]",
    "password": "securepassword123"
  }'

Create API Token

curl -X POST https://your-worker.your-domain.workers.dev/api/auth/tokens \\
  -H "Authorization: Bearer <JWT_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "server_id": "my-minecraft-server",
    "permissions": "read,write"
  }'

Send Auction Event

curl -X POST https://your-worker.your-domain.workers.dev/api/events \\
  -H "Authorization: Bearer <API_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "event_type": "ITEM_LISTED",
    "server_id": "my-server",
    "timestamp": "2024-01-01T12:00:00Z",
    "auction_id": 123,
    "data": {
      "seller_uuid": "a730b4c5-38e2-4d0c-ad28-588d229030e5",
      "seller_name": "Player1",
      "item_name": "Diamond Sword",
      "item_type": "DIAMOND_SWORD",
      "quantity": 1,
      "start_price": 1000,
      "buyout_price": 2000,
      "created_at": "2024-01-01T12:00:00Z",
      "expires_at": "2024-01-10T12:00:00Z"
    }
  }'

Get Auctions

curl https://your-worker.your-domain.workers.dev/api/auctions?server_id=my-server \\
  -H "Authorization: Bearer <API_TOKEN>"

Development

Local Development

npm run dev

Testing

npm test

Build

npm run build

Minecraft Plugin Integration

Configure the Minecraft plugin with:

cloud:
  enabled: true
  base_url: "https://your-worker.your-domain.workers.dev"
  api_token: "your-api-token-here"
  server_id: "your-server-id"

Security Features

• Rate Limiting - Prevents API abuse
• CORS Protection - Configurable origins
• Security Headers - XSS, CSRF protection
• Token Expiration - Configurable token lifetime
• Permission System - Read/write/admin permissions
• Input Validation - Comprehensive request validation

Monitoring

The API provides built-in monitoring through:

• Health check endpoints
• Request/response logging
• Error tracking
• Performance metrics

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the documentation
2. Review error logs in Cloudflare dashboard
3. Create an issue in the repository