@lonca/trendyol 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -79,6 +79,562 @@ declare class BrandsResource {
     list(params?: CursorPaginationParams): Promise<CursorPage<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;
+}
+/**
+ * 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 consult Trendyol's separate value
+     * lookup mechanisms (a dedicated `getAttributeValues` endpoint may land in a
+     * future release of this SDK).
+     */
+    values: CategoryAttributeValue[];
+}
+
+/**
+ * Trendyol category-tree and category-attribute endpoints.
+ *
+ * Rate limits (per Trendyol service limits):
+ * - Category list: 50 req/min
+ * - Category attributes: 50 req/min
+ *
+ * Both rate counters live on the same Trendyol service, so we share one
+ * limiter across both endpoints.
+ */
+declare class CategoriesResource {
+    private readonly transport;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, limiter?: TokenBucketRateLimiter);
+    /**
+     * 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[]>;
+}
+
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+
+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;
+}
+/**
+ * Trendyol product list + batch-result endpoints.
+ *
+ * Rate limits (per Trendyol service limits):
+ * - filterProducts: 2000 req/min
+ * - getBatchRequestResult: 1000 req/min
+ */
+declare class ProductsResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly filterLimiter;
+    private readonly batchLimiter;
+    constructor(transport: TrendyolTransport, sellerId: number, options?: {
+        filterLimiter?: TokenBucketRateLimiter;
+        batchLimiter?: TokenBucketRateLimiter;
+    });
+    /**
+     * 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>;
+}
+
+/**
+ * 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 {
     /** Trendyol seller (supplier) ID — visible in Partner Panel → Account Info. */
     sellerId: number;
@@ -107,6 +663,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 +688,4 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-export { type Brand, BrandsResource, type CreateClientOptions, type TrendyolClient, type TrendyolEnvironment, createTrendyolClient };
+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 };