एक एपीआई क्लाइंट एकीकरण बनाएं

एक ग्राहक चुनें

रिपॉजिटरी में तीन संबंधित क्लाइंट सतहें हैं। वे समापन बिंदु घोषणाएँ साझा करते हैं, लेकिन उनका निर्माण, इनपुट आकार, रनटाइम निर्भरता और त्रुटि चैनल भिन्न होते हैं। जानबूझकर किसी एक को चुनें और उस सतह से उदाहरण एक साथ रखें।

एपीआई पैकेज स्रोत निर्यात के साथ एक निजी कार्यक्षेत्र है। नीचे दिए गए आयात इस मोनोरेपो या वितरण के लिए हैं जो वास्तव में उन निर्यातों को प्रदान करता है; यह पृष्ठ अलग से उपलब्ध सार्वजनिक एनपीएम पैकेज का दावा नहीं करता है। स्वतंत्र ग्राहक इसका उपयोग कर सकते हैं ओपनएपीआई दस्तावेज़ या सादा HTTP.

क्लाइंट-लाइब्रेरी सेटअप के बिना पहले अनुरोध के लिए, से प्रारंभ करें hTTP वॉकथ्रू कैप्चर किया गया. यह स्थापित करता है कि संचालन के बीच सफलता और विफलता के निकाय कैसे भिन्न होते हैं।

कनेक्शन का समाधान करें

वर्तमान साइडकार लॉन्च से संबंधित यूआरएल और एप्लिकेशन बियरर टोकन का उपयोग करें। टौरी उन्हें प्राप्त करती है get_sidecar_endpoint. एक मैन्युअल विकास प्रक्रिया एक तैयार इवेंट में अपने निर्दिष्ट पोर्ट को प्रिंट करती है। मूल को दस्तावेज़ीकरण साइट या वीआईटी संपत्तियों के बजाय साइडकार या स्वीकृत साथी गेटवे पर इंगित करना चाहिए।

साइडकार पुनरारंभ होने के बाद, कनेक्शन को फिर से हल करें। पिछले पोर्ट का पुन: उपयोग करने से कनेक्शन अस्वीकृत हो सकता है या गलती से किसी अन्य प्रक्रिया को संबोधित किया जा सकता है। पुराने लॉन्च टोकन का पुन: उपयोग करने से प्राधिकरण विफलता उत्पन्न होती है। एक सफल सार्वजनिक स्वास्थ्य प्रतिक्रिया यह साबित नहीं करती है कि संरक्षित अनुरोध स्वीकार कर लिया जाएगा।

खाता चयन, एप्लिकेशन प्रवेश, डिवाइस प्रवेश और बाहरी एजेंट पहुंच अलग-अलग हैं। वैकल्पिक x-session-token आवेदन प्रवेश के बाद एक खाते का चयन करता है। एक प्रोजेक्ट-स्कोप्ड ब्रिज टोकन इसके एक्शन ब्रिज एंडपॉइंट तक सीमित है। एक फ़ोन टोकन गेटवे की अनुमति-सूची के माध्यम से काम करता है। का पीछा करो प्रमाणीकरण संदर्भ एकीकरण के लिए कनेक्शन चुनने से पहले.

वादा एसडीके

निर्यातित नामस्थान है CadCam, और इसका कंस्ट्रक्टर है make. एक आधार यूआरएल और डिफ़ॉल्ट हेडर प्रदान करें। नीचे दी गई निर्माण और प्राप्त विधियाँ नेस्टेड के बजाय चपटे फ़ील्ड का उपयोग करती हैं payload या params वस्तु।

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl,
  headers: { Authorization: "Bearer " + token },
})

const projects = await client.projects.list()
const created = await client.projects.create({
  name: "Fixture plate",
  description: "An integration-created project",
})
const detail = await client.projects.get({ id: created.id })
console.log(projects.length, detail.name, detail._count.drawings)

प्रत्येक कॉल सीधे उस समापन बिंदु के सफलता पेलोड का समाधान करती है। projects.list() एक सरणी लौटाता है; projects.create() एक प्रोजेक्ट पंक्ति लौटाता है। कोई सार्वभौमिक नहीं है { data, error } रैपर और नहीं throwOnError इस एसडीके में कंस्ट्रक्टर विकल्प। कुछ समापन बिंदु पेलोड स्वयं शामिल होते हैं data या success क्योंकि वह उनका HTTP अनुबंध है।

एसडीके एंडपॉइंट पथ और कॉन्फ़िगर किए गए बेस यूआरएल से एक यूआरएल तैयार करता है, पथ पहचानकर्ताओं को एन्कोड करता है, घोषित JSON इनपुट को क्रमबद्ध करता है, और ऑपरेशन की सटीक घोषित सफलता स्थिति की जांच करता है। इसके बाद यह JSON को पार्स करता है और उसका टाइप किया गया मान लौटाता है। प्रॉमिस रनटाइम प्रत्येक लौटाए गए पेलोड पर एक प्रभाव स्कीमा डिकोडर लागू नहीं करता है; टाइपस्क्रिप्ट आउटपुट प्रकार एक मनमाना सर्वर कार्यान्वयन को मान्य नहीं करते हैं।

घोषित और परिवहन त्रुटियाँ

घोषित HTTP विफलताएं डिकोडेड प्रतिक्रिया निकाय के साथ अस्वीकार हो जाती हैं। वह मान जावास्क्रिप्ट त्रुटि के उदाहरण के बजाय एक टैग की गई सादा वस्तु हो सकती है। परिवहन और प्रोटोकॉल विफलताएँ SDK का उपयोग करती हैं ClientError.

import { ClientError } from "@cadcamfun/api/sdk"

try {
  await client.projects.create({})
} catch (error) {
  if (error instanceof ClientError) {
    console.error(error.reason, error.message)
  } else if (error && typeof error === "object" && "message" in error) {
    console.error(String(error.message))
  } else {
    console.error("Unrecognized API failure", error)
  }
}

उदाहरण के लिए, एक अनुपलब्ध प्रोजेक्ट नाम एक HTTP 400 व्यावसायिक विफलता है, भले ही निर्माण इनपुट प्रकार चूक की अनुमति देता है। प्रोजेक्ट बनाते समय कनेक्शन रीसेट करना अलग होता है: यह क्लाइंट को अनिश्चित बना देता है कि लेखन पूरा हुआ या नहीं। किसी उत्परिवर्तन को दोहराने से पहले संसाधन स्थिति पढ़ें। एसडीके एक एप्लिकेशन-वाइड इडेम्पोटेंसी प्रोटोकॉल नहीं जोड़ता है या हर अस्वीकृत कॉल को स्वचालित रूप से पुनः प्रयास नहीं करता है।

रद्दीकरण और शीर्षलेख

ClientOptions स्वीकार baseUrl, एक वैकल्पिक फ़ेच कार्यान्वयन, और डिफ़ॉल्ट हेडर। प्रति कॉल RequestOptions एक सिग्नल और अतिरिक्त हेडर स्वीकार करता है। समापन बिंदु इनपुट के बिना विधियों के लिए, अनुरोध विकल्प पहला तर्क हैं; इनपुट के साथ विधियाँ इसके बाद अनुरोध विकल्प लेती हैं।

const controller = new AbortController()
const pending = client.projects.get(
  { id: projectId },
  {
    signal: controller.signal,
    headers: { "x-session-token": accountSessionToken },
  },
)
// Call controller.abort() when the operation is no longer needed.
const project = await pending

अनुरोध बिल्डर डिफ़ॉल्ट हेडर, एंडपॉइंट-घोषित हेडर और फिर प्रति-कॉल हेडर लागू करता है। प्रति-कॉल मान डिफ़ॉल्ट को ओवरराइड कर सकता है; खाता जोड़ते समय या हेडर ट्रेस करते समय गलती से प्राधिकरण बदलने से बचें। लॉग में कॉपी किए गए एंडपॉइंट यूआरएल में क्रेडेंशियल न डालें।

इंजेक्शन fetch इन-प्रोसेस टेस्ट ट्रांसपोर्ट या नियंत्रित एडाप्टर का समर्थन करता है। एडॉप्टर को अभी भी अनुरोध हेडर, बॉडी, रद्दीकरण, सामग्री प्रकार और प्रतिक्रिया स्थिति शब्दार्थ का सम्मान करना होगा। डेस्कटॉप का अपना इफ़ेक्ट इंटीग्रेशन और फ़ोन का पिन किया हुआ नेटिव ट्रांसपोर्ट अतिरिक्त काम करता है; एक मनमाना फ़ेच को प्रतिस्थापित करने से उन मूल सीमाओं का पुनरुत्पादन नहीं होता है।

पूर्ण प्रभाव ग्राहक

ApiClient.layer पूर्ण HttpApi क्लाइंट, फ़ेच ट्रांसपोर्ट और बियरर मिडलवेयर का निर्माण करता है। यह अंतर्निहित HttpApi अनुरोध आकार के साथ समापन बिंदु विधियों को उजागर करता है। एक उत्परिवर्तन का पेलोड नीचे चला जाता है payload, और पथ मान नीचे चले जाते हैं params.

import { ApiClient } from "@cadcamfun/api"
import { Effect } from "effect"

const createProject = Effect.gen(function* () {
  const api = yield* ApiClient
  return yield* api.projects.create({
    payload: { name: "Fixture plate" },
  })
}).pipe(Effect.provide(ApiClient.layer({ baseUrl, token })))

const project = await Effect.runPromise(createProject)

यह क्लाइंट संपूर्ण एपीआई घोषणा से प्राप्त होता है और जेनरेट किए गए लक्ष्यों से छोड़े गए एंडपॉइंट के लिए विकल्प है। यह इफ़ेक्ट के टाइप किए गए त्रुटि चैनल और स्कीमा-जागरूक ट्रांसपोर्ट को संरक्षित करता है। संसाधन जीवनकाल, स्ट्रीम रुकावट, और परत प्रावधान कॉलिंग प्रभाव कार्यक्रम से संबंधित हैं; प्रभाव बनाने से उसका निष्पादन नहीं होता।

पुन: प्रयोज्य परत एप्लिकेशन टोकन की आपूर्ति करती है। डेस्कटॉप अपनी स्वयं की परत बनाता है apps/desktop/src/app/client.ts वैकल्पिक खाता सत्र स्थिति और इंजेक्टेड ट्रांसपोर्ट संलग्न करने के लिए। प्रति घटक दूसरा कनेक्शन/रनटाइम बनाने के बजाय डेस्कटॉप के अंदर काम करते समय उस एकीकरण का पुन: उपयोग करें।

उत्पन्न प्रभाव एडेप्टर

उत्पन्न इफ़ेक्ट क्लाइंट वास्तविक स्कीमा आयात करता है और तरीकों को चपटे क्षेत्रों में अनुकूलित करता है। इसका CadCam.make एक प्रभाव लौटाता है जो अनुकूलित क्लाइंट का निर्माण करता है। यह अपनी स्वयं की फ़ेच ट्रांसपोर्ट या एप्लिकेशन प्राधिकरण परत प्रदान नहीं करता है, इसलिए कॉल करने वाले को संबंधित सेवाएं और मिडलवेयर प्रदान करना होगा।

उत्पन्न त्रुटि एडॉप्टर ट्रांसपोर्ट/स्कीमा/एसएसई विफलताओं को एक टैग में मैप करता है ClientError घोषित डोमेन विफलताओं को बरकरार रखते हुए। यह त्रुटि वर्ग प्रॉमिस एसडीके के जावास्क्रिप्ट त्रुटि वर्ग से अलग है reason डोरी। नाम की समानता उनके संचालन को विनिमेय नहीं बनाती है।

इनपुट उदाहरण स्पष्ट रखें. वादा और उत्पन्न प्रभाव प्रपत्र का उपयोग करें projects.get({ id }); कच्चे अनुबंध प्रपत्र का उपयोग करता है projects.get({ params: { id } }). अनियंत्रित प्रकार के दावे के माध्यम से एक सतह के इनपुट ऑब्जेक्ट को दूसरे में भेजने से बचें।

स्ट्रीमिंग

वादा एसएसई संचालन एसिंक पुनरावर्तनीय लौटाता है। नेटवर्क सेटअप तब होता है जब पुनरावृत्ति शुरू होती है। रनटाइम सफलता की स्थिति और इवेंट-स्ट्रीम सामग्री प्रकार की जांच करता है, वृद्धिशील यूटीएफ-8 डेटा पढ़ता है, फ़्रेम सीमाओं को सामान्य करता है, और JSON-डेटा फ़्रेम को डीकोड करता है। एक विकृत फ्रेम पुनरावृत्ति में विफल रहता है; रीडर क्लीनअप तब चलता है जब पुनरावृत्ति समाप्त होती है या बाहर निकलती है।

रनटाइम का गार्ड है 16 * 1024 * 1024 बफ़र्ड जावास्क्रिप्ट स्ट्रिंग इकाइयाँ। यह फ़्रेम सीमा से पहले संचय को सीमित करता है; यह कोई वादा नहीं है कि प्रत्येक मनमाना 16 एमबी पेलोड एप्लिकेशन के इवेंट स्कीमा के लिए उपयोगी या मान्य है।

एआई घटनाओं को उनके विभेदकों के अनुसार उपभोग करें और सत्र पहचानकर्ता को संरक्षित करें। एक समाप्त परिवहन टर्मिनल वार्तालाप घटना का प्रमाण नहीं है। उपयोग एआई स्ट्रीमिंग और रिकवरी कतार, निरस्त, अनुमति, प्रश्न और स्थिति पुनर्प्राप्ति व्यवहार के लिए। EventSource प्राधिकरण हेडर और JSON बॉडी वाले POST अनुरोध के लिए ड्रॉप-इन प्रतिस्थापन नहीं है।

कवरेज और पुनर्जनन

जनरेटर के पास उन आकृतियों के लिए स्पष्ट चूक सूचियाँ हैं जिनका वह प्रतिनिधित्व नहीं कर सकता है। साझा चूक में मल्टीपार्ट प्रोफ़ाइल/प्लगइन अपलोड, एकाधिक सफलता स्कीमा के साथ एमसीपी निर्माण, टकराने वाले इनपुट नाम, और इसके स्ट्रीम पर प्रतिक्रिया हेडर के साथ प्लगइन की सेवा शामिल है। अतिरिक्त प्रॉमिस चूक में कच्चे हस्ताक्षरित वेबहुक, जावास्क्रिप्ट प्लगइन बूटस्ट्रैप, बाइनरी डाउनलोड और फ्री-फॉर्म जनरेटर अनुरोध शामिल हैं।

सटीक वर्तमान सूचियाँ पढ़ें packages/api/scripts/generate-clients.ts और यह एपीआई सिंहावलोकन. अनुपस्थित जनरेट की गई विधि यह स्थापित नहीं करती है कि सर्वर एंडपॉइंट अनुपलब्ध है। उस ऑपरेशन के लिए पूर्ण अनुबंध क्लाइंट या उपयुक्त कच्चे परिवहन का उपयोग करें।

bun run generate
bun run generate:check
bun run --filter @cadcamfun/web generate:api-reference
bun run --filter @cadcamfun/web check:api-reference

ग्राहक पुनर्जनन और दस्तावेज़ीकरण पुनर्जनन एक ही अनुबंध से अलग-अलग आउटपुट हैं। समापन बिंदु परिवर्तन के बाद दोनों को चालू रखें। सर्वर की इनपुट आवश्यकताओं को बदलने के लिए जेनरेट की गई विधि निकायों को संपादित न करें।

जनरेट किया गया कोड लिखा जाता है packages/api/src/client/generated और packages/api/src/sdk/generated. उन फ़ाइलों को हाथ से संपादित न करें; अनुबंध बदलें और पुन: उत्पन्न करें।

एकीकरण सत्यापन

यहां दिखाए गए प्रॉमिस क्रिएट/रीड/प्लेन-रिजल्ट व्यवहार और घोषित विफलता को माइग्रेट किए गए डिस्पोजेबल डेटाबेस का उपयोग करके वास्तविक साइडकार हैंडलर स्टैक के विरुद्ध प्रयोग किया गया था। HTTP वॉकथ्रू में संबंधित देखी गई प्रतिक्रियाएँ शामिल हैं। जनरेटर, प्रमाणीकरण, या एंडपॉइंट स्कीमा बदलते समय केंद्रित जांच दोहराएं।

For an integration acceptance check, verify public health; a protected request without a token; the same request with the current token; a valid create/read cycle; a declared validation failure; a cancelled request; and a stream whose terminal state is checked. Use a disposable project and never infer successful persistence from a frontend fixture alone.

कार्यान्वयन स्रोत हैं packages/api/src/sdk/generated/client.ts, इसका client-error.ts, packages/api/src/client.ts, packages/api/src/client/generated, और packages/httpapi-codegen/src/index.ts. जनरेटर और प्रतिबद्ध आउटपुट मिलकर वास्तविक ग्राहक व्यवहार स्थापित करते हैं।

वादा एसडीके विकल्प संदर्भ

जब एक शरीर मौजूद है और नहीं content-type हेडर सेट किया गया था, SDK सेट होता है application/json और के साथ क्रमबद्ध करता है JSON.stringify. पथ पैरामीटर हमेशा पारित किए जाते हैं encodeURIComponent, तो एक कुंजी जैसे docs.walkthrough.units या एक युक्त / एक खंड रहता है.

क्लाइंटत्रुटि कारण

ए का संदेश ClientError कारण संदेश के बाद कारण है (उदाहरण के लिए)। Transport: fetch failed), इसलिए लॉगिंग error.message अकेले पहले से ही निदान है।

import { CadCam, ClientError } from "@cadcamfun/api/sdk"

async function withRetry<T>(read: () => Promise<T>, attempts = 3): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await read()
    } catch (error) {
      const transient = error instanceof ClientError && error.reason === "Transport"
      if (!transient || attempt >= attempts) throw error
      await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt))
    }
  }
}

const projects = await withRetry(() => client.projects.list())

एसडीके के साथ एक स्ट्रीम का उपभोग

const controller = new AbortController()
const events = client.ai.chatStream(
  { message: "Pocket the 40 x 30 rectangle, 3 mm deep", projectId },
  { signal: controller.signal },
)

for await (const event of events) {
  switch (event.type) {
    case "delta": render(event); break
    case "permission_request": askUser(event); break
    case "done": finish(event); break
    case "error": showError(event); break
  }
}

पुनरावर्तक प्रत्येक SSE ब्लॉक को पार्स करता है: यह जुड़ता है data: ब्लॉक की पंक्तियाँ, JSON को पार्स करती हैं और उसे उत्पन्न करती हैं। बिना टिप्पणियाँ और ब्लॉक data: छोड़ दिए गए हैं. लूप को जल्दी छोड़ना (break, एक अपवाद, या निरस्त) रीडर को रद्द कर देता है और कनेक्शन जारी कर देता है। समारोह type मान सहायक स्ट्रीमिंग गाइड में सूचीबद्ध हैं; उत्पन्न की जाँच करें AiChatStreamOutput सटीक संघ के लिए टाइप करें.

उदाहरण: एसडीके के माध्यम से प्राथमिकताएँ

const key = "docs.walkthrough.units"

try {
  await client.kv.get({ key })
} catch (error) {
  if ((error as { _tag?: string })._tag !== "NotFound") throw error   // first run: 404
}

const saved = await client.kv.set({ key, value: { units: "mm" } })
// saved: { key, value: { units: "mm" }, updatedAt: "2026-…" }

const { entries } = await client.kv.list({ prefix: "docs." })
await client.kv.remove({ key })   // { message: "…" }

कुंजियाँ 512 वर्णों तक सीमित हैं और उनमें गैर-व्हाट्सएप पाठ होना चाहिए; मान JSON-संगत होने चाहिए (कोई चक्र, फ़ंक्शन या गैर-परिमित संख्या नहीं)।

3डी में