Referencia API

Descripción general

El sidecar es un solo efecto. HttpApi. Cada punto final es un tipo HttpApiEndpoint con cuerpos de solicitud y respuesta verificados por esquema, por lo que esta referencia, el SDK generado y el servidor en ejecución provienen de la misma declaración en packages/api.

URL base

No hay una API CADCAMFUN alojada. El sidecar corre en su máquina, se une 127.0.0.1 en un puerto que el sistema operativo elige (escucha en el puerto 0), verifica su propio /api/health, y solo entonces imprime una línea JSON en stdout. La URL base es http://127.0.0.1:<port> de esa línea.

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

Autenticación

El contrato declara un esquema de seguridad, bearer (HTTP Bearer). 324 de 325 operaciones lo requieren; solo GET /api/health es público.

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

Convenciones

• JSON entra, JSON sale. Los cuerpos son application/json a menos que una tarjeta indique lo contrario: dos cargas de varias partes, un webhook de secuencia de octetos, un arranque de JavaScript, una descarga zip, un archivo de complemento binario y dos secuencias de eventos.
• Los identificadores de operación están punteados. projects.get, vcs.commit: la etiqueta de grupo, un punto, el nombre del método utilizado por los clientes generados.
• Los errores se escriben. Las fallas se declaran por punto final y llevan un _tag; actívelo en lugar de analizar mensajes. En todo el contrato, 401 se declara en 269 operaciones, 500 en 264 y 400 en 206.
• Los anclajes de operación son estables. Cada tarjeta se puede vincular como #op-<method>-<path>, por ejemplo /docs/api/projects#op-get-api-projects-id.

Transmisión

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

Clientela

@cadcamfun/api/sdk se genera a partir de este mismo contrato: cada identificación de operación a continuación es un método escrito en CadCam.make(...), tomando una entrada plana de parámetros de ruta y campos de cuerpo. Se generan 259 de las 325 operaciones; cada tarjeta muestra su llamada exacta.

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

Recursos

325 operaciones en 35 grupos, organizadas según lo que sirven.

Centro

Diseño

Fabricación

Recursos

Extensiones

Cuentas

Documento OpenAPI

Descargar /docs/api/openapi.json (la instantánea registrada que muestra este sitio) o buscar el documento en vivo desde un sidecar en ejecución en /api/openapi.json. Regenerar la instantánea con bun run generate:api-reference en packages/web después de cambiar un punto final.

Contrato y servidor

@cadcamfun/api define esquemas de solicitud y respuesta con Effect HttpApi. Exporta la raíz. Api, registros de dominio, errores etiquetados y clientes. Los controladores de solicitudes, las decisiones de autorización, las consultas de bases de datos y las llamadas a proveedores se ejecutan en el sidecar. La importación de un esquema no inicia un servidor.

El sidecar publica su contrato cumplido en GET /api/openapi.json. Utilice ese documento en ejecución para inspeccionar métodos, parámetros de ruta, cargas útiles y códigos de estado de la aplicación a la que está conectado. El servidor reúne sus grupos en apps/sidecar/src/layers.ts; el contrato compartido se ensambla en packages/api/src/index.ts.

Autenticación e identidad

Las rutas protegidas requieren Authorization: Bearer <token>. El escritorio recibe un nuevo token de aplicación cuando se inicia su sidecar. GET /api/health es la investigación de salud pública; nativo /health y /version están protegidos. Los tokens portadores de aplicaciones se comparan con una comparación de tiempo seguro.

Un opcional x-session-token lleva una cuenta de sesión JWT. El token al portador admite la aplicación local; la sesión selecciona su cuenta de actuación. Una sesión ausente, caducada, no válida o huérfana recurre al perfil local de la instalación. Luego, los manejadores de recursos verifican la propiedad o el acceso a la organización a través de ayudantes de autorización del repositorio.

Un token de puente con alcance solo admite GET /api/ai/actions y POST /api/ai/actions/invoke. No otorga acceso al proyecto CRUD, configuración de credenciales u otras rutas HTTP. El puente de acción vuelve a comprobar su proyecto y su alcance de lectura/escritura.

Familias de recursos

• Diseño: proyectos, dibujos, componentes, versiones de dibujos, importación/exportación de entidades y análisis CAD exacto, exportación STEP y análisis de ensamblaje.
• Fabricación: trayectorias y versiones de herramientas, comentarios, sugerencias de generadores, análisis, verificación de reproducciones, trabajos de fabricación nativos, materiales, herramientas, configuraciones de máquinas, elementos de biblioteca y costos de producción.
• Asistente: proveedores, credenciales, modelos, sesiones, turnos de transmisión, controles de sesión, acciones, memoria del proyecto, contexto del espacio de trabajo y consejos sin estado.
• Colaboración: ramas, confirmaciones, diferencias, solicitudes de extracción, revisiones, réplicas de GitHub, archivos y ejecuciones de flujo de trabajo, eventos en vivo y emparejamiento complementario.
• Servicios de aplicación: usuarios, autenticación, organizaciones, notificaciones, archivos, complementos, facturación, análisis, lista de espera, configuración de MCP y almacenamiento local de valores-clave.

Los grupos de contratos conservan sus formas de respuesta específicas de los terminales. Un cliente debe decodificar el esquema de la operación que llama en lugar de asumir un único sobre JSON para toda la aplicación.

Respuestas y fracasos

Los errores etiquetados comunes se asignan a HTTP 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict), y 500 (InternalError). Sus esquemas declarados llevan un formato legible por humanos. message. Algunos grupos usan un sobre con success: false, message, y errors; un pequeño número utiliza un error campo.

Las respuestas exitosas pueden ser un registro, una matriz, un valor que acepta valores NULL o un sobre. Envelope incluye success, message, y data; EnvelopeOpt hace que el mensaje sea opcional. Los puntos finales de creación declaran explícitamente 201 cuando corresponda. No infiera el éxito únicamente a partir de un campo JSON sin verificar el estado HTTP y el esquema del punto final.

La decodificación del esquema valida la entrada del transporte antes de que se ejecute el controlador. La validación comercial aún se ejecuta en el servicio: una solicitud estructuralmente válida puede hacer referencia a un dibujo inaccesible, contener un artefacto de fabricación obsoleto o solicitar una operación de sucursal conflictiva.

Utilice el cliente compartido

ApiClient.layer toma un baseUrl y aplicación token. Proporciona el transporte de recuperación y el middleware de autorización del cliente. Sus métodos se derivan directamente de Api, por lo que este cliente también cubre operaciones omitidas por la generación de código.

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

La URL base es la dirección de loopback del sidecar y el puerto asignado. Resuélvalo desde la conexión de escritorio, en lugar de conservar un puerto entre los lanzamientos. Mantenga los tokens fuera de las URL y los registros.

Solicitudes de diseño y fabricación.

Uso de operaciones del proyecto /api/projects; los dibujos y las trayectorias de herramientas tienen sus propias colecciones y rutas detalladas. POST /api/toolpaths/generate produce código G, datos de programas analizados, advertencias y estadísticas a partir de la configuración y la geometría del generador. /suggest, /parse, y /verify exponer consejos sobre parámetros, interpretación de códigos G y reproducción de acciones. Estos cálculos no crean una trayectoria guardada.

POST /api/toolpaths/manufacture acepta una instantánea CAD versionada y devuelve un resultado del núcleo con NC, asignaciones de herramientas, datos de corte, reclamaciones, problemas y un nivel de versión. Guarde un documento resultante por separado mediante una operación de creación o actualización de trayectoria. Ver Configuraciones para la validación de evidencia durante la persistencia.

POST /api/cad/exact/analyze, /step, y /assembly aceptar elementos explícitos o un identificador de dibujo almacenado. La lectura de un dibujo almacenado aplica las comprobaciones normales de acceso al dibujo de la persona que llama.

Transmisión y recuperación

El flujo de IA transporta eventos escritos para texto, razonamiento, llamadas y resultados de herramientas, solicitudes de permiso y preguntas, reintentos, estado de turno, contexto y finalización. Los clientes deben consumir eventos de forma incremental y conservar el identificador de sesión. El final de una conexión HTTP no es evidencia suficiente de que finalizó un turno de modelo: el estado de la sesión se puede leer nuevamente después de volver a conectarse.

Los esquemas de eventos de IA viven en packages/api/src/ai-events.ts y packages/ai/src/events.ts. Los eventos generales en vivo utilizan el grupo de eventos. Las descargas binarias, las respuestas de arranque del complemento JavaScript y los cuerpos de webhooks sin formato firmados requieren su propio manejo de transporte.

Enumerar las rutas que utilizan sus resultados page y limit parámetros de consulta. Para configuraciones de máquinas, page por defecto es 1, limit el valor predeterminado es 20 y está fijado en 1–100, y la respuesta lleva pagination con page, limit, total, y totalPages (apps/sidecar/src/http/machine-configs.ts). Consulte la página de referencia de cada grupo para conocer los parámetros que realmente declara.

SDK generados

@cadcamfun/httpapi-codegen refleja los grupos HttpApi en metadatos de operación y clientes generados. El generador de API escribe un SDK de promesa para packages/api/src/sdk/generated y lograr que los clientes packages/api/src/client/generated. El SDK público de Promise se exporta como @cadcamfun/api/sdk.

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

Ambos objetivos generados omiten la carga de perfiles de varias partes, la instalación de complementos de varias partes, la creación de MCP con múltiples esquemas de éxito, la actualización de MCP con identificadores en colisión, la creación de trayectorias de herramientas del proyecto con nombres de entrada duplicados y el envío de archivos de complementos con encabezados de secuencia. El objetivo de Promise también omite los webhooks sin formato de Stripe, el arranque de JavaScript del complemento, la descarga de archivos binarios y las solicitudes de generación/sugerencia del generador. Estas omisiones son explícitas en packages/api/scripts/generate-clients.ts; utilizar el cliente contratado o el transporte bruto adecuado para dichas operaciones.

Organización fuente

groups/ contiene contratos de recursos. La geometría compartida y los esquemas CAM provienen de @cadcamfun/core; cad-exact.ts, cam-kernel.ts, y cam-program.ts describir resultados CAD/CAM enriquecidos y documentos portátiles. client.ts construye el cliente de contrato, mientras que el script de generación posee los objetivos generados y las listas de omisiones.

Reglas de integración

Reutilice esquemas de contratos en los límites de transporte y mantenga las dependencias de la base de datos en el sidecar. Introduzca un punto final a través de su contrato, controlador, servicio o repositorio y cobertura HTTP enfocada en conjunto. Los archivos generados son salidas: edite su contrato o generador y regenerelos. Una versión de esquema de API, una versión de archivo portátil y una versión de API de complemento describen contratos separados.

Referencia de recursos

325 operaciones al otro lado de 232 rutas y 35 grupos de recursos, con 56 esquemas con nombre. Cada página de recursos enumera sus operaciones y muestra los parámetros de ruta/consulta/encabezado declarados, campos obligatorios y opcionales, valores que aceptan valores NULL, tipos de contenido, estados de éxito y error, y esquemas completos.

Los datos se emiten desde packages/api/src/index.ts, el mismo contrato HttpApi compuesto utilizado por los clientes y el sidecar. Las páginas describen el contrato prestado; inspeccionar el servidor en ejecución /api/openapi.json si te conectas a otra versión.

Descargar OpenAPI JSON · Siga las solicitudes con respuestas capturadas

Convenciones de conexión y solicitud

La API la proporciona el sidecar local en lugar de un punto final alojado fijo. Tauri obtiene su URL de loopback seleccionada dinámicamente y su token de lanzamiento. Un sidecar iniciado manualmente anuncia su puerto en un evento listo para JSON. En su lugar, un cliente móvil emparejado se conecta a través de su puerta de enlace HTTPS configurada.

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

Establezca ambas variables desde la conexión real. Las plantillas de solicitud en páginas de recursos utilizan deliberadamente marcadores de posición y archivos de carga útil. Los campos de transporte opcionales no son promesas de que todas las operaciones comerciales puedan omitirlos: la creación de un proyecto, por ejemplo, rechaza un nombre que falta en su controlador.

Mantenimiento de referencia generado

packages/web/script/generate-api-reference.mjs lee el contrato compuesto utilizando la implementación Effect instalada del paquete API y escribe el JSON de referencia. El trabajador de documentación consume el contenido generado; no inicializa el servidor de aplicaciones para responder solicitudes de documentación.

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

La cobertura de recursos se compara con cada operación declarada. Un grupo recién agregado debe recibir metadatos y navegación de cara al lector, y se debe volver a generar una solicitud o respuesta modificada. Las guías escritas a mano todavía explican las reglas de autorización, los efectos secundarios, la configuración del servicio y los límites que un esquema HTTP por sí solo no puede expresar.

Recetas de integración

Empezar con solicitudes HTTP capturadas para ver cómo responden realmente la creación de proyectos, la validación empresarial, el rechazo del portador, los registros relacionados y la persistencia del valor clave. Usar integración de cliente mecanografiada para reproducir esas operaciones con Promise SDK o el cliente Effect y manejar sus distintos canales de falla.

Estas recetas conectan los contratos HTTP con el comportamiento real del servicio. Un esquema puede describir la presencia requerida, la codificación y una forma devuelta; su guía vinculada explica las reglas de acceso, los efectos de persistencia, la recuperación admitida y los límites que no se pueden inferir únicamente de esos tipos.

Operaciones por grupo de recursos

El contrato actualmente declara 270 operaciones en 34 grupos, todos bajo un mismo bearer Esquema de seguridad HTTP. La única operación sin seguridad al portador es la investigación de salud pública. La tabla se calcula a partir del documento OpenAPI generado: operaciones por grupo, los métodos HTTP utilizados, cuántas rutas distintas y una ruta representativa.

Códigos de estado en todo el contrato

Contar cada respuesta declarada una vez por operación da esta imagen de lo que un cliente debe estar listo para decodificar:

Cada error es un error etiquetado como Efecto, por lo que su cuerpo JSON siempre contiene un _tag discriminador junto a sus campos. Hay tres familias de cuerpos, heredados de los controladores heredados para que los clientes existentes sigan trabajando:

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

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

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

Los sobres de éxito reflejan el sobre de error: { success: true, message, data }, dónde data tal vez null. El EnvelopeOpt variante omite message cuando el responsable no la haya facilitado. Encender _tag en lugar de en la presencia de message o error.

Cómo se procesa una solicitud

1. El enrutador coincide con el método y la ruta. Las rutas desconocidas nunca llegan a un controlador.
2. El middleware portador compara el token en tiempo constante. Un token faltante o incorrecto detiene la solicitud con 401 antes de cualquier decodificación.
3. La ruta, la consulta, los encabezados y el cuerpo se decodifican según los esquemas de la operación. Los problemas estructurales se vuelven 400 sin ejecutar código comercial.
4. El controlador resuelve la cuenta actual, verifica la propiedad o la membresía de la organización (403/404) y ejecuta el servicio.
5. El resultado se codifica con el esquema de éxito declarado, o el fracaso con su esquema de error etiquetado y su estado.

Respuestas que no son JSON

El SDK de Promise generado rechaza una respuesta de transmisión cuyo tipo de contenido no sea text/event-stream con ClientError("UnsupportedContentType")y un único evento SSE mayor que 16 MiB con SseEventTooLarge.

Llamar a la API sin un cliente

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

Prefiere los clientes generados en TypeScript: conocen el estado de éxito de cada operación y los estados de error declarados, y tratan cualquier otra cosa como UnexpectedStatus en lugar de adivinar.

En 3D