wix-cli-service-plugin

Wix サービスプラグイン（SPI）ビルダー

Wix CLI アプリケーション向けのサービスプラグイン拡張機能を作成します。サービスプラグインは、Wix が定義する API のセットです。これらを使用すると、Wix ビジネスソリューションの既存のバックエンドフローにカスタムロジックを挿入したり、Wix サイトにまったく新しいフローを導入したりできます。

サービスプラグインを実装すると、特定のフロー中に Wix がカスタム関数を呼び出します。一般的なユースケースには、eコマースのカスタマイズ（配送、手数料、税金、検証）や Bookings のカスタマイズ（スタッフの並べ替え）がありますが、SPI を公開している Wix ビジネスソリューションであれば、どれでもサービスプラグインで拡張できます。

クイックスタートチェックリスト

サービスプラグインを作成する際は、次の手順を順番に実行してください。

1. SPI タイプのリファレンスドキュメントを読み、その後、リファレンスに記載されているドキュメント URL を指定して ReadFullDocsMethodSchema を呼び出し、正確なリクエスト／レスポンスタイプを取得します — スキーマを取得するまでコードを書かないでください
2. プラグインフォルダーを作成します：src/extensions/backend/service-plugins/<service-type>/<plugin-name>/
3. 正しいインポートと provideHandlers() の呼び出しを含む plugin.ts を作成します
4. 必須のハンドラー関数をすべて、完全なビジネスロジックで実装します
5. 適切なビルダーメソッドと一意の UUID を含む extensions.ts を作成します
6. 新しい拡張機能をインポートして使用するよう、src/extensions.ts を更新します
7. npx tsc --noEmit を実行して TypeScript がコンパイルされることを確認します
8. npx wix build を実行してビルドが成功することを確認します
9. 該当するサイトの操作（例：手数料の場合はカートへの追加）を実行してテストします

リファレンス

該当する SPI を実装する前に、関連するリファレンスドキュメントを必ず読んでください。 各リファレンスには、正しいインポート、ハンドラーのシグネチャ、レスポンス構造、動作するサンプルが記載されています。

SPI タイプ	リファレンス
追加手数料	ADDITIONAL-FEES.md
割引トリガー	DISCOUNT-TRIGGERS.md
ギフトカード	GIFT-CARDS.md
配送料金	SHIPPING-RATES.md
税額計算	TAX-CALCULATION.md
検証	VALIDATIONS.md
Bookings スタッフの並べ替え	BOOKINGS-STAFF-SORTING.md

出力構成

サービスプラグインは、連携して動作する 2 つのファイルで構成されます。プラグインの登録には、拡張機能ビルダーファイルが必要です。

src/extensions/backend/service-plugins/
└── {service-type}/
    └── {plugin-name}/
        ├── plugin.ts           # Handler logic with provideHandlers()
        └── extensions.ts       # Builder configuration (id, name, source)

ファイルの説明

ファイル	目的
plugin.ts	provideHandlers() を使用したサービスプラグインのハンドラーロジックが含まれます。カスタムビジネスロジックを実装するファイルです
extensions.ts	ID（GUID）、名前、ソースパス、ビルダー固有のオプションフィールドを含む、サービスプラグインビルダーの設定が含まれます

実装要件

生成要件

1. 必須のハンドラー関数をすべて、完全なビジネスロジックで実装します
2. 適切な TypeScript 型とエラー処理を含めます
3. ユーザープロンプトで説明されているビジネスロジックを正確に実装することに重点を置きます

実装パターン

• 機能が文書化されていない、または利用できない場合は、その不足を明示し、文書化されている最小限のロジックのみを実装します
• Wix の仕様に従って、必須のハンドラー関数をすべて実装します
• プレースホルダーは使用しないでください。常に完全に動作する機能を実装します

データ検証

すべてのサービスプラグインには、包括的なデータ検証を含める必要があります。

• Wix のリクエストから受け取るすべての入力データを検証します
• 必須フィールドが存在し、適切な形式であることを確認します
• データの欠落や形式の不備を適切に処理します
• ビジネスロジック上の制約（例：最低注文金額、有効な住所）を検証します

実装パターン

ハンドラーファイル（plugin.ts）には、サービスプラグインのロジックが含まれます。以下を満たす必要があります。

1. 適切なパッケージから該当するサービスプラグインをインポートします（例：eコマースの場合は @wix/ecom/service-plugins、Bookingsの場合は @wix/bookings/service-plugins）。
2. ハンドラー関数を含むオブジェクトを指定して provideHandlers() を呼び出します。
3. 各ハンドラー関数は、request と metadata を含むペイロードを受け取ります。
4. そのSPIタイプで期待されるレスポンス構造を返します。

import { shippingRates } from "@wix/ecom/service-plugins";

shippingRates.provideHandlers({
  getShippingRates: async (payload) => {
    const { request, metadata } = payload;

    // Implement custom logic based on request data
    // - request contains cart items, shipping address, etc.
    // - metadata contains currency, locale, etc.

    return {
      shippingRates: [
        {
          code: "custom-shipping",
          title: "Custom Shipping",
          logistics: {
            deliveryTime: "3-5 business days",
          },
          cost: {
            price: "9.99",
            currency: metadata.currency || "USD",
          },
        },
      ],
    };
  },
});

該当するサイトアクションがトリガーされると、Wixによってハンドラー関数が自動的に呼び出されます。各ハンドラー関数の中にカスタムロジックを記述してください。

API呼び出しの権限昇格

サービスプラグインからWix APIを呼び出す際は、@wix/essentials の auth.elevate を使用して権限を昇格させる必要があります。

import { auth } from "@wix/essentials";
import { items } from "@wix/data";

export const myFunction = async () => {
  const elevatedFunction = auth.elevate(items.query);
  const elevatedResponse = await elevatedFunction("myCollection");
  return elevatedResponse;
};

import { auth } from "@wix/essentials";
import { cart } from "@wix/ecom";

export const myFunction = async () => {
  const elevatedFunction = auth.elevate(cart.getCart);
  const elevatedResponse = await elevatedFunction("cart-id");
  return elevatedResponse;
};

import { auth } from "@wix/essentials";
import { products } from "@wix/stores";

export const myFunction = async () => {
  const elevatedFunction = auth.elevate(products.deleteCollection);
  const elevatedResponse = await elevatedFunction("collection-id");
  return elevatedResponse;
};

ベストプラクティス

開発ワークフロー

• 常に完全に動作する機能を実装してください。プレースホルダーは使用しないでください。
• Wixのドキュメントに従って、必須フィールドをすべて処理してください。
• すべての入力データに対して適切な検証を実装してください。
• Wixが期待する正確な形式でレスポンスを返してください。
• すべての失敗シナリオに対して、包括的なエラー処理を追加してください。
• 意味のある変数名を使い、明確なコード構造にしてください。
• さまざまな入力の組み合わせで、十分にテストしてください。

実装ガイドライン

• すべての入力を検証する： 必須フィールドが存在し、適切な形式であることを確認します。
• エラーを適切に処理する： 適切なエラーレスポンスを返し、未処理の例外をスローしないでください。
• 正確な形式で返す： レスポンスは、Wixがドキュメントで定義している構造と完全に一致する必要があります。
• TypeScriptの型を使用する： SDKの型を活用して、型安全性を高めます。
• エッジケースをテストする： 空のカート、住所の欠落、無効なデータなどをテストします。
• パフォーマンス： チェックアウトのたびに実行されるため、計算の効率を保ちます。
• ロギング： デバッグには console.log を追加しますが、本番環境のログは最小限に抑えます。

拡張機能の登録

拡張機能の登録は必須で、必須の手順が2つあります。

手順1：プラグイン固有の拡張機能ファイルを作成する

各サービスプラグインのフォルダーに、SPIタイプに適したビルダーメソッドを含む extensions.ts ファイルが必要です。

import { extensions } from "@wix/astro/builders";

export const ecomadditionalfeesMyFees = extensions.ecomAdditionalFees({
  id: "{{GENERATE_UUID}}",
  name: "My Additional Fees",
  source: "./extensions/backend/service-plugins/ecom-additional-fees/my-fees/plugin.ts",
});

重要：UUIDの生成

id は、一意で固定のUUID v4文字列である必要があります。拡張機能ごとに新しいUUIDを生成してください。randomUUID() を使用したり、例からUUIDをコピーしたりしないでください。{{GENERATE_UUID}} を、"a1b2c3d4-e5f6-7890-abcd-ef1234567890" のような新たに生成したUUIDに置き換えてください。

ビルダー設定フィールド

すべてのビルダーメソッドは、次の3つのフィールドを受け取ります。

フィールド	型	説明
id	string	GUID形式のサービスプラグインIDです。プロジェクト内のすべての拡張機能で一意である必要があります。
name	string	サービスプラグイン名です（アプリの開発時にアプリのダッシュボードに表示されます）。
source	string	プラグインロジックを含むサービスプラグインハンドラーファイルへのパスです。

SPIタイプ別のビルダーメソッドと受け付けるフィールド：

SPIタイプ	ビルダーメソッド	受け付けるフィールド
配送料金	ecomShippingRates()	id、name、source、description、learnMoreUrl、dashboardUrl、fallbackDefinitionMandatory、thumbnailUrl
追加料金	ecomAdditionalFees()	id、name、source
バリデーション	ecomValidations()	id、name、source、validateInCart
割引トリガー	ecomDiscountTriggers()	id、name、source
ギフトカード	ecomGiftCards()	id、name、source
決済設定	ecomPaymentSettings()	id、name、source、fallbackValueForRequires3dSecure
予約スタッフの並べ替え	bookingsStaffSortingProvider()	id、name、source、methodName、methodDescription、dashboardPluginId

descriptionを受け付けるのはecomShippingRates()のみです。他のビルダーに未対応のフィールドを渡すと、TypeScriptエラーが発生します。bookingsStaffSortingProvider()ではmethodNameとmethodDescriptionが必須で、dashboardPluginIdは任意で指定できます。

ステップ2：メインの拡張機能ファイルに登録する

重要： プラグイン固有の拡張機能ファイルを作成したら、必ずwix-cli-extension-registrationを読み、「App Registration」セクションに従ってsrc/extensions.tsを更新してください。

ステップ2を完了しないと、サービスプラグインはeCommerceシステムで有効になりません。

サービスプラグインのテスト

サービスプラグイン拡張機能をテストするには、次の手順を実行します。

1. バージョンをリリースする：変更を反映します。新しいサービスプラグインや既存のサービスプラグインへの変更は、プロジェクトをビルドしてリリースするまで有効になりません。
2. 関連する操作を実行して、サービスプラグインの呼び出しをトリガーする（例：追加料金をテストするには、カートに商品を追加してカートを表示する）