@audiodn/agent-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) AudioDN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @audiodn/agent-kit
+
+Install AudioDN-specific guidance for AI coding agents into any repository, and
+validate AudioDN integrations for common mistakes.
+
+```bash
+npx @audiodn/agent-kit init
+```
+
+## What it installs
+
+`init` writes guidance in the formats you select. All installs are **merge-safe**
+(they never clobber your own content) and **idempotent** (re-running reports
+`unchanged`):
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.github/copilot-instructions.md`
+- `.cursor/rules/audiodn.mdc`
+- `.agents/skills/audiodn/` — a portable Skill (references, framework templates, and a validator)
+
+Kit-owned content lives inside a managed block:
+
+```
+<!-- AUDIODN:BEGIN v0.1.0 (managed by @audiodn/agent-kit — do not edit inside) -->
+...
+<!-- AUDIODN:END -->
+```
+
+Anything outside that block is yours and is preserved.
+
+## Commands
+
+```bash
+npx @audiodn/agent-kit init                 # interactive
+npx @audiodn/agent-kit init --yes           # non-interactive (all formats)
+npx @audiodn/agent-kit init --formats agents,cursor,skill
+npx @audiodn/agent-kit init --dry-run       # preview, no writes
+npx @audiodn/agent-kit init --force         # overwrite unmanaged conflicts
+
+npx @audiodn/agent-kit validate [path]      # scan a project for AudioDN mistakes
+npx @audiodn/agent-kit validate . --json
+
+npx @audiodn/agent-kit uninstall            # remove managed blocks / kit files only
+npx @audiodn/agent-kit list                 # show formats + bundled doc versions
+```
+
+## What the validator catches
+
+Server API key exposed to client code, invented endpoints, a missing per-track
+upload request, treating an upload URL as permanent, playback before processing
+is ready, hardcoded secrets, incorrect API origin, and obsolete documentation
+URLs. See [`assets/skill/references/security.md`](assets/skill/references/security.md).
+
+## Canonical sources
+
+Guidance and the bundled OpenAPI snapshot derive from the public AudioDN docs
+(`https://audiodeliverynetwork.com/openapi.json`, `/llms-full.txt`). The snapshot
+is refreshed by `npm run sync` and pinned in
+[`assets/snapshots/sources.json`](assets/snapshots/sources.json). This repository
+never depends on the AudioDN monorepo; it only reads the public site.
+
+## Development
+
+```bash
+npm install
+npm run build     # tsc -> dist
+npm test          # vitest
+npm run smoke     # build + init into a temp dir + validate
+```
+
+## License
+
+MIT

package/assets/content/instructions.md

@@ -0,0 +1,48 @@
+# AudioDN integration guide for coding agents
+
+This project uses (or integrates with) **AudioDN** (Audio Delivery Network).
+AudioDN handles audio **upload, processing, normalization, variants, previews,
+waveforms, secure delivery, and playback**. Follow this guidance whenever you
+write or review code that touches AudioDN.
+
+## Golden rules
+
+1. **Never put server API credentials in browser or mobile code.** API Access
+   keys (Bearer tokens) belong only on a server you control. Client-side keys
+   may be used **only** where AudioDN specifically supports them (e.g. a
+   Client-Side Player/Uploader key for components).
+2. **Never invent endpoints, fields, or parameters.** Verify every operation
+   against the canonical OpenAPI document:
+   `https://audiodeliverynetwork.com/openapi.json`.
+3. **Creating an upload session is not the whole upload flow.** Each track needs
+   a **separate** request that returns that track's own upload URL.
+4. **Playback must account for processing readiness.** A freshly uploaded track
+   is not immediately playable.
+5. **Preserve existing API compatibility.** Do not change request/response
+   shapes, rename endpoints, or drop backward-compatible behavior.
+6. **Use the correct hosts.** API base is `https://api.audiodelivery.net/v1/`.
+   The marketing/docs host `audiodeliverynetwork.com` must never be used as the
+   API origin for `/v1/` requests.
+
+{{PARTIALS}}
+
+## Canonical references
+
+- OpenAPI 3.1 spec: https://audiodeliverynetwork.com/openapi.json
+- LLM-readable overview: https://audiodeliverynetwork.com/llms-full.txt
+- Docs: https://audiodeliverynetwork.com/docs
+- AI-agent guide: https://audiodeliverynetwork.com/for-ai-agents
+
+## Validate your work
+
+If this repo has the AudioDN Skill installed, run its validator before finishing:
+
+```bash
+node .agents/skills/audiodn/scripts/validate.mjs .
+```
+
+Or, with the kit:
+
+```bash
+npx @audiodn/agent-kit validate .
+```

package/assets/content/partials/auth.md

@@ -0,0 +1,17 @@
+## Authentication
+
+AudioDN uses three credential types:
+
+- **API Access key** (`Bearer` token): full server-side access. Server-only.
+  Used to create upload sessions, read track status, and create play sessions.
+- **Client-Side keys** (Player / Uploader): scoped keys safe to ship in a
+  browser or app for the web components only.
+- **Session IDs as capability tokens**: some endpoints are authorized by a
+  session ID instead of a Bearer token and take **no** Authorization header:
+  - `GET /v1/upload_session/{id}`
+  - `POST /v1/upload/{upload_session_id}/track`
+  - `GET /v1/play/{play_session_id}/{play_track_id}`
+  - `GET /v1/play/{play_session_id}/{play_track_id}/{variant_index}/download`
+
+Rule: server code holds the Bearer key; the client only ever receives a session
+ID or a finished signed URL. See `references/authentication.md` in the Skill.

package/assets/content/partials/compatibility.md

@@ -0,0 +1,10 @@
+## API compatibility
+
+AudioDN's public API is stable. When integrating or refactoring:
+
+- Do not rename endpoints, change path styles, or alter request/response shapes.
+- API paths use underscores (`/v1/upload_session`, `/v1/play_session`). HTML
+  component attributes use hyphens (`upload-session-id`).
+- Prefer additive changes; keep backward-compatible behavior intact.
+- If something seems missing, re-check the OpenAPI spec before assuming it does
+  not exist — do not invent a replacement endpoint.

package/assets/content/partials/playback.md

@@ -0,0 +1,14 @@
+## Playback and delivery
+
+Two supported ways to deliver audio, both gated by readiness:
+
+- **Play sessions**: `POST /v1/play_session/{scope}` (server, Bearer) returns
+  signed variant URLs in `first_track.variants[].url` plus waveform `levels`.
+  Fetch more tracks with `GET /v1/play/{play_session_id}/{play_track_id}` (no
+  Bearer). Best for per-listener authorization and short expiry.
+- **Signed delivery**: sign a delivery URL on your server with a URL Signing key
+  (HMAC-SHA256; the `verify` query param must be appended **last**). Skips play
+  sessions for public/entitled tracks. The signing secret is server-only.
+
+For components, pass a Client-Side Player key or a server-provisioned play
+session ID to `<audiodn-player>`. See `references/playback.md` in the Skill.

package/assets/content/partials/processing.md

@@ -0,0 +1,17 @@
+## Processing and readiness
+
+After the bytes are uploaded, AudioDN processes the track: probing, waveform
+generation, variant transcodes/previews, optional fallback processing, and cover
+extraction. This takes time, so a track is not playable the instant it uploads.
+
+Determine readiness in one of two ways:
+
+- **Poll**: `GET /v1/track/{track_id}` (server, Bearer) until
+  `track.track_status_id === 'ready'` (or a terminal state like `incomplete`,
+  `error`, `init_error`).
+- **Webhook** (preferred in production): react to the Track Processing webhook,
+  which fires on terminal outcomes / when the file set is complete — not on every
+  transitional status.
+
+Never build a playback experience that assumes a just-uploaded track is ready.
+See `references/processing.md` in the Skill.

package/assets/content/partials/security.md

@@ -0,0 +1,14 @@
+## Security
+
+- **Server key isolation**: API Access keys (Bearer) live only in server code and
+  server-side environment variables. They must never appear in browser bundles,
+  mobile apps, `public/` assets, client components, or committed files.
+- **No hardcoded secrets**: read keys and signing secrets from environment
+  variables. Never inline a literal `adn_...` key, `Bearer` token, or signing
+  secret in source.
+- **Signing secret stays server/edge-side**: URL Signing is done on your server or
+  in an edge worker; the secret is never sent to the client.
+- **Least privilege on the client**: use resource-scoped Client-Side keys and
+  short-lived, per-listener play sessions.
+
+See `references/security.md` in the Skill.

package/assets/content/partials/upload.md

@@ -0,0 +1,17 @@
+## Upload flow (do not skip steps)
+
+The upload lifecycle is multi-step. Creating a session alone uploads nothing.
+
+1. **Create an upload session** (server, Bearer):
+   `POST /v1/upload_session` -> returns `upload_session_id`. A session can hold
+   many tracks and does **not** return an upload URL by itself.
+2. **Create a track in the session** (no Bearer — the session ID authorizes it):
+   `POST /v1/upload/{upload_session_id}/track` -> returns `track_id` and a
+   per-track upload target in `track_upload.upload_url` (with `track_upload.method`).
+   Do this **once per file**.
+3. **Upload the bytes**: `PUT` the file to `track_upload.upload_url`.
+4. **Wait for readiness** before playback (see Processing).
+
+The per-track upload URL is **short-lived and single-purpose**. Never store it
+in a database, cache it, or treat it as a permanent link — mint a fresh track if
+it expires. See `references/upload-flow.md` in the Skill.

package/assets/content/partials/webhooks.md

@@ -0,0 +1,13 @@
+## Webhooks
+
+Configure webhooks in the dashboard to react to processing without polling:
+
+- **Track Processing** (`webhook_url`): fires when a track reaches a terminal
+  status (`ready`, `incomplete`, `error`, `init_error`) or when its full file set
+  is complete (`files_completed_at`) — not on transitional statuses.
+- **Track File** (`webhook_url_file`): fires once per track file with a status of
+  `success`/`failed`.
+- **Collection Sync**: collection create/update/delete events.
+
+Verify webhook authenticity and make handlers idempotent (deliveries can retry).
+See `references/webhooks.md` in the Skill.

package/assets/skill/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: audiodn
+description: Use when integrating AudioDN (Audio Delivery Network) — audio upload, processing, variants/previews, waveforms, secure delivery, and playback. Covers auth boundaries, the multi-step upload flow, processing readiness, playback, webhooks, and security, plus a validator for common mistakes.
+---
+
+# AudioDN integration skill
+
+Use this skill whenever you write or review code that uploads, processes,
+delivers, or plays audio through AudioDN. Read the relevant reference before
+implementing, and run the validator before you finish.
+
+## Non-negotiable rules
+
+1. Server API credentials (Bearer / API Access keys) never appear in browser or
+   mobile code. Client-side keys only where AudioDN supports them.
+2. Never invent endpoints, fields, or params. Verify against the canonical
+   OpenAPI: https://audiodeliverynetwork.com/openapi.json
+3. Creating an upload session is not the whole upload. Each track needs a
+   separate request that returns its own `track_upload.upload_url`.
+4. Playback must wait for processing readiness.
+5. Preserve existing API compatibility (paths use underscores; no shape changes).
+6. API host is `https://api.audiodelivery.net/v1/`; never use the marketing host
+   `audiodeliverynetwork.com` for `/v1/` calls.
+
+## References (read as needed)
+
+- `references/authentication.md` — key types and which endpoints are session-gated.
+- `references/upload-flow.md` — session -> per-track -> PUT -> readiness.
+- `references/processing.md` — statuses and readiness detection.
+- `references/playback.md` — play sessions and signed delivery.
+- `references/webhooks.md` — track/file/collection webhooks.
+- `references/security.md` — secret handling and the validator's rules.
+
+## Framework templates
+
+Copy-adapt the correct server/client boundary for your stack:
+
+- `templates/nextjs.md`
+- `templates/vue-nuxt.md`
+- `templates/cloudflare-worker.md`
+- `templates/node-server.md`
+
+## Validate before finishing
+
+```bash
+node .agents/skills/audiodn/scripts/validate.mjs .
+```
+
+Fix every error (exit code is non-zero while errors remain) and review warnings.
+The validator checks: server key in client code, invented endpoints, missing
+per-track request, permanent upload URL, playback before ready, hardcoded
+secrets, incorrect API origin, and obsolete documentation URLs.

package/assets/skill/references/authentication.md

@@ -0,0 +1,27 @@
+# Authentication reference
+
+## Credential types
+
+- **API Access key** — `Authorization: Bearer <key>`. Full server-side access.
+  Server-only. Used to create upload sessions, read track status, create play
+  sessions, and manage resources.
+- **Client-Side keys** (Player / Uploader) — scoped keys safe to ship to a
+  browser/app, but ONLY for the AudioDN web components.
+- **Session IDs as capability tokens** — some endpoints are authorized purely by
+  a session ID in the path and take NO `Authorization` header.
+
+## Session-gated endpoints (no Bearer)
+
+- `GET  /v1/upload_session/{upload_session_id}`
+- `POST /v1/upload/{upload_session_id}/track`
+- `GET  /v1/play/{play_session_id}/{play_track_id}`
+- `GET  /v1/play/{play_session_id}/{play_track_id}/{variant_index}/download`
+
+## Rules
+
+- The browser holds only a Client-Side key or a session ID/signed URL provisioned
+  by your server.
+- Read keys from environment variables; never hardcode them.
+- Errors use `{ ok: false, message, api_request_id }` with 400/401/404/500.
+
+Canonical: https://audiodeliverynetwork.com/docs/api and `/openapi.json`.

package/assets/skill/references/playback.md

@@ -0,0 +1,29 @@
+# Playback reference
+
+Two supported delivery paths, both gated by readiness.
+
+## Play sessions (per-listener)
+
+`POST /v1/play_session/{scope}` (server, Bearer), scope `track` or `collection`:
+
+- Body: `{ track_id | collection_id, variants?, expires_in?, is_downloadable? }`.
+- Returns signed variant URLs in `first_track.variants[].url` and waveform data
+  in `first_track.levels`.
+- Fetch more tracks: `GET /v1/play/{play_session_id}/{play_track_id}` (no Bearer).
+- Downloads: `GET /v1/play/{play_session_id}/{play_track_id}/{variant_index}/download`
+  (only if the session is downloadable).
+
+## Signed delivery (public/entitled, no session)
+
+Sign a delivery URL on your server with a URL Signing key (HMAC-SHA256). The
+`verify` query parameter must be appended LAST. The signing secret is
+server/edge-only. Skips play sessions for public tracks.
+
+## Components
+
+Pass a Client-Side Player key or a server-provisioned play session ID to
+`<audiodn-player>`. Do not embed a server key.
+
+Canonical: https://audiodeliverynetwork.com/docs/api/play-sessions and
+`/docs/integration/signed-delivery`.
+OpenAPI operationIds: `createPlaySession`, `getPlayTrack`, `downloadPlayTrackVariant`.

package/assets/skill/references/processing.md

@@ -0,0 +1,23 @@
+# Processing reference
+
+After the bytes upload, AudioDN processes the track (probe, waveform, variants,
+optional fallback processing, cover extraction). A track is not immediately
+playable.
+
+## Detect readiness
+
+- **Poll** (server, Bearer): `GET /v1/track/{track_id}` until
+  `track.track_status_id === 'ready'`. Terminal states also include
+  `incomplete` (some variants failed but at least one plays), `error`,
+  `init_error`.
+- **Webhook** (preferred): the Track Processing webhook fires on terminal
+  outcomes / when the file set is complete (`files_completed_at`), not on every
+  transitional status.
+
+## Statuses you may observe
+
+`processing`, `fallback_processing` (retry on higher-capacity worker), then a
+terminal state. Do not assume a just-uploaded track is `ready`.
+
+Canonical: https://audiodeliverynetwork.com/docs and `/docs/webhooks/track-processing`.
+OpenAPI operationId: `getTrack`.

package/assets/skill/references/security.md

@@ -0,0 +1,30 @@
+# Security reference
+
+## Principles
+
+- **Server key isolation**: API Access keys (Bearer) live only in server code and
+  server-side env vars. Never in browser bundles, mobile apps, `public/` assets,
+  client components, or committed files.
+- **No hardcoded secrets**: read keys and signing secrets from environment
+  variables. Never inline an `adn_...` key, `Bearer` token, or signing secret.
+- **Signing secret stays server/edge-side**: URL signing happens on your server
+  or an edge worker; the secret is never sent to the client.
+- **Least privilege on the client**: resource-scoped Client-Side keys and
+  short-lived, per-listener play sessions.
+
+## What the validator enforces
+
+The bundled `scripts/validate.mjs` flags:
+
+- `server-key-in-client` (error) — server credential referenced in client code.
+- `invented-endpoint` (error) — `/v1/...` path not in the OpenAPI.
+- `missing-per-track-request` (warn) — session created, no per-track upload URL.
+- `upload-url-treated-permanent` (warn) — `upload_url` persisted/cached.
+- `playback-before-ready` (warn) — playback with no readiness gate.
+- `hardcoded-secret` (error) — literal key/secret in source.
+- `incorrect-api-origin` (error) — wrong host for `/v1/` (e.g. marketing host).
+- `obsolete-doc-url` (warn) — deprecated paths/params (`/v1/upload-session`,
+  `ttl_seconds`, `session.url`, docs-on-API-host, etc.).
+
+Configure exceptions in `.audiodn-validate.json` (`{ "ignore": [], "ignoreFiles": [] }`)
+or add `audiodn-validate-ignore` on a specific line.

package/assets/skill/references/upload-flow.md

@@ -0,0 +1,29 @@
+# Upload-flow reference
+
+The upload lifecycle is multi-step. A session alone uploads nothing.
+
+## Steps
+
+1. **Create upload session** (server, Bearer)
+   `POST /v1/upload_session` with optional `{ collection_id }`.
+   Returns `upload_session_id`. Holds many tracks; returns no upload URL.
+
+2. **Create a track in the session** (no Bearer)
+   `POST /v1/upload/{upload_session_id}/track` with `{ file_name }`.
+   Returns `track_id` and `track_upload` = `{ method, upload_url }`.
+   Do this once per file.
+
+3. **Upload the bytes**
+   `PUT` the file to `track_upload.upload_url` using `track_upload.method`.
+   Processing begins automatically once the PUT completes.
+
+4. **Wait for readiness** (see processing.md) before playback.
+
+## Critical
+
+- The per-track `upload_url` is short-lived and single-use. Never store it in a
+  DB, cache, or config; if it expires, create a fresh track and retry.
+- The session-create step does NOT return `upload_url` — do not expect one.
+
+Canonical: https://audiodeliverynetwork.com/docs/api/upload-sessions
+OpenAPI operationIds: `createUploadSession`, `createUploadSessionTrack`.

package/assets/skill/references/webhooks.md

@@ -0,0 +1,19 @@
+# Webhook reference
+
+Configure webhooks in the dashboard to react to processing without polling.
+
+- **Track Processing** (`webhook_url`): fires when a track reaches a terminal
+  status (`ready`, `incomplete`, `error`, `init_error`) or when its file set is
+  complete (`files_completed_at`) — not on transitional statuses.
+- **Track File** (`webhook_url_file`): fires once per track file with a status of
+  `success`/`failed` (`track_file.created` / `track_file.failed`).
+- **Collection Sync**: collection create/update/delete events.
+
+## Handler rules
+
+- Make handlers idempotent — deliveries can retry.
+- Verify authenticity before trusting the payload.
+- Use the terminal event to advance your own workflow (mark ready, notify user).
+
+Canonical: https://audiodeliverynetwork.com/docs/webhooks/track-processing,
+`/docs/webhooks/track-files`, `/docs/webhooks/collection-sync`.

package/assets/skill/scripts/known-endpoints.json

@@ -0,0 +1,28 @@
+{
+  "note": "Canonical AudioDN v1 path templates. Regenerated from the public OpenAPI by scripts/sync-canonical.mjs. Used by validate.mjs to detect invented endpoints.",
+  "openapiVersion": "1.0.0",
+  "apiBase": "https://api.audiodelivery.net/v1",
+  "paths": [
+    "/v1/api_key",
+    "/v1/collection",
+    "/v1/collection/{collection_id}",
+    "/v1/collection/{collection_id}/cover",
+    "/v1/collection/{collection_id}/track",
+    "/v1/creator",
+    "/v1/creator/{creator_id}",
+    "/v1/organization/{organization_id}",
+    "/v1/play/{play_session_id}/{play_track_id}",
+    "/v1/play/{play_session_id}/{play_track_id}/{variant_index}/download",
+    "/v1/play_session/{play_session_id}",
+    "/v1/play_session/{scope}",
+    "/v1/track",
+    "/v1/track/{track_id}",
+    "/v1/track/{track_id}/cover",
+    "/v1/track/{track_id}/variant",
+    "/v1/upload/{upload_session_id}/track",
+    "/v1/upload_session",
+    "/v1/upload_session/{upload_session_id}",
+    "/v1/variant",
+    "/v1/variant/{variant_id}"
+  ]
+}