OffshoreProz Agent API

Cloudflare Worker que expõe a API REST e o servidor MCP para formação de empresas agent-native.

Fonte da verdade: este diretório no monorepo docs-offshore-proz é canônico (é daqui que o wrangler deploy roda). O repo público offshoreproz/offshoreproz-agent-api é um mirror open-source. Após mergear mudanças aqui, atualize o mirror com scripts/sync-public-mirror.sh (ele exclui wrangler.jsonc — IDs de produção — e publica wrangler.example.jsonc). Demo para clientes: ver docs/DEMO.md.

• Domínio: api.offshoreproz.com (produção) | api-staging.offshoreproz.com (staging)
• Worker: offshoreproz-agent-api
• Account: OffshoreProz Account (edcb1c764cb522105ca309000b0a8843)
• Sprint atual: Sprint 1 — Worker Shell

Plano completo: docs/plano-agentes-heitor/plano-definitivo/

---

Recursos Cloudflare criados

Recurso	Nome	ID
D1 AGENT_DB	offshoreproz-agent-api	cbcbfc99-e891-49ea-a6a8-b97f2a569f5e
D1 PORTAL_DB	offshoreproz-docs-db	5f1c4aa7-750e-4277-9cd8-486381c93ec6
KV	AGENT_API_RATE_LIMIT	b1ec474373044fdca11bf4a12132a18c
R2	offshoreproz-docs-storage	(pré-existente, prefixo agent-api/)

---

Setup local

# 1. Instalar dependências
cd workers/agent-api
npm install

# 2. Gerar tipos Cloudflare a partir do wrangler.jsonc
npx wrangler types

# 3. Copiar e preencher secrets locais
cp .dev.vars.example .dev.vars
# editar .dev.vars com API_KEY_ENCRYPTION_SECRET

# 4. Aplicar migrations no banco local
npm run migrate:local

# 5. Iniciar Worker local
npm run dev

---

Endpoints implementados (Sprint 1)

Método	Rota	Auth	Descrição
GET	/health	—	Status do Worker
GET	/openapi.json	—	Especificação OpenAPI 3.1
GET	/v1/jurisdictions	—	Listar jurisdições
GET	/v1/jurisdictions/:code	—	Detalhes de uma jurisdição
GET	/v1/jurisdictions/:code/requirements	—	Campos obrigatórios para criação
POST	/v1/jurisdictions/:code/estimate	—	Calcular custo + gerar estimate_token

---

Estrutura

workers/agent-api/
├── wrangler.jsonc          ← configuração com todos os bindings e environments
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .dev.vars.example       ← copiar para .dev.vars (não commitar)
├── src/
│   ├── index.ts            ← entry point (Hono app)
│   ├── types.ts            ← Env + FormationStatus + tipos compartilhados
│   ├── config/
│   │   └── jurisdictions.ts ← dados estáticos: WY, MI, NV, BVI, PA, UAE
│   ├── routes/
│   │   ├── health.ts
│   │   ├── jurisdictions.ts
│   │   └── openapi.ts
│   ├── middleware/
│   │   ├── cors.ts
│   │   ├── errors.ts
│   │   └── trace.ts
│   └── lib/
│       ├── crypto.ts       ← geração de IDs, hash, HMAC, timing-safe compare
│       ├── logger.ts       ← JSON estruturado, sanitização de PII
│       └── response.ts     ← helpers de resposta padronizados
├── migrations/
│   └── agent-db/
│       ├── 0001_initial_schema.sql   ← api_keys, formations, events, idempotency, webhooks
│       └── 0002_usage_tracking.sql   ← usage_daily, admin_actions
└── tests/
    └── health.test.ts

---

Regra de D1

Binding	Database	Uso
AGENT_DB	offshoreproz-agent-api	API keys, formations, events, webhooks, usage
PORTAL_DB	offshoreproz-docs-db	projects, clients, docs, invoices, renewals
site-offshore-db	NUNCA bindar	Marketing/CMS do root — proibido aqui

---

Deploy

# Staging
npm run deploy:staging

# Produção (BLOQUEADO até live gate checklist)
# Ver: docs/plano-agentes-heitor/plano-definitivo/10-PLANO-DE-INICIO-ENG.md
npm run deploy:production:force  # apenas com aprovação explícita

---

Testes

npm run test           # run once
npm run test:watch     # watch mode
npm run test:coverage  # with coverage

---

Migrations

npm run migrate:local    # aplica no banco local (dev)
npm run migrate:staging  # aplica no AGENT_DB remoto (staging)
npm run migrate:list     # lista migrations e status

---

Próximos Sprints

Ver TRACKING-SPRINTS.md

Sprint	Objetivo
Sprint 1 ✅	Worker shell, endpoints estáticos, sem DB write
Sprint 2	AGENT_DB schema + auth test mode + formations sandbox
Sprint 3	Portal sync (criar projeto em PORTAL_DB)
Sprint 4	Tracking completo + webhooks externos
Sprint 5	Owner actions + root account router
Sprint 6	R2 documents + portal vault
Sprint 7	Wyoming live gate
Sprint 8	MCP sandbox + beta