salla-app-functions-design

アプリの関数 — トリガーと実行タイプを設計する

コードを書く前に、_何_を_いつ_実行するかを決めます。

ステップ 1 — イベントの契約を確認する

ドキュメントに基づくイベントカタログ（トリガーを Merchant と Customer に分類した一覧、同期／非同期のタイプ、ドキュメントに記載された payload.data の形状）は、references/event-contexts.md にあります。ここからトリガーを選び、コンテキストの形状を確認してください。ペイロードを決めつけてはいけません。

信頼できる情報源：現在のトリガー名とカテゴリーは salla_functions action=list_triggers（app_id は不要）で確認できます。トリガーの正式な .d.ts は salla_functions action=get で確認できます。Customer イベントのドキュメントに記載されたペイロードは説明用の例です。これらのフィールド名に依存する前に、action=get またはスキーマドキュメントで確認してください。

確認事項：「このイベントの payload.data のフィールド名は確認済みですか？」

ステップ 2 — 実行タイプを選ぶ

タイプ	タイミング	ユーザーをブロックするか	タイムアウト	戻り値の影響
非同期イベント	操作の後	いいえ	30 秒	Fire-and-forget：ログに記録されますが、フローには影響しません。
同期アクション	操作の前	はい	合計 5 秒	ブロッキング：パラメーターを変更したり、操作を拒否／ブロックしたりできます。

• 同期アクションは merchant_actions カテゴリーに該当するもののみです。shipment.creating と shipment.cancelling が該当します（動詞の形ではなく、salla_functions action=list_triggers でカテゴリーを確認してください）。ライフサイクルが完了する前に介入します。エラーが発生すると 操作がキャンセルされ、成功するとデータを変更できます。ドキュメントに記載された 同期の例は shipment.creating で、単純な Resp ではなく Shipment （(context: Shipments): Promise<Shipment>）を返します。配送番号／ラベルを設定します。ビルダーの仕組み → salla-app-functions-handler。
• 非同期イベント（例：order.created、product.added）は、メインの処理とは別に実行されます。ログに記録されるよう、有効な成功／エラー結果を返してください。

タイムアウトの予算

タイプ	合計タイムアウト	内部の非同期呼び出しごと
同期	ハードリミット 5 秒、目標 < 500 ミリ秒	< 2 秒、AbortController で制限
非同期	30 秒	AbortController で制限

同期アクション中はマーチャントがブロックされるため、500 ミリ秒未満を目標、5 秒を上限としてください。各 fetch／待機中の I/O に上限を設けることで、上流の処理が遅くてもタイムアウトの予算を超えずに済みます（AbortController の仕組み → salla-app-functions-handler）。制限時間を超えると、実行がブロックされる（同期）か、ドロップされます（非同期）。

確認事項：「同期か非同期かを決め、タイムアウトの予算を把握しましたか？」

セキュリティとデータの引き渡し

ハンドラーがトークン、マーチャント認証、または外部への呼び出しを扱う場合は、次の場所に振り分けてください。トークンストレージ／OAuth／マーチャントアクセストークン → salla-app-auth、Webhook の署名検証と冪等性 → salla-webhooks。引き渡し項目の全一覧 → references/event-contexts.md。

次へ：salla-app-functions-handler で実装します。