@lonca/trendyol 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -77,6 +77,1049 @@ 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[]>;
+}
+
+/**
+ * A node in the Trendyol category tree.
+ *
+ * Trendyol exposes categories as a deeply nested structure where each node
+ * can have child categories under `subCategories`. We normalize numeric IDs
+ * to strings to match the `@lonca/core` convention.
+ */
+interface Category {
+    id: string;
+    name: string;
+    /** `null` when this is a root category. */
+    parentId: string | null;
+    subCategories: Category[];
+}
+/** A single allowed value for a category attribute. */
+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
+ * products that omit `required` attributes.
+ */
+interface CategoryAttribute {
+    id: string;
+    name: string;
+    /** The category this attribute belongs to (echoed back by Trendyol). */
+    categoryId?: string;
+    required: boolean;
+    /** Whether the attribute accepts custom text values in addition to the listed ones. */
+    allowCustom: boolean;
+    /** Whether the attribute participates in product variants (e.g. color, size). */
+    varianter: boolean;
+    /** Whether the attribute is used as a price slicer (e.g. size for shoes). */
+    slicer: boolean;
+    /**
+     * V2-only: whether the attribute accepts multiple values at once.
+     * Present on responses from the V2 `getCategoryAttributes` endpoint; absent on V1.
+     */
+    allowMultipleAttributeValues?: boolean;
+    /**
+     * Allowed values for this attribute.
+     *
+     * 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 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)
+ *
+ * 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, 
+    /**
+     * 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.
+     *
+     * Trendyol returns the entire tree in one response — there is no pagination.
+     * Cache the result aggressively in your application; the tree changes rarely.
+     */
+    list(): Promise<Category[]>;
+    /**
+     * Fetch the attributes (required and optional) for a single category.
+     *
+     * Call this before `createProduct V2` so you know which attributes are
+     * mandatory — the API rejects products that omit any `required` attribute.
+     *
+     * @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>;
+}
+
+/**
+ * A single price / stock update entry.
+ *
+ * `barcode` is the only required field. Include any combination of:
+ * - `quantity` to update stock (max 20 000 per product)
+ * - `salePrice` to update the sale price
+ * - `listPrice` to update the list (strikethrough) price
+ *
+ * `listPrice` must be greater than or equal to `salePrice`.
+ */
+interface PriceInventoryUpdate {
+    barcode: string;
+    quantity?: number;
+    salePrice?: number;
+    listPrice?: number;
+}
+/** Response from `updatePriceAndInventory` — poll with `products.getBatchStatus`. */
+interface UpdatePriceInventoryResponse {
+    batchRequestId: string;
+}
+
+/**
+ * Trendyol stock & price update endpoint (a.k.a. `updatePriceAndInventory`).
+ *
+ * Rate limit: **none** — Trendyol explicitly lists this endpoint as
+ * `NO LIMIT` in its service limits table. The `15-minute duplicate
+ * suppression` rule still applies on Trendyol's side, but that's a
+ * server-side concern.
+ *
+ * The endpoint is asynchronous. The response carries a `batchRequestId`
+ * you can poll with `client.products.getBatchStatus(batchRequestId)` —
+ * Trendyol retains the result for 4 hours.
+ */
+declare class InventoryResource {
+    private readonly transport;
+    private readonly sellerId;
+    constructor(transport: TrendyolTransport, sellerId: number);
+    /**
+     * Update price and/or stock for one or more SKUs (by barcode).
+     *
+     * @example
+     * ```ts
+     * const { batchRequestId } = await client.inventory.update([
+     *   { barcode: 'ABC123', quantity: 42, salePrice: 199.9, listPrice: 249.9 },
+     *   { barcode: 'XYZ789', quantity: 0 },
+     * ]);
+     * const status = await client.products.getBatchStatus(batchRequestId);
+     * ```
+     *
+     * @throws {ValidationError} when `items` is empty or longer than 1000.
+     */
+    update(items: PriceInventoryUpdate[]): Promise<UpdatePriceInventoryResponse>;
+}
+
+/**
+ * Trendyol shipment-package status.
+ *
+ * Trendyol uses ~13 distinct values (Created, Picking, Invoiced, Shipped,
+ * Cancelled, Delivered, UnDelivered, Returned, UnSupplied, Awaiting,
+ * UnPacked, AtCollectionPoint, Verified). Typed as a union with an open
+ * escape so unknown values still type-check.
+ */
+type ShipmentPackageStatus = 'Created' | 'Picking' | 'Invoiced' | 'Shipped' | 'Cancelled' | 'Delivered' | 'UnDelivered' | 'Returned' | 'UnSupplied' | 'Awaiting' | 'UnPacked' | 'AtCollectionPoint' | 'Verified' | (string & {});
+interface OrderAddressLines {
+    addressLine1?: string;
+    addressLine2?: string;
+}
+/**
+ * A customer or invoice/shipment address returned alongside a shipment package.
+ * Field set is conservative — Trendyol returns many optional locality fields
+ * and we surface them as-is.
+ */
+interface OrderAddress {
+    id?: string;
+    firstName?: string;
+    lastName?: string;
+    fullName?: string;
+    company?: string;
+    address1?: string;
+    address2?: string;
+    fullAddress?: string;
+    shortAddress?: string;
+    city?: string;
+    cityCode?: number;
+    district?: string;
+    districtId?: number;
+    neighborhoodId?: number;
+    countyId?: number;
+    countyName?: string;
+    stateName?: string;
+    postalCode?: string;
+    countryCode?: string;
+    phone?: string;
+    addressLines?: OrderAddressLines;
+}
+/** Customer details on a shipment package (a subset of what Trendyol exposes). */
+interface OrderCustomer {
+    id?: string;
+    firstName: string;
+    lastName: string;
+    email?: string;
+    taxNumber?: string;
+    identityNumber?: string;
+}
+interface OrderLineDiscountDetail {
+    lineItemPrice?: number;
+    lineItemSellerDiscount?: number;
+    lineItemTyDiscount?: number;
+}
+/** A single item line inside a shipment package. */
+interface OrderLine {
+    /** Trendyol's `lineId`. */
+    id: string;
+    quantity: number;
+    productName: string;
+    barcode: string;
+    productSize?: string;
+    productColor?: string;
+    stockCode?: string;
+    contentId?: string;
+    sellerId?: string;
+    productCategoryId?: string;
+    salesCampaignId?: string;
+    currencyCode?: string;
+    lineUnitPrice: number;
+    lineGrossAmount: number;
+    lineSellerDiscount?: number;
+    lineTyDiscount?: number;
+    lineTotalDiscount?: number;
+    vatRate?: number;
+    commission?: number;
+    orderLineItemStatusName?: string;
+    businessUnit?: string;
+    fastDeliveryOptions?: unknown[];
+    discountDetails?: OrderLineDiscountDetail[];
+    /** Untouched raw line response. */
+    raw: Record<string, unknown>;
+}
+/** A status transition entry in `packageHistories`. */
+interface PackageHistoryEntry {
+    status?: ShipmentPackageStatus;
+    /** ISO 8601 UTC string (converted from Trendyol's ms-epoch). */
+    createdAt?: string;
+    raw: Record<string, unknown>;
+}
+/**
+ * A Trendyol order — Trendyol models orders as "shipment packages". A single
+ * customer order may produce multiple shipment packages (one per warehouse,
+ * one per cancellation, etc.).
+ *
+ * `id` is the `shipmentPackageId` (the operational unit); `orderNumber`
+ * groups packages that came from the same customer order.
+ */
+interface ShipmentPackage {
+    /** `shipmentPackageId` — the operational identifier for this package. */
+    id: string;
+    orderNumber: string;
+    shipmentNumber?: string;
+    originPackageIds?: string[] | null;
+    warehouseId?: string;
+    supplierId?: string;
+    status: ShipmentPackageStatus;
+    /** Usually identical to `status`; surfaced for completeness. */
+    shipmentPackageStatus?: ShipmentPackageStatus;
+    customer: OrderCustomer;
+    orderDate: string;
+    lastModifiedDate: string;
+    agreedDeliveryDate?: string;
+    estimatedDeliveryStartDate?: string;
+    estimatedDeliveryEndDate?: string;
+    originShipmentDate?: string;
+    currencyCode: string;
+    packageTotalPrice: number;
+    packageGrossAmount: number;
+    packageSellerDiscount: number;
+    packageTyDiscount: number;
+    packageTotalDiscount: number;
+    invoiceAddress?: OrderAddress;
+    shipmentAddress?: OrderAddress;
+    deliveryAddressType?: string;
+    cargoTrackingNumber?: string;
+    cargoProviderName?: string;
+    cargoProviderId?: string;
+    cargoSenderNumber?: string;
+    deliveryType?: string;
+    whoPays?: number;
+    timeSlotId?: number;
+    fastDelivery?: boolean;
+    fastDeliveryType?: string;
+    deliveredByService?: boolean;
+    commercial?: boolean;
+    micro?: boolean;
+    giftBoxRequested?: boolean;
+    /** Renamed from Trendyol's wire field `3pByTrendyol` (identifier cannot start with a digit). */
+    threePByTrendyol?: boolean;
+    containsDangerousProduct?: boolean;
+    isCod?: boolean;
+    is4P?: boolean;
+    invoiceLink?: string;
+    createdBy?: string;
+    lines: OrderLine[];
+    packageHistories: PackageHistoryEntry[];
+    /** Untouched raw response for fields not modeled yet. */
+    raw: Record<string, unknown>;
+}
+
+interface ListOrdersParams extends CursorPaginationParams {
+    status?: ShipmentPackageStatus;
+    orderNumber?: string;
+    /** Filter packages updated on or after this date (Trendyol expects ms-epoch). */
+    startDate?: Date;
+    /** Filter packages updated on or before this date. */
+    endDate?: Date;
+}
+/**
+ * Trendyol order (shipment-package) endpoints.
+ *
+ * Rate limit (per Trendyol service limits): scheduled to tighten on 2026-05-15;
+ * for now we set a generous default that the user can tune via the constructor.
+ *
+ * Pagination: Trendyol uses page-based pagination here (not nextPageToken).
+ * The SDK still exposes `CursorPage<ShipmentPackage>` so the caller can
+ * iterate with `paginate()` from `@lonca/core`; the opaque cursor encodes the
+ * page index.
+ */
+declare class OrdersResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    /**
+     * List shipment packages for the seller.
+     *
+     * @example
+     * ```ts
+     * import { paginate } from '@lonca/core';
+     * for await (const pkg of paginate((p) => client.orders.list({ ...p, status: 'Created' }))) {
+     *   console.log(pkg.id, pkg.status, pkg.customer.firstName);
+     * }
+     * ```
+     */
+    list(params?: ListOrdersParams): Promise<CursorPage<ShipmentPackage>>;
+}
+
+/** A `{ id, name }` reference object used in product/category/brand wire types. */
+interface NamedRef {
+    id: string;
+    name: string;
+}
+/**
+ * A single attribute on a Trendyol product or variant.
+ *
+ * `attributeValueId` and `attributeValue` are mutually exclusive in createProduct
+ * payloads but can both be present in filter responses.
+ */
+interface ProductAttribute {
+    attributeId: string;
+    attributeName?: string;
+    attributeValueId?: string;
+    attributeValue?: string;
+}
+/**
+ * A variant of a Trendyol product — the actual purchasable SKU.
+ *
+ * Trendyol scopes barcode + stock + commission to the variant level even for
+ * products that only have a single variant. To read a product's barcode use
+ * `product.variants[0].barcode`.
+ */
+interface ProductVariant {
+    variantId: string;
+    barcode: string;
+    commission?: number;
+    attributes: ProductAttribute[];
+    productUrl?: string;
+    onSale?: boolean;
+    /** Stock quantity (when the response includes stock data). */
+    stock?: number;
+    /** Untouched raw response for fields not modeled yet. */
+    raw: Record<string, unknown>;
+}
+/**
+ * A Trendyol marketplace product (approved variant).
+ *
+ * Lonca surfaces the stable fields we have verified against live Trendyol
+ * responses. Everything else stays accessible via `raw`.
+ */
+interface Product {
+    contentId: string;
+    productMainId: string;
+    title: string;
+    description?: string;
+    brand: NamedRef;
+    category: NamedRef;
+    /** Image URLs in display order. */
+    images: string[];
+    attributes: ProductAttribute[];
+    variants: ProductVariant[];
+    /** ISO 8601 UTC string (converted from Trendyol's ms-epoch). */
+    createdAt: string;
+    /** ISO 8601 UTC string. */
+    updatedAt: string;
+    lastModifiedBy?: string;
+    /** 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.
+ */
+type BatchRequestStatus = 'PROCESSING' | 'COMPLETED' | 'FAILED' | (string & {});
+interface BatchRequestItemResult {
+    requestItem?: unknown;
+    status?: string;
+    failureReasons?: string[];
+}
+/**
+ * Result of polling `getBatchRequestResult` for a previously-submitted batch.
+ *
+ * Trendyol retains batch results for **4 hours** after the originating request.
+ */
+interface BatchRequestResult {
+    batchRequestId: string;
+    status: BatchRequestStatus;
+    itemCount?: number;
+    failedItemCount?: number;
+    items: BatchRequestItemResult[];
+    /** ISO 8601 UTC string (converted from Trendyol's ms-epoch). */
+    createdAt?: string;
+    /** ISO 8601 UTC string. */
+    lastModifiedAt?: string;
+    /** Trendyol category of submission (e.g. `MarketPlace`). */
+    sourceType?: string;
+    /** Operation type (e.g. `CreateProducts`, `PriceUpdate`). */
+    batchRequestType?: string;
+    notes?: string;
+    /** Storage object key Trendyol uses internally for the batch payload. */
+    objectKey?: string;
+    storeFrontCode?: string;
+    /** Untouched raw response. */
+    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;
+    /** Filter products updated on or after this date (Trendyol expects ms-epoch). */
+    startDate?: Date;
+    /** 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 read + write + lifecycle + batch-result endpoints.
+ *
+ * Rate limits (per Trendyol service limits):
+ * - 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.
+     *
+     * Trendyol exposes both page-based and `nextPageToken`-based pagination
+     * (the latter required when the dataset exceeds 10,000 items). The SDK
+     * picks the right strategy automatically — pass our opaque `cursor` from
+     * the previous response and we forward it as `nextPageToken`.
+     *
+     * @example
+     * ```ts
+     * import { paginate } from '@lonca/core';
+     * for await (const product of paginate((p) => client.products.list(p))) {
+     *   for (const variant of product.variants) {
+     *     console.log(variant.barcode, product.title);
+     *   }
+     * }
+     * ```
+     */
+    list(params?: ListProductsParams): Promise<CursorPage<Product>>;
+    /**
+     * Poll a batch request returned by an async write (e.g. `createProducts`,
+     * `updatePriceAndInventory`).
+     *
+     * Trendyol retains batch results for **4 hours** after the originating
+     * request — poll within that window.
+     *
+     * @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>;
+}
+
+/**
+ * The role an address plays in the seller's logistics flow.
+ *
+ * Trendyol allows a single physical address to play more than one role
+ * (e.g., shipment + invoice), so always check the boolean flags rather than
+ * relying solely on `addressType`.
+ */
+type SupplierAddressType = 'SHIPMENT' | 'RETURNING' | 'INVOICE' | 'WAREHOUSE';
+/**
+ * A supplier address registered in the Trendyol Partner Panel.
+ *
+ * Used by `createProduct V2` for `shipmentAddressId` / `returningAddressId`.
+ *
+ * NOTE: The exact field set is best-effort; some optional fields may differ
+ * once verified against real STAGE responses. Bumped fields land in a follow-up
+ * minor release if needed.
+ */
+interface SupplierAddress {
+    id: string;
+    /** Free-form label set by the seller. */
+    name?: string;
+    /** Primary role declared by Trendyol. */
+    addressType: SupplierAddressType;
+    isShipmentAddress: boolean;
+    isReturningAddress: boolean;
+    isInvoiceAddress: boolean;
+    isDefault: boolean;
+    /** Multi-line address string as registered in the Partner Panel. */
+    address?: string;
+    city?: string;
+    district?: string;
+    postCode?: string;
+    fullName?: string;
+}
+
+interface SuppliersResourceOptions {
+    /** Override the in-memory cache TTL. Defaults to 1 hour. */
+    cacheTtlMs?: number;
+}
+/**
+ * Trendyol supplier address endpoints.
+ *
+ * **Critical:** Trendyol rate-limits `getSuppliersAddresses` to **1 request
+ * per hour per seller**. This resource therefore wraps the endpoint with an
+ * in-memory cache (default TTL: 1 hour) so callers can request addresses
+ * as often as needed without tripping the limit.
+ *
+ * Use `{ forceRefresh: true }` or `invalidateCache()` only when you know the
+ * address list changed in the Partner Panel.
+ */
+declare class SuppliersResource {
+    private readonly transport;
+    private readonly sellerId;
+    private cache;
+    private readonly cacheTtlMs;
+    private readonly limiter;
+    private inflight;
+    constructor(transport: TrendyolTransport, sellerId: number, options?: SuppliersResourceOptions);
+    /**
+     * List the seller's registered addresses (shipment, returning, invoice, warehouse).
+     *
+     * Returns the cached value if it is still fresh. Concurrent calls share a
+     * single in-flight request.
+     */
+    getAddresses(options?: {
+        forceRefresh?: boolean;
+    }): Promise<SupplierAddress[]>;
+    /** Drop the cache; the next `getAddresses()` call hits the API. */
+    invalidateCache(): void;
+    private fetchFresh;
 }
 
 interface CreateClientOptions {
@@ -107,6 +1150,11 @@ interface CreateClientOptions {
 }
 interface TrendyolClient {
     brands: BrandsResource;
+    categories: CategoriesResource;
+    suppliers: SuppliersResource;
+    products: ProductsResource;
+    inventory: InventoryResource;
+    orders: OrdersResource;
 }
 /**
  * Create a Trendyol Marketplace SDK client.
@@ -127,4 +1175,4 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-export { type Brand, BrandsResource, type CreateClientOptions, type TrendyolClient, type TrendyolEnvironment, createTrendyolClient };
+export { type BarcodeCategoryLookup, type BatchAcceptedResponse, type BatchRequestItemResult, type BatchRequestResult, type BatchRequestStatus, type Brand, BrandsResource, type BuyboxInfo, CategoriesResource, type Category, type CategoryAttribute, type CategoryAttributeValue, type CreateClientOptions, type CreateProductV2Input, type DeliveryOptionInput, InventoryResource, type ListCategoryAttributeValuesParams, type ListOrdersParams, type ListProductsParams, type ListUnapprovedProductsParams, type NamedRef, type OrderAddress, type OrderAddressLines, type OrderCustomer, type OrderLine, type OrderLineDiscountDetail, OrdersResource, type PackageHistoryEntry, type PriceInventoryUpdate, type Product, type ProductAttribute, type ProductAttributeV2Input, type ProductBase, type ProductImageInput, type ProductVariant, ProductsResource, type ShipmentPackage, type ShipmentPackageStatus, type SupplierAddress, type SupplierAddressType, SuppliersResource, type SuppliersResourceOptions, type TrendyolClient, type TrendyolEnvironment, type UnapprovedDateQueryType, type UnapprovedProduct, type UnapprovedProductRejectReason, type UnapprovedProductStatus, type UpdateContentInput, type UpdateDeliveryInfoInput, type UpdatePriceInventoryResponse, type UpdateUnapprovedInput, type UpdateVariantInput, createTrendyolClient };