# Demeter Example Applications

Runnable examples that use the
[`@demeter/api-client`](../../../libs/demeter/api-client) SDK against a live
Demeter API. They double as copy-paste starting points for your own
integrations.

## Prerequisites

- A running Demeter API (`pnpm --filter @demeter/api dev`, or a deployed URL).
  See [local development setup](../docs/development/local-development.md).
- `tsx` to run TypeScript directly (`npx tsx <file>`).

## Examples

| File                                   | Auth                            | Shows                                                                               |
| -------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| [`quickstart.ts`](quickstart.ts)       | User (login + refresh rotation) | Sign in, create a garden, list gardens, read one back                               |
| [`sensor-ingest.ts`](sensor-ingest.ts) | Machine (API key)               | Push a batch of sensor readings — the SDK equivalent of a DIY device's MQTT publish |

## Run

```bash
# Quickstart (user auth)
DEMETER_API_URL=http://localhost:3030 \
DEMETER_EMAIL=me@example.com DEMETER_PASSWORD=secret \
npx tsx apps/demeter/examples/quickstart.ts

# Sensor ingest (API-key auth)
DEMETER_API_URL=http://localhost:3030 \
DEMETER_API_KEY=dk_xxx DEMETER_SENSOR_ID=<uuid> DEMETER_SAMPLE_VALUE=27.4 \
npx tsx apps/demeter/examples/sensor-ingest.ts
```

## What to notice

- **Token rotation:** `quickstart.ts` passes `onTokensRefreshed` so you can
  persist the rotated pair — refresh tokens are single-use.
- **Two auth modes:** user flows use a Bearer JWT; machine flows use a scoped
  API key (`X-API-Key`). See
  [building on the API](../docs/development/building-on-the-api.md).
- **Typed errors:** both examples catch `DemeterApiError` and read its `status`.

For deeper background see the [API reference](../docs/api/README.md) and the
[data models](../docs/data-models.md).
