@lonca/trendyol 0.9.0 → 0.11.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { TokenBucketRateLimiter, ValidationError, noopLogger, retry, TimeoutError, NetworkError, LoncaError, ServerError, RateLimitError, NotFoundError, AuthError } from '@lonca/core';
+import { createStatusNormalizer, TokenBucketRateLimiter, ValidationError, TimeoutError, ServerError, noopLogger, retry, NetworkError, LoncaError, RateLimitError, NotFoundError, AuthError } from '@lonca/core';
 import { randomUUID } from 'crypto';
 
 // src/resources/brands.ts
@@ -737,11 +737,37 @@ var FinanceResource = class {
   }
 };
 var MAX_ITEMS_PER_REQUEST = 1e3;
+async function pollBatchStatus(getStatus, batchRequestId, opts = {}) {
+  const pollIntervalMs = opts.pollIntervalMs ?? 2e3;
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    opts.signal?.throwIfAborted();
+    const result = await getStatus(batchRequestId);
+    if (result.status === "COMPLETED" || result.status === "FAILED") {
+      return result;
+    }
+    if (Date.now() >= deadline) {
+      throw new TimeoutError({
+        message: `Trendyol batch ${batchRequestId} did not settle within ${timeoutMs}ms (last status: ${result.status})`,
+        data: { batchRequestId, lastStatus: result.status, lastResult: result }
+      });
+    }
+    await delay(pollIntervalMs, opts.signal);
+  }
+}
 var InventoryResource = class {
-  constructor(transport) {
+  /**
+   * @param transport Trendyol transport.
+   * @param getBatchStatus Batch-status poller (wired by `createTrendyolClient`
+   *   to `products.getBatchStatus`). Required only for `updateAndWait`.
+   */
+  constructor(transport, getBatchStatus) {
     this.transport = transport;
+    this.getBatchStatus = getBatchStatus;
   }
   transport;
+  getBatchStatus;
   /**
    * Update price and/or stock for one or more SKUs (by barcode).
    *
@@ -755,6 +781,9 @@ var InventoryResource = class {
    * ```
    *
    * @throws {ValidationError} when `items` is empty or longer than 1000.
+   * @throws {ServerError} when Trendyol accepts the request but returns no
+   *   `batchRequestId` (an unpollable response — surfaced loudly instead of
+   *   handing back an empty id).
    */
   async update(items) {
     if (items.length === 0) {
@@ -770,9 +799,70 @@ var InventoryResource = class {
       path: `/integration/inventory/sellers/${this.transport.sellerId}/products/price-and-inventory`,
       body: { items }
     });
-    return { batchRequestId: data.batchRequestId ?? "" };
+    if (!data.batchRequestId) {
+      throw new ServerError({
+        message: "Trendyol updatePriceAndInventory returned no batchRequestId",
+        data: { response: data }
+      });
+    }
+    return { batchRequestId: data.batchRequestId };
+  }
+  /**
+   * Submit price/stock updates and wait for them to settle.
+   *
+   * Splits `items` into chunks of ≤1000, submits each via {@link update}, and
+   * polls each `batchRequestId` to a terminal state. Returns one
+   * `BatchRequestResult` per chunk (read `failedItemCount` / `items[]` for
+   * per-barcode outcomes). Compose `@lonca/core`'s `retry` around this for
+   * transient-error resilience.
+   *
+   * @throws {ValidationError} when `items` is empty.
+   * @throws {TimeoutError} when any chunk does not settle within `timeoutMs`;
+   *   `error.data.batchRequestId` identifies the stuck chunk.
+   */
+  async updateAndWait(items, opts = {}) {
+    if (items.length === 0) {
+      throw new ValidationError({ message: "updateAndWait: items must not be empty" });
+    }
+    const getStatus = this.getBatchStatus;
+    if (!getStatus) {
+      throw new Error(
+        "updateAndWait requires a batch-status poller; obtain the client via createTrendyolClient()"
+      );
+    }
+    const results = [];
+    for (const batch of chunk(items, MAX_ITEMS_PER_REQUEST)) {
+      const { batchRequestId } = await this.update(batch);
+      results.push(await pollBatchStatus(getStatus, batchRequestId, opts));
+    }
+    return results;
   }
 };
+function chunk(items, size) {
+  if (items.length <= size) return [items];
+  const chunks = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks;
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("Aborted"));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("Aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 var InvoicesResource = class {
   constructor(transport, limiter) {
     this.transport = transport;
@@ -974,6 +1064,7 @@ var LocationsResource = class {
 };
 var MAX_PAGE_SIZE = 200;
 var DEFAULT_PAGE_SIZE2 = 50;
+var MAX_OFFSET_RECORDS = 1e4;
 function toIso3(epochMs) {
   if (typeof epochMs !== "number" || !Number.isFinite(epochMs) || epochMs === 0) {
     return void 0;
@@ -1150,6 +1241,11 @@ var OrdersResource = class {
   async list(params = {}) {
     const size = Math.min(params.limit ?? DEFAULT_PAGE_SIZE2, MAX_PAGE_SIZE);
     const page = params.cursor ? Number.parseInt(params.cursor, 10) : 0;
+    if ((page + 1) * size > MAX_OFFSET_RECORDS) {
+      throw new ValidationError({
+        message: `getShipmentPackages can reach at most ${MAX_OFFSET_RECORDS} records (page ${page} \xD7 size ${size} exceeds it); use listStream() for full scans`
+      });
+    }
     const query = { page, size };
     if (params.status) query.status = params.status;
     if (params.orderNumber) query.orderNumber = params.orderNumber;
@@ -1603,6 +1699,7 @@ var OrdersResource = class {
 };
 var DEFAULT_PAGE_SIZE3 = 50;
 var MAX_PAGE_SIZE2 = 1e3;
+var MAX_INVENTORY_PAGE_SIZE = 100;
 var MAX_BUYBOX_BARCODES = 10;
 function normalizeRef(ref) {
   return {
@@ -1668,6 +1765,30 @@ function normalizeProduct(node) {
   if (node.lastModifiedBy !== void 0) out.lastModifiedBy = node.lastModifiedBy;
   return out;
 }
+function normalizeStockPriceVariant(node) {
+  const out = {
+    variantId: node.variantId !== void 0 ? String(node.variantId) : "",
+    barcode: node.barcode ?? "",
+    raw: node
+  };
+  if (typeof node.salePrice === "number") out.salePrice = node.salePrice;
+  if (typeof node.listPrice === "number") out.listPrice = node.listPrice;
+  if (typeof node.quantity === "number") out.quantity = node.quantity;
+  if (node.stockCode !== void 0) out.stockCode = node.stockCode;
+  if (node.stockLastModifiedDate !== void 0 && node.stockLastModifiedDate !== null) {
+    const iso = toIso4(node.stockLastModifiedDate);
+    if (iso) out.stockLastModifiedAt = iso;
+  }
+  return out;
+}
+function normalizeStockPrice(node) {
+  return {
+    contentId: node.contentId !== void 0 ? String(node.contentId) : "",
+    productMainId: node.productMainId ?? "",
+    variants: (node.variants ?? []).map(normalizeStockPriceVariant),
+    raw: node
+  };
+}
 function normalizeUnapprovedRejectReason(r) {
   const out = {};
   if (r.rejectReason !== void 0) out.rejectReason = r.rejectReason;
@@ -1858,6 +1979,63 @@ var ProductsResource = class {
     }
     return page;
   }
+  /**
+   * List **stock and price** for approved products — Trendyol's lightweight
+   * `inventory-and-price` filter. A slim alternative to {@link list} when you
+   * only need pricing + stock: the response carries `contentId`,
+   * `productMainId`, and a `variants[]` array with `barcode`, `salePrice`,
+   * `listPrice`, `quantity`, `stockCode`, and `stockLastModifiedAt` — nothing
+   * else.
+   *
+   * Filter by `barcode`, `contentId`, `stockCode`, `productMainId`, or listing
+   * `status`. Sort with `orderByDirection` (`SellerCreatedDate`). `size` caps
+   * at **100** here (tighter than `list`'s 1000).
+   *
+   * Pagination follows the same convention as {@link list}: pass our opaque
+   * `cursor` from the previous response and we forward it as `nextPageToken`
+   * (required once the dataset exceeds 10,000 items).
+   *
+   * @example
+   * ```ts
+   * import { paginate } from '@lonca/core';
+   * for await (const p of paginate((q) =>
+   *   client.products.listInventoryAndPrice({ ...q, status: 'onSale' }),
+   * )) {
+   *   for (const v of p.variants) {
+   *     console.log(v.barcode, v.quantity, v.salePrice);
+   *   }
+   * }
+   * ```
+   */
+  async listInventoryAndPrice(params = {}) {
+    const size = Math.min(params.limit ?? DEFAULT_PAGE_SIZE3, MAX_INVENTORY_PAGE_SIZE);
+    const query = { size };
+    if (params.cursor) {
+      query.nextPageToken = params.cursor;
+    } else {
+      query.page = 0;
+    }
+    if (params.barcode) query.barcode = params.barcode;
+    if (params.contentId) query.contentId = params.contentId;
+    if (params.stockCode) query.stockCode = params.stockCode;
+    if (params.productMainId) query.productMainId = params.productMainId;
+    if (params.status) query.status = params.status;
+    if (params.orderByDirection) query.orderByDirection = params.orderByDirection;
+    const headers = params.storeFrontCode ? { storeFrontCode: params.storeFrontCode } : void 0;
+    const data = await this.transport.request({
+      method: "GET",
+      path: `/integration/product/sellers/${this.transport.sellerId}/products/approved/inventory-and-price`,
+      query,
+      headers,
+      rateLimiter: this.filterLimiter
+    });
+    const items = (data.content ?? []).map(normalizeStockPrice);
+    const page = { items };
+    if (data.nextPageToken) {
+      page.nextCursor = data.nextPageToken;
+    }
+    return page;
+  }
   /**
    * Poll a batch request returned by an async write (e.g. `createProducts`,
    * `updatePriceAndInventory`).
@@ -2506,6 +2684,16 @@ var WebhooksResource = class {
   }
 };
 
+// src/capabilities.ts
+var trendyolCapabilities = {
+  /** Trendyol has no time-bounded / scheduled pricing (`pricings[]`). */
+  scheduledPricing: false,
+  /** `inventory.update` accepts stock-only items (`quantity` with no price). */
+  stockOnlyBatch: true,
+  /** Products expose `updatedAt`, so last-write-wins guards are supported. */
+  listingUpdatedAt: true
+};
+
 // src/auth.ts
 function buildAuthHeader(apiKey, apiSecret) {
   const token = Buffer.from(`${apiKey}:${apiSecret}`, "utf8").toString("base64");
@@ -2516,27 +2704,31 @@ function buildUserAgent(sellerId, integratorName) {
 }
 function mapHttpError(status, body, retryAfterMs) {
   const data = { body };
+  const issues = normalizeErrorIssues(body);
   switch (status) {
     case 401:
       return new AuthError({
         message: "Trendyol authentication failed (check apiKey / apiSecret)",
         status,
-        data
+        data,
+        issues
       });
     case 403:
       return new ValidationError({
         message: "Trendyol forbidden (check User-Agent header or endpoint path)",
         status,
-        data
+        data,
+        issues
       });
     case 404:
-      return new NotFoundError({ message: "Trendyol resource not found", status, data });
+      return new NotFoundError({ message: "Trendyol resource not found", status, data, issues });
     case 429:
       return new RateLimitError({
         message: "Trendyol rate limit exceeded",
         status,
         retryAfterMs,
-        data
+        data,
+        issues
       });
     case 500:
     case 502:
@@ -2545,7 +2737,8 @@ function mapHttpError(status, body, retryAfterMs) {
       return new ServerError({
         message: `Trendyol server error (${status})`,
         status,
-        data
+        data,
+        issues
       });
     default:
       return new LoncaError({
@@ -2553,10 +2746,42 @@ function mapHttpError(status, body, retryAfterMs) {
         message: `Trendyol unexpected response (${status})`,
         status,
         data,
+        issues,
         retryable: false
       });
   }
 }
+function normalizeErrorIssues(body) {
+  const errors = extractErrorsArray(body);
+  if (!errors) return [];
+  const issues = [];
+  for (const entry of errors) {
+    if (typeof entry === "string") {
+      issues.push({ message: entry });
+      continue;
+    }
+    if (entry && typeof entry === "object") {
+      const e = entry;
+      if (typeof e.message !== "string") continue;
+      const issue = { message: e.message };
+      if (typeof e.field === "string") issue.field = e.field;
+      if (typeof e.code === "string") issue.code = e.code;
+      issues.push(issue);
+    }
+  }
+  return issues;
+}
+function extractErrorsArray(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const b = body;
+  if (Array.isArray(b.errors)) return b.errors;
+  const nested = b.body;
+  if (nested && typeof nested === "object") {
+    const n2 = nested;
+    if (Array.isArray(n2.errors)) return n2.errors;
+  }
+  return void 0;
+}
 function parseRetryAfter(header) {
   if (!header) return void 0;
   const seconds = Number(header);
@@ -2594,7 +2819,7 @@ var TrendyolTransport = class {
         if (opts.rateLimiter) await opts.rateLimiter.acquire(opts.signal);
         const url = this.buildUrl(opts.path, opts.query);
         const correlationId = randomUUID();
-        const headers = this.buildHeaders(correlationId);
+        const headers = { ...this.buildHeaders(correlationId), ...opts.headers };
         const init = {
           method: opts.method,
           headers,
@@ -2652,11 +2877,11 @@ var TrendyolTransport = class {
       },
       {
         signal: opts.signal,
-        onRetry: (err, attempt, delay) => {
+        onRetry: (err, attempt, delay2) => {
           if (err instanceof LoncaError) {
             this.logger.warn("trendyol.retry", {
               attempt,
-              delayMs: delay,
+              delayMs: delay2,
               code: err.code,
               status: err.status
             });
@@ -2714,12 +2939,16 @@ function createTrendyolClient(opts) {
     logger: opts.logger,
     timeoutMs: opts.timeoutMs
   });
+  return buildClient(transport);
+}
+function buildClient(transport) {
+  const products = new ProductsResource(transport);
   return {
     brands: new BrandsResource(transport),
     categories: new CategoriesResource(transport),
     suppliers: new SuppliersResource(transport),
-    products: new ProductsResource(transport),
-    inventory: new InventoryResource(transport),
+    products,
+    inventory: new InventoryResource(transport, (id) => products.getBatchStatus(id)),
     orders: new OrdersResource(transport),
     claims: new ClaimsResource(transport),
     webhooks: new WebhooksResource(transport),
@@ -2730,7 +2959,8 @@ function createTrendyolClient(opts) {
     testOrders: new TestOrdersResource(transport),
     locations: new LocationsResource(transport),
     exportCenter: new ExportCenterResource(transport),
-    videos: new VideosResource(transport)
+    videos: new VideosResource(transport),
+    capabilities: trendyolCapabilities
   };
 }
 function parseWebhookEvent(rawBody) {
@@ -2767,7 +2997,29 @@ function parseWebhookEvent(rawBody) {
     raw: body
   };
 }
+var statusMap = {
+  Created: "created",
+  Awaiting: "created",
+  // new order awaiting seller acceptance
+  Verified: "created",
+  // accepted/verified, before picking
+  Picking: "picking",
+  UnPacked: "picking",
+  // back in fulfillment after being unpacked
+  Invoiced: "invoiced",
+  Shipped: "shipped",
+  AtCollectionPoint: "shipped",
+  // in transit, awaiting pickup
+  UnDelivered: "shipped",
+  // delivery attempt failed; still in carrier's hands
+  Delivered: "delivered",
+  Cancelled: "cancelled",
+  UnSupplied: "cancelled",
+  // seller couldn't supply → effectively cancelled
+  Returned: "returned"
+};
+var normalizeStatus = createStatusNormalizer(statusMap);
 
-export { BrandsResource, CategoriesResource, ClaimsResource, ExportCenterResource, FinanceResource, InventoryResource, InvoicesResource, LabelsResource, LocationsResource, OrdersResource, ProductsResource, QuestionsResource, SuppliersResource, TestOrdersResource, VideosResource, WebhooksResource, createTrendyolClient, normalizeShipmentPackage, parseWebhookEvent };
+export { BrandsResource, CategoriesResource, ClaimsResource, ExportCenterResource, FinanceResource, InventoryResource, InvoicesResource, LabelsResource, LocationsResource, OrdersResource, ProductsResource, QuestionsResource, SuppliersResource, TestOrdersResource, VideosResource, WebhooksResource, createTrendyolClient, normalizeShipmentPackage, normalizeStatus, parseWebhookEvent, pollBatchStatus, statusMap, trendyolCapabilities };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map