# Tidings

> Tidings is lightweight product analytics: your application POSTs JSON events
> to one HTTP endpoint, and your team reads them as live feeds, user
> histories, and dashboards. There is no SDK — the whole integration is one
> POST request.

## API

- Endpoint: POST /api/v1/events/ (base URL: your Tidings instance, e.g. https://api.tidingshq.com)
- Auth: per-project API key in the X-API-Key header. Keys are prefixed td_ and managed in the app under Settings -> API keys. Revoking a key stops ingestion immediately.
- Single event: {"name": "<snake_case>", "distinct_id": "<stable id>", "properties": {<any JSON>}, "timestamp": "<optional ISO 8601>"}
- name and distinct_id are required; timestamp defaults to arrival time; properties defaults to {}.
- Batch: {"events": [<up to 500 events>]} in one request.
- Responses: 202 {"accepted": n} on success; 400 invalid payload; 401 missing/unknown/revoked key; 429 rate limited.
- Backfills: send past timestamps and events file into history where they belong.

## Integration prompt

The following prompt makes an AI coding assistant integrate Tidings into a codebase:

Integrate Tidings product analytics into this codebase.

Tidings is an event-analytics service. The whole integration is plain HTTP — there is no SDK to install.

API contract:
- POST $TIDINGS_API/api/v1/events/ with headers "Content-Type: application/json" and "X-API-Key: $TIDINGS_KEY".
- Single event body: {"name": "<snake_case_event>", "distinct_id": "<stable user or visit id>", "properties": {<arbitrary JSON>}, "timestamp": "<optional ISO 8601, defaults to arrival time>"}.
- Batch body: {"events": [<up to 500 event objects>]}.
- Success is HTTP 202 with {"accepted": n}. 400 = invalid payload, 401 = missing/revoked key, 429 = rate limited.

Requirements:
1. Create a small tracking helper in this project's language and house style, exposing track(name, properties).
2. Read the endpoint and key from configuration or environment (TIDINGS_API, TIDINGS_KEY). If the key is unset, every call must silently no-op.
3. Analytics must never break the product: swallow all errors, never throw, and never block the caller — fire-and-forget (use keepalive / background delivery where the platform offers it).
4. Choose a stable distinct_id: the signed-in user's id where available, otherwise a session-scoped identifier. Do not write persistent identifiers to end users' devices without consent — a session-scoped id keeps the integration cookieless.
5. Instrument this app's 3-5 most meaningful events (signup, core action completed, purchase, ...) plus page or screen views where relevant. Name events in snake_case.
6. Keep property payloads small and free of secrets or personal data beyond what is needed.

When done, list the events you instrumented and where the calls live.

## Links

- Documentation: /docs
- Privacy: /privacy
- Terms: /terms