TypeScript üçün SDK

Bir fayl, heç bir asılılıq yoxdur. Node 18+ və müasir brauzerlərdə işləyir (daxili fetch, FormData, Web Crypto). Versiya 1.11.0 (fayldakı SDK_VERSION sabiti). Klientdə hər API əməliyyatı üçün metod var.

Quraşdırma

grem.ts faylını yükləyin və layihənizə əlavə edin. npm paketi yoxdur.

Sürətli başlanğıc

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);

Standart baza ünvanı https://developers.grem.capital/api/v1-dir (baseUrl parametri). Açarı kabinetdə yaradın: API → Açarlar.

Tapşırıqlar

Hər tapşırıq cavabında jobId var (API 1.6.0+). jobs.wait statusu (pulsuz) state dəyəri completed, partial, failed və ya action_required olana qədər sorğulayır. Uğursuz sorğu (şəbəkə, 5xx, 429) onu dayandırmır: o, ardıcıl 5 uğursuzluğa qədər sorğulamağa davam edir:

const job = await grem.text.generate({ city: 'Berlin', totalArea: 64, language: 'en' });
const done = await grem.jobs.wait('text/generate', job.jobId);
if (done.state === 'failed') throw new Error('generation failed');

Hesabat yoxlaması təsdiq gözləyir:

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);

Klientdə nələr var

Fayllı alətlər FormData qəbul edir - onu necə dolduracağınız hər alətin səhifəsində təsvir olunub.

Sandbox

Test açarı ilə simulate parametri hər simulyasiya olunan çağırışın nəticəsini seçir (Sandbox):

const grem = new GremClient({ apiKey: process.env.GREM_TEST_KEY, simulate: 'failed' });

Canlı açarla simulate parametri klient yaradılarkən xəta atır: çağırış real şəkildə icra olunardı.

Sorğular standart olaraq 5 dəqiqəyə qədər gözləyir (timeoutMs): aləti işə salmaq bir dəqiqədən çox çəkə bilər, vaxtından əvvəl imtina etmək isə nə işi, nə də onun ödənişini dayandırır.

Klient rədd edilmiş çağırışı Retry-After müddətindən sonra maxRetries dəfəyə qədər təkrarlayır (standart 3, ən çoxu 10; 0 təkrarları söndürür): 429 - həmişə, çünki limitə düşən çağırış emal olunmayıb; 503 - oxumalar üçün, yazmalar üçün isə yalnız Idempotency-Key ötürdükdə, çünki 503 yan təsirdən sonra gələ bilər. 30 saniyədən uzun Retry-After gözlənilmir: xəta dərhal atılır. Sizin AbortSignal da fasiləni ləğv edir. Həmin signal dəyərini request() metoduna ötürün. Retry-After olmadan fasilələr 1, 2, 4 ... saniyədir. Yükləmə (uploads.images) 503 sonrası təkrarlanmır (429 sonrası təkrarlanır: yükləmə emal olunmayıb). Ötürdüyünüz signal sorğunun vaxt aşımını (timeoutMs) əvəz edir. 1.8.0 versiyasından klient eyni Idempotency-Key ilə çağırışı şəbəkə qırılmasından və ya sorğunun vaxt aşımından sonra, 502, 504, 524 sonrası (iş bitmiş ola bilər - təkrar onu ikinci ödəniş olmadan qaytarır) və 409 idempotency_conflict sonrası (ilk çağırış hələ icra olunur) da təkrarlayır: təxminən 1, 2, 4 ... saniyəlik fasilələrlə, ən çoxu 30, cəmi retryWindowMs müddətindən çox olmamaqla (standart 10 dəqiqə). Açarsız yazmalar (yükləmələr, vebhukların idarə edilməsi) qırılmadan sonra təkrarlanmır. maxRetries: 0 bütün təkrarları söndürür.

Uzun çağırışlar

valuation.express və valuation.rent 30-150 saniyə çəkə bilər, ~100 saniyə ərzində başlamayan cavab isə 524 ilə kəsilir. respondAsync parametri ilə klient Prefer: respond-async göndərir, dərhal tapşırıq alır və onu sorğulayır (pulsuz); metod sinxron çağırışdakı eyni nəticəni qaytarır, uğursuz tapşırıq isə GremError atır:

const grem = new GremClient({ apiKey, respondAsync: true });         // all long calls
const est = await grem.valuation.express(input);                     // same result
await grem.valuation.rent(input, undefined, { respondAsync: true }); // or per call

Özünüz sorğulamaq üçün: grem.jobs.result('valuation/express', jobId) (və ya jobs.get / jobs.wait), yaxud express.completed / express.failed və rent.completed / rent.failed hadisələrinə abunə olun.

1.9.0 versiyasından floorplan.create və valuation.review də eyni parametri qəbul edir: onların yüklənən faylı tapşırıq yaranmazdan əvvəl emal olunur (böyük sənəd üçün bir dəqiqə və ya daha çox). respondAsync ilə fayllar bir dəfə yüklənir, server dərhal sorğu tapşırığı ilə cavab verir və metod parametrsiz haldakı eyni Job obyektini qaytarır (yoxlama action_required vəziyyətində qayıdır - sonra confirmReview). Xidmətin yenidən başladılması ilə kəsilən sorğu tapşırığı (code: interrupted, ödəniş tutulmur) eyni forma və eyni Idempotency-Key ilə ən çoxu iki dəfə yenidən göndərilir.

const plan = await grem.floorplan.create(form, undefined, { respondAsync: true });

1.10.0 versiyasından respondAsync seçimini draft.extract də qəbul edir: metod sinxron çağırışla eyni qaralamanı qaytarır. 1.11.0 versiyasından bu seçimi site.create də qəbul edir.

Xətalar

4xx və ya 5xx cavabı status, title, detail, code, errors, requestId və retryAfter (429 və 503 üçün) sahələri olan GremError atır:

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);
}

Təhlükəsiz təkrarlar

Aləti işə salan və ya qeyd yaradan metodların son arqumenti Idempotency-Key-dir:

await grem.pdf.create({ pdfName: 'Presentation', objectId, language: 'ENG' }, crypto.randomUUID());

uploads.images də açar qəbul edir, lakin API onu nəzərə almır: təkrar yükləmə faylları yenidən saxlayır.

1.8.0 versiyasından API-nin idempotent etdiyi hər POST (alətlər, ekspress qiymətləndirmə, obyektlər, lidlər, Swipe Match hadisələri) açar alır - sizin və ya klientin yaratdığı açar - və çağırışın bütün təkrarları ondan istifadə edir: əlaqə qırılsa belə, ödənişli alət üçün ödəniş bir dəfə tutulur. Çağırışı sonra özünüz təkrarlaya bilmək üçün (məsələn, prosesiniz yenidən başladıqdan sonra) öz açarınızı ötürün; GremError.idempotencyKey çağırışın istifadə etdiyi açarı saxlayır.

Vebhuklar

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);
});

Çat

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, 'Hello!');
stop.abort(); // when you no longer need the stream
await streaming;

Üçüncü arqument olmadan sendMessage təsadüfi clientMessageId göndərir (Node 18 də daxil olmaqla). Mesajı təhlükəsiz təkrarlamaq üçün öz identifikatorunuzu ötürün və ondan yenidən istifadə edin: eyni identifikatora bir dəfə cavab verilir və bir dəfə ödəniş tutulur.

Əlaqəli

• Sürətli başlanğıc
• Tapşırıqlar və nəticələr
• Xətalar