@lonca/trendyol 0.11.0 → 0.11.1

package/README.md

@@ -8,35 +8,38 @@
 
 Type-safe TypeScript SDK for the [Trendyol Marketplace API](https://developers.trendyol.com).
 
-> **`0.6.0` — Trendyol surface complete.** 14 resources, ~70 typed methods, plus a `parseWebhookEvent` helper for inbound event handling. Every endpoint a non-AutoFT non-V1 seller can hit is covered.
+> [!IMPORTANT]
+> **Unofficial.** This is an independent, community-maintained SDK. It is not affiliated with, endorsed by, or supported by Trendyol. "Trendyol" and related names are trademarks of their respective owners.
+
+> **Trendyol surface complete.** 16 resources spanning catalog, orders, claims, finance, webhooks, and Export Center, plus a `parseWebhookEvent` helper for inbound event handling. Every endpoint a non-AutoFT non-V1 seller can hit is covered. See the [npm badge](https://www.npmjs.com/package/@lonca/trendyol) above for the current release.
 
 ## Coverage
 
-Each entry is a method on the client. Endpoints marked `★` are discovery-first wire-verified against live Trendyol STAGE — the SDK normalizes any spec/wire mismatch.
+Each entry is a method on the client.
 
 | Resource         | Methods                                                                                                                                                                                                                                                                                                                            |
 | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `brands`         | `list()`, `search(name)` ★                                                                                                                                                                                                                                                                                                         |
-| `categories`     | `list()`, `getAttributes(id)`, `getAttributeValues(catId, attrId)` ★, `getByBarcodes(barcodes)` (AutoFT)                                                                                                                                                                                                                           |
+| `brands`         | `list()`, `search(name)`                                                                                                                                                                                                                                                                                                           |
+| `categories`     | `list()`, `getAttributes(id)`, `getAttributeValues(catId, attrId)`, `getByBarcodes(barcodes)` (AutoFT)                                                                                                                                                                                                                             |
 | `suppliers`      | `getAddresses({forceRefresh?})` (1-hour cache; rate-limited 1 req/hour on Trendyol)                                                                                                                                                                                                                                                |
-| `products` read  | `list({...})` ★, `listUnapproved({...})` ★, `getBase(barcode)` ★, `getBuyboxInfo(barcodes)` ★, `getBatchStatus(id)` ★                                                                                                                                                                                                              |
-| `products` write | `create(items)`, `updateContent(items)`, `updateVariants(items)`, `updateUnapproved(items)` ★, `updateDeliveryInfo(items)`                                                                                                                                                                                                         |
+| `products` read  | `list({...})`, `listInventoryAndPrice({...})` (lightweight stock + price), `listUnapproved({...})`, `getBase(barcode)`, `getBuyboxInfo(barcodes)`, `getBatchStatus(id)`                                                                                                                                                            |
+| `products` write | `create(items)`, `updateContent(items)`, `updateVariants(items)`, `updateUnapproved(items)`, `updateDeliveryInfo(items)`                                                                                                                                                                                                           |
 | `products` life  | `delete(barcodes)`, `archive(barcodes)`, `unarchive(barcodes)`, `unlock(barcodes)`                                                                                                                                                                                                                                                 |
-| `inventory`      | `update(items)` ★ (stock + price, async batch)                                                                                                                                                                                                                                                                                     |
-| `orders` read    | `list({...})` ★, `listStream({...})` ★ (opaque cursor for >10K), `getCargoInvoiceItems(serial, {...})`                                                                                                                                                                                                                             |
+| `inventory`      | `update(items)` (stock + price, async batch)                                                                                                                                                                                                                                                                                       |
+| `orders` read    | `list({...})`, `listStream({...})` (opaque cursor for >10K), `getCargoInvoiceItems(serial, {...})`                                                                                                                                                                                                                                 |
 | `orders` write   | `updatePackageStatus(id, {...})`, `cancelPackageItem(id, {...})`, `extendDeliveryDate(id, 1\|2\|3)`, `processAlternativeDelivery(id, {...})`                                                                                                                                                                                       |
 | `orders` split   | `splitPackage`, `splitPackageByQuantity`, `multiSplitPackage`, `splitMultiPackagesByQuantity` (4 variants)                                                                                                                                                                                                                         |
 | `orders` cargo   | `changeCargoProvider(id, code)`, `manualDeliverByPackageId(id)`, `manualDeliverByTrackingNumber(trk)`, `markDeliveredByService(id)`                                                                                                                                                                                                |
 | `orders` ops     | `updateBoxInfo(id, {...})`, `updateLaborCosts(id, items)`, `updateWarehouse(id, warehouseId)`                                                                                                                                                                                                                                      |
 | `orders` returns | `manualReturnByPackageId(id)`, `manualReturnByTrackingNumber(trk)`, `getCompensationTickets({...})` (TEX)                                                                                                                                                                                                                          |
-| `claims`         | `create({...})`, `createIssue(id, {...})` (multipart), `approveLineItems(id, {...})`, `list({...})`, `getIssueReasons()` ★, `getItemAudits(itemId)` ★                                                                                                                                                                              |
+| `claims`         | `create({...})`, `createIssue(id, {...})` (multipart), `approveLineItems(id, {...})`, `list({...})`, `getIssueReasons()`, `getItemAudits(itemId)`                                                                                                                                                                                  |
 | `webhooks`       | `create({...})`, `list()`, `update(id, {...})`, `delete(id)`, `activate(id)`, `deactivate(id)`                                                                                                                                                                                                                                     |
-| `questions`      | `get(id)`, `list({...})` ★, `answer(id, text)`                                                                                                                                                                                                                                                                                     |
+| `questions`      | `get(id)`, `list({...})`, `answer(id, text)`                                                                                                                                                                                                                                                                                       |
 | `invoices`       | `uploadFile({shipmentPackageId, file, ...})` (multipart), `sendLink({...})`, `deleteLink({...})`                                                                                                                                                                                                                                   |
-| `finance`        | `getSettlements({...})`, `getOtherFinancials({...})` — both return typed `FinancialTransaction[]` ★                                                                                                                                                                                                                                |
-| `labels`         | `createCommon(trackingNumber, {format: 'ZPL', ...})`, `getCommon(trackingNumber)` ★                                                                                                                                                                                                                                                |
+| `finance`        | `getSettlements({...})`, `getOtherFinancials({...})` — both return typed `FinancialTransaction[]`                                                                                                                                                                                                                                  |
+| `labels`         | `createCommon(trackingNumber, {format: 'ZPL', ...})`, `getCommon(trackingNumber)`                                                                                                                                                                                                                                                  |
 | `testOrders`     | `create({...})`, `updateStatus(id, status)`, `setClaimsWaitingInAction()` — **STAGE-only utility**                                                                                                                                                                                                                                 |
-| `locations`      | `getCountries()` ★, `getTurkeyCities()` ★, `getTurkeyDistricts(cityCode)`, `getTurkeyNeighborhoods(cityCode, districtCode)`, `getAzerbaijanCities()`, `getAzerbaijanDistricts(...)`, `getCitiesByCountry/getDistrictsByCity(...)`                                                                                                  |
+| `locations`      | `getCountries()`, `getTurkeyCities()`, `getTurkeyDistricts(cityCode)`, `getTurkeyNeighborhoods(cityCode, districtCode)`, `getAzerbaijanCities()`, `getAzerbaijanDistricts(...)`, `getCitiesByCountry/getDistrictsByCity(...)`                                                                                                      |
 | `exportCenter`   | `listProducts({...})`, `createProducts(items)`, `updatePrices(items)`, `updateStocks(items)`, `getBatchStatus(batchId)`, `listPackagesV2/V3({...})`, `getPackageItems({packageId, ...})`, `getCategoryAttributes(id)`, `getCareInstructions()`, `getCompositions()`, `getOrigins()` — **Trendyol Export Center / İhracat Merkezi** |
 | `videos`         | `create({contentId, url, ...})`, `list({id?, sellerIntegrationStatus?, ...})` — product-page video upload + status                                                                                                                                                                                                                 |
 | **top-level**    | `parseWebhookEvent(rawBody)`, `normalizeShipmentPackage(rawNode)` — for inbound webhook handlers                                                                                                                                                                                                                                   |
@@ -238,6 +241,7 @@ await client.suppliers.getAddresses({ forceRefresh: true });
 
 // products — read
 await client.products.list({ barcode: 'BC1' });
+await client.products.listInventoryAndPrice({ status: 'onSale', limit: 100 }); // stock + price only
 await client.products.listUnapproved({ limit: 50 });
 await client.products.getBase('BC1');
 await client.products.getBuyboxInfo(['BC1', 'BC2']); // max 10 per call
@@ -379,25 +383,6 @@ const status = await client.products.getBatchStatus(batchRequestId);
 
 **Important:** Trendyol's overall batch `status` can lag at `PROCESSING` even after each `items[].status` has settled. Trust the per-item status, or re-read the affected products via `list({ barcode })` / `getBase(barcode)` to verify the change landed. Batch results are retained for **4 hours** on Trendyol's side.
 
-## Discovery-first wire fixes
-
-`@lonca/trendyol` was built by hitting the live Trendyol STAGE for every endpoint before writing types. Places where the official OpenAPI spec disagrees with the live wire are normalized automatically:
-
-- `categories.getAttributeValues`: spec says `attributeValueName`, wire returns `attributeValue` → SDK normalizes to `{ id, name }`
-- `products.listUnapproved`: spec says `media: [{url}]`, wire returns `images: [{url}]` → SDK exposes `images: string[]`
-- `products.getBuyboxInfo`: wire returns extra `secondBuyboxPrice` / `thirdBuyboxPrice` fields beyond spec → both surfaced
-- `products.updateUnapproved`: spec marks only `barcode` required, but live endpoint returns HTTP 500 (`TypeError`) when too many optional fields are omitted → documented in JSDoc
-- `brands.search`: docs claim case-sensitive exact match, live is substring + case-insensitive → documented in JSDoc
-- `getBatchRequestResult`: returns `PROCESSING + empty items` for unknown batch IDs (not 404)
-- `orders.listStream` returns package ID as `id`, regular `orders.list` returns it as `shipmentPackageId` → normalizer accepts both
-- `orders.updateLaborCosts`: body is a **raw array** (no `{ items: [...] }` envelope) — only endpoint in the surface that does this
-- `getCompensationTickets`: spec says `{ data: { items: [] } }`, but SDK also accepts `{ data: [] }` and `{ content: [] }` defensively
-- `labels.getCommon`: response is `{ data: [{ label, format }] }` → SDK surfaces `labels[]` for ergonomic access
-- `finance.*`: both `getSettlements` and `getOtherFinancials` share the same `FinancialTransaction` wire schema → unified typed surface
-- `webhooks.list`: SDK accepts 3 envelope shapes (`[]` raw, `{ webhooks: [] }`, `{ content: [] }`) and 3 active-flag spellings (`active`, `isActive`, `status: 'ACTIVE'`)
-
-Each fix is pinned by a regression mock test using the exact STAGE shape.
-
 ## Authentication
 
 Trendyol uses HTTP Basic Auth. Get your `sellerId`, `apiKey`, and `apiSecret` from the [Trendyol Partner Panel → Account Info → Integration Information](https://partner.trendyol.com/account/info?tab=integrationInformation) (master-user only).
@@ -413,7 +398,7 @@ Trendyol uses HTTP Basic Auth. Get your `sellerId`, `apiKey`, and `apiSecret` fr
 
 ## Built-in robustness
 
-- **Retry with exponential backoff** on 429 (respects `Retry-After`) and 5xx
+- **Idempotency-aware retry with exponential backoff** — reads (`GET`) retry on 429 (honoring `Retry-After`), 5xx, and network/timeout errors. Writes (`POST`/`PUT`/`DELETE`) retry **only** on 429, which the server rejects before processing; ambiguous 5xx/network/timeout failures on a write are not replayed, so a transient error can't duplicate an order action or stock/price push. A `Retry-After: 0` no longer collapses backoff to an immediate retry.
 - **Per-endpoint rate limiting** (token bucket) sized to Trendyol's documented limits — see defaults below; override per resource
 - **Per-request correlation ID** — every call gets a UUID surfaced in log messages and the `x-correlationid` header for Trendyol-side log tracing
 - **Structured errors** via `@lonca/core` (`AuthError`, `RateLimitError`, `NotFoundError`, `ServerError`, `ValidationError`, `NetworkError`, `TimeoutError`)

package/dist/{client-BZeFAlrp.d.cts → client-CCA1P7sb.d.cts}

@@ -1,4 +1,4 @@
-import { Logger, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, OffsetPaginationParams } from '@lonca/core';
+import { Logger, BaseRequestOptions, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, OffsetPaginationParams } from '@lonca/core';
 
 declare const BASE_URLS: {
     readonly prod: "https://apigw.trendyol.com";
@@ -18,34 +18,22 @@ interface TransportConfig {
     /** Override the underlying `fetch` (tests inject a mock). */
     fetch?: typeof fetch;
 }
-interface RequestOptions {
+interface RequestOptions extends BaseRequestOptions {
     method: 'GET' | 'POST' | 'PUT' | 'DELETE';
     /** Path beginning with `/` (e.g., `/sapigw/brands`). */
     path: string;
     query?: Record<string, string | number | boolean | undefined>;
-    body?: unknown;
-    signal?: AbortSignal;
-    /**
-     * Extra per-request headers merged over the default header set (caller
-     * headers win). Used for endpoint-specific headers like `storeFrontCode`.
-     */
-    headers?: Record<string, string>;
-    /** Per-endpoint rate limiter; acquire one token before each attempt. */
-    rateLimiter?: TokenBucketRateLimiter;
 }
 declare class TrendyolTransport {
     private readonly config;
     private readonly baseUrl;
-    private readonly logger;
-    private readonly timeoutMs;
-    private readonly fetchImpl;
+    private readonly requester;
     constructor(config: TransportConfig);
     /** Seller ID this transport is configured with. Resources read it for path-building. */
     get sellerId(): number;
     request<T>(opts: RequestOptions): Promise<T>;
     private buildUrl;
     private buildHeaders;
-    private composeSignal;
 }
 
 /**
@@ -89,7 +77,7 @@ declare class BrandsResource {
      * `createProducts` and don't want to page through the full `list()`
      * (1000 brands per page).
      *
-     * **Discovery-first wire fact (verified STAGE 2026-05-25):** Trendyol's
+     * **Wire fact (verified STAGE 2026-05-25):** Trendyol's
      * doc claims this is a case-sensitive *exact* match, but live behaviour
      * is **substring + case-insensitive** — `search('Trendyol')` returns
      * 17 hits including `TRENDYOLMILLA`, `trendyol vavist`, `Trendyol Üyelik`.

package/dist/{client-BZeFAlrp.d.ts → client-CCA1P7sb.d.ts}

@@ -1,4 +1,4 @@
-import { Logger, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, OffsetPaginationParams } from '@lonca/core';
+import { Logger, BaseRequestOptions, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, OffsetPaginationParams } from '@lonca/core';
 
 declare const BASE_URLS: {
     readonly prod: "https://apigw.trendyol.com";
@@ -18,34 +18,22 @@ interface TransportConfig {
     /** Override the underlying `fetch` (tests inject a mock). */
     fetch?: typeof fetch;
 }
-interface RequestOptions {
+interface RequestOptions extends BaseRequestOptions {
     method: 'GET' | 'POST' | 'PUT' | 'DELETE';
     /** Path beginning with `/` (e.g., `/sapigw/brands`). */
     path: string;
     query?: Record<string, string | number | boolean | undefined>;
-    body?: unknown;
-    signal?: AbortSignal;
-    /**
-     * Extra per-request headers merged over the default header set (caller
-     * headers win). Used for endpoint-specific headers like `storeFrontCode`.
-     */
-    headers?: Record<string, string>;
-    /** Per-endpoint rate limiter; acquire one token before each attempt. */
-    rateLimiter?: TokenBucketRateLimiter;
 }
 declare class TrendyolTransport {
     private readonly config;
     private readonly baseUrl;
-    private readonly logger;
-    private readonly timeoutMs;
-    private readonly fetchImpl;
+    private readonly requester;
     constructor(config: TransportConfig);
     /** Seller ID this transport is configured with. Resources read it for path-building. */
     get sellerId(): number;
     request<T>(opts: RequestOptions): Promise<T>;
     private buildUrl;
     private buildHeaders;
-    private composeSignal;
 }
 
 /**
@@ -89,7 +77,7 @@ declare class BrandsResource {
      * `createProducts` and don't want to page through the full `list()`
      * (1000 brands per page).
      *
-     * **Discovery-first wire fact (verified STAGE 2026-05-25):** Trendyol's
+     * **Wire fact (verified STAGE 2026-05-25):** Trendyol's
      * doc claims this is a case-sensitive *exact* match, but live behaviour
      * is **substring + case-insensitive** — `search('Trendyol')` returns
      * 17 hits including `TRENDYOLMILLA`, `trendyol vavist`, `Trendyol Üyelik`.

package/dist/index.cjs

@@ -1,7 +1,6 @@
 'use strict';
 
 var core = require('@lonca/core');
-var crypto = require('crypto');
 
 // src/resources/brands.ts
 var DEFAULT_PAGE_SIZE = 1e3;
@@ -41,7 +40,7 @@ var BrandsResource = class {
    * `createProducts` and don't want to page through the full `list()`
    * (1000 brands per page).
    *
-   * **Discovery-first wire fact (verified STAGE 2026-05-25):** Trendyol's
+   * **Wire fact (verified STAGE 2026-05-25):** Trendyol's
    * doc claims this is a case-sensitive *exact* match, but live behaviour
    * is **substring + case-insensitive** — `search('Trendyol')` returns
    * 17 hits including `TRENDYOLMILLA`, `trendyol vavist`, `Trendyol Üyelik`.
@@ -1262,7 +1261,8 @@ var OrdersResource = class {
     const items = (data.content ?? []).map(normalizePackage2);
     const totalPages = typeof data.totalPages === "number" ? data.totalPages : 0;
     const result = { items };
-    if (page + 1 < totalPages) {
+    const nextPageWithinCap = (page + 2) * size <= MAX_OFFSET_RECORDS;
+    if (page + 1 < totalPages && nextPageWithinCap) {
       result.nextCursor = String(page + 1);
     }
     return result;
@@ -2784,14 +2784,6 @@ function extractErrorsArray(body) {
   }
   return void 0;
 }
-function parseRetryAfter(header) {
-  if (!header) return void 0;
-  const seconds = Number(header);
-  if (!Number.isNaN(seconds)) return Math.max(0, seconds * 1e3);
-  const epoch = Date.parse(header);
-  if (!Number.isNaN(epoch)) return Math.max(0, epoch - Date.now());
-  return void 0;
-}
 
 // src/transport.ts
 var BASE_URLS = {
@@ -2802,95 +2794,26 @@ var TrendyolTransport = class {
   constructor(config) {
     this.config = config;
     this.baseUrl = BASE_URLS[config.env];
-    this.logger = config.logger ?? core.noopLogger;
-    this.timeoutMs = config.timeoutMs ?? 3e4;
-    this.fetchImpl = config.fetch ?? fetch;
+    this.requester = core.createRequester({
+      fetch: config.fetch ?? fetch,
+      logger: config.logger,
+      timeoutMs: config.timeoutMs ?? 3e4,
+      label: "Trendyol",
+      logPrefix: "trendyol",
+      buildUrl: (opts) => this.buildUrl(opts.path, opts.query),
+      buildHeaders: (correlationId) => this.buildHeaders(correlationId),
+      mapHttpError
+    });
   }
   config;
   baseUrl;
-  logger;
-  timeoutMs;
-  fetchImpl;
+  requester;
   /** Seller ID this transport is configured with. Resources read it for path-building. */
   get sellerId() {
     return this.config.sellerId;
   }
-  async request(opts) {
-    return core.retry(
-      async (attempt) => {
-        if (opts.rateLimiter) await opts.rateLimiter.acquire(opts.signal);
-        const url = this.buildUrl(opts.path, opts.query);
-        const correlationId = crypto.randomUUID();
-        const headers = { ...this.buildHeaders(correlationId), ...opts.headers };
-        const init = {
-          method: opts.method,
-          headers,
-          signal: this.composeSignal(opts.signal)
-        };
-        if (opts.body !== void 0 && opts.method !== "GET") {
-          if (opts.body instanceof FormData) {
-            init.body = opts.body;
-            delete headers["Content-Type"];
-          } else {
-            init.body = JSON.stringify(opts.body);
-          }
-        }
-        this.logger.debug("trendyol.request", {
-          method: opts.method,
-          url,
-          correlationId,
-          attempt
-        });
-        let response;
-        try {
-          response = await this.fetchImpl(url, init);
-        } catch (err) {
-          if (err instanceof Error && err.name === "AbortError") {
-            throw new core.TimeoutError({
-              message: `Trendyol request timed out after ${this.timeoutMs}ms`,
-              cause: err
-            });
-          }
-          throw new core.NetworkError({
-            message: "Trendyol network failure",
-            cause: err
-          });
-        }
-        if (!response.ok) {
-          const body = await safeJson(response);
-          const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
-          const error = mapHttpError(response.status, body, retryAfterMs);
-          this.logger.warn("trendyol.error", {
-            method: opts.method,
-            url,
-            correlationId,
-            status: response.status,
-            code: error.code,
-            retryable: error.retryable
-          });
-          throw error;
-        }
-        this.logger.debug("trendyol.response", {
-          correlationId,
-          status: response.status
-        });
-        if (response.status === 204) return void 0;
-        return await safeJson(response);
-      },
-      {
-        signal: opts.signal,
-        onRetry: (err, attempt, delay2) => {
-          if (err instanceof core.LoncaError) {
-            this.logger.warn("trendyol.retry", {
-              attempt,
-              delayMs: delay2,
-              code: err.code,
-              status: err.status
-            });
-          }
-        }
-      }
-    );
+  request(opts) {
+    return this.requester(opts);
   }
   buildUrl(path, query) {
     const url = new URL(path, this.baseUrl);
@@ -2913,21 +2836,7 @@ var TrendyolTransport = class {
       Accept: "application/json"
     };
   }
-  composeSignal(external) {
-    const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
-    if (!external) return timeoutSignal;
-    return AbortSignal.any([external, timeoutSignal]);
-  }
 };
-async function safeJson(response) {
-  const text = await response.text();
-  if (!text) return void 0;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
 
 // src/client.ts
 function createTrendyolClient(opts) {