@lonca/trendyol 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -77,6 +77,21 @@ declare class BrandsResource {
      * ```
      */
     list(params?: CursorPaginationParams): Promise<CursorPage<Brand>>;
+    /**
+     * Search brands by name. Useful when you need a brand's numeric ID for
+     * `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
+     * 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`.
+     * Plan for ranking your results client-side if you need an exact match.
+     * The endpoint returns an empty array when nothing matches (no 404).
+     *
+     * @param name The brand name to search for.
+     */
+    search(name: string): Promise<Brand[]>;
 }
 
 /**
@@ -98,6 +113,22 @@ interface CategoryAttributeValue {
     id: string;
     name: string;
 }
+/**
+ * Result of `categories.getByBarcodes` — a barcode → category mapping
+ * sourced from Trendyol's Export Center (AutoFT) lookup endpoint.
+ */
+interface BarcodeCategoryLookup {
+    /** Successful matches. */
+    matches: Array<{
+        barcode: string;
+        category: {
+            id: string;
+            name: string;
+        };
+    }>;
+    /** Barcodes Trendyol could not resolve to a category. */
+    notFound: string[];
+}
 /**
  * A required or optional attribute for products in a given category.
  * Use these when constructing a `createProduct V2` payload — the API rejects
@@ -126,27 +157,40 @@ interface CategoryAttribute {
      * NOTE: Trendyol's live API often omits this field on the `getCategoryAttributes`
      * response — the endpoint returns attribute metadata + flags, not the full value
      * catalog. In that case `values` is an empty array. If `allowCustom` is `true`,
-     * any custom text is accepted; otherwise consult Trendyol's separate value
-     * lookup mechanisms (a dedicated `getAttributeValues` endpoint may land in a
-     * future release of this SDK).
+     * any custom text is accepted; otherwise use `client.categories.getAttributeValues(categoryId, attributeId)`
+     * to fetch the catalog from the dedicated V2 endpoint.
      */
     values: CategoryAttributeValue[];
 }
 
+type ListCategoryAttributeValuesParams = CursorPaginationParams;
 /**
  * Trendyol category-tree and category-attribute endpoints.
  *
  * Rate limits (per Trendyol service limits):
  * - Category list: 50 req/min
  * - Category attributes: 50 req/min
+ * - Category attribute values: 50 req/min (same service tier)
  *
- * Both rate counters live on the same Trendyol service, so we share one
- * limiter across both endpoints.
+ * All three counters live on the same Trendyol service, so we share one
+ * limiter across the endpoints.
  */
 declare class CategoriesResource {
     private readonly transport;
+    /**
+     * Trendyol seller (supplier) ID — required only for the AutoFT-scoped
+     * `getByBarcodes` lookup. Other category endpoints don't need it.
+     * Provided automatically when constructed via `createTrendyolClient`.
+     */
+    private readonly sellerId?;
     private readonly limiter;
-    constructor(transport: TrendyolTransport, limiter?: TokenBucketRateLimiter);
+    constructor(transport: TrendyolTransport, limiter?: TokenBucketRateLimiter, 
+    /**
+     * Trendyol seller (supplier) ID — required only for the AutoFT-scoped
+     * `getByBarcodes` lookup. Other category endpoints don't need it.
+     * Provided automatically when constructed via `createTrendyolClient`.
+     */
+    sellerId?: number | undefined);
     /**
      * Fetch the full Trendyol category tree.
      *
@@ -163,6 +207,43 @@ declare class CategoriesResource {
      * @param categoryId Trendyol numeric category ID; accepts `string` or `number`.
      */
     getAttributes(categoryId: string | number): Promise<CategoryAttribute[]>;
+    /**
+     * Fetch the allowed values for a single category attribute (paginated).
+     *
+     * `getCategoryAttributes` returns attribute metadata + flags but typically
+     * omits the value catalog. Use this method to fetch the catalog for an
+     * attribute when `allowCustom` is `false` and you need to map your data
+     * onto Trendyol's accepted values.
+     *
+     * @param categoryId  Trendyol numeric category ID; accepts `string` or `number`.
+     * @param attributeId Attribute ID returned by `getAttributes`.
+     * @param params      Cursor pagination (max page size 1000; default 100).
+     *
+     * @example
+     * ```ts
+     * import { paginate } from '@lonca/core';
+     * for await (const value of paginate((p) =>
+     *   client.categories.getAttributeValues(catId, attrId, p),
+     * )) {
+     *   console.log(value.id, value.name);
+     * }
+     * ```
+     */
+    getAttributeValues(categoryId: string | number, attributeId: string | number, params?: ListCategoryAttributeValuesParams): Promise<CursorPage<CategoryAttributeValue>>;
+    /**
+     * Look up category info for a list of barcodes (Trendyol Export Center
+     * / AutoFT endpoint).
+     *
+     * **Requires Export Center enrollment.** Sellers who have not joined
+     * Trendyol's "İhracat Merkezi" program will get an auth error on this
+     * endpoint even though their regular Marketplace credentials are valid.
+     *
+     * @param barcodes 1–N barcodes to look up.
+     * @throws {ValidationError} when `barcodes` is empty.
+     * @throws Error when the client was created without a `sellerId` and this
+     *   method is called directly (use `createTrendyolClient` to wire it).
+     */
+    getByBarcodes(barcodes: string[]): Promise<BarcodeCategoryLookup>;
 }
 
 /**
@@ -310,6 +391,145 @@ interface PackageHistoryEntry {
     createdAt?: string;
     raw: Record<string, unknown>;
 }
+/**
+ * A package line update tuple used by `updatePackageStatus` and
+ * `cancelPackageItem`. `lineId` is the per-line ID from `ShipmentPackage.lines[].lineId`.
+ */
+interface PackageLineUpdate {
+    lineId: number;
+    quantity: number;
+}
+/**
+ * Input for `orders.updatePackageStatus`. Trendyol restricts the seller-side
+ * status push to `Picking` (mark as being prepared) and `Invoiced`
+ * (invoice issued); other transitions are driven by Trendyol / the cargo
+ * provider. `lines` is optional and only used when transitioning subset of
+ * line items.
+ */
+interface UpdatePackageStatusInput {
+    status: 'Picking' | 'Invoiced';
+    lines?: PackageLineUpdate[];
+}
+/**
+ * Input for `orders.cancelPackageItem` — Trendyol's "supply failure" notification.
+ * Marks specific line items as un-suppliable. `reasonId` is a numeric code
+ * Trendyol publishes separately (e.g. `577` = "tedarik edemiyorum"); consult
+ * Trendyol's seller panel or the "Tedarik Edememe" docs for current values.
+ */
+interface CancelPackageItemInput {
+    lines: PackageLineUpdate[];
+    reasonId: number;
+}
+/**
+ * One row from `orders.getCargoInvoiceItems` — a cargo invoice line item
+ * that ties a parcel ID to its cargo fee. Useful for reconciling Trendyol's
+ * cargo deductions against your shipped packages.
+ */
+interface CargoInvoiceItem {
+    /** e.g. "Gönderi Kargo Bedeli" (outbound) or "İade Kargo Bedeli" (return). */
+    shipmentPackageType?: string;
+    /** Cargo parcel unique ID. */
+    parcelUniqueId?: number | string;
+    orderNumber?: string;
+    /** Fee charged in this row. */
+    amount?: number;
+    /** Desi value used to compute the fee. */
+    desi?: number;
+    /** Untouched raw row. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Filter params for `orders.listStream` — the streaming alternative to
+ * `orders.list`. Uses Trendyol's opaque `nextCursor` (forwarded as the
+ * `@lonca/core` `CursorPaginationParams.cursor`) instead of page-index
+ * pagination.
+ */
+interface ListOrdersStreamParams {
+    cursor?: string;
+    limit?: number;
+    /**
+     * CSV of package-item statuses to filter by (e.g.
+     * `'Created,Picking,Invoiced'`). Trendyol accepts the same status
+     * vocabulary as `ShipmentPackageStatus`.
+     */
+    packageItemStatuses?: string;
+    /** Lower bound for `lastModified` (Trendyol expects ms-epoch). */
+    lastModifiedStartDate?: Date;
+    /** Upper bound for `lastModified`. */
+    lastModifiedEndDate?: Date;
+}
+/**
+ * Box / packaging metadata for `orders.updateBoxInfo`. Both fields are
+ * optional but at least one should be set for the call to be meaningful.
+ */
+interface UpdateBoxInfoInput {
+    /** Desi value (volumetric weight used by Trendyol for shipping cost). */
+    deci?: number;
+    /** Number of physical boxes in the shipment. */
+    boxQuantity?: number;
+}
+/**
+ * Per-line labor cost for `orders.updateLaborCosts`. The Trendyol API
+ * accepts a raw array of these (no envelope) — the SDK forwards as-is.
+ */
+interface LaborCostInput {
+    orderLineId: number;
+    /** Labor cost charged per single unit of this line. */
+    laborCostPerItem: number;
+}
+/**
+ * Trendyol cargo provider codes accepted by `orders.changeCargoProvider`.
+ * Use the string union for autocomplete; `(string & {})` keeps unknown
+ * codes type-compatible so Trendyol can add providers without breaking
+ * callers.
+ */
+type TrendyolCargoProvider = 'YKMP' | 'ARASMP' | 'SURATMP' | 'HOROZMP' | 'DHLECOMMP' | 'PTTMP' | 'CEVAMP' | 'TEXMP' | 'KOLAYGELSINMP' | 'CEVATEDARIK' | (string & {});
+/**
+ * Per-line quantity split for `orders.splitPackageByQuantity`. Each item
+ * in `quantities` becomes its own new package containing that many units
+ * of `orderLineId`.
+ *
+ * @example
+ * // splits 5 units of line 100 into 3 packages: 2 + 2 + 1
+ * { orderLineId: 100, quantities: [2, 2, 1] }
+ */
+interface QuantitySplit {
+    orderLineId: number;
+    quantities: number[];
+}
+/**
+ * A group of line IDs that should become a new package together,
+ * for `orders.multiSplitPackage`.
+ */
+interface SplitGroup {
+    orderLineIds: number[];
+}
+/**
+ * One package's contents for `orders.splitMultiPackagesByQuantity`. Each
+ * element of the outer array becomes a new package; each `packageDetails`
+ * entry carries an `orderLineId` and the **single** quantity assigned to
+ * that package (note: singular `quantities`, despite the field name).
+ */
+interface PackageDetail {
+    orderLineId: number;
+    /** Quantity of this line to include in this package (singular integer). */
+    quantities: number;
+}
+interface SplitPackagePlan {
+    packageDetails: PackageDetail[];
+}
+/**
+ * Input for `orders.processAlternativeDelivery`. Used when the seller is
+ * shipping via a non-Trendyol cargo provider — provide either a phone number
+ * (which Trendyol SMSes the tracking link to) or a direct tracking URL.
+ */
+interface ProcessAlternativeDeliveryInput {
+    /** When true, `trackingInfo` is a phone number; when false, a tracking URL. */
+    isPhoneNumber: boolean;
+    trackingInfo: string;
+    /** Provider-specific extra parameters (Trendyol forwards verbatim). */
+    params: Record<string, string>;
+}
 /**
  * A Trendyol order — Trendyol models orders as "shipment packages". A single
  * customer order may produce multiple shipment packages (one per warehouse,
@@ -407,6 +627,162 @@ declare class OrdersResource {
      * ```
      */
     list(params?: ListOrdersParams): Promise<CursorPage<ShipmentPackage>>;
+    /**
+     * 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.
+     */
+    updatePackageStatus(packageId: string | number, input: UpdatePackageStatusInput): Promise<void>;
+    /**
+     * 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.
+     */
+    cancelPackageItem(packageId: string | number, input: CancelPackageItemInput): Promise<void>;
+    /**
+     * 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.
+     */
+    extendDeliveryDate(packageId: string | number, extendedDayCount: 1 | 2 | 3): Promise<void>;
+    /**
+     * 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.
+     */
+    processAlternativeDelivery(packageId: string | number, input: ProcessAlternativeDeliveryInput): Promise<void>;
+    /**
+     * 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.
+     */
+    splitPackage(packageId: string | number, orderLineIds: number[]): Promise<void>;
+    /**
+     * 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.
+     */
+    splitPackageByQuantity(packageId: string | number, quantitySplit: QuantitySplit[]): Promise<void>;
+    /**
+     * 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.
+     */
+    multiSplitPackage(packageId: string | number, splitGroups: SplitGroup[]): Promise<void>;
+    /**
+     * 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.
+     */
+    splitMultiPackagesByQuantity(packageId: string | number, splitPackages: SplitPackagePlan[]): Promise<void>;
+    /**
+     * 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.
+     */
+    changeCargoProvider(packageId: string | number, cargoProvider: TrendyolCargoProvider): Promise<void>;
+    /**
+     * 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.
+     */
+    manualDeliverByPackageId(packageId: string | number): Promise<void>;
+    /**
+     * 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}/...`.
+     */
+    manualDeliverByTrackingNumber(cargoTrackingNumber: string | number): Promise<void>;
+    /**
+     * 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.
+     */
+    markDeliveredByService(packageId: string | number): Promise<void>;
+    /**
+     * Update box / packaging metadata on a shipment package (desi value
+     * and/or number of boxes). Either field can be sent alone.
+     */
+    updateBoxInfo(packageId: string | number, input: UpdateBoxInfoInput): Promise<void>;
+    /**
+     * 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.
+     */
+    updateLaborCosts(packageId: string | number, items: LaborCostInput[]): Promise<void>;
+    /**
+     * Reassign a shipment package to a different warehouse. `warehouseId`
+     * comes from `client.suppliers.getAddresses()` (filter by `isShipmentAddress`).
+     */
+    updateWarehouse(packageId: string | number, warehouseId: number): Promise<void>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    listStream(params?: ListOrdersStreamParams): Promise<CursorPage<ShipmentPackage>>;
+    /**
+     * 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).
+     */
+    getCargoInvoiceItems(invoiceSerialNumber: string, params?: CursorPaginationParams): Promise<CursorPage<CargoInvoiceItem>>;
+    private packagePath;
 }
 
 /** A `{ id, name }` reference object used in product/category/brand wire types. */
@@ -470,6 +846,117 @@ interface Product {
     /** Untouched raw response — read fields we have not modeled yet. */
     raw: Record<string, unknown>;
 }
+/**
+ * Lifecycle status of an unapproved (draft) product on Trendyol.
+ *
+ * Verified values seen on STAGE/PROD as of 2026-05-25:
+ * - `pendingApproval` — submitted; Trendyol content review in progress.
+ * - `rejected` — review failed; `rejectReasonDetails` is populated.
+ *
+ * Older docs also mention `waiting`. Treat as open-enum (`(string & {})`)
+ * since Trendyol can add new statuses without notice.
+ */
+type UnapprovedProductStatus = 'pendingApproval' | 'waiting' | 'rejected' | (string & {});
+interface UnapprovedProductRejectReason {
+    /** Short title (e.g. "Kategori Bilgisi Eksik veya Yanlış"). */
+    rejectReason?: string;
+    /** Full explanation of the rejection. */
+    rejectReasonDetail?: string;
+}
+/**
+ * An unapproved (draft) product as returned by `filterUnapprovedProducts`.
+ *
+ * Important: the wire shape is **flatter** than the approved-product shape
+ * exposed by `Product` — `barcode`, `quantity`, `salePrice`, etc. live at the
+ * root (no `variants[]` array). Each draft is one barcode/SKU.
+ *
+ * Verified against Trendyol STAGE on 2026-05-25. The official OpenAPI spec
+ * calls the image-list field `media`, but the live API returns it as
+ * `images`. SDK normalizes to `images`.
+ */
+interface UnapprovedProduct {
+    /** Seller (supplier) ID echoed back by Trendyol. */
+    supplierId?: string;
+    productMainId: string;
+    /** Lifecycle status — see `UnapprovedProductStatus`. */
+    status?: UnapprovedProductStatus;
+    brand: NamedRef;
+    category: NamedRef;
+    barcode: string;
+    title: string;
+    description?: string;
+    /** Stock quantity at the moment of the query. */
+    quantity?: number;
+    listPrice?: number;
+    salePrice?: number;
+    /** VAT rate as a percentage (e.g. `20` for 20%). */
+    vatRate?: number;
+    dimensionalWeight?: number;
+    stockCode?: string;
+    /** Image URLs in display order (Trendyol's `images` field, spec says `media`). */
+    images: string[];
+    attributes: ProductAttribute[];
+    /** Populated when `status === 'rejected'`. */
+    rejectReasonDetails: UnapprovedProductRejectReason[];
+    /** Returned by Trendyol; null when the seller has not configured this. */
+    origin?: string | null;
+    locationBasedDelivery?: 'ENABLED' | 'DISABLED' | null;
+    lotNumber?: string | null;
+    /** Special consumption tax (ÖTV) where applicable. */
+    specialConsumptionTax?: number | null;
+    /** Suggested governance retail price (Suggested Government Retail price). */
+    sgrPrice?: number | null;
+    /** ISO 8601 UTC string (from `createDateTime` ms-epoch). */
+    createdAt?: string;
+    /** ISO 8601 UTC string (from `lastUpdateDate`). */
+    updatedAt?: string;
+    /** ISO 8601 UTC string (from `lastPriceChangeDate`). */
+    lastPriceChangedAt?: string;
+    /** ISO 8601 UTC string (from `lastStockChangeDate`). */
+    lastStockChangedAt?: string;
+    /** Untouched raw response. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Basic lifecycle info for a single product, returned by `getProductBase`.
+ *
+ * Cheap to call (no body — just barcode in path) and useful as a polling
+ * primitive after `createProducts` to detect `approved: true`.
+ */
+interface ProductBase {
+    barcode: string;
+    approved: boolean;
+    archived: boolean;
+    /** ISO 8601 UTC string (from `approvedDate` ms-epoch); `undefined` until approved. */
+    approvedAt?: string;
+    /** Stable listing ID assigned after approval. */
+    listingId?: string;
+    /** Trendyol's content ID — the same field on `Product.contentId`. */
+    contentId?: string;
+    /** Untouched raw response. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Buybox status for a single barcode, returned by `getBuyboxInformation`.
+ *
+ * `buyboxOrder === 1` means you currently hold the buybox.
+ * `secondBuyboxPrice` / `thirdBuyboxPrice` are surfaced from live wire (not
+ * in the spec) so you can see what other sellers are charging.
+ */
+interface BuyboxInfo {
+    barcode: string;
+    /** Position in the buybox ranking (1 = you hold it). */
+    buyboxOrder?: number;
+    /** Current buybox-winning price. */
+    buyboxPrice?: number;
+    hasMultipleSeller?: boolean;
+    /** Second-best price (when multiple sellers compete). */
+    secondBuyboxPrice?: number | null;
+    /** Third-best price. */
+    thirdBuyboxPrice?: number | null;
+    /** Untouched raw response. */
+    raw: Record<string, unknown>;
+}
 /**
  * Status of an async batch request returned by `createProducts`,
  * `updatePriceAndInventory`, and other Trendyol bulk endpoints.
@@ -507,6 +994,140 @@ interface BatchRequestResult {
     raw: Record<string, unknown>;
 }
 
+/**
+ * Input types for Trendyol product write endpoints (V2).
+ *
+ * All five write endpoints (`createProducts`, `updateContentBulk`,
+ * `updateVariantBulk`, `updateUnapproved`, `updateDeliveryInfoBulk`) are
+ * async batch operations: SDK accepts the typed payload, Trendyol returns
+ * `{ batchRequestId }`, and the caller polls via `products.getBatchStatus`.
+ */
+/** Response shape for every async write endpoint in the product API. */
+interface BatchAcceptedResponse {
+    /** Opaque ID — pass to `products.getBatchStatus(...)` to track. */
+    batchRequestId: string;
+}
+/** A V2 product attribute payload. Mutually-exclusive value selectors. */
+interface ProductAttributeV2Input {
+    attributeId: number;
+    /**
+     * One or more attribute value IDs (V2 supports multi-value when the
+     * attribute's `allowMultipleAttributeValues` flag is true).
+     */
+    attributeValueIds?: number[];
+    /** Free-text value (only when the attribute's `allowCustom` flag is true). */
+    attributeValue?: string;
+}
+/** Image entry: just a URL (Trendyol fetches the image asynchronously). */
+interface ProductImageInput {
+    /** https URL; Trendyol recommends 1200×1800, 96 DPI. */
+    url: string;
+}
+/** Per-variant delivery option (used by `create` + `updateUnapproved`). */
+interface DeliveryOptionInput {
+    deliveryDuration?: number;
+    fastDeliveryType?: 'SAME_DAY_SHIPPING' | 'FAST_DELIVERY';
+}
+/**
+ * Payload for one item in `createProducts` (V2).
+ *
+ * Trendyol requires all 14 fields listed in the spec — the type makes them
+ * non-optional so missing required fields fail at compile time, not at
+ * runtime after a failed batch.
+ */
+interface CreateProductV2Input {
+    /** Barcode (≤40 chars, allows `.`, `-`, `_`). */
+    barcode: string;
+    /** Title (≤100 chars). */
+    title: string;
+    /** Parent product ID for variant grouping (≤40 chars). */
+    productMainId: string;
+    /** Trendyol numeric brand ID (from `brands.list`). */
+    brandId: number;
+    /** Trendyol numeric category ID (from `categories.list`). */
+    categoryId: number;
+    /** Initial stock quantity. */
+    quantity: number;
+    /** Seller-side stock code (≤100 chars). */
+    stockCode: string;
+    /** Desi value used for shipping cost calculation. */
+    dimensionalWeight: number;
+    /** HTML-friendly product description (≤30 000 chars). */
+    description: string;
+    /** List price (PSF). Must be ≥ `salePrice`. */
+    listPrice: number;
+    /** Sale price (TSF). */
+    salePrice: number;
+    /** 1–8 image URLs. */
+    images: ProductImageInput[];
+    /** VAT rate as integer percent (0, 1, 10, 20). */
+    vatRate: number;
+    /** Required attributes for the category — fetch via `categories.getAttributes`. */
+    attributes: ProductAttributeV2Input[];
+    /** Delivery duration / fast-delivery type. */
+    deliveryOption?: DeliveryOptionInput;
+    /** Lot/SKT info (≤100 chars). */
+    lotNumber?: string | null;
+    /** Shipment warehouse ID (from `suppliers.getAddresses`). */
+    shipmentAddressId?: number;
+    /** Returning warehouse ID. */
+    returningAddressId?: number;
+}
+/** Payload for one item in `updateContentBulk` (only `contentId` is required). */
+interface UpdateContentInput {
+    /** From `Product.contentId` on `products.list` results. */
+    contentId: number;
+    title?: string;
+    description?: string;
+    images?: ProductImageInput[];
+    /**
+     * If you update ANY attribute, you must send ALL attributes — partial
+     * attribute updates are not supported by Trendyol on this endpoint.
+     */
+    attributes?: ProductAttributeV2Input[];
+}
+/**
+ * Payload for one item in `updateVariantBulk`. `barcode` is the identifier;
+ * Trendyol does not allow updating the barcode itself via this endpoint.
+ */
+interface UpdateVariantInput {
+    barcode: string;
+    stockCode?: string;
+    vatRate?: number;
+    shipmentAddressId?: number;
+    returningAddressId?: number;
+    dimensionalWeight?: number;
+    lotNumber?: string | null;
+    locationBasedDelivery?: 'ENABLED' | 'DISABLED' | null;
+}
+/** Payload for one item in `updateUnapprovedProducts` — all optional except `barcode`. */
+interface UpdateUnapprovedInput {
+    barcode: string;
+    title?: string;
+    description?: string;
+    productMainId?: string;
+    brandId?: number;
+    categoryId?: number;
+    stockCode?: string;
+    dimensionalWeight?: number;
+    vatRate?: number;
+    deliveryOption?: DeliveryOptionInput;
+    locationBasedDelivery?: 'ENABLED' | 'DISABLED' | null;
+    lotNumber?: string | null;
+    shipmentAddressId?: number;
+    returningAddressId?: number;
+    images?: ProductImageInput[];
+    attributes?: ProductAttributeV2Input[];
+}
+/** Payload for one item in `updateDeliveryInfoBulk`. */
+interface UpdateDeliveryInfoInput {
+    barcode: string;
+    deliveryOptions?: {
+        deliveryDuration?: number;
+        fastDeliveryType?: 'SAME_DAY_SHIPPING' | 'FAST_DELIVERY';
+    };
+}
+
 interface ListProductsParams extends CursorPaginationParams {
     /** Filter by a single barcode. */
     barcode?: string;
@@ -515,22 +1136,47 @@ interface ListProductsParams extends CursorPaginationParams {
     /** Filter products updated on or before this date. */
     endDate?: Date;
 }
+/** Date field to filter against on `listUnapproved` (default: server choice). */
+type UnapprovedDateQueryType = 'CREATED_DATE' | 'LAST_MODIFIED_DATE';
+interface ListUnapprovedProductsParams extends CursorPaginationParams {
+    barcode?: string;
+    startDate?: Date;
+    endDate?: Date;
+    /** Choose which date `startDate`/`endDate` apply to. */
+    dateQueryType?: UnapprovedDateQueryType;
+    /**
+     * Optional override of the seller-scoped query (rare; defaults to the
+     * client's `sellerId`).
+     */
+    supplierId?: number;
+}
 /**
- * Trendyol product list + batch-result endpoints.
+ * Trendyol product read + write + lifecycle + batch-result endpoints.
  *
  * Rate limits (per Trendyol service limits):
- * - filterProducts: 2000 req/min
+ * - filterProducts (approved + unapproved + getProductBase): 2000 req/min
  * - getBatchRequestResult: 1000 req/min
+ * - getBuyboxInformation: 1000 req/min
+ * - create/update/archive/unlock product writes: 1000 req/min (shared bucket)
+ * - delete: 100 req/min (separate bucket)
  */
 declare class ProductsResource {
     private readonly transport;
     private readonly sellerId;
     private readonly filterLimiter;
     private readonly batchLimiter;
+    private readonly buyboxLimiter;
+    private readonly writeLimiter;
+    private readonly deleteLimiter;
     constructor(transport: TrendyolTransport, sellerId: number, options?: {
         filterLimiter?: TokenBucketRateLimiter;
         batchLimiter?: TokenBucketRateLimiter;
+        buyboxLimiter?: TokenBucketRateLimiter;
+        writeLimiter?: TokenBucketRateLimiter;
+        deleteLimiter?: TokenBucketRateLimiter;
     });
+    private validateBarcodes;
+    private submitWrite;
     /**
      * List approved products. Use `paginate()` from `@lonca/core` to iterate
      * lazily across pages.
@@ -561,6 +1207,142 @@ declare class ProductsResource {
      * @param batchRequestId The opaque ID returned by the originating call.
      */
     getBatchStatus(batchRequestId: string): Promise<BatchRequestResult>;
+    /**
+     * List **unapproved** (draft / rejected / pending-review) products.
+     *
+     * Wire shape is intentionally flatter than the approved-product shape:
+     * each barcode is one top-level item with `barcode`, `quantity`, `salePrice`
+     * etc. at the root. Rejected drafts carry `rejectReasonDetails` so you can
+     * surface why Trendyol's content team turned them down.
+     *
+     * Pagination follows the same convention as `list()`: `cursor` from the
+     * previous response forwards as `nextPageToken`.
+     *
+     * @example
+     * ```ts
+     * const page = await client.products.listUnapproved({ limit: 50 });
+     * for (const draft of page.items) {
+     *   if (draft.status === 'rejected') {
+     *     console.warn(draft.barcode, draft.rejectReasonDetails);
+     *   }
+     * }
+     * ```
+     */
+    listUnapproved(params?: ListUnapprovedProductsParams): Promise<CursorPage<UnapprovedProduct>>;
+    /**
+     * Fetch the basic lifecycle status of a single product by barcode.
+     *
+     * Cheap and useful as a polling primitive after `createProducts`: poll
+     * this endpoint until `approved` flips to `true` (or use
+     * `client.products.getBatchStatus()` to track the originating batch).
+     *
+     * @param barcode The product barcode to look up.
+     */
+    getBase(barcode: string): Promise<ProductBase>;
+    /**
+     * Fetch buybox information for up to 10 barcodes in one call.
+     *
+     * Returns rank (`buyboxOrder === 1` means you hold the buybox), the
+     * current buybox price, and — beyond the spec — the second and third
+     * competing prices when other sellers are present.
+     *
+     * @param barcodes 1–10 product barcodes.
+     * @throws {ValidationError} when `barcodes` is empty or longer than 10.
+     */
+    getBuyboxInfo(barcodes: string[]): Promise<BuyboxInfo[]>;
+    /**
+     * Create products (V2). Async batch — returns a `batchRequestId` you can
+     * poll with `getBatchStatus`. Max 1000 items per call.
+     *
+     * Trendyol requires the full V2 attribute payload — fetch via
+     * `categories.getAttributes` (and `categories.getAttributeValues` for
+     * values when `allowCustom === false`). Shipment / returning warehouse
+     * IDs come from `suppliers.getAddresses`.
+     *
+     * @throws {ValidationError} when `items` is empty or longer than 1000.
+     */
+    create(items: CreateProductV2Input[]): Promise<BatchAcceptedResponse>;
+    /**
+     * Update **content** of approved products (title, description, images,
+     * attributes). Identified by `contentId`. Partial update is supported
+     * except for attributes — if you update ANY attribute, send ALL of them.
+     *
+     * @throws {ValidationError} when `items` is empty or longer than 1000.
+     */
+    updateContent(items: UpdateContentInput[]): Promise<BatchAcceptedResponse>;
+    /**
+     * Update **variant** fields of approved products (stockCode, vatRate,
+     * dimensionalWeight, warehouse IDs, location-based delivery, lot). Identified
+     * by `barcode`. The barcode itself cannot be changed via this endpoint.
+     *
+     * @throws {ValidationError} when `items` is empty or longer than 1000.
+     */
+    updateVariants(items: UpdateVariantInput[]): Promise<BatchAcceptedResponse>;
+    /**
+     * Update **unapproved** (draft) products. Identified by `barcode`. All
+     * other fields are optional partial updates. Use this to fix drafts that
+     * Trendyol rejected — `client.products.listUnapproved` surfaces the
+     * `rejectReasonDetails` you need to act on.
+     *
+     * **Gotcha (verified live STAGE 2026-05-25):** Trendyol's V2 spec claims
+     * only `barcode` is required, but the endpoint returns HTTP 500
+     * (`TrendyolSystemException` / `TypeError`) when too many optional fields
+     * are omitted. In practice, send at least `title`, `description`,
+     * `productMainId`, `brandId`, `categoryId`, `stockCode`,
+     * `dimensionalWeight`, `vatRate`, `images[]`, and `attributes[]` (an
+     * empty array is OK for the latter). The SDK forwards your payload
+     * as-is; trim fields only if you have verified the server accepts it.
+     *
+     * @throws {ValidationError} when `items` is empty or longer than 1000.
+     */
+    updateUnapproved(items: UpdateUnapprovedInput[]): Promise<BatchAcceptedResponse>;
+    /**
+     * Update product **delivery information** (deliveryDuration,
+     * fastDeliveryType). Identified by `barcode`.
+     *
+     * @throws {ValidationError} when `items` is empty or longer than 1000.
+     */
+    updateDeliveryInfo(items: UpdateDeliveryInfoInput[]): Promise<BatchAcceptedResponse>;
+    /**
+     * Delete products by barcode. Trendyol allows deletion of unapproved
+     * products and approved products that have been archived for more than a
+     * day (and have not been sales-stopped by Trendyol).
+     *
+     * Async batch — returns `{ batchRequestId }` to poll via `getBatchStatus`.
+     * Separately rate-limited at **100 req/min** (much tighter than create/update).
+     *
+     * @param barcodes 1–1000 barcodes.
+     * @throws {ValidationError} when `barcodes` is empty or longer than 1000.
+     */
+    delete(barcodes: string[]): Promise<BatchAcceptedResponse>;
+    /**
+     * Archive products by barcode (Trendyol's `archived=true` state).
+     * Archived products are not visible to customers; pair with `delete`
+     * after the 24-hour archive cool-down to remove them entirely.
+     *
+     * Async batch — returns `{ batchRequestId }`.
+     *
+     * @throws {ValidationError} when `barcodes` is empty or longer than 1000.
+     */
+    archive(barcodes: string[]): Promise<BatchAcceptedResponse>;
+    /**
+     * Unarchive products by barcode (Trendyol's `archived=false` state).
+     * Restores visibility for previously-archived products.
+     *
+     * @throws {ValidationError} when `barcodes` is empty or longer than 1000.
+     */
+    unarchive(barcodes: string[]): Promise<BatchAcceptedResponse>;
+    private setArchivedState;
+    /**
+     * Unlock products whose sale was paused by Trendyol due to pricing
+     * issues (under/over-pricing, critical price error, supplier issues).
+     * Restores selling status for the listed barcodes.
+     *
+     * Async batch — returns `{ batchRequestId }`.
+     *
+     * @throws {ValidationError} when `barcodes` is empty or longer than 1000.
+     */
+    unlock(barcodes: string[]): Promise<BatchAcceptedResponse>;
 }
 
 /**
@@ -688,4 +1470,4 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-export { type BatchRequestItemResult, type BatchRequestResult, type BatchRequestStatus, type Brand, BrandsResource, CategoriesResource, type Category, type CategoryAttribute, type CategoryAttributeValue, type CreateClientOptions, InventoryResource, type ListOrdersParams, type ListProductsParams, type NamedRef, type OrderAddress, type OrderAddressLines, type OrderCustomer, type OrderLine, type OrderLineDiscountDetail, OrdersResource, type PackageHistoryEntry, type PriceInventoryUpdate, type Product, type ProductAttribute, type ProductVariant, ProductsResource, type ShipmentPackage, type ShipmentPackageStatus, type SupplierAddress, type SupplierAddressType, SuppliersResource, type SuppliersResourceOptions, type TrendyolClient, type TrendyolEnvironment, type UpdatePriceInventoryResponse, createTrendyolClient };
+export { type BarcodeCategoryLookup, type BatchAcceptedResponse, type BatchRequestItemResult, type BatchRequestResult, type BatchRequestStatus, type Brand, BrandsResource, type BuyboxInfo, type CancelPackageItemInput, type CargoInvoiceItem, CategoriesResource, type Category, type CategoryAttribute, type CategoryAttributeValue, type CreateClientOptions, type CreateProductV2Input, type DeliveryOptionInput, InventoryResource, type LaborCostInput, type ListCategoryAttributeValuesParams, type ListOrdersParams, type ListOrdersStreamParams, type ListProductsParams, type ListUnapprovedProductsParams, type NamedRef, type OrderAddress, type OrderAddressLines, type OrderCustomer, type OrderLine, type OrderLineDiscountDetail, OrdersResource, type PackageDetail, type PackageHistoryEntry, type PackageLineUpdate, type PriceInventoryUpdate, type ProcessAlternativeDeliveryInput, type Product, type ProductAttribute, type ProductAttributeV2Input, type ProductBase, type ProductImageInput, type ProductVariant, ProductsResource, type QuantitySplit, type ShipmentPackage, type ShipmentPackageStatus, type SplitGroup, type SplitPackagePlan, type SupplierAddress, type SupplierAddressType, SuppliersResource, type SuppliersResourceOptions, type TrendyolCargoProvider, type TrendyolClient, type TrendyolEnvironment, type UnapprovedDateQueryType, type UnapprovedProduct, type UnapprovedProductRejectReason, type UnapprovedProductStatus, type UpdateBoxInfoInput, type UpdateContentInput, type UpdateDeliveryInfoInput, type UpdatePackageStatusInput, type UpdatePriceInventoryResponse, type UpdateUnapprovedInput, type UpdateVariantInput, createTrendyolClient };