Cliente
Crie um cliente do SDK do Nodaro com createClient, defina URL base, autenticação, tempo limite e espaço de trabalho, e veja todos os recursos do 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): NodaroClientPropriedade
Tipo
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>.
| Recurso | O que cobre | Referência |
|---|---|---|
client.workflows | Workflows: criar, atualizar, compartilhar, exportar, importar e executar | Workflows e projetos |
client.projects | Os projetos que guardam os workflows | Workflows e projetos |
client.sessions | Sessões de geração dentro de projetos | Workflows e projetos |
client.executions | Execuções de um workflow inteiro | Tarefas e execuções |
client.jobs | Tarefas de geração avulsas, com avaliações e filtros | Tarefas e execuções |
client.webhooks | Endpoints que o Nodaro chama quando uma tarefa termina | Tarefas e execuções |
client.videoPro | Interromper ou continuar uma execução do Gerar vídeo Pro | Tarefas e execuções |
client.nodes | O catálogo de nós e as execuções de um único nó | Executar nós |
client.apps | Apps publicados e as execuções deles | Apps e templates |
client.templates | O marketplace de templates | Apps e templates |
client.tutorials | Vídeos de tutorial e workflows de tutorial | Apps e templates |
client.llm | Saída estruturada de um modelo de linguagem | LLM e Reduce |
client.reduce | Escolher o melhor de muitos resultados, ou combiná-los | LLM e Reduce |
client.uploads | Upload de arquivos | Mídia e uploads |
client.library | As suas mídias armazenadas | Mídia e uploads |
client.gallery | A galeria pública e os seus favoritos | Mídia e uploads |
client.media | Baixar, cortar, legendar, sobrepor e fazer colagens de mídias | Mídia e uploads |
client.voices | Vozes, modificador de voz, design de voz e dublagem | Vozes e áudio |
client.dubbing | Faz uma dublagem, lê as falas e as legendas dela e adiciona um idioma | Vozes e áudio |
client.audio | Separar, isolar, mixar, cortar e transcrever áudio | Vozes e áudio |
client.edit | Edição de podcast em uma chamada (enxugar, capítulos, trailer, clipes, layout de falantes), detecção de silêncio, sincronização de áudio, troca de câmeras, planos de edição e renderizações de EDL | Edição |
client.scene3d | Cenas 3D editáveis e Renderização 3D Pro | Cenas 3D |
client.characters | Personagens | Personagens |
client.locations | Locais | Locais |
client.objects | Objetos e adereços | Objetos e criaturas |
client.creatures | Animais e criaturas | Objetos e criaturas |
client.community | A biblioteca compartilhada de entidades da comunidade | Biblioteca da comunidade |
client.studio | Produções do Studio | Produções do Studio |
client.shots | Registros compartilhados de tomadas, por trás dos links de compartilhamento | Produções do Studio |
client.recast | Execuções do Recast e roteiros próprios | Recast |
client.videoRemake | Substitui as pessoas, os pets, os produtos ou o lugar de um vídeo curto, só no Nodaro Cloud | Video Remake |
client.trends | Receitas prontas do Video Remake executadas com as suas próprias imagens, só no Nodaro Cloud | Trends |
client.pipelines | Pipelines de história para vídeo | Pipelines |
client.copilot | Threads do Copilot, apenas dentro do app do Nodaro | Copilot |
client.models | O catálogo de modelos | Modelos e créditos |
client.credits | O seu saldo e os preços dos modelos | Modelos e créditos |
client.billing | Planos, preços e a sua assinatura | Modelos e créditos |
client.pickerCatalogs | As opções válidas de cada seletor | Seletores, predefinições e prompts |
client.catalogs | Todos os catálogos de seletores em uma única chamada | Seletores, predefinições e prompts |
client.presets | Predefinições de nó salvas e nativas | Seletores, predefinições e prompts |
client.palettes | As suas paletas de cores | Seletores, predefinições e prompts |
client.moodboards | Os seus painéis de inspiração | Seletores, predefinições e prompts |
client.promptHelper | O Assistente de prompt | Seletores, predefinições e prompts |
client.organizations | Organizações, membros e convites | Organizações e espaços de trabalho |
client.workspaces | Espaços de trabalho, membros e códigos de entrada | Organizações e espaços de trabalho |
client.userSettings | As suas próprias configurações: idioma, visibilidade na galeria, preferências do menu de nós e do canvas, e o e-mail de extrato mensal | Configurações do usuário |
client.surface | O que esta implantação oferece a você: tipos de nó, modelos e mundos | Surface |
client.developerApps | Os apps OAuth que você possui | OAuth e apps de desenvolvedor |
client.oauth | Troca de código, revogação de tokens e dados da tela de consentimento | OAuth e apps de desenvolvedor |
O próprio cliente tem mais cinco métodos: me(), connectedApps(), revokeConnectedApp(), withWorkspace() e request().
Pontos de entrada por recurso
A raiz @nodaro/sdk exporta tudo. Cada recurso também é publicado como um ponto de entrada próprio, @nodaro/sdk/<entry>, que carrega só esse recurso e os tipos que ele recebe e retorna. Por exemplo, @nodaro/sdk/jobs, @nodaro/sdk/nodes e @nodaro/sdk/workflows.
@nodaro/sdk/clientcontémcreateClient,NodaroCliente os provedores de autenticação.@nodaro/sdk/corecontémNodaroClientCoree os mesmos provedores de autenticação.@nodaro/sdk/errorscontém as classes de erro ethrowFromResponse.- Cada um dos outros pontos de entrada leva o nome do seu recurso.
@nodaro/sdk/node-presetséclient.presets, e@nodaro/sdk/webhookstambém contémverifyWebhookSignature.
import { NotFoundError } from "@nodaro/sdk/errors"
import type { Job, JobStatus } from "@nodaro/sdk/jobs"Um valor importado de um ponto de entrada é o mesmo importado da raiz, então instanceof NotFoundError funciona qualquer que seja o caminho usado por cada lado. createClient monta todos os recursos, então @nodaro/sdk/client carrega todos eles. Os subcaminhos mais antigos @nodaro/sdk/supabase e @nodaro/sdk/signup-signals não mudaram.
Um cliente só com os recursos que você usa
NodaroClientCore é o cliente sem os recursos: as opções que createClient recebe, os métodos de requisição, e me(), connectedApps() e revokeConnectedApp(). NodaroClient o estende com todos os recursos. Estenda-o você mesmo só com os recursos que você chama, e os outros módulos de recurso nunca são carregados:
import { NodaroClientCore, StaticTokenAuth } from "@nodaro/sdk/core"
import { JobsResource } from "@nodaro/sdk/jobs"
import { NodesResource } from "@nodaro/sdk/nodes"
class AppClient extends NodaroClientCore {
readonly jobs = new JobsResource(this)
readonly nodes = new NodesResource(this) // polls through `jobs`
}
const client = new AppClient({ baseUrl: "https://app.nodaro.ai", auth: new StaticTokenAuth(token) })
await client.nodes.runAndWait("generate-image", { prompt: "a lighthouse at dusk" })Toda classe de recurso recebe um NodaroClientCore. NodesResource precisa de jobs no mesmo cliente, e Scene3DResource precisa de nodes: os tipos dos construtores dizem isso, então deixar um de fora falha na compilação. withWorkspace é um método de NodaroClient. Para trabalhar em um espaço de trabalho, passe workspaceId para o construtor.
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ê escreveconst { data } = await client.workflows.get(id). As listas paginadas acrescentam um cursor ao lado dedata, comonextCursor. - Alguns recursos retornam o payload. Alguns métodos desembrulham a resposta: por exemplo,
client.characters.list()resolve com{ characters, nextCursor }, eclient.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
Jobusa campos em snake_case, comooutput_dataecreated_at, porque a API os envia assim. UmWorkflowe umWorkflowExecutionusam 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)| Campo | Tipo | Descrição |
|---|---|---|
id | string | O ID do usuário no Nodaro. |
email | string | O endereço de e-mail do usuário. |
displayName | string | null | O nome de exibição, ou null quando não está definido. |
avatarUrl | string | null | A URL do avatar, ou null quando não está definida. |
tier | string | O nível de assinatura armazenado, como "free" ou "pro". Para o nível realmente aplicado, incluindo o pagamento conforme o uso, leia effectiveTier em client.credits.balance(). |
isAdmin | boolean | Se o usuário é administrador. Use-o apenas para decidir o que mostrar. O próprio servidor verifica todas as permissões. |
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:
| O que você vê | O que significa | O que fazer |
|---|---|---|
| Os campos estão ausentes | A instância não tem organizações | Não mostre um seletor de espaço de trabalho. |
| Os campos estão presentes e vazios | A conta não pertence a nenhuma organização | Ofereça criar uma organização ou entrar em uma. |
organizationsUnavailable: true | A consulta falhou | Mantenha a seleção que você já tinha. Não diga ao usuário que ele perdeu o acesso. |
connectedApps()
connectedApps(): Promise<ConnectedApp[]>Retorna todos os apps com acesso à conta do usuário conectado (GET /v1/me/connected-apps), da autorização mais recente para a mais antiga. A lista inclui apps de desenvolvedor, os conectores MCP de assistentes de IA e instalações auto-hospedadas. São os dados por trás de uma tela de configurações Apps conectados. Veja OAuth para entender o que é uma autorização.
Este método precisa de uma sessão de navegador com login. Ele aceita um token de sessão de supabaseAuth() ou de createSharedSupabaseClient. Ele recusa um token de API (ndr_…) ou um token de app (ndr_app_…) com UnauthorizedError, para que um app não possa listar nem revogar as autorizações que usa. Uma integração do lado do servidor não pode chamá-lo.
const apps = await client.connectedApps()
// [{ authorizationId, name, kind, homepageUrl, scopes, connectedAt, lastUsedAt, grantedBy? }]| Campo | Tipo | Descrição |
|---|---|---|
authorizationId | string | A autorização. Passe-a para revokeConnectedApp(). |
name | string | null | O nome do app. Um cliente MCP que se registrou sozinho escolheu o próprio nome. |
kind | DeveloperAppKind | user (um app de desenvolvedor), first_party_mcp, dynamic_mcp (um cliente MCP que se registrou sozinho) ou community_instance (uma instalação auto-hospedada). |
homepageUrl | string | null | A página inicial do app, quando ele informou uma. |
scopes | DeveloperAppScope[] | Os escopos que a autorização contém. |
connectedAt | string | Quando o usuário concedeu o acesso, em ISO 8601. |
lastUsedAt | string | null | O uso mais recente de qualquer token emitido com essa autorização, ou null se nunca foi usado. |
grantedBy | "assertion_exchange", opcional | Presente em uma autorização que o app obteve pela troca para a própria aplicação de uma implantação, sem tela de consentimento. Ausente em toda autorização que o usuário aprovou. |
revokeConnectedApp(authorizationId)
revokeConnectedApp(authorizationId: string): Promise<void>Encerra o acesso de um app (POST /v1/me/connected-apps/:authorizationId/revoke). Revoga a autorização e todos os tokens emitidos com ela de uma vez, então a próxima chamada do app falha com 401. Como connectedApps(), precisa de uma sessão de navegador com login. Lança NotFoundError quando a autorização não é do usuário ou já foi revogada.
await client.revokeConnectedApp(app.authorizationId)client.userSettings
client.userSettings lê e altera as configurações da própria pessoa com login: o idioma da interface, a visibilidade na galeria, as preferências do menu de nós e do canvas, e o e-mail de extrato mensal. Ele também pode ser importado como @nodaro/sdk/user-settings. Um app mostra as configurações de que precisa e devolve só os campos que altera.
| Método | Endpoint | Observações |
|---|---|---|
get() | GET /v1/user/settings | Retorna UserSettings: { tier, publicOutputs, promptTemplates, textTemplates, preferredLocale, mcpPreferences, showRecentNodes, showMostUsedNodes, variableDisplayMode, nodeDoubleClickAction, monthlyStatementEmail }. Lança UnauthorizedError quando ninguém fez login. |
update(patch) | PATCH /v1/user/settings | Altera só os campos que você envia e retorna as configurações como foram salvas, sem tier. |
Regras de update(patch):
promptTemplatesetextTemplatessubstituem o valor armazenado por inteiro, então envie o mapa ou a lista completa. Uma chave de template que o servidor não conhece, ou um valor igual ao padrão, é descartado.mcpPreferencesé mesclado um eixo de cada vez.nulllimpa um dos campos, por exemploupdate({ mcpPreferences: { image: { model: null } } }), e as ferramentas MCP passam a usar o próprio padrão para ele. O tipo do patch éUserMcpPreferencesPatch.publicOutputs: falseexige o plano Standard ou superior no Nodaro Cloud. Caso contrário, lançaForbiddenError.preferredLocaleé um dos idiomas que o Nodaro oferece (UserSettingsLocale).- Um valor inválido, ou um patch sem nada para alterar, lança um
NodaroErrorcom status 400 (validation_error). Um perfil ausente lançaNotFoundError.
// The monthly statement toggle on a billing screen.
const { monthlyStatementEmail } = await client.userSettings.get()
await client.userSettings.update({ monthlyStatementEmail: !monthlyStatementEmail })Os tipos são UserSettings, UserSettingsPatch, UserSettingsSaved, UserSettingsLocale, UserTextTemplate, UserMcpPreferences, UserMcpPreferencesPatch, VariableDisplayMode e NodeDoubleClickAction.
Em uma implantação em que uma conta de cobrança paga por todos os usuários, tier é o plano da implantação, o nível da conta de cobrança, e desligar publicOutputs segue esse plano.
client.surface
client.surface diz o que esta implantação oferece a quem chama: os tipos de nó, os modelos, as fontes do Web Scrape e os mundos que um app deve mostrar à pessoa na tela. A resposta depende de quem pergunta, então ela nunca fica em um cache compartilhado. Sem login, a resposta é a de um usuário. Também pode ser importado como @nodaro/sdk/surface.
| Método | Endpoint | Observações |
|---|---|---|
availability() | GET /v1/surface/availability | Retorna SurfaceAvailability: { nodes: { denied, hiddenFromUsers }, models: { denied, restricted }, webScrapeSources: { denied, hiddenFromUsers }, worlds }. hiddenFromUsers fica vazio para quem não é administrador. models.restricted é true quando a implantação limita quais modelos oferece. Um modelo que um administrador desligou é negado, mas não é uma restrição. Um servidor mais antigo omite restricted: leia isso como false. worlds lista todos os mundos (SurfaceAvailabilityWorld: { id, enabled }) na ordem de exibição da implantação, e um servidor mais novo pode acrescentar um. Um mundo é enabled quando a implantação o deixa passar e todos os tipos de nó que ele executa estão disponíveis para quem chama. |
// The shared header shows only the worlds this person can use.
const { worlds } = await client.surface.availability()
const tabs = worlds.filter((w) => w.enabled).map((w) => w.id)Os campos estão descritos em O que esta implantação oferece a você.
withWorkspace(workspaceId)
withWorkspace(workspaceId: string | null): NodaroClientRetorna 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 spaceO 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 a tarefa periodicamente: client.nodes.runAndWait() faz as duas coisas por você. Os métodos de transmissão contínua, 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
Responseprontos a partir de um mock. - Novas tentativas. Envolva o
fetchglobal em uma função auxiliar 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),
})Ambientes de execução 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
allowedOriginsdo app de desenvolvedor. Veja OAuth e apps de desenvolvedor. - CORS com uma sessão. Um app de navegador que usa
supabaseAuthnã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 tarefa. No navegador, o rótulo padrão não é enviado, porque o cabeçalhoOrigindo navegador já identifica o seu app. UmclientLabeldefinido por você é sempre enviado.
Perguntas frequentes
Qual URL base devo usar com o SDK do Nodaro?
Use https://app.nodaro.ai para o Nodaro Cloud e o endereço da sua instância para uma instalação auto-hospedada. Em um app de navegador servido pela mesma origem que o Nodaro, use uma string vazia.
Qual é o tempo limite padrão das requisições?
60 segundos. Mude-o com a opção timeoutMs. Uma geração demora mais que qualquer requisição, então inicie a geração e consulte a tarefa periodicamente em vez de aumentar o tempo limite.
Como fazer requisições em um espaço de trabalho?
Chame client.withWorkspace(workspaceId). Ele retorna um novo cliente que envia todas as requisições nesse espaço de trabalho, e o cliente original continua trabalhando no seu espaço pessoal.
Como chamar um endpoint que não tem método no SDK?
Use client.request(method, path, options). Ele envia o mesmo cabeçalho de autenticação, aplica o mesmo tempo limite e lança os mesmos erros tipados que todos os métodos de recurso.
Páginas relacionadas
SDK para TypeScript
Autenticação
Erros
Organizações e espaços de trabalho
Tipos
Última atualização
SDK para TypeScript
Instale o @nodaro/sdk, use um token de API e execute nós e workflows do Nodaro em TypeScript, no Node.js, no navegador e em ambientes de execução de borda.
Autenticação
Escolha como o SDK do Nodaro se autentica, com StaticTokenAuth, CallbackAuth ou supabaseAuth, e compartilhe um login do navegador entre seus subdomínios.