amazon-kdp

Amazon KDP Automation

Self-contained skill repo with a local Express + Playwright server. Amazon has no public KDP metadata API — this uses saved browser session cookies to call KDP's internal pages and report endpoints.

Agent responsibilities

You run everything. Do not ask the user to run terminal commands.

Ensure setup: npm install, copy .env.example → .env if missing.
Start the server if not running: npm run server:start (background).
Check session before any sync/update/download: npm run status.
Run all KDP tasks yourself via npm scripts or the local REST API.
Only pause for the user during Amazon login — they must complete sign-in (incl. MFA) in the visible Chromium window. Poll npm run status until connected: true.

Session persists in .kdp-session/ (gitignored).

Sequential operations (required)

When the user asks for multiple books or multiple write tasks, process them one at a time — never in parallel and never in a single batch request.

Do:

Complete one book (or one metadata/pricing/content update) fully before starting the next
Use single-book endpoints: /api/kdp/metadata/update, /api/kdp/pricing/update, /api/kdp/content/upload, /api/kdp/publish — one HTTP call per book
Run npm run publish:book -- spec.json --live once per title; generate a separate spec JSON per book if needed
Wait for each call to finish (publish can take several minutes) and verify the result before continuing
If a step fails, stop or fix that book before moving on — do not fire the rest of the queue blindly

Do not:

Create batch scripts that loop inside one long-running process without user approval
Call batch API routes (/batch endpoints) for multiple titles in one request
Run multiple publish/upload commands in parallel or in background at the same time
Open more than one Playwright browser session for KDP writes at once

This avoids HTTP timeouts, Amazon "Server Busy" rate limits, and browser/session conflicts. Batch endpoints exist for advanced use only; agents should default to sequential single-book calls.

Sub-skills — read the matching file before acting

Task	Skill file
Sign in / session status	skills/connect-session/SKILL.md
Account info + reports catalog	skills/account-info/SKILL.md
Download royalty reports	skills/download-reports/SKILL.md
Parse royalty Excel → JSON summary	skills/parse-reports/SKILL.md
Pull book metadata (all or one)	skills/sync-metadata/SKILL.md
Export metadata to Excel	skills/export-metadata/SKILL.md
Audit metadata (keywords, categories)	skills/analyze-metadata/SKILL.md
Push listing changes (details page)	skills/update-metadata/SKILL.md
Push pricing / KDP Select	skills/update-pricing/SKILL.md
Upload interior / cover PDFs	skills/upload-content/SKILL.md
Full publish wizard (create → publish)	skills/publish-book/SKILL.md

Quick commands (agent runs these)

npm run status                    # session connected?
npm run account:info              # catalog size, vendor code
npm run bookshelf:list            # fast title/format refs
npm run catalog:get               # all titles + ASINs from kdpreports
npm run download:report           # lifetime royalties → output/
npm run parse:report -- file.xlsx # summarize royalties
npm run sync:metadata             # full Bookshelf scrape → cache
npm run sync:book -- ID paperback # refresh one book
npm run metadata:get              # print cached JSON
npm run metadata:export           # cache → Excel
npm run metadata:analyze          # keyword/category audit
npm run update:metadata -- file.json --dry-run
npm run publish:book -- examples/publish-book.example.json

Architecture

Browser session (.kdp-session/amazon-kdp.json)
        ↓
Local server (server/src/index.ts) — REST API
        ↓
Playwright session cookies
        ↓
Request-first: kdpreports JSON APIs → HTML GET + parse → browser fallback
        ↓
Global rate limit (KDP_REQUEST_DELAY_MS between every request)

Read operations

Operation	Endpoint / command
Session status	`GET /api/kdp/status`
Account info	`GET /api/kdp/account`
Reports catalog	`GET /api/kdp/catalog`
Bookshelf list (fast)	`GET /api/kdp/bookshelf`
Metadata cache	`GET /api/kdp/metadata`
Full metadata sync	`POST /api/kdp/metadata/sync`
Single book sync	`POST /api/kdp/metadata/sync/:titleId/:format`
Metadata audit	`GET /api/kdp/metadata/analyze`
Lifetime royalties	`POST /api/kdp/sync`
Date-range royalties	`POST /api/kdp/reports/download`

Write operations

Operation	Endpoint
Update details (keywords, description, author, flags)	`POST /api/kdp/metadata/update`
Batch metadata update	`POST /api/kdp/metadata/update/batch`
Update pricing / KDP Select	`POST /api/kdp/pricing/update`
Batch pricing update	`POST /api/kdp/pricing/update/batch`
Upload interior/cover	`POST /api/kdp/content/upload`
Batch upload	`POST /api/kdp/content/upload/batch`
Create new title	`POST /api/kdp/titles/create`
Update categories	`POST /api/kdp/categories/update`
Full publish wizard	`POST /api/kdp/publish`
Unpublish live title	`POST /api/kdp/titles/unpublish`
Delete draft	`POST /api/kdp/titles/delete`
Archive title	`POST /api/kdp/titles/archive`
Recovery learnings	`GET /api/kdp/recovery/learnings`

Always dry-run one book before live writes on additional books. Never set publish: true without explicit user confirmation.

Batch REST endpoints (/batch) are for manual/advanced use. Agents must not use them for multi-book work — call the single-book endpoint repeatedly, one title at a time, waiting for each to complete.

Automatic error recovery

Write flows (details save, content upload, pricing, publish wizard) retry with recovery when KDP blocks progress:

Built-in playbook: dismiss modals, set release date, approve manuscript preview, select cover upload accordion, bypass Server Busy, wait for processing, etc.
Learnings file: .kdp-session/recovery-learnings.json — successful error→action pairs are ranked higher on future runs.
Publish API responses may include recoveryLog describing what was tried.

If recovery exhausts retries, read errors and recoveryLog, then fix the underlying issue (e.g. invalid cover PDF dimensions).

Rules for agents

Always check session (npm run status) before sync/update. If connected: false, run login sub-skill first.
One operation at a time for writes — see Sequential operations. No batch scripts, no parallel publishes, no /batch API for multiple titles.
Never commit .kdp-session/ or downloaded .xlsx files.
Rate limiting: the server spaces every KDP page load and API call by KDP_REQUEST_DELAY_MS (default 4s). Do not bypass this.
Metadata/pricing updates: dry-run one book, then apply live changes one book per request.
Verify saves by re-reading metadata from KDP (built into update flows).
Categories: writable via browse node IDs or modal path picker (POST /api/kdp/categories/update or publish wizard).
Publish: use npm run publish:book dry-run first; live publish requires "publish": true and user confirmation. One book per publish:book invocation.

References

references/api-endpoints.md — REST API
references/metadata-fields.md — scraped book shape
references/troubleshooting.md — Server Busy, auth, pagination