API クライアント

Framedash API クライアント（@framedash/api-client）は、Framedash 開発者プラットフォームの REST API を型付きで扱う TypeScript / JavaScript クライアントです。@framedash/cli と @framedash/mcp-server の内部で使われているものと同じクライアントを単独パッケージとして公開しており、Framedash のテレメトリを自社の内製ツール・ダッシュボード・自動化処理に直接組み込めます。

認証、プロジェクトスコープのパス生成、レスポンスのアンラップ、構造化エラーに加え、いくつかのセキュリティガード（HTTPS 限定のベース URL、認証情報を漏らさないリダイレクト拒否、リクエストタイムアウト）を内蔵しているため、データの取得に集中できます。

要件

• Node.js 18 以降（グローバル fetch、AbortSignal.timeout、node:net を使用）
• Web API アクセス用の管理者 API キー（fd_admin_ プレフィックス）

ノート

これはブラウザ向け SDK ではなく、Node.js のサーバーサイド / ツール用クライアントです。API キーを X-API-Key ヘッダーで送信するため、信頼できる環境（CI、バックエンドサービス、内部 CLI など）で実行してください。管理者キーをゲームクライアントやブラウザに同梱しないでください。ゲーム内テレメトリには Unity または UE5 の SDK を使用します。

インストール

npm install @framedash/api-client

クイックスタート

import { ApiClient, ApiError } from "@framedash/api-client";

const client = new ApiClient({
  baseUrl: "https://app.framedash.dev",
  apiKey: process.env.FRAMEDASH_API_KEY ?? "",
  projectId: process.env.FRAMEDASH_PROJECT_ID ?? "",
  onError: (err: ApiError) => {
    // onError は成功以外のレスポンスで呼ばれます。必ず throw（または終了）すること。
    // 戻り値の型は `never` です。throw した値は await へ伝播します。
    throw err;
  },
});

// プロジェクトスコープの GET -> /api/v1/projects/{projectId}/dashboard?days=30
const dashboard = await client.get(client.projectPath("dashboard?days=30"));
console.log(dashboard);

クライアントは API のエンベロープを自動でアンラップします。成功時の { "success": true, "data": ... } は data の値だけに解決されます。

設定

ApiClient のコンストラクタは 1 つのオプションオブジェクトを受け取ります:

オプション	型	説明
baseUrl	string	アプリケーションホスト URL（例: https://app.framedash.dev）。HTTPS 必須（HTTP は localhost / ループバックのみ許可）。
apiKey	string	管理者 API キー。毎リクエストの X-API-Key ヘッダーで送信されます。
projectId	string	デフォルトのプロジェクト UUID。projectPath() に必須。プロジェクト外パスでは X-Project-Id ヘッダーとしても送信されます。
onError	(error: ApiError) => never	成功以外のレスポンスで呼ばれます。throw またはプロセス終了が必須です。

ノート

baseUrl はアプリケーションホスト URL です。クライアントが内部的に /api/v1/... などの API パスを付加します（projectPath() がプロジェクトスコープのプレフィックスを構築します）。これは REST API を直接呼び出す際に使う API リファレンス のベース URL（api.framedash.dev/api）とは異なります。どちらも同じエンドポイントに到達します。

ベース URL はクライアント構築時に検証され、安全でない、または不正な URL は即座に throw されます。同じチェックは公開関数 assertSafeBaseUrl(baseUrl) で自分でも実行できます。

リクエストの実行

4 つの HTTP ヘルパーで Web API をカバーします。いずれもアンラップ済みの data ペイロードを返し、ジェネリックパラメータで型を指定できます:

const data = await client.get<MyType>("/api/v1/...");
await client.post("/api/v1/...", body);
await client.patch("/api/v1/...", body);
await client.delete("/api/v1/...");

プロジェクトスコープのパス

ほとんどのエンドポイントはプロジェクト単位です。projectPath(suffix) は、クライアントに設定された projectId を使って /api/v1/projects/{projectId}/{suffix} を構築します:

// GET /api/v1/projects/{projectId}/status
const status = await client.get(client.projectPath("status"));

// GET /api/v1/projects/{projectId}/retention?days=30
const retention = await client.get(client.projectPath("retention?days=30"));

// GET /api/v1/projects/{projectId}/maps
const maps = await client.get(client.projectPath("maps"));

projectId が未設定のまま projectPath() を呼ぶと throw されます。

プロジェクトコンテキストの切り替え

withProject(projectId) は、同じベース URL・API キー・エラーハンドラを再利用しつつ、別プロジェクトにバインドされた新しいクライアントを返します。元のクライアントは変更されません:

const other = client.withProject("another-project-uuid");
const otherStatus = await other.get(other.projectPath("status"));

// 現在バインドされているプロジェクト ID:
console.log(client.currentProjectId);

使用例

SQL クエリの実行

const rows = await client.post("/api/v1/query", {
  sql: "SELECT event_name, count() FROM events GROUP BY event_name",
  project_id: client.currentProjectId,
  limit: 100,
});

アラートの管理

// アラートルールの一覧取得
const alerts = await client.get(client.projectPath("alerts"));

// アラートルールの作成
const created = await client.post(client.projectPath("alerts"), {
  name: "FPS Alert",
  // ...残りのルールフィールド
});

// アラートルールの無効化
await client.delete(client.projectPath(`alerts/${alertId}`));

コンテンツレジストリへのインポート

// content エンドポイントはパス上ではプロジェクトスコープではありません。
// クライアントが設定済みの projectId から X-Project-Id ヘッダーを自動付加します。
// 一括 upsert のボディは配列を entries プロパティで包みます（1 リクエストあたり最大 500 件）。
await client.post("/api/v1/content", { entries });
const content = await client.get("/api/v1/content");

エンドポイント・クエリパラメータ・ペイロード構造の一覧は API リファレンス を参照してください。

エラーハンドリング

成功以外のレスポンス（ネットワークエラー、2xx 以外のステータス、success: true を持たないボディ）はすべて ApiError に変換され、onError コールバックに渡されます。ApiError は解析済みの RFC 9457 Problem Details を保持します:

メンバー	型	説明
status	number	HTTP ステータスコード。
headers	Headers	レスポンスヘッダー（例: X-RateLimit-Reset）。
message	string	人間可読のエラーメッセージ。
retryable	boolean	API がリトライ可能と示したかどうか。
retryAfter	number | undefined	推奨リトライ間隔（秒）。
errorCategory	string | undefined	API のエラーカテゴリ。
problem	ProblemDetails	解析済みの生の Problem Details オブジェクト。

レート制限を考慮したハンドラ:

const client = new ApiClient({
  baseUrl: "https://app.framedash.dev",
  apiKey: process.env.FRAMEDASH_API_KEY ?? "",
  projectId: process.env.FRAMEDASH_PROJECT_ID ?? "",
  onError: (err: ApiError): never => {
    if (err.status === 429) {
      const retryAfter = err.retryAfter ?? err.headers.get("X-RateLimit-Reset");
      throw new Error(`Rate limited; retry after ${retryAfter}`);
    }
    throw err;
  },
});

ノート

onError の戻り値の型は never です。コールバックは必ず throw するか処理を終了させてください。誤って return した場合でも、クライアントは不正な結果を返す代わりに防御的にエラーを throw します。

セキュリティ動作

管理者キーが漏れないよう、クライアントはいくつかの安全策を強制します:

• HTTPS 限定のベース URL。プレーンな HTTP は localhost / ループバックの開発エンドポイントを除き拒否され、認証情報を埋め込んだ URL（https://...@host）も拒否されます。
• リダイレクト不可。API はプログラム的な JSON リクエストをリダイレクトしないため、3xx はすべてエラー扱いです。クライアントはリダイレクト先に X-API-Key ヘッダーを再送しません。
• 1 リクエストあたり 30 秒のタイムアウト（AbortSignal.timeout 経由）。

次のステップ

• API リファレンス — REST エンドポイントの詳細
• CLI リファレンス — このクライアントを利用したコマンドラインツール
• MCP Server — このクライアントを利用した LLM 連携