Référence API

Aperçu

Le sidecar est un seul effet HttpApi. Chaque point de terminaison est un typé HttpApiEndpoint avec des corps de requête et de réponse vérifiés par le schéma, donc cette référence, le SDK généré et le serveur en cours d'exécution proviennent de la même déclaration dans packages/api.

URL de base

Il n’existe pas d’API CADCAMFUN hébergée. Le sidecar fonctionne sur votre machine, se lie 127.0.0.1 sur un port choisi par le système d'exploitation (il écoute sur le port 0), vérifie le sien /api/health, et imprime ensuite seulement une ligne JSON sur la sortie standard. L'URL de base est http://127.0.0.1:<port> de cette ligne.

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

Authentification

Le contrat déclare un système de sécurité, bearer (HTTP Bearer). 324 opérations sur 325 l'exigent ; seulement GET /api/health est publique.

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

Congrès

• JSON en entrée, JSON en sortie. Les corps sont application/json sauf indication contraire sur une carte : deux téléchargements en plusieurs parties, un webhook de flux d'octets, un bootstrap JavaScript, un téléchargement zip, un fichier de plugin binaire et deux flux d'événements.
• Les identifiants d’opération sont en pointillés. projects.get, vcs.commit: la balise group, un point, le nom de la méthode utilisée par les clients générés.
• Les erreurs sont tapées. Les échecs sont déclarés par point de terminaison et portent un _tag; allumez-le au lieu d’analyser les messages. Dans l'ensemble du contrat, 401 est déclaré sur 269 opérations, 500 sur 264 et 400 sur 206.
• Les ancres d’opération sont stables. Chaque carte peut être liée comme #op-<method>-<path>, par exemple /docs/api/projects#op-get-api-projects-id.

Streaming

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

Clientèle

@cadcamfun/api/sdk est généré à partir de ce même contrat : chaque identifiant d'opération ci-dessous est une méthode typée sur CadCam.make(...), en prenant une entrée plate des paramètres de chemin et des champs de corps. 259 des 325 opérations sont générées ; chaque carte montre son appel exact.

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" })

Ressources

325 opérations dans 35 groupes, classées en fonction de ce qu'elles servent.

Cœur

Conception

Fabrication

Ressources

Rallonges

Comptes

Document OpenAPI

Télécharger /docs/api/openapi.json (l'instantané archivé rendu par ce site) ou récupérez le document en direct à partir d'un sidecar en cours d'exécution à l'adresse /api/openapi.json. Régénérez l'instantané avec bun run generate:api-reference dans packages/web après avoir modifié un point de terminaison.

Contrat et serveur

@cadcamfun/api définit les schémas de demande et de réponse avec Effect HttpApi. Il exporte la racine Api, enregistrements de domaine, erreurs marquées et clients. Les gestionnaires de requêtes, les décisions d'autorisation, les requêtes de base de données et les appels de fournisseur s'exécutent dans le sidecar. L'importation d'un schéma ne démarre pas un serveur.

Le sidecar publie son contrat servi sur GET /api/openapi.json. Utilisez ce document en cours d'exécution pour inspecter les méthodes, les paramètres de chemin, les charges utiles et les codes d'état de l'application à laquelle vous êtes connecté. Le serveur rassemble ses groupes dans apps/sidecar/src/layers.ts; le contrat partagé est assemblé en packages/api/src/index.ts.

Authentification et identité

Les itinéraires protégés nécessitent Authorization: Bearer <token>. Le bureau reçoit un nouveau jeton d'application au démarrage de son sidecar. GET /api/health est l’enquête de santé publique ; indigène /health et /version sont protégés. Les jetons du porteur d'application sont comparés avec une comparaison sécurisée dans le temps.

Un facultatif x-session-token porte une session de compte JWT. Le jeton au porteur admet l'application locale ; la session sélectionne son compte intérimaire. Une session absente, expirée, invalide ou orpheline revient au profil local de l'installation. Les gestionnaires de ressources vérifient ensuite la propriété ou l'accès à l'organisation via les assistants d'autorisation du référentiel.

Un jeton de pont étendu admet uniquement GET /api/ai/actions et POST /api/ai/actions/invoke. Il n'accorde pas l'accès au CRUD du projet, aux paramètres d'informations d'identification ou à d'autres routes HTTP. Son projet et sa portée en lecture/écriture sont à nouveau vérifiés par le pont d'action.

Familles de ressources

• Conception: projets, dessins, composants, versions de dessins, importation/exportation d'entités, analyse CAO exacte, exportation STEP et analyse d'assemblage.
• Fabrication: parcours d'outils et versions, commentaires, suggestions de générateurs, analyse, vérification de relecture, tâches de fabrication natives, matériaux, outils, configurations de machines, éléments de bibliothèque et coûts de production.
• Assistant: fournisseurs, informations d'identification, modèles, sessions, tours de streaming, contrôles de session, actions, mémoire de projet, contexte de l'espace de travail et conseils sans état.
• Collaboration: branches, validations, différences, demandes d'extraction, critiques, miroirs GitHub, fichiers et exécutions de workflow, événements en direct et couplage de compagnons.
• Services applicatifs : utilisateurs, authentification, organisations, notifications, fichiers, plugins, facturation, analyses, liste d'attente, configuration MCP et stockage local de valeurs-clés.

Les groupes contractuels conservent leurs formes de réponse spécifiques au point final. Un client doit décoder le schéma de l’opération qu’il appelle au lieu de supposer une seule enveloppe JSON à l’échelle de l’application.

Réponses et échecs

Les erreurs marquées courantes correspondent à HTTP 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict), et 500 (InternalError). Leurs schémas déclarés portent un format lisible par l'homme message. Certains groupes utilisent une enveloppe avec success: false, message, et errors; un petit nombre utilise un error champ.

Les réponses réussies peuvent être un enregistrement, un tableau, une valeur nullable ou une enveloppe. Envelope comprend success, message, et data; EnvelopeOpt rend le message facultatif. Les points de terminaison de création déclarent explicitement 201 le cas échéant. Ne déduisez pas le succès uniquement à partir d'un champ JSON sans vérifier l'état HTTP et le schéma du point de terminaison.

Le décodage du schéma valide l'entrée de transport avant l'exécution du gestionnaire. La validation métier s'exécute toujours dans le service : une demande structurellement valide peut faire référence à un dessin inaccessible, contenir un artefact de fabrication obsolète ou demander une opération de branche conflictuelle.

Utiliser le client partagé

ApiClient.layer prend un baseUrl et candidature token. Il fournit le transport de récupération et le middleware d'autorisation client. Ses méthodes sont directement dérivées de Api, ce client couvre donc également les opérations omises par la génération de code.

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 })))

L'URL de base est l'adresse de bouclage du sidecar et le port attribué. Résolvez-le à partir de la connexion du bureau, plutôt que de conserver un port lors des lancements. Gardez les jetons hors des URL et des journaux.

Demandes de conception et de fabrication

Utilisation des opérations du projet /api/projects; les dessins et les parcours d'outils ont leurs propres collections et itinéraires détaillés. POST /api/toolpaths/generate produit du code G, des données de programme analysées, des avertissements et des statistiques à partir des paramètres et de la géométrie du générateur. /suggest, /parse, et /verify exposez des conseils sur les paramètres, l’interprétation du code G et la relecture des stocks. Ces calculs ne créent pas de parcours d'outil enregistré.

POST /api/toolpaths/manufacture accepte un instantané CAO versionné et renvoie un résultat du noyau avec la CN, les affectations d'outils, les données de coupe, les réclamations, les problèmes et un niveau de version. Enregistrez un document résultant séparément via une opération de création ou de mise à jour de parcours d'outil. Voir Configurations pour la validation des preuves pendant la persistance.

POST /api/cad/exact/analyze, /step, et /assembly accepter des éléments explicites ou un identifiant de dessin stocké. La lecture d'un dessin stocké applique les contrôles d'accès aux dessins normaux de l'appelant.

Streaming et récupération

Le flux d'IA transporte des événements typés pour le texte, le raisonnement, les appels et les résultats d'outils, les demandes d'autorisation et de questions, les tentatives, l'état du tour, le contexte et l'achèvement. Les clients doivent consommer les événements de manière incrémentielle et conserver l'identifiant de session. La fin d'une connexion HTTP n'est pas une preuve suffisante de la fin d'un tour de modèle : l'état de la session peut être relu après la reconnexion.

Les schémas d'événements IA sont présents dans packages/api/src/ai-events.ts et packages/ai/src/events.ts. Les événements généraux en direct utilisent le groupe d'événements. Les téléchargements binaires, les réponses d'amorçage du plug-in JavaScript et les corps de webhook bruts signés nécessitent leur propre gestion de transport.

Répertorier les itinéraires que la page utilise dans leurs résultats page et limit paramètres de requête. Pour les configurations de machines, page la valeur par défaut est 1, limit la valeur par défaut est 20 et est limitée à 1–100, et la réponse porte pagination avec page, limit, total, et totalPages (apps/sidecar/src/http/machine-configs.ts). Vérifiez la page de référence de chaque groupe pour connaître les paramètres qu'il déclare réellement.

SDK générés

@cadcamfun/httpapi-codegen reflète les groupes HttpApi dans les métadonnées d'opération et les clients générés. Le générateur d'API écrit un SDK Promise dans packages/api/src/sdk/generated et inciter les clients à packages/api/src/client/generated. Le SDK public Promise est exporté sous @cadcamfun/api/sdk.

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

Les deux cibles générées omettent le téléchargement en plusieurs parties du profil, l'installation du plug-in en plusieurs parties, la création de MCP avec plusieurs schémas de réussite, la mise à jour du MCP avec des identifiants en collision, la création de parcours d'outils de projet avec des noms d'entrée en double et la diffusion de fichiers de plug-in avec des en-têtes de flux. La cible Promise omet également les webhooks bruts Stripe, le bootstrap JavaScript du plug-in, le téléchargement de fichiers binaires et les requêtes de génération/suggestion du générateur. Ces omissions sont explicites dans packages/api/scripts/generate-clients.ts; utiliser le client contractuel ou le transport de matières premières approprié pour ces opérations.

Organisation source

groups/ contient des contrats de ressources. La géométrie partagée et les schémas CAM proviennent de @cadcamfun/core; cad-exact.ts, cam-kernel.ts, et cam-program.ts décrire de riches résultats CAO/FAO et des documents portables. client.ts construit le client contractuel, tandis que le script de génération possède les cibles générées et les listes d'omissions.

Règles d'intégration

Réutilisez les schémas de contrat aux limites de transport et conservez les dépendances de base de données dans le sidecar. Présentez un point de terminaison via son contrat, son gestionnaire, son service ou son référentiel et sa couverture HTTP ciblée. Les fichiers générés sont des sorties : éditez leur contrat ou générateur et régénérez-les. Une version de schéma API, une version de fichier portable et une version d'API de plugin décrivent des contrats distincts.

Référence des ressources

325 opérations à travers 232 chemins et 35 groupes de ressources, avec 56 schémas nommés. Chaque page de ressources répertorie ses opérations et affiche les paramètres de chemin/requête/en-tête déclarés, les champs obligatoires et facultatifs, les valeurs nullables, les types de contenu, les statuts de réussite et d'erreur et les schémas complets.

Les données sont émises depuis packages/api/src/index.ts, le même contrat HttpApi composé utilisé par les clients et le sidecar. Les pages décrivent le contrat extrait ; inspecter le serveur en cours d'exécution /api/openapi.json si vous vous connectez à une autre version.

Télécharger OpenAPI JSON · Suivez les demandes avec des réponses capturées

Conventions de connexion et de demande

L'API est fournie par le sidecar local plutôt que par un point de terminaison hébergé fixe. Tauri obtient son URL de bouclage et son jeton de lancement sélectionnés dynamiquement. Un sidecar démarré manuellement annonce son port dans un événement prêt pour JSON. Un client mobile couplé se connecte via sa passerelle HTTPS configurée.

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

Définissez les deux variables à partir de la connexion réelle. Les modèles de requête sur les pages de ressources utilisent délibérément des espaces réservés et des fichiers de charge utile. Les champs de transport facultatifs ne garantissent pas que chaque opération commerciale puisse les omettre : la création d'un projet, par exemple, rejette un nom manquant dans son gestionnaire.

Maintenance de référence générée

packages/web/script/generate-api-reference.mjs lit le contrat composé à l'aide de l'implémentation Effect installée du package API et écrit le JSON de référence. Le travailleur de documentation consomme le contenu généré ; il n'initialise pas le serveur d'applications pour répondre aux demandes de documentation.

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

La couverture des ressources est vérifiée par rapport à chaque opération déclarée. Un groupe nouvellement ajouté doit recevoir des métadonnées et une navigation destinées au lecteur, et une demande ou une réponse modifiée doit être régénérée. Les guides manuscrits expliquent toujours les règles d'autorisation, les effets secondaires, la configuration des services et les limites qu'un schéma HTTP ne peut à lui seul exprimer.

Recettes d'intégration

Commencez par requêtes HTTP capturées pour voir comment la création de projet, la validation métier, le rejet du porteur, les enregistrements associés et la persistance des valeurs-clés réagissent réellement. Utiliser intégration client typée pour reproduire ces opérations avec le SDK Promise ou le client Effect et gérer leurs canaux de défaillance distincts.

Ces recettes relient les contrats HTTP au comportement réel du service. Un schéma peut décrire la présence requise, le codage et une forme renvoyée ; son guide lié explique les règles d'accès, les effets de persistance, la récupération prise en charge et les limites qui ne peuvent être déduites de ces seuls types.

Opérations par groupe de ressources

Le contrat déclare actuellement 270 opérations dans 34 groupes, le tout sous un seul bearer Schéma de sécurité HTTP. La seule opération sans sécurité du porteur est l’enquête de santé publique. Le tableau est calculé à partir du document OpenAPI généré : opérations par groupe, méthodes HTTP utilisées, nombre de chemins distincts et un chemin représentatif.

Codes de statut dans tout le contrat

Compter chaque réponse déclarée une fois par opération donne cette image de ce qu'un client doit être prêt à décoder :

Chaque erreur est une erreur étiquetée Effect, donc son corps JSON contient toujours un _tag discriminateur à côté de ses champs. Il existe trois familles de corps, héritées des anciens gestionnaires afin que les clients existants continuent de fonctionner :

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

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

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

Les enveloppes de réussite reflètent l’enveloppe d’erreur : { success: true, message, data }, où data peut être null. Le EnvelopeOpt la variante omet message lorsque le gestionnaire ne l'a pas fourni. Allumer _tag plutôt que sur la présence de message ou error.

Comment une demande est traitée

1. Le routeur correspond à la méthode et au chemin. Les itinéraires inconnus n’atteignent jamais un gestionnaire.
2. Le middleware porteur compare le jeton en temps constant. Un jeton manquant ou erroné arrête la requête avec 401 avant tout décodage.
3. Le chemin, la requête, les en-têtes et le corps sont décodés par rapport aux schémas de l'opération. Les problèmes structurels deviennent 400 sans exécuter de code métier.
4. Le gestionnaire résout le compte actif, vérifie la propriété ou l'appartenance à l'organisation (403/404) et exécute le service.
5. Le résultat est codé avec le schéma de réussite déclaré, ou l'échec avec son schéma d'erreur et son statut étiquetés.

Réponses qui ne sont pas JSON

Le SDK Promise généré rejette une réponse de streaming dont le type de contenu n'est pas text/event-stream avec ClientError("UnsupportedContentType"), et un seul événement SSE supérieur à 16 Mio avec SseEventTooLarge.

Appeler l'API sans client

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" },
)

Préférez les clients générés dans TypeScript : ils connaissent le statut de réussite de chaque opération et les statuts d'erreur déclarés, et traitent tout le reste comme UnexpectedStatus au lieu de deviner.

En 3D