APIリファレンス

概要

サイドカーは単一のエフェクトです HttpApi。すべてのエンドポイントは型付きです HttpApiEndpoint スキーマチェックされたリクエストおよびレスポンスボディを使用するため、この参照、生成された SDK、および実行中のサーバーは、次の同じ宣言から取得されます。 packages/api.

ベースURL

ホストされた CADCAMFUN API はありません。サイドカーはマシン上で実行され、バインドされます 127.0.0.1 オペレーティング システムが選択したポート上で (ポート 0 でリッスンします)、独自のチェックを行います /api/health、そしてその後のみ標準出力に 1 行の JSON を出力します。ベースURLは http://127.0.0.1:<port> その線から。

export CADCAMFUN_TOKEN=dev-token
CADCAMFUN_DATA_DIR=$(mktemp -d) \
CADCAMFUN_MIGRATIONS_DIR=$PWD/packages/db/drizzle \
CADCAMFUN_AI_OFFLINE=true \
  bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":46709}
export CADCAMFUN_URL=http://127.0.0.1:46709

認証

契約では 1 つのセキュリティ スキームが宣言されています。 bearer (HTTP Bearer）。 324 回中 325 回の操作でこれが必要です。のみ GET /api/health 公開されています。

curl -s "$CADCAMFUN_URL/api/health"
curl -s "$CADCAMFUN_URL/api/projects" -H "Authorization: Bearer $CADCAMFUN_TOKEN"

慣例

• JSON 入力、JSON 出力。 身体は application/json カードに別途記載がない限り、2 つのマルチパート アップロード、1 つのオクテット ストリーム Webhook、1 つの JavaScript ブートストラップ、zip ダウンロード、1 つのバイナリ プラグイン ファイル、および 2 つのイベント ストリーム。
• オペレーション ID は点線で表示されます。 projects.get, vcs.commit: グループ タグ、ドット、生成されたクライアントによって使用されるメソッド名。
• エラーが入力されます。 障害はエンドポイントごとに宣言され、 _tag;メッセージを解析する代わりにスイッチをオンにします。コントラクト全体で、401 は 269 オペレーションで宣言され、500 は 264 で宣言され、400 は 206 で宣言されます。
• 動作アンカーは安定しています。 各カードは次のようにリンクできます #op-<method>-<path>、 例えば /docs/api/projects#op-get-api-projects-id.

ストリーミング

curl -N "$CADCAMFUN_URL/api/projects/$PROJECT_ID/events" \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN"

クライアント

@cadcamfun/api/sdk これと同じコントラクトから生成されます。以下のすべての操作 ID は、 CadCam.make(...)、パスパラメータと本文フィールドの 1 つのフラットな入力を受け取ります。 259 オペレーションのうち 325 が生成されます。各カードにはその正確なコールが表示されます。

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

const projects = await client.projects.list()
const created = await client.projects.create({ name: "Bracket" })

リソース

325 グループの 35 オペレーションを、提供するものごとに並べたもの。

コア

デザイン

製造業

リソース

拡張機能

アカウント

OpenAPIドキュメント

ダウンロード /docs/api/openapi.json (このサイトがレンダリングするチェックインされたスナップショット) または、実行中のサイドカーからライブ ドキュメントをフェッチします。 /api/openapi.json。次のコマンドでスナップショットを再生成します。 bun run generate:api-reference で packages/web エンドポイントを変更した後。

契約とサーバー

@cadcamfun/api effect HttpApi を使用してリクエストとレスポンスのスキーマを定義します。ルートをエクスポートします Api、ドメイン レコード、タグ付きエラー、およびクライアント。リクエスト ハンドラー、認可決定、データベース クエリ、プロバイダー呼び出しはサイドカーで実行されます。スキーマをインポートしてもサーバーは起動しません。

サイドカーは、サービスされたコントラクトを次の場所に公開します。 GET /api/openapi.json。その実行中のドキュメントを使用して、接続しているアプリケーションのメソッド、パス パラメーター、ペイロード、およびステータス コードを検査します。サーバーはそのグループを組み立てます。 apps/sidecar/src/layers.ts;共有コントラクトは以下にまとめられます packages/api/src/index.ts.

認証とアイデンティティ

保護されたルートには次のものが必要です Authorization: Bearer <token>。デスクトップは、サイドカーの開始時に新しいアプリケーション トークンを受け取ります。 GET /api/health 公衆衛生調査です。ネイティブ /health そして /version 保護されています。アプリケーション ベアラー トークンは、タイミングセーフな比較で比較されます。

オプションの x-session-token アカウントセッション JWT を伝送します。ベアラー トークンはローカル アプリケーションを許可します。セッションはその代理アカウントを選択します。存在しないセッション、期限切れのセッション、無効なセッション、または孤立したセッションは、インストールのローカル プロファイルにフォールバックします。次に、リソース ハンドラーは、リポジトリ承認ヘルパーを通じて所有権または組織へのアクセスを確認します。

スコープ付きブリッジ トークンは、次のことのみを許可します。 GET /api/ai/actions そして POST /api/ai/actions/invoke。プロジェクト CRUD、資格情報設定、またはその他の HTTP ルートへのアクセスは許可されません。そのプロジェクトと読み取り/書き込みスコープは、アクション ブリッジによって再度チェックされます。

リソースファミリー

• デザイン： プロジェクト、図面、コンポーネント、図面バージョン、エンティティのインポート/エクスポート、正確な CAD 解析、STEP エクスポート、アセンブリ解析。
• 製造: ツールパスとバージョン、コメント、ジェネレーターの提案、解析、リプレイ検証、ネイティブ製造ジョブ、材料、ツール、マシン構成、ライブラリ項目、および製造コスト。
• アシスタント： プロバイダー、認証情報、モデル、セッション、ストリーミング ターン、セッション コントロール、アクション、プロジェクト メモリ、ワークスペース コンテキスト、およびステートレス アドバイス。
• コラボレーション： ブランチ、コミット、差分、プル リクエスト、レビュー、GitHub ミラー、ワークフロー ファイルと実行、ライブ イベント、コンパニオン ペアリング。
• アプリケーションサービス: ユーザー、認証、組織、通知、ファイル、プラグイン、請求、分析、待機リスト、MCP 構成、ローカル キーと値のストレージ。

コントラクト グループは、エンドポイント固有の応答形状を保持します。クライアントは、アプリケーション全体の単一の JSON エンベロープを想定するのではなく、呼び出す操作のスキーマをデコードする必要があります。

対応と失敗

一般的なタグ付きエラーは HTTP 400 にマップされます (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict)、および 500 (InternalError）。宣言されたスキーマには、人間が読める形式のスキーマが含まれています。 message。一部のグループでは封筒を使用します。 success: false, message、 そして errors;少数の場合は error 分野。

成功の応答は、レコード、配列、NULL 許容値、またはエンベロープにすることができます。 Envelope 含まれています success, message、 そして data; EnvelopeOpt メッセージをオプションにします。作成エンドポイントは、必要に応じて 201 を明示的に宣言します。 HTTP ステータスとエンドポイント スキーマを確認せずに、JSON フィールドだけから成功を推測しないでください。

スキーマ デコードでは、ハンドラーが実行される前にトランスポート入力が検証されます。ビジネス検証は引き続きサービス内で実行されます。構造的に有効なリクエストは、アクセスできない図面を参照しているか、古い製造成果物が含まれているか、競合するブランチ操作をリクエストしている可能性があります。

共有クライアントを使用する

ApiClient.layer かかります baseUrl そしてアプリケーション token。フェッチトランスポートとクライアント認証ミドルウェアを提供します。そのメソッドは以下から直接派生しています。 Api, したがって、このクライアントは、コード生成によって省略される操作もカバーします。

import { ApiClient } from "@cadcamfun/api"
import { Effect } from "effect"

const projects = Effect.gen(function* () {
  const api = yield* ApiClient
  return yield* api.projects.list()
}).pipe(Effect.provide(ApiClient.layer({ baseUrl, token })))

ベース URL は、サイドカーのループバック アドレスと割り当てられたポートです。起動間でポートを保持するのではなく、デスクトップ接続から解決します。 URL やログにトークンを含めないようにしてください。

設計・製作のご依頼

プロジェクト運営の用途 /api/projects;図面とツールパスには独自のコレクションと詳細ルートがあります。 POST /api/toolpaths/generate g コード、解析されたプログラム データ、警告、およびジェネレーターの設定とジオメトリからの統計を生成します。 /suggest, /parse、 そして /verify パラメーターのアドバイス、G コードの解釈、ストックの再生を公開します。これらの計算では、保存されたツールパスは作成されません。

POST /api/toolpaths/manufacture バージョン管理された CAD スナップショットを受け取り、NC、ツールの割り当て、切断データ、クレーム、問題、リリース レベルを含むカーネル結果を返します。ツールパスの作成または更新操作を通じて、結果のドキュメントを個別に保存します。見る セットアップ 永続化中の証拠検証用。

POST /api/cad/exact/analyze, /step、 そして /assembly 明示的な要素または保存された図面識別子を受け入れます。保存された図面を読み取ると、呼び出し元の通常の図面アクセス チェックが適用されます。

ストリーミングとリカバリ

AI ストリームは、テキスト、推論、ツールの呼び出しと結果、許可と質問のリクエスト、再試行、ターン ステート、コンテキスト、および完了の型指定されたイベントを伝送します。クライアントはイベントを段階的に消費し、セッション ID を保持する必要があります。 HTTP 接続の終了は、モデルのターンが終了したことを示す十分な証拠ではありません。セッション状態は、再接続後に再度読み取ることができます。

AI イベント スキーマが存在する packages/api/src/ai-events.ts そして packages/ai/src/events.ts。一般的なライブ イベントはイベント グループを使用します。バイナリのダウンロード、JavaScript プラグインのブートストラップ応答、および署名された生の Webhook 本体には、独自のトランスポート処理が必要です。

ページ結果が使用するルートをリストする page そして limit クエリパラメータ。マシン構成については、 page デフォルトは 1、 limit デフォルトは 20 で、1 ～ 100 に固定され、応答は次のようになります。 pagination と page, limit, total、 そして totalPages (apps/sidecar/src/http/machine-configs.ts）。実際に宣言されているパラメータについては、各グループのリファレンス ページを確認してください。

生成されたSDK

@cadcamfun/httpapi-codegen httpApi グループを操作メタデータと生成されたクライアントに反映します。 The API generator writes a Promise SDK to packages/api/src/sdk/generated そしてクライアントに影響を与える packages/api/src/client/generated。パブリック Promise SDK は次のようにエクスポートされます。 @cadcamfun/api/sdk.

bun run --filter @cadcamfun/api generate
bun run --filter @cadcamfun/api generate:check

生成されたターゲットはどちらも、プロファイルのマルチパートのアップロード、プラグインのマルチパートのインストール、複数の成功スキーマを使用した MCP の作成、衝突する識別子を使用した MCP の更新、重複した入力名を使用したプロジェクト ツールパスの作成、およびストリーム ヘッダーを使用したプラグイン ファイルの提供を省略します。 Promise ターゲットでは、Stripe の生の Webhook、プラグインの JavaScript ブートストラップ、バイナリ ファイルのダウンロード、ジェネレーターの生成/提案リクエストも省略されます。これらの省略は明確に示されています packages/api/scripts/generate-clients.ts;これらの操作には、コントラクト クライアントまたは適切な raw トランスポートを使用します。

ソース組織

groups/ リソース契約が含まれています。共有ジオメトリと CAM スキーマの由来 @cadcamfun/core; cad-exact.ts, cam-kernel.ts、 そして cam-program.ts 豊富な CAD/CAM 結果とポータブル ドキュメントを説明します。 client.ts はコントラクト クライアントを構築し、生成スクリプトは生成されたターゲットと省略リストを所有します。

統合ルール

トランスポート境界でコントラクト スキーマを再利用し、データベースの依存関係をサイドカーに保持します。コントラクト、ハンドラー、サービスまたはリポジトリ、および集中的な HTTP カバレッジを通じてエンドポイントを導入します。生成されたファイルは出力です。コントラクトまたはジェネレーターを編集して再生成します。 API スキーマ バージョン、ポータブル ファイル バージョン、およびプラグイン API バージョンは、個別のコントラクトを記述します。

リソースリファレンス

325 オペレーション 横切って 232 個のパス そして 35 個のリソース グループ、56 という名前のスキーマを使用します。各リソース ページにはその操作がリストされ、宣言されたパス/クエリ/ヘッダー パラメーター、必須およびオプションのフィールド、Null 許容値、コンテンツ タイプ、成功およびエラーのステータス、および完全なスキーマが表示されます。

データはから出力されます packages/api/src/index.ts、クライアントとサイドカーによって使用される同じ構成された HttpApi コントラクト。これらのページには、チェックアウトされた契約について説明されています。実行中のサーバーを検査する /api/openapi.json 別のバージョンに接続する場合。

OpenAPI JSON をダウンロード · キャプチャされた応答でリクエストを追跡する

接続とリクエストの規則

API は、固定ホスト型エンドポイントではなく、ローカル サイドカーによって提供されます。 Tauri は、動的に選択されたループバック URL と起動トークンを取得します。手動で開始されたサイドカーは、JSON Ready イベントでそのポートをアナウンスします。ペアリングされたモバイル クライアントは、代わりに構成された HTTPS ゲートウェイを介して接続します。

curl --silent --show-error "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

実際の接続から両方の変数を設定します。リソース ページのリクエスト テンプレートでは、プレースホルダーとペイロード ファイルを意図的に使用します。オプションのトランスポート フィールドは、すべてのビジネス オペレーションで省略できるという保証はありません。たとえば、プロジェクトの作成では、ハンドラーで名前が欠落していると拒否されます。

生成された参照メンテナンス

packages/web/script/generate-api-reference.mjs aPI パッケージのインストールされたエフェクト実装を使用して、構成されたコントラクトを読み取り、参照 JSON を書き込みます。ドキュメント ワーカーは生成されたコンテンツを消費します。ドキュメント要求に応答するためにアプリケーション サーバーを初期化するわけではありません。

bun run generate:api-reference
bun run check:api-reference
bun run check:docs-index

リソース カバレッジは、宣言されたすべての操作に対してチェックされます。新しく追加されたグループは、読者向けのメタデータとナビゲーションを受信する必要があり、変更されたリクエストまたはレスポンスを再生成する必要があります。手書きのガイドでは、HTTP スキーマだけでは表現できない認可ルール、副作用、サービス構成、および制限について説明しています。

統合レシピ

から始める キャプチャされたHTTPリクエスト プロジェクトの作成、ビジネス検証、ベアラーの拒否、関連レコード、キーと値の永続化が実際にどのように反応するかを確認します。使用 型付きクライアントの統合 promise SDK または Effect クライアントを使用してこれらの操作を再現し、それらの個別の失敗チャネルを処理します。

これらのレシピは、HTTP コントラクトを実際のサービスの動作に結び付けます。スキーマは、必要なプレゼンス、エンコーディング、および返される形状を記述することができます。リンクされたガイドでは、アクセス ルール、永続化効果、サポートされているリカバリ、およびこれらのタイプだけからは推測できない制限について説明しています。

リソースグループごとの操作

現在、コントラクトでは、270 グループの 34 オペレーションがすべて単一の下で宣言されています。 bearer HTTP セキュリティ方式。ベアラーセキュリティのない唯一の業務は公衆衛生調査です。このテーブルは、生成された OpenAPI ドキュメント、つまりグループごとの操作、使用される HTTP メソッド、個別のパスの数、および 1 つの代表的なパスから計算されます。

契約全体のステータス コード

宣言された各応答を操作ごとに 1 回カウントすると、クライアントが何をデコードする準備ができていなければならないかが次のようにわかります。

すべてのエラーは Effect タグ付きエラーであるため、その JSON 本文には常に _tag そのフィールドの隣にある識別子。既存のクライアントが引き続き動作できるように、従来のハンドラーから継承された 3 つの本体ファミリーがあります。

{ "_tag": "NotFound", "message": "Project not found" }

{ "_tag": "EnvNotFound", "success": false, "message": "Material not found", "errors": null }

{ "_tag": "KeyedInternal", "error": "Failed to load components" }

成功エンベロープはエラー エンベロープを反映しています。 { success: true, message, data }、 どこ data 多分 null。の EnvelopeOpt 異形の省略 message ハンドラーがそれを提供しなかった場合。スイッチオン _tag の存在ではなく message または error.

リクエストの処理方法

1. ルーターはメソッドとパスを一致させます。未知のルートはハンドラーに到達しません。
2. ベアラー ミドルウェアは一定時間内にトークンを比較します。トークンが欠落しているか間違っていると、デコードの前にリクエストが 401 で停止されます。
3. パス、クエリ、ヘッダー、および本文は、操作のスキーマに対してデコードされます。ビジネス コードを実行しなくても、構造的な問題は 400 になります。
4. ハンドラーは、代理アカウントを解決し、所有権または組織のメンバーシップ (403/404) を確認して、サービスを実行します。
5. 結果は宣言された成功スキーマでエンコードされるか、失敗はタグ付けされたエラー スキーマとステータスでエンコードされます。

JSON ではない応答

生成された Promise SDK は、コンテンツ タイプが次のとおりではないストリーミング応答を拒否します。 text/event-stream と ClientError("UnsupportedContentType")、および 16 MiB を超える単一の SSE イベント SseEventTooLarge.

クライアントなしで API を呼び出す

type TaggedError = { _tag: string; message?: string; error?: string }

async function call<T>(base: string, token: string, method: string, path: string, body?: unknown): Promise<T> {
  const response = await fetch(new URL(path, base), {
    method,
    headers: {
      authorization: `Bearer ${token}`,
      ...(body === undefined ? {} : { "content-type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  if (response.status === 204) return undefined as T
  const payload = await response.json()
  if (!response.ok) {
    const failure = payload as TaggedError
    throw new Error(`${response.status} ${failure._tag}: ${failure.message ?? failure.error}`)
  }
  return payload as T
}

const project = await call<{ id: string; name: string }>(
  process.env.CADCAMFUN_URL!, process.env.CADCAMFUN_TOKEN!,
  "POST", "/api/projects", { name: "Bracket" },
)

TypeScript で生成されたクライアントを優先します。クライアントは各操作の成功ステータスと宣言されたエラー ステータスを認識しており、それ以外のものはすべて同様に扱います。 UnexpectedStatus 推測する代わりに。

3Dで