building-nango-functions

Nango Functions の構築

実行ワークフローを選択せずに、Nango のアクションおよび同期の実装を構築します。

このスキルでは、関数の設計契約を扱います。スキーマ、プロバイダーへの呼び出し、アクションの出力、同期モデル、チェックポイント、削除処理、メタデータ、リトライ、ランタイムの制約が対象です。ローカル CLI による検証／デプロイや、リモート API によるコンパイル／ドライラン／デプロイは対象外です。

タスクが明確にローカル／CLI ベースの場合は、代わりに building-nango-functions-locally を使用してください。明確にリモート／API ベースの場合は、代わりに building-nango-functions-remotely を使用してください。

実装範囲

• Nango 関数の実装を構築または変更する
• createAction() を使用して Nango でアクションを構築する
• createSync() を使用して Nango で同期を構築する
• コンパイル、ドライラン、テスト、デプロイの手順には、アクティブなワークフロースキルを使用する

同期戦略ゲート（コードを書く前に必須）

タスクが同期の場合、コードを書く前に references/syncs.md を読み、まず以下のいずれかの方針を明示してください。

• チェックポイント計画：
  • 変更の検出元（updated_at、modified_since、変更レコードのエンドポイント、カーソル、ページトークン、オフセット／ページ、since_id、または Webhook）
  • チェックポイントのスキーマ
  • チェックポイントによってプロバイダーへのリクエストまたは再開状態がどのように変わるか
  • リクエストが引き続きデータセット全体を走査するのか、変更された行のみを返すのか
  • 削除戦略
• フルリフレッシュの阻害要因：
  • ドキュメントまたはサンプルペイロードに記載された、プロバイダーの具体的な制約
  • チェックポイントを使用できない理由

無効な同期の実装：

• より簡単だからという理由でフルリフレッシュにする
• getCheckpoint() を使用せずに saveCheckpoint() を呼び出す
• チェックポイントをリクエストパラメーターまたはページネーション状態に反映せず、読み取る、または保存する
• 新しい同期で syncType: 'incremental' または nango.lastSyncDate を使用する
• checkpoint スキーマがないフルリフレッシュ、または各ページの後に保存されないフルリフレッシュ。実行ウィンドウを超えると、実行はページ 1 から再開されます
• 残りのページがある場合にのみ実行されるよう saveCheckpoint() を条件で囲む（例：if (nextCursor) { await nango.saveCheckpoint(...) }）。最後のページを含む、成功した各ページで saveCheckpoint() を呼び出す必要があります。そうしないと、1 ページだけの同期でチェックポイント行がないまま clearCheckpoint() に到達し、checkpoint_conflict が発生します。
• clearCheckpoint() より前に trackDeletesEnd() を呼び出す、または先行する clearCheckpoint() なしで呼び出す
• 変更のみを取得するチェックポイント（modified_after、updated_after、変更レコードのエンドポイント）で trackDeletesStart()／trackDeletesEnd() を使用する。これらのリクエストでは変更されていない行が省かれるため、trackDeletesEnd() によってそれらが誤って削除されます。
• 明示的な削除レコードイベントをすでに処理するインクリメンタル同期で trackDeletesStart()／trackDeletesEnd() を使用する

方針を選ぶ

アクション：

• ユーザーが実行する単発のリクエスト。createAction() で構築します
• コードを書く前に references/actions.md を読みます

同期：

• createSync() で構築する、スケジュールまたは Webhook 駆動のキャッシュ更新
• まず同期戦略ゲートを完了します
• コードを書く前に references/syncs.md を読みます

必須入力項目（不足している場合はユーザーに確認）

常に必要：

• インテグレーション ID（プロバイダー名）
• スクリプト／関数名（ケバブケース）
• API リファレンス URL またはサンプルレスポンス
• アクティブなワークフローで関数を検証またはドライランする場合は、接続 ID

アクション固有：

• ユースケースの概要
• 入力パラメーター
• 出力フィールド
• 必要な場合はメタデータ JSON
• アクティブなワークフローでアクションを検証またはドライランする場合は、テスト入力 JSON（入力不要のアクションでは {} を使用）

同期固有：

• モデル名（単数形、パスカルケース）
• 頻度（1時間ごと、5分ごとなど）
• チェックポイントのスキーマ（タイムスタンプ、カーソル、ページトークン、オフセット／ページ、since_id、または複合型）
• チェックポイントがプロバイダーへのリクエストまたは再開状態にどのように反映されるか
• 削除戦略（削除済みレコードのエンドポイント／Webhook、または全件更新が必要な理由）
• 全件更新を提案する場合、ドキュメント／サンプルレスポンスに記載された、チェックポイントの利用を妨げるプロバイダーの制約の具体的な内容
• 必要な場合はメタデータ JSON（team_id、workspace_id）

必須の外部値が不足している場合は、リポジトリとプロバイダーのドキュメントを確認したうえで、要点を絞って質問してください。同期では、プロバイダーが対応している場合、チェックポイントと削除戦略を選択してください。実行可能なチェックポイント戦略が見つからない場合は、全件更新を実装する前に、その理由を具体的に説明してください。

必ず守るルール

共通プラットフォームの制約

• Nango 関数では createAction() ／ createSync() を使用します。
• 任意のパッケージは追加できません。選択したワークフローでサポートされている場合に限り相対インポートを使用できます。組み込みで利用できるのは zod、crypto／node:crypto、url／node:url です。
• 関数コード外で接続の検索、認証情報の取得、プロキシ呼び出しを行うには、Nango HTTP API を使用してください。CLI のトークンや接続コマンドを捏造しないでください。
• 各プロバイダー呼び出しの上に、API ドキュメントへのリンクコメントを追加してください。
• アクションの出力は 2MB を超えてはなりません。
• ファイルのアップロードとダウンロードはアクションとして実装できません（サンドボックス環境：fs なし、axios なし、出力上限 2 MB）。代わりに {integration}/proxy/ 内のプロキシスクリプトで @nangohq/node を使用してください。詳しくは references/actions.md を参照してください。
• HTTP の再試行はデフォルトで 0 です。retries は意図を持って設定してください。通常の上限は 3 とし、同期のプロバイダー呼び出しでは、ドキュメントで安全性と必要性が証明されていない限り、3 を超える値は実質的に禁止です。冪等性をサポートする API でない限り、冪等でない書き込みの再試行は避けてください。
• 非推奨の関数定義ルーティングフィールドは設定しないでください：アクションの endpoint および同期の endpoints。SDK／API を介してアクション名でアクションを実行し、records API を介して同期レコードを取得してください。

同期ルール

• 同期レコードには、安定した文字列の id が必要です。
• 新しい同期では checkpoint スキーマを定義し、最初に nango.getCheckpoint() を呼び出し、各ページまたはバッチの処理後に nango.saveCheckpoint() を呼び出してください。
• チェックポイントが有効なのは、リクエストまたは再開状態（since、updated_after、cursor、page_token、offset、page、since_id など）を変更する場合に限ります。利用せずに保存するだけでは、増分同期にはなりません。
• 新しい同期では syncType: 'incremental' や nango.lastSyncDate を使用しないでください。
• 基本的に nango.paginate(...) と nango.batchSave(...) を使用してください。cursor、link、offset によるページネーションが適している場合は、手動の while (true) ループを避けてください。
• プロバイダーから削除、削除済みレコードを示すマーカー、または削除 Webhook が返される場合は、batchDelete() を優先してください。
• プロバイダーが変更、削除、再開状態を返せない場合、またはデータセットがごく小さい場合に限り、全件再取得を使用してください。
• 全件再取得を使う場合は、ドキュメントまたはペイロードに記載されたプロバイダーの制約を正確に引用してください。「その方が簡単だから」では不十分です。
• 全件再取得の同期でも、増分同期だけでなく、ページネーションの進捗を記録する checkpoint スキーマ（ページ／カーソル／オフセット）が必要です。Nango の同期は実行時間が制限された環境で実行されます。チェックポイントのない全件再取得は、実行時間を超過するたびに1ページ目から再開され、同じ先頭ページを再取得して計算リソースを無駄にするうえ、残りのページに到達できません。
• deleteRecordsFromPreviousExecutions() は非推奨です。全件再取得では、毎回の実行で trackDeletesStart() を呼び出し（安全かつ冪等です。すでに開始済みのウィンドウの開始位置は上書きされません）、各ページの後に saveCheckpoint() を呼び出し、最後のページの後に clearCheckpoint() を呼び出してから、trackDeletesEnd() を呼び出してください。
• 全件再取得では、最後のページを含む各ページの処理成功後に、clearCheckpoint() を呼び出す前に必ず saveCheckpoint() を呼び出してください。「残りのページがある場合」という条件で保存を制御してはいけません。異なる実行経路でチェックポイントが一度も作成されない場合（たとえば、ページを1つも処理しない場合）は、その経路で clearCheckpoint() を呼び出さないでください。実行時に checkpoint_conflict が発生します。この例外を理由に、最後のページのチェックポイント保存を省略してはいけません。
• trackDeletesStart()／trackDeletesEnd() と、変更されたレコードのみを対象とするチェックポイント（modified_after、updated_after、変更レコード用エンドポイントなど）を組み合わせてはいけません。変更のない行が対象外となるため、trackDeletesEnd() によってそれらが削除されてしまいます。
• チェックポイントを使う全件再取得も、全件再取得であることに変わりはありません。trackDeletesEnd() は、チェックポイントを完了してクリアする実行でのみ呼び出してください。
• 同期にメタデータ（例：team_id、workspace_id、guild_id）が必要な場合は、autoStart: false を設定してください。呼び出し元がメタデータを設定するまで同期は実行できないため、自動的に開始すると失敗します。

規約

• フィールドの大文字・小文字は外部 API に合わせてください。パススルーフィールドはプロバイダーの表記を維持し、パススルー以外のフィールドは、その API で多数を占める表記を使用してください。
• 明示的なフィールド名を優先してください。
• ID、タイムスタンプ、列挙値、URL には .describe() の例を追加してください。
• any は避け、インラインのマッピング型を使用してください。
• リストアクションでは cursor と、その API で多数を占める表記に合わせた次のカーソル用フィールド（next_cursor、nextCursor など）を公開してください。
• カスタム検証またはロギングが必要な場合にのみ nango.zodValidateInput() を使用してください。それ以外の場合は、スキーマと選択した検証ワークフローに任せてください。

スキーマのセマンティクス

• デフォルトで、必須ではない入力には .optional() を指定します。
• null に意味がある場合にのみ .nullable() を使用します。通常は更新時に値をクリアする場合です。呼び出し元がフィールドを省略することもできる場合は、.optional() も追加します。
• 生のプロバイダースキーマはプロバイダーに合わせます。省略されたフィールドには .optional()、明示的な null には .nullable() を指定し、プロバイダーが実際に両方に対応している場合にのみ .nullish() を使用します。
• 最終的なアクションの出力と正規化された同期モデルでは、.optional() を優先し、null に意味がなければ、上流の null を省略に正規化します。
• 生成されるスキーマでは、必須ではない入力と正規化された出力にデフォルトで .optional() を指定します。上流の契約で正当化される場合にのみ、許容範囲を広げます。
• z.union([z.null(), T]) または z.union([T, z.null()]) より .nullable() を優先します。
• 出力スキーマで許可されている場合にのみ null を返します。
• z.object() はデフォルトで不明なキーを取り除きます。プロバイダーのデータをそのまま渡すには、z.object({}).passthrough()、z.record(z.unknown())、または最小限の絞り込みを加えた z.unknown() を使用します。

フィールドの命名と大文字・小文字のルール

• APIで多数派の大文字・小文字の形式を使い、明示的なサフィックスを付けます。ID（user_id、userId）、名前（channel_name、channelName）、メールアドレス（user_email、userEmail）、URL（callback_url、callbackUrl）、タイムスタンプ（created_at、createdAt）などです。

マッピングの例（APIが別のパラメーター名を要求する場合）：

const InputSchema = z.object({
    userId: z.string()
});

const config: ProxyConfiguration = {
    endpoint: 'users.info',
    params: {
        user: input.userId
    },
    retries: 3
};

APIが snake_case の場合は、代わりに user_id を使用します。目的は、APIとの一貫性を保つことです。

参考資料

• アクションのパターン、CRUDの例、メタデータの使用方法、ActionErrorの例：references/actions.md
• 同期のパターン、具体的なチェックポイントの例、削除戦略、完全更新へのフォールバック：references/syncs.md

Nangoの便利なドキュメント（クイックリンク）

• FunctionsランタイムSDKリファレンス：https://nango.dev/docs/reference/functions
• アクションの実装：https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action
• 同期の実装：https://nango.dev/docs/implementation-guides/use-cases/syncs/implement-a-sync
• チェックポイント：https://nango.dev/docs/implementation-guides/use-cases/syncs/checkpoints
• 削除の検出（完全更新と差分更新）：https://nango.dev/docs/implementation-guides/use-cases/syncs/deletion-detection
• インテグレーションのテスト（dryrun、--save、Vitest）：https://nango.dev/docs/implementation-guides/platform/functions/testing
• Nango HTTP APIリファレンス：https://nango.dev/docs/reference/api

APIドキュメントが表示されない場合

ウェブからの取得でドキュメントが不完全な場合（JavaScriptでレンダリングされている場合）：

• ユーザーにサンプルレスポンスを依頼します
• ワークスペースに既存のNangoアクションまたは同期があれば、それらをパターンとして使用します
• 成功するまで、スキル固有の検証またはdryrunのワークフローを使用します