@lonca/trendyol 0.12.0 → 0.14.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="left">
-  <img src="https://raw.githubusercontent.com/loncadev/lonca/main/assets/brand/icon.svg" alt="Lonca" height="32">
+  <img src="https://raw.githubusercontent.com/loncadev/.github/main/brand/logomark.svg" alt="Lonca" height="32">
 </p>
 
 # @lonca/trendyol
@@ -53,13 +53,12 @@ pnpm add @lonca/trendyol @lonca/core
 # or npm install / yarn add
 ```
 
-`@lonca/core` is a peer dependency (provides `paginate`, `CursorPage`, error classes, the token-bucket limiter).
+`@lonca/core` is a peer dependency (error classes, the token-bucket limiter). The `paginate` / `paginateOffset` helpers and the `CursorPage` / `OffsetPage` types are re-exported from `@lonca/trendyol`, so you can import them straight from this package.
 
 ## Quick start
 
 ```ts
-import { createTrendyolClient } from '@lonca/trendyol';
-import { paginate } from '@lonca/core';
+import { createTrendyolClient, paginate } from '@lonca/trendyol';
 
 const client = createTrendyolClient({
   sellerId: 12345,
@@ -203,7 +202,8 @@ const start = new Date('2026-05-01');
 const end = new Date('2026-05-31');
 
 for await (const tx of paginate((p) =>
-  client.finance.getSettlements({ ...p, startDate: start, endDate: end }),
+  // `transactionType` is required (Trendyol 500s without it); `limit` is clamped to 500/1000.
+  client.finance.getSettlements({ ...p, startDate: start, endDate: end, transactionType: 'Sale' }),
 )) {
   // tx is a typed FinancialTransaction — no .raw drill required for documented fields
   if (tx.transactionType === 'Satış' && tx.orderNumber) {
@@ -349,7 +349,7 @@ await client.invoices.sendLink({ shipmentPackageId: 100, invoiceLink: 'https://x
 await client.invoices.deleteLink({ serviceSourceId: 1, channelId: 2, customerId: 3 });
 
 // finance — typed FinancialTransaction[]
-await client.finance.getSettlements({ startDate, endDate });
+await client.finance.getSettlements({ startDate, endDate, transactionType: 'Sale' }); // transactionType required
 await client.finance.getOtherFinancials({ transactionType: 'DeductionInvoices' });
 
 // labels

package/dist/{client-BJjLOn4v.d.cts → client-CtygosAW.d.cts}

@@ -1,4 +1,4 @@
-import { Logger, BaseRequestOptions, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, OffsetPaginationParams } from '@lonca/core';
+import { Logger, BaseRequestOptions, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, MutationResult, OffsetPaginationParams } from '@lonca/core';
 
 declare const BASE_URLS: {
     readonly prod: "https://apigw.trendyol.com";
@@ -349,7 +349,7 @@ declare class ClaimsResource {
      *
      * @throws {ValidationError} when `claimItems` is empty.
      */
-    create(input: CreateClaimInput): Promise<unknown>;
+    create(input: CreateClaimInput): Promise<MutationResult>;
     /**
      * File a seller-side rejection ("ret talebi") against a customer claim.
      *
@@ -358,14 +358,14 @@ declare class ClaimsResource {
      * commas (Trendyol expects a single comma-separated string field).
      * Attach supporting docs (PDF / JPEG) via `files: [Blob, ...]`.
      */
-    createIssue(claimId: string, input: CreateClaimIssueInput): Promise<unknown>;
+    createIssue(claimId: string, input: CreateClaimIssueInput): Promise<MutationResult>;
     /**
      * 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>;
+    approveLineItems(claimId: string, input: ApproveClaimLineItemsInput): Promise<MutationResult>;
     /**
      * List claims (page-based; SDK exposes opaque cursor convention).
      *
@@ -696,7 +696,17 @@ type OtherFinancialRow = FinancialTransaction;
 interface ListFinanceParams extends CursorPaginationParams {
     startDate?: Date;
     endDate?: Date;
+    /**
+     * **Required** by Trendyol's CHE finance API (it returns 500 without one),
+     * e.g. `'Sale'`, `'Return'`, `'Discount'`, `'DeductionInvoices'`. The SDK
+     * throws a `ValidationError` if omitted.
+     */
     transactionType?: string;
+    /**
+     * Page size. Trendyol's finance API only accepts **500 or 1000** — the SDK
+     * clamps any value to the nearest of those (default 500).
+     */
+    limit?: number;
 }
 interface CreateCommonLabelInput {
     /** Currently the only documented format Trendyol accepts. */
@@ -743,18 +753,28 @@ interface Country {
     raw: Record<string, unknown>;
 }
 interface City {
+    /**
+     * Trendyol's internal city id — the value the **nested** endpoints expect
+     * (`getTurkeyDistricts(city.id)`). Distinct from `code` (the plate-style
+     * display code, e.g. `"1"` for Adana); passing `code` there returns 500.
+     */
+    id?: string;
     code: string;
     name?: string;
     countryCode?: string;
     raw: Record<string, unknown>;
 }
 interface District {
+    /** Trendyol's internal district id — pass to `getTurkeyNeighborhoods(cityId, district.id)`. */
+    id?: string;
     code: string;
     name?: string;
     cityCode?: string;
     raw: Record<string, unknown>;
 }
 interface Neighborhood {
+    /** Trendyol's internal neighborhood id. */
+    id?: string;
     code: string;
     name?: string;
     districtCode?: string;
@@ -835,13 +855,16 @@ interface ProductVariant {
     raw: Record<string, unknown>;
 }
 /**
- * A Trendyol marketplace product (approved variant).
+ * The content fields shared by an approved {@link Product} and an unapproved
+ * (draft) {@link UnapprovedProduct} — so callers can read title / brand /
+ * category / images from either shape without branching.
  *
- * Lonca surfaces the stable fields we have verified against live Trendyol
- * responses. Everything else stays accessible via `raw`.
+ * Intentionally just the common surface: the two diverge structurally beyond
+ * this (`Product` carries `variants[]`; `UnapprovedProduct` is flat with a root
+ * `barcode`), and their timestamp fields differ in optionality, so those stay on
+ * the concrete types.
  */
-interface Product {
-    contentId: string;
+interface ProductContentBase {
     productMainId: string;
     title: string;
     description?: string;
@@ -850,6 +873,15 @@ interface Product {
     /** Image URLs in display order. */
     images: string[];
     attributes: ProductAttribute[];
+}
+/**
+ * A Trendyol marketplace product (approved variant).
+ *
+ * Lonca surfaces the stable fields we have verified against live Trendyol
+ * responses. Everything else stays accessible via `raw`.
+ */
+interface Product extends ProductContentBase {
+    contentId: string;
     variants: ProductVariant[];
     /** ISO 8601 UTC string (converted from Trendyol's ms-epoch). */
     createdAt: string;
@@ -887,17 +919,12 @@ interface UnapprovedProductRejectReason {
  * calls the image-list field `media`, but the live API returns it as
  * `images`. SDK normalizes to `images`.
  */
-interface UnapprovedProduct {
+interface UnapprovedProduct extends ProductContentBase {
     /** Seller (supplier) ID echoed back by Trendyol. */
     supplierId?: string;
-    productMainId: string;
     /** Lifecycle status — see `UnapprovedProductStatus`. */
     status?: UnapprovedProductStatus;
-    brand: NamedRef;
-    category: NamedRef;
     barcode: string;
-    title: string;
-    description?: string;
     /** Stock quantity at the moment of the query. */
     quantity?: number;
     listPrice?: number;
@@ -906,9 +933,6 @@ interface UnapprovedProduct {
     vatRate?: number;
     dimensionalWeight?: number;
     stockCode?: string;
-    /** Image URLs in display order (Trendyol's `images` field, spec says `media`). */
-    images: string[];
-    attributes: ProductAttribute[];
     /** Populated when `status === 'rejected'`. */
     rejectReasonDetails: UnapprovedProductRejectReason[];
     /** Returned by Trendyol; null when the seller has not configured this. */
@@ -1145,11 +1169,11 @@ declare class InvoicesResource {
      *
      * Max 10 MB. Accepted formats: PDF, JPEG, PNG.
      */
-    uploadFile(input: UploadInvoiceFileInput): Promise<unknown>;
+    uploadFile(input: UploadInvoiceFileInput): Promise<MutationResult>;
     /** Register an invoice URL with Trendyol (alternative to uploading the file). */
-    sendLink(input: SendInvoiceLinkInput): Promise<unknown>;
+    sendLink(input: SendInvoiceLinkInput): Promise<MutationResult>;
     /** Remove a previously-registered invoice link. */
-    deleteLink(input: DeleteInvoiceLinkInput): Promise<unknown>;
+    deleteLink(input: DeleteInvoiceLinkInput): Promise<MutationResult>;
 }
 
 /**
@@ -1193,10 +1217,20 @@ declare class LocationsResource {
     /** 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[]>;
+    /**
+     * List districts for a Turkish city. **Pass the city `id`** (`City.id`) — the
+     * nested endpoint keys off Trendyol's internal id, not the display `code`, and
+     * returns 500 for the code. Verified live.
+     */
+    getTurkeyDistricts(cityId: string | number): Promise<District[]>;
+    /**
+     * List neighborhoods for a Turkish district. **Pass the ids** (`City.id`,
+     * `District.id`) — not the display codes (those 500).
+     */
+    getTurkeyNeighborhoods(cityId: string | number, districtId: string | number): Promise<Neighborhood[]>;
     getAzerbaijanCities(): Promise<City[]>;
-    getAzerbaijanDistricts(cityCode: string | number): Promise<District[]>;
+    /** List districts for an Azerbaijani city. **Pass the city `id`** (`City.id`), not `code`. */
+    getAzerbaijanDistricts(cityId: string | number): Promise<District[]>;
     getCitiesByCountry(countryCode: string): Promise<City[]>;
     getDistrictsByCity(countryCode: string, cityId: string | number): Promise<District[]>;
     private cities;
@@ -2016,6 +2050,11 @@ declare class ProductsResource {
      * List approved products. Use `paginate()` from `@lonca/core` to iterate
      * lazily across pages.
      *
+     * **Approved only:** this endpoint silently excludes products still in review
+     * or rejected — use {@link listUnapproved} for those. Date fields on the
+     * returned {@link Product} (`createdAt` / `updatedAt`) are ISO 8601 UTC
+     * **strings**, not `Date` objects.
+     *
      * Trendyol exposes both page-based and `nextPageToken`-based pagination
      * (the latter required when the dataset exceeds 10,000 items). The SDK
      * picks the right strategy automatically — pass our opaque `cursor` from
@@ -2624,4 +2663,4 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-export { type FinancialTransaction as $, type ApproveClaimLineItemsInput as A, type BarcodeCategoryLookup as B, type CancelPackageItemInput as C, type Country as D, type CreateClaimInput as E, type CreateClaimIssueInput as F, type CreateClaimItemInput as G, type CreateClientOptions as H, type CreateCommonLabelInput as I, type CreateProductV2Input as J, type CreateTestOrderInput as K, type CreateVideoInput as L, type DeleteInvoiceLinkInput as M, type DeliveryOptionInput as N, type District as O, type ExportBatchAcceptedResponse as P, type ExportBatchStatus as Q, type ExportCategoryAttribute as R, ExportCenterResource as S, type ExportPackage as T, type ExportPackageItem as U, type ExportPackageStatus as V, type ExportPriceUpdateInput as W, type ExportProduct as X, type ExportProductInput as Y, type ExportStockUpdateInput as Z, FinanceResource as _, type ApprovedProductStatus as a, type TestOrderStatus as a$, type GetExportPackageItemsParams as a0, InventoryResource as a1, InvoicesResource as a2, type KnownShipmentPackageStatus as a3, LabelsResource as a4, type LaborCostInput as a5, type ListCategoryAttributeValuesParams as a6, type ListClaimsParams as a7, type ListCompensationTicketsParams as a8, type ListExportPackagesV2Params as a9, type ProductAttribute as aA, type ProductAttributeV2Input as aB, type ProductBase as aC, type ProductComposition as aD, type ProductImageInput as aE, type ProductOrigin as aF, type ProductStockPrice as aG, type ProductStockPriceVariant as aH, type ProductVariant as aI, ProductsResource as aJ, type QuantitySplit as aK, type Question as aL, type QuestionAnswer as aM, type QuestionStatus as aN, QuestionsResource as aO, type SellerIntegrationStatus as aP, type SellerVideo as aQ, type SendInvoiceLinkInput as aR, type SettlementRow as aS, type ShipmentPackage as aT, type ShipmentPackageStatus as aU, type SplitGroup as aV, type SplitPackagePlan as aW, type SupplierAddress as aX, type SupplierAddressType as aY, SuppliersResource as aZ, type SuppliersResourceOptions as a_, type ListExportPackagesV3Params as aa, type ListExportProductsParams as ab, type ListFinanceParams as ac, type ListInventoryAndPriceParams as ad, type ListOrdersParams as ae, type ListOrdersStreamParams as af, type ListProductsParams as ag, type ListQuestionsParams as ah, type ListUnapprovedProductsParams as ai, type ListVideosParams as aj, LocationsResource as ak, type NamedRef as al, type Neighborhood as am, type OrderAddress as an, type OrderAddressLines as ao, type OrderCustomer as ap, type OrderLine as aq, type OrderLineDiscountDetail as ar, OrdersResource as as, type OtherFinancialRow as at, type PackageDetail as au, type PackageHistoryEntry as av, type PackageLineUpdate as aw, type PriceInventoryUpdate as ax, type ProcessAlternativeDeliveryInput as ay, type Product as az, type BatchAcceptedResponse as b, TestOrdersResource as b0, type TrendyolCapabilities as b1, type TrendyolCargoProvider as b2, type TrendyolClient as b3, type TrendyolEnvironment as b4, type UnapprovedDateQueryType as b5, type UnapprovedProduct as b6, type UnapprovedProductRejectReason as b7, type UnapprovedProductStatus as b8, type UpdateBoxInfoInput as b9, type UpdateContentInput as ba, type UpdateDeliveryInfoInput as bb, type UpdatePackageStatusInput as bc, type UpdatePriceInventoryResponse as bd, type UpdateUnapprovedInput as be, type UpdateVariantInput as bf, type UploadInvoiceFileInput as bg, VideosResource as bh, type Webhook as bi, type WebhookAuthenticationType as bj, type WebhookInput as bk, WebhooksResource as bl, createTrendyolClient as bm, normalizeShipmentPackage as bn, pollBatchStatus as bo, trendyolCapabilities as bp, type BatchPollOptions as c, type BatchRequestItemResult as d, type BatchRequestResult as e, type BatchRequestStatus as f, type Brand as g, BrandsResource as h, type BuyboxInfo as i, type CareInstruction as j, type CargoInvoiceItem as k, CategoriesResource as l, type Category as m, type CategoryAttribute as n, type CategoryAttributeValue as o, type City as p, type Claim as q, type ClaimIssueReason as r, type ClaimItemAudit as s, type ClaimItemStatus as t, ClaimsResource as u, type CommonLabel as v, type CommonLabelEntry as w, type CompensationItemDetail as x, type CompensationTicket as y, type CompensationTicketState as z };
+export { type FinancialTransaction as $, type ApproveClaimLineItemsInput as A, type BarcodeCategoryLookup as B, type CancelPackageItemInput as C, type Country as D, type CreateClaimInput as E, type CreateClaimIssueInput as F, type CreateClaimItemInput as G, type CreateClientOptions as H, type CreateCommonLabelInput as I, type CreateProductV2Input as J, type CreateTestOrderInput as K, type CreateVideoInput as L, type DeleteInvoiceLinkInput as M, type DeliveryOptionInput as N, type District as O, type ExportBatchAcceptedResponse as P, type ExportBatchStatus as Q, type ExportCategoryAttribute as R, ExportCenterResource as S, type ExportPackage as T, type ExportPackageItem as U, type ExportPackageStatus as V, type ExportPriceUpdateInput as W, type ExportProduct as X, type ExportProductInput as Y, type ExportStockUpdateInput as Z, FinanceResource as _, type ApprovedProductStatus as a, type SuppliersResourceOptions as a$, type GetExportPackageItemsParams as a0, InventoryResource as a1, InvoicesResource as a2, type KnownShipmentPackageStatus as a3, LabelsResource as a4, type LaborCostInput as a5, type ListCategoryAttributeValuesParams as a6, type ListClaimsParams as a7, type ListCompensationTicketsParams as a8, type ListExportPackagesV2Params as a9, type ProductAttribute as aA, type ProductAttributeV2Input as aB, type ProductBase as aC, type ProductComposition as aD, type ProductContentBase as aE, type ProductImageInput as aF, type ProductOrigin as aG, type ProductStockPrice as aH, type ProductStockPriceVariant as aI, type ProductVariant as aJ, ProductsResource as aK, type QuantitySplit as aL, type Question as aM, type QuestionAnswer as aN, type QuestionStatus as aO, QuestionsResource as aP, type SellerIntegrationStatus as aQ, type SellerVideo as aR, type SendInvoiceLinkInput as aS, type SettlementRow as aT, type ShipmentPackage as aU, type ShipmentPackageStatus as aV, type SplitGroup as aW, type SplitPackagePlan as aX, type SupplierAddress as aY, type SupplierAddressType as aZ, SuppliersResource as a_, type ListExportPackagesV3Params as aa, type ListExportProductsParams as ab, type ListFinanceParams as ac, type ListInventoryAndPriceParams as ad, type ListOrdersParams as ae, type ListOrdersStreamParams as af, type ListProductsParams as ag, type ListQuestionsParams as ah, type ListUnapprovedProductsParams as ai, type ListVideosParams as aj, LocationsResource as ak, type NamedRef as al, type Neighborhood as am, type OrderAddress as an, type OrderAddressLines as ao, type OrderCustomer as ap, type OrderLine as aq, type OrderLineDiscountDetail as ar, OrdersResource as as, type OtherFinancialRow as at, type PackageDetail as au, type PackageHistoryEntry as av, type PackageLineUpdate as aw, type PriceInventoryUpdate as ax, type ProcessAlternativeDeliveryInput as ay, type Product as az, type BatchAcceptedResponse as b, type TestOrderStatus as b0, TestOrdersResource as b1, type TrendyolCapabilities as b2, type TrendyolCargoProvider as b3, type TrendyolClient as b4, type TrendyolEnvironment as b5, type UnapprovedDateQueryType as b6, type UnapprovedProduct as b7, type UnapprovedProductRejectReason as b8, type UnapprovedProductStatus as b9, type UpdateBoxInfoInput as ba, type UpdateContentInput as bb, type UpdateDeliveryInfoInput as bc, type UpdatePackageStatusInput as bd, type UpdatePriceInventoryResponse as be, type UpdateUnapprovedInput as bf, type UpdateVariantInput as bg, type UploadInvoiceFileInput as bh, VideosResource as bi, type Webhook as bj, type WebhookAuthenticationType as bk, type WebhookInput as bl, WebhooksResource as bm, createTrendyolClient as bn, normalizeShipmentPackage as bo, pollBatchStatus as bp, trendyolCapabilities as bq, type BatchPollOptions as c, type BatchRequestItemResult as d, type BatchRequestResult as e, type BatchRequestStatus as f, type Brand as g, BrandsResource as h, type BuyboxInfo as i, type CareInstruction as j, type CargoInvoiceItem as k, CategoriesResource as l, type Category as m, type CategoryAttribute as n, type CategoryAttributeValue as o, type City as p, type Claim as q, type ClaimIssueReason as r, type ClaimItemAudit as s, type ClaimItemStatus as t, ClaimsResource as u, type CommonLabel as v, type CommonLabelEntry as w, type CompensationItemDetail as x, type CompensationTicket as y, type CompensationTicketState as z };

package/dist/{client-BJjLOn4v.d.ts → client-CtygosAW.d.ts}

@@ -1,4 +1,4 @@
-import { Logger, BaseRequestOptions, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, OffsetPaginationParams } from '@lonca/core';
+import { Logger, BaseRequestOptions, TokenBucketRateLimiter, CursorPaginationParams, CursorPage, MutationResult, OffsetPaginationParams } from '@lonca/core';
 
 declare const BASE_URLS: {
     readonly prod: "https://apigw.trendyol.com";
@@ -349,7 +349,7 @@ declare class ClaimsResource {
      *
      * @throws {ValidationError} when `claimItems` is empty.
      */
-    create(input: CreateClaimInput): Promise<unknown>;
+    create(input: CreateClaimInput): Promise<MutationResult>;
     /**
      * File a seller-side rejection ("ret talebi") against a customer claim.
      *
@@ -358,14 +358,14 @@ declare class ClaimsResource {
      * commas (Trendyol expects a single comma-separated string field).
      * Attach supporting docs (PDF / JPEG) via `files: [Blob, ...]`.
      */
-    createIssue(claimId: string, input: CreateClaimIssueInput): Promise<unknown>;
+    createIssue(claimId: string, input: CreateClaimIssueInput): Promise<MutationResult>;
     /**
      * 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>;
+    approveLineItems(claimId: string, input: ApproveClaimLineItemsInput): Promise<MutationResult>;
     /**
      * List claims (page-based; SDK exposes opaque cursor convention).
      *
@@ -696,7 +696,17 @@ type OtherFinancialRow = FinancialTransaction;
 interface ListFinanceParams extends CursorPaginationParams {
     startDate?: Date;
     endDate?: Date;
+    /**
+     * **Required** by Trendyol's CHE finance API (it returns 500 without one),
+     * e.g. `'Sale'`, `'Return'`, `'Discount'`, `'DeductionInvoices'`. The SDK
+     * throws a `ValidationError` if omitted.
+     */
     transactionType?: string;
+    /**
+     * Page size. Trendyol's finance API only accepts **500 or 1000** — the SDK
+     * clamps any value to the nearest of those (default 500).
+     */
+    limit?: number;
 }
 interface CreateCommonLabelInput {
     /** Currently the only documented format Trendyol accepts. */
@@ -743,18 +753,28 @@ interface Country {
     raw: Record<string, unknown>;
 }
 interface City {
+    /**
+     * Trendyol's internal city id — the value the **nested** endpoints expect
+     * (`getTurkeyDistricts(city.id)`). Distinct from `code` (the plate-style
+     * display code, e.g. `"1"` for Adana); passing `code` there returns 500.
+     */
+    id?: string;
     code: string;
     name?: string;
     countryCode?: string;
     raw: Record<string, unknown>;
 }
 interface District {
+    /** Trendyol's internal district id — pass to `getTurkeyNeighborhoods(cityId, district.id)`. */
+    id?: string;
     code: string;
     name?: string;
     cityCode?: string;
     raw: Record<string, unknown>;
 }
 interface Neighborhood {
+    /** Trendyol's internal neighborhood id. */
+    id?: string;
     code: string;
     name?: string;
     districtCode?: string;
@@ -835,13 +855,16 @@ interface ProductVariant {
     raw: Record<string, unknown>;
 }
 /**
- * A Trendyol marketplace product (approved variant).
+ * The content fields shared by an approved {@link Product} and an unapproved
+ * (draft) {@link UnapprovedProduct} — so callers can read title / brand /
+ * category / images from either shape without branching.
  *
- * Lonca surfaces the stable fields we have verified against live Trendyol
- * responses. Everything else stays accessible via `raw`.
+ * Intentionally just the common surface: the two diverge structurally beyond
+ * this (`Product` carries `variants[]`; `UnapprovedProduct` is flat with a root
+ * `barcode`), and their timestamp fields differ in optionality, so those stay on
+ * the concrete types.
  */
-interface Product {
-    contentId: string;
+interface ProductContentBase {
     productMainId: string;
     title: string;
     description?: string;
@@ -850,6 +873,15 @@ interface Product {
     /** Image URLs in display order. */
     images: string[];
     attributes: ProductAttribute[];
+}
+/**
+ * A Trendyol marketplace product (approved variant).
+ *
+ * Lonca surfaces the stable fields we have verified against live Trendyol
+ * responses. Everything else stays accessible via `raw`.
+ */
+interface Product extends ProductContentBase {
+    contentId: string;
     variants: ProductVariant[];
     /** ISO 8601 UTC string (converted from Trendyol's ms-epoch). */
     createdAt: string;
@@ -887,17 +919,12 @@ interface UnapprovedProductRejectReason {
  * calls the image-list field `media`, but the live API returns it as
  * `images`. SDK normalizes to `images`.
  */
-interface UnapprovedProduct {
+interface UnapprovedProduct extends ProductContentBase {
     /** Seller (supplier) ID echoed back by Trendyol. */
     supplierId?: string;
-    productMainId: string;
     /** Lifecycle status — see `UnapprovedProductStatus`. */
     status?: UnapprovedProductStatus;
-    brand: NamedRef;
-    category: NamedRef;
     barcode: string;
-    title: string;
-    description?: string;
     /** Stock quantity at the moment of the query. */
     quantity?: number;
     listPrice?: number;
@@ -906,9 +933,6 @@ interface UnapprovedProduct {
     vatRate?: number;
     dimensionalWeight?: number;
     stockCode?: string;
-    /** Image URLs in display order (Trendyol's `images` field, spec says `media`). */
-    images: string[];
-    attributes: ProductAttribute[];
     /** Populated when `status === 'rejected'`. */
     rejectReasonDetails: UnapprovedProductRejectReason[];
     /** Returned by Trendyol; null when the seller has not configured this. */
@@ -1145,11 +1169,11 @@ declare class InvoicesResource {
      *
      * Max 10 MB. Accepted formats: PDF, JPEG, PNG.
      */
-    uploadFile(input: UploadInvoiceFileInput): Promise<unknown>;
+    uploadFile(input: UploadInvoiceFileInput): Promise<MutationResult>;
     /** Register an invoice URL with Trendyol (alternative to uploading the file). */
-    sendLink(input: SendInvoiceLinkInput): Promise<unknown>;
+    sendLink(input: SendInvoiceLinkInput): Promise<MutationResult>;
     /** Remove a previously-registered invoice link. */
-    deleteLink(input: DeleteInvoiceLinkInput): Promise<unknown>;
+    deleteLink(input: DeleteInvoiceLinkInput): Promise<MutationResult>;
 }
 
 /**
@@ -1193,10 +1217,20 @@ declare class LocationsResource {
     /** 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[]>;
+    /**
+     * List districts for a Turkish city. **Pass the city `id`** (`City.id`) — the
+     * nested endpoint keys off Trendyol's internal id, not the display `code`, and
+     * returns 500 for the code. Verified live.
+     */
+    getTurkeyDistricts(cityId: string | number): Promise<District[]>;
+    /**
+     * List neighborhoods for a Turkish district. **Pass the ids** (`City.id`,
+     * `District.id`) — not the display codes (those 500).
+     */
+    getTurkeyNeighborhoods(cityId: string | number, districtId: string | number): Promise<Neighborhood[]>;
     getAzerbaijanCities(): Promise<City[]>;
-    getAzerbaijanDistricts(cityCode: string | number): Promise<District[]>;
+    /** List districts for an Azerbaijani city. **Pass the city `id`** (`City.id`), not `code`. */
+    getAzerbaijanDistricts(cityId: string | number): Promise<District[]>;
     getCitiesByCountry(countryCode: string): Promise<City[]>;
     getDistrictsByCity(countryCode: string, cityId: string | number): Promise<District[]>;
     private cities;
@@ -2016,6 +2050,11 @@ declare class ProductsResource {
      * List approved products. Use `paginate()` from `@lonca/core` to iterate
      * lazily across pages.
      *
+     * **Approved only:** this endpoint silently excludes products still in review
+     * or rejected — use {@link listUnapproved} for those. Date fields on the
+     * returned {@link Product} (`createdAt` / `updatedAt`) are ISO 8601 UTC
+     * **strings**, not `Date` objects.
+     *
      * Trendyol exposes both page-based and `nextPageToken`-based pagination
      * (the latter required when the dataset exceeds 10,000 items). The SDK
      * picks the right strategy automatically — pass our opaque `cursor` from
@@ -2624,4 +2663,4 @@ interface TrendyolClient {
  */
 declare function createTrendyolClient(opts: CreateClientOptions): TrendyolClient;
 
-export { type FinancialTransaction as $, type ApproveClaimLineItemsInput as A, type BarcodeCategoryLookup as B, type CancelPackageItemInput as C, type Country as D, type CreateClaimInput as E, type CreateClaimIssueInput as F, type CreateClaimItemInput as G, type CreateClientOptions as H, type CreateCommonLabelInput as I, type CreateProductV2Input as J, type CreateTestOrderInput as K, type CreateVideoInput as L, type DeleteInvoiceLinkInput as M, type DeliveryOptionInput as N, type District as O, type ExportBatchAcceptedResponse as P, type ExportBatchStatus as Q, type ExportCategoryAttribute as R, ExportCenterResource as S, type ExportPackage as T, type ExportPackageItem as U, type ExportPackageStatus as V, type ExportPriceUpdateInput as W, type ExportProduct as X, type ExportProductInput as Y, type ExportStockUpdateInput as Z, FinanceResource as _, type ApprovedProductStatus as a, type TestOrderStatus as a$, type GetExportPackageItemsParams as a0, InventoryResource as a1, InvoicesResource as a2, type KnownShipmentPackageStatus as a3, LabelsResource as a4, type LaborCostInput as a5, type ListCategoryAttributeValuesParams as a6, type ListClaimsParams as a7, type ListCompensationTicketsParams as a8, type ListExportPackagesV2Params as a9, type ProductAttribute as aA, type ProductAttributeV2Input as aB, type ProductBase as aC, type ProductComposition as aD, type ProductImageInput as aE, type ProductOrigin as aF, type ProductStockPrice as aG, type ProductStockPriceVariant as aH, type ProductVariant as aI, ProductsResource as aJ, type QuantitySplit as aK, type Question as aL, type QuestionAnswer as aM, type QuestionStatus as aN, QuestionsResource as aO, type SellerIntegrationStatus as aP, type SellerVideo as aQ, type SendInvoiceLinkInput as aR, type SettlementRow as aS, type ShipmentPackage as aT, type ShipmentPackageStatus as aU, type SplitGroup as aV, type SplitPackagePlan as aW, type SupplierAddress as aX, type SupplierAddressType as aY, SuppliersResource as aZ, type SuppliersResourceOptions as a_, type ListExportPackagesV3Params as aa, type ListExportProductsParams as ab, type ListFinanceParams as ac, type ListInventoryAndPriceParams as ad, type ListOrdersParams as ae, type ListOrdersStreamParams as af, type ListProductsParams as ag, type ListQuestionsParams as ah, type ListUnapprovedProductsParams as ai, type ListVideosParams as aj, LocationsResource as ak, type NamedRef as al, type Neighborhood as am, type OrderAddress as an, type OrderAddressLines as ao, type OrderCustomer as ap, type OrderLine as aq, type OrderLineDiscountDetail as ar, OrdersResource as as, type OtherFinancialRow as at, type PackageDetail as au, type PackageHistoryEntry as av, type PackageLineUpdate as aw, type PriceInventoryUpdate as ax, type ProcessAlternativeDeliveryInput as ay, type Product as az, type BatchAcceptedResponse as b, TestOrdersResource as b0, type TrendyolCapabilities as b1, type TrendyolCargoProvider as b2, type TrendyolClient as b3, type TrendyolEnvironment as b4, type UnapprovedDateQueryType as b5, type UnapprovedProduct as b6, type UnapprovedProductRejectReason as b7, type UnapprovedProductStatus as b8, type UpdateBoxInfoInput as b9, type UpdateContentInput as ba, type UpdateDeliveryInfoInput as bb, type UpdatePackageStatusInput as bc, type UpdatePriceInventoryResponse as bd, type UpdateUnapprovedInput as be, type UpdateVariantInput as bf, type UploadInvoiceFileInput as bg, VideosResource as bh, type Webhook as bi, type WebhookAuthenticationType as bj, type WebhookInput as bk, WebhooksResource as bl, createTrendyolClient as bm, normalizeShipmentPackage as bn, pollBatchStatus as bo, trendyolCapabilities as bp, type BatchPollOptions as c, type BatchRequestItemResult as d, type BatchRequestResult as e, type BatchRequestStatus as f, type Brand as g, BrandsResource as h, type BuyboxInfo as i, type CareInstruction as j, type CargoInvoiceItem as k, CategoriesResource as l, type Category as m, type CategoryAttribute as n, type CategoryAttributeValue as o, type City as p, type Claim as q, type ClaimIssueReason as r, type ClaimItemAudit as s, type ClaimItemStatus as t, ClaimsResource as u, type CommonLabel as v, type CommonLabelEntry as w, type CompensationItemDetail as x, type CompensationTicket as y, type CompensationTicketState as z };
+export { type FinancialTransaction as $, type ApproveClaimLineItemsInput as A, type BarcodeCategoryLookup as B, type CancelPackageItemInput as C, type Country as D, type CreateClaimInput as E, type CreateClaimIssueInput as F, type CreateClaimItemInput as G, type CreateClientOptions as H, type CreateCommonLabelInput as I, type CreateProductV2Input as J, type CreateTestOrderInput as K, type CreateVideoInput as L, type DeleteInvoiceLinkInput as M, type DeliveryOptionInput as N, type District as O, type ExportBatchAcceptedResponse as P, type ExportBatchStatus as Q, type ExportCategoryAttribute as R, ExportCenterResource as S, type ExportPackage as T, type ExportPackageItem as U, type ExportPackageStatus as V, type ExportPriceUpdateInput as W, type ExportProduct as X, type ExportProductInput as Y, type ExportStockUpdateInput as Z, FinanceResource as _, type ApprovedProductStatus as a, type SuppliersResourceOptions as a$, type GetExportPackageItemsParams as a0, InventoryResource as a1, InvoicesResource as a2, type KnownShipmentPackageStatus as a3, LabelsResource as a4, type LaborCostInput as a5, type ListCategoryAttributeValuesParams as a6, type ListClaimsParams as a7, type ListCompensationTicketsParams as a8, type ListExportPackagesV2Params as a9, type ProductAttribute as aA, type ProductAttributeV2Input as aB, type ProductBase as aC, type ProductComposition as aD, type ProductContentBase as aE, type ProductImageInput as aF, type ProductOrigin as aG, type ProductStockPrice as aH, type ProductStockPriceVariant as aI, type ProductVariant as aJ, ProductsResource as aK, type QuantitySplit as aL, type Question as aM, type QuestionAnswer as aN, type QuestionStatus as aO, QuestionsResource as aP, type SellerIntegrationStatus as aQ, type SellerVideo as aR, type SendInvoiceLinkInput as aS, type SettlementRow as aT, type ShipmentPackage as aU, type ShipmentPackageStatus as aV, type SplitGroup as aW, type SplitPackagePlan as aX, type SupplierAddress as aY, type SupplierAddressType as aZ, SuppliersResource as a_, type ListExportPackagesV3Params as aa, type ListExportProductsParams as ab, type ListFinanceParams as ac, type ListInventoryAndPriceParams as ad, type ListOrdersParams as ae, type ListOrdersStreamParams as af, type ListProductsParams as ag, type ListQuestionsParams as ah, type ListUnapprovedProductsParams as ai, type ListVideosParams as aj, LocationsResource as ak, type NamedRef as al, type Neighborhood as am, type OrderAddress as an, type OrderAddressLines as ao, type OrderCustomer as ap, type OrderLine as aq, type OrderLineDiscountDetail as ar, OrdersResource as as, type OtherFinancialRow as at, type PackageDetail as au, type PackageHistoryEntry as av, type PackageLineUpdate as aw, type PriceInventoryUpdate as ax, type ProcessAlternativeDeliveryInput as ay, type Product as az, type BatchAcceptedResponse as b, type TestOrderStatus as b0, TestOrdersResource as b1, type TrendyolCapabilities as b2, type TrendyolCargoProvider as b3, type TrendyolClient as b4, type TrendyolEnvironment as b5, type UnapprovedDateQueryType as b6, type UnapprovedProduct as b7, type UnapprovedProductRejectReason as b8, type UnapprovedProductStatus as b9, type UpdateBoxInfoInput as ba, type UpdateContentInput as bb, type UpdateDeliveryInfoInput as bc, type UpdatePackageStatusInput as bd, type UpdatePriceInventoryResponse as be, type UpdateUnapprovedInput as bf, type UpdateVariantInput as bg, type UploadInvoiceFileInput as bh, VideosResource as bi, type Webhook as bj, type WebhookAuthenticationType as bk, type WebhookInput as bl, WebhooksResource as bm, createTrendyolClient as bn, normalizeShipmentPackage as bo, pollBatchStatus as bp, trendyolCapabilities as bq, type BatchPollOptions as c, type BatchRequestItemResult as d, type BatchRequestResult as e, type BatchRequestStatus as f, type Brand as g, BrandsResource as h, type BuyboxInfo as i, type CareInstruction as j, type CargoInvoiceItem as k, CategoriesResource as l, type Category as m, type CategoryAttribute as n, type CategoryAttributeValue as o, type City as p, type Claim as q, type ClaimIssueReason as r, type ClaimItemAudit as s, type ClaimItemStatus as t, ClaimsResource as u, type CommonLabel as v, type CommonLabelEntry as w, type CompensationItemDetail as x, type CompensationTicket as y, type CompensationTicketState as z };