לקוח

הלקוח הוא האובייקט ש-createClient() מחזירה: מופע של NodaroClient ששומר את כתובת הבסיס, את ספק האימות ואת ההגדרות שלכם, וחושף כל חלק של ה-API של Nodaro כמשאב, כמו client.workflows או client.nodes. יוצרים אותו פעם אחת ומשתמשים בו שוב בכל קריאה.

יצירת לקוח

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

ה-SDK מייצא את 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>.

ללקוח עצמו יש עוד חמש מתודות: me(), connectedApps(), revokeConnectedApp(), withWorkspace() ו-request().

נקודות כניסה לכל משאב

החבילה הראשית, @nodaro/sdk, מייצאת הכל. כל משאב מתפרסם גם כנקודת כניסה משלו, @nodaro/sdk/<entry>, שטוענת רק את המשאב הזה ואת הטיפוסים שהוא מקבל ומחזיר. למשל @nodaro/sdk/jobs, @nodaro/sdk/nodes ו-@nodaro/sdk/workflows.

• ב-@nodaro/sdk/client נמצאים createClient, NodaroClient וספקי האימות.
• ב-@nodaro/sdk/core נמצאים NodaroClientCore ואותם ספקי אימות.
• ב-@nodaro/sdk/errors נמצאות מחלקות השגיאה ו-throwFromResponse.
• כל נקודת כניסה אחרת נקראת על שם המשאב שלה. נקודת הכניסה @nodaro/sdk/node-presets היא client.presets, וב-@nodaro/sdk/webhooks נמצאת גם הפונקציה verifyWebhookSignature.

import { NotFoundError } from "@nodaro/sdk/errors"
import type { Job, JobStatus } from "@nodaro/sdk/jobs"

ערך שמייבאים מנקודת כניסה זהה לערך שמייבאים מהחבילה הראשית, ולכן בדיקת instanceof NotFoundError עובדת בלי קשר לנתיב שממנו כל צד ייבא. הפונקציה createClient בונה את כל המשאבים, ולכן נקודת הכניסה @nodaro/sdk/client טוענת את כולם. תת־הנתיבים הישנים @nodaro/sdk/supabase ו-@nodaro/sdk/signup-signals לא השתנו.

לקוח עם המשאבים שאתם משתמשים בהם בלבד

המחלקה NodaroClientCore היא הלקוח בלי המשאבים שלו: האפשרויות ש-createClient מקבלת, מתודות הבקשה והמתודות me(), connectedApps() ו-revokeConnectedApp(). המחלקה NodaroClient מרחיבה אותה עם כל המשאבים. הרחיבו אותה בעצמכם רק עם המשאבים שאתם קוראים להם, והמודולים של שאר המשאבים לא נטענים אף פעם:

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" })

כל מחלקת משאב מקבלת NodaroClientCore. המחלקה NodesResource צריכה את jobs על אותו לקוח, והמחלקה Scene3DResource צריכה את nodes: הטיפוסים של הבנאים שלהן מציינים זאת, ולכן קוד שמשמיט אחד מהם לא עובר קומפילציה. המתודה withWorkspace שייכת ל-NodaroClient. כדי לעבוד בסביבת עבודה, העבירו את workspaceId לבנאי.

מה המתודות מחזירות

• המעטפות נשמרות. כשנקודת קצה מחזירה { "data": ... }, המתודה מחזירה את המעטפת הזו, ולכן כותבים const { data } = await client.workflows.get(id). ברשימות עם עמודים יש גם cursor ליד data, כמו nextCursor.
• חלק מהמשאבים מחזירים את המטען עצמו. כמה מתודות פותחות את המעטפת של התגובה. למשל, המתודה client.characters.list() מחזירה { characters, nextCursor }, והמתודה client.credits.balance() מחזירה את היתרה עצמה. בדף של כל משאב מופיע טיפוס ההחזרה המדויק.
• מחיקות וביטולים מחזירים בדרך כלל { success: true }.
• שמות השדות זהים לפורמט שה-API שולח. השדות של Job כתובים ב-snake_case, כמו output_data ו-created_at, כי כך ה-API שולח אותם. השדות של 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), לפי מועד אישור הגישה, מהחדש לישן. הרשימה כוללת יישומי מפתחים, מחברי MCP של עוזרי AI והתקנות באירוח עצמי. אלה הנתונים שמסך הגדרות של אפליקציות מחוברות מציג. ראו את הדף אפליקציות 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)

client.userSettings

המשאב client.userSettings קורא ומשנה את ההגדרות של האדם המחובר עצמו: שפת הממשק, הנראות בגלריה, הדוח החודשי במייל וההעדפות של תפריט הוספת רכיב ושל הקנבס. אפשר גם לייבא אותו מ-@nodaro/sdk/user-settings. אפליקציה מציגה את ההגדרות שהיא צריכה, ושולחת בחזרה רק את השדות שהיא משנה.

כללים ל-update(patch):

• השדות promptTemplates ו-textTemplates מחליפים את הערך השמור כולו, ולכן שלחו את המפה או את הרשימה המלאה. השרת משמיט מפתח תבנית שהוא לא מכיר, וגם ערך ששווה לברירת המחדל.
• השדה mcpPreferences ממוזג ציר אחר ציר.
• הערך publicOutputs: false דורש ב-Nodaro Cloud את תוכנית Standard ומעלה. אחרת המתודה זורקת ForbiddenError.
• השדה preferredLocale מקבל אחת מהשפות ש-Nodaro תומך בהן (UserSettingsLocale).
• כשערך לא תקין, או כשאין ב-patch מה לשנות, המתודה זורקת NodaroError עם סטטוס 400 (validation_error). כשהפרופיל חסר, היא זורקת NotFoundError.

// The monthly statement toggle on a billing screen.
const { monthlyStatementEmail } = await client.userSettings.get()
await client.userSettings.update({ monthlyStatementEmail: !monthlyStatementEmail })

הטיפוסים הם UserSettings, UserSettingsPatch, UserSettingsSaved, UserSettingsLocale, UserTextTemplate, UserMcpPreferences, VariableDisplayMode ו-NodeDoubleClickAction.

withWorkspace(workspaceId)‎

withWorkspace(workspaceId: string | null): NodaroClient

מחזירה לקוח חדש שפועל ב-workspaceId. הלקוח החדש חולק עם המקורי את האימות, את כתובת הבסיס, את פסק הזמן ואת פונקציית ה-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

המתודה מחזירה לקוח חדש במקום לשנות את הלקוח הנוכחי. לכן שתי פעולות שרצות באותו זמן על אותו לקוח אף פעם לא מתבלבלות בין סביבות העבודה שלהן.

סביבת העבודה קובעת את ההיקף, אף פעם לא את הגישה. היא בוחרת מאיזו סביבת עבודה נקראת רשימה, ואיפה נוצר פריט חדש. קריאה, שינוי, מחיקה או הרצה של פריט שאתם מציינים לפי מזהה נקבעים לפי סביבת העבודה של הפריט עצמו. כששוכחים לציין סביבת עבודה, העבודה שלכם לא נעלמת, וסביבת עבודה שגויה לא נותנת גישה לעבודה של אף אחד אחר.

ב-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 נשלח כהעלאת multipart. ערכי שאילתה שהם undefined מושמטים. מדריך ה-REST API מפרט את כל נקודות הקצה ואת השדות שלהן.

פסקי זמן ו-fetch משלכם

האפשרות timeoutMs מבטלת בקשה שנמשכת יותר מהמגבלה, 60 שניות כברירת מחדל. רוב היצירות נמשכות יותר מכל פסק זמן סביר של HTTP, ולכן התחילו את היצירה ובדקו את סטטוס המשימה מדי כמה שניות: המתודה client.nodes.runAndWait() עושה את שני הדברים בשבילכם. מתודות ההזרמה, client.copilot.stream() ו-client.media.downloadVideoProgress(), לא מחילות את פסק הזמן, כי הן אמורות להישאר פתוחות במשך דקות.

העבירו fetch משלכם כדי לשנות את הדרך שבה הבקשות נשלחות:

• בדיקות. החזירו מ-mock אובייקטי 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. אין צורך ב-polyfill.

• CORS עם אסימוני OAuth. אפליקציית דפדפן שקוראת ל-Nodaro עם אסימון גישה של OAuth חייבת לרוץ על origin שמופיע ב-allowedOrigins של יישום המפתחים. ראו את הדף OAuth ויישומי מפתחים.
• CORS עם סשן. אפליקציית דפדפן שמשתמשת ב-supabaseAuth לא נבדקת מול הרשימה הזו.
• תווית הלקוח. בשרת, ה-SDK שולח X-Nodaro-Client: sdk/<version>, ו-Nodaro רושם אותה כמקור של כל משימה. בדפדפן, תווית ברירת המחדל לא נשלחת, כי כותרת ה-Origin של הדפדפן כבר מציינת את האפליקציה שלכם. ערך clientLabel שהגדרתם בעצמכם נשלח תמיד.