@rewloy/node 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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

package/README.md

@@ -52,7 +52,7 @@ işlemin gerektirdikleriyle:
 - `query`: sorgu parametreleri;
 - `body`: JSON gövde;
 - `merchant`: `Rewloy-Merchant` başlığı;
-- `idempotencyKey`: `Idempotency-Key` başlığı (satış, 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 }`,
@@ -86,7 +86,7 @@ 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`; `/v1` olmadan, kütüphane ekler);
+- `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;
@@ -100,7 +100,7 @@ API'nin başka bir kopyasına (kendi staging ortamınız ya da bir vekil sunucu)
 ```ts
 const rewloy = new Rewloy({
   apiKey: process.env.REWLOY_API_KEY!,
-  baseUrl: 'https://rewloy-staging.ornek.com',   // /v1 olmadan
+  baseUrl: 'https://rewloy-staging.ornek.com',   // sonuna /v1 yazsanız da olur
 });
 ```
 
@@ -175,11 +175,19 @@ hiçbir şey yazılmaz.
 
 ### `Idempotency-Key`
 
-`recordSale`, `passAction` ve `sendCampaign` bir `Idempotency-Key` ister.
-Verilmezse kütüphane bir UUID üretir ve aynı çağrının her denemesinde aynısını
-gönderir; ama uygulama çöküp yeniden başlarsa yeni bir anahtar üretilir ve
-satış ikinci kez yazılabilir. Kasada anahtarı kendiniz üretip satışla birlikte
-saklayın:
+`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.
+
 - **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
@@ -522,14 +530,23 @@ const sale = await rewloy.recordSale({
   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` and `sendCampaign` need an
-  `Idempotency-Key`. A key is unique **for good per credential**: do not use the
+- **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`. A generated key only covers the retries
-  of one call, not a restart of your app.
+  receipt number goes in `reference`.
 - **Base URL.** `new Rewloy({ apiKey, baseUrl: 'https://staging.example.com' })`
-  (the origin, without `/v1`). Default `https://app.rewloy.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

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

package/dist/generated/types.d.ts

@@ -80,7 +80,7 @@ export interface IssuePassArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`: 8–64 printable ASCII characters. When omitted, the client generates a UUID and sends the same one on every retry of this call.
      */
     idempotencyKey?: string | undefined;
     /**
@@ -256,9 +256,9 @@ export interface PassActionArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`, required: 8–64 printable ASCII characters. The client never makes one up (a generated key would not survive a restart of your app); it sends this one on every retry of the call.
      */
-    idempotencyKey?: string | undefined;
+    idempotencyKey: string;
     /**
      * Ekip oturumu birden fazla işletmede koltuk taşıyorsa hangi işletme için olduğu (tek işletmede gerekmez).
      *
@@ -320,9 +320,9 @@ export interface RecordSaleArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`, required: 8–64 printable ASCII characters. The client never makes one up (a generated key would not survive a restart of your app); it sends this one on every retry of the call.
      */
-    idempotencyKey?: string | undefined;
+    idempotencyKey: string;
     /**
      * Ekip oturumu birden fazla işletmede koltuk taşıyorsa hangi işletme için olduğu (tek işletmede gerekmez).
      *
@@ -770,7 +770,7 @@ export interface HolderLoginArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`: 8–64 printable ASCII characters. When omitted, the client generates a UUID and sends the same one on every retry of this call.
      */
     idempotencyKey?: string | undefined;
 }
@@ -4114,9 +4114,9 @@ export interface SendCampaignArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`, required: 8–64 printable ASCII characters. The client never makes one up (a generated key would not survive a restart of your app); it sends this one on every retry of the call.
      */
-    idempotencyKey?: string | undefined;
+    idempotencyKey: string;
     /**
      * Ekip oturumu birden fazla işletmede koltuk taşıyorsa hangi işletme için olduğu (tek işletmede gerekmez).
      *
@@ -7738,9 +7738,9 @@ export interface RefundShopRedemptionArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`, required: 8–64 printable ASCII characters. The client never makes one up (a generated key would not survive a restart of your app); it sends this one on every retry of the call.
      */
-    idempotencyKey?: string | undefined;
+    idempotencyKey: string;
     /**
      * Ekip oturumu birden fazla işletmede koltuk taşıyorsa hangi işletme için olduğu (tek işletmede gerekmez).
      *
@@ -10122,7 +10122,7 @@ export interface AddHolderEmailArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`: 8–64 printable ASCII characters. When omitted, the client generates a UUID and sends the same one on every retry of this call.
      */
     idempotencyKey?: string | undefined;
 }
@@ -10169,7 +10169,7 @@ export interface AddHolderPhoneArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`: 8–64 printable ASCII characters. When omitted, the client generates a UUID and sends the same one on every retry of this call.
      */
     idempotencyKey?: string | undefined;
 }
@@ -10268,7 +10268,7 @@ export interface ReplaceHolderIdentityArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`: 8–64 printable ASCII characters. When omitted, the client generates a UUID and sends the same one on every retry of this call.
      */
     idempotencyKey?: string | undefined;
 }
@@ -10764,7 +10764,7 @@ export interface StartHolderRecoveryArgs extends RequestOptions {
     /**
      * Aynı işlemin iki kez yapılmasını önler: aynı anahtarla tekrar, ilk sonucu döndürür.
      *
-     * `Idempotency-Key`. When omitted, the client generates a UUID and sends the same one on every retry of this call.
+     * `Idempotency-Key`: 8–64 printable ASCII characters. When omitted, the client generates a UUID and sends the same one on every retry of this call.
      */
     idempotencyKey?: string | undefined;
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This library's version (package.json's; test/client.test.ts keeps them equal). */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** This library's version (package.json's; test/client.test.ts keeps them equal). */
-export const VERSION = '0.2.0';
+export const VERSION = '0.2.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rewloy/node",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Rewloy API için resmî Node.js ve TypeScript kütüphanesi / The official Node.js and TypeScript library for the Rewloy API",
   "license": "MIT",
   "author": "Rewloy",