feat: align examples with production contract

Author: erickkkyt

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## What changed
+
+Describe the developer-facing behavior this pull request changes.
+
+## Contract impact
+
+- [ ] No public API contract change
+- [ ] OpenAPI was changed in the private service repository and synchronized
+- [ ] Fixtures and examples were updated to match the contract
+
+## Verification
+
+- [ ] `npm run verify`
+- [ ] `npm run check:openapi-sync` when the service repository is available
+- [ ] `npm run smoke:live` for changes that affect public HTTP behavior
+- [ ] No API keys, webhook secrets, private media URLs, or customer data added

.github/workflows/live-smoke.yml

@@ -0,0 +1,27 @@
+name: Live read-only smoke
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 3 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      BEATAPI_API_KEY: ${{ secrets.BEATAPI_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22.12"
+          cache: npm
+
+      - run: npm ci
+      - run: npm run smoke:live

.github/workflows/verify.yml

@@ -11,13 +11,17 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ["20.19", "22.12"]
 
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: ${{ matrix.node-version }}
           cache: npm
 
       - uses: actions/setup-python@v5

CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our standard
+
+BeatAPI welcomes developers of every background and experience level. Be
+respectful, assume good intent, give actionable technical feedback, and keep
+discussions focused on improving developer integrations.
+
+Unacceptable behavior includes harassment, discrimination, threats, publishing
+private information, sharing credentials or customer data, and repeatedly
+disrupting project discussions.
+
+## Scope
+
+This standard applies to repository issues, pull requests, discussions, and
+other spaces where someone is representing the BeatAPI project.
+
+## Reporting
+
+Report conduct concerns privately to support@beatapi.io. Do not use a public
+issue when a report contains personal information, credentials, security
+details, or customer data.
+
+Project maintainers may edit or remove contributions and may temporarily or
+permanently restrict participation when behavior is unsafe or disruptive.

README.md

@@ -2,6 +2,8 @@
 
 Official runnable examples for the BeatAPI async AI video API.
 
+[![Verify examples](https://github.com/erickkkyt/beatapi-examples/actions/workflows/verify.yml/badge.svg)](https://github.com/erickkkyt/beatapi-examples/actions/workflows/verify.yml)
+
 [Website](https://beatapi.io/) ·
 [API documentation](https://docs.beatapi.io/) ·
 [Music Video Playground](https://beatapi.io/music-video-api) ·
@@ -17,6 +19,17 @@ The primary launch route is `POST /v1/music-video/tasks`.
 Create task -> queued/processing -> succeeded/failed -> hosted output
 ```
 
+```mermaid
+flowchart LR
+  A["Create task"] --> B["queued / processing"]
+  B --> C{"Final state?"}
+  C -->|No| D["Wait 5-10 seconds"]
+  D --> E["GET /v1/tasks/{task_id}"]
+  E --> C
+  C -->|succeeded| F["Read output.media"]
+  C -->|failed| G["Inspect error_code and usage"]
+```
+
 > This repository contains examples and a small reference client. It is not a
 > versioned SDK and it does not contain the BeatAPI service implementation.
 
@@ -41,7 +54,8 @@ curl https://api.beatapi.io/v1/music-video/tasks \
     "prompt": "Neon rooftop performance with cinematic light trails.",
     "language": "en",
     "aspect_ratio": "9:16",
-    "resolution": "720p"
+    "resolution": "720p",
+    "compose_mode": "auto"
   }'
 ```
 
@@ -78,7 +92,8 @@ are available in `data.output.media`.
 
 ### Node.js
 
-Requires Node.js 20 or newer. No install step is required.
+The dependency-free examples require Node.js 20 or newer. Repository
+verification requires Node.js 20.19+ or 22.12+.
 
 ```bash
 node examples/node/music-video.mjs
@@ -157,6 +172,7 @@ credit, or concurrency errors.
 Webhook requests include:
 
 ```text
+X-BeatAPI-Event
 X-BeatAPI-Signature
 X-BeatAPI-Timestamp
 ```
@@ -165,14 +181,28 @@ Verify the signature against the exact raw request body before parsing JSON,
 and reject timestamps older than five minutes. The Node.js receiver example
 implements HMAC-SHA256 verification with a constant-time comparison.
 
+The signed JSON body uses `event`, not `type`:
+
+```json
+{
+  "id": "evt_example_123",
+  "event": "task.succeeded",
+  "created_at": 1784188934,
+  "data": {
+    "id": "task_8K2qA",
+    "status": "succeeded"
+  }
+}
+```
+
 ```bash
 export BEATAPI_WEBHOOK_SECRET="whsec_your_secret"
 node examples/node/webhook-server.mjs
 ```
 
 ## Integration guides
 
-- [n8n](integrations/n8n/README.md)
+- [n8n guide and importable bounded-polling workflow](integrations/n8n/README.md)
 - [Postman](integrations/postman/README.md)
 - [Sanitized response fixtures](fixtures/)
 - [Production API reference](https://docs.beatapi.io/)
@@ -202,6 +232,24 @@ npm run test:python
 npm run verify
 ```
 
+The public OpenAPI file is synchronized byte-for-byte from the private service
+repository:
+
+```bash
+npm run sync:openapi
+npm run check:openapi-sync
+```
+
+Run a read-only production smoke test with:
+
+```bash
+npm run smoke:live
+```
+
+Without `BEATAPI_API_KEY`, it checks anonymous workflow discovery. When the
+environment variable is present, it additionally verifies authenticated
+`GET /v1/usage`. The smoke test never creates tasks or consumes credits.
+
 ## License
 
 Original example code in this repository is available under the

SECURITY.md

@@ -5,10 +5,13 @@
 Do not open a public issue for vulnerabilities, exposed API keys, authentication
 problems, webhook bypasses, credit issues, or customer data.
 
-Report security concerns privately through the contact method listed on
-[beatapi.io](https://beatapi.io/). Include the affected endpoint, impact,
-reproduction steps, and relevant request IDs. Remove API keys, webhook secrets,
-personal data, and private media URLs from the report.
+Report security concerns privately by emailing support@beatapi.io. Include the
+affected endpoint, impact, reproduction steps, and relevant request IDs. Remove
+API keys, webhook secrets, personal data, and private media URLs from the
+report.
+
+GitHub private vulnerability reporting can be enabled when this repository
+becomes public. Until then, do not use a public issue for a security report.
 
 ## API key exposure
 

examples/curl/music-video.sh

@@ -14,5 +14,6 @@ curl --fail-with-body --silent --show-error \
     "prompt": "Neon rooftop performance with cinematic light trails.",
     "language": "en",
     "aspect_ratio": "9:16",
-    "resolution": "720p"
+    "resolution": "720p",
+    "compose_mode": "auto"
   }'

examples/node/lib/webhook.mjs

@@ -1,5 +1,11 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 
+export function describeBeatAPIWebhookEvent(payload) {
+  const event = payload?.event || "unknown event";
+  const taskId = payload?.data?.id || "unknown task";
+  return `${event} for ${taskId}`;
+}
+
 export function verifyBeatAPIWebhook({
   rawBody,
   secret,

examples/node/music-video.mjs

@@ -11,6 +11,7 @@ try {
     language: "en",
     aspect_ratio: "9:16",
     resolution: "720p",
+    compose_mode: "auto",
   });
 
   console.log(`Created ${created.id}`);