# @azothos/sdk وواجهة v1 REST API

طريقان للدخول. أرسل الاستدعاءات عبر البوابة الخاضعة للحوكمة بأي عميل متوافق مع OpenAI — وهو المسار الذي تُطبَّق فيه القواعد وتُختم فيه القرارات — أو أبلِغ عن الاستدعاءات التي تجري في مكان آخر بمُغلِّفات SDK.

## التثبيت

```
npm install @azothos/sdk
```

الإصدار 18 من Node.js أو أحدث، ومفتاح API من **الإعدادات › الوصول** (`az_live_…` أو `az_test_…`). وتتحقق حزمة SDK من شكل المفتاح قبل أي طلب.

## عبر البوابة

وجّه عميل OpenAI إلى `https://www.azothos.ai/api/v1` — أو إلى مضيفك الخاص في الاستضافة الذاتية. تبني الدالة `azothGatewayHeaders` ترويسات Azoth وتطلق خطأً عند أي قيمة كانت البوابة سترفضها:

```
import OpenAI from 'openai';
import { azothGatewayHeaders } from '@azothos/sdk';

const openai = new OpenAI({
  baseURL: 'https://www.azothos.ai/api/v1',
  apiKey: process.env.AZOTH_API_KEY,
  defaultHeaders: azothGatewayHeaders({ usecaseId }),
});

await openai.chat.completions.create(body, {
  headers: azothGatewayHeaders({ decisionRef: creditFileId, subjectZone: 'FR' }),
});
```

- `X-Azoth-Usecase` — `usecaseId`: النظام (التفويض) الذي يخدمه الاستدعاء
- `X-Azoth-Decision-Ref` — `decisionRef`: القرار التجاري، بمعرّف مبهم
- `X-Azoth-Subject-Zone` — `subjectZone`: مكان الأشخاص المعنيين — `FR`، `US-CA`، `EU`…
- `X-Azoth-End-User` — `endUser`: زائر نظام عام، بمعرّف مبهم، وليس عنوان بريد إلكتروني أبدًا
- `X-Azoth-Challenge-Passed` — `challengePassed`: رمز nonce لتحدٍّ اجتازه الزائر
- `X-Azoth-Locale` — لغة الرفض: `en` أو `fr` أو `es` أو `zh` أو `ar`
- `X-Azoth-On-Behalf-Of` — الشخص الذي يُجرى الاستدعاء من أجله — معرّفه في SCIM أو بريده — بمفتاح خدمة مسموح له بتسمية الأشخاص؛ تضبطه بنفسك ([الإسناد البشري](https://www.azothos.ai/ar/docs/admin#attribution))

## الإيصالات

تقرأ الدالة `receiptOf(response | body | headers)` إيصالًا، و`decodeReceipt(token)` مطالباته، وتتحقق `verifyReceipt(token, jwks)` من توقيعه باستخدام WebCrypto. ومنذ SDK 1.2.0 ترفض أيضًا إيصالًا وُقّع عند لحظة الاختراق المعلَن لمفتاحه أو بعدها (حسب `status` و`compromised_at` للمفتاح): تُنشر مفاتيح مساحة العمل وحالتها على `/api/proof/keys/<workspaceId>`.

## حالات الرفض والإعفاءات

تقرأ الدالة `parseRefusal(err)` كتلة الرفض، وتعطي `formatRefusal` نصًا للعرض، و`alternativeRequest(option)` الترويسات والتغيير في الجسم لخيار ممتثل، وتطلب `requestException(…)` من مالك القاعدة إعفاءً محدود المدة. وعند تلقي 428، تعيد `exhaustionChallengeOf(err)` التحدي الواجب اجتيازه.

```
import { parseRefusal, formatRefusal, alternativeRequest, requestException } from '@azothos/sdk';

try {
  await openai.chat.completions.create(body, { headers: { 'X-Azoth-Locale': 'fr' } });
} catch (err) {
  const refusal = parseRefusal(err);
  if (!refusal) throw err;
  showToUser(formatRefusal(refusal));
  const option = refusal.alternatives[0];
  if (option) {
    const { headers, body: change } = alternativeRequest(option);
    await openai.chat.completions.create({ ...body, ...change }, { headers });   // governed again in full
  } else if (refusal.exception.available) {
    await requestException({
      apiKey: process.env.AZOTH_API_KEY,
      refusal,
      justification: 'Quarter-end audit needs this model this week',
    });
  }
}
```

## وفي SDK أيضًا

- `createClientVault`: احتفظ بمحتوى نظام في وضع الخزنة مشفّرًا بمفتاحك، في مخزنك؛ ولا يختم Azoth إلا البصمات.
- `groundingSources(passages)`: المقاطع التي يجب أن تستند إليها الإجابة، للتحقق من الاستناد.
- `runReferenceSet`: شغّل مجموعة حالات مرجعية محفوظة في خزنتك وأرسل إيصالها، للتحكم في تغيير النماذج.

## الإبلاغ عن الاستدعاءات التي تجري خارج البوابة

تغلّف الدوال `wrapOpenAI` و`wrapAnthropic` و`wrapBedrock` و`wrapMistral` و`wrapGemini` عميلك الحالي: يُبلَّغ Azoth بكل استدعاء — التكلفة، والزمن الكامن، والرموز — في الخلفية، مع امتدادات OpenTelemetry `gen_ai.*` اختيارية. وهذه الاستدعاءات مراقَبة لا خاضعة للحوكمة: لا يمكن لأي قاعدة إيقافها.

### wrapOpenAI

```
import OpenAI from 'openai';
import { AzothClient, wrapOpenAI } from '@azothos/sdk';

const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const openai = wrapOpenAI(new OpenAI(), azoth, {
  provider: 'openai',
  model: 'gpt-4o-mini',
  agentId: 'support-bot',        // the spend line it is attributed to
  workflowId: 'ticket-triage',
});
```

### wrapAnthropic

```
import Anthropic from '@anthropic-ai/sdk';
import { AzothClient, wrapAnthropic } from '@azothos/sdk';

const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const anthropic = wrapAnthropic(new Anthropic(), azoth);
```

### خيارات العميل

- `apiKey` — إلزامي: مفتاح API لمساحة العمل
- `baseUrl` — افتراضيًا `https://www.azothos.ai`؛ ومضيفك الخاص في الاستضافة الذاتية
- `workspaceId` — إلزامي لـ `client.io.*` وللمحاكاة
- `enableTracing · tracer` — إصدار امتدادات OpenTelemetry
- `timeoutMs` — لكل محاولة، 30 000 افتراضيًا
- `maxRetries` — إجمالي المحاولات عند 429 أو 5xx، 3 افتراضيًا؛ وتُحترم الترويسة `Retry-After` عند 429

## واجهة v1 REST API

تقبل معظم مسارات `/api/v1` مفتاح API: `Authorization: Bearer <key>` أو `X-Azoth-API-Key: <key>`. ولا يصل المفتاح ذو النطاقات إلا إلى المسارات التي تقابلها نطاقاته. أما قراءات لوحة التحكم نفسها — `/api/v1/me` وقراءات GreenOps — فتتطلب جلسة مسجّلة بدلًا من ذلك، ولا تقبل مفتاحًا أبدًا. وكل مسار، وطريقة مصادقته، وحقوله، وإجاباته موجودة في [مرجع واجهة API](https://www.azothos.ai/ar/docs/api)، المنشور أيضًا ملفًّا بصيغة OpenAPI.

- `POST /api/v1/chat/completions` — البوابة الخاضعة للحوكمة، متوافقة مع OpenAI
- `POST /api/v1/chat` — البوابة الخاضعة للحوكمة مع `provider` صريح، وبدائل احتياطية، وتدفق
- `POST /api/v1/infer/resume` — تنفيذ استدعاء محتجز بعد الموافقة عليه
- `GET /api/v1/journal` — القرارات المختومة
- `GET /api/v1/journal/export?format=dossier` — ملف التدقيق، بصيغة ZIP
- `POST /api/v1/decisions/export` — ملف قرار، حسب مرجع القرار
- `POST /api/v1/exceptions` — طلب إعفاء من رفض
- `POST /api/v1/insights/{tool}` — أدوات القراءة الخاصة بالمساعد، بالنطاق `insights:read`
- `POST /api/v1/mcp` — بوابة MCP الخاضعة للحوكمة، بمفتاح مرتبط بوكيل
- `GET /api/v1/usage · /api/v1/report · /api/v1/budgets` — الاستخدام، وتقرير النفقات، والميزانيات
- `POST /api/ingest` — الإبلاغ عن الاستدعاءات التي تجري خارج البوابة
- `GET /api/proof/keys/{workspaceId}` — المفاتيح العامة لمساحة العمل (JWKS)، دون مفتاح

```
POST /api/v1/chat
Authorization: Bearer <key>

{
  "provider": "anthropic",             // openai | anthropic | mistral | gemini | azure_openai
  "model": "claude-haiku-4-5",         // | openrouter | ollama | deepseek | huggingface | internal
  "messages": [{ "role": "user", "content": "Summarise this document." }],
  "maxTokens": 1024,
  "stream": false,
  "fallbackProviders": [{ "provider": "mistral", "model": "mistral-small-latest" }]
}
```

## الإجابات المتوقعة

- `400 validation_failed` — لم يجتز جسم الطلب التحقق من الصحة: يسمّي `field` الحقل، ويقول `error` السبب.
- `401` — مفتاح API مفقود أو غير صالح أو ملغى.
- `402 budget_exceeded` — رفضت ميزانيةٌ الاستدعاء قبل النموذج.
- `202 human_review_required` — محتجز بانتظار شخص؛ استأنفه بـ `approval_request_id` الخاص به.
- `403` — رفضته قاعدة: `policy_blocked`، `usecase_unresolved`، `usecase_not_approved`، `usecase_prohibited`، `usecase_archived`، `mandate_suspended`، `mandate_expired`، `kill_switch_active`، `jurisdiction_blocked`، `sovereignty_blocked`، `egress_blocked`…
- `428 exhaustion_challenge_required` — يطلب نظام عام من الزائر اجتياز تحدٍّ.
- `429` — حدّ للمعدل، أو `exhaustion_slow` أو `exhaustion_blocked`: الحقل `retryAfterMs` في الجسم، والترويسة `Retry-After` في الترويسات.
- `503 governance_error` — تعذّر تشغيل الحوكمة والنشر مغلق عند الفشل: أعد المحاولة.

> يُختم رفض الحوكمة ويحمل إيصاله. أما حالات رفض استنزاف التكاليف فتُحصى بدلًا من ذلك، وتُختم عند كل تغيير في المستوى. ويُشرح كل `code` في [رموز الأخطاء](https://www.azothos.ai/ar/docs/errors)، وهي الصفحة التي يقود إليها `doc_url` في الإجابة.
