클라이언트

클라이언트는 createClient()가 반환하는 객체입니다. NodaroClient는 내 기본 URL, 인증 공급자, 설정을 보관하고, client.workflows나 client.nodes처럼 Nodaro API의 모든 부분을 리소스로 제공합니다. 클라이언트는 한 번 만들고 모든 호출에서 다시 사용하세요.

클라이언트 만들기

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는 클래스로도 내보내지므로, 클라이언트를 받는 함수에 타입을 지정할 수 있습니다.

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

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

클라이언트의 리소스

모든 리소스는 createClient가 만들며, client.<resource>로 접근합니다.

클라이언트 자체에는 메서드가 5개 더 있습니다. me(), connectedApps(), revokeConnectedApp(), withWorkspace(), request()입니다.

메서드가 반환하는 값

• 엔벨로프는 그대로 유지됩니다. 엔드포인트가 { "data": ... }로 응답하면 메서드는 그 엔벨로프로 이행하므로, const { data } = await client.workflows.get(id)처럼 작성합니다. 페이지 단위 목록에는 nextCursor 같은 커서가 data 옆에 추가됩니다.
• 일부 리소스는 페이로드를 반환합니다. 몇몇 메서드는 응답을 풀어서 반환합니다. 예를 들어 client.characters.list()는 { characters, nextCursor }로, client.credits.balance()는 잔액 자체로 이행합니다. 정확한 반환 타입은 각 참조 페이지에 나와 있습니다.
• 삭제와 취소는 보통 { success: true }로 이행합니다.
• 필드 이름은 전송 형식을 따릅니다. Job은 API가 그렇게 보내므로 output_data나 created_at 같은 snake_case 필드를 사용합니다. Workflow와 WorkflowExecution은 camelCase를 사용합니다.

모든 응답 타입과 입력 타입이 내보내지므로 import type으로 가져올 수 있습니다. 타입을 참조하세요.

me()

me(): Promise<UserIdentity & MeOrganizations>

현재 토큰 뒤에 있는 사용자 정보를 반환합니다(GET /v1/me). 유효한 토큰이면 API 토큰이든 OAuth 액세스 토큰이든 브라우저 세션이든 그 소유자로 이행합니다. 토큰이 없거나 유효하지 않으면 UnauthorizedError가 발생합니다.

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

조직이 있는 Nodaro Cloud 인스턴스에서는 결과에 organizations, workspaces, lastWorkspaceId, organizationsUnavailable도 포함됩니다. 세 가지 상태를 각각 다르게 처리하세요.

connectedApps()

connectedApps(): Promise<ConnectedApp[]>

로그인한 사용자의 계정에 접근할 수 있는 모든 앱을 최근 권한 부여 순으로 반환합니다(GET /v1/me/connected-apps). 목록에는 개발자 앱, AI 어시스턴트의 MCP 커넥터, 셀프 호스팅 설치가 포함됩니다. 연결된 앱 설정 화면의 데이터입니다. 권한 부여가 무엇인지는 OAuth를 참조하세요.

이 메서드에는 로그인한 브라우저 세션이 필요합니다. supabaseAuth()나 createSharedSupabaseClient의 세션 토큰을 받습니다. API 토큰(ndr_…)이나 앱 토큰(ndr_app_…)은 UnauthorizedError로 거부하므로, 앱은 자신이 쓰는 권한 부여를 나열하거나 취소할 수 없습니다. 서버 측 통합에서는 호출할 수 없습니다.

const apps = await client.connectedApps()
// [{ authorizationId, name, kind, homepageUrl, scopes, connectedAt, lastUsedAt }]

revokeConnectedApp(authorizationId)

revokeConnectedApp(authorizationId: string): Promise<void>

앱의 접근을 끝냅니다(POST /v1/me/connected-apps/:authorizationId/revoke). 권한 부여와 그로 발급된 모든 토큰을 즉시 취소하므로, 앱의 다음 호출은 401로 실패합니다. connectedApps()처럼 로그인한 브라우저 세션이 필요합니다. 권한 부여가 사용자의 것이 아니거나 이미 취소되었으면 NotFoundError를 발생시킵니다.

await client.revokeConnectedApp(app.authorizationId)

withWorkspace(workspaceId)

withWorkspace(workspaceId: string | null): NodaroClient

workspaceId에서 동작하는 새 클라이언트를 반환합니다. 새 클라이언트는 원래 클라이언트의 인증, 기본 URL, 타임아웃, fetch를 공유합니다. 내 개인 공간을 쓰려면 null을 전달하세요.

const classroom = client.withWorkspace(workspaceId)

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

이 메서드는 현재 클라이언트를 바꾸지 않고 새 클라이언트를 반환합니다. 따라서 한 클라이언트에서 동시에 실행되는 두 작업의 워크스페이스가 서로 섞일 일이 없습니다.

워크스페이스는 범위를 정할 뿐, 접근 권한은 정하지 않습니다. 목록을 어느 워크스페이스에서 읽을지, 새 항목을 어디에 만들지를 정합니다. ID로 지정한 항목을 읽고, 바꾸고, 삭제하고, 실행할 수 있는지는 그 항목이 속한 워크스페이스에 따라 정해집니다. 워크스페이스를 빠뜨려도 내 작업이 숨겨지지 않고, 잘못 지정해도 다른 사람의 작업에 닿지 않습니다.

워크스페이스는 Nodaro Cloud의 조직에 속합니다. 조직과 워크스페이스와 워크스페이스를 참조하세요.

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>

모든 엔드포인트에 요청을 보냅니다. 아직 리소스 메서드가 없는 몇몇 엔드포인트에 사용하세요. 인증 헤더와 워크스페이스를 추가하고, body를 JSON으로 보내고, timeoutMs를 적용하며, 리소스 메서드와 같은 타입 지정 오류를 발생시킵니다.

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

FormData 본문은 멀티파트 업로드로 전송됩니다. 값이 undefined인 쿼리 항목은 빠집니다. 모든 엔드포인트와 필드는 REST API 참조에 나와 있습니다.

타임아웃과 사용자 지정 fetch

timeoutMs는 제한 시간보다 오래 걸리는 요청을 중단하며, 기본값은 60초입니다. 대부분의 생성은 적당한 HTTP 타임아웃보다 오래 걸리므로, 생성을 시작한 다음 작업을 폴링하세요. client.nodes.runAndWait()가 두 가지를 모두 처리합니다. 스트리밍 메서드인 client.copilot.stream()과 client.media.downloadVideoProgress()는 몇 분 동안 열려 있도록 만들어졌으므로 타임아웃을 적용하지 않습니다.

요청이 전달되는 방식을 바꾸려면 직접 만든 fetch를 전달하세요.

• 테스트. 목에서 미리 준비한 Response 객체를 반환합니다.
• 재시도. 전역 fetch를 5xx 응답에서 재시도하는 헬퍼로 감쌉니다.
• 추적. 사용하는 추적 또는 모니터링 라이브러리로 감쌉니다.

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

런타임과 브라우저

SDK는 fetch와 URL만 사용합니다. 둘 다 Node.js 20 이상, 최신 브라우저, React Native, Cloudflare Workers, Deno, Bun에서 전역으로 제공됩니다. 폴리필은 필요하지 않습니다.

• OAuth 토큰과 CORS. OAuth 액세스 토큰으로 Nodaro를 호출하는 브라우저 앱은 개발자 앱의 allowedOrigins에 등록된 출처에서 실행되어야 합니다. OAuth와 개발자 앱을 참조하세요.
• 세션과 CORS. supabaseAuth를 사용하는 브라우저 앱은 이 목록으로 확인하지 않습니다.
• 클라이언트 레이블. 서버에서는 SDK가 X-Nodaro-Client: sdk/<version>을 보내고, Nodaro는 이 값을 각 작업의 출처로 기록합니다. 브라우저에서는 브라우저의 Origin 헤더가 이미 내 앱을 알려 주므로 기본 레이블을 보내지 않습니다. 직접 설정한 clientLabel은 항상 전송됩니다.