ثلاث حزم SDK رسمية: TypeScript وPython وPHP بدل curl الخام

يمكن الوصول إلى الـ API عبر curl أو fetch الخام: فالعقد بسيط، ترويسة واحدة X-Api-Key وJSON ذهابًا وإيابًا. لكن عندما يتجاوز عدد نقاط النهاية 865، وتحتوي أجسام الطلبات على عشرات الحقول، فإن العميل ذا الأنواع يوفّر ساعات: إكمال تلقائي للمسارات، وأنواع للطلب والاستجابة، وإعادة محاولة تلقائية على الشبكات غير المستقرة.

لذلك لدينا ثلاث حزم SDK رسمية مولَّدة من عقد OpenAPI 3.1 واحد.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

الاستدعاء نفسه لخريطة الميلاد بثلاث لغات.

TypeScript: غلاف رفيع فوق openapi-fetch (نحو 6 KB وقت التشغيل)، مع إكمال تلقائي للمسارات:

import { Astroway } from '@astroway/sdk';

const aw = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const { data: chart } = await aw.client.POST('/chart', {
  body: {
    date: '1990-07-14',
    time: '14:30:00',
    timezoneOffset: 3,
    latitude: 50.4501,
    longitude: 30.5234,
    houseSystem: 'P',
  },
});

// aw.client.POST is the raw typed fetch, so `chart` is the { ok, data } envelope
console.log(chart.data.houses.ascendant);  // 212.0952574979425

Python: الصنف المتزامن Astroway وغير المتزامن AsyncAstroway بواجهة متطابقة، فوق httpx:

from astroway import Astroway

aw = Astroway(api_key=os.environ['ASTROWAY_API_KEY'])

chart = aw.post('/chart', body={
    'date': '1990-07-14',
    'time': '14:30:00',
    'timezoneOffset': 3,
    'latitude': 50.4501,
    'longitude': 30.5234,
    'houseSystem': 'P',
})

print(chart['houses']['ascendant'])

PHP: فوق Guzzle 7 وPSR-18:

<?php
use Astroway\Astroway;

$aw = new Astroway(['apiKey' => getenv('ASTROWAY_API_KEY')]);

$chart = $aw->post('/chart', body: [
    'date'           => '1990-07-14',
    'time'           => '14:30:00',
    'timezoneOffset' => 3,
    'latitude'       => 50.4501,
    'longitude'      => 30.5234,
    'houseSystem'    => 'P',
]);

echo $chart['houses']['ascendant'];

ثلاث لغات مختلفة، لكن الضمانات نفسها، لأن الثلاث مولَّدة من عقد OpenAPI نفسه:

• أنواع الطلب والاستجابة لجميع نقاط النهاية. تمنحك TS إكمالًا تلقائيًا للمسارات وأجسامًا ذات أنواع؛ وPython حزمة typed وفق PEP 561؛ وPHP تواقيع ذات أنواع. بيئة التطوير تقترح الحقول بدل التوثيق في تبويب مجاور.
• إعادة محاولة مدمجة مع backoff عند 408 و409 و429 و5xx. عطل شبكة مؤقت أو rate-limit لا يُسقط كودك: العميل يعيد المحاولة بنفسه.
• تسلسل أخطاء بأسلوب Stainless. الأخطاء مصنّفة بأصناف ذات أنواع، لا مجرد نص في catch. تلتقط نوعًا محددًا مثل RateLimitError أو ValidationError وتعالجه بدقة.
• OpenAPI 3.1 مصدرًا. أضفنا نقطة نهاية إلى الـ API، فتظهر في SDK مع الإصدار التالي دون تكرار يدوي.
• OIDC وإثبات منشأ SLSA عند النشر: TS وPHP عبر Trusted Publisher / auto-mirror، وPython عبر Trusted Publisher OIDC على PyPI. سلسلة التوريد قابلة للتحقق.

عنوان Base URL في الجميع هو https://api.astroway.info/v1/، ويُمرَّر المفتاح في الترويسة X-Api-Key. إنه المفتاح نفسه المستخدم لاستدعاءات HTTP الخام؛ SDK لا يغيّر شيئًا في التفويض.

فوق حزم SDK الأساسية الثلاث توجد تكاملات جاهزة لبيئات محددة:

• @astroway/react: خطافات (hooks) لتطبيقات React
• astroway/sdk-symfony: حزمة bundle لـ Symfony
• astroway/sdk-laravel: حزمة لـ Laravel

قيد العمل ولم تُنشر بعد: Go وRuby وRust. صفحاتها موجودة بالفعل في كتالوج SDK مع معاينة لأمر التثبيت؛ وعندما تصدر الحزمة في السجل، تتغير حالتها إلى “متاحة”.

1. احصل على مفتاح من dashboard/sign-up: 10 000 رصيد شهريًا مجانًا
2. ثبّت SDK بلغتك (الأوامر أعلاه)
3. أول استدعاء: خريطة الميلاد من المقتطف أعلاه، ضع مفتاحك في ASTROWAY_API_KEY

القائمة الكاملة لحزم SDK مع أمثلة لكل منها في صفحة SDK.