@lonca/trendyol 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -246,6 +246,297 @@ declare class CategoriesResource {
     getByBarcodes(barcodes: string[]): Promise<BarcodeCategoryLookup>;
 }
 
+/**
+ * Trendyol claim ("iade" / return-claim) types.
+ *
+ * A claim is a customer-initiated return on a delivered order. The
+ * seller can also open a `createClaimIssue` (a rejection) against a
+ * customer-filed claim, and either party can have line items approved
+ * via `approveClaimLineItems`.
+ */
+
+/** One item inside `claims.create()`. */
+interface CreateClaimItemInput {
+    /** Barcode of the ordered SKU. */
+    barcode: string;
+    /** Number of units being returned. */
+    quantity: number;
+    /**
+     * Numeric reason code customers select on trendyol.com.
+     * Trendyol's docs note `401` ("Vazgectim" — changed my mind) as a
+     * safe default when you don't have a more specific code.
+     */
+    reasonId: number;
+    /** Free-text note from the customer. */
+    customerNote?: string;
+}
+/** Payload for `claims.create()`. */
+interface CreateClaimInput {
+    /** The order to file the claim against. */
+    orderNumber: string;
+    claimItems: CreateClaimItemInput[];
+    /** Trendyol customer ID (the one who placed the order). */
+    customerId?: number;
+    /** Suppress this claim from listing pages. */
+    excludeListing?: boolean;
+    /** Force a new shipment package to be created for the return. */
+    forcePackageCreation?: boolean;
+}
+/**
+ * Payload for `claims.createIssue()` — file a seller-side rejection
+ * ("ret talebi") against a customer claim. Wire format is
+ * `multipart/form-data` because optional `files` are PDF / JPEG
+ * supporting documents.
+ */
+interface CreateClaimIssueInput {
+    /** Numeric reason ID from `claims.getIssueReasons()`. */
+    claimIssueReasonId: number;
+    /** Per-line claim item IDs being rejected. SDK joins with commas. */
+    claimItemIdList: string[];
+    /** Free-text explanation (≤500 chars). */
+    description: string;
+    /** Optional supporting documents (Blob / File). */
+    files?: Blob[];
+}
+/** Payload for `claims.approveLineItems()`. */
+interface ApproveClaimLineItemsInput {
+    /** Claim line-item IDs to approve. */
+    claimLineItemIdList: string[];
+    /** Optional extra params Trendyol forwards verbatim. */
+    params?: Record<string, string>;
+}
+/**
+ * Claim item lifecycle state. Open enum — Trendyol can add new states
+ * without breaking callers.
+ */
+type ClaimItemStatus = 'Created' | 'WaitingInAction' | 'WaitingFraudCheck' | 'Accepted' | 'Unresolved' | 'Rejected' | (string & {});
+/** Filter / pagination for `claims.list()`. */
+interface ListClaimsParams extends CursorPaginationParams {
+    startDate?: Date;
+    endDate?: Date;
+    /** Filter claims by item-level status. */
+    claimItemStatus?: ClaimItemStatus;
+}
+/**
+ * A return claim. Trendyol returns ~20 fields; the SDK surfaces the
+ * stable subset and keeps everything else on `raw`.
+ */
+interface Claim {
+    /** Claim ID (Trendyol returns it under both `id` and `claimId` — same value). */
+    id: string;
+    orderNumber: string;
+    /** ISO 8601 UTC (from ms-epoch `orderDate`). */
+    orderDate?: string;
+    /** ISO 8601 UTC (from ms-epoch `claimDate`). */
+    claimDate?: string;
+    customerFirstName?: string;
+    customerLastName?: string;
+    /** Untouched raw claim — pull undocumented fields from here. */
+    raw: Record<string, unknown>;
+}
+/** Rejection-reason catalog row from `claims.getIssueReasons()`. */
+interface ClaimIssueReason {
+    id: number;
+    name: string;
+}
+/**
+ * Audit entry for a single claim item, returned by `claims.getItemAudits()`.
+ * Trendyol's response shape varies; only `raw` is guaranteed.
+ */
+interface ClaimItemAudit {
+    /** Untouched raw audit row. */
+    raw: Record<string, unknown>;
+}
+
+/**
+ * Trendyol claims (return / iade) endpoints.
+ *
+ * Rate limit (per Trendyol service limits): shares the order service bucket;
+ * the SDK provisions its own 1000 req/min limiter that the caller can override.
+ */
+declare class ClaimsResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    /**
+     * Create a return claim against an order. Use this to file a return on
+     * behalf of a customer (e.g. when they called your CS line). For
+     * customer-initiated returns coming from trendyol.com, you receive them
+     * via `claims.list()` — no need to call `create`.
+     *
+     * Returns whatever Trendyol returns (typically the new claim's identifier).
+     *
+     * @throws {ValidationError} when `claimItems` is empty.
+     */
+    create(input: CreateClaimInput): Promise<unknown>;
+    /**
+     * File a seller-side rejection ("ret talebi") against a customer claim.
+     *
+     * **Wire format: `multipart/form-data`** — the SDK builds the FormData
+     * internally from the typed input. `claimItemIdList` is joined with
+     * commas (Trendyol expects a single comma-separated string field).
+     * Attach supporting docs (PDF / JPEG) via `files: [Blob, ...]`.
+     */
+    createIssue(claimId: string, input: CreateClaimIssueInput): Promise<unknown>;
+    /**
+     * Approve specific claim line items. After approval, Trendyol moves
+     * those line items into the post-approval refund / return-shipping flow.
+     *
+     * @throws {ValidationError} when `claimLineItemIdList` is empty.
+     */
+    approveLineItems(claimId: string, input: ApproveClaimLineItemsInput): Promise<unknown>;
+    /**
+     * List claims (page-based; SDK exposes opaque cursor convention).
+     *
+     * @example
+     * ```ts
+     * import { paginate } from '@lonca/core';
+     * for await (const c of paginate((p) =>
+     *   client.claims.list({ ...p, claimItemStatus: 'WaitingInAction' }),
+     * )) {
+     *   console.log(c.id, c.orderNumber, c.claimDate);
+     * }
+     * ```
+     */
+    list(params?: ListClaimsParams): Promise<CursorPage<Claim>>;
+    /**
+     * Fetch the catalog of rejection-reason IDs the seller can use on
+     * `claims.createIssue()`. Cache the result — it changes rarely.
+     *
+     * Note: this endpoint is **not seller-scoped** (no `sellerId` in path).
+     */
+    getIssueReasons(): Promise<ClaimIssueReason[]>;
+    /**
+     * Fetch the audit log for a single claim item (state transitions,
+     * actor, timestamp). Trendyol's response shape varies — the SDK
+     * surfaces each row as `{ raw }` and leaves field extraction to the
+     * caller until we observe a stable shape on the wire.
+     */
+    getItemAudits(claimItemId: string): Promise<ClaimItemAudit[]>;
+}
+
+/**
+ * Misc types for Trendyol's smaller surfaces — invoices, finance,
+ * common labels, test orders, and location lookups. Most shapes are
+ * loosely typed (`Record<string, unknown>`) because the Trendyol response
+ * shapes here are wide and seldom-evolved; callers drill into `raw` for
+ * fields beyond the stable surface.
+ */
+
+interface UploadInvoiceFileInput {
+    /** Trendyol shipment package ID (required). */
+    shipmentPackageId: number;
+    /** Invoice file (PDF / JPEG / PNG, max 10 MB). */
+    file: Blob;
+    /** ms-epoch — mandatory for micro-export orders, optional otherwise. */
+    invoiceDateTime?: number;
+    /**
+     * Invoice number — mandatory for micro-export orders. Format:
+     * `[A-Za-z0-9]{3}(20[2-9][0-9])\d{9}`.
+     */
+    invoiceNumber?: string;
+}
+interface SendInvoiceLinkInput {
+    invoiceLink: string;
+    shipmentPackageId: number;
+    invoiceDateTime?: number;
+    invoiceNumber?: string;
+}
+interface DeleteInvoiceLinkInput {
+    serviceSourceId?: number;
+    channelId?: number;
+    customerId?: number;
+    /** Forward-compatible: pass any extra fields Trendyol may add. */
+    [key: string]: unknown;
+}
+/**
+ * One row from `finance.getSettlements()` — loosely typed because the
+ * settlement schema is broad. Drill into `raw` for any field.
+ */
+interface SettlementRow {
+    raw: Record<string, unknown>;
+}
+interface OtherFinancialRow {
+    raw: Record<string, unknown>;
+}
+/**
+ * Shared filter shape for both finance endpoints.
+ * `transactionType` lets you scope to one settlement category.
+ */
+interface ListFinanceParams extends CursorPaginationParams {
+    startDate?: Date;
+    endDate?: Date;
+    transactionType?: string;
+}
+interface CreateCommonLabelInput {
+    /** Currently the only documented format Trendyol accepts. */
+    format: 'ZPL' | (string & {});
+    boxQuantity?: number;
+    /** Volumetric height (height × width × depth / 3000 → desi). */
+    volumetricHeight?: number;
+}
+interface CommonLabel {
+    raw: Record<string, unknown>;
+}
+/**
+ * Payload for `testOrders.create()`. Top-level requireds are
+ * `customer`, `invoiceAddress`, `lines`, `seller`, `shippingAddress`;
+ * each sub-object has its own field rules (see Trendyol's
+ * `createTestOrder` reference). Kept loose because the inner schema is
+ * deep and used only in STAGE.
+ */
+interface CreateTestOrderInput {
+    customer: Record<string, unknown>;
+    invoiceAddress: Record<string, unknown>;
+    shippingAddress: Record<string, unknown>;
+    seller: Record<string, unknown>;
+    lines: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+type TestOrderStatus = 'Created' | 'Picking' | 'Invoiced' | 'Shipped' | 'Delivered' | 'Cancelled' | 'Returned' | 'UnDelivered' | (string & {});
+interface Country {
+    /** ISO country code (e.g. `'TR'`, `'AZ'`). */
+    code: string;
+    name?: string;
+    raw: Record<string, unknown>;
+}
+interface City {
+    code: string;
+    name?: string;
+    countryCode?: string;
+    raw: Record<string, unknown>;
+}
+interface District {
+    code: string;
+    name?: string;
+    cityCode?: string;
+    raw: Record<string, unknown>;
+}
+interface Neighborhood {
+    code: string;
+    name?: string;
+    districtCode?: string;
+    raw: Record<string, unknown>;
+}
+
+/**
+ * Trendyol finance endpoints — current-account-statement settlements and
+ * "other financials" (cargo invoices, labor cost adjustments, etc.).
+ *
+ * Both rows are kept as `{ raw }` because the schemas are wide and
+ * evolve frequently; drill into `raw` for any field.
+ */
+declare class FinanceResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    getSettlements(params?: ListFinanceParams): Promise<CursorPage<SettlementRow>>;
+    getOtherFinancials(params?: ListFinanceParams): Promise<CursorPage<OtherFinancialRow>>;
+    private queryPage;
+}
+
 /**
  * A single price / stock update entry.
  *
@@ -300,6 +591,75 @@ declare class InventoryResource {
     update(items: PriceInventoryUpdate[]): Promise<UpdatePriceInventoryResponse>;
 }
 
+/**
+ * Trendyol invoice endpoints — upload PDF/JPEG/PNG invoice files or
+ * register/delete invoice links. Pair these with `orders.updatePackageStatus(_, { status: 'Invoiced' })`
+ * after invoice issuance.
+ */
+declare class InvoicesResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    /**
+     * Upload an invoice file for a shipment package. **Multipart**: the
+     * SDK builds the FormData internally from the typed input.
+     *
+     * Max 10 MB. Accepted formats: PDF, JPEG, PNG.
+     */
+    uploadFile(input: UploadInvoiceFileInput): Promise<unknown>;
+    /** Register an invoice URL with Trendyol (alternative to uploading the file). */
+    sendLink(input: SendInvoiceLinkInput): Promise<unknown>;
+    /** Remove a previously-registered invoice link. */
+    deleteLink(input: DeleteInvoiceLinkInput): Promise<unknown>;
+}
+
+/**
+ * Common-label (ortak etiket) endpoints — request and retrieve a
+ * combined ZPL shipping label for a cargo tracking number.
+ */
+declare class LabelsResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    /**
+     * Request a common ZPL label for a cargo tracking number. After this
+     * returns, call `getCommon()` with the same `cargoTrackingNumber` to
+     * retrieve the generated label.
+     *
+     * @throws {ValidationError} when `format` is missing.
+     */
+    createCommon(cargoTrackingNumber: string | number, input: CreateCommonLabelInput): Promise<unknown>;
+    /** Retrieve the previously-created common label. */
+    getCommon(cargoTrackingNumber: string | number): Promise<CommonLabel>;
+}
+
+/**
+ * Trendyol location lookups for building shipment / invoice addresses
+ * with the correct city / district / neighborhood codes.
+ *
+ * Trendyol exposes these under a different prefix (`/integration/member/`)
+ * — not under `/integration/order/` or `/integration/product/`.
+ */
+declare class LocationsResource {
+    private readonly transport;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, limiter?: TokenBucketRateLimiter);
+    /** List all supported countries (Türkiye + AZ + GULF + CEE). */
+    getCountries(): Promise<Country[]>;
+    getTurkeyCities(): Promise<City[]>;
+    getTurkeyDistricts(cityCode: string | number): Promise<District[]>;
+    getTurkeyNeighborhoods(cityCode: string | number, districtCode: string | number): Promise<Neighborhood[]>;
+    getAzerbaijanCities(): Promise<City[]>;
+    getAzerbaijanDistricts(cityCode: string | number): Promise<District[]>;
+    getCitiesByCountry(countryCode: string): Promise<City[]>;
+    getDistrictsByCity(countryCode: string, cityId: string | number): Promise<District[]>;
+    private cities;
+    private districts;
+    private neighborhoods;
+}
+
 /**
  * Trendyol shipment-package status.
  *
@@ -391,6 +751,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,
@@ -452,6 +951,63 @@ interface ShipmentPackage {
     raw: Record<string, unknown>;
 }
 
+/**
+ * Returns + compensation types for Trendyol orders.
+ *
+ * Trendyol distinguishes two separate concepts:
+ * - **Manual return** — seller-side notification that a package was
+ *   received back (no body, just a state flip on the package).
+ * - **Compensation ticket** — Trendyol Express-specific dispute filed
+ *   when a shipment is lost or damaged. Multi-state lifecycle with up to
+ *   ~18 documented states.
+ */
+
+/**
+ * Lifecycle state of a Trendyol Express compensation ticket. Trendyol
+ * documents 18 distinct states (`Empty`, `MarkInCompensation`,
+ * `CompensationApproved`, etc.) — kept as an open enum so unknown future
+ * values still type-check.
+ *
+ * Verified against the official spec on 2026-05-25.
+ */
+type CompensationTicketState = 'Empty' | 'MarkInCompensation' | 'OpenedForRefund' | 'StartCompensationFinanceProgress' | 'StartCompensationInApprovalProgress' | 'CompensationApproved' | 'CompensationRejected' | 'FoundAfterCompensationComplete' | 'NotCompensationCase' | 'FoundInCompensation' | 'FoundInvestigationProgress' | 'MarkCompensationCancel' | 'CreateCompensationTicket' | 'FinalizeCompensation' | 'CloseCompensationTicket' | 'FoundInvestigationProgressDeliveredToCustomer' | 'FoundInCompensationDeliveredToCustomer' | 'FoundAfterCompensationCompleteDeliveredToCustomer' | (string & {});
+/** One line item under a compensation ticket. */
+interface CompensationItemDetail {
+    /** Amount (e.g. unit price). */
+    itemAmount?: number;
+    itemCode?: string;
+    /** Item count (number of units claimed). */
+    itemCount?: number;
+    itemName?: string;
+}
+/**
+ * A Trendyol Express compensation ticket — filed when a shipment is lost
+ * or damaged in transit. Returned by `orders.getCompensationTickets()`.
+ */
+interface CompensationTicket {
+    cargoProvider?: string;
+    compensateReason?: string;
+    /** ISO 8601 UTC string (converted from `createDate` ms-epoch). */
+    createdAt?: string;
+    currentState?: CompensationTicketState;
+    deliveryNumber?: string;
+    itemDetails: CompensationItemDetail[];
+    orderNumber?: string;
+    requestedBy?: string;
+    stateMessage?: string;
+    /** Total amount across items — Trendyol returns this as a string. */
+    totalItemsAmount?: string;
+    /** Untouched raw ticket response. */
+    raw: Record<string, unknown>;
+}
+/** Filter / pagination params for `orders.getCompensationTickets()`. */
+interface ListCompensationTicketsParams extends CursorPaginationParams {
+    /** Lower bound on `createDate` (Trendyol expects ms-epoch). */
+    startDate?: Date;
+    /** Upper bound on `createDate`. */
+    endDate?: Date;
+}
+
 interface ListOrdersParams extends CursorPaginationParams {
     status?: ShipmentPackageStatus;
     orderNumber?: string;
@@ -488,6 +1044,199 @@ 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>>;
+    /**
+     * Notify Trendyol that a shipped package was returned to you (manual
+     * return flow, e.g. customer dropped it at your address or you got the
+     * package back without going through Trendyol's return cargo).
+     *
+     * No body; Trendyol responds with 200 + empty body on success.
+     */
+    manualReturnByPackageId(packageId: string | number): Promise<void>;
+    /**
+     * Manual-return variant that takes the cargo tracking number instead of
+     * the package ID. Useful when the cargo provider's webhook only carries
+     * the tracking number.
+     *
+     * Sibling path (not under `/{packageId}/...`).
+     */
+    manualReturnByTrackingNumber(cargoTrackingNumber: string | number): Promise<void>;
+    /**
+     * Fetch Trendyol Express compensation tickets (claims filed when a
+     * shipment is lost or damaged in transit). Page-based pagination
+     * internally; the SDK exposes the cursor convention.
+     *
+     * Note the different base path — `/integration/tex/compensation/...`,
+     * not the regular `/integration/order/...`.
+     *
+     * @example
+     * ```ts
+     * import { paginate } from '@lonca/core';
+     * const tickets = await client.orders.getCompensationTickets({
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-02-01'),
+     * });
+     * for (const t of tickets.items) {
+     *   console.log(t.orderNumber, t.currentState, t.stateMessage);
+     * }
+     * ```
+     */
+    getCompensationTickets(params?: ListCompensationTicketsParams): Promise<CursorPage<CompensationTicket>>;
+    private packagePath;
 }
 
 /** A `{ id, name }` reference object used in product/category/brand wire types. */
@@ -1050,6 +1799,86 @@ declare class ProductsResource {
     unlock(barcodes: string[]): Promise<BatchAcceptedResponse>;
 }
 
+/**
+ * Trendyol customer Q&A types.
+ *
+ * Customers can post product questions on Trendyol; sellers reply via
+ * `questions.answer()`. Status lifecycle:
+ *   `WAITING_FOR_ANSWER` → seller replies → `ANSWERED`
+ *                       → reported by another seller / Trendyol → `REPORTED`
+ *                       → rejected by Trendyol moderation → `REJECTED`
+ */
+
+type QuestionStatus = 'WAITING_FOR_ANSWER' | 'ANSWERED' | 'REJECTED' | 'REPORTED' | (string & {});
+interface QuestionAnswer {
+    text?: string;
+    /** ISO 8601 UTC (converted from `creationDate` ms-epoch). */
+    createdAt?: string;
+    status?: string;
+}
+interface Question {
+    id: string;
+    text?: string;
+    customerId?: string;
+    /** Masked customer display name. */
+    userName?: string;
+    showUserName?: boolean;
+    status?: QuestionStatus;
+    /** Whether the question is visible publicly. */
+    public?: boolean;
+    productMainId?: string;
+    productName?: string;
+    imageUrl?: string;
+    webUrl?: string;
+    /** ISO 8601 UTC (from ms-epoch). */
+    createdAt?: string;
+    /** Trendyol's pre-formatted "answered on ..." message (Turkish). */
+    answeredDateMessage?: string;
+    answer?: QuestionAnswer;
+    rejectedAnswer?: QuestionAnswer;
+    /** ISO 8601 UTC if the question was rejected. */
+    rejectedAt?: string;
+    reason?: string;
+    reportReason?: string;
+    /** ISO 8601 UTC if the question was reported. */
+    reportedAt?: string;
+    /** Untouched raw response. */
+    raw: Record<string, unknown>;
+}
+interface ListQuestionsParams extends CursorPaginationParams {
+    /** Filter to questions about a specific product barcode. */
+    barcode?: string;
+    startDate?: Date;
+    endDate?: Date;
+    /** Filter by current status. */
+    status?: QuestionStatus;
+}
+
+/**
+ * Trendyol customer Q&A management. Customers post product questions on
+ * Trendyol; sellers reply with `questions.answer()`.
+ */
+declare class QuestionsResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    /** Fetch a single question by its numeric ID. */
+    get(questionId: string | number): Promise<Question>;
+    /**
+     * Filter questions by barcode / date range / status. Page-based
+     * pagination internally; SDK exposes the opaque-cursor convention.
+     */
+    list(params?: ListQuestionsParams): Promise<CursorPage<Question>>;
+    /**
+     * Reply to a question. Trendyol enforces 10–2000 characters on the
+     * answer text; the SDK pre-validates client-side.
+     *
+     * @throws {ValidationError} when `text` is outside the 10–2000 char range.
+     */
+    answer(questionId: string | number, text: string): Promise<unknown>;
+}
+
 /**
  * The role an address plays in the seller's logistics flow.
  *
@@ -1122,6 +1951,127 @@ declare class SuppliersResource {
     private fetchFresh;
 }
 
+/**
+ * STAGE-only helper endpoints for creating + driving test orders /
+ * test claims through their state machine. **Do not use in PROD** —
+ * Trendyol's test endpoints are scoped to the test environment.
+ */
+declare class TestOrdersResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    /**
+     * Create a test order with the given customer / addresses / lines. The
+     * SDK forwards the typed payload verbatim — drill into Trendyol's
+     * `createTestOrder` doc for inner field rules.
+     *
+     * @throws {ValidationError} when required top-level fields are missing.
+     */
+    create(input: CreateTestOrderInput): Promise<unknown>;
+    /** Push a test shipment package to the given status. */
+    updateStatus(packageId: string | number, status: TestOrderStatus): Promise<unknown>;
+    /** Move test claims to the `WaitingInAction` state. */
+    setClaimsWaitingInAction(): Promise<unknown>;
+}
+
+/**
+ * Trendyol webhook subscription types.
+ *
+ * Webhooks let Trendyol push shipment-package status events to a URL you
+ * own instead of polling. Max 15 active webhooks per seller. Trendyol
+ * itself authenticates against your endpoint (you don't sign Trendyol's
+ * request) — pick `BASIC_AUTHENTICATION` (username+password) or `API_KEY`
+ * (rotatable; recommended).
+ */
+
+/** Auth method Trendyol uses when calling your webhook URL. */
+type WebhookAuthenticationType = 'BASIC_AUTHENTICATION' | 'API_KEY';
+/**
+ * Payload for `webhooks.create` / `webhooks.update`. Same shape for both.
+ */
+interface WebhookInput {
+    /** Your endpoint URL (must accept POST JSON from Trendyol). */
+    url: string;
+    /** Auth scheme Trendyol will use to call your endpoint. */
+    authenticationType: WebhookAuthenticationType;
+    /** Username (only when `authenticationType === 'BASIC_AUTHENTICATION'`). */
+    username?: string;
+    /** Password (only when `authenticationType === 'BASIC_AUTHENTICATION'`). */
+    password?: string;
+    /** API key (only when `authenticationType === 'API_KEY'`). */
+    apiKey?: string;
+    /**
+     * Order statuses you want events for. Empty/omitted = all statuses.
+     * Trendyol accepts the same vocabulary as `ShipmentPackageStatus`
+     * (the upper-snake-case variants — `'CREATED'`, `'PICKING'`, etc. — see
+     * Trendyol docs for the exact wire spelling, which sometimes differs
+     * from the read-side `'Created'`/`'Picking'`).
+     */
+    subscribedStatuses?: string[];
+}
+/** A registered webhook subscription as returned by `webhooks.list`. */
+interface Webhook {
+    id: string;
+    url?: string;
+    authenticationType?: WebhookAuthenticationType;
+    username?: string;
+    apiKey?: string;
+    subscribedStatuses?: string[];
+    /** Active vs deactivated. */
+    active?: boolean;
+    /** Untouched raw webhook entry. */
+    raw: Record<string, unknown>;
+}
+
+/**
+ * Trendyol webhook subscription management.
+ *
+ * Max **15 active webhooks per seller** (Trendyol-enforced). Webhooks
+ * fire on shipment-package status events only — there is no webhook
+ * support for product / stock changes.
+ *
+ * Trendyol's gateway authenticates **against your endpoint** with the
+ * `authenticationType` you configure. Pick `API_KEY` over
+ * `BASIC_AUTHENTICATION` so you can rotate the secret without redeploying.
+ *
+ * No HMAC signature — security relies entirely on the auth method you
+ * pick + the secret you store with Trendyol.
+ */
+declare class WebhooksResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    /**
+     * Create a new webhook subscription. Trendyol caps subscriptions at 15
+     * per seller — the SDK does NOT pre-check (you'd need to call `list()`
+     * first), but Trendyol returns 400 when the cap is exceeded.
+     *
+     * @throws {ValidationError} when `url` or `authenticationType` is missing.
+     */
+    create(input: WebhookInput): Promise<unknown>;
+    /** List all registered webhook subscriptions. */
+    list(): Promise<Webhook[]>;
+    /**
+     * Update a webhook subscription. Same input shape as `create`; replaces
+     * the whole subscription (Trendyol does NOT partially update).
+     */
+    update(webhookId: string | number, input: WebhookInput): Promise<unknown>;
+    /** Permanently delete a webhook subscription. */
+    delete(webhookId: string | number): Promise<unknown>;
+    /** Re-activate a previously-deactivated webhook subscription. */
+    activate(webhookId: string | number): Promise<unknown>;
+    /**
+     * Deactivate a webhook subscription. Trendyol automatically deactivates
+     * a subscription after persistent delivery failures (and sends 2 emails);
+     * use `activate()` to bring it back online once your endpoint is healthy.
+     */
+    deactivate(webhookId: string | number): Promise<unknown>;
+    private validateInput;
+    private webhookPath;
+}
+
 interface CreateClientOptions {
     /** Trendyol seller (supplier) ID — visible in Partner Panel → Account Info. */
     sellerId: number;
@@ -1155,6 +2105,14 @@ interface TrendyolClient {
     products: ProductsResource;
     inventory: InventoryResource;
     orders: OrdersResource;
+    claims: ClaimsResource;
+    webhooks: WebhooksResource;
+    questions: QuestionsResource;
+    invoices: InvoicesResource;
+    finance: FinanceResource;
+    labels: LabelsResource;
+    testOrders: TestOrdersResource;
+    locations: LocationsResource;
 }
 /**
  * Create a Trendyol Marketplace SDK client.
@@ -1175,4 +2133,4 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-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 };
+export { type ApproveClaimLineItemsInput, 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 City, type Claim, type ClaimIssueReason, type ClaimItemAudit, type ClaimItemStatus, ClaimsResource, type CommonLabel, type CompensationItemDetail, type CompensationTicket, type CompensationTicketState, type Country, type CreateClaimInput, type CreateClaimIssueInput, type CreateClaimItemInput, type CreateClientOptions, type CreateCommonLabelInput, type CreateProductV2Input, type CreateTestOrderInput, type DeleteInvoiceLinkInput, type DeliveryOptionInput, type District, FinanceResource, InventoryResource, InvoicesResource, LabelsResource, type LaborCostInput, type ListCategoryAttributeValuesParams, type ListClaimsParams, type ListCompensationTicketsParams, type ListFinanceParams, type ListOrdersParams, type ListOrdersStreamParams, type ListProductsParams, type ListQuestionsParams, type ListUnapprovedProductsParams, LocationsResource, type NamedRef, type Neighborhood, type OrderAddress, type OrderAddressLines, type OrderCustomer, type OrderLine, type OrderLineDiscountDetail, OrdersResource, type OtherFinancialRow, 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 Question, type QuestionAnswer, type QuestionStatus, QuestionsResource, type SendInvoiceLinkInput, type SettlementRow, type ShipmentPackage, type ShipmentPackageStatus, type SplitGroup, type SplitPackagePlan, type SupplierAddress, type SupplierAddressType, SuppliersResource, type SuppliersResourceOptions, type TestOrderStatus, TestOrdersResource, 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, type UploadInvoiceFileInput, type Webhook, type WebhookAuthenticationType, type WebhookInput, WebhooksResource, createTrendyolClient };