gamecore-sdk 0.1.0

package/skill/gamecore-integration/references/api-reference.md

@@ -0,0 +1,271 @@
+# GameCore API Reference
+
+Complete endpoint catalog. All paths prefixed with `/v1` unless noted as `/admin/v1`.
+
+## Authentication
+
+All requests require `X-API-KEY` header (format: `prefix.body`). Tenant creation and health check are the only unauthenticated endpoints.
+
+---
+
+## Tenant & API Keys
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/tenants` | Create tenant. Body: `{ name }`. Returns: `{ id, name, apiKey }`. |
+| `GET` | `/tenants/me` | Get current tenant info. |
+| `GET` | `/tenants/me/api-keys` | List active API keys (prefixes only, bodies not returned). |
+| `POST` | `/tenants/me/api-keys` | Generate new API key. Returns full key once. |
+| `DELETE` | `/tenants/me/api-keys/:prefix` | Revoke an API key by prefix. |
+
+**Example — Create tenant:**
+```bash
+curl -X POST http://localhost:3000/v1/tenants \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My App"}'
+# Response: { "id": "...", "name": "My App", "apiKey": "prefix.bodyhash..." }
+```
+
+---
+
+## Users
+
+User IDs (`externalId`) are provided by you — GameCore does not generate them.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/users` | Create user. Body: `{ externalId, name?, attributes?, deviceTokens? }`. |
+| `PUT` | `/users/:id` | Upsert user (creates if not exists, updates if exists). |
+| `GET` | `/users/:id` | Get user by externalId. |
+| `GET` | `/users` | List users (paginated). |
+| `PATCH` | `/users/:id` | Update user fields (name, attributes, deviceTokens, preferences). |
+| `DELETE` | `/users/:id` | Full deletion (LGPD compliant). |
+| `DELETE` | `/users/:id/data` | Anonymize user data — keeps user record but clears PII. |
+| `POST` | `/users/:id/consent` | Record user consent. Body: `{ type, granted }`. |
+| `PATCH` | `/users/:id/preferences` | Set notification preferences by type and channel. |
+
+**Example — Upsert user:**
+```bash
+curl -X PUT http://localhost:3000/v1/users/user-123 \
+  -H "Content-Type: application/json" \
+  -H "X-API-KEY: prefix.body" \
+  -d '{"name": "João Silva", "attributes": {"region": "sul", "plan": "premium"}}'
+```
+
+User attributes are arbitrary key-value pairs used for achievement filtering and leaderboard breakdowns.
+
+---
+
+## Metrics
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/metrics` | Create metric definition. Body: `{ key, displayName, unit? }`. |
+| `GET` | `/metrics` | List all metrics for the tenant. |
+| `GET` | `/metrics/:key` | Get metric definition. |
+| `GET` | `/metrics/:key/users/:userId` | Get user's total for a metric. |
+| **`POST`** | **`/metrics/:key/event`** | **Send metric event — the central orchestrator.** |
+
+### Metric Event (POST /metrics/:key/event)
+
+**Request body:**
+```json
+{
+  "userId": "string (required)",
+  "value": 1.0 (optional, default 1),
+  "idempotencyKey": "string (optional)",
+  "attributes": { "key": "value" } (optional, for achievement filtering)
+}
+```
+
+**Response — all side effects in one call:**
+```json
+{
+  "metricId": "uuid",
+  "eventId": "uuid",
+  "total": 42,
+  "achievements": [
+    { "key": "10-lessons", "name": "10 Lições", "badgeUrl": "https://..." }
+  ],
+  "currentStreak": {
+    "streakId": "uuid",
+    "length": 5,
+    "frequency": "daily",
+    "extended": true
+  },
+  "points": {
+    "xp": {
+      "systemId": "uuid",
+      "total": 150,
+      "added": 10,
+      "level": { "name": "Bronze", "icon": "🥉", "minPoints": 0 }
+    }
+  },
+  "leaderboards": {
+    "weekly-xp": { "rank": 3, "previousRank": 7, "score": 150 }
+  },
+  "idempotentReplayed": false
+}
+```
+
+**Idempotency:** Send `Idempotency-Key` header. Duplicate keys return `202` with cached response — no side effects replayed.
+
+---
+
+## Achievements
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/achievements` | List all achievements for the tenant. |
+| `GET` | `/achievements/:key` | Get achievement definition. |
+| `GET` | `/achievements/:key/users/:userId` | Check if user has completed an achievement. |
+| `GET` | `/users/:id/achievements` | List all achievements for a user. |
+| `POST` | `/achievements/:key/complete` | Manually complete an API-type achievement. Body: `{ userId }`. |
+
+**Achievement types (configured via Admin API):**
+
+| Type | Auto-triggered by | Example config |
+|------|-------------------|----------------|
+| `metric` | Metric event reaching threshold | `{ type: "metric", metricKey: "lessons_completed", threshold: 100 }` |
+| `api` | Manual `POST /achievements/:key/complete` | `{ type: "api" }` |
+| `streak` | Streak reaching length threshold | `{ type: "streak", streakKey: "daily", threshold: 7 }` |
+| `composite` | All prerequisites completed | `{ type: "composite", prerequisiteKeys: ["a", "b", "c"] }` |
+
+**Status workflow:** `inactive` → `active` → `locked` → `archived`
+
+---
+
+## Streaks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/streaks` | List all streak definitions for the tenant. |
+| `GET` | `/streaks/:key` | Get streak definition. |
+| `GET` | `/streaks/rankings` | Get global streak rankings. |
+| `GET` | `/users/:id/streak` | Get user's current streak state. |
+
+---
+
+## Points
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/points/:key` | Get points system definition. |
+| `GET` | `/points/summary` | Get summary of all points systems. |
+| `GET` | `/points/:key/boosts` | List active boosts for a points system. |
+| `GET` | `/points/:key/levels` | List level tiers for a points system. |
+| `GET` | `/users/:id/points` | Get all points balances for a user. |
+| `GET` | `/users/:id/points/:key` | Get specific points balance for a user. |
+
+---
+
+## Leaderboards
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/leaderboards` | List all leaderboards for the tenant. |
+| `GET` | `/leaderboards/:key` | Get leaderboard with current rankings. |
+| `GET` | `/users/:id/leaderboards` | Get user's positions across all leaderboards. |
+
+---
+
+## Webhooks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/webhooks` | List webhook configurations. |
+| `POST` | `/webhooks` | Create webhook. Body: `{ url, secret, eventTypes[] }`. |
+| `GET` | `/webhooks/:id` | Get webhook config. |
+| `PATCH` | `/webhooks/:id` | Update webhook config. |
+| `DELETE` | `/webhooks/:id` | Delete webhook. |
+| `GET` | `/webhooks/:id/logs` | Get delivery logs for a webhook. |
+
+**Event types:**
+`achievement.completed`, `streak.extended`, `streak.lost`, `points.changed`, `points.level_changed`, `points.boost_started`, `notification.email_sent`, `notification.email_failed`, `notification.push_sent`, `notification.push_failed`, `user.deleted`, `user.anonymized`
+
+**Security:** HMAC-SHA256 signature in `X-Webhook-Signature` header. Verify using your webhook secret.
+
+---
+
+## Attributes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/attributes` | List attribute definitions. |
+| `POST` | `/attributes` | Create attribute definition. Body: `{ key, name, scope: "user"\|"event", type: "string"\|"number"\|"boolean"\|"date" }`. |
+| `DELETE` | `/attributes/:key` | Delete attribute definition. |
+
+---
+
+## Notifications Config
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/tenants/me/email-config` | Set email provider. Body: `{ provider: "resend", apiKey, fromAddress }`. |
+| `GET` | `/tenants/me/email-config` | Get email config. |
+| `POST` | `/tenants/me/email-config/verify` | Verify email configuration. |
+| `DELETE` | `/tenants/me/email-config` | Remove email config. |
+| `POST` | `/tenants/me/push-config` | Set push provider. Body: `{ provider: "expo", credentials }`. |
+| `GET` | `/tenants/me/push-config` | Get push config. |
+| `DELETE` | `/tenants/me/push-config` | Remove push config. |
+
+---
+
+## Health
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Basic health check. No auth required. |
+| `GET` | `/health/detailed` | Detailed health (DB, Redis status). No auth required. |
+
+---
+
+## Admin API (/admin/v1)
+
+The Admin API uses magic-link authentication (cookie `gc_session`) instead of API keys. These endpoints are for the dashboard, not for production app integration.
+
+### Auth
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/admin/v1/auth/magic-link` | Send magic link. Body: `{ tenantId, email }`. |
+| `POST` | `/admin/v1/auth/verify` | Verify magic link token. Body: `{ token }`. Sets cookie. |
+| `POST` | `/admin/v1/auth/logout` | Clear session. |
+
+### Management Endpoints (admin only)
+
+Full CRUD available for all domains:
+- **Metrics:** `GET/POST /admin/v1/metrics`, `GET/PATCH/DELETE /admin/v1/metrics/:key`
+- **Achievements:** `GET/POST /admin/v1/achievements`, `GET/PATCH/DELETE /admin/v1/achievements/:key`
+- **Streaks:** `GET/POST /admin/v1/streaks`, `GET/PATCH/DELETE /admin/v1/streaks/:key`. Also: `POST /admin/v1/streaks/:key/restore` (restore lost streak), `POST /admin/v1/streaks/:key/freezes` (grant freezes)
+- **Points:** `GET/POST /admin/v1/points`, `GET/PATCH/DELETE /admin/v1/points/:key`. Also: `POST /admin/v1/points/:key/boosts` (create boost)
+- **Leaderboards:** `GET/POST /admin/v1/leaderboards`, `GET/PATCH/DELETE /admin/v1/leaderboards/:key`
+- **Users:** `GET /admin/v1/users` (list, search, filter), `GET /admin/v1/users/:id`
+- **Audit Logs:** `GET /admin/v1/audit-logs`
+- **Notification Templates:** `GET/POST /admin/v1/notifications/templates`, `GET/PATCH/DELETE /admin/v1/notifications/templates/:id`
+
+---
+
+## Rate Limiting
+
+| Tier | Limit | Applies to |
+|------|-------|-----------|
+| TIER_1 | 10 req/s | Metric events (`POST /metrics/:key/event`), achievement completions, all writes |
+| TIER_2 | 100 req/s | Reads and lighter endpoints |
+
+Rate limit headers are included in responses. Exceeding returns `429 Too Many Requests`.
+
+---
+
+## Common Response Codes
+
+| Code | Meaning |
+|------|---------|
+| `200` | Success |
+| `201` | Created |
+| `202` | Idempotent replay — duplicate event accepted, cached response returned |
+| `400` | Validation error — check request body |
+| `401` | Missing or invalid API key |
+| `404` | Resource not found |
+| `409` | Conflict (e.g., duplicate metric key) |
+| `429` | Rate limited — slow down |
+| `500` | Server error — check GameCore logs |