@lonca/trendyol 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -451,15 +451,56 @@ interface DeleteInvoiceLinkInput {
     [key: string]: unknown;
 }
 /**
- * One row from `finance.getSettlements()` — loosely typed because the
- * settlement schema is broad. Drill into `raw` for any field.
+ * 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 SettlementRow {
-    raw: Record<string, unknown>;
-}
-interface OtherFinancialRow {
+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.
@@ -476,7 +517,19 @@ interface CreateCommonLabelInput {
     /** 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>;
 }
 /**
@@ -524,16 +577,16 @@ interface Neighborhood {
  * 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.
+ * 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<SettlementRow>>;
-    getOtherFinancials(params?: ListFinanceParams): Promise<CursorPage<OtherFinancialRow>>;
+    getSettlements(params?: ListFinanceParams): Promise<CursorPage<FinancialTransaction>>;
+    getOtherFinancials(params?: ListFinanceParams): Promise<CursorPage<FinancialTransaction>>;
     private queryPage;
 }
 
@@ -631,7 +684,14 @@ declare class LabelsResource {
      * @throws {ValidationError} when `format` is missing.
      */
     createCommon(cargoTrackingNumber: string | number, input: CreateCommonLabelInput): Promise<unknown>;
-    /** Retrieve the previously-created common label. */
+    /**
+     * 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>;
 }
 
@@ -1016,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.
  *
@@ -2133,4 +2203,92 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-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 };
+/**
+ * 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 };

package/dist/index.d.ts

@@ -451,15 +451,56 @@ interface DeleteInvoiceLinkInput {
     [key: string]: unknown;
 }
 /**
- * One row from `finance.getSettlements()` — loosely typed because the
- * settlement schema is broad. Drill into `raw` for any field.
+ * 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 SettlementRow {
-    raw: Record<string, unknown>;
-}
-interface OtherFinancialRow {
+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.
@@ -476,7 +517,19 @@ interface CreateCommonLabelInput {
     /** 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>;
 }
 /**
@@ -524,16 +577,16 @@ interface Neighborhood {
  * 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.
+ * 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<SettlementRow>>;
-    getOtherFinancials(params?: ListFinanceParams): Promise<CursorPage<OtherFinancialRow>>;
+    getSettlements(params?: ListFinanceParams): Promise<CursorPage<FinancialTransaction>>;
+    getOtherFinancials(params?: ListFinanceParams): Promise<CursorPage<FinancialTransaction>>;
     private queryPage;
 }
 
@@ -631,7 +684,14 @@ declare class LabelsResource {
      * @throws {ValidationError} when `format` is missing.
      */
     createCommon(cargoTrackingNumber: string | number, input: CreateCommonLabelInput): Promise<unknown>;
-    /** Retrieve the previously-created common label. */
+    /**
+     * 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>;
 }
 
@@ -1016,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.
  *
@@ -2133,4 +2203,92 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-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 };
+/**
+ * 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 };