# AnyBio Integration Context
# Place this file at your project root as .cursorrules
# Docs: https://developer.anybio.io/bioui-web/guides/cursor-integration

## Platform
AnyBio is a biosignal infrastructure platform. It handles BLE device connectivity,
real-time signal processing, FHIR output, and clinical AI — so you build the product, not the pipeline.

## Authentication Model
- Organization API key: `org_*` (server-side only, never expose to browser)
- Project key: `proj_*` (identifies the project)
- SDK key: `sdk_*` (browser-safe, limited scope)
- XUser token: short-lived JWT for end-user access (minted server-side via POST /api/v1/sdk/token)

IMPORTANT: org_* keys must NEVER appear in client-side code (React components, HTML, mobile app bundles).
Always mint xuser tokens via a server-side route and pass the token to the client.

## Key API Endpoints (base: https://api.anybio.io)
- POST /api/v1/sdk/token — Mint xuser token (requires org_* key, server-side only)
  Body: { external_id: "user-id", project_key: "proj_*" }
  Returns: { xuser_token: "eyJ...", xuser_id: "...", expires_in: 3600 }
- GET  /api/v1/xusers — List users in project
- GET  /api/v1/episodes — List episodes (query: xuser_id, from, to)
- GET  /api/v1/episodes/:id — Episode detail with artifacts
- POST /api/v1/charts/query — Query chart data
- GET  /api/v1/admin/usage/summary — BPU usage (query: window=30d)
- GET  /api/v1/bootstrap — SDK bootstrap config (device profiles)
- POST /ingest/raw-packet — Protobuf biosignal ingest (SDK handles this automatically)
- OpenAPI spec: https://api.anybio.io/api-docs

## BioSDK (iOS) — Native BLE device streaming
Swift Package: https://github.com/anybio/biosdk-ios-binary.git
Info.plist required: NSBluetoothAlwaysUsageDescription, UIBackgroundModes: bluetooth-central

```swift
import BioSDK
let sdk = try await BioSDKClient.initialize(
    configuration: .auto(organizationKey: "org_*", projectKey: "proj_*"))
sdk.startScan()
sdk.connect(sdk.discoveredDevices.first!)
sdk.startStreaming(for: "user-id")

// Receive events via Combine
sdk.events.sink { event in
    switch event {
    case .sample(let deviceId, let sample):
        print("[\(deviceId)] \(sample.signalName): \(sample.data)")
    case .lifecycle(let lifecycle):
        // .discovered, .connected, .disconnected
    case .deviceState(let device, let connection, let stream):
        // connection: .discovered, .connecting, .ready, .disconnected
        // stream: .idle, .streaming, .paused
    default: break
    }
}
```

## BioUI Web — Browser widgets (CDN, zero build step)
```html
<script src="https://cdn.anybio.io/biosdk-web/v1/bioui.js"></script>
<link rel="stylesheet" href="https://cdn.anybio.io/biosdk-web/v1/bioui-base.css" />

<bio-provider api-key="sdk_*" project-key="proj_*" xuser-token="eyJ...">
  <bio-health-metrics></bio-health-metrics>
  <bio-checkin></bio-checkin>
</bio-provider>
```

Available widgets:
- <bio-health-metrics> — Wearable data (steps, sleep, HR, stress)
- <bio-mood> — Mood tracking with configurable scales
- <bio-checkin> — PRO questionnaires (PHQ-9, GAD-7, etc.)
- <bio-journal> — Daily journaling with prompts
- <bio-task-list> — Daily task tracking
- <bio-progress-ring> — Circular progress visualization
- <bio-trend-card> — Single biosignal trend summary
- <bio-trend-chart> — Multi-biosignal trend charts

## Security Rules
- NEVER put org_* keys in client-side code
- Use sdk_* or xuser tokens for client-side authentication
- Mint xuser tokens server-side (edge function, API route, serverless function)
- All /api/v1/* endpoints require authentication
- Token expiry: 1 hour. Listen for anybio:token:expiring event to refresh.

## Documentation
- Full docs: https://developer.anybio.io
- OpenAPI spec: https://api.anybio.io/api-docs
- BioSDK iOS: https://developer.anybio.io/biosdk/quickstart
- BioUI Web: https://developer.anybio.io/bioui-web/quickstart
- Lovable guide: https://developer.anybio.io/bioui-web/guides/lovable-integration