feat: Implement Processor and Queue Infrastructure (Issue #6)

specs/core-pipeline/api.md

@@ -0,0 +1,152 @@
+# Core Pipeline: API Reference
+
+**Version**: 1.0
+**Last Updated**: 2025-01-11
+
+---
+
+## Core Collection Endpoint
+
+**Endpoint**: `POST /collect` or `POST /collect/{stream}`
+
+**Path Parameters**:
+- `stream` (optional): Stream name (default: "default")
+
+**Request Body**: Any valid JSON
+
+**Response**: `202 Accepted`
+```json
+{
+  "message": "Event received",
+  "data": {
+    "received": true,
+    "stream": "users"
+  }
+}
+```
+
+**Batch Support**:
+```json
+POST /collect/events
+[
+  {"type": "track", "event": "Button Clicked"},
+  {"type": "track", "event": "Page Viewed"}
+]
+
+Response: {"message": "Events received", "data": {"received": 2}}
+```
+
+---
+
+## Convenience Endpoints (Segment-Compatible)
+
+| Endpoint | Stream | Purpose |
+|----------|--------|---------|
+| `POST /v1/identify` | `users` | User identification and traits |
+| `POST /v1/track` | `events` | Event tracking |
+| `POST /v1/page` | `pages` | Page views |
+
+All delegate to `POST /collect/{stream}` with appropriate stream.
+
+---
+
+## Health Endpoints
+
+| Endpoint | Response | Purpose |
+|----------|----------|---------|
+| `GET /health` | `200 OK` | Liveness check |
+| `GET /ready` | `200 OK` or `503 Service Unavailable` | Readiness check (Firestore connectivity) |
+
+---
+
+## Event Formats
+
+### Identify Event
+
+```json
+POST /v1/identify
+{
+  "userId": "user_123",
+  "traits": {
+    "email": "user@example.com",
+    "name": "Alice",
+    "plan": "premium"
+  },
+  "timestamp": "2025-01-11T12:00:00Z"
+}
+```
+
+**Optional Fields**:
+- `anonymousId`: Anonymous identifier (fallback if userId missing)
+- `$set`: Profile fields to set (PostHog pattern)
+- `$set_once`: Profile fields to set only if not already set
+
+---
+
+### Track Event
+
+```json
+POST /v1/track
+{
+  "userId": "user_123",
+  "event": "Button Clicked",
+  "properties": {
+    "button_id": "cta_primary",
+    "page": "/home"
+  },
+  "timestamp": "2025-01-11T12:00:00Z"
+}
+```
+
+**Required Fields**:
+- `event`: Event name (string)
+- `userId` OR `anonymousId`: At least one identity required
+
+---
+
+### Page Event
+
+```json
+POST /v1/page
+{
+  "userId": "user_123",
+  "name": "/home",
+  "properties": {
+    "title": "Homepage",
+    "referrer": "https://google.com"
+  },
+  "timestamp": "2025-01-11T12:00:00Z"
+}
+```
+
+---
+
+## Error Responses
+
+### 400 Bad Request
+
+```json
+{
+  "error": "Invalid JSON",
+  "detail": "Expected object or array, got string"
+}
+```
+
+### 503 Service Unavailable
+
+```json
+{
+  "error": "Service unavailable",
+  "detail": "Firestore connection failed"
+}
+```
+
+**Note**: Invalid events are accepted (202) but stored in error queue—they don't return 4xx errors.
+
+---
+
+## Related Documentation
+
+- **[Specification](./spec.md)** - User stories and requirements
+- **[Data Models](./data-models.md)** - Event schemas
+- **[Architecture](./architecture.md)** - Component design