Cliente

O cliente é o objeto que createClient() retorna: um NodaroClient que guarda a URL base, o provedor de autenticação e as configurações, e expõe cada parte da API do Nodaro como um recurso, como client.workflows ou client.nodes. Você o cria uma vez e o reutiliza em todas as chamadas.

Criar um cliente

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
  timeoutMs: 120_000,
})

createClient(options: ClientOptions): NodaroClient

NodaroClient também é exportado como classe, então você pode tipar uma função que recebe um cliente:

import type { NodaroClient } from "@nodaro/sdk"

async function countWorkflows(client: NodaroClient, projectId: string) {
  const { data } = await client.workflows.list({ projectId })
  return data.length
}

Recursos do cliente

Cada recurso é criado por createClient e acessado como client.<resource>.

O próprio cliente tem mais três métodos: me(), withWorkspace() e request().

O que os métodos retornam

• Os envelopes são mantidos. Quando um endpoint responde { "data": ... }, o método resolve com esse envelope, então você escreve const { data } = await client.workflows.get(id). As listas paginadas acrescentam um cursor ao lado de data, como nextCursor.
• Alguns recursos retornam o payload. Alguns métodos desembrulham a resposta: por exemplo, client.characters.list() resolve com { characters, nextCursor }, e client.credits.balance(), com o próprio saldo. Cada página de referência mostra o tipo de retorno exato.
• Exclusões e cancelamentos em geral resolvem com { success: true }.
• Os nomes dos campos seguem o formato da API. Um Job usa campos em snake_case, como output_data e created_at, porque a API os envia assim. Um Workflow e um WorkflowExecution usam camelCase.

Todos os tipos de resposta e de entrada são exportados, então você pode importá-los com import type. Veja Tipos.

me()

me(): Promise<UserIdentity & MeOrganizations>

Retorna a identidade por trás do token atual (GET /v1/me). Qualquer token válido leva ao dono dele, seja um token de API, um token de acesso OAuth ou uma sessão do navegador. Um token ausente ou inválido lança UnauthorizedError.

const me = await client.me()
console.log(me.email, me.tier)

Em uma instância do Nodaro Cloud com organizações, o resultado também traz organizations, workspaces, lastWorkspaceId e organizationsUnavailable. Trate os três estados deles de formas diferentes:

withWorkspace(workspaceId)

withWorkspace(workspaceId: string | null): NodaroClient

Retorna um novo cliente que age em workspaceId. O novo cliente compartilha a autenticação, a URL base, o tempo limite e o fetch do original. Passe null para usar o seu espaço pessoal.

const classroom = client.withWorkspace(workspaceId)

await classroom.workflows.run(workflowId) // runs in the workspace
await client.workflows.run(workflowId)    // runs in the personal space

O método retorna um novo cliente em vez de alterar o atual. Por isso, duas operações executadas ao mesmo tempo em um mesmo cliente nunca misturam os espaços de trabalho.

O espaço de trabalho define o escopo, nunca o acesso. Ele escolhe de qual espaço de trabalho uma lista lê e onde um novo item é criado. Ler, alterar, excluir ou executar um item que você indica pelo ID depende do espaço de trabalho do próprio item. Esquecer o espaço de trabalho não esconde o seu trabalho, e um espaço de trabalho errado não alcança o trabalho de outras pessoas.

Os espaços de trabalho pertencem às organizações no Nodaro Cloud. Veja Organizações e espaços de trabalho e Espaços de trabalho.

request(method, path, options)

request<T>(method: string, path: string, options?: {
  body?: unknown
  query?: Record<string, string | number | boolean | undefined>
  headers?: Record<string, string>
  signal?: AbortSignal
}): Promise<T>

Envia uma requisição a qualquer endpoint, para os poucos que ainda não têm método de recurso. Adiciona o seu cabeçalho de autenticação e o seu espaço de trabalho, envia body como JSON, aplica timeoutMs e lança os mesmos erros tipados que os métodos de recurso.

// The same request that client.jobs.list() sends
const page = await client.request<{ data: unknown[]; next: string | null }>("GET", "/v1/jobs", {
  query: { type: "llm-structured", limit: 20 },
})

Um corpo FormData é enviado como upload multipart. Os valores de query que são undefined ficam de fora. A referência da API REST lista todos os endpoints e os campos deles.

Tempos limite e um fetch personalizado

timeoutMs aborta uma requisição que demora mais que o limite, de 60 segundos por padrão. A maioria das gerações demora mais que qualquer tempo limite HTTP razoável, então, em vez disso, inicie a geração e consulte o job periodicamente: client.nodes.runAndWait() faz as duas coisas por você. Os métodos de streaming, client.copilot.stream() e client.media.downloadVideoProgress(), não aplicam o tempo limite, porque foram feitos para ficar abertos por minutos.

Passe o seu próprio fetch para mudar o caminho das requisições:

• Testes. Retorne objetos Response prontos a partir de um mock.
• Novas tentativas. Envolva o fetch global em um helper que tente de novo diante de uma resposta 5xx.
• Rastreamento. Envolva-o com a sua biblioteca de rastreamento ou de monitoramento.

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
  fetch: (input, init) => tracedFetch(input, init),
})

Runtimes e navegadores

O SDK usa apenas fetch e URL, que são globais no Node.js 20 ou mais recente, nos navegadores modernos, no React Native, no Cloudflare Workers, no Deno e no Bun. Não é preciso nenhum polyfill.

• CORS com tokens OAuth. Um app de navegador que chama o Nodaro com um token de acesso OAuth precisa rodar em uma origem listada em allowedOrigins do app de desenvolvedor. Veja OAuth e apps de desenvolvedor.
• CORS com uma sessão. Um app de navegador que usa supabaseAuth não é verificado com essa lista.
• O rótulo do cliente. Em um servidor, o SDK envia X-Nodaro-Client: sdk/<version>, e o Nodaro o registra como a origem de cada job. No navegador, o rótulo padrão não é enviado, porque o cabeçalho Origin do navegador já identifica o seu app. Um clientLabel definido por você é sempre enviado.