TypeScript SDK

Tek dosya, bağımlılık yok. Node 18+ ve modern tarayıcılarda çalışır (yerleşik fetch, FormData, Web Crypto). Sürüm 1.7.2 (dosyadaki SDK_VERSION sabiti). İstemcide her API işlemi için bir yöntem vardır.

Kurulum

grem.ts dosyasını indirin ve projenize koyun. npm paketi yoktur.

Hızlı başlangıç

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

Varsayılan temel adres https://developers.grem.capital/api/v1 (baseUrl seçeneği). Panelde bir anahtar oluşturun: API → Anahtarlar.

İşler

Her iş yanıtı jobId içerir (API 1.6.0+). jobs.wait, state değeri completed, partial, failed veya action_required olana kadar durumu (ücretsiz) sorgular. Başarısız bir sorgu (ağ, 5xx, 429) onu durdurmaz: üst üste en fazla 5 hataya kadar sorgulamaya devam eder:

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

Rapor incelemesi onay bekler:

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

İstemcide neler var

Dosyalı araçlar FormData alır: nasıl doldurulacağı her aracın sayfasında açıklanmıştır.

Sandbox

Test anahtarıyla simulate seçeneği her simüle edilen çağrının sonucunu belirler (Sandbox):

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

Gerçek bir anahtarla simulate seçeneği istemci oluşturulurken hata fırlatır: çağrı gerçekten çalışırdı.

İstekler varsayılan olarak 5 dakikaya kadar bekler (timeoutMs): bir aracı başlatmak bir dakikadan uzun sürebilir ve erken vazgeçmek ne işi ne de ücretini durdurur.

İstemci reddedilen bir çağrıyı Retry-After sonrasında maxRetries kez tekrarlar (varsayılan 3, en fazla 10; 0 tekrarları kapatır): 429 her zaman, çünkü limiti aşan çağrı işlenmemiştir; 503 okumalarda, yazmalarda ise yalnızca bir Idempotency-Key verdiğinizde, çünkü 503 bir yan etkiden sonra gelebilir. 30 saniyeden uzun bir Retry-After beklenmez: hata hemen fırlatılır. AbortSignal'ınız beklemeyi de iptal eder. Bu signal değerini request() çağrısına verin. Retry-After yoksa beklemeler 1, 2, 4 ... saniyedir. Yükleme (uploads.images) 503 sonrasında tekrarlanmaz (429 sonrasında tekrarlanır: yükleme işlenmemiştir). Verdiğiniz signal, istek zaman aşımının (timeoutMs) yerini alır.

Hatalar

4xx veya 5xx yanıtı status, title, detail, code, errors, requestId ve retryAfter (429 ve 503 için) içeren bir GremError fırlatı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);
}

Güvenli tekrarlar

Bir araç başlatan veya kayıt oluşturan yöntemlerin son argümanı Idempotency-Key değeridir:

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

uploads.images da bir anahtar alır, ancak API bunu yok sayar: tekrarlanan yükleme dosyaları yeniden kaydeder.

Webhook'lar

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

Sohbet

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

Üçüncü argüman olmadan sendMessage rastgele bir clientMessageId gönderir (Node 18'de de). Bir mesajı güvenle tekrarlamak için kendi kimliğinizi verin ve yeniden kullanın: aynı kimlik bir kez yanıtlanır ve bir kez ücretlendirilir.

İlgili makaleler

• Hızlı başlangıç
• İşler ve sonuçlar
• Hatalar