<!-- Source: https://docs.infraio.xyz/tr/sdks/javascript -->
<!-- Last updated: 2026-10-04 -->

# 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. Henüz bir backend SDK'sı yok.
API'yi doğrudan çağırın; [Hızlı başlangıç](https://docs.infraio.xyz/tr/get-started/quickstart)
sayfası bir HMAC imzalama yardımcısı içerir.

- 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

> **Note:**
>
> **Sunucu tarafı giriş** yoktur. Webhook'lar için imza doğrulama
> yardımcıları pakete dahil değildir — bunları kendiniz `crypto` ile
> uygulayın ([imza doğrulama sayfası](https://docs.infraio.xyz/tr/webhooks/signature-verification)
> 4 dilde kopyala-yapıştır kodları içerir).

## Kurulum

**npm**

```bash
npm install @lartech/infraio-checkout-js
```

**pnpm**

```bash
pnpm add @lartech/infraio-checkout-js
```

**yarn**

```bash
yarn add @lartech/infraio-checkout-js
```

**bun**

```bash
bun add @lartech/infraio-checkout-js
```

**CDN**

```html
<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.

```ts
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",
});
```

| Param | Tip | Gerekli | Notlar |
| --- | --- | --- | --- |
| `publicKey` | `string` | ✓ | `pk_(live\|test)_…` ile eşleşmelidir |
| `options.checkoutUrl` | `string` | — | Temel checkout URL'sini geçersiz kıl. Varsayılan: `https://checkout.infraio.xyz`. Checkout sayfası eşleşen API'ye otomatik olarak bağlanır. |

## `sdk.checkout({ … })`

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

| Alan | Tip | Gerekli | Notlar |
| --- | --- | --- | --- |
| `sessionId` | `string` | ✓ | `POST /b2b/v1/checkout-sessions/quick` tarafından döndürülen `session_key` |
| `checkoutUrl` | `string` | — | Aynı uç nokta tarafından döndürülen tam URL. Atlanırsa, SDK bunu `loadInfraIo()`'nun `checkoutUrl`'sinden (veya varsayılandan) + `sessionId`'den oluşturur |
| `mode` | `"popup" \| "redirect" \| "embed"` | — | Varsayılan `"popup"` |
| `container` | `string \| HTMLElement` | yalnızca embed | iframe'in monte edileceği CSS selector veya DOM öğesi |
| `width` | `number` | — | Yalnızca popup. Varsayılan `560`. `[320, 1280]` aralığında kısıtlanır |
| `height` | `number` | — | Yalnızca popup. Varsayılan `780`. `[400, 1000]` aralığında kısıtlanır |
| `timeoutMs` | `number` | — | Yalnızca popup. iframe yükleme zaman aşımı. Varsayılan `30000`. Devre dışı bırakmak için `0` geçirin |
| `locale` | `string` | — | Checkout sayfasına `?locale=` olarak iletilen BCP-47 etiketi (`en`, `vi`, `ja`, `ko`, `es`, `pt-BR`, `ru`, `tr`, `zh-CN`, `zh-TW`) |
| `hideSummary` | `boolean` | — | Sipariş özeti sütununu gizler. Varsayılan `false` |
| `hideHeader` | `boolean` | — | InfraIO Pay başlığını ve yerleşik cüzdan-bağlama butonunu gizler. Varsayılan `false`. Tam white-label için `walletAddress` ile eşleştirin |
| `walletAddress` | `string` | — | Bir alıcı cüzdanını önceden bağla. `onSignRequest` gerektirir |
| `walletChainId` | `number` | — | Önceden bağlı cüzdan için EVM chain ID |
| `onReady` | `() => void` | — | iframe etkileşimli olduğunda tetiklenir. Yalnızca popup/embed |
| `onSignRequest` | `(req: { method: string; params: unknown[] }) => Promise<string>` | `walletAddress` ayarlandığında | SDK cüzdan RPC'lerini handler'ınıza proxy'ler; imzalı hex'i döndürün |
| `onSuccess` | `({ sessionId }) => void` | — | Başarılı ödemede tetiklenir. **Yetkili değildir — webhook yetkilidir** |
| `onCancel` | `() => void` | — | Alıcı popup/embed'i ödemeden kapattığında tetiklenir |
| `onError` | `(err: InfraIoError) => void` | — | iframe yükleme hatasında tetiklenir (popup + embed modları). Geçersiz argümanlar senkron olarak fırlatılır, burada **teslim edilmez**. Yönlendirme modunda runtime hata yüzeyi yoktur — başarısızlık yönlendirilen sayfada gözlenir. |

> **Warning:**
>
> `onSuccess` yetkili **değildir**. Webhook daha sonra ödemenin başarısız
> olduğunu tespit etse bile tetiklenebilir (testnet reorg'ları, alıcı
> tarafı zamanlama). Yalnızca UX için kullanın ("Teşekkürler!" göster,
> yönlendir). Karşılamadan önce her zaman webhook üzerinden onaylayın.

## `sdk.close()`

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

```ts
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.

> **Note:**
>
> Form `https://checkout.infraio.xyz/refund-request/:token` adresinde
> yaşar. Bu metod yalnızca o URL'yi bir popup / yönlendirme / gömme içine
> sarar, böylece alıcı asla alanınızdan ayrılmaz (popup / embed'de) veya
> otomatik olarak ona geri döner (yönlendirmede). Backend'inizin token'ı
> üretmek için vurduğu uç nokta
> `POST /b2b/v1/merchants/{merchant_id}/refund-requests`'tir — secret
> anahtarınızla HMAC ile imzalanır, B2B yüzeyinin geri kalanıyla aynı
> auth. Bkz. [Kavramlar → İadeler](https://docs.infraio.xyz/tr/concepts/refunds#mint-via-b2b-api).

```ts
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();
```

| Alan | Tip | Gerekli | Notlar |
| --- | --- | --- | --- |
| `token` | `string` | ✓ | `POST /b2b/v1/merchants/{merchant_id}/refund-requests` tarafından döndürülen `rfqt_…` token'ı |
| `mode` | `"popup" \| "redirect" \| "embed"` | — | Varsayılan `"popup"`. `sdk.checkout()` ile aynı yüzey semantiği — bkz. [Mod notları](#mode-notes) |
| `container` | `string \| HTMLElement` | yalnızca embed | iframe'in monte edileceği CSS selector veya DOM öğesi |
| `locale` | `string` | — | `?locale=` olarak iletilen BCP-47 etiketi (`en`, `vi`, `ja`, `ko`, `es`, `pt-BR`, `ru`, `tr`, `zh-CN`, `zh-TW`) |
| `hideHeader` | `boolean` | — | iframe içindeki InfraIO Pay başlığını gizler. Popup/embed'de SDK kendi modal kabuğunu çizer, bu yüzden sayfa başlığı genellikle gereksizdir. Varsayılan `false` |
| `hideSummary` | `boolean` | — | Sipariş Özeti sütununu gizler ve yalnızca iade formunu gösterir. Varsayılan `false` |
| `walletAddress` | `string` | — | Hedef cüzdan alanını önceden doldurur (`?wallet_address=`). Alıcının cüzdanını zaten bilen bir satıcının manuel yeniden yazımı atlamasını sağlar |
| `onSuccess` | `(data: { linkToken: string; refundId: string }) => void` | — | Alıcı formu gönderdikten sonra tetiklenir. `linkToken` → alıcıyla paylaşılacak `/r/:linkToken` durum sayfası. `refundId` → approve / reject için B2B API ile kullanın |
| `onCancel` | `() => void` | — | Alıcı popup/embed'i göndermeden kapattığında tetiklenir |
| `onError` | `(err: InfraIoError) => void` | — | iframe yükleme hatası veya geçersiz argümanlarda tetiklenir. Token süresinin dolması / iptali, `onError` üzerinden değil, barındırılan sayfa tarafından işlenir |

**`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ı).

> **Warning:**
>
> `openRefundRequest` iade niyetini kaydeder — fonları hareket ettirmez.
> `onSuccess` sonrasında iade satırı `PENDING`'dir (veya satıcı
> yapılandırmanız müşteri iadelerini otomatik onaylıyorsa `APPROVED`).
> Hâlâ satıcı cüzdanınızdan zincir üstü transferi imzalamanız ve yaymanız,
> ardından tx hash'i `POST /b2b/v1/refunds/:id/submit-tx`'a postlamanız
> gerekir. Tam yaşam döngüsü için bkz.
> [Kavramlar → İadeler](https://docs.infraio.xyz/tr/concepts/refunds).

## Hata sınıfı

```ts
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:

```ts
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.