SDK لـ Node.js

تغلّف أداة SDK الرسمية لـ Node.js واجهة Sofia API v1 في صنف واحد هو Sofia: طريقة لكل مسار، وطلبات وردود مُنمَّطة، ونوع خطأ واحد لكل فشل. لا تعتمد على أي حزم أخرى وتعمل على Node.js 20 أو أحدث.

التثبيت

تُنشر الـ SDK على npm باسم الحزمة @sofia-post/node. وتعمل مع import وrequire على السواء.

npm install @sofia-post/node

بداية سريعة

أنشئ عميلًا بمفتاحك، وابحث عن المنشأة التي تريد النشر لها، ثم جدول منشورًا على Instagram:

import { Sofia } from '@sofia-post/node';

const sofia = new Sofia(process.env.SOFIA_API_KEY);

const [establishment] = await sofia.establishments();

const post = await sofia.post({
  establishmentId: establishment.id,
  targets: [{ platform: 'instagram', text: 'Tarte tatin du jour 🍎' }],
  scheduledAt: new Date('2026-12-01T09:00:00Z'),
});

console.log(post.id, post.status);

المصادقة

يأخذ المُنشئ مفتاحًا شخصيًا تنشئه في الإعدادات › API، تبويب الوصول الشخصي، أو رمز وصول OAuth إذا كان تطبيقك يعمل باسم مستخدمين آخرين في Sofia (OAuth2). ترسله الـ SDK بالشكل Authorization: Bearer … مع كل طلب.

يتصل العميل بـ https://api.sofia-post.com افتراضيًا. الوسيط الثاني يغيّر عنوان URL الأساسي، أو دالة fetch التي يرسل بها الطلبات:

const sofia = new Sofia(apiKey, { baseUrl: 'http://localhost:3008' });

الطرق

المنشورات

لكل منشور هدف واحد لكل شبكة، ولكل هدف نصه ووسائطه وصيغته. افحصه أولًا بـ dryRun: لا يُكتب شيء، ويسرد الرفض كل قاعدة يخالفها. مرّر idempotencyKey حتى لا يؤدي طلب مُعاد إلى النشر مرتين. يقبل scheduledAt قيمة Date أو سلسلة ISO 8601.

import type { PublishPostInput } from '@sofia-post/node';

const input: PublishPostInput = {
  establishmentId,
  targets: [
    { platform: 'instagram', text: 'Menu du jour', media: [{ id: media.id }] },
    { platform: 'facebook', text: 'Menu du jour : tarte tatin et café' },
  ],
};

await sofia.post(input, { dryRun: true });
await sofia.post(input, { idempotencyKey: crypto.randomUUID() });

الوسائط

ارفع الملف مرة واحدة، ثم ضع id الخاص به في media المنشور. تقبل upload كائن Buffer أو Uint8Array أو Blob، وتقرأ نوع المحتوى من اسم الملف ما لم تمرّر contentType. أما uploadFromUrl فتتيح لـ Sofia تنزيل الملف بنفسها.

import { readFile } from 'node:fs/promises';

const media = await sofia.upload({
  establishmentId,
  file: await readFile('tarte-tatin.jpg'),
  fileName: 'tarte-tatin.jpg',
});

const imported = await sofia.uploadFromUrl({ establishmentId, url: 'https://example.com/menu.png' });

الترقيم

تردّ postList وmediaList بصفحة واحدة في كل مرة. مرّر nextCursor الخاص بصفحة على أنه cursor في الاستدعاء التالي؛ والصفحة الأخيرة لا تحتويه.

let cursor: string | undefined;
do {
  const page = await sofia.postList({ establishmentId, status: 'published', limit: 100, cursor });
  page.data.forEach((post) => console.log(post.id));
  cursor = page.nextCursor;
} while (cursor);

الأخطاء

تُطلق كل طريقة SofiaApiError عندما ترفض الواجهة الاستدعاء. يحمل الخطأ status الخاص بـ HTTP، وcode الثابت من غلاف الأخطاء، وdetails (وفي المنشور المرفوض: كل قاعدة شبكة يخالفها)، وrequestId لتسليمه إلى الدعم، وعند 429 القيمة retryAfterSeconds.

import { SofiaApiError } from '@sofia-post/node';

try {
  await sofia.post(input);
} catch (error) {
  if (!(error instanceof SofiaApiError)) throw error;
  if (error.code === 'post_refused') console.log(error.details);
  if (error.status === 429) await wait(error.retryAfterSeconds);
}

إذا تعذّر الوصول إلى الواجهة تمامًا، يكون رمز الخطأ network_error والحالة 0. لا تعيد الـ SDK المحاولة من تلقاء نفسها: انتظر retryAfterSeconds عند 429، وباعد بين المحاولات عند 5xx.

TypeScript

تأتي الحزمة بأنواعها: تُصدَّر PublishPostInput وPost وMedia وSocialAccount وEstablishmentInsights وغيرها بجانب Sofia، فيُكمل محررك كل حقل وكل قيمة تعداد.

بعد ذلك: يصف مرجع API كل مسار تستدعيه الـ SDK، وتدير أداة CLI الواجهة نفسها من الطرفية.