Riferimento API

Panoramica

Il sidecar è un unico effetto HttpApi. Ogni endpoint è tipizzato HttpApiEndpoint con corpi di richiesta e risposta controllati dallo schema, quindi questo riferimento, l'SDK generato e il server in esecuzione provengono dalla stessa dichiarazione in packages/api.

URL di base

Non esiste un'API CADCAMFUN ospitata. Il sidecar funziona sulla tua macchina, si lega 127.0.0.1 su una porta scelta dal sistema operativo (è in ascolto sulla porta 0), controlla la propria /api/healthe solo allora stampa una riga JSON su stdout. L'URL di base è http://127.0.0.1:<port> da quella linea.

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

Autenticazione

Il contratto dichiara uno schema di sicurezza, bearer (HTTP Bearer). 324 di 325 operazioni lo richiedono; soltanto GET /api/health è pubblico.

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

Convenzioni

• JSON dentro, JSON fuori. I corpi sono application/json a meno che una scheda non indichi diversamente: due caricamenti in più parti, un webhook con flusso di ottetti, un bootstrap JavaScript, un download zip, un file plugin binario e due flussi di eventi.
• Gli ID delle operazioni sono punteggiati. projects.get, vcs.commit: il tag del gruppo, un punto, il nome del metodo utilizzato dai client generati.
• Gli errori vengono digitati. Gli errori vengono dichiarati per endpoint e portano a _tag; accenderlo invece di analizzare i messaggi. Nel contratto, 401 viene dichiarato su 269 operazioni, 500 su 264 e 400 su 206.
• Gli ancoraggi operativi sono stabili. Ogni carta è collegabile come #op-<method>-<path>, per esempio /docs/api/projects#op-get-api-projects-id.

Streaming

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

Clienti

@cadcamfun/api/sdk viene generato da questo stesso contratto: ogni ID operazione seguente è un metodo tipizzato su CadCam.make(...), prendendo un input semplice di parametri del percorso e campi del corpo. Vengono generate 259 delle 325 operazioni; ogni carta mostra la sua chiamata esatta.

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

Risorse

325 operazioni in 35 gruppi, organizzate in base a ciò che servono.

Nucleo

Progetto

Produzione

Risorse

Estensioni

Conti

Documento OpenAPI

Scaricamento /docs/api/openapi.json (l'istantanea archiviata resa da questo sito) o recupera il documento live da un sidecar in esecuzione su /api/openapi.json. Rigenera lo snapshot con bun run generate:api-reference in packages/web dopo aver modificato un endpoint.

Contratto e server

@cadcamfun/api definisce gli schemi di richiesta e risposta con effetto HttpApi. Esporta la radice Api, record di dominio, errori contrassegnati e client. I gestori delle richieste, le decisioni di autorizzazione, le query del database e le chiamate ai provider vengono eseguiti nel sidecar. L'importazione di uno schema non avvia un server.

Il sidecar pubblica il suo contratto servito su GET /api/openapi.json. Utilizza quel documento in esecuzione per controllare metodi, parametri di percorso, payload e codici di stato per l'applicazione a cui sei connesso. Il server riunisce i suoi gruppi in apps/sidecar/src/layers.ts; viene assemblato il contratto condiviso packages/api/src/index.ts.

Autenticazione e identità

Richiedono percorsi protetti Authorization: Bearer <token>. Il desktop riceve un nuovo token dell'applicazione all'avvio del sidecar. GET /api/health è l'indagine sulla salute pubblica; nativo /health e /version sono protetti. I token al portatore dell'applicazione vengono confrontati con un confronto temporale.

Un facoltativo x-session-token porta una sessione di account JWT. Il token al portatore ammette l'applicazione locale; la sessione seleziona il suo account di recitazione. Una sessione assente, scaduta, non valida o orfana ricade nel profilo locale dell'installazione. I gestori delle risorse controllano quindi la proprietà o l'accesso dell'organizzazione tramite gli assistenti di autorizzazione del repository.

Un token bridge con ambito ammette solo GET /api/ai/actions e POST /api/ai/actions/invoke. Non concede l'accesso al CRUD del progetto, alle impostazioni delle credenziali o ad altri percorsi HTTP. Il suo progetto e l'ambito di lettura/scrittura vengono nuovamente controllati dall'action bridge.

Famiglie di risorse

• Progetto: progetti, disegni, componenti, versioni di disegni, importazione/esportazione di entità e analisi CAD esatta, esportazione STEP e analisi di assiemi.
• Produzione: percorsi utensile e versioni, commenti, suggerimenti sul generatore, analisi, verifica della riproduzione, lavori di produzione nativi, materiali, strumenti, configurazioni della macchina, elementi di libreria e costi di produzione.
• Assistente: provider, credenziali, modelli, sessioni, turni di streaming, controlli di sessione, azioni, memoria di progetto, contesto dell'area di lavoro e consigli stateless.
• Collaborazione: rami, commit, differenze, richieste pull, revisioni, mirror GitHub, file ed esecuzioni del flusso di lavoro, eventi live e abbinamento di compagni.
• Servizi applicativi: utenti, autenticazione, organizzazioni, notifiche, file, plug-in, fatturazione, analisi, lista d'attesa, configurazione MCP e archiviazione di valori-chiave locali.

I gruppi di contratto mantengono le forme di risposta specifiche dell'endpoint. Un client dovrebbe decodificare lo schema dell'operazione che chiama invece di presupporre una singola busta JSON a livello di applicazione.

Risposte e fallimenti

Gli errori contrassegnati più comuni vengono mappati su HTTP 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict) e 500 (InternalError). I loro schemi dichiarati hanno un carattere leggibile dall'uomo message. Alcuni gruppi utilizzano una busta con success: false, message, e errors; un piccolo numero usa an error campo.

Le risposte con esito positivo possono essere un record, una matrice, un valore nullable o una busta. Envelope include success, message, e data; EnvelopeOpt rende il messaggio facoltativo. Gli endpoint di creazione dichiarano esplicitamente 201 dove appropriato. Non dedurre il successo esclusivamente da un campo JSON senza controllare lo stato HTTP e lo schema dell'endpoint.

La decodifica dello schema convalida l'input del trasporto prima dell'esecuzione del gestore. La convalida aziendale viene ancora eseguita nel servizio: una richiesta strutturalmente valida può fare riferimento a un disegno inaccessibile, contenere un artefatto di produzione obsoleto o richiedere un'operazione di ramo in conflitto.

Utilizzare il client condiviso

ApiClient.layer ci vuole un baseUrl e applicazione token. Fornisce il trasporto di recupero e il middleware di autorizzazione del client. I suoi metodi derivano direttamente da Api, quindi questo client copre anche le operazioni omesse dalla generazione del codice.

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 di base è l'indirizzo di loopback del sidecar e la porta assegnata. Risolvilo dalla connessione desktop, anziché mantenere una porta tra i lanci. Tieni i token fuori da URL e log.

Richieste di progettazione e produzione

Utilizzo delle operazioni di progetto /api/projects; i disegni e i percorsi utensile hanno le proprie raccolte e percorsi dettagliati. POST /api/toolpaths/generate produce codice G, dati di programma analizzati, avvisi e statistiche dalle impostazioni e dalla geometria del generatore. /suggest, /parse, e /verify esporre consigli sui parametri, interpretazione del codice G e riproduzione delle scorte. Questi calcoli non creano un percorso utensile salvato.

POST /api/toolpaths/manufacture accetta un'istantanea CAD con versione e restituisce un risultato del kernel con NC, assegnazioni di strumenti, dati di taglio, reclami, problemi e un livello di rilascio. Salvare un documento risultante separatamente tramite un'operazione di creazione o aggiornamento del percorso utensile. Vedere Configurazioni per la convalida delle prove durante la persistenza.

POST /api/cad/exact/analyze, /step, e /assembly accettare elementi espliciti o un identificatore di disegno memorizzato. La lettura di un disegno memorizzato applica i normali controlli di accesso al disegno del chiamante.

Streaming e recupero

Il flusso AI trasporta eventi digitati per testo, ragionamento, chiamate e risultati di strumenti, richieste di autorizzazione e domande, tentativi, stato di turno, contesto e completamento. I client devono consumare gli eventi in modo incrementale e conservare l'identificatore di sessione. La fine di una connessione HTTP non è una prova sufficiente che un turno del modello sia terminato: lo stato della sessione può essere letto nuovamente dopo la riconnessione.

Gli schemi di eventi dell'intelligenza artificiale risiedono packages/api/src/ai-events.ts e packages/ai/src/events.ts. Gli eventi live generali utilizzano il gruppo eventi. I download binari, le risposte bootstrap del plug-in JavaScript e i corpi webhook non elaborati firmati richiedono la propria gestione del trasporto.

Elenca i percorsi utilizzati dalle pagine dei risultati page e limit parametri di interrogazione. Per le configurazioni della macchina, page il valore predefinito è 1, limit il valore predefinito è 20 ed è limitato a 1–100 e la risposta trasporta pagination con page, limit, total, e totalPages (apps/sidecar/src/http/machine-configs.ts). Controlla la pagina di riferimento di ciascun gruppo per i parametri che dichiara effettivamente.

SDK generati

@cadcamfun/httpapi-codegen riflette i gruppi HttpApi nei metadati dell'operazione e nei client generati. Il generatore API scrive un SDK Promise packages/api/src/sdk/generated ed effettuare clienti a packages/api/src/client/generated. L'SDK Promise pubblico viene esportato come @cadcamfun/api/sdk.

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

Entrambi i target generati omettono il caricamento in più parti del profilo, l'installazione in più parti del plug-in, la creazione di MCP con più schemi di successo, l'aggiornamento di MCP con identificatori in collisione, la creazione del percorso utensile del progetto con nomi di input duplicati e la fornitura di file di plug-in con intestazioni di flusso. Il target Promise omette inoltre i webhook grezzi di Stripe, il bootstrap JavaScript del plug-in, il download di file binari e le richieste di generazione/suggerimento del generatore. Queste omissioni sono esplicite in packages/api/scripts/generate-clients.ts; utilizzare il cliente contrattuale o il trasporto grezzo appropriato per tali operazioni.

Organizzazione delle fonti

groups/ contiene contratti di risorse. Da qui provengono la geometria condivisa e gli schemi CAM @cadcamfun/core; cad-exact.ts, cam-kernel.ts, e cam-program.ts descrivere ricchi risultati CAD/CAM e documenti portatili. client.ts costruisce il client del contratto, mentre lo script di generazione possiede gli obiettivi generati e gli elenchi di omissione.

Regole di integrazione

Riutilizza gli schemi di contratto ai confini del trasporto e mantieni le dipendenze del database nel sidecar. Introduci un endpoint attraverso il suo contratto, gestore, servizio o repository e una copertura HTTP mirata insieme. I file generati sono output: modifica il loro contratto o generatore e rigenerali. Una versione dello schema API, una versione del file portatile e una versione dell'API del plug-in descrivono contratti separati.

Riferimento alle risorse

325 operazioni attraverso 232 percorsi e 35 gruppi di risorse, con 56 schemi denominati. Ogni pagina di risorsa elenca le relative operazioni e mostra i parametri di percorso/query/intestazione dichiarati, campi obbligatori e facoltativi, valori nullable, tipi di contenuto, stati di successo ed errore e schemi completi.

I dati vengono emessi da packages/api/src/index.ts, lo stesso contratto HttpApi composto utilizzato dai clienti e dal sidecar. Le pagine descrivono il contratto check-out; ispezionare i server in esecuzione /api/openapi.json se ti connetti a un'altra versione.

Scarica OpenAPI JSON · Segui le richieste con le risposte acquisite

Convenzioni di connessione e richiesta

L'API viene fornita dal sidecar locale anziché da un endpoint ospitato fisso. Tauri ottiene l'URL di loopback selezionato dinamicamente e il token di avvio. Un sidecar avviato manualmente annuncia il suo port in un evento pronto per JSON. Un client mobile accoppiato si connette invece tramite il gateway HTTPS configurato.

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

Imposta entrambe le variabili dalla connessione effettiva. I modelli di richiesta nelle pagine delle risorse utilizzano deliberatamente segnaposto e file di payload. I campi di trasporto facoltativi non sono promesse che ogni operazione aziendale può omettere: la creazione del progetto, ad esempio, rifiuta un nome mancante nel suo gestore.

Manutenzione dei riferimenti generati

packages/web/script/generate-api-reference.mjs legge il contratto composto utilizzando l'implementazione Effect installata nel pacchetto API e scrive il JSON di riferimento. Il Documentation Worker consuma il contenuto generato; non inizializza il server delle applicazioni per rispondere alle richieste di documentazione.

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

La copertura delle risorse viene verificata rispetto a ogni operazione dichiarata. Un gruppo appena aggiunto deve ricevere metadati e navigazione rivolti al lettore e una richiesta o risposta modificata deve essere rigenerata. Le guide scritte a mano spiegano ancora le regole di autorizzazione, gli effetti collaterali, la configurazione del servizio e i limiti che uno schema HTTP da solo non può esprimere.

Ricette di integrazione

Inizia con richieste HTTP catturate per vedere come rispondono effettivamente la creazione del progetto, la convalida aziendale, il rifiuto della portante, i record correlati e la persistenza del valore-chiave. Utilizzo integrazione client digitato per riprodurre tali operazioni con il client Promise SDK o Effect e gestire i relativi canali di errore distinti.

Queste ricette collegano i contratti HTTP al comportamento del servizio reale. Uno schema può descrivere la presenza richiesta, la codifica e una forma restituita; la sua guida collegata spiega le regole di accesso, gli effetti di persistenza, il ripristino supportato e i limiti che non possono essere dedotti solo da questi tipi.

Operazioni per gruppo di risorse

Il contratto attualmente dichiara 270 operazioni in 34 gruppi, tutti sotto un unico bearer Schema di sicurezza HTTP. L’unica operazione senza sicurezza del portatore è l’indagine sulla salute pubblica. La tabella viene calcolata dal documento OpenAPI generato: operazioni per gruppo, metodi HTTP utilizzati, quanti percorsi distinti e un percorso rappresentativo.

Codici di stato nel contratto

Contare ciascuna risposta dichiarata una volta per operazione fornisce questa immagine di ciò che un client deve essere pronto a decodificare:

Ogni errore è un errore con tag Effect, quindi il suo corpo JSON contiene sempre un file _tag discriminatore accanto ai suoi campi. Esistono tre famiglie di corpi, ereditate dai gestori legacy in modo che i client esistenti continuino a funzionare:

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

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

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

Le buste di successo rispecchiano la busta di errore: { success: true, message, data }, dove data forse null. IL EnvelopeOpt la variante omette message quando il conduttore non ne ha fornito uno. Accendi _tag piuttosto che sulla presenza di message o error.

Come viene elaborata una richiesta

1. Il router corrisponde al metodo e al percorso. I percorsi sconosciuti non raggiungono mai un handler.
2. Il middleware al portatore confronta il token in tempo costante. Un token mancante o errato interrompe la richiesta con 401 prima di qualsiasi decodifica.
3. Percorso, query, intestazioni e corpo vengono decodificati rispetto agli schemi dell'operazione. I problemi strutturali diventano 400 senza eseguire il codice aziendale.
4. Il gestore risolve l'account attivo, controlla la proprietà o l'appartenenza all'organizzazione (403/404) ed esegue il servizio.
5. Il risultato è codificato con lo schema di successo dichiarato o l'errore con lo schema e lo stato di errore contrassegnati.

Risposte che non sono JSON

L'SDK Promise generato rifiuta una risposta di streaming il cui tipo di contenuto non lo è text/event-stream con ClientError("UnsupportedContentType")e un singolo evento SSE più grande di 16 MiB con SseEventTooLarge.

Chiamata all'API senza 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" },
)

Preferiscono i client generati in TypeScript: conoscono lo stato di successo di ogni operazione e gli stati di errore dichiarati e trattano qualsiasi altra cosa come UnexpectedStatus invece di indovinare.

Nel 3D