@lonca/trendyol 0.3.0 → 0.4.0

package/README.md

@@ -1,15 +1,37 @@
 # @lonca/trendyol
 
+[![npm version](https://img.shields.io/npm/v/@lonca/trendyol.svg)](https://www.npmjs.com/package/@lonca/trendyol)
+
 Type-safe TypeScript SDK for the [Trendyol Marketplace API](https://developers.trendyol.com).
 
-> ⚠️ **Alpha** — Only the `brands` resource is implemented in this initial scaffold. More endpoints (orders, products, inventory, webhooks) land in follow-up releases.
+> **`0.3.0` — bottom-up Phase 2 complete.** The full product surface is now wire-verified: brands · categories · suppliers · products (read + write + lifecycle) · inventory · orders.
+
+## Coverage
+
+Each entry is a method on the client. Endpoints behind `★` are discovery-first wire-verified against live Trendyol STAGE — the SDK normalizes any spec/wire mismatch.
+
+| Resource         | Methods                                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `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`       | `list({...})` ★, `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`         | `list({...})` (shipment packages) ★                                                                                        |
+
+Trendyol's product API has 12 V2 read/write/lifecycle endpoints — all 12 are covered. Categories V2 (tree + attributes + values + barcode→category lookup) is complete. V1 endpoints are intentionally skipped (Trendyol sunsets them August 2026). Order sub-endpoints (`updatePackageStatus`, `splitShipmentPackage`, returns, claims, webhooks) land in subsequent phases.
 
 ## Install
 
 ```bash
-pnpm add @lonca/trendyol
+pnpm add @lonca/trendyol @lonca/core
+# or npm install / yarn add
 ```
 
+`@lonca/core` is a peer dependency (provides `paginate`, `CursorPage`, error classes, the token-bucket limiter).
+
 ## Quick start
 
 ```ts
@@ -24,24 +46,151 @@ const client = createTrendyolClient({
   integratorName: 'MyCompany', // optional; defaults to 'SelfIntegration'
 });
 
-for await (const brand of paginate((p) => client.brands.list(p))) {
-  console.log(brand.id, brand.name);
+// Iterate every product page-by-page.
+for await (const product of paginate((p) => client.products.list(p))) {
+  for (const variant of product.variants) {
+    console.log(variant.barcode, product.title, variant.stock ?? '?');
+  }
 }
 ```
 
-## Authentication
+## End-to-end: create a product
 
-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).
+The chain `brand → category → category attributes (+ values) → addresses → create → poll → verify` is the canonical "create a real listing" flow.
+
+```ts
+import { createTrendyolClient } from '@lonca/trendyol';
 
-**Production vs Stage** have different credentials. Stage also requires IP whitelisting — register your CI/server IP with Trendyol support.
+const client = createTrendyolClient({ ... });
+
+// 1. Resolve brand + category IDs.
+const [brand] = await client.brands.search('TRENDYOLMİLLA');
+const tree = await client.categories.list();
+const category = findLeaf(tree, /Elbise/); // your own walker
+
+// 2. Fetch required attributes + a value (Renk = Kırmızı).
+const attrs = await client.categories.getAttributes(category.id);
+const renk = attrs.find((a) => a.name === 'Renk')!;
+const renkValues = await client.categories.getAttributeValues(category.id, renk.id);
+const kirmizi = renkValues.items.find((v) => v.name === 'Kırmızı')!;
+
+// 3. Resolve shipment / returning warehouse IDs.
+const addresses = await client.suppliers.getAddresses();
+const shipment = addresses.find((a) => a.isShipmentAddress)!;
+const returning = addresses.find((a) => a.isReturningAddress)!;
+
+// 4. Submit the create (async batch).
+const { batchRequestId } = await client.products.create([
+  {
+    barcode: 'MY-SKU-001',
+    title: 'Kırmızı Elbise',
+    productMainId: 'MY-MAIN-001',
+    brandId: Number(brand.id),
+    categoryId: Number(category.id),
+    quantity: 10,
+    stockCode: 'MY-SC-001',
+    dimensionalWeight: 1,
+    description: '<p>...</p>',
+    listPrice: 299.9,
+    salePrice: 199.9,
+    images: [{ url: 'https://cdn.example.com/dress.jpg' }],
+    vatRate: 20,
+    attributes: [{ attributeId: Number(renk.id), attributeValueIds: [Number(kirmizi.id)] }],
+    shipmentAddressId: Number(shipment.id),
+    returningAddressId: Number(returning.id),
+  },
+]);
+
+// 5. Poll until Trendyol finishes content review.
+let result;
+do {
+  await new Promise((r) => setTimeout(r, 2000));
+  result = await client.products.getBatchStatus(batchRequestId);
+} while (result.items[0]?.status === 'PROCESSING');
+
+// 6. Detect approval (or surface a rejection reason).
+if (result.items[0]?.status === 'SUCCESS') {
+  const base = await client.products.getBase('MY-SKU-001');
+  console.log('Approved:', base.approved, 'contentId:', base.contentId);
+}
+```
 
-## Built-in robustness
+## Per-resource cheat sheet
 
-- **Retry with exponential backoff** on 429 (respects `Retry-After`) and 5xx
-- **Per-endpoint rate limiting** (token bucket) sized to Trendyol's documented limits
-- **Structured errors** via `@lonca/core` (`AuthError`, `RateLimitError`, `NotFoundError`, `ServerError`, `ValidationError`, `NetworkError`, `TimeoutError`)
-- **Correlation ID** auto-generated per request (`x-correlationid` header) for Trendyol-side log tracing
-- **`AbortSignal` support** for cancellation throughout
+```ts
+// brands
+await client.brands.list({ limit: 1000 });
+await client.brands.search('TRENDYOLMİLLA'); // substring + case-insensitive
+
+// categories
+const tree = await client.categories.list();
+const attrs = await client.categories.getAttributes(catId);
+const values = await client.categories.getAttributeValues(catId, attrId);
+await client.categories.getByBarcodes(['BC1', 'BC2']); // requires AutoFT enrollment
+
+// suppliers (cached 1h)
+await client.suppliers.getAddresses();
+await client.suppliers.getAddresses({ forceRefresh: true });
+
+// products — read
+await client.products.list({ barcode: 'BC1' });
+await client.products.listUnapproved({ limit: 50 });
+await client.products.getBase('BC1');
+await client.products.getBuyboxInfo(['BC1', 'BC2']); // max 10 per call
+await client.products.getBatchStatus(batchRequestId);
+
+// products — write (all return { batchRequestId }; max 1000 items)
+await client.products.create([...]);
+await client.products.updateContent([{ contentId: 123, title: '...' }]);
+await client.products.updateVariants([{ barcode: 'BC1', stockCode: 'NEW' }]);
+await client.products.updateUnapproved([{ barcode: 'BC1', title: '...', /* fuller payload */ }]);
+await client.products.updateDeliveryInfo([{ barcode: 'BC1', deliveryOptions: { deliveryDuration: 3 } }]);
+
+// products — lifecycle
+await client.products.delete(['BC1']);     // separately rate-limited (100/min)
+await client.products.archive(['BC1']);    // PUT archived=true
+await client.products.unarchive(['BC1']);  // PUT archived=false
+await client.products.unlock(['BC1']);     // restore after Trendyol price-lock
+
+// inventory — async batch
+await client.inventory.update([{ barcode: 'BC1', quantity: 50, salePrice: 199.9, listPrice: 299.9 }]);
+
+// orders — shipment packages
+for await (const pkg of paginate((p) => client.orders.list(p))) {
+  console.log(pkg.id, pkg.status, pkg.lines.length);
+}
+```
+
+## Async batch + polling
+
+Every write endpoint (`products.create`, `updateContent`, `updateVariants`, `updateUnapproved`, `updateDeliveryInfo`, `delete`, `archive`, `unarchive`, `unlock`, `inventory.update`) is **asynchronous**: Trendyol accepts the batch and returns a `{ batchRequestId }`. Poll the result with:
+
+```ts
+const status = await client.products.getBatchStatus(batchRequestId);
+// status.status: 'PROCESSING' | 'COMPLETED' | 'FAILED'
+// status.items[].status: per-item outcome
+```
+
+**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. Several 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)
+
+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).
+
+**Production vs Stage have different credentials.** Stage also requires IP whitelisting — register your CI/server IP with Trendyol support (0850 258 58 00). The SDK auto-sends the 5 mandatory headers (`Authorization`, `x-clientip`, `x-correlationid`, `x-agentname`, `User-Agent`).
 
 ## Environments
 
@@ -50,9 +199,18 @@ Trendyol uses HTTP Basic Auth. Get your `sellerId`, `apiKey`, and `apiSecret` fr
 | `prod`  | `https://apigw.trendyol.com`      | No IP whitelist                               |
 | `stage` | `https://stageapigw.trendyol.com` | IP whitelist required — call Trendyol support |
 
+## Built-in robustness
+
+- **Retry with exponential backoff** on 429 (respects `Retry-After`) and 5xx
+- **Per-endpoint rate limiting** (token bucket) sized to Trendyol's documented limits — separate buckets for filter (2000/min), batch read (1000/min), buybox (1000/min), writes (1000/min), and delete (100/min)
+- **Structured errors** via `@lonca/core` (`AuthError`, `RateLimitError`, `NotFoundError`, `ServerError`, `ValidationError`, `NetworkError`, `TimeoutError`)
+- **Client-side validation** before the network: empty batches, oversized batches (>1000 items), >10 buybox barcodes throw `ValidationError`
+- **Correlation ID** auto-generated per request for Trendyol-side log tracing
+- **`AbortSignal` support** throughout
+
 ## Stability
 
-`0.x` — alpha. Public APIs may change between minor versions until `1.0.0`.
+`0.x` — alpha. The product surface is feature-complete and STAGE-verified, but public types may still adjust between minor versions until `1.0.0`.
 
 ## License
 

package/dist/index.cjs

@@ -359,8 +359,9 @@ function normalizeCustomer(node) {
   return out;
 }
 function normalizePackage(node) {
+  const pkgId = node.shipmentPackageId ?? node.id;
   const out = {
-    id: node.shipmentPackageId !== void 0 ? String(node.shipmentPackageId) : "",
+    id: pkgId !== void 0 ? String(pkgId) : "",
     orderNumber: node.orderNumber ?? "",
     status: node.status ?? "",
     customer: normalizeCustomer(node),
@@ -468,6 +469,342 @@ var OrdersResource = class {
     }
     return result;
   }
+  /**
+   * Push a shipment-package status update.
+   *
+   * Trendyol restricts the seller-side push to two transitions:
+   * - `Picking`  — order picked up from the shelf / being prepared
+   * - `Invoiced` — invoice issued, ready for cargo handoff
+   *
+   * Other transitions (`Shipped`, `Delivered`, etc.) are driven by Trendyol
+   * or the cargo provider — call `processAlternativeDelivery` or
+   * `manualDeliverByPackageId` if you ship outside Trendyol's cargo
+   * network.
+   *
+   * Returns void; Trendyol responds with 200 + empty body on success.
+   */
+  async updatePackageStatus(packageId, input) {
+    await this.transport.request({
+      method: "PUT",
+      path: this.packagePath(packageId),
+      body: input,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Notify Trendyol that one or more line items cannot be supplied
+   * ("Tedarik Edememe Bildirimi"). Marks the listed line IDs as
+   * `UnSupplied`. Trendyol cancels those quantities and notifies the
+   * customer.
+   *
+   * `reasonId` is a numeric code Trendyol publishes separately — consult
+   * the seller panel or the "Tedarik Edememe" docs for current values.
+   *
+   * Returns void; Trendyol responds with 200 + empty body on success.
+   */
+  async cancelPackageItem(packageId, input) {
+    if (!Array.isArray(input?.lines) || input.lines.length === 0) {
+      throw new core.ValidationError({ message: "cancelPackageItem: lines must not be empty" });
+    }
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/items/unsupplied`,
+      body: input,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Extend the agreed delivery date for a shipment package by 1, 2, or 3 days.
+   * Trendyol enforces the [1, 3] range server-side; the SDK validates client-side
+   * to fail fast.
+   *
+   * Returns void; Trendyol responds with 200 + empty body on success.
+   */
+  async extendDeliveryDate(packageId, extendedDayCount) {
+    if (![1, 2, 3].includes(extendedDayCount)) {
+      throw new core.ValidationError({
+        message: `extendDeliveryDate: extendedDayCount must be 1, 2, or 3 (got ${extendedDayCount})`
+      });
+    }
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/extended-agreed-delivery-date`,
+      body: { extendedDayCount },
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Notify Trendyol of an alternative delivery channel — used when the
+   * seller is shipping via a non-Trendyol cargo provider. Trendyol then
+   * either SMSes the customer the tracking link (when `isPhoneNumber` is
+   * `true`) or stores the tracking URL on the package directly.
+   *
+   * Returns void; Trendyol responds with 200 + empty body on success.
+   */
+  async processAlternativeDelivery(packageId, input) {
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/alternative-delivery`,
+      body: input,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Split a shipment package by moving a set of line IDs into a new
+   * package. The original package keeps the remaining lines.
+   *
+   * @param packageId    The package to split.
+   * @param orderLineIds Line IDs to move into the new package (1+).
+   * @throws {ValidationError} when `orderLineIds` is empty.
+   */
+  async splitPackage(packageId, orderLineIds) {
+    if (!Array.isArray(orderLineIds) || orderLineIds.length === 0) {
+      throw new core.ValidationError({ message: "splitPackage: orderLineIds must not be empty" });
+    }
+    await this.transport.request({
+      method: "POST",
+      path: `${this.packagePath(packageId)}/split`,
+      body: { orderLineIds },
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Split a shipment package by quantity. Each `QuantitySplit` entry
+   * carves a single line into multiple packages — e.g. `{ orderLineId: 100,
+   * quantities: [2, 2, 1] }` splits 5 units of line 100 into three packages
+   * of 2 + 2 + 1.
+   *
+   * @throws {ValidationError} when `quantitySplit` is empty.
+   */
+  async splitPackageByQuantity(packageId, quantitySplit) {
+    if (!Array.isArray(quantitySplit) || quantitySplit.length === 0) {
+      throw new core.ValidationError({
+        message: "splitPackageByQuantity: quantitySplit must not be empty"
+      });
+    }
+    await this.transport.request({
+      method: "POST",
+      path: `${this.packagePath(packageId)}/quantity-split`,
+      body: { quantitySplit },
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Split a shipment package into multiple new packages by grouping line
+   * IDs. Each `SplitGroup` becomes one new package containing the listed
+   * line IDs.
+   *
+   * @throws {ValidationError} when `splitGroups` is empty.
+   */
+  async multiSplitPackage(packageId, splitGroups) {
+    if (!Array.isArray(splitGroups) || splitGroups.length === 0) {
+      throw new core.ValidationError({ message: "multiSplitPackage: splitGroups must not be empty" });
+    }
+    await this.transport.request({
+      method: "POST",
+      path: `${this.packagePath(packageId)}/multi-split`,
+      body: { splitGroups },
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Split a shipment package into multiple new packages, each containing a
+   * mix of line items at specific quantities. This is the most expressive
+   * split — use it when you need fine-grained control over which line IDs
+   * and how many of each end up in each new package.
+   *
+   * @throws {ValidationError} when `splitPackages` is empty.
+   */
+  async splitMultiPackagesByQuantity(packageId, splitPackages) {
+    if (!Array.isArray(splitPackages) || splitPackages.length === 0) {
+      throw new core.ValidationError({
+        message: "splitMultiPackagesByQuantity: splitPackages must not be empty"
+      });
+    }
+    await this.transport.request({
+      method: "POST",
+      path: `${this.packagePath(packageId)}/split-packages`,
+      body: { splitPackages },
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Change the cargo provider on an existing shipment package. Use one of
+   * Trendyol's documented marketplace cargo codes (`'YKMP'`, `'ARASMP'`,
+   * `'SURATMP'`, etc.) — see `TrendyolCargoProvider` for the full list.
+   */
+  async changeCargoProvider(packageId, cargoProvider) {
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/cargo-providers`,
+      body: { cargoProvider },
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Mark a shipment package as manually delivered via its package ID.
+   * Used when the seller delivered the order outside Trendyol's cargo
+   * network and needs to flip the package to `Delivered` after handover.
+   *
+   * No request body; Trendyol responds with 200 + empty body on success.
+   */
+  async manualDeliverByPackageId(packageId) {
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/manual-invoice-delivery`,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Manual-deliver variant that takes the cargo tracking number instead
+   * of the package ID. Useful when you only have the tracking number on
+   * hand (e.g., from a cargo provider webhook).
+   *
+   * Note the path structure: tracking number sits at a sibling location,
+   * not under `/shipment-packages/{id}/...`.
+   */
+  async manualDeliverByTrackingNumber(cargoTrackingNumber) {
+    await this.transport.request({
+      method: "PUT",
+      path: `/integration/order/sellers/${this.sellerId}/shipment-packages/manual-invoice-delivery-by-tracking-number/${encodeURIComponent(String(cargoTrackingNumber))}`,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Mark a package as delivered through an authorized service ("yetkili
+   * servis"). For appliance / installation-required products that are
+   * delivered + installed by a third-party service partner.
+   */
+  async markDeliveredByService(packageId) {
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/delivered-by-service`,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Update box / packaging metadata on a shipment package (desi value
+   * and/or number of boxes). Either field can be sent alone.
+   */
+  async updateBoxInfo(packageId, input) {
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/box-info`,
+      body: input,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Update labor costs for one or more order lines.
+   *
+   * **Wire note:** Trendyol's request body is a raw array (no envelope),
+   * not `{ items: [...] }`. The SDK forwards `items` verbatim.
+   *
+   * @throws {ValidationError} when `items` is empty.
+   */
+  async updateLaborCosts(packageId, items) {
+    if (!Array.isArray(items) || items.length === 0) {
+      throw new core.ValidationError({ message: "updateLaborCosts: items must not be empty" });
+    }
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/labor-costs`,
+      body: items,
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Reassign a shipment package to a different warehouse. `warehouseId`
+   * comes from `client.suppliers.getAddresses()` (filter by `isShipmentAddress`).
+   */
+  async updateWarehouse(packageId, warehouseId) {
+    await this.transport.request({
+      method: "PUT",
+      path: `${this.packagePath(packageId)}/warehouse`,
+      body: { warehouseId },
+      rateLimiter: this.limiter
+    });
+  }
+  /**
+   * Stream variant of `list()`. Trendyol's `getShipmentPackagesStream`
+   * returns the same `ShipmentPackage` shape but paginates with an opaque
+   * cursor — useful when the dataset is large and page-based pagination
+   * would hit the 10 000-record cap.
+   *
+   * @example
+   * ```ts
+   * import { paginate } from '@lonca/core';
+   * for await (const pkg of paginate((p) =>
+   *   client.orders.listStream({ ...p, packageItemStatuses: 'Created,Picking' }),
+   * )) {
+   *   console.log(pkg.id, pkg.status);
+   * }
+   * ```
+   */
+  async listStream(params = {}) {
+    const size = Math.min(params.limit ?? DEFAULT_PAGE_SIZE2, MAX_PAGE_SIZE);
+    const query = { size };
+    if (params.cursor) query.nextCursor = params.cursor;
+    if (params.packageItemStatuses) query.packageItemStatuses = params.packageItemStatuses;
+    if (params.lastModifiedStartDate) {
+      query.lastModifiedStartDate = params.lastModifiedStartDate.getTime();
+    }
+    if (params.lastModifiedEndDate) {
+      query.lastModifiedEndDate = params.lastModifiedEndDate.getTime();
+    }
+    const data = await this.transport.request({
+      method: "GET",
+      path: `/integration/order/sellers/${this.sellerId}/orders/stream`,
+      query,
+      rateLimiter: this.limiter
+    });
+    const items = (data.content ?? []).map(normalizePackage);
+    const result = { items };
+    if (data.hasMore && data.nextCursor) {
+      result.nextCursor = data.nextCursor;
+    }
+    return result;
+  }
+  /**
+   * Fetch the per-parcel cargo-fee breakdown for a single cargo invoice
+   * (Trendyol's `getCargoInvoiceItems`). Useful for reconciling Trendyol's
+   * cargo deductions against your shipped packages.
+   *
+   * `invoiceSerialNumber` is sourced from the Current Account Statement
+   * ("Cari Hesap Ekstresi") with `transactionType=DeductionInvoices`.
+   *
+   * Page-based pagination internally (cursor encodes the page index).
+   */
+  async getCargoInvoiceItems(invoiceSerialNumber, params = {}) {
+    const size = Math.min(params.limit ?? 500, 500);
+    const page = params.cursor ? Number.parseInt(params.cursor, 10) : 0;
+    const data = await this.transport.request({
+      method: "GET",
+      path: `/integration/finance/che/sellers/${this.sellerId}/cargo-invoice/${encodeURIComponent(invoiceSerialNumber)}/items`,
+      query: { page, size },
+      rateLimiter: this.limiter
+    });
+    const items = (data.content ?? []).map((row) => {
+      const out = { raw: row };
+      if (row.shipmentPackageType !== void 0) out.shipmentPackageType = row.shipmentPackageType;
+      if (row.parcelUniqueId !== void 0) {
+        out.parcelUniqueId = typeof row.parcelUniqueId === "string" ? row.parcelUniqueId : String(row.parcelUniqueId);
+      }
+      if (row.orderNumber !== void 0) out.orderNumber = row.orderNumber;
+      if (typeof row.amount === "number") out.amount = row.amount;
+      if (typeof row.desi === "number") out.desi = row.desi;
+      return out;
+    });
+    const totalPages = typeof data.totalPages === "number" ? data.totalPages : 0;
+    const result = { items };
+    if (page + 1 < totalPages) {
+      result.nextCursor = String(page + 1);
+    }
+    return result;
+  }
+  packagePath(packageId) {
+    return `/integration/order/sellers/${this.sellerId}/shipment-packages/${encodeURIComponent(String(packageId))}`;
+  }
 };
 var DEFAULT_PAGE_SIZE3 = 50;
 var MAX_PAGE_SIZE2 = 1e3;