amazon-kdp

Amazon KDP 自動化

ローカルの Express ＋ Playwright サーバーを備えた、自己完結型のスキルリポジトリです。Amazon には 公開されている KDP メタデータ API がありません。このツールでは、保存済みのブラウザーセッション Cookie を使って KDP の内部ページとレポートエンドポイントを呼び出します。

エージェントの責任

すべての操作を実行してください。 ユーザーにターミナルコマンドの実行を依頼してはいけません。

1. セットアップを確認します：npm install を実行し、.env が存在しない場合は .env.example を .env にコピーします。
2. サーバーが起動していない場合は起動します：npm run server:start（バックグラウンドで実行）。
3. 同期、更新、ダウンロードの前にセッションを確認します：npm run status を実行します。
4. npm スクリプトまたはローカル REST API を使って、KDP のタスクをすべて実行します。
5. ユーザーの操作が必要なのは、Amazon へのログイン時のみです。ユーザーは、表示されている Chromium ウィンドウでサインイン（MFA を含む）を完了する必要があります。connected: true になるまで npm run status をポーリングします。

セッションは .kdp-session/ に保持されます（gitignore 対象）。

順次実行（必須）

ユーザーから複数の本、または複数の書き込みタスクを依頼された場合は、一度に 1 件ずつ処理してください。並列で実行したり、1 回のバッチリクエストで処理したりしてはいけません。

実行すること：

• 次の本に取りかかる前に、1 冊（または 1 件のメタデータ／価格／コンテンツ更新）を最後まで完了します。
• 1 冊用のエンドポイントを使用します：/api/kdp/metadata/update、/api/kdp/pricing/update、/api/kdp/content/upload、/api/kdp/publish。本ごとに HTTP 呼び出しを 1 回行います。
• npm run publish:book -- spec.json --live はタイトルごとに 1 回実行します。必要に応じて、本ごとに個別の spec JSON を生成します。
• 各呼び出しが完了するまで待ち（公開には数分かかる場合があります）、結果を確認してから続行します。
• 手順が失敗した場合は、先に進まず停止するか、その本の問題を修正します。残りの処理を確認せずに実行してはいけません。

実行しないこと：

• ユーザーの承認なしに、1 つの長時間実行プロセス内でループするバッチスクリプトを作成する。
• 1 回のリクエストで複数のタイトルを処理するバッチ API ルート（/batch エンドポイント）を呼び出す。
• 複数の公開／アップロードコマンドを並列または同時にバックグラウンドで実行する。
• KDP への書き込み中に、Playwright のブラウザーセッションを複数同時に開く。

これにより、HTTP タイムアウト、Amazon の「Server Busy」レート制限、ブラウザー／セッションの競合を防げます。バッチエンドポイントは高度な用途のためにのみ用意されています。エージェントは、デフォルトで 1 冊ずつ順次呼び出してください。

サブスキル — 操作の前に該当するファイルを読む

タスク	スキルファイル
サインイン／セッション状態	skills/connect-session/SKILL.md
アカウント情報＋レポート一覧	skills/account-info/SKILL.md
ロイヤリティレポートをダウンロード	skills/download-reports/SKILL.md
ロイヤリティの Excel を解析 → JSON の要約	skills/parse-reports/SKILL.md
書籍のメタデータを取得（すべて、または 1 冊）	skills/sync-metadata/SKILL.md
メタデータを Excel にエクスポート	skills/export-metadata/SKILL.md
メタデータを監査（キーワード、カテゴリ）	skills/analyze-metadata/SKILL.md
商品ページの掲載情報を更新	skills/update-metadata/SKILL.md
価格／KDP Select を更新	skills/update-pricing/SKILL.md
本文／表紙の PDF をアップロード	skills/upload-content/SKILL.md
公開ウィザード全体（作成 → 公開）	skills/publish-book/SKILL.md

クイックコマンド（エージェントが実行）

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

アーキテクチャ

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)

読み取り操作

操作	エンドポイント／コマンド
セッションの状態	GET /api/kdp/status
アカウント情報	GET /api/kdp/account
レポートカタログ	GET /api/kdp/catalog
本棚一覧（高速）	GET /api/kdp/bookshelf
メタデータキャッシュ	GET /api/kdp/metadata
メタデータの完全同期	POST /api/kdp/metadata/sync
1 冊の同期	POST /api/kdp/metadata/sync/:titleId/:format
メタデータ監査	GET /api/kdp/metadata/analyze
全期間のロイヤリティ	POST /api/kdp/sync
期間指定のロイヤリティ	POST /api/kdp/reports/download

書き込み操作

操作	エンドポイント
詳細情報の更新（キーワード、説明、著者、フラグ）	POST /api/kdp/metadata/update
メタデータの一括更新	POST /api/kdp/metadata/update/batch
価格／KDP Select の更新	POST /api/kdp/pricing/update
価格の一括更新	POST /api/kdp/pricing/update/batch
本文／表紙のアップロード	POST /api/kdp/content/upload
一括アップロード	POST /api/kdp/content/upload/batch
新しいタイトルの作成	POST /api/kdp/titles/create
カテゴリの更新	POST /api/kdp/categories/update
公開ウィザード全体	POST /api/kdp/publish
公開中のタイトルの非公開化	POST /api/kdp/titles/unpublish
下書きの削除	POST /api/kdp/titles/delete
タイトルのアーカイブ	POST /api/kdp/titles/archive
復旧に関する学習内容	GET /api/kdp/recovery/learnings

追加の書籍に対して本番環境で書き込みを行う前に、必ず 1 冊でドライランを実施してください。明示的なユーザー確認なしに publish: true を設定しないでください。

一括 REST エンドポイント（/batch）は手動または上級者向けです。エージェントは複数の書籍に対する作業に使用してはいけません。1 タイトルずつ、単一書籍用エンドポイントを繰り返し呼び出し、それぞれの完了を待ってください。

自動エラー復旧

書き込みフロー（詳細の保存、コンテンツのアップロード、価格設定、公開ウィザード）では、KDP によって処理がブロックされた場合、復旧を試みながら再試行します。

• 組み込みの手順：モーダルを閉じる、発売日を設定する、原稿プレビューを承認する、表紙アップロードのアコーディオンを選択する、Server Busy を回避する、処理を待つなど。
• 学習内容ファイル：.kdp-session/recovery-learnings.json — 成功したエラー→アクションの組み合わせは、以降の実行でより高く評価されます。
• 公開 API のレスポンスには、試した内容を記述する recoveryLog が含まれる場合があります。

復旧の再試行がすべて失敗した場合は、errors と recoveryLog を確認し、根本的な問題（例：表紙 PDF の寸法が無効）を修正してください。

エージェント向けのルール

1. 同期／更新の前に、必ずセッションを確認してください（npm run status）。connected: false の場合は、先にログインのサブスキルを実行してください。
2. 書き込み操作は一度に 1 つだけ実行してください。順次操作を参照してください。一括スクリプト、並列での公開、複数タイトルに対する /batch API の使用は禁止です。
3. .kdp-session/ やダウンロードした .xlsx ファイルをコミットしないでください。
4. レート制限：サーバーは KDP_REQUEST_DELAY_MS（既定値：4s）に従って、KDP のページ読み込みと API 呼び出しの間隔を空けます。これを回避しないでください。
5. メタデータ／価格の更新：1 冊でドライランを実施してから、リクエストごとに 1 冊ずつ本番環境に変更を適用してください。
6. KDP からメタデータを再読み込みして、保存されたことを確認してください（更新フローに組み込まれています）。
7. カテゴリ：ブラウズノード ID またはモーダルのパス選択機能から更新できます（POST /api/kdp/categories/update または公開ウィザード）。
8. 公開：まず npm run publish:book でドライランを実施してください。本番環境での公開には "publish": true とユーザーの確認が必要です。publish:book の実行 1 回につき 1 冊だけ処理してください。

参考資料

• references/api-endpoints.md — REST API
• references/metadata-fields.md — スクレイピングされた書籍のデータ構造
• references/troubleshooting.md — Server Busy、認証、ページネーション