derive-client

記録したセッションから API クライアントを導出する

ブラウザを操作することは、最初の訪問には適した手段ですが、100 回目の訪問には不適切な手段です。このスキルは、サイトを一度使用する間にそのサイトのネットワークトラフィックを記録し、キャプチャしたリクエストを、サイトの内部 API と直接通信するスタンドアロンのクライアント（スクリプト、CLI、またはライブラリ）に変換します。

記録だけに必要なものはすべて含まれています。agent-browser はデフォルトでテキストのレスポンスボディ（JSON/HTML/JS）を HAR に埋め込むため、ブラウザを閉じた後でもオフラインでエンドポイントの形を調査できます。

ワークフロー

1. Record     Start HAR capture, drive the flows you want in the client
2. Identify   Find the real API endpoints among the noise
3. Extract    Pull request shapes, response schemas, and auth material
4. Generate   Write the client, one function per flow
5. Verify     Call every endpoint for real before declaring done

1. 記録する

agent-browser network har start          # embeds text response bodies by default
# ... drive the site: search, open a detail page, paginate, etc. ...
agent-browser network har stop /tmp/site.har

• クライアントがサポートすべきすべてのフローを実行し、それぞれを異なる入力で少なくとも 2 回実行してください（2 つの検索語、2 つの詳細ページなど）。記録された URL を差分比較すると、どの部分がパラメータであるかが明らかになります。
• サイトがログインを必要とする場合は、HAR を開始する前にログインしてください。そうすれば、認証情報が不必要に記録に残りません。セッション Cookie はステップ 3 で別途エクスポートされます。
• --content all はバイナリボディも埋め込みます（base64）。--content none は埋め込みを無効にします。ボディごとの上限は 2 MB です。

セッションがまだ開いている間に、agent-browser network requests と network request <id> を使えば同じデータを対話的に取得できますが、ナビゲーションやブラウザの終了を経ても残るのは HAR だけなので、複数ページにわたるものには HAR を優先してください。

2. エンドポイントを特定する

jq で HAR をクエリします。

# All JSON API calls: method, URL, status
jq -r '.log.entries[]
  | select(.response.content.mimeType | test("json"))
  | "\(.request.method) \(.response.status) \(.request.url)"' /tmp/site.har

分析やインフラストラクチャのノイズは無視してください。テレメトリのエンドポイント（/collect、/track、/beacon、/log）、サードパーティのドメイン（google-analytics、segment、sentry、datadog、intercom、hotjar）、および静的アセットです。実際の API は通常ファーストパーティで、JSON であり、実行した操作と相関しています。

3. 形と認証を抽出する

# Full detail for one endpoint: request headers, POST body, response body
jq '.log.entries[] | select(.request.url | test("api/search"))
  | {request: {method: .request.method, headers: .request.headers,
     postData: .request.postData.text},
     response: .response.content.text}' /tmp/site.har

• レスポンススキーマ: .response.content.text を読み取ってください。これが実際のペイロードであり、型を導出するために使用します。
• 認証: エンドポイント間でリクエストヘッダーを比較します。authorization、cookie、x-csrf-token、x-api-key、およびサイト固有の x-* ヘッダーを探してください。重要なものだけを再現します。ステップ 5 で省略してテストします。
• Cookie: agent-browser cookies get --json > cookies.json でライブセッションをエクスポートし、クライアントが実行時に読み込めるようにします。Cookie の値を生成されたソースにハードコードしないでください。

4. クライアントを生成する

• 記録されたフローごとに 1 つの関数（search(query)、getItem(id)）を作成し、観測されたレスポンスボディから型付けします。
• 認証情報（Cookie、ベアラートークン）はファイルまたは環境変数から読み込み、有効期限が切れたときにブラウザでのログインを再実行するようユーザーに伝える明確なエラーを表示します。
• API が実際に要求するヘッダーを再現してください。一部のサイトでは、一致する user-agent、referer、または x-requested-with がないと 403 を返します。
• 記録されたクエリ文字列に現れたページネーション、ソート、フィルターのパラメータは、関数のオプションとして維持してください。

5. 検証する

生成されたすべての関数をライブ API に対して呼び出し、レスポンスの形を記録と比較します。よくある失敗:

症状	原因	修正
401/403	セッションの期限切れまたは欠落	agent-browser で再ログインし、Cookie を再エクスポートする
書き込み時の 403/419	CSRF トークンがセッションごとまたはフォームごと	まずトークンエンドポイントを取得するか、そのフローをブラウザ駆動のままにする
動作するがその後壊れる	署名付きまたは期限切れのリクエストパラメータ	そのステップはブラウザにフォールバックし、残りを導出する
HAR と形が異なる	A/B テストまたは地域依存のレスポンス	再記録し、それらの和集合をオプションフィールドとして扱う

注意事項

• 内部 API はバージョン管理されておらず、予告なく変更されます。クライアントを再導出できるように HAR を保管してください。
• サイトの利用規約とレート制限を尊重してください。一括取得には遅延を追加してください。
• HAR ファイルにはライブセッションの認証情報（Cookie、トークン、POST ボディ）が含まれています。シークレットと同様に扱ってください。バージョン管理から除外し、完了したら削除してください。