@lonca/trendyol 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -246,6 +246,350 @@ 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 Trendyol's current-account statement — returned by both
+ * `finance.getSettlements()` and `finance.getOtherFinancials()` (both
+ * endpoints share the `FinancialTransaction` wire schema).
+ *
+ * Field set verified against the spec on 2026-05-25. The SDK exposes the
+ * stable subset; anything Trendyol adds later remains accessible via `raw`.
+ */
+interface FinancialTransaction {
+    /** Transaction ID (string per Trendyol). */
+    id: string;
+    /** ISO 8601 UTC (from ms-epoch `transactionDate`). */
+    transactionDate?: string;
+    /** Product barcode when the transaction is tied to a SKU. */
+    barcode?: string | null;
+    /** Transaction category (e.g. `'Satış'`, `'Ödeme'`). */
+    transactionType?: string;
+    /** Receipt ID ("dekont no") when applicable. */
+    receiptId?: number | null;
+    description?: string | null;
+    /** Debit amount on the seller's account. */
+    debt?: number;
+    /** Credit amount on the seller's account. */
+    credit?: number;
+    paymentPeriod?: number | null;
+    commissionRate?: number | null;
+    commissionAmount?: number | null;
+    commissionInvoiceSerialNumber?: string | null;
+    /** Net seller revenue after Trendyol's cut. */
+    sellerRevenue?: number | null;
+    orderNumber?: string | null;
+    paymentOrderId?: number | null;
+    /** ISO 8601 UTC (from ms-epoch `paymentDate`). */
+    paymentDate?: string;
+    sellerId?: number;
+    storeId?: number | null;
+    storeName?: string | null;
+    storeAddress?: string | null;
+    country?: string | null;
+    /** Untouched raw row — pull any undocumented fields from here. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Aliases preserved for source-compatibility with `0.5.0`. Both legacy
+ * names now resolve to the unified `FinancialTransaction`.
+ *
+ * @deprecated since `0.5.1` — use `FinancialTransaction`.
+ */
+type SettlementRow = FinancialTransaction;
+/** @deprecated since `0.5.1` — use `FinancialTransaction`. */
+type OtherFinancialRow = FinancialTransaction;
+/**
+ * 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;
+}
+/** One label entry inside a `CommonLabel` response. */
+interface CommonLabelEntry {
+    /** Encoded label payload (e.g. ZPL string `^XA...^XZ`). */
+    label: string;
+    format: 'ZPL' | (string & {});
+}
+/**
+ * Response from `labels.getCommon()` — Trendyol's wire shape is
+ * `{ data: [{ label, format }] }`. SDK surfaces the array directly via
+ * `labels` for ergonomic access; `raw` is the untouched response.
+ */
+interface CommonLabel {
+    labels: CommonLabelEntry[];
+    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 endpoints return the same `FinancialTransaction` shape on the wire,
+ * so the SDK exposes one typed surface for them.
+ */
+declare class FinanceResource {
+    private readonly transport;
+    private readonly sellerId;
+    private readonly limiter;
+    constructor(transport: TrendyolTransport, sellerId: number, limiter?: TokenBucketRateLimiter);
+    getSettlements(params?: ListFinanceParams): Promise<CursorPage<FinancialTransaction>>;
+    getOtherFinancials(params?: ListFinanceParams): Promise<CursorPage<FinancialTransaction>>;
+    private queryPage;
+}
+
 /**
  * A single price / stock update entry.
  *
@@ -300,6 +644,82 @@ 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. Trendyol returns
+     * `{ data: [{ label, format }] }`; the SDK surfaces the array as
+     * `labels[]` for ergonomic access.
+     *
+     * Typically `labels.length === 1` per tracking number, but kept as an
+     * array to match the wire shape.
+     */
+    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.
  *
@@ -591,6 +1011,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;
@@ -599,6 +1076,16 @@ interface ListOrdersParams extends CursorPaginationParams {
     /** Filter packages updated on or before this date. */
     endDate?: Date;
 }
+/**
+ * Normalize one raw Trendyol shipment-package node into the public
+ * `ShipmentPackage` shape. Exported so consumers handling Trendyol
+ * webhooks can reuse the SDK's normalization logic on the event body
+ * (Trendyol POSTs the same shape it returns from `getShipmentPackages`).
+ *
+ * For full-webhook parsing use `parseWebhookEvent(rawBody)` from the
+ * top-level package, which calls this internally per item.
+ */
+declare function normalizeShipmentPackage(rawNode: unknown): ShipmentPackage;
 /**
  * Trendyol order (shipment-package) endpoints.
  *
@@ -782,6 +1269,43 @@ declare class OrdersResource {
      * 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;
 }
 
@@ -1345,6 +1869,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.
  *
@@ -1417,6 +2021,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;
@@ -1450,6 +2175,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.
@@ -1470,4 +2203,92 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-export { type BarcodeCategoryLookup, type BatchAcceptedResponse, type BatchRequestItemResult, type BatchRequestResult, type BatchRequestStatus, type Brand, BrandsResource, type BuyboxInfo, type CancelPackageItemInput, type CargoInvoiceItem, CategoriesResource, type Category, type CategoryAttribute, type CategoryAttributeValue, type CreateClientOptions, type CreateProductV2Input, type DeliveryOptionInput, InventoryResource, type LaborCostInput, type ListCategoryAttributeValuesParams, type ListOrdersParams, type ListOrdersStreamParams, type ListProductsParams, type ListUnapprovedProductsParams, type NamedRef, type OrderAddress, type OrderAddressLines, type OrderCustomer, type OrderLine, type OrderLineDiscountDetail, OrdersResource, type PackageDetail, type PackageHistoryEntry, type PackageLineUpdate, type PriceInventoryUpdate, type ProcessAlternativeDeliveryInput, type Product, type ProductAttribute, type ProductAttributeV2Input, type ProductBase, type ProductImageInput, type ProductVariant, ProductsResource, type QuantitySplit, type ShipmentPackage, type ShipmentPackageStatus, type SplitGroup, type SplitPackagePlan, type SupplierAddress, type SupplierAddressType, SuppliersResource, type SuppliersResourceOptions, type TrendyolCargoProvider, type TrendyolClient, type TrendyolEnvironment, type UnapprovedDateQueryType, type UnapprovedProduct, type UnapprovedProductRejectReason, type UnapprovedProductStatus, type UpdateBoxInfoInput, type UpdateContentInput, type UpdateDeliveryInfoInput, type UpdatePackageStatusInput, type UpdatePriceInventoryResponse, type UpdateUnapprovedInput, type UpdateVariantInput, createTrendyolClient };
+/**
+ * Inbound webhook event payloads — what Trendyol POSTs to YOUR endpoint
+ * when a subscribed shipment-package status event fires.
+ *
+ * Per Trendyol's "Webhook Model" doc:
+ *   - Method: POST, body: JSON
+ *   - Wire shape: identical to `getShipmentPackages` response envelope
+ *     (`{ totalElements, totalPages, page, size, content: [...] }`)
+ *   - Sent on every status transition for a subscribed status (see
+ *     `WebhookEventStatus` below) — the full order data is delivered
+ *     each time, not a delta.
+ *
+ * Trendyol authenticates against YOUR endpoint using the method you
+ * configured on the subscription (BASIC_AUTHENTICATION or API_KEY). The
+ * SDK does NOT validate auth on its end — handle that in your request
+ * middleware before passing the body to `parseWebhookEvent`.
+ *
+ * Retry: on a non-2xx response, Trendyol retries every 5 minutes; after
+ * persistent failures the subscription is auto-deactivated (you'll get
+ * 2 emails). Reactivate via `client.webhooks.activate(id)` once your
+ * endpoint is healthy again.
+ */
+
+/**
+ * Status values Trendyol sends as the event trigger. Note the
+ * **upper-snake-case** spelling here, distinct from `ShipmentPackageStatus`
+ * (which uses PascalCase on the API read responses).
+ */
+type WebhookEventStatus = 'CREATED' | 'PICKING' | 'INVOICED' | 'SHIPPED' | 'CANCELLED' | 'DELIVERED' | 'UNDELIVERED' | 'RETURNED' | 'UNSUPPLIED' | 'AWAITING' | 'UNPACKED' | 'AT_COLLECTION_POINT' | 'VERIFIED' | (string & {});
+/**
+ * Origin of a package, surfaced as `ShipmentPackage.createdBy` on the
+ * normalized event payload. Useful for routing logic (e.g. trigger a
+ * different flow for `'split'` packages than `'order-creation'`).
+ */
+type PackageCreatedBy = 'order-creation' | 'cancel' | 'split' | 'transfer' | (string & {});
+/**
+ * The parsed webhook event body. `packages` is the normalized
+ * `content[]` from the inbound JSON; `pageInfo` carries Trendyol's
+ * pagination envelope verbatim so you can log / surface it.
+ *
+ * In practice `packages.length === 1` for status-change events, but the
+ * model is defined as a page so the same handler can absorb future
+ * batch events without breaking.
+ */
+interface WebhookEvent {
+    packages: ShipmentPackage[];
+    pageInfo: {
+        totalElements?: number;
+        totalPages?: number;
+        page?: number;
+        size?: number;
+    };
+    /** Raw inbound body — fall back here for fields the SDK doesn't surface. */
+    raw: Record<string, unknown>;
+}
+
+/**
+ * Top-level helper for parsing incoming Trendyol webhook event bodies
+ * into the SDK's typed shape.
+ *
+ * Usage in an Express route:
+ *
+ * ```ts
+ * import { parseWebhookEvent } from '@lonca/trendyol';
+ *
+ * app.post('/trendyol/webhook', express.json(), (req, res) => {
+ *   const event = parseWebhookEvent(req.body);
+ *   for (const pkg of event.packages) {
+ *     // pkg: typed ShipmentPackage — same shape as orders.list()
+ *     await myQueue.enqueue({ packageId: pkg.id, status: pkg.status });
+ *   }
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+
+/**
+ * Parse an inbound webhook body into a typed `WebhookEvent`.
+ *
+ * Accepts either an already-parsed object or a JSON string. Returns
+ * normalized `ShipmentPackage[]` (the same shape `orders.list()`
+ * produces), plus the page envelope and the raw body for fallthrough.
+ *
+ * @throws {ValidationError} when the body isn't an object / valid JSON,
+ *   or when `content` is missing or not an array.
+ */
+declare function parseWebhookEvent(rawBody: unknown): WebhookEvent;
+
+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 CommonLabelEntry, 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, type FinancialTransaction, 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 PackageCreatedBy, 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 WebhookEvent, type WebhookEventStatus, type WebhookInput, WebhooksResource, createTrendyolClient, normalizeShipmentPackage, parseWebhookEvent };