استخدام TypeScript API من Narwhal مع Node.js

يمكنك استخدام Node.js وTypeScript مع Narwhal لسحب الإجازات الرسمية ومواعيد الإصدار والبيانات الاقتصادية وأسعار السلع الفورية وأسعار الصرف واحتمالات أسواق التنبؤ. استخدم fetch العادية مع مفتاح API، ثم جدول البرنامج النصي بـ cron أو بمهمة مجدولة على المضيف.

ما الذي ستعدّه

يوفّر Node.js بيئة JavaScript لبرنامج نصي يستدعي Narwhal REST API ويقرأ استجابات JSON. ستحصل على وحدة ES تضم دالة مساعدة مشتركة للطلبات واستدعاءات لجميع مجالات البيانات الستة. يستخدم Narwhal حسابًا واحدًا ومفتاح API واحدًا لجميع واجهات البيانات، ويتشارك REST وMCP المفتاح نفسه. يستخدم البرنامج النصي هنا REST، مع قراءة المفتاح من متغير بيئة.

اضبط مفتاح API الخاص بك

  1. أنشئ مفتاحًا مجانيًا احصل على مفتاح API مجاني من صفحة التسجيل. يوثّق المفتاح نفسه طلبات كل مجال بيانات في هذا البرنامج النصي.
  2. تخزين المفتاح في ملف بيئة ضع المفتاح في ملف .env تحت الاسم NARWHAL_API_KEY. استبدل YOUR_KEY بمفتاحك؛ يقرأ البرنامج النصي القيمة عبر process.env.NARWHAL_API_KEY.
    ملف البيئة
    NARWHAL_API_KEY=YOUR_KEY
  3. استخدام وحدة ES وإصدار Node المناسب احفظ البرنامج النصي باسم pull.mjs. يتوفر fetch عامًا في Node 18.17 أو أحدث، لذا لا يحتاج استدعاء REST إلى أي حزمة. ويتطلب تحميل ملف .env عبر node --env-file=.env pull.mjs الإصدار Node 20.6 أو أحدث.

ترويسة الطلب هي Authorization: Bearer YOUR_KEY. في البرنامج النصي تأخذ الترويسة قيمتها من متغير البيئة، ويبقى عنوان URL الأساسي https://api.narwhalapi.com. يستخدم كل استدعاء الترويسة نفسها عبر الدالة المساعدة المشتركة.

اسحب البيانات بالكود

احفظ هذه الشيفرة في pull.mjs. تبني الدالة المساعدة get عنوان URL من العنوان الأساسي والمسار، وتضيف معلمات الاستعلام الممررة، وترسل طلب GET باستخدام fetch. وإذا لم تنجح الاستجابة فإنها ترمي خطأً يتضمن الحالة ونص الاستجابة، وإلا فتعيد استجابة JSON ليقرأها الكود المستدعي.

أبقِ الدالة المساعدة واستدعاءات المجالات في وحدة ES نفسها، مع تعريف العنوان الأساسي والترويسة قبل الطلبات. كائن المعلمات يخص كل استدعاء: فاستدعاء التقويم يوفّر مرشحات الدولة والتاريخ، واستدعاء CPI يوفّر فترة البداية، واستدعاء FX يوفّر العملات.

Node، ستة مجالات
const API = "https://api.narwhalapi.com";
const headers = { Authorization: `Bearer ${process.env.NARWHAL_API_KEY}` };

async function get(path, params = {}) {
  const url = new URL(API + path);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

const { holidays } = await get("/v1/calendars/holidays/USA/2026");
const { releases } = await get("/v1/economics/calendar", {
  countries: "USA",
  start_date: "2026-11-01",
  end_date: "2026-11-30",
  limit: 100,
});
const { observations } = await get("/v1/economics/USA/cpi/observations", {
  start: "2025-09",
});
const { price } = await get("/v1/commodities/spot/BRENT/USD");
const { rates } = await get("/v1/fx/rates/USD", { currencies: "EUR,IDR" });
const { meetings } = await get("/v1/predictions/policy-paths/federal-reserve");

console.log(holidays.length, holidays[0].name);
console.log(releases.length, observations.at(-1));
console.log(
  "Brent",
  price,
  Object.fromEntries(rates.map((rate) => [rate.currency, rate.rate])),
);
console.log(meetings[0].resolves_at.slice(0, 10), meetings[0].p_hold);

شغّل node --env-file=.env pull.mjs لتحميل المفتاح واستدعاء API. تستخرج الاستدعاءات حقول الاستجابة التي تستخدمها عبارات الإخراج. وفي أسعار الصرف يحوّل البرنامج النصي إدخالات العملة والسعر المُعادة إلى كائن، وفي استجابة التوقعات يقرأ تاريخ الاجتماع واحتمال الإبقاء على الفائدة. وتستخدم عيّنات المجالات التالية الدالة get والترويسة نفسيهما.

جدولة السحب

استخدم cron أو مهمة مجدولة على المضيف. ففي cron يتضمن الأمر مسار ملف البيئة ومسار pull.mjs، فيحصل البرنامج النصي المجدول على المفتاح في process.env.NARWHAL_API_KEY. ويظل الخيار --env-file يتطلب Node 20.6 أو أحدث حتى عند جدولة الأمر.

إدخال cron
0 7 * * * node --env-file=/path/.env /path/pull.mjs

استبدل /path/.env و/path/pull.mjs بمسارات ملفاتك. وللمزيد عن جدولة الطلب راجع جدولة سحب يومي للبيانات.

الإجازات الرسمية في Node.js

اطلب الإجازات الرسمية في الولايات المتحدة لعام 2026 واقرأ المصفوفة holidays. لكل إجازة date وname؛ وتطبع العيّنة طول المصفوفة واسم أول إجازة. في 24 أكتوبر 2026 احتوت الاستجابة على 11 إجازة رسمية أمريكية لعام 2026. لاستخدام التاريخ في مخرجاتك اقرأ date من عنصر الإجازة. ويوفّر الحقل name اسم الإجازة المرتبط بذلك التاريخ.

قراءة الإجازات الرسمية
const { holidays } = await get(
  "/v1/calendars/holidays/USA/2026"
);
console.log(holidays.length, holidays[0].name);

مواعيد الإصدار في Node.js

اطلب التقويم الاقتصادي للولايات المتحدة لنافذة نوفمبر 2026 واقرأ releases. لكل عنصر at وperiod وtopic وstatus، فتقرأ تاريخ الإصدار مع موضوعه وفترته. في 24 أكتوبر 2026 احتوت نافذة نوفمبر 2026 هذه على 31 إصدارًا. مرشحات التاريخ تخص طلب التقويم، أما الحقل period فيخص كل عنصر إصدار. اقرأ الموضوع والحالة من العنصر نفسه عندما تحتاجهما في مخرجاتك.

قراءة مواعيد الإصدار
const { releases } = await get("/v1/economics/calendar", {
  countries: "USA", start_date: "2026-11-01", end_date: "2026-11-30", limit: 100
});
console.log(releases.length);

البيانات الاقتصادية في Node.js

اطلب ملاحظات CPI للولايات المتحدة مع المعلمة start واقرأ observations. لكل ملاحظة period وvalue، وتقرأ العيّنة آخر عنصر في المصفوفة المُعادة. في 24 أكتوبر 2026 كانت قيمة CPI لفترة 2026-09 تساوي 336.940. تشمل البيانات الاقتصادية في Narwhal أيضًا التضخم والناتج المحلي الإجمالي (GDP) والعوائد. احتفظ بالفترة مع القيمة عند قراءة الملاحظة، حتى تبيّن مخرجاتك أي فترة CPI تنتمي إليها القيمة. وتُمرَّر فترة بداية الطلب معلمةَ استعلام.

اقرأ ملاحظات CPI
const { observations } = await get(
  "/v1/economics/USA/cpi/observations", { start: "2025-09" }
);
console.log(observations.at(-1));

الأسعار الفورية للسلع في Node.js

اطلب Brent بالدولار الأمريكي (USD) واقرأ حقل الاستجابة price. في 24 أكتوبر 2026 كان سعر Brent 116.8809 دولارًا للبرميل. تشمل رموز الأسعار الفورية على سبيل المثال XAU وXAG وXPT وXPD وXCU وBRENT وWTI. تُبقي هذه العيّنة BRENT وUSD في مسار الطلب. ويقرأ الكود هنا حقل price واحدًا من استجابة JSON. رمز السلعة والعملة جزءان من عنوان URL الممرَّر إلى الدالة المساعدة المشتركة للطلبات.

قراءة سعر Brent الفوري
const { price } = await get(
  "/v1/commodities/spot/BRENT/USD"
);
console.log("Brent", price);

أسعار الصرف في Node.js

اطلب EUR وIDR مع USD أساسًا واقرأ rates. لكل عنصر currency وrate، والأسعار العشرية نصوص. في 24 أكتوبر 2026 كان USD/EUR يساوي 0.89342 وUSD/IDR يساوي 18107.8. تستخدم العيّنة كل عملة خاصية في كائن لسعرها المُعاد. العملات المطلوبة معلمات استعلام، أما العملة الأساسية فجزء من المسار. اقرأ حقل العملة مع كل سعر عند استخدام المصفوفة المُعادة مباشرةً.

اقرأ أسعار الصرف
const { rates } = await get(
  "/v1/fx/rates/USD", { currencies: "EUR,IDR" }
);
console.log(Object.fromEntries(rates.map((rate) => [rate.currency, rate.rate])));

احتمالات أسواق التنبؤ في Node.js

اطلب مسار سياسة الاحتياطي الفيدرالي واقرأ meetings. لكل اجتماع resolves_at وp_cut وp_hold وp_hike. في 24 أكتوبر 2026 كان احتمال الإبقاء على الفائدة في اجتماع 28 أكتوبر 2026 يساوي 0.9188. تطبع العيّنة التاريخ من عنصر الاجتماع الأول مع احتمال الإبقاء. استخدم p_cut أو p_hike من عنصر الاجتماع عندما تريد احتمال الخفض أو الرفع. واحتفظ بـ resolves_at مع الاحتمال لتحديد الاجتماع الذي يصفه.

قراءة احتمالات الاجتماع
const { meetings } = await get(
  "/v1/predictions/policy-paths/federal-reserve"
);
console.log(meetings[0].resolves_at.slice(0, 10), meetings[0].p_hold);

هل أحتاج إلى أنواع TypeScript؟

اكتب أنواع حقول الاستجابة التي تقرؤها فقط. في مثال FX يكون شكل الاستجابة { rates: { currency: string; rate: string }[] }. القيم العشرية نصوص، لذا استخدم string للحقل rate في شكل TypeScript.

لماذا يوجد await في المستوى الأعلى؟

تسمح وحدات ES باستخدام await في المستوى الأعلى، وبهذه الطريقة تنتظر العيّنة كل استدعاء get. استخدم الامتداد .mjs الموضح هنا، أو اضبط "type": "module" لوحدة JavaScript من نوع ES.

نُشر في .

الخطوات التالية