دليل البدء السريع لـ SDK: TypeScript و Python

تقدم Ody حزم SDK رسمية لـ TypeScript و Python تغطي واجهة REST API بالكامل — جهات الاتصال، المحادثات، الرسائل (مع عمليات إرسال متطابقة)، مكالمات الذكاء الاصطناعي الصادرة، البحث عن الأرقام وشرائها، تسجيل 10DLC، وكيل الذكاء الاصطناعي الخاص بك، وإدارة الويب هوكس، بالإضافة إلى مدقق توقيع Standard-Webhooks مدمج.

قبل أن تبدأ

• تحتاج إلى مفتاح API — انظر احصل على مفتاح Ody API الخاص بك. استخدم مفتاح ody_test_… أثناء التطوير لكي تتم محاكاة عمليات الإرسال (الإنشاء بأمان باستخدام وضع الاختبار).
• لم يتم نشر أي من الحزمتين في سجل بعد. قم بتثبيت كليهما من دليل sdks/ في مستودع ody-platform؛ بمجرد نشرهما، سيكونان @ody/sdk (npm) و ody-sdk (PyPI).

TypeScript (@ody/sdk)

يتطلب Node 18+ (يعمل أيضًا في المتصفحات، Deno، و Bun — يستخدم fetch العامة وليس لديه أي تبعيات وقت التشغيل). قم بالبناء والتثبيت من المستودع:

cd ody-platform/sdks/typescript
npm run build   # emits dist/
npm install /path/to/ody-platform/sdks/typescript   # from your project

import { Ody, OdyError } from "@ody/sdk";

const ody = new Ody(process.env.ODY_API_KEY!);

// Contacts — create, search, and auto-paginate (follows nextCursor for you)
const contact = await ody.contacts.create({ firstName: "Ada", phone: "+15125550123" });
for await (const c of ody.contacts.listAll()) console.log(c.id, c.firstName);

// Conversations
const open = await ody.conversations.list({ status: "open" });
await ody.conversations.setStatus(open.conversations[0].id, "done");

// Send an SMS — idempotent, safe to retry with the same key for 24h
const sent = await ody.messages.send({
  to: "+15125550123",
  body: "Your order shipped!",
  idempotencyKey: "order-1042-shipped",
});

// Errors are typed
try {
  await ody.contacts.get("00000000-0000-0000-0000-000000000000");
} catch (err) {
  if (err instanceof OdyError) console.error(err.code, err.status, err.requestId);
}

Python (ody-sdk)

يتطلب Python ≥ 3.9، المكتبة القياسية فقط. قم بالتثبيت من المستودع:

pip install /path/to/ody-platform/sdks/python
# or for development: pip install -e sdks/python

from ody import Ody, OdyError

client = Ody("ody_live_...")

# Contacts — create, search, and auto-paginate
contact = client.contacts.create(first_name="Ada", phone="+15125550123")
for c in client.contacts.list_all():
    print(c["id"], c["firstName"])

# Send an SMS — idempotent, safe to retry with the same key for 24h
sent = client.messages.send(
    to="+15125550123",
    body="Your order shipped!",
    idempotency_key="order-1042-shipped",
)

# Errors are typed
try:
    client.contacts.get("00000000-0000-0000-0000-000000000000")
except OdyError as err:
    print(err.code, err.status, err.request_id)

ما تغطيه كلتا حزمتي SDK

المجموعة	الأساليب
جهات الاتصال	list, listAll/list_all, create, get, update, delete
المحادثات	list, listAll/list_all, get, setStatus/set_status
الرسائل	send (with idempotency key), search
المكالمات	list, place (outbound AI call)
الأرقام	list, searchAvailable/search_available, buy (with idempotency key), connectAgent/connect_agent, disconnectAgent/disconnect_agent
المراسلة (10DLC)	status, register, refresh
الوكيل	get, update, publish
الويب هوكس	list, create, get, update, delete, rotate, test, deliveries, eventTypes/event_types

تتضمن كلتا الحزمتين أيضًا مدقق توقيع الويب هوك — verifyWebhookSignature (TypeScript، خوادم Node فقط) و verify_webhook_signature (Python) — مع مقارنة بوقت ثابت وحماية من إعادة التشغيل لمدة 5 دقائق. مرر بايتات النص الأساسي الخام، وليس JSON المحلل. انظر استقبال الويب هوكس والتحقق من التوقيعات للتدفق الكامل.

تغطي أساليب الأرقام، المراسلة، الوكيل، و calls.place (على سبيل المثال ody.numbers.searchAvailable، ody.numbers.buy، ody.messaging.register، ody.agent.update، ody.agent.publish، ody.calls.place — بصيغة snake_case في Python) نفس سطح خط الهاتف مثل REST API. انظر شراء الأرقام وتسجيل الرسائل النصية عبر API و إجراء مكالمات الذكاء الاصطناعي وإدارة Astra عبر API.

عند حدوث خطأ 429، تُظهر كلتا حزمتي SDK قيمة Retry-After (err.retryAfter / err.retry_after) — احترمها، وفقًا لـ حدود معدل API وأفضل الممارسات.

مقالات ذات صلة

• نظرة عامة على API والمصادقة
• استقبال الويب هوكس والتحقق من التوقيعات
• التقسيم، التماثل، ومعالجة الأخطاء
• الإنشاء بأمان باستخدام وضع الاختبار

---