NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
SDK para TypeScript

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): NodaroClient

Propriedade

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>.

RecursoO que cobreReferência
client.workflowsWorkflows: criar, atualizar, compartilhar, exportar, importar e executarWorkflows e projetos
client.projectsOs projetos que guardam os workflowsWorkflows e projetos
client.sessionsSessões de geração dentro de projetosWorkflows e projetos
client.executionsExecuções de um workflow inteiroTarefas e execuções
client.jobsTarefas de geração avulsas, com avaliações e filtrosTarefas e execuções
client.webhooksEndpoints que o Nodaro chama quando uma tarefa terminaTarefas e execuções
client.videoProInterromper ou continuar uma execução do Gerar vídeo ProTarefas e execuções
client.nodesO catálogo de nós e as execuções de um único nóExecutar nós
client.appsApps publicados e as execuções delesApps e templates
client.templatesO marketplace de templatesApps e templates
client.tutorialsVídeos de tutorial e workflows de tutorialApps e templates
client.llmSaída estruturada de um modelo de linguagemLLM e Reduce
client.reduceEscolher o melhor de muitos resultados, ou combiná-losLLM e Reduce
client.uploadsUpload de arquivosMídia e uploads
client.libraryAs suas mídias armazenadasMídia e uploads
client.galleryA galeria pública e os seus favoritosMídia e uploads
client.mediaBaixar, cortar, legendar, sobrepor e fazer colagens de mídiasMídia e uploads
client.voicesVozes, modificador de voz, design de voz e dublagemVozes e áudio
client.dubbingFaz uma dublagem, lê as falas e as legendas dela e adiciona um idiomaVozes e áudio
client.audioSeparar, isolar, mixar, cortar e transcrever áudioVozes e áudio
client.editEdiçã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 EDLEdição
client.scene3dCenas 3D editáveis e Renderização 3D ProCenas 3D
client.charactersPersonagensPersonagens
client.locationsLocaisLocais
client.objectsObjetos e adereçosObjetos e criaturas
client.creaturesAnimais e criaturasObjetos e criaturas
client.communityA biblioteca compartilhada de entidades da comunidadeBiblioteca da comunidade
client.studioProduções do StudioProduções do Studio
client.shotsRegistros compartilhados de tomadas, por trás dos links de compartilhamentoProduções do Studio
client.recastExecuções do Recast e roteiros própriosRecast
client.videoRemakeSubstitui as pessoas, os pets, os produtos ou o lugar de um vídeo curto, só no Nodaro CloudVideo Remake
client.trendsReceitas prontas do Video Remake executadas com as suas próprias imagens, só no Nodaro CloudTrends
client.pipelinesPipelines de história para vídeoPipelines
client.copilotThreads do Copilot, apenas dentro do app do NodaroCopilot
client.modelsO catálogo de modelosModelos e créditos
client.creditsO seu saldo e os preços dos modelosModelos e créditos
client.billingPlanos, preços e a sua assinaturaModelos e créditos
client.pickerCatalogsAs opções válidas de cada seletorSeletores, predefinições e prompts
client.catalogsTodos os catálogos de seletores em uma única chamadaSeletores, predefinições e prompts
client.presetsPredefinições de nó salvas e nativasSeletores, predefinições e prompts
client.palettesAs suas paletas de coresSeletores, predefinições e prompts
client.moodboardsOs seus painéis de inspiraçãoSeletores, predefinições e prompts
client.promptHelperO Assistente de promptSeletores, predefinições e prompts
client.organizationsOrganizações, membros e convitesOrganizações e espaços de trabalho
client.workspacesEspaços de trabalho, membros e códigos de entradaOrganizações e espaços de trabalho
client.userSettingsAs 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 mensalConfigurações do usuário
client.surfaceO que esta implantação oferece a você: tipos de nó, modelos e mundosSurface
client.developerAppsOs apps OAuth que você possuiOAuth e apps de desenvolvedor
client.oauthTroca de código, revogação de tokens e dados da tela de consentimentoOAuth 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/client contém createClient, NodaroClient e os provedores de autenticação.
  • @nodaro/sdk/core contém NodaroClientCore e os mesmos provedores de autenticação.
  • @nodaro/sdk/errors contém as classes de erro e throwFromResponse.
  • Cada um dos outros pontos de entrada leva o nome do seu recurso. @nodaro/sdk/node-presets é client.presets, e @nodaro/sdk/webhooks também contém verifyWebhookSignature.
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ê 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)
CampoTipoDescrição
idstringO ID do usuário no Nodaro.
emailstringO endereço de e-mail do usuário.
displayNamestring | nullO nome de exibição, ou null quando não está definido.
avatarUrlstring | nullA URL do avatar, ou null quando não está definida.
tierstringO 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().
isAdminbooleanSe 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 significaO que fazer
Os campos estão ausentesA instância não tem organizaçõesNão mostre um seletor de espaço de trabalho.
Os campos estão presentes e vaziosA conta não pertence a nenhuma organizaçãoOfereça criar uma organização ou entrar em uma.
organizationsUnavailable: trueA consulta falhouMantenha 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? }]
CampoTipoDescrição
authorizationIdstringA autorização. Passe-a para revokeConnectedApp().
namestring | nullO nome do app. Um cliente MCP que se registrou sozinho escolheu o próprio nome.
kindDeveloperAppKinduser (um app de desenvolvedor), first_party_mcp, dynamic_mcp (um cliente MCP que se registrou sozinho) ou community_instance (uma instalação auto-hospedada).
homepageUrlstring | nullA página inicial do app, quando ele informou uma.
scopesDeveloperAppScope[]Os escopos que a autorização contém.
connectedAtstringQuando o usuário concedeu o acesso, em ISO 8601.
lastUsedAtstring | nullO uso mais recente de qualquer token emitido com essa autorização, ou null se nunca foi usado.
grantedBy"assertion_exchange", opcionalPresente 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étodoEndpointObservações
get()GET /v1/user/settingsRetorna 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/settingsAltera só os campos que você envia e retorna as configurações como foram salvas, sem tier.

Regras de update(patch):

  • promptTemplates e textTemplates substituem 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. null limpa um dos campos, por exemplo update({ mcpPreferences: { image: { model: null } } }), e as ferramentas MCP passam a usar o próprio padrão para ele. O tipo do patch é UserMcpPreferencesPatch.
  • publicOutputs: false exige o plano Standard ou superior no Nodaro Cloud. Caso contrário, lança ForbiddenError.
  • preferredLocale é um dos idiomas que o Nodaro oferece (UserSettingsLocale).
  • Um valor inválido, ou um patch sem nada para alterar, lança um NodaroError com status 400 (validation_error). Um perfil ausente lança NotFoundError.
// 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étodoEndpointObservações
availability()GET /v1/surface/availabilityRetorna 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): 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 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 Response prontos a partir de um mock.
  • Novas tentativas. Envolva o fetch global 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 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 tarefa. 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.

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.

Última atualização

Nesta página