JavaScript / Tarayıcı SDK’sı

@lartech/infraio-checkout-js bugün yayımladığımız tek SDK’dır. Tarayıcıda çalışır ve barındırılan checkout’umuzu açar. Backend SDK’ları (Node, Go, Python) yol haritasında; o zamana kadar doğrudan geçide konuşun — bir HMAC imzalama yardımcısı için Hızlı başlangıç sayfasına bakın.

• Mevcut sürüm: 0.1.1-beta.17 (1.0 öncesi; minor bozulmalar bekleyin)
• Formatlar: ESM (index.js), CJS (index.cjs), IIFE (index.global.js)
• Tipler dahil (index.d.ts)
• Sıfır runtime peer — React, jQuery veya başka bağımlılık yok

Kurulum

npm install @lartech/infraio-checkout-js

pnpm add @lartech/infraio-checkout-js

yarn add @lartech/infraio-checkout-js

bun add @lartech/infraio-checkout-js

<script src="https://unpkg.com/@lartech/infraio-checkout-js/dist/index.global.js"></script>
<script>
  const sdk = await InfraIo.loadInfraIo("pk_live_yourkeyhere");
  sdk.checkout({ sessionId, checkoutUrl });
</script>

loadInfraIo(publicKey, options?)

Bir Promise<InfraIoInstance> döndürür.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // Opsiyonel. Yalnızca prod olmayan bir ortama yönelirken geçersiz kılın.
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

Barındırılan checkout’u açar. void döndürür (durum için callback’leri kullanın).

sdk.close()

Açık bir popup’ı veya embed’i programatik olarak kapatın. Yönlendirme modu için no-op’tur.

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// daha sonra, örn. kullanıcı uzaklaştığında
sdk.close();

sdk.openRefundRequest({ … })

Backend’inizin POST /b2b/v1/merchants/{merchant_id}/refund-requests aracılığıyla ürettiği tek kullanımlık bir token için barındırılan iade-talep formunu açar. Alıcı iade hedef adresini + nedenini + (opsiyonel) metadata’yı bizim sayfamızda doldurur; sayfanız yalnızca açma/kapama yaşam döngüsünü yönetir. Bir close() fonksiyonu döndürür — popup’ı programatik olarak kapatmak veya embed iframe’ini ayırmak için onu çağırın. Yönlendirme modunda döndürülen fonksiyon bir no-op’tur.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// Token'ı sunucu tarafında üretin, ardından tarayıcıda SDK'ya verin.
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
const close = sdk.openRefundRequest({
  token,
  mode: "popup",
  onSuccess: ({ linkToken, refundId }) => {
    // Alıcı formu gönderdi.
    // linkToken → /r/:linkToken durum sayfası (alıcıyla paylaşın).
    // refundId  → approve / reject için B2B API ile kullanın.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* alıcı göndermeden kapattı */ },
});
 
// Gerekirse popup'ı programatik olarak daha sonra kapatın:
// close();

onError üzerinden yüzeye çıkan token durumları

Alıcı eski bir token açarsa, sayfanın kendisi gösterimi halleder (“Süresi doldu — yeni bağlantı talep et” uyarısı vb. render eder) ve SDK bu durumlar için onError tetiklemez — alıcı form akışının içindedir ve kodunuzun tepki vermesi gerekmez. onError yalnızca kodunuzun harekete geçebileceği şeyler için tetiklenir (hatalı argümanlar, iframe yüklerken ağ hatası).

Hata sınıfı

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* hatalı sessionId / args */ break;
      case "iframe_load_error":       /* iframe yüklenemedi */ break;
      case "iframe_timeout_error":    /* timeoutMs aşıldı */ break;
      case "already_open_error":      /* başka bir checkout zaten açık */ break;
      case "network_error":           /* checkout origin ile konuşurken geçici ağ sorunu */ break;
      case "api_error":               /* SDK tarafından yapılan bir çağrı için backend 2xx olmayan döndürdü */ break;
    }
  },
});

sdk.openRefundRequest() yalnızca invalid_request_error (eksik veya geçersiz token / args) fırlatır, senkron olarak. iframe_load_error (iade-talep iframe’i yüklenemedi) asenkron olarak onError üzerinden teslim edilir, fırlatılmaz. iframe_timeout_error veya already_open_error yaymaz — iade-talep popup’ının yükleme zaman aşımı yoktur ve birden fazla eşzamanlı popup’a izin verir.

Mod notları

Popup

• Koyu yarı saydam bir backdrop ile ortalanmış katman
• z-index: 2147483647 (max int32) — her şeyin üstüne oturur
• Açıkken gövde kaydırma kilitlenir; kapanışta geri yüklenir
• Kapatma butonu ilk odağı alır; Tab popup’ta tuzaklanır
• Şununla kapatılır: kapatma butonu, Escape, dışarıya tıklama, sdk.close(). Bunların tümü onCancel’ı çağırır
• Checkout sayfası postMessage üzerinden yeniden boyutlandırma talep edebilir — SDK width/height sınırları içinde kısıtlar

Yönlendirme

• window.location.href üzerinden sert navigasyon
• Otomatik olarak ?return_url=<current-page> ekler, böylece alıcı geldiği yere geri döner. Oturumdaki success_url / cancel_url’niz bunu zaten kapsıyorsa, gidiş-dönüş return_url’yi yok sayar

Gömme

• allow="payment; clipboard-write" ile iframe (HTML5 Feature Policy direktifleri — sandbox özelliği değil). iframe checkout origin’inden sunulur, bu yüzden cüzdan popup’ları ve alıcı tarafından panoya yazma daha fazla opt-in olmadan çalışır.
• Konteyner genişliği %100; yükseklik INFRAIO_RESIZE postMessage üzerinden otomatik boyutlanır, [200, 2000]px aralığında kısıtlanır
• iframe sınırı ötesinde CSS izolasyonu yoktur — üst sayfa stilleriniz içeri sızmaz
• Checkout etkileşimli olduğunda kendi yükleme durumunuzu gizleyebilmek için her zaman onReady’yi bağlayın

TypeScript

Tüm tipler pakete dahildir. En kullanışlı export’lar:

import type {
  CheckoutOptions,
  RefundRequestOptions,
  LoadOptions,
  InfraIoInstance,
  InfraIoErrorCode,
} from "@lartech/infraio-checkout-js";
import { loadInfraIo, InfraIoError, VERSION } from "@lartech/infraio-checkout-js";

VERSION, SDK’nın kendi sürüm string’idir — hata raporlarında yararlıdır.

Sırada ne var

• React / Vue framework sarmalayıcıları — saf JS yüzeyi pilot satıcılar arasında stabilleştikten sonraki lansman-sonrası iterasyon için planlandı. Saf SDK bugün React içinde sorunsuz çalışıyor; sarmalayıcılar yalnızca manuel useRef + yaşam döngüsü kablolamasını kaldıracak.
• Sekmeler arası oturum devamı — checkout’u A sekmesinde aç, B sekmesinde bitir. Bir alıcının akış ortasında bir magic-link takip ettiği durumlarda kullanışlı. Bir sonraki minor sürüm için izleniyor.
• CSS değişkenleri üzerinden temalama — iframe üzerinde küçük bir tasarım token kümesi (yarıçap, vurgu rengi) sunmak, böylece satıcılar sayfayı fork etmeden markalarına uydurabilir.
• Sunucu tarafı yardımcılar — backend kodunun HMAC ritüelini kopyalamasına gerek kalmayacak şekilde verifyWebhook() + signedRequest() sunan küçük bir @lartech/infraio-server paketi. Yayımlanana kadar, imza doğrulama sayfası TypeScript, Go, Python ve Ruby için drop-in implementasyonları listeler.