salla-app-functions-validate

App Functions — 保存前に検証する

save が成功しても、検証が始まるだけで、終わりではありません。 salla_functions action=save は、ラッパーの最初と最後の行が一致すると 200 を返しますが、本文の型チェックや実行は行いません。そのため、200 は関数が正しいことを意味しません。すべての salla_functions action=save を、クリーンな状態になるまで検証 → 修正 → 再度 save → 再検証を行う一連のループのトリガーとして扱ってください。型エラーになるハンドラーや実行時に問題が起きるハンドラーは、デプロイ後にデモストアで表面化します。

ループ（以下の各ステップ）：（1） ラッパーの最初と最後の行がテンプレートと一致する → （2） エディターの基準に合わせて、トリガーの .d.ts を使って TypeScript コンパイラーを実行する（非 strict、未使用の TS6133 は無視） → （3） 各 Admin API 呼び出しのリクエスト／レスポンスを、ドキュメント化された OpenAPI に照らして検証する → （4） デモストアで salla_functions action=preview をクリーンに実行する（→ salla-app-functions-test） → 失敗があれば修正して再度 save し、ループをもう一度実行します。ステップ 1～2 は保存前にできる唯一の安全策です。保存のたびに実行してください。

認証情報は保存するソースではなく、App Settings に保持してください（context.settings で読み取ります）。App Functions は外部サービスを呼び出すことがよくありますが、シークレット、トークン、API キーは設定に保存してください。トークン／OAuth の処理 → salla-app-auth、Webhook の署名＋冪等性 → salla-webhooks。

1. テンプレートのラッパーに正確に合わせる（厳守）

ラッパーの最初の行（関数シグネチャ）と最後の行（関数定義の閉じ）は、トリガーによって固定されています。salla_functions action=get の template からラッパーをコピーし、本文だけを編集してください。context パラメーター名、その型、戻り値の型、閉じの行は、与えられたとおりに保ってください。コードはすべて本文の内側に置きます。すべての const／let／function／import／class は、最初と最後の行の間に置いてください（ホイストされた定数やヘルパーが、最もよくある問題の原因です）。

save はテンプレートを取得し、最初または最後のラッパー行が異なる content を拒否し、期待される行を返します。content は本文だけではなく、ラッパー全体を文字列にした関数全体です。保存時に本文自体はチェックされません。それを確認するのが、ステップ 2 のローカルな tsc チェックです。

2. トリガーの型で型チェックする（エディターの基準に合わせる）

Portal エディターは、Monaco の TypeScript ワーカー（typescript コンパイラー）で検証します。addExtraLib を使ってトリガーの .d.ts（config.types）を読み込み、デフォルトのコンパイラーオプションは非 strictで、TS6133（宣言済みだが未使用）を無視します。実際に保存を妨げる条件より厳しくならないよう、同じコンパイラー、同じ型、同じ許容度で検証してください。

types（action=get から取得）は .d.ts のURLのリストで、エディターが読み込むライブラリそのものです。ハンドラーの隣にそれぞれをダウンロードしてください。このトリガーについて action=get が返す URL だけを取得し（任意またはユーザー指定の URL は使わないでください）、手書きのモックではなく実際の .d.ts を使用します。

curl -sSL "https://…/shipments.d.ts" -o salla-globals.d.ts   # one per types URL

ラッパー全体を handler.ts に入れ、エディターの基準に合わせて両方を型チェックしてください。非 strict（Monaco のデフォルト）、出力なしで、エディターが無視する TS6133（未使用）以外のエラーをすべて修正します。

# Editor's bar: non-strict, ignores unused (TS6133)
npx -y -p typescript tsc --noEmit --skipLibCheck salla-globals.d.ts handler.ts

任意の、より厳格な上位基準： --strict を使うとさらに多くの問題を検出できますが、エディターの基準は非 strict で、未使用（TS6133）を無視します。エディターより高い基準を選ぶ場合に限り、保存前に --strict の問題を解消してください。これは保存を妨げる条件ではありません。

npx -y -p typescript tsc --noEmit --strict --skipLibCheck salla-globals.d.ts handler.ts  # optional, stricter than the editor

types の URL にアクセスできない場合は、再試行するか、action=get から再取得してください。手書きのモックは最終手段としてのみ使用し、1 つのトリガー専用に形を合わせてください。以下の例は配送用の形なので、コンテキストの型名を変更し、トリガーに合わせて payload を調整してから、まずそのトリガーの types で実際の形を確認してください。

// ILLUSTRATIVE fallback — verify the exact shape from the trigger's `types` (action=get).
declare class Resp {
  static success(): Resp;
  static error(): Resp;
  setStatus(status: number): Resp;
  setMessage(message: string): Resp;
  setData(data: Record<string, unknown>): Resp;
}
declare type Shipments = {
  merchant?: { id?: string | number };
  payload?: {
    event?: string;
    created_at?: string;
    data?: Record<string, unknown>;
  };
  settings?: Record<string, unknown>;
};

確認事項：「最初と最後のラッパー行がテンプレートと一致し、すべてのコードがラッパーの内側にあり、トリガーの types を使った tsc --noEmit がエディターの基準（非 strict、TS6133 は無視）でエラーなくコンパイルされるか？」→ ステップ 3。

3. ドキュメント化されたスキーマに照らして、Admin API への送信リクエストを検証する

ステップ 1～2 ではハンドラーの構造を確認します。このステップでは、ハンドラーが呼び出す Admin API まで確認します。関数がドキュメント化されたエンドポイントを呼び出す場合は、そのエンドポイントの OpenAPI スキーマに照らして、リクエストのボディ／パラメーター と 解析済みレスポンスを検証します。Salla のドキュメントページ（docs.salla.dev/<id>.md）には、完全な OpenAPI 3.x ブロック（パス、components スキーマ、型、列挙値、required）が含まれています。

各呼び出しについて、salla-api-core の標準的な ドキュメントの OpenAPI を読む → 一致するように構築する → 検証する → 修正する → 再試行する ループを実行します。エンドポイントのドキュメント ID を確認し（→ salla-docs）、リクエストと解析済みレスポンスをスキーマの required／型／列挙値に照らして確認し、不一致があれば修正して、問題がなくなるまで再実行します。ここでループを繰り返し説明しないでください。ループの管理は salla-api-core が担います。

ゲート：「ドキュメント化された各 Admin API 呼び出しのリクエストと解析済みレスポンスは、エンドポイントの OpenAPI スキーマに照らして問題なく検証されますか？」→ ステップ 4。

4. デモストアで保存した関数を実行する

tsc とスキーマ検証に問題がなくても、実際のデータで関数が正しく動作するとは限りません。save した後、デモストアで salla_functions action=preview を実行し、ハンドラーをエンドツーエンドでテストします（→ salla-app-functions-test）。プレビューが失敗するか、誤った結果を返した場合は、ボディを修正し、再度 save して、プレビューに問題がなくなるまでステップ 1～4 を再実行します。

ゲート：「ラッパー、tsc、各 Admin API 呼び出しのスキーマ検証に問題がなく、デモストアで action=preview が問題なく実行されますか？」→ salla-app-functions-release。