@lonca/trendyol 0.3.0 → 0.4.0

package/dist/index.js

@@ -357,8 +357,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),
@@ -466,6 +467,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 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 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 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 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 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 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 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;