TypeScript SDK - Conare

تغلّف conare الواجهة البرمجية لـ Node 18 أو أحدث وBun، دون أي تبعيات.

npm install conare

import { Conare } from "conare";

const conare = new Conare(); // reads CONARE_API_KEY
const docs = conare.namespace("docs");

await docs.add({ text: "Refunds are available for 30 days." });
const results = await docs.query("how do refunds work?");

Result

[
  {
    "id": "doc_HmsFWqbQQc2mY03FhVZE",
    "text": "Refunds are available for 30 days.",
    "score": 0.3192,
    "reranked": true,
    "metadata": {}
  }
]

حقول الاستجابة بصيغة camelCase، والطوابع الزمنية من نوع Date.

الخيارات

new Conare({
  apiKey: "sk-conare-...",           // default: CONARE_API_KEY
  baseURL: "https://api.conare.ai",  // default: CONARE_BASE_URL
  timeout: 60_000,                   // ms per attempt
  maxRetries: 2,
  organization: "org_...",           // for a multi-organization key
});

تقبل كل دالة أيضًا { signal, timeout, idempotencyKey } كوسيط أخير.

الدوال

الدالة	تُرجع
`conare.namespace(name)`	مقبض لمساحة أسماء؛ لا يُرسل شيء حتى تستدعي دالة
`conare.namespaces({ prefix })`	`[{ name, documents, embeddingModel, rerankModel }]`
`ns.add(docs)`	المعرّفات
`ns.write(docs)`	`[{ id, version, result, chunks, chunksEmbedded }]`
`ns.query(query, { topK, filter, rerank, rerankDepth, retrievers, user, userPrefix, excludeIds, hops })`	`[{ id, text, score, reranked, metadata }]`
`ns.queryPages(query, { maxResults, ... })`	مكرِّر غير متزامن للصفحات
`ns.get(id)`	المستند، أو `null`
`ns.list({ limit })`	مكرِّر غير متزامن على كل المستندات
`ns.delete(id)`	لا شيء
`ns.deleteMany(ids)`، `ns.deleteWhere(filter)`	عدد المحذوفات
`ns.create({ embeddingModel })`	`{ embeddingModel }`
`ns.drop({ force })`	`{ sourcesDeleted }`
`ns.uploadFile(file, name, { id, type, user, metadata, pages, password, layout, wait })`	الرفع، ونصّه بصيغة Markdown عندما يصبح `ready`
`ns.getFile(fileId, { user })`	آخر رفع للملف
`conare.parse(file or { url }, { name, type, pages, password, layout, wait })`	Markdown الخاص بالملف، دون تخزين أي شيء
`conare.getParse(id)`	تحليل أجاب بـ `parsing`
`conare.embed(texts, { type, outputDtype })`	المتجهات؛ ومع `int8`، `{ values, scales }` (تعيدها `dequantize` كما كانت)
`conare.rerank(query, documents, { topK })`	`[{ index, score, document }]`، مع `unscored`
`conare.sources`	`connect`، `create`، `list`، `get`، `sync`، `update`، `delete`، `types`
`conare.organizations()`	المؤسسات التي يعمل المفتاح نيابةً عنها
`conare.users.delete(user)`، `deletePrefix(prefix)`	العملية التي تحذف بيانات مستخدم
`conare.events.list({ cursor, types })`	ما الذي تغيّر، بالترتيب

تقبل add وwrite مستندًا واحدًا أو مصفوفة بأي حجم، وترسل 100 في كل مرة.
البحث في كل مساحات الأسماء (POST /query) وanswer ليس لهما دالة بعد: استدعهما عبر HTTP.

الأخطاء

كل فشل يرمي ConareError يحتوي على status وcode وmessage وrequestId.

import { ConareError } from "conare";

try {
  await docs.add({ text: "" });
} catch (err) {
  if (err instanceof ConareError) console.log(err.status, err.code); // 400 "invalid_request"
}

الحالة	السلوك
لا توجد استجابة	قيمة `status` هي `0`، و`code` هو `timeout` أو `connection_error`
`429` و`5xx` وأخطاء الشبكة	يُعاد المحاولة حتى `maxRetries` مرة، بعد `Retry-After` أو فترة تراجع
عمليات الكتابة	تحمل `Idempotency-Key`، فلا تكتب إعادة المحاولة مرتين أبدًا