feat: ship release-ready BeatAPI client and CLI

Author: erickkkyt

.env.example

@@ -1,3 +1,4 @@
 BEATAPI_API_KEY=sk_your_key
 BEATAPI_BASE_URL=https://api.beatapi.io
-
+BEATAPI_API_KEY=
+BEATAPI_BASE_URL=https://api.beatapi.io

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run verify

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Publish npm packages
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm run verify
+      - run: npm publish --workspace beatapi-client
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: npm publish --workspace beatapi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -4,4 +4,5 @@ node_modules/
 !.env.example
 coverage/
 dist/
+*.tsbuildinfo
 .worktrees/

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-17
+
+### Added
+
+- Type-safe `beatapi-client` generated from the reviewed BeatAPI OpenAPI
+  contract.
+- `beatapi` CLI with secure login, JSON output, and stderr progress.
+- Music Video automatic and manual shot workflows.
+- Ecommerce Video task creation and asynchronous task polling.
+- File upload, usage, workflow discovery, and webhook CRUD commands.
+- Structured errors, request IDs, bounded retries, CI, package checks, and npm
+  release automation.
+
+[Unreleased]: https://github.com/erickkkyt/beatapi-cli/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/erickkkyt/beatapi-cli/releases/tag/v0.1.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Contributor Covenant Code of Conduct
+
+We are committed to a welcoming, harassment-free community for everyone.
+Contributors must communicate respectfully, accept constructive feedback, and
+focus discussion on improving BeatAPI users' experience.
+
+Unacceptable behavior includes harassment, discrimination, threats, deliberate
+exposure of private information, and publishing credentials or private user
+media.
+
+Project maintainers may remove or reject contributions and community
+participation that violate these expectations. Report conduct concerns
+privately through the repository owner's GitHub profile. Security issues belong
+in GitHub private vulnerability reporting instead of public issues.
+
+This policy is adapted from the Contributor Covenant, version 2.1.

README.md

@@ -1,44 +1,184 @@
-# BeatAPI CLI
+# BeatAPI CLI and TypeScript Client
 
-A dependency-free Node.js command-line client for BeatAPI's public asynchronous
-video workflows.
+Official command-line interface and TypeScript client for BeatAPI's public
+asynchronous AI video workflows.
 
-This is an MVP scaffold. It is local-only and marked `private` until command
-behavior, package naming, authentication UX, and release ownership are reviewed.
+The repository contains two independently publishable npm packages:
 
-## Requirements
+- [`beatapi`](./packages/cli) — a human-, script-, and agent-friendly CLI.
+- [`beatapi-client`](./packages/client) — the typed runtime client shared by the
+  CLI and the BeatAPI Codex plugin.
 
-- Node.js 20 or newer
-- `BEATAPI_API_KEY` for authenticated commands
+Both packages are generated and tested against the reviewed OpenAPI snapshot in
+[`contract/beatapi.openapi.yaml`](./contract/beatapi.openapi.yaml). The lock file
+records the exact source commit and SHA-256 digest.
+
+## Install the CLI
+
+Node.js 20.19+ or 22.12+ is required.
+
+```bash
+npm install --global beatapi
+beatapi auth login
+```
+
+`auth login` reads the API key through hidden terminal input, validates it with
+`GET /v1/usage`, and saves it in the operating system credential manager.
+
+For CI, containers, or short-lived shells:
 
 ```bash
 export BEATAPI_API_KEY="sk_your_key"
-npm link
-beatapi --help
+beatapi auth status
 ```
 
-## Commands
+Environment credentials take precedence over a saved credential. The CLI does
+not accept API keys as command-line arguments and never prints the key.
+
+## Five-minute workflow
+
+Create `music-video.json`:
+
+```json
+{
+  "images": ["https://media.example.com/reference.png"],
+  "audio_url": "https://media.example.com/song.mp3",
+  "prompt": "Cinematic nighttime performance with light trails.",
+  "language": "en",
+  "resolution": "720p",
+  "compose_mode": "auto"
+}
+```
+
+Then create and follow the task:
 
 ```bash
-beatapi workflows
+beatapi music-video create --file music-video.json
+beatapi tasks wait task_123 --interval 7000
+```
+
+Command results are formatted JSON on stdout. Polling progress and errors use
+stderr, so output can be piped to `jq`, saved, or consumed by automation.
+
+## Command reference
+
+```text
+beatapi auth login
+beatapi auth status
+beatapi auth logout
+
+beatapi workflows list
 beatapi usage
-beatapi file upload ./input.mp3
-beatapi music-video create --json ./music-video.json
-beatapi ecommerce-video create --json ./ecommerce-video.json
-beatapi task get task_123
-beatapi task wait task_123 --interval 7000 --attempts 120
+beatapi files upload ./input.mp3
+
+beatapi music-video create --file ./music-video.json
+beatapi music-video shots edit TASK SHOT --prompt "New direction"
+beatapi music-video shots edit TASK SHOT --file ./shot-edit.json
+beatapi music-video shots media TASK SHOT
+beatapi music-video compose TASK --shot SHOT_1 --shot SHOT_2
+
+beatapi ecommerce-video create --file ./ecommerce-video.json
+
+beatapi tasks get TASK
+beatapi tasks wait TASK --interval 7000 --attempts 120
+
+beatapi webhooks list
+beatapi webhooks create --file ./webhook.json
+beatapi webhooks get WEBHOOK
+beatapi webhooks update WEBHOOK --file ./webhook-update.json
+beatapi webhooks delete WEBHOOK
 ```
 
-Task creation JSON follows the canonical public contract at
-`../beatapi-examples/openapi/beatapi.yaml`.
+Use `beatapi --help` for the installed command summary. `--json` remains an
+alias for `--file` on JSON-input commands.
 
-The CLI writes machine-readable result JSON to stdout. Polling progress and
-errors go to stderr so commands can be used in scripts.
+## TypeScript client
 
-## Development
+```bash
+npm install beatapi-client
+```
+
+```ts
+import { BeatAPIClient, BeatAPIError } from "beatapi-client";
+
+const beatapi = new BeatAPIClient({
+  apiKey: process.env.BEATAPI_API_KEY,
+});
+
+try {
+  const task = await beatapi.createEcommerceVideoTask({
+    images: ["https://media.example.com/product.png"],
+    duration: 15,
+    prompt: "Fast vertical product launch ad.",
+    aspect_ratio: "9:16",
+  });
+
+  const result = await beatapi.waitForTask(task.id, {
+    intervalMs: 7_000,
+    onUpdate: ({ status }) => console.error(status),
+  });
+
+  console.log(result.output?.media);
+} catch (error) {
+  if (error instanceof BeatAPIError) {
+    console.error(error.code, error.requestId);
+  }
+  throw error;
+}
+```
+
+The client exposes every launch-contract operation: workflows, usage, file
+upload, music-video automatic and manual composition, ecommerce-video tasks,
+task polling, and webhook CRUD.
+
+Retries are bounded and opt-in through method retry options. The client
+preserves BeatAPI error code, HTTP status, request ID, details, and
+`Retry-After` information.
+
+## Security model
+
+- API keys are read from `BEATAPI_API_KEY` or an OS credential manager.
+- macOS forces the native Keychain backend, Windows uses Credential Manager,
+  and Linux uses Secret Service.
+- Unsupported systems fail closed and instruct the user to use the environment
+  variable; the CLI does not fall back to plaintext or file-based storage.
+- API keys must never be committed, placed in JSON input files, pasted into
+  issue reports, or passed as command arguments.
+- Webhook signing secrets are returned once by the API and should be stored
+  with the same care as an API key.
+
+See [SECURITY.md](./SECURITY.md) for reporting instructions.
+
+## Contract and development
 
 ```bash
-npm run check
+npm ci
+npm run contract:check
+npm run check:generated
 npm test
+npm run verify
 ```
 
+Important scripts:
+
+- `npm run contract:sync` copies the reviewed public contract snapshot.
+- `npm run generate:types` regenerates TypeScript definitions.
+- `npm run check:generated` proves generated definitions are current.
+- `npm run verify` runs contract, type, test, build, and package checks.
+
+The canonical private contract is maintained in the BeatAPI product repository.
+This public repository contains only its reviewed, publication-safe snapshot.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) before changing behavior.
+
+## Publishing
+
+GitHub Actions verifies every pull request. Publishing is triggered by a GitHub
+release or manually through the release workflow after the repository
+environment contains an `NPM_TOKEN` secret.
+
+Release steps and ownership prerequisites are documented in
+[`docs/releasing.md`](./docs/releasing.md).
+
+## License
+
+MIT

bin/beatapi.mjs

@@ -0,0 +1,38 @@
+# Release guide
+
+## One-time setup
+
+1. Create the public GitHub repository `erickkkyt/beatapi-cli`.
+2. Log in to npm with the BeatAPI publishing account.
+3. Publish or reserve both package names: `beatapi-client` and `beatapi`.
+4. In GitHub, create an environment named `npm`.
+5. Add an environment secret named `NPM_TOKEN` with publish access to both
+   packages. Keep required reviewer protection enabled for production releases.
+
+The package names were unregistered when this repository was prepared. npm
+names are first-come, first-served, so reserve them before announcing the
+release.
+
+## Release checklist
+
+1. Synchronize and review the public OpenAPI snapshot.
+2. Run `npm run verify` from a clean checkout.
+3. Confirm `npm audit --omit=dev` reports no known runtime vulnerabilities.
+4. Update `CHANGELOG.md` and both package versions together.
+5. Commit and push the release branch.
+6. Merge to `main` only after CI passes.
+7. Create a GitHub release tagged `vX.Y.Z`.
+8. Approve the protected `npm` environment deployment.
+9. Confirm both npm package pages and install the CLI in a clean temporary
+   directory.
+10. Run `beatapi --version`, `beatapi --help`, and an authenticated
+    `beatapi auth status` smoke test.
+
+## Rollback
+
+npm package versions are immutable. If a release is defective:
+
+1. Deprecate the affected version with a clear message.
+2. Publish a corrected patch release.
+3. Mark the GitHub release as superseded and link to the patch.
+4. Revoke any credential that may have entered logs or artifacts.