---
description: Integrate Podnivo podcast catalog, search, listener state, and events
globs: "**/*.{ts,tsx,js,jsx,java,kt,swift,py,go,rb,php,cs,rs}"
alwaysApply: false
---

# Podnivo rules

Before coding, read:

- Complete guide: https://api.podnivo.com/ai/INTEGRATION.md
- Authoritative OpenAPI: https://api.podnivo.com/v3/api-docs
- Interactive reference: https://api.podnivo.com/scalar

If the sources cannot be reached, ask the developer to attach them. Never guess an endpoint, field, enum, or status code.

- Read `PODNIVO_BASE_URL` and server-only `PODNIVO_API_KEY` from environment configuration; authenticate with `Authorization: Bearer <token>`.
- Never expose a `pb_live_` key in public clients, source control, logs, analytics, or prompts. Mint short-lived listener tokens server-side with `POST /v1/user-tokens`.
- Preserve `page.next` exactly as `after`; IDs and cursors are opaque strings.
- Reuse project HTTP, timeout, validation, error, and test patterns.
- Handle 400/401/403/404/409/429/5xx, honor `Retry-After`, and never blindly retry `POST`.
- Verify webhook HMAC signatures using the raw body and deduplicate event IDs.
- Do not mirror publisher audio without rights. Use only permission-aware transcripts returned by the API.

Core routes include `/v1/search`, `/v1/search/suggestions`, `/v1/podcasts/{id}`, `/v1/podcasts/{id}/episodes`, `/v1/episodes/{id}`, `/v1/user-tokens`, `/v1/users/{userId}/home`, `/v1/users/{userId}/progress/{episodeId}`, and `/v1/changes`.

The full route directory, scopes, listener-token flow, webhook algorithm, quotas, errors, retries, privacy rules, and completion checklist live in the guide above. Add focused tests and report whether verification used a mock, local service, or live API.