ملف واحد بلا تبعيات. يعمل في Node 18+ والمتصفحات الحديثة (fetch وFormData وWeb Crypto المدمجة). الإصدار 1.7.2 (الثابت SDK_VERSION في الملف). في العميل دالة لكل عملية في API.
التثبيت
نزّل grem.ts وضعه في مشروعك. لا توجد حزمة npm.
بداية سريعة
import { GremClient } from './grem';
const grem = new GremClient({ apiKey: process.env.GREM_API_KEY });
const { estimate } = await grem.valuation.express({
propertyCategory: 'apartment',
addressText: 'Torstraße 12, Berlin',
totalArea: 64,
});
console.log(estimate.pricePoint, estimate.currency);
العنوان الأساسي الافتراضي https://developers.grem.capital/api/v1 (الخيار baseUrl). أنشئ مفتاحا في لوحة التحكم: API → المفاتيح.
المهام
كل رد مهمة يحتوي على jobId (API 1.6.0+). jobs.wait يستعلم عن الحالة (مجانا) حتى تصبح state هي completed أو partial أو failed أو action_required. ولا يوقفه استعلام فاشل (الشبكة، 5xx، 429): يواصل الاستعلام حتى 5 إخفاقات متتالية:
const job = await grem.text.generate({ city: 'Berlin', totalArea: 64, language: 'ar' });
const done = await grem.jobs.wait('text/generate', job.jobId);
if (done.state === 'failed') throw new Error('generation failed');
مراجعة التقرير تنتظر التأكيد:
const form = new FormData();
form.append('file', pdfBlob, 'report.pdf');
const review = await grem.valuation.review(form);
await grem.valuation.confirmReview(review.jobId);
const result = await grem.jobs.wait('valuation/review', review.jobId);
ما في العميل
| المجموعة | الدوال |
|---|---|
| المفتاح | ping()، me() |
| التقييم | valuation.express، valuation.report، valuation.rent، valuation.review، valuation.confirmReview |
| المحتوى | content.generate، text.generate، video.create، video.music، video.endings، avatar.video، avatar.list |
| المواد | site.create، pdf.create، flyer.create، draft.extract، photo.enhance، floorplan.create |
| المراجع | voices()، toolsStatus()، works()، dictionaries() |
| المهام والملفات | jobs.get، jobs.wait، artifact(path, { range, signal })، uploads.images |
| العقارات | objects.list، get، create، update، delete، setAgency، setAssignee |
| العملاء المحتملون | leads.list، get، create، update، delete، matches، claim، returnToPool |
| Swipe Match | match.list، get، events، sendEvent |
| Webhooks | webhooks.list، create، update، delete، test، deliveries، resend |
| المحادثة | chat.createSession، listSessions، updateSession، deleteSession، sendMessage، history، stream |
الأدوات التي تأخذ ملفات تقبل FormData: طريقة ملئه موصوفة في صفحة كل أداة.
بيئة الاختبار
مع مفتاح الاختبار يحدد الخيار simulate نتيجة كل استدعاء محاكى (بيئة الاختبار):
const grem = new GremClient({ apiKey: process.env.GREM_TEST_KEY, simulate: 'failed' });
مع مفتاح حقيقي يرمي الخيار simulate خطأ عند إنشاء العميل: فالاستدعاء كان سيُنفذ فعلا.
تنتظر الطلبات افتراضيا حتى 5 دقائق (timeoutMs): قد يستغرق تشغيل أداة أكثر من دقيقة، والتوقف المبكر لا يوقف العمل ولا خصمه.
يعيد العميل الاستدعاء المرفوض بعد Retry-After، حتى maxRetries مرات (الافتراضي 3 والحد الأقصى 10؛ و0 يوقف الإعادة): 429 دائما، لأن الاستدعاء الذي تجاوز الحد لم يُعالج؛ و503 للقراءة، وللكتابة فقط إذا مررت Idempotency-Key، لأن 503 قد يأتي بعد أثر جانبي. لا ينتظر العميل Retry-After أطول من 30 ثانية: يُطلق الخطأ فورا. وAbortSignal الخاص بك يلغي الانتظار أيضا. مرّر هذا signal إلى request(). ومن دون Retry-After تكون فترات الانتظار 1 ثم 2 ثم 4 ... ثوانٍ. ولا يُعاد الرفع (uploads.images) بعد 503 (ويُعاد بعد 429 لأن الرفع لم يُعالج). وsignal الذي تمرره يحل محل مهلة الطلب (timeoutMs).
الأخطاء
الرد 4xx أو 5xx يرمي GremError يحتوي status وtitle وdetail وcode وerrors وrequestId وretryAfter (لـ 429 و503):
import { GremError } from './grem';
try {
await grem.text.generate({});
} catch (e) {
if (e instanceof GremError) console.error(e.status, e.title, e.code, e.detail);
}
الإعادة الآمنة
آخر وسيط في الدوال التي تشغل أداة أو تنشئ سجلا هو Idempotency-Key:
await grem.pdf.create({ pdfName: 'عرض تقديمي', objectId, language: 'ARB' }, crypto.randomUUID());
uploads.images يقبل مفتاحا أيضا، لكن API يتجاهله: الرفع المتكرر يحفظ الملفات مرة أخرى.
Webhooks
import { verifyWebhookSignature } from './grem';
app.post('/grem-hook', express.raw({ type: 'application/json' }), async (req, res) => {
const raw = req.body.toString('utf8');
const ok = await verifyWebhookSignature(process.env.GREM_WEBHOOK_SECRET, req.get('x-grem-signature'), raw);
if (!ok) return res.status(400).send('invalid signature');
const event = JSON.parse(raw);
res.sendStatus(200);
});
المحادثة
const session = await grem.chat.createSession();
const stop = new AbortController();
const streaming = grem.chat
.stream(session.sessionId, (data) => console.log(data), stop.signal)
.catch((e) => { if (e.name !== 'AbortError') throw e; }); // stop.abort() rejects with AbortError
await grem.chat.sendMessage(session.sessionId, 'مرحبا!');
stop.abort(); // when you no longer need the stream
await streaming;
دون الوسيط الثالث يرسل sendMessage قيمة clientMessageId عشوائية (وفي Node 18 أيضا). لإعادة رسالة بأمان مرّر معرّفك وأعد استخدامه: يُجاب على المعرّف نفسه ويُخصم مرة واحدة.