prava-shopping

Prava Shopping — AI エージェント向けの商品検索と購入

Prava CLI を使って、検索から購入までを一貫して行います。複数の加盟店から商品を検索し、商品を開いてバリエーションを選び、正確な価格を見積もり、カードセッションを作成してチェックアウトします。 ユーザーがカードを一度承認すれば、あとはエージェントが処理します。

意図に応じたルート（最初にお読みください）

ユーザーの希望…	対応
Prava に商品を検索・購入してほしい（「〜を探して／買って」「カートの会計をして」）	このスキル：以下のフロー
すでに選んだ商品を特定の店舗で支払う、請求書を支払う、または利用中のチェックアウトで支払う	prava-pay に引き継ぎます
後日または繰り返しの購入を事前承認する、または「予算を設定する」（今すぐ購入するものはない）	prava-pay の 委任支払いの設定 フローに引き継ぎます。ここで委任支払いの設定を重複して行わないでください
購入を伴わない調査・閲覧（レストラン、旅行、情報、「ライブラリ／API を探して」）	どちらのスキルも使いません。対応しないでください
Prava に関する質問、設定、連携	prava-pay

有効化するタイミング

ユーザーが、Prava に物理的な商品を探して購入してほしい場合（「〜を探して／買って」「これを注文して」「カートの会計をして」）に有効化します。

方法が曖昧な場合は確認してください。決めつけたり、しつこく尋ねたりしないでください。

• Prava がユーザーの設定済み購入方法で、依頼が明確な購入であれば、そのまま進めます。ただし、最初に伝えてください：「Prava（連携済みカード）を使って、商品を探して購入します。」その後の確認（購入提案の確認 → 合計金額の確認 → --yes）が中止する機会になります。
• ユーザーが別の場所で探したり購入したりする可能性を示す場合（別の店舗やツールを指定する、「X を見ています」と言う、商品リンクを貼る、または依頼が探索的な場合）は、まず尋ねてください：「Prava を使って商品を探して購入しますか？それとも別の場所で購入しますか？」

次の場合は、商品検索を実行せず、このスキルを使わないでください。

• 依頼が商品購入に関するものではない場合（一般的な調査・閲覧、レストラン、旅行、情報など）。対象外です。このスキルは購入用であり、検索エンジンではありません。
• ユーザー自身が商品を探している場合、または別の場所で特定の店舗の特定の商品をすでに選んでいる場合 → 必要なのは支払いだけです → prava-pay を使います（その加盟店で支払い、Prava のカタログ検索は行いません）。
• ユーザーが**「自分で探します」「支払いだけして」「検索しないで」**と言った場合 → その意向を尊重し、shop search を省略する（以下を参照）か、prava-pay に引き継ぎます。
• 個人間送金、既存のリンクがある請求書、または Prava に関する質問 → prava-pay を使います。

商品検索は省略できます。 このスキルを必ず search から始める必要はありません。ユーザーがすでに商品を特定している場合（product_id と加盟店がわかっている、またはカタログ内の特定商品を指定している場合）は、product／quote から開始できます。検索を代行しなくても、Prava の見積もりと安全なチェックアウトを利用できます。search は、ユーザーが実際に Prava に商品候補を探してほしい場合にのみ使います。

このスキルは prava-pay と同じ CLI を使い、支払いの手順は同スキルで説明されている prava sessions のフローに引き継ぎます。

前提条件

エージェントがユーザーの Prava アカウントに連携済みであり、prava CLI がインストールされている必要があります。 prava status が active でない場合は、まず連携フローを実行してください。手順については、prava-pay スキルの「前提条件」および「CLI がインストール済みで、エージェントが連携済みであることを確認する」を参照してください。ここで同じ手順を重複して記載しません。

環境変数のプレフィックスは不要です。 CLI はコマンド（shop * → prava-shopping）からスキルを判別し、インストール済みのスキルバージョンを自動的に読み取るため、そのまま prava shop … を実行してください。（標準以外のエージェントホストでのみ、上書き設定として PRAVA_SKILL_VERSION=<ver> を設定します。）

フロー（ID チェーン：product_id → variant_id → checkout_session_id）

進行ペース — 1 ターンにつき 1 つの判断を求めます。提示したら、そこで止めてユーザーの返信を待ってください。 以下のステップはチェックポイントであり、最初から最後まで一気に実行するスクリプトではありません。**このうち 2 つのコマンドを同じターンで続けて実行してはいけません。**具体的には、search の後はユーザーが商品を選ぶのを待ち、product の後は販売者／バリエーションを確認するのを待ち、quote の後は支出の承認を待ってください。各 prava shop コマンドは、ユーザーが前のステップに返信した後にのみ実行します。「X を買って」という依頼は、フローの開始を許可するものであり、黙って最後まで実行することを許可するものではありません。

1. 検索

検索には、簡潔なキーワードを指定する --query と、ユーザーの自然言語での依頼全体（用途、贈る相手、雰囲気、予算の表現）を含める --intent の 2 つを指定します。UCP は intent を使って、ユーザーが実際に求めているものに近い結果を優先します。--query だけでは、その文脈が失われます。

prava shop search --query "dark roast coffee" \
  --intent "a smooth, not-too-bitter dark roast as a gift for my dad" \
  [--merchant bonescoffee.com] [--ships-to US] [--limit 10]

• --query = 商品のキーワードのみ（何を検索するか）。
• --intent = ユーザー自身の言葉での依頼内容（理由／対象者／予算）。ユーザーの依頼が単なるキーワードより具体的な場合は、必ず指定してください。例：「ガールフレンドへのプレゼントに、30 ドル以下の帽子」→ --query "hat" --intent "a hat as a gift for my girlfriend, under $30"。

各検索結果には、タイトル、価格、販売者、product-id が表示されます。タイトル＋価格＋販売者を、わかりやすい言葉でユーザーに提示してください。**生の JSON や画像 URL を貼り付けてはいけません。**ほかの候補を希望する場合は、カーソルを使ってページを切り替えてください（ページネーションを参照）。選択が曖昧な場合は、どの商品（またはどの販売者）を希望するのかユーザーに尋ねてください。

2. 商品 → 販売者を選ぶ（オファー）

prava shop product --product-id "<product_id>" --merchant <merchant>

同じ商品が複数の販売者によって販売されていることがよくあります。CLI はそれぞれをオファーとして表示します。 ラベル — $価格［オプション］ · 販売者 + variant-id の形式で、注文可能なオファーを先に、その後に価格の安い順で表示します。価格は商品本体のみで、送料は見積もり時に加算されます。したがって：

• **product の後は必ず止まり、そのターンで quote を実行してはいけません。**商品について、タイトル＋1 行の説明とオファー（販売者 · 価格 · バリエーション）を簡潔にまとめて伝え、どれを希望するかユーザーに確認してください。オファーが 1 つだけの場合も同じです。そのオファー（「選択肢は 1 つです：<販売者>、<バリエーション>、$<価格>＋送料です。価格を確認しますか？」）を提示し、見積もりに進む前に返信を待ってください。商品について説明しながら、そのまま次へ進んではいけません。 （説明を伝えるために必要であれば、product --json を実行してください。）
• ユーザーに明示的に選んでもらってください。価格で選ぶ場合（デフォルトは注文可能なオファーのうち最安のもの）、またはオファー間で実際に異なるオプション（サイズ／挽き方／色）で選ぶ場合があります。ユーザーに断りなく販売者を切り替えてはいけません。
• **(out of stock) と表示されたオファーは、実際には注文できない価格表示のみの場合があります。**安く見えるという理由だけで選ばないでください。オファー一覧ではすでに末尾に配置されています。
• 選択されたオファーの見積もりには、検索時の販売者とは限らないため、該当オファーの行に表示されたそのオファー固有の販売者を指定してください。

2.5 配送先住所（見積もり前に必須）

quote はユーザーが保存した住所に商品を発送します。ウォレットがサーバー側で住所を挿入するため、あなた（エージェント）が生の住所や電話番号を扱うことはありません。登録内容を確認します。

prava shop address list   # MASKED: label · "•••• St, City RG •••NN, US" · address-id · [default]

• デフォルトの住所が登録されている（またはユーザーが住所を指定した）→ 見積もりに進みます（デフォルト以外の住所の場合は、必要に応じて --address-id <id> を指定します）。
• 住所が未登録 → ユーザーが住所を追加する必要があります。Prava ダッシュボードを優先してください（最も安全です。個人情報があなたを経由しません）。ダッシュボードの URL を伝え、住所と電話番号を追加してから address list を再実行するよう依頼します。代替手段：ユーザーに住所を伝えてもらい、prava shop address add で保存します。尋ねるときは、以下をすべて確認します。
  • 氏名（宛先）
  • 番地 — 1 行目（該当する場合は 2 行目も）
  • 市区町村、州／地域、ZIP／郵便番号
  • 国（ISO-2。例：US、IN、GB）
  • 電話番号 — 国番号を含む（例：+91 98765 43210、+1 415 555 0100）。必ず先頭の +<code> を含めるよう依頼します。ユーザーが国番号なしの番号を伝えた場合は、どの国番号（+91、+1 など）か確認します。 次に、prava shop address add --first-name … --last-name … --line1 … [--line2 …] --city … --region … --postal … --country US --phone "+1 415 555 0100" --default を実行します。
• 個人情報に関するルール — 住所や電話番号の全体を読み上げたり、繰り返したり、ログに記録したりしないでください。取得できるのはマスキングされた概要だけです。住所はラベル／address-idで参照してください。
• 住所または連絡先が未登録の場合、quote／checkout は SHOP_ADDRESS_REQUIRED／SHOP_CONTACT_REQUIRED を返します。メッセージを伝え、ダッシュボードを案内してください。

3. 見積もり → 正確な価格

ユーザーがオファーを確認し（手順 2）、住所が登録された後（手順 2.5）にのみ実行してください。 CLI ではオファーの確認が必須です。quote は --yes を指定しないと拒否されます。ユーザーが販売者／バリエーションを選んだ後にのみ --yes を渡してください。

prava shop quote --variant-id "<variant_id>" --merchant <merchant> [--quantity 1] --yes

最終価格（送料／税金を含む）、checkout-session-id、有効期限（見積もりは約 5 分間有効）が返されます。合計金額をユーザーに伝え、その後は確認ゲート（手順 4）で必ず停止してください。

ハーネスの処理には時間がかかる場合があります。タイムアウトまたはサーバーエラー時、見積もりは自動的に 1 回再試行します（--retries <n> で調整できます。例：--retries 2）。それでもタイムアウトした場合は、quote を再実行してください。セッションを開くだけなので、安全に再試行できます。checkout は自動再試行しません。タイムアウトした決済が完了している可能性があるため、結果を確認してから再実行してください（再実行すると、保存済みの結果が返されます）。

4. ユーザーに確認する — その後、カードセッションを発行する

必ず停止してください — オファーが 1 つしかない商品でも、ユーザーがすでに「X を買って」と言っていても、この手順を省略してはいけません。「X を買って」は購入の意図であり、価格への承認ではありません。販売者、バリエーション、送料、合計金額は見積もりが出るまで分かりません。支払いを伴う操作の前に、以下を提示し、明示的な**「はい」**を得てください。

• 商品 — タイトルと 1 行の説明
• 販売者（加盟店）と、購入予定のバリエーション
• 数量
• 配送先住所 — ラベル／マスキングされた概要のみ（住所全体は決して表示しないでください）
• 最終合計金額（送料込み。見積もりに基づく）

明示的な確認を得てから、カードセッションを発行するか、チェックアウトに進みます。ユーザーから返答がない場合は、待機してください。処理を続行してはいけません。

カードセッションを発行する前に、この見積もりの販売者と合計金額が適用対象となるマンダートを確認するために必要な情報と一致しているか確認します。ここでも prava-pay の購入フロー手順 0（prava mandate list --json）を実行してください。一致するマンダートがある場合は、新しいセッションを発行せず、そのフローに従って提案するか自動的に請求します。一致しない場合は、以下に進みます。

見積もりと完全に同じ合計金額でカードセッションを発行します（prava-pay と同じフローです。金額は見積もりの合計と一致する必要があります）。

prava sessions create \
  --total-amount "<quote total, e.g. 27.98>" --currency <CUR> \
  --merchant-name "<merchant>" --merchant-url "https://<merchant>" --merchant-country US \
  --product '{"description":"<product title>","unit_price":"<quote total>","quantity":1}'

支払い URL が表示されます。ユーザーに提示し、承認してカード情報を入力するまで待ちます。その後、トークン化された認証情報をポーリングします。

prava sessions poll --session-id <session_id>

→ Token、Cryptogram、Expiry が返されます（1 回限り使用可能。有効期限は約 30 分です）。

5. 決済

checkout は --yes を指定しないと拒否されます — ステップ4でユーザーが合計金額を承認した後にのみ指定してください。

prava shop checkout --checkout-session-id "<checkout_session_id>" \
  --token <token> --cryptogram <cryptogram> --expiry-month <MM> --expiry-year <YYYY> --yes

成功すると、注文 ID とともに ✓ Paid が表示されます。CLI が分かりやすい結果を表示するので、ユーザーに伝えてください。

ページネーション（「さらに表示」）

検索結果は、厳選されたページ（デフォルトは10件）を返します。CLI に "More results — next page" という行が表示された場合、--cursor <value> を含む正確なコマンドが示されています。さらに表示するには、その --cursor を指定して検索を再実行します。"more" の行が表示されなければ、結果は最後まで表示されています。カーソルは不透明な値です — そのまま渡し、決して作成したりデコードしたりしないでください。（生の next_cursor を取得する必要がある場合は、--json を使用します。）

表示ルール（簡潔に保つ）

• ユーザーの判断に役立つ情報を表示します：タイトル、1行の説明、価格、販売者、バリエーション、最終合計金額、注文結果。（説明は判断に関わる情報です — ユーザーが商品を選んだら伝えてください。）生の JSON、画像 URL、内部のセント単位の金額、価格内訳オブジェクトは決して表示しないでください。
• CLI の厳選された出力には、必要な情報がすでに含まれています。次のコマンドにつなぐために id／cursor を取得する必要がある場合にのみ --json を使用してください — JSON をユーザーに見せないでください。

ユーザーに確認するタイミング

• search の後 → 停止し、ユーザーに商品を選んでもらいます（商品を自動で開かないでください）。
• product の後 → 停止し、概要（タイトル＋1行の説明＋オファー：販売者 · 価格 · バリエーション）を伝え、quote を実行する前に販売者／バリエーションを確認してもらいます — オファーが1件だけの場合も同様です。product → quote を1回のターンで続けて実行しないでください。
• あいまいな検索結果（候補となる商品／販売者が複数）→ どれを希望するか尋ねます。
• バリエーション（サイズ／挽き方／色）が複数ある場合 → どれを希望するか尋ねます。
• 支払いを伴う操作（カードセッションの発行／決済）の前 → 必須：商品、販売者、バリエーション、数量、最終合計金額（送料を含む）を確認し、明示的な「はい」を得てください。これがステップ4の必須停止地点です。
• ユーザーが「もっと／ほかの選択肢」を求めた場合 → カーソルを使って次のページを表示します。

実行例 — 「コーヒーを1袋買って」

1. prava shop search --query "coffee" → 上位の数件（タイトル · 価格 · 販売者）を表示します。停止 — ユーザーが1番目を選びます。
2. prava shop product --product-id <id> --merchant bonescoffee.com → 結果を伝えます：「コスタリカ シングルオリジン 12oz — ミディアムロースト、チョコレート／ナッツ風味 — bonescoffee.com の全豆が $19.99 です。 選択肢はこれだけです — 最終価格を確認しますか？」停止 — ユーザーが「はい」と答えます。
3. prava shop quote --variant-id <vid> --merchant bonescoffee.com → $27.98（送料 $7.99 込み）。 確認ステップ：「送料込みで合計 $27.98、bonescoffee.com からの購入です — 購入しますか？」停止 — 明示的な「はい」を待ちます。「はい」の場合 →
4. prava sessions create --total-amount "27.98" --currency USD --merchant-name "bonescoffee.com" --merchant-url "https://bonescoffee.com" --merchant-country US --product '{"description":"Costa Rica Single-Origin Coffee | 12oz","unit_price":"27.98","quantity":1}' → URL を表示し、ユーザーの承認を得たら → prava sessions poll --session-id <id> → トークン＋クリプトグラム。
5. prava shop checkout --checkout-session-id <cs> --token <t> --cryptogram <c> --expiry-month 12 --expiry-year 2028 → ✓ Paid が表示されたら、注文 ID を伝えます。

エラー（安全なメッセージを伝え、その内容に従って対応します）

• 見積もりの期限切れ（SHOP_SESSION_EXPIRED／"expired"）— 価格が古くなっています。quote を再実行して新しい checkout-session-id を取得し、決済してください。
• 拒否／"captcha required"／失敗 — 決済が完了しなかったことをユーザーに伝え、再試行するか別の販売者を試すか尋ねます。失敗したセッションは再試行できません — 新しい quote を開始してください。
• "already being processed"（SHOP_CHECKOUT_IN_PROGRESS）— 決済処理中です。再送信せず、完了を待ってください。
• 決済上限／未完了の決済が多すぎます（クォータ）— メッセージを伝えます。ユーザーは上限に達しています。

アンチパターン

• 商品、販売者、合計金額をユーザーが明示的に確認していない状態で、product／quote から支払いに進むこと。「Xを買って」と言われた場合でも同様です。絶対にしてはいけないことの第1位です。
• ユーザーの返答を待たずに、1回のターンで prava shop コマンドを2つ続けて実行すること（例：product → quote）。提示したら、返答を待ちます。
• 商品を黙って選び、その説明やオファーをユーザーに伝えないこと。
• 生の JSON、画像 URL、セント単位の金額をユーザーにそのまま提示すること。
• 選択肢が複数あるのに質問せず、バリエーションを推測すること。
• ユーザーがカードセッションを承認する前に checkout を呼び出すこと（まだトークンがありません）。
• 期限切れまたは失敗したセッションで再度チェックアウトし、見積もりを取り直さないこと。
• 見積もりの合計金額と一致しない金額でセッションを発行すること。
• Prava の公式に関する質問や P2P 決済にこのスキルを使うこと（それらは prava-pay の対象であり、このスキルの範囲外です）。

クイックリファレンス

フラグ、出力、終了コードの詳細については、cli-shop リファレンスを参照してください。

# No env prefix needed — the CLI detects the skill + version automatically.
prava shop search   --query "<keywords>" [--intent "<user's full ask>"] [--merchant <d>] [--ships-to US] [--limit N] [--cursor <c>] [--json]
prava shop product  --product-id "<id>" --merchant <d> [--json]
prava shop quote    --variant-id "<id>" --merchant <d> [--quantity N] --yes [--json]
prava shop checkout --checkout-session-id "<cs>" --token <t> --cryptogram <c> --expiry-month <MM> --expiry-year <YYYY> --yes

終了コード：0 成功 · 1 エラー／拒否 · 2 エージェントが連携されていません。

---

AI エージェント向け決済スタック — Prava Payments が開発しました。