אימות

ספק אימות אומר ל-SDK של Nodaro איזה אסימון לשלוח. לפני כל בקשה, הלקוח קורא ל-getToken() של הספק ושולח את התוצאה כ-Authorization: Bearer <token>. כשהספק מחזיר null, הבקשה נשלחת בלי הכותרת, כבקשה אנונימית.

בחירת ספק אימות

האסימונים שאפשר להשתמש בהם

• אסימון API משמש כפרטי גישה קבועים, בלי תקרת הוצאה. האסימון עובד עד שתשביתו או תמחקו אותו, ולכן שמרו אותו בשרת. המגבלות והגדרות מגבלת הקצב מפורטות בדף ה-API אימות.
• אסימון גישה של OAuth כולל רק את ההרשאות שהמשתמש אישר. השתמשו בו כשהאפליקציה שלכם פועלת בשם אנשים אחרים. ראו את הדף אפליקציות OAuth.
• בהתקנה של מהדורת Community באירוח עצמי, האפליקציה לא מציעה אסימוני API. התחברו והשתמשו במקומם באסימון הסשן שלכם, עם supabaseAuth או עם CallbackAuth.

הממשק Auth

interface Auth {
  getToken(): Promise<string | null>
}

כל אובייקט במבנה הזה יכול לשמש כאפשרות auth של createClient. שלושת הספקים שבהמשך מממשים את הממשק הזה.

StaticTokenAuth

new StaticTokenAuth(token: string)

עוטף אסימון קבוע אחד. השתמשו בו כשהאסימון לא משתנה כל זמן שהקוד שלכם רץ: אסימון API, או אסימון גישה של OAuth שהשרת שלכם קיבל בזרימת ה-authorization code.

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

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

CallbackAuth

new CallbackAuth(fn: () => string | null | Promise<string | null>)

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

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

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

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new CallbackAuth(async () => {
    const session = await sessionStore.read()
    if (!session) return null
    if (Date.now() > session.expiresAt - 60_000) {
      await refresh(session)
    }
    return session.accessToken
  }),
})

supabaseAuth(supabase)‎

supabaseAuth(supabase: SupabaseLikeClient): Auth

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

import { createClient, supabaseAuth } from "@nodaro/sdk"
import { createClient as createSupabase } from "@supabase/supabase-js"

const supabase = createSupabase(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY,
)

const client = createClient({
  baseUrl: import.meta.env.VITE_API_URL ?? "",
  auth: supabaseAuth(supabase),
})

כשאף אחד לא מחובר, הבקשה נשלחת בלי אסימון.

createSharedSupabaseClient(options)‎

import { createSharedSupabaseClient } from "@nodaro/sdk/supabase"

createSharedSupabaseClient<Db = any>(options: {
  url: string
  anonKey: string
  cookieDomain?: string
}): SupabaseClient<Db>

יוצרת לקוח Supabase לדפדפן ששומר את הסשן ב-cookies במקום ב-local storage. עם cookieDomain, כמה אפליקציות בתת־דומיינים של אותו דומיין חולקות התחברות אחת: משתמש שמתחבר באחת מהן מחובר בכולן, והתנתקות באחת מהן מנתקת את המשתמש מכולן.

import { createClient, supabaseAuth } from "@nodaro/sdk"
import { createSharedSupabaseClient } from "@nodaro/sdk/supabase"

const supabase = createSharedSupabaseClient({
  url: SUPABASE_URL,
  anonKey: SUPABASE_ANON_KEY,
  cookieDomain: ".example.com",
})

const client = createClient({ baseUrl: "", auth: supabaseAuth(supabase) })

• האפשרות cookieDomain חלה רק כשהדומיין של הדף הוא הדומיין הזה או אחד מתת־הדומיינים שלו. בכל דומיין אחר, כמו localhost או כתובת של סביבת תצוגה מקדימה, ה-cookies נשארים בדומיין הנוכחי, ולכן בפיתוח מקומי יש לכל origin סשן נפרד.
• בטעינה הראשונה, סשן קיים ב-local storage עובר ל-cookie, והרשומה הישנה נמחקת. משתמש שכבר היה מחובר נשאר מחובר. סשנים שפג תוקפם נמחקים.
• הייצוא הזה נמצא בנתיב נפרד, @nodaro/sdk/supabase, ולכן החבילה הראשית לא תלויה ב-Supabase. כדי להשתמש בו, התקינו את @supabase/supabase-js ואת @supabase/ssr.

הרשאות (scopes) והרשאות חסרות

אסימון גישה של OAuth כולל את ההרשאות שהמשתמש אישר, כמו workflows:read או workflows:execute. בדף של כל משאב מצוינת ההרשאה שהמתודות שלו צריכות. כשלאסימון חסרה הרשאה, המתודה זורקת ForbiddenError, והשדה missingScope של השגיאה מציין את ההרשאה החסרה:

import { ForbiddenError } from "@nodaro/sdk"

try {
  await client.workflows.run(workflowId)
} catch (err) {
  if (err instanceof ForbiddenError && err.missingScope) {
    requestConsentFor([err.missingScope]) // send the user through OAuth again
  } else {
    throw err
  }
}

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

כללים לדפדפן

• לעולם אל תשימו אסימון API בקוד של דפדפן. כל אחד יכול לקרוא אותו מהדף, והוא פועל בשמכם.
• אסימוני OAuth בדפדפן עובדים רק מ-origin שמופיע ב-allowedOrigins של יישום המפתחים שלכם. ראו את הדף OAuth ויישומי מפתחים.
• אסימוני סשן מ-supabaseAuth לא נבדקים מול הרשימה הזו.
• שמרו סודות בשרת. החלפת הקוד של OAuth באסימון דורשת את סוד הלקוח שלכם, ולכן הריצו את client.oauth.exchangeCode() רק בקוד שרץ בשרת.