# HiveForge

> HiveForge is a batteries-included SaaS platform that lets you deploy production-ready applications with built-in AI, billing, email, vector search, webhooks, and MCP integration.

## Documentation

- [Getting Started](https://docs.hiveforge.dev/getting-started/quick-start): Quick start guide with SDK installation and first API call
- [Authentication](https://docs.hiveforge.dev/authentication): JWT tokens, API keys, OAuth, deployment credentials
- [TypeScript SDK](https://docs.hiveforge.dev/sdk): Full SDK reference for @producthacker/hiveforge-sdk
- [API Reference](https://docs.hiveforge.dev/api): REST API documentation with examples
- [MCP Integration](https://docs.hiveforge.dev/mcp): Model Context Protocol integration for AI agents
- [Entitlements & Tiers](https://docs.hiveforge.dev/entitlements): Feature flags, quotas, and credit system

## SDK

Install: `npm install @producthacker/hiveforge-sdk`

### AI Proxy
- [AI Completions](https://docs.hiveforge.dev/sdk/ai): Chat completions, streaming, embeddings
- [AI Quota](https://docs.hiveforge.dev/api/proxy/ai-quota): Check usage and limits

### Billing
- [Billing](https://docs.hiveforge.dev/sdk/billing): Stripe checkout, customer portal

### Credits
- [Credits](https://docs.hiveforge.dev/sdk/credits): Balance, usage, cost management

### Email
- [Email](https://docs.hiveforge.dev/sdk/email): Transactional email sending

### Vectors
- [Vectors](https://docs.hiveforge.dev/sdk/vectors): Vector search, upsert, delete

### Webhooks
- [Webhooks](https://docs.hiveforge.dev/sdk/webhooks): Webhook delivery with HMAC signing

### React
- [React Components](https://docs.hiveforge.dev/sdk/react): Provider, hooks, entitlement gates

### Enterprise
- [Enterprise](https://docs.hiveforge.dev/sdk/enterprise): Self-hosted license management

## API Endpoints

Base URL: `https://api.hiveforge.dev/api/v1`

### Proxy Endpoints (Deployment Credentials)
- POST /proxy/ai/completions - Chat completion
- POST /proxy/ai/completions/stream - Streaming completion
- POST /proxy/ai/embeddings - Generate embeddings
- GET /proxy/ai/quota - Check AI quota
- POST /proxy/billing/checkout - Create Stripe checkout
- POST /proxy/billing/portal - Create customer portal
- POST /proxy/email/send - Send transactional email
- POST /proxy/vectors/search - Semantic vector search
- POST /proxy/vectors/upsert - Upsert vectors
- POST /proxy/vectors/delete - Delete vectors
- POST /proxy/webhooks/send - Send webhook

### MCP Endpoints
- POST /mcp/stdio/check-entitlement - Check tool entitlement (API key auth)
- POST /mcp/stdio/record-usage - Record tool usage (API key auth)
- POST /mcp/check-entitlement - Check entitlement (service key auth)
- POST /mcp/usage - Record usage (service key auth)
- GET /mcp/resolve-deployment - Resolve user to deployment
- GET /mcp/credit-costs - Get credit costs per tool

## Authentication

Four auth mechanisms:
1. **JWT Bearer Token** - For platform API calls: `Authorization: Bearer <supabase-jwt>`
2. **API Keys** - For programmatic access: `Authorization: Bearer hf_live_...`
3. **Deployment Credentials** - For SDK/proxy: `X-Deployment-ID` + `X-Deployment-Secret` headers
4. **MCP Service Key** - For MCP servers: `X-MCP-Service-Key` header

## Entitlement Tiers

| Tier | AI | Rate Limit | MCP | Custom Domain | White Label |
|------|-----|-----------|-----|--------------|-------------|
| Sandbox | No | 100/min | No | No | No |
| Trial | Yes (1K) | 500/min | Yes | No | No |
| Launch | Yes (10K) | 2K/min | Yes | Yes | No |
| Growth | Yes (50K) | 10K/min | Yes | Yes | Yes |
| Enterprise | Unlimited | Unlimited | Yes | Yes | Yes |