fcode-examples

Factorial Code — リファレンス実装

Factorial Code アプリの、実際の運用を想定した一連の実装例です。references/ の各リファレンスでは、実際のサンプルを1つ取り上げ、そのアーキテクチャ、主要なコード、応用方法を説明しています。ルールに重点を置いたスキル（fcode-core-concepts、fcode-javascript／fcode-python、fcode-json-schema、fcode-forms、fcode-cli）を補完するもので、これらのスキルが fcode コードの書き方 を説明するのに対し、このリファレンスでは 完成したアプリの姿 を紹介します。

そのまま貼り付けず、応用してください。 これらは、ユーザーの実際のベンダーや要件に合わせて作り直すためのパターンです。スラッグ、変数、マッピングの名前を変更し、ユースケースに不要なものは削除してください。

参照先

作成するもの…	参照先
Factorial のデータ（給与計算、休暇など）を外部システムに届けるマーケットプレイス連携	references/integration-acme.md
インストール／アンインストールのライフサイクルを持つカスタムアプリ：セットアップフォーム、Webhook、スケジュール	references/custom-app-linear.md
1回限りの自動化：エクスポート／レポート生成、ファイル処理	references/utility-processes.md
フォームから OAuth でサードパーティアカウントに接続するアプリ（API トークンの貼り付けなし）	references/oauth-connect.md

パターン一覧

作成するアプリの種類にかかわらず、特定のパターンの参照先を確認できます。

パターン	リファレンス
outbound-sync 基底クラス（OutboundSync）の拡張	integration-acme
アイテムごとの API プッシュと、集約してファイル配信する方法の比較	integration-acme
アイテムごとの同期ステータス（success／invalid／failed）の報告	integration-acme
プロセスコード内ではなく、プラットフォームによって認証される Webhook のエントリーポイント	integration-acme, custom-app-linear
metadata.json での Webhook／フォームトリガーの有効化と、Webhook の保護（webhook.authMode と、ワークスペースの webhookAuth、マーケットプレイスの appRole）	integration-acme, custom-app-linear
複数ステップのセットアップフォーム（nextProcessId による連鎖）	custom-app-linear
preRenderProcess + #/variables による動的なフォームのドロップダウン	custom-app-linear
フォームの OAuth 接続ボタン（ui:widget: "oauth"）：事前レンダリングで fcode.oauth.start() を呼び出します。プラットフォームが両方のリダイレクト処理を実行し、完了プロセスを呼び出します。完了プロセスはコードを交換し、SDK のコールバックページに 302 リダイレクトします。onComplete: "reload" により、接続済みの状態を表示します	oauth-connect
インストール時の Webhook とスケジュールの作成、アンインストールに備えた記録	custom-app-linear
データストアのカーソルを使ったポーリングと冪等性（重複排除マップ、または利用可能な場合はベンダーの upsert）	custom-app-linear
ベストエフォートのアンインストール／ティアダウン	custom-app-linear
ストレージへのアップロード + 署名付きダウンロード URL + fcode.sendMail によるメール送信	utility-processes
フォームでアップロードされたファイルを Storage から読み込む方法	utility-processes
Factorial API SDK（factorial-sdk モジュール）の呼び出し	3つすべて

基本ワークスペース（常に存在します — 再作成しないでください）

すべての fcode App ワークスペースは、基本アプリから共有モジュールを継承します。fcode.import(...) / fcode.import_module(...) でインポートし、再実装しないでください：

モジュール	配布元	提供内容
factorial-sdk	base-app	createFactorialClient() — 認証済みの @factorialco/api-client / factorial-api-client インスタンス
factorial-utils	base-app	getCompanyId()、setupWebhook()、listWebhookSubscriptions()、deleteWebhookSubscription()
fcode-forms	base-app	フォームスキーマビルダー：selectField()、toOptions()、…
mail-helper	base-app	スタイル設定済みのメール本文用 brandedHtml()
error-handler	base-app	共通エラー処理
outbound-sync	base-integration-app	マーケットプレイス同期用の OutboundSync 基底クラス

インテグレーションアプリは base-integration-app を継承し（base-integration-app は base-app を継承します）、カスタムアプリは base-app を直接継承します。

注：上記の fcode-forms モジュール（fcode.import でインポートするフォームスキーマビルダー）は、Web ページへのフォーム埋め込みについて説明する fcode-forms スキルとは無関係です。

リファレンスではコードを簡潔にするため、定型的なログ処理を省略しています。実際の実装では、共有の fcode-logs モジュールを使用して詳細にログを記録してください（fcode-javascript / fcode-python を参照）。

言語バリアント

すべてのサンプルは、JavaScript（Node.js v22）と Python（3.13）で同じ構造と動作を持つものが用意されています。リファレンスでは JavaScript を示しています。Python バリアントは慣用的な記述のみが異なります（main.py、fcode.import_module、fcode.send_mail、snake_case）。fcode-python を参照してください。