wix-vibe-headless

Wix Vibe Headless — クライアント専用 REST コネクター

既存のフロントエンドを、サイトの公開 WIX_CLIENT_ID を使って、ブラウザーから直接、ライブ Wix サイトに接続します。手書きの REST を使用し、@wix/sdk なし、バックエンドなし、ビルド手順なし、依存関係なし。スキルは 1 つ、共有トランスポートは 1 つ、Wix のビジネスソリューションごとに、そのままコピーして使える REST レイヤーを用意します。すべてオーナーのコンテンツに対する読み取り専用です。ライブの Wix データを表示するか、正直な空の状態を表示します。商品、投稿、イベント、メニュー、プラン、レビュー、件数を決してモックせず、作成せず、捏造しません。

このスキルを使う場合

• ユーザーがフロントエンド（バイブコーディングされたアプリ、プレーンな HTML/JSX、Vite/React プロジェクト、デザインツールからのエクスポートなど）を持っている、または構築中で、ライブの既存 Wix サイトのデータを表示し、クライアントから実際の購入や予約を完了できるようにしたい場合。
• 公開 WIX_CLIENT_ID を渡され、「これを自分の Wix ストア／ブログ／予約／イベント／…に接続して」と頼まれた場合。
• プレースホルダー／モックデータを実際の Wix コンテンツに置き換える場合や、すでにあるアプリにカート、チェックアウト、予約、出欠確認、チケット販売、レストラン予約、フォーム、購読のフローを追加する場合。

このスキルを使わない場合

シナリオ	代わりに使用
1 つのプロンプトから Wix サイトを一から最後まで構築する（要件確認 → デザイン → 構築 → ホスティング）	wix-headless
プロジェクトで Wix SDK（@wix/sdk）や Wix CLI を使う場合、または Wix 上でホストする場合	wix-headless
REST 経由でサイトを管理／設定する（アプリのインストール、カタログの初期データ登録、ビジネスソリューションのセットアップ）	wix-manage
Wix のアプリ拡張機能（ダッシュボードページ、ウィジェット、バックエンド、プラグイン）を構築する場合	wix-app

このスキルは、意図的にクライアント専用、REST 専用の方法です。wix-headless（SDK ＋ CLI ＋ ホスティング）とは独立しています。同じプロジェクト内で両者を混在させないでください。

共通モデル（すべての分野に適用）

• 認証情報は公開クライアント ID 1つです。 WIX_CLIENT_ID は購入者／訪問者向けの認証情報です。匿名訪問者トークンの発行にのみ使われます。シークレットではないため、ハードコードしてコミットしても問題ありません。ユーザーがこれを指定します（そのユーザーの vibe／ホストプラットフォームには、IDを入力済みのコピー可能なプロンプトが表示されます）。wix-config.js の <YOUR-CLIENT-ID> プレースホルダーを置き換えて貼り付けます。
• 金額／価格フィールドは常にオブジェクトで、スカラー値ではありません。 Wix API が返すすべての価格／金額――Stores の price.actualPrice、Bookings サービスの payment.fixed.price、Events チケットの registration.tickets.lowestPrice など――は { value, currency, formattedValue } の形式です。formattedValue（通貨記号がすでに含まれています）を表示するか、value と currency から組み立てます。オブジェクトをそのまま UI に渡したり、数値／文字列として扱ったりしてはいけません。その場合、[object Object] または書式設定されていない数値が表示されます。**寄付の場合の例外：**キャンペーン価格は { amount, formattedAmount } の形式で、amount は小数を含む文字列です。一方、寄付カートの options.amount には JSON の数値を指定する必要があります。寄付の手順に従ってください。
• 訪問者トークンが ID です。 wix-client.js は匿名訪問者トークンを発行し、リフレッシュトークンを localStorage に保存して、有効期限が切れると更新します。このトークンがカート／予約／会員セッションの ID です。ページの読み込みごとに匿名トークンを再発行してはいけません。カートが何も表示されないまま空になります。
• 会員ログインでは同じクライアント上でトークン一式を切り替えます。 members の垂直機能はカスタムログインです。ログイン UI はフロントエンド側で用意し、会員が Wix ホストのログインページにリダイレクトされることはありません。ログインに成功すると、訪問者トークンと同じストアに会員のトークンを書き込みます（setSessionTokens）。これにより、以降のすべての wixApiRequest は会員として実行され、カート／セッションも引き継がれます。「マイ…」機能（プラン、注文、予約、登録）は、ログイン後にのみ利用できます。
• ⚠️ Wix で構築するなら、認証、会員データ、その他のビジネス機能も Wix 上で完結させてください。 WIX_CLIENT_ID を使って Wix のストアフロント／ブログなどを構築する場合は、アプリの残りの部分も、ホストプラットフォーム独自のバックエンドやログイン機能ではなく、Wix を使うことをおすすめします。**特に認証では、**ユーザーが会員機能を求めている場合、Wix 会員（members 垂直機能）としてログインさせてください。ホストプラットフォームの認証機能を追加してはいけません。同様に、会員が作成するコンテンツ（いいね、レビュー、投稿、「マイ…」リスト）は、ホスト側のデータベースではなく、Wix CMS コレクション（cms 垂直機能）に保存します。
  • **ID が分裂する落とし穴：**最もよくある失敗は、2つを混在させることです。たとえば、Wix セッションの会員 ID を使いながら、ホスト側のデータベースに「いいね」を保存したり、Wix 会員でログインさせながら、ホスト側のユーザー ID にデータを関連付けたりするケースです。2つの ID は決して一致しないため、所有者フィルターが何も返さず（いいねが更新時に消えるなど）、データもほかの Wix コンテンツと一緒に保存されません。
  • **基本ルール：**機能ごとに、ストアと ID を1つずつ使います。Wix を使う機能では、Wix 会員と Wix コレクションを組み合わせ、所有者情報には Wix サーバーが設定する _owner を使います（手動で保存した ID やホスト側から渡された会員 ID は使いません）。ホスト側だけで扱うデータにホストのバックエンドを使うのは問題ありません。ただし、1つの機能を両方にまたがらせてはいけません。
• **モックデータの作成も、データの登録も禁止です。**これらのひな形が読み取るのは、オーナーが管理するコンテンツのみです。オーナーは Wix ダッシュボードで商品／投稿／サービス／イベント／メニュー／プランを追加します。コレクションが空の場合は空の状態を表示し、データ、レビュー、評価、件数を捏造してはいけません。
• **購入処理は Wix を通じて行います。**チェックアウト／チケット購入／プラン購入は、必ず Wix のリダイレクトセッション／Wix ホストのフォームを通じて完了させます。/checkout や購入用 URL を手動で作成してはいけません。
• **エラーは必ず表面化させます。**ヘルパーは、在庫切れ、空のカート、予約できない枠、有効期限切れの仮押さえ、未払いの状態で例外をスローします。正常に完了した場合だけ、成功を示してください。エラーを握りつぶしてはいけません。
• 同梱のヘルパーはそのままコピーして使い、内部を書き換えてはいけません。 UI はエクスポートされた関数に接続してください。ヘルパーの本体を「リファクタリング」したり、再実装したりしてはいけません。Wix リクエストの形式には厳密で、壊れやすいものがいくつかあります（members の createRedirectSession のボディは典型例です。書き換えると 400 が返され、ログインできなくなります）。機能を拡張する場合は、エクスポートされた関数を呼び出すか、本当に不足している機能に対して新しい wixApiRequest 呼び出しを追加します。同梱の関数は編集しないでください。
• **スニペットにない情報は、推測せずに調べてください。**テンプレートと同梱の references/<vertical>/ ヘルパーが実装の基準です。まずこれらをもとに構築してください。本当に不足している情報（スニペットにないフィールド、エンドポイント、エラー）がある場合は、エンドポイント、メソッド、ボディを正確に確認してから、wixApiRequest でクライアントを拡張します。**その実装やトラブルシューティングでは、**適切なエンドポイントの特定、メソッドのリクエスト／レスポンススキーマの確認、API エラーの診断に、利用環境で使えるドキュメントスキルを使って公式の Wix API ドキュメントを参照し、メソッドやページ、API スキーマを調べてください。リファレンスインデックス：https://dev.wix.com/docs/api-reference.md
• **ユーザーには Wix ダッシュボードへのディープリンクを提供してください。**多くの場合、ユーザーは Wix ダッシュボードで垂直機能の既定データを変更する必要があります。必ずこれらのリンクを提供してください。各垂直機能に関係するリンクは、その INSTRUCTIONS.md ファイルに記載されています。

このスキルの構成

<SKILL_ROOT> はこのファイルのディレクトリです（/SKILL.md を取り除いたもの）。各業種向けの統合コードは references/<vertical>/app/ にあります。REST ヘルパーは app/rest/ にあり、業種によってはユーティリティ、フック、コンテキスト、コンポーネント、ページも含まれます。すべての業種で、references/shared/app/ にある 共通トランスポート（app/rest/wix-client.js と wix-config.js。すべての業種で同一）を使用します。wix-config.js で WIX_CLIENT_ID（および WIX_METASITE_ID）を設定してください。references/<vertical>/app/ と references/shared/app/ をアプリの src/ に配置すると、すべてのファイルが適切な場所に収まります。REST ヘルパーは src/rest/ に配置されるため、相対インポートが解決されます。

これらのファイルをアプリのどこに配置し、どう配置するか（セットアップ時にインストール済みか、コピーして配置するか）は、ご利用のプラットフォームの判断に委ねられます。その方法については、プラットフォームの手順に従ってください。

各業種の INSTRUCTIONS.md には、前提条件、提供される要素、エクスポートされるインターフェース、構築する必要があるプレゼンテーションが記載されています。実装前に必ずお読みください。提供済みの要素を再利用し、すでに実装されているロジックを作り直さずに、不足しているプレゼンテーションを構築してください。プラットフォームおよび業種の完了ガイダンスがある場合は、それに従ってください。

ルーティング — リクエストに応じて縦割り領域を選ぶ

ユーザーのアプリに必要な縦割り領域を読み込みます。プロジェクトでは複数の領域を組み合わせることもできます（例：ブログを併設したレストラン、料金プランのあるストア）。

各縦割り領域の統合ファイルは references/<vertical>/app/ にあります。このディレクトリと references/shared/app/ をアプリの src/ にコピーしてください（base44 ではインストール時に deploy.cjs を使ってコピーします）。

ユーザーの要望…	縦割り領域	参照先
オンラインストア：商品、カテゴリ、カート、チェックアウト	storefront	references/storefront/INSTRUCTIONS.md
寄付：募金キャンペーン、単発または定期的な寄付、ホスト型チェックアウト	donations	references/donations/INSTRUCTIONS.md
予約：サービス、時間枠、予約、チェックアウト — 予約可能なサービスに紐づくフォーム	bookings	references/bookings/INSTRUCTIONS.md
レンタル：顧客が選ぶ期間（日単位または時間単位）での物品貸し出し — Wix Rentals は Bookings API を利用しているため、同じ縦割り領域です	bookings	references/bookings/INSTRUCTIONS.md（「Rentals」）
ブログ／ニュース：投稿フィード、投稿ページ、カテゴリ、タグ	blog	references/blog/INSTRUCTIONS.md
イベント：閲覧、イベントページ、出欠確認、チケット販売 — チケットのない単発イベントであっても、出欠確認は forms ではなくこちらです	events	references/events/INSTRUCTIONS.md
ポートフォリオ／ショーケース：コレクション、プロジェクト、メディアギャラリー	portfolio	references/portfolio/INSTRUCTIONS.md
レストラン：メニュー、オンライン注文、テーブル予約	restaurants	references/restaurants/INSTRUCTIONS.md
訪問者が入力できるあらゆるフォーム：問い合わせ、見込み客、登録、ウェイティングリスト、申請、フィードバック／アンケート、見積もり依頼、受付、または登録。イベントの出欠確認（events）、サービスごとの予約フォーム（bookings）、寄付の申し込み（donations）は対象外です	forms	references/forms/INSTRUCTIONS.md
CMS コンテンツ：一覧／詳細、フィルター／検索、データの CRUD。訪問者が入力するフォームは forms です — アプリが登録内容を読み戻す必要がある場合に限り cms を使います	cms	references/cms/INSTRUCTIONS.md
プランと料金：会員資格／サブスクリプション、申し込み、自分のプラン	pricing-plans	references/pricing-plans/INSTRUCTIONS.md
会員アカウント：カスタムのログイン／登録（メールアドレスとパスワード、Google／Facebook、SSO）、アカウントエリア、アクセス制限付きコンテンツ	members	references/members/INSTRUCTIONS.md

⚠️ 訪問者が入力して送信するものはすべて forms です — ただし、次の4つは例外です：

1. 登録内容を読み戻す必要がある → cms。 公開ギャラリー、一覧表示、会員の「自分の送信内容」などが該当します。訪問者は Forms の送信内容を読めないため、こうした場合はコレクションが必要です。送信のみの場合は常に forms を使います。insertDataItem に接続したフォームも動作しますが、ダッシュボードのフォームビルダー、スパム対策、送信通知、CRM の連絡先マッピングが使えなくなり、誰でも送信できるようにするには、事前にオーナーがコレクションの権限を手動で設定する必要があります。
2. イベントや催しへの出席を確認する → events。 結婚式、パーティー、集まりなどが該当します。events には、組み込みの出欠確認登録フォームが含まれています。チケットのない単発の催しでも、こちらに振り分けてください。
3. 予約可能なサービスに紐づくフォーム → bookings。
4. 寄付キャンペーンへの寄付 → donations。 定期的な寄付は Pricing Plans の購入ではありません。寄付フォームでは、キャンペーンの金額／頻度のルールを維持し、そのカタログ参照を使用する必要があります。

リクエストで Wix Business Solution が指定されていない場合 — 質問するか、サイトを確認する

曖昧な依頼から、どの Wix Business Solution（ストア、予約、ブログ、イベント、ポートフォリオ、レストラン、CMS、料金プラン、メンバーなど）を構築するか推測しないでください。ユーザーに、何を提供しているのか（商品？予約？投稿？イベント？）を短く質問するか、サイトに実際にあるものを確認してください。各候補ソリューションのヘルパー（queryProducts、queryServices、queryPosts、queryEvents、…）から、低コストの読み取りを呼び出します。WIX_CLIENT_ID から発行した訪問者トークン、または利用可能であれば管理者トークンで認証し、実際のコンテンツが返されるソリューション向けに構築してください。428「アプリがインストールされていません」（ブログの場合は 401）は、そのソリューションがサイトにないことを意味します。「Sample product 3」のようなサンプルらしいコンテンツは、アプリがインストールされていることを示すだけで、そのビジネスの内容を示すものではありません。何も指定されていないからといって、ストアや予約をデフォルトにしないでください。

実行手順

1. WIX_CLIENT_ID を取得します。 ユーザーから提供されます（Wix／vibe プラットフォームからの引き継ぎプロンプトに含まれています）。見つからない場合は、配線を始める前に尋ねてください。これがないと何も動作しません。
2. ルーティングテーブルから垂直分野を選びます。リクエストで指定されていない場合は、推測せずに質問するか、サイトを確認してください（上記を参照）。選んだ各垂直分野の INSTRUCTIONS.md を開きます。
3. 垂直分野のファイルが配置されていることを確認します。references/<vertical>/app/ と references/shared/app/ をアプリの src/ にコピーし、wix-config.js に WIX_CLIENT_ID を設定します。（配置場所や方法は利用するプラットフォームによって異なります。プラットフォームの手順を参照してください。base44 ではインストール手順で wix-config.js が作成・検証されるため、手動で設定する必要はありません。）
4. 垂直分野の INSTRUCTIONS.md に従って、プレゼンテーションを構築し、連携を配線します。 提供された各要素は、文書化されたインターフェースを通じて再利用し、任されたプレゼンテーションを構築して、指定どおりにルート／プロバイダーを接続します。提供済みのロジックを再実装しないでください。新しいプレゼンテーションのスタイルには、既存のプラットフォームテーマを使用します。
5. 該当するプラットフォームおよび垂直分野のガイダンスを完了します。必須の確認項目や、提供されている引き継ぎ手順も含みます。

一部のフローでは、後でユーザーが Wix 側の設定を完了する必要があります（決済の接続、ホスト型チェックアウトの戻り先としてデプロイ済みドメインを OAuth クライアントの許可リストに追加、コレクションの権限設定など）。 これらはここでは対象外です。その理由で呼び出しに失敗した場合は、その旨を伝えて続行してください。モックデータに切り替えないでください。