Referência da API

Visão geral

O sidecar é um efeito único HttpApi. Cada endpoint é digitado HttpApiEndpoint com corpos de solicitação e resposta verificados pelo esquema, portanto, esta referência, o SDK gerado e o servidor em execução vêm da mesma declaração em packages/api.

URL base

Não há API CADCAMFUN hospedada. O sidecar roda em sua máquina, liga 127.0.0.1 em uma porta escolhida pelo sistema operacional (ele escuta na porta 0), verifica sua própria porta /api/healthe só então imprime uma linha JSON no stdout. O URL base é http://127.0.0.1:<port> dessa linha.

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

Autenticação

O contrato declara um esquema de segurança, bearer (HTTP Bearer). 324 de 325 operações exigem isso; apenas GET /api/health é público.

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

Convenções

• Entrada JSON, saída JSON. Os corpos são application/json a menos que um cartão diga o contrário: dois uploads multiparte, um webhook de fluxo de octeto, um bootstrap JavaScript, um download zip, um arquivo de plug-in binário e dois fluxos de eventos.
• Os IDs de operação estão pontilhados. projects.get, vcs.commit: a tag do grupo, um ponto, o nome do método usado pelos clientes gerados.
• Erros são digitados. As falhas são declaradas por endpoint e carregam um _tag; ligue-o em vez de analisar mensagens. Em todo o contrato, 401 é declarado em 269 operações, 500 em 264 e 400 em 206.
• As âncoras de operação estão estáveis. Cada cartão pode ser vinculado como #op-<method>-<path>, por exemplo /docs/api/projects#op-get-api-projects-id.

Transmissão

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

Clientes

@cadcamfun/api/sdk é gerado a partir deste mesmo contrato: cada ID de operação abaixo é um método digitado em CadCam.make(...), recebendo uma entrada simples de parâmetros de caminho e campos de corpo. 259 das 325 operações são geradas; cada cartão mostra sua chamada exata.

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 operações em 35 grupos, organizadas de acordo com o que servem.

Essencial

Projeto

Fabricação

Recursos

Extensões

Contas

Documento OpenAPI

Download /docs/api/openapi.json (o instantâneo com check-in que este site renderiza) ou busque o documento ativo de um sidecar em execução em /api/openapi.json. Gere novamente o instantâneo com bun run generate:api-reference em packages/web depois de alterar um endpoint.

Contrato e servidor

@cadcamfun/api define esquemas de solicitação e resposta com Effect HttpApi. Ele exporta a raiz Api, registros de domínio, erros de tags e clientes. Manipuladores de solicitações, decisões de autorização, consultas de banco de dados e chamadas de provedor são executadas no sidecar. A importação de um esquema não inicia um servidor.

O sidecar publica seu contrato servido em GET /api/openapi.json. Use esse documento em execução para inspecionar métodos, parâmetros de caminho, cargas úteis e códigos de status do aplicativo ao qual você está conectado. O servidor monta seus grupos em apps/sidecar/src/layers.ts; o contrato compartilhado é montado em packages/api/src/index.ts.

Autenticação e identidade

Rotas protegidas exigem Authorization: Bearer <token>. A área de trabalho recebe um novo token de aplicativo quando seu sidecar é iniciado. GET /api/health é a investigação de saúde pública; nativo /health e /version estão protegidos. Os tokens portadores do aplicativo são comparados com uma comparação segura de tempo.

Um opcional x-session-token carrega um JWT de sessão de conta. O token ao portador admite a aplicação local; a sessão seleciona sua conta atuante. Uma sessão ausente, expirada, inválida ou órfã retorna ao perfil local da instalação. Os manipuladores de recursos verificam a propriedade ou o acesso da organização por meio de auxiliares de autorização de repositório.

Um token de ponte com escopo admite apenas GET /api/ai/actions e POST /api/ai/actions/invoke. Ele não concede acesso ao CRUD do projeto, configurações de credenciais ou outras rotas HTTP. Seu projeto e escopo de leitura/gravação são verificados novamente pela ponte de ação.

Famílias de recursos

• Projeto: projetos, desenhos, componentes, versões de desenhos, importação/exportação de entidades e análise CAD exata, exportação STEP e análise de montagem.
• Fabricação: percursos da ferramentas e versões, comentários, sugestões de geradores, análise, verificação de repetição, trabalhos de fabricação nativa, materiais, ferramentas, configurações de máquinas, itens de biblioteca e custos de produção.
• Assistente: provedores, credenciais, modelos, sessões, turnos de streaming, controles de sessão, ações, memória do projeto, contexto do espaço de trabalho e aconselhamento sem estado.
• Colaboração: ramificações, confirmações, diferenças, solicitações pull, revisões, espelhos GitHub, arquivos e execuções de fluxo de trabalho, eventos ao vivo e emparelhamento complementar.
• Serviços de aplicativos: usuários, autenticação, organizações, notificações, arquivos, plug-ins, faturamento, análises, lista de espera, configuração de MCP e armazenamento local de valores-chave.

Os grupos de contratos mantêm seus formatos de resposta específicos de endpoint. Um cliente deve decodificar o esquema da operação que ele chama em vez de assumir um único envelope JSON para todo o aplicativo.

Respostas e falhas

Erros comuns de tags são mapeados para HTTP 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict) e 500 (InternalError). Seus esquemas declarados carregam um formato legível por humanos message. Alguns grupos usam um envelope com success: false, message, e errors; um pequeno número usa um error campo.

As respostas bem-sucedidas podem ser um registro, uma matriz, um valor anulável ou um envelope. Envelope inclui success, message, e data; EnvelopeOpt torna a mensagem opcional. Os pontos de extremidade de criação declaram explicitamente 201 quando apropriado. Não infira o sucesso apenas de um campo JSON sem verificar o status HTTP e o esquema do endpoint.

A decodificação do esquema valida a entrada do transporte antes da execução do manipulador. A validação de negócios ainda é executada no serviço: uma solicitação estruturalmente válida pode referir-se a um desenho inacessível, conter um artefato de fabricação obsoleto ou solicitar uma operação de filial conflitante.

Use o cliente compartilhado

ApiClient.layer leva um baseUrl e aplicação token. Ele fornece o transporte de busca e o middleware de autorização do cliente. Seus métodos são derivados diretamente de Api, portanto, este cliente também cobre operações omitidas pela geração 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 })))

O URL base é o endereço de loopback do sidecar e a porta atribuída. Resolva-o a partir da conexão da área de trabalho, em vez de persistir uma porta entre inicializações. Mantenha os tokens fora de URLs e logs.

Solicitações de design e fabricação

Uso de operações do projeto /api/projects; desenhos e percursos da ferramenta têm suas próprias coleções e rotas detalhadas. POST /api/toolpaths/generate produz código G, dados de programa analisados, avisos e estatísticas de configurações e geometria do gerador. /suggest, /parse, e /verify expor conselhos de parâmetros, interpretação de código G e reprodução de estoque. Esses cálculos não criam um percurso salvo.

POST /api/toolpaths/manufacture aceita um instantâneo CAD versionado e retorna um resultado do kernel com NC, atribuições de ferramentas, dados de corte, reclamações, problemas e um nível de liberação. Salve um documento resultante separadamente através de uma operação de criação ou atualização de percurso. Ver Configurações para validação de evidências durante a persistência.

POST /api/cad/exact/analyze, /step, e /assembly aceitar elementos explícitos ou um identificador de desenho armazenado. A leitura de um desenho armazenado aplica as verificações normais de acesso ao desenho do chamador.

Streaming e recuperação

O fluxo de IA transporta eventos digitados para texto, raciocínio, chamadas e resultados de ferramentas, solicitações de permissão e perguntas, novas tentativas, estado de turno, contexto e conclusão. Os clientes devem consumir eventos de forma incremental e reter o identificador de sessão. O término de uma conexão HTTP não é evidência suficiente de que a virada do modelo foi concluída: o estado da sessão pode ser lido novamente após a reconexão.

Esquemas de eventos de IA residem em packages/api/src/ai-events.ts e packages/ai/src/events.ts. Eventos gerais ao vivo usam o grupo de eventos. Downloads binários, respostas de inicialização de plug-ins JavaScript e corpos de webhook brutos assinados exigem seu próprio manuseio de transporte.

Liste as rotas que a página usa para seus resultados page e limit parâmetros de consulta. Para configurações de máquina, page o padrão é 1, limit o padrão é 20 e é fixado em 1–100, e a resposta carrega pagination com page, limit, total, e totalPages (apps/sidecar/src/http/machine-configs.ts). Verifique na página de referência de cada grupo os parâmetros que ele realmente declara.

SDKs gerados

@cadcamfun/httpapi-codegen reflete grupos HttpApi em metadados de operação e clientes gerados. O gerador de API grava um Promise SDK em packages/api/src/sdk/generated e efetuar clientes para packages/api/src/client/generated. O Promise SDK público é exportado como @cadcamfun/api/sdk.

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

Ambos os destinos gerados omitem upload multiparte de perfil, instalação multiparte de plug-in, criação de MCP com vários esquemas de sucesso, atualização de MCP com identificadores de colisão, criação de caminho de ferramenta do projeto com nomes de entrada duplicados e serviço de arquivo de plug-in com cabeçalhos de fluxo. O destino Promise também omite webhooks brutos do Stripe, inicialização do plug-in JavaScript, download de arquivo binário e solicitações de geração/sugestão do gerador. Essas omissões são explícitas em packages/api/scripts/generate-clients.ts; utilizar o cliente contratado ou o transporte bruto adequado para essas operações.

Organização de origem

groups/ contém contratos de recursos. A geometria compartilhada e os esquemas CAM vêm de @cadcamfun/core; cad-exact.ts, cam-kernel.ts, e cam-program.ts descrever resultados avançados de CAD/CAM e documentos portáteis. client.ts constrói o cliente do contrato, enquanto o script de geração possui metas geradas e listas de omissões.

Regras de integração

Reutilize esquemas de contrato nos limites de transporte e mantenha as dependências do banco de dados no sidecar. Introduza um endpoint por meio de seu contrato, manipulador, serviço ou repositório e cobertura HTTP focada em conjunto. Os arquivos gerados são saídas: edite seu contrato ou gerador e gere-os novamente. Uma versão do esquema da API, uma versão do arquivo portátil e uma versão da API do plugin descrevem contratos separados.

Referência de recurso

325 operações entre 232 caminhos e 35 grupos de recursos, com 56 esquemas nomeados. Cada página de recurso lista suas operações e mostra parâmetros de caminho/consulta/cabeçalho declarados, campos obrigatórios e opcionais, valores anuláveis, tipos de conteúdo, status de sucesso e erro e esquemas completos.

Os dados são emitidos de packages/api/src/index.ts, o mesmo contrato HttpApi composto usado pelos clientes e sidecar. As páginas descrevem o contrato verificado; inspecionar o servidor em execução /api/openapi.json se você se conectar a outra versão.

Baixar OpenAPI JSON · Siga solicitações com respostas capturadas

Convenções de conexão e solicitação

A API é fornecida pelo sidecar local em vez de um endpoint hospedado fixo. Tauri obtém seu URL de loopback selecionado dinamicamente e token de inicialização. Um sidecar iniciado manualmente anuncia sua porta em um evento pronto para JSON. Em vez disso, um cliente móvel emparelhado se conecta por meio do gateway HTTPS configurado.

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

Defina ambas as variáveis da conexão real. Os modelos de solicitação nas páginas de recursos usam deliberadamente espaços reservados e arquivos de carga útil. Os campos de transporte opcionais não são promessas de que toda operação de negócios possa omiti-los: a criação do projeto, por exemplo, rejeita um nome ausente em seu manipulador.

Manutenção de referência gerada

packages/web/script/generate-api-reference.mjs lê o contrato composto usando a implementação de efeito instalada do pacote de API e grava o JSON de referência. O Worker de documentação consome o conteúdo gerado; ele não inicializa o servidor de aplicativos para responder às solicitações de documentação.

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

A cobertura de recursos é verificada em relação a cada operação declarada. Um grupo recém-adicionado deve receber metadados e navegação voltados para o leitor, e uma solicitação ou resposta alterada deve ser regenerada. Guias manuscritos ainda explicam regras de autorização, efeitos colaterais, configuração de serviço e limites que um esquema HTTP sozinho não consegue expressar.

Receitas de integração

Comece com solicitações HTTP capturadas para ver como a criação do projeto, a validação do negócio, a rejeição do portador, os registros relacionados e a persistência do valor-chave realmente respondem. Usar integração de cliente digitado para reproduzir essas operações com o Promise SDK ou o cliente Effect e lidar com seus canais de falha distintos.

Essas receitas conectam contratos HTTP ao comportamento real do serviço. Um esquema pode descrever a presença necessária, a codificação e uma forma retornada; seu guia vinculado explica regras de acesso, efeitos de persistência, recuperação suportada e limites que não podem ser inferidos apenas desses tipos.

Operações por grupo de recursos

O contrato atualmente declara 270 operações em 34 grupos, todos sob um único bearer Esquema de segurança HTTP. A única operação sem segurança ao portador é a investigação de saúde pública. A tabela é calculada a partir do documento OpenAPI gerado: operações por grupo, os métodos HTTP usados, quantos caminhos distintos e um caminho representativo.

Códigos de status em todo o contrato

Contar cada resposta declarada uma vez por operação fornece esta imagem do que um cliente deve estar pronto para decodificar:

Cada erro é um erro marcado com Effect, portanto, seu corpo JSON sempre contém um _tag discriminador próximo aos seus campos. Existem três famílias de corpos, herdadas dos manipuladores legados para que os clientes existentes continuem trabalhando:

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

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

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

Os envelopes de sucesso refletem o envelope de erro: { success: true, message, data }, onde data talvez null. O EnvelopeOpt variante omite message quando o manipulador não forneceu um. Ligar _tag e não na presença de message ou error.

Como uma solicitação é processada

1. O roteador corresponde ao método e ao caminho. Rotas desconhecidas nunca alcançam um manipulador.
2. O middleware bearer compara o token em tempo constante. Um token ausente ou errado interrompe a solicitação com 401 antes de qualquer decodificação.
3. Caminho, consulta, cabeçalhos e corpo são decodificados em relação aos esquemas da operação. Os problemas estruturais tornam-se 400 sem a execução do código comercial.
4. O gerenciador resolve a conta atuante, verifica a propriedade ou a associação à organização (403/404) e executa o serviço.
5. O resultado é codificado com o esquema de sucesso declarado ou a falha com seu esquema e status de erro marcado.

Respostas que não são JSON

O Promise SDK gerado rejeita uma resposta de streaming cujo tipo de conteúdo não é text/event-stream com ClientError("UnsupportedContentType")e um único evento SSE maior que 16 MiB com SseEventTooLarge.

Chamando a API sem 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" },
)

Prefira os clientes gerados em TypeScript: eles conhecem o status de sucesso de cada operação e os status de erro declarados, e tratam qualquer resto como UnexpectedStatus em vez de adivinhar.

Em 3D