Cursor Integration

# AnyBio Integration Context

## 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)

## Key API Endpoints (base: https://api.anybio.io)
- POST /api/v1/sdk/token — Mint xuser token (requires org_* key, server-side)
- GET  /api/v1/xusers — List users in project
- GET  /api/v1/episodes — List episodes for a user
- GET  /api/v1/episodes/:id — Episode detail with artifacts
- POST /api/v1/charts/query — Query chart data
- GET  /api/v1/bootstrap — SDK bootstrap config (device profiles)
- POST /ingest/raw-packet — Protobuf biosignal ingest (SDK handles this)

## BioSDK (iOS) — BLE device streaming
```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")

<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="org_*" project-key="proj_*" xuser-id="user-123">
  <bio-health-metrics></bio-health-metrics>
  <bio-checkin></bio-checkin>
</bio-provider>

## Step 2: Use Cursor with AnyBio

With `.cursorrules` in place, Cursor's AI understands AnyBio's APIs. Try these prompts:

### Adding BioUI Web widgets to an existing app

> Add AnyBio health widgets to my dashboard page. Use the BioUI Web CDN. Create a server-side route at /api/anybio-token that mints xuser tokens using my org key, then initialize the widgets client-side after login.

### Building an iOS app with BioSDK

> Create a SwiftUI view that scans for BLE devices, shows a list, and lets the user tap to connect and start streaming. Use BioSDK. Show real-time heart rate from the .sample events.

### Querying episode data

> Add an episodes list page that fetches from /api/v1/episodes for the current user, shows episode type, duration, and attention score. Include a detail view that displays the episode timeline and any artifact PDFs.

## Step 3: Point to the OpenAPI Spec

For Cursor's `@docs` feature, you can reference the AnyBio OpenAPI spec directly:

1. Open Cursor Settings > Features > Docs
2. Add: `https://api.anybio.io/api-docs`
3. Now use `@AnyBio` in prompts to reference the full API schema

## Tips

- **Start with BioUI Web** if you're building a web app — it's CDN-based with zero build step
- **Start with BioSDK** if you're building a native iOS app
- **Always create tokens server-side** — Cursor sometimes puts API keys in client code; review and move to a server route
- **Use `@docs`** to let Cursor read the OpenAPI spec for endpoint details
- **Iterate in Composer** — paste error messages back and Cursor will fix them with AnyBio context

## Troubleshooting

| Issue | Solution |
|---|---|
| Cursor puts `org_*` key in React code | Tell it: "Move the AnyBio org key to a server-side API route. Only use sdk_* or xuser tokens client-side." |
| Widgets don't render | Ensure `bio-provider` wraps all widgets and has valid credentials. Check browser console. |
| Cursor doesn't know AnyBio APIs | Verify `.cursorrules` is at your project root. Try `@docs` with the OpenAPI URL. |
| Authentication errors (401) | Check that you're using the right key type for the endpoint. SDK endpoints need `org_*`, widget endpoints need xuser tokens. |

## Next Steps

- [AI Prompt Templates](/docs/bioui-web/guides/ai-prompt-templates) — Copy-paste prompts for common integration tasks
- [BioUI Web Quickstart](/docs/bioui-web/quickstart) — Manual setup without AI tools
- [BioSDK Quickstart](/docs/biosdk/quickstart) — iOS native integration
- [Lovable Integration](/docs/bioui-web/guides/lovable-integration) — Lovable-specific setup