@rewloy/node 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,75 @@ https://rewloy.com/gelistiriciler/degisiklikler
 
 This library's releases. The API's own changes are listed at the link above.
 
+## 0.2.1 (2026-10-05)
+
+Dışarıdan geliştiricilerin bulduğu üç sorun düzeltildi.
+
+Three problems found by outside developers, fixed.
+
+- **`Idempotency-Key` is checked before sending.** A key with non-ASCII
+  characters (`fiş-0042`) made `fetch` throw a bare `TypeError` about the header
+  value. Now the client refuses any key that is not printable ASCII
+  (0x21–0x7E), 8–64 characters, with a clear `TypeError` ("Idempotency-Key
+  yalnız ASCII karakterler içerebilir …") and sends nothing. The API will also
+  answer `400 VALIDATION` for such a key in its next release.
+- **`baseUrl` takes the address with or without `/v1`.** The documentation and
+  the OpenAPI document show `https://app.rewloy.com/v1`; the client wanted the
+  origin only. Now both work; a trailing `/v1` or `/v1/` and trailing slashes
+  are stripped (`rewloy.baseUrl` is the origin).
+- **`idempotencyKey` is required where the API requires it.** For `recordSale`,
+  `passAction`, `sendCampaign` and `refundShopRedemption` the OpenAPI document
+  marks the header required, but the client made up a random UUID when it was
+  missing, which does not survive a restart of your app. `idempotencyKey` is now
+  a required argument of those methods (a type error in TypeScript, a
+  `TypeError` before sending in JavaScript). Where the header is optional
+  (`issuePass`, …) a UUID is still generated and reused on every retry.
+  **Breaking for callers that relied on the generated key** (a small break,
+  taken in a patch release because the old behaviour could write a sale twice).
+
+## 0.2.0 (2026-10-05)
+
+Rewloy API 1.0.5'e göre yeniden üretildi: 255 işlem (0.1.0'da 237). Kasa için
+`recordSale` ve `reverseSale`; README'de yeni bir kasa örneği, test modu ve
+`baseUrl`.
+
+Regenerated from Rewloy API 1.0.5: 255 operations (237 in 0.1.0).
+
+- **New operations (18).**
+  - *Till:* `recordSale` (`POST /v1/passes/{serial}/sale`: write a completed
+    sale to a card; the card type decides what is written) and `reverseSale`
+    (`POST /v1/passes/{serial}/sale/reverse`: take a refunded sale back).
+  - *Checkout codes and shop connections:* `quoteCheckoutCode`,
+    `holdCheckoutCode`, `captureCheckoutOrder`, `releaseCheckoutOrder`,
+    `refundCheckoutOrder`, `listOrderRedemptions`, `listShopRedemptions`,
+    `releaseShopRedemption`, `refundShopRedemption`, `setShopSettings`,
+    `setShopCeiling`, `setShopPluginAbilities`, and for the card holder
+    `holderCheckoutCodes`, `mintHolderCheckoutCode`, `cancelHolderCheckoutCode`.
+  - `getMeta` (`GET /v1/meta`): the API's version.
+- **`getPass`** now also returns `programName`, `currency`, `stamps`
+  (`count`, `max`), `points`, `money` (`amountMinor`, `currency`), `customer`
+  (with `customers.read`), `actions` and `sale`.
+- **Webhooks.** `webhooks.manage` API keys manage webhooks (`createWebhook`,
+  `listWebhooks`, `getWebhook`, `setWebhookStatus`, `testWebhook`,
+  `listWebhookDeliveries`, `webhookEvents`); a webhook reports `createdByKey`.
+- **Other fields.** `issuePass` returns `created`; business lists and `me`
+  carry `currency`; programs carry `sale`; batches `onlineValue`; shops
+  `accepts`, `settings`, `shopName`, `unbacked` and the plugin key's
+  `abilities`.
+- **Generator.** A doc comment holding an unbalanced bracket no longer
+  breaks an object union such as the answer of `me`.
+- **README.**
+  - A till example with `recordSale`, the structured fields of `getPass` and
+    a refund with `reverseSale`.
+  - `Idempotency-Key`: a key is unique for good per credential. The
+    receipt number alone is not a key (fiscal receipt numbers restart after
+    the Z report): use register + Z number + receipt number, or a UUID
+    stored with the sale. The receipt number goes in `reference`.
+  - Test mode exists: `rwk_test_` keys and a test business. The "being
+    prepared" wording is gone.
+  - How to set a custom base URL (staging), and a link to the developer
+    docs, https://rewloy.com/gelistiriciler.
+
 ## 0.1.0 (2026-10-04)
 
 

package/README.md

@@ -13,15 +13,16 @@ kartı, kupon ve indirimdir:
 
 Kasada QR okutulur; bakiye, ödül ve kampanyalar kartın kendisinde güncellenir.
 Panelde yapılabilen her şey [Rewloy API v1](https://rewloy.com/gelistiriciler)
-ile de yapılabilir; bu kütüphane onu Node.js'ten kullanır:
+ile de yapılabilir; bu kütüphane onu Node.js'ten kullanır. Geliştirici
+belgeleri: **https://rewloy.com/gelistiriciler**.
 
 - **Tam tipli.** API'nin her işlemi, `operationId` adıyla bir metottur.
   Parametreler, gövdeler ve yanıtlar OpenAPI belgesinden
   ([`openapi.json`](https://app.rewloy.com/v1/openapi.json)) üretilen
   tiplerle gelir. CI belgeyi her gün okur ve değişince yeniden üretir.
 - **Bağımlılıksız.** Node 22 ve üstü; yerleşik `fetch` ve `node:crypto`.
-- **Güvenli tekrar.** Geçici hatalarda ölçülü yeniden deneme; kasa işleminde
-  ve kampanyada `Idempotency-Key`.
+- **Güvenli tekrar.** Geçici hatalarda ölçülü yeniden deneme; satışta, kasa
+  işleminde ve kampanyada `Idempotency-Key`.
 - **Ötesi:** sayfalama, canlı akış (SSE), webhook imzası doğrulama,
   kullanımdan kalkma uyarıları.
 
@@ -51,7 +52,7 @@ işlemin gerektirdikleriyle:
 - `query`: sorgu parametreleri;
 - `body`: JSON gövde;
 - `merchant`: `Rewloy-Merchant` başlığı;
-- `idempotencyKey`: `Idempotency-Key` başlığı (kasa işlemi ve kampanya);
+- `idempotencyKey`: `Idempotency-Key` başlığı (satış, kasa işlemi, kampanya ve mağaza iadesinde zorunlu);
 - `signal`, `timeoutMs`, `maxRetries`.
 
 Metot yanıttaki `data`yı döndürür. Sayfalı listelerde `{ data, meta }`,
@@ -85,12 +86,27 @@ Bir işlem istemcinin kimlik türünü kabul etmiyor ama kimliksiz de çalışı
 bir kimliği reddeder (`CREDENTIAL_NOT_ALLOWED`).
 
 Diğer seçenekler:
-- `baseUrl` (varsayılan `https://app.rewloy.com`);
+- `baseUrl` (varsayılan `https://app.rewloy.com`; sonuna `/v1` eklemeniz ya da eklememeniz fark etmez: `https://app.rewloy.com/v1` de olur, kütüphane `/v1`i kendisi ekler);
 - `timeoutMs` (60000);
 - `maxRetries` (2);
 - `fetch`: kendi `fetch`iniz;
 - `userAgent`: gönderilen `User-Agent`a eklenir, örneğin `"KasaPOS/4.2"`.
 
+### Başka bir adres (staging)
+
+API'nin başka bir kopyasına (kendi staging ortamınız ya da bir vekil sunucu)
+`baseUrl` ile bağlanılır:
+
+```ts
+const rewloy = new Rewloy({
+  apiKey: process.env.REWLOY_API_KEY!,
+  baseUrl: 'https://rewloy-staging.ornek.com',   // sonuna /v1 yazsanız da olur
+});
+```
+
+Gerçek müşterilere dokunmadan denemek için adres değiştirmeniz gerekmez:
+[test modu](#test-modu) aynı adreste, ayrı bir test ortamıyla çalışır.
+
 ## Kart vermek ve kasada işlem
 
 ```ts
@@ -101,16 +117,87 @@ const { serial, cardUrl } = await rewloy.issuePass({
 const sonuc = await rewloy.passAction({
   params: { serial },
   body: { action: 'earn-stamps', locationId, count: 1 },
-  idempotencyKey: `fis-${fisNo}`,
+  idempotencyKey: `kasa3-z0187-fis${fisNo}`,   // aşağıya bakın
+});
+if (sonuc.duplicate) console.log('Bu işlem zaten yazılmış');
+```
+
+### Satış: `recordSale`
+
+Kasa ya da kendi yazılımınız için en kolay yol `recordSale`dir: "bu satış
+oldu, sen yaz". Ödenen toplamı (kartın para biriminde, kuruş) gönderirsiniz;
+ne yazılacağına kartın türü ve programın kendi kuralı karar verir. Kartın
+türünü bilmeniz gerekmez.
+
+```ts
+const kart = await rewloy.getPass({ params: { serial } });
+// Kartın türüne özgü alanlar; `balance` yerine bunları okuyun.
+if (kart.stamps) console.log(`${kart.stamps.count} / ${kart.stamps.max} damga`);
+if (kart.points !== undefined) console.log(`${kart.points} puan`);
+if (kart.money) console.log(`${kart.money.amountMinor / 100} ${kart.money.currency}`);
+console.log(kart.programName, kart.customer?.name);   // customer: yalnız customers.read yetkisiyle
+
+// Fiş numarası anahtar olamaz: kasa + Z no + fiş no, ya da satışla saklanan bir UUID.
+const anahtar = `kasa3-z0187-fis${fisNo}`;
+const satis = await rewloy.recordSale({
+  params: { serial },
+  body: {
+    locationId,
+    amountMinor: 4550,           // 45,50: kartın para biriminde (`kart.currency`), kuruş
+    currency: kart.currency,     // isteğe bağlı güvence: uyuşmazsa 422 CURRENCY_MISMATCH
+    reference: `fis-${fisNo}`,   // fiş numarası buraya yazılır
+  },
+  idempotencyKey: anahtar,
+});
+if (satis.applied === 'none') console.log('Yazılan bir şey yok:', satis.reason);
+else console.log(`${satis.credited} ${satis.applied} yazıldı, bakiye ${satis.balance}`);
+if (satis.rewardReady) console.log('Ödül hazır');
+```
+
+`GET /v1/passes/{serial}` ayrıca `actions` (kartın aldığı kasa işlemleri ve
+şimdi yapılıp yapılamayacakları) ve `sale` (bir satışın bu kartta ne
+yazacağı) alanlarını verir.
+
+**İade.** `reverseSale` bir satışın karta yazdığını geri alır; satışı
+yazarken gönderdiğiniz anahtarla (`saleKey`) ya da `reference`la bulur:
+
+```ts
+const geri = await rewloy.reverseSale({
+  params: { serial },
+  body: { saleKey: anahtar, locationId },
 });
-if (sonuc.duplicate) console.log('Bu fiş zaten işlenmiş');
+console.log(geri.reversed, geri.applied, geri.balance, geri.duplicate);
 ```
 
-`passAction` ve `sendCampaign` bir `Idempotency-Key` ister. Verilmezse
+Bir satış bir kez geri alınır (tekrar `duplicate: true` döner). Kazanılan
+kullanılmışsa (ödüle ya da harcamaya gitmişse) `409 SALE_ALREADY_SPENT` gelir ve
+hiçbir şey yazılmaz.
+
+### `Idempotency-Key`
+
+`recordSale`, `passAction`, `sendCampaign` ve `refundShopRedemption` bir
+`Idempotency-Key` **ister**: API'nin tanımında (OpenAPI) bu başlık bu işlemlerde
+zorunludur, bu yüzden `idempotencyKey` bu metotlarda zorunlu bir argümandır.
+Verilmezse kütüphane istek göndermeden `TypeError` fırlatır; **sizin yerinize
+anahtar üretmez**. Üretilmiş rastgele bir anahtar yalnızca tek çağrının yeniden
+denemelerini korurdu: uygulama çöküp yeniden başlarsa yeni bir anahtar çıkar ve
+satış ikinci kez yazılabilirdi. Anahtarı kendiniz üretip satışla birlikte
+saklayın. Anahtar 8–64 karakterlik görünür ASCII olmalıdır (0x21–0x7E: harf,
+rakam ve noktalama; boşluk, Türkçe harf ya da `fiş` gibi ASCII dışı karakter
+olmaz); aksi halde kütüphane yine istek göndermeden `TypeError` fırlatır.
+Başlığın isteğe bağlı olduğu işlemlerde (örneğin `issuePass`) anahtar verilmezse
 kütüphane bir UUID üretir ve aynı çağrının her denemesinde aynısını gönderir.
-Kasada fiş numarası gibi kendi anahtarınızı vermek daha iyidir: uygulama
-çöküp yeniden başlasa bile aynı fiş ikinci kez işlenmez, aynı anahtarla tekrar
-ilk sonucu `duplicate: true` ile döndürür.
+
+- **Anahtar bir kimlik için kalıcı olarak tekildir** (8–64 karakter; defterden
+  hiç silinmez). Aynı anahtarla aynı isteğin tekrarı ikinci kez yazmaz ve
+  ilk sonucu `duplicate: true` ile döndürür. Aynı anahtar başka bir gövdeyle
+  `422 IDEMPOTENCY_KEY_REUSED` alır.
+- **Fiş numarası tek başına anahtar olamaz:** yazarkasa fiş numaraları Z
+  raporundan sonra yeniden başlar. Kasa + Z no + fiş no birleşimi
+  (`kasa3-z0187-fis0042`) ya da satışla birlikte saklanıp tekrarda yeniden
+  gönderilen bir UUID kullanın.
+- **Fiş numarası `reference` alanına** yazılır; müşterinin geçmişinde ve işlem
+  dökümünde görünür.
 
 ## Sayfalama
 
@@ -164,6 +251,22 @@ gösterilen sırla (`whsec_…`) doğrular:
 - `t` şimdiden 300 saniyeden (`toleranceSeconds`) uzaksa reddeder;
 - gövdeyi ayrıştırılmış olarak döndürür.
 
+Webhook'u panelden ya da API'den ekleyebilirsiniz. `webhooks.manage` yetkili
+bir API anahtarı `createWebhook`, `listWebhooks`, `getWebhook`,
+`setWebhookStatus`, `testWebhook` ve `listWebhookDeliveries`yi çağırabilir;
+`webhookEvents` abone olunabilecek olayları söyler. Sır (`secret`) yalnız
+`createWebhook` yanıtında gelir, saklayın:
+
+```ts
+const { webhook, secret } = await rewloy.createWebhook({
+  body: { url: 'https://ornek.com/rewloy/webhook', events: ['pass.activity', 'pass.voided'] },
+});
+await rewloy.testWebhook({ params: { id: webhook.id } });   // webhook.test olayı gönderir
+```
+
+Adres herkese açık bir `https` adresi olmalıdır (test ortamında da);
+yerelde bir tünel kullanın.
+
 Tutmazsa `WebhookSignatureError` atar: 400 ile yanıtlayın ve hiçbir işlem
 yapmayın. Gövde mutlaka ham olmalıdır. JSON olarak ayrıştırılıp yeniden yazılan
 bir gövde imzayı tutturmaz.
@@ -238,7 +341,7 @@ try {
   await rewloy.passAction({
     params: { serial },
     body: { action: 'spend', locationId, amountMinor: 5000 },
-    idempotencyKey: `fis-${fisNo}`,
+    idempotencyKey: `kasa3-z0187-fis${fisNo}`,
   });
 } catch (err) {
   if (err instanceof RateLimitError) console.log(`${err.retryAfter} saniye sonra yeniden deneyin`);
@@ -309,14 +412,35 @@ yanit.data;       // kampanya
 `data`, sayfalı listede `meta`, `status`, `headers`, `requestId`, `mode` ve
 `replayed`.
 
-`mode`, yanıtın `Rewloy-Mode` başlığıdır. Platformda test modu hazırlanıyor:
-gerçek mesaj göndermeyen, gerçek kart vermeyen test anahtarları. Geldiğinde
-test yanıtları bunu bu başlıkla söyleyecek. Başlık yoksa `null`. Canlı akışta
-aynı bilgi `akis.mode`dadır.
+`mode`, yanıtın `Rewloy-Mode` başlığıdır: `live` ya da `test`. Başlık yoksa
+`null`. Canlı akışta aynı bilgi `akis.mode`dadır.
 
 İşlem tablosu da dışa açıktır: `OPERATIONS.passAction` →
 `{ method, path, auth, merchant, idempotency, paged, stream, deprecated, … }`.
 
+## Test modu
+
+Gerçek müşterilere dokunmadan denemek için işletmenizin bir **test ortamı**
+vardır: ona bağlı ayrı bir işletme (adı "· Test" ile biter); kendi
+programları, müşterileri, kartları, anahtarları ve webhook'ları. Panel →
+Geliştirici → "Test ortamını aç" ya da `POST /v1/test/environment`. Orada
+oluşturulan anahtar `rwk_test_` ile başlar ve aynı adreste, aynı yollarla
+çalışır:
+
+```ts
+const rewloy = new Rewloy({ apiKey: process.env.REWLOY_TEST_KEY! });   // rwk_test_…
+const yanit = await rewloy.request('getPass', { params: { serial } });
+yanit.mode;   // 'test'
+```
+
+- Test ortamı hiçbir şey göndermez (e-posta, bildirim, SMS); kartlar
+  cüzdanlara eklenmez. Gönderilmeyenler `GET /v1/test/messages` ile okunur.
+- Webhook'lar teslim edilir ve `Rewloy-Test: 1` başlığıyla `"test": true`
+  taşır.
+- Gerçek müşteri verisini test ortamına girmeyin.
+
+Ayrıntı: https://rewloy.com/gelistiriciler#test-ortamı
+
 ## Geliştirme
 
 ```sh
@@ -369,7 +493,8 @@ Bir güvenlik açığı bulursanız [SECURITY.md](SECURITY.md) dosyasındaki yol
 > **Status: preview (0.x), published on npm. The API is stable; the
 > library's interface may change until 1.0.**
 
-The documentation of the API itself is in Turkish (links above). In short:
+The documentation of the API itself is in Turkish. Developer docs:
+**https://rewloy.com/gelistiriciler**. In short:
 
 - Every operation of the API is a method named by its `operationId`, typed
   from the OpenAPI document, which CI reads daily and regenerates from.
@@ -393,21 +518,46 @@ import { Rewloy } from '@rewloy/node';
 const rewloy = new Rewloy({ apiKey: process.env.REWLOY_API_KEY! });   // or { staffSession, merchant } or { holderSession }
 
 const { serial } = await rewloy.issuePass({ body: { programId, email, kvkkConsent: true } });
-const result = await rewloy.passAction({
+const sale = await rewloy.recordSale({
   params: { serial },
-  body: { action: 'earn-stamps', locationId },
-  idempotencyKey: `receipt-${receiptNo}`,   // generated when omitted, reused across retries
+  body: { locationId, amountMinor: 4550, reference: `receipt-${receiptNo}` },  // amount in the card's currency, minor units
+  idempotencyKey: `till3-z0187-r${receiptNo}`,
 });
 ```
 
+- **Till.** `recordSale` writes a completed sale to a card (the card type and
+  the programme's own rule decide what is written); `getPass` returns the
+  card's structured fields (`programName`, `currency`, `stamps`, `points`,
+  `money`, `customer`); `reverseSale` takes a refunded sale back:
+  `rewloy.reverseSale({ params: { serial }, body: { saleKey: key } })`.
+- **Idempotency keys.** `recordSale`, `passAction`, `sendCampaign` and
+  `refundShopRedemption` need an `Idempotency-Key`: the API's OpenAPI document
+  marks the header required for them, so `idempotencyKey` is a required
+  argument and the client throws a `TypeError` before sending if it is missing.
+  It never makes one up for you (a generated key would not survive a restart of
+  your app). The key must be 8–64 printable ASCII characters (0x21–0x7E); a
+  non-ASCII key such as `fiş-0042` is refused client-side, with a `TypeError`,
+  before anything is sent. Where the header is optional (for example
+  `issuePass`) the client still generates a UUID and reuses it on every retry
+  of the call. A key is unique **for good per credential**: do not use the
+  receipt number alone (fiscal receipt numbers restart after the Z report) but
+  register + Z number + receipt number, or a UUID stored with the sale. The
+  receipt number goes in `reference`.
+- **Base URL.** `new Rewloy({ apiKey, baseUrl: 'https://staging.example.com' })`
+  or `baseUrl: 'https://staging.example.com/v1'`: with or without a trailing
+  `/v1` (and trailing slashes), the client appends `/v1/...` itself. Default
+  `https://app.rewloy.com`.
+- **Test mode.** Open the test environment (panel → Developer, or
+  `POST /v1/test/environment`) and use its `rwk_test_` key at the same address:
+  a separate test business that sends nothing and never reaches real
+  customers. Webhooks are delivered with `Rewloy-Test: 1`.
 - **Arguments.** Each method takes one object: `params`, `query` and `body` as
   the operation needs, plus `merchant`, `idempotencyKey`, `signal`, `timeoutMs`
   and `maxRetries`.
 - **Results.** It resolves to the answer's `data`: `{ data, meta }` for paged
   lists, `undefined` for 204, a `Blob` for files.
 - **The whole answer.** `rewloy.request(id, args)` returns `status`,
-  `headers`, `requestId`, `mode` (the `Rewloy-Mode` header, for the coming
-  test mode) and `replayed` (`Idempotent-Replayed`).
+  `headers`, `requestId`, `mode` (the `Rewloy-Mode` header: `live` or `test`) and `replayed` (`Idempotent-Replayed`).
 - **Pagination.** `rewloy.paginate('listCustomers', args)` iterates the items
   of every page.
 - **Streams.** `rewloy.liveFeed({ signal })` (or `rewloy.stream('liveFeed',
@@ -451,3 +601,9 @@ const event = verifyWebhook({ payload: req.body, header: req.get('Rewloy-Signatu
 
 Report vulnerabilities privately, as [SECURITY.md](SECURITY.md) says.
 [MIT](LICENSE) licensed.
+
+## Yeni sürüm yayımlamak / Releasing
+
+`package.json`'daki sürümü ve CHANGELOG'u güncelleyin, commit'leyin, `v<sürüm>` etiketini gönderin (`git tag v0.2.0 && git push origin v0.2.0`). `release.yml` npm'e güvenilir yayıncı (trusted publishing) yoluyla, jetonsuz ve kaynak kanıtıyla (provenance) yayımlar.
+
+Bump the version in `package.json` and the changelog, commit, and push a `v<version>` tag. `release.yml` publishes to npm through trusted publishing: no token, with provenance.

package/dist/client.d.ts

@@ -60,6 +60,17 @@ type ItemOf<K extends PagedOperationId> = Operations[K]['data'] extends (infer T
 export declare function parseRetryAfter(value: string | null, now?: number): number | null;
 /** Exponential backoff with jitter for the retry after attempt `attempt` (0-based). */
 export declare function backoff(attempt: number, random?: () => number): number;
+/**
+ * The base URL without trailing slashes and without a trailing `/v1`: the
+ * paths of the operations carry `/v1` themselves, and the documentation shows
+ * the address both ways (`https://app.rewloy.com` and `https://app.rewloy.com/v1`).
+ */
+export declare function normalizeBaseUrl(url: string): string;
+/**
+ * An `Idempotency-Key` is 8–64 printable ASCII characters (0x21–0x7E): an HTTP
+ * header value cannot carry anything else, and `fetch` would throw a bare TypeError.
+ */
+export declare function checkIdempotencyKey(key: unknown): string;
 /**
  * A client of the Rewloy API (`https://app.rewloy.com/v1`).
  *

package/dist/client.js

@@ -56,6 +56,24 @@ export function backoff(attempt, random = Math.random) {
     const cap = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** attempt);
     return Math.round(cap / 2 + random() * (cap / 2));
 }
+/**
+ * The base URL without trailing slashes and without a trailing `/v1`: the
+ * paths of the operations carry `/v1` themselves, and the documentation shows
+ * the address both ways (`https://app.rewloy.com` and `https://app.rewloy.com/v1`).
+ */
+export function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, '').replace(/\/v1$/, '').replace(/\/+$/, '');
+}
+/**
+ * An `Idempotency-Key` is 8–64 printable ASCII characters (0x21–0x7E): an HTTP
+ * header value cannot carry anything else, and `fetch` would throw a bare TypeError.
+ */
+export function checkIdempotencyKey(key) {
+    if (typeof key !== 'string' || !/^[\x21-\x7e]{8,64}$/.test(key)) {
+        throw new TypeError('Rewloy: Idempotency-Key yalnız ASCII karakterler içerebilir (görünür karakterler, 8–64) / the Idempotency-Key must be printable ASCII (0x21–0x7E), 8–64 characters');
+    }
+    return key;
+}
 /** The URL a `Link` header gives for `rel="deprecation"` (else its first). */
 function deprecationLink(link) {
     if (!link)
@@ -135,7 +153,7 @@ export class Rewloy extends RewloyMethods {
         if (options.merchant !== undefined && which !== 'staffSession')
             throw new TypeError('Rewloy: `merchant` goes with a staffSession');
         this.merchant = options.merchant ?? null;
-        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
         this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
         const f = options.fetch ?? globalThis.fetch;
@@ -251,7 +269,7 @@ export class Rewloy extends RewloyMethods {
         const qs = query.toString();
         return `${this.baseUrl}${path}${qs ? `?${qs}` : ''}`;
     }
-    #headers(op, a, lastEventId) {
+    #headers(id, op, a, lastEventId) {
         const h = new Headers();
         h.set('accept', op.stream ? 'text/event-stream' : op.response === 'json' || op.response === 'raw-json' ? 'application/json' : '*/*');
         if (this.#userAgent)
@@ -264,15 +282,21 @@ export class Rewloy extends RewloyMethods {
         const merchant = a.merchant ?? (this.credential === 'staff' ? this.merchant : null);
         if (op.merchant && merchant)
             h.set('rewloy-merchant', merchant);
-        if (op.idempotency)
-            h.set('idempotency-key', a.idempotencyKey ?? randomUUID());
+        if (op.idempotency) {
+            if (a.idempotencyKey === undefined && op.idempotency === 'required') {
+                throw new TypeError(`Rewloy: ${id} needs idempotencyKey: Idempotency-Key gerekli, kütüphane uydurmaz (8–64 ASCII karakter) / the Idempotency-Key is required and is never generated for you (8–64 printable ASCII characters)`);
+            }
+            h.set('idempotency-key', a.idempotencyKey === undefined ? randomUUID() : checkIdempotencyKey(a.idempotencyKey));
+        }
         if (op.body)
             h.set('content-type', 'application/json');
         if (lastEventId)
             h.set('last-event-id', lastEventId);
-        for (const [k, v] of Object.entries(a.headers ?? {}))
-            if (v !== undefined && v !== null)
-                h.set(k, String(v));
+        for (const [k, v] of Object.entries(a.headers ?? {})) {
+            if (v === undefined || v === null)
+                continue;
+            h.set(k, k.toLowerCase() === 'idempotency-key' ? checkIdempotencyKey(v) : String(v));
+        }
         return h;
     }
     #notice(id, op, headers) {
@@ -290,7 +314,7 @@ export class Rewloy extends RewloyMethods {
     async #exchange(id, op, args, stream) {
         const a = args ?? {};
         const url = this.#url(id, op, a);
-        const headers = this.#headers(op, a, stream?.lastEventId);
+        const headers = this.#headers(id, op, a, stream?.lastEventId);
         const body = op.body ? JSON.stringify(a.body ?? {}) : undefined;
         const retryable = IDEMPOTENT_METHODS.has(op.method) || headers.has('idempotency-key');
         const maxRetries = Math.max(0, a.maxRetries ?? this.maxRetries);