@lonca/trendyol 0.12.0 → 0.13.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-DMndJSb0.d.cts}

@@ -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;
@@ -1193,10 +1213,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;

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

@@ -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;
@@ -1193,10 +1213,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;

package/dist/index.cjs

@@ -716,12 +716,20 @@ var FinanceResource = class {
     );
   }
   async queryPage(path, params) {
-    const size = Math.min(params.limit ?? 50, 200);
+    if (!params.transactionType) {
+      throw new core.ValidationError({
+        message: "finance: transactionType is required (Trendyol returns 500 without it) \u2014 pass e.g. { transactionType: 'Sale' }."
+      });
+    }
+    const size = (params.limit ?? 500) > 500 ? 1e3 : 500;
     const page = params.cursor ? Number.parseInt(params.cursor, 10) : 0;
-    const query = { page, size };
+    const query = {
+      page,
+      size,
+      transactionType: params.transactionType
+    };
     if (params.startDate) query.startDate = params.startDate.getTime();
     if (params.endDate) query.endDate = params.endDate.getTime();
-    if (params.transactionType) query.transactionType = params.transactionType;
     const data = await this.transport.request({
       method: "GET",
       path,
@@ -998,22 +1006,32 @@ var LocationsResource = class {
   async getTurkeyCities() {
     return this.cities(`/integration/member/countries/domestic/TR/cities`);
   }
-  async getTurkeyDistricts(cityCode) {
+  /**
+   * 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.
+   */
+  async getTurkeyDistricts(cityId) {
     return this.districts(
-      `/integration/member/countries/domestic/TR/cities/${encodeURIComponent(String(cityCode))}/districts`
+      `/integration/member/countries/domestic/TR/cities/${encodeURIComponent(String(cityId))}/districts`
     );
   }
-  async getTurkeyNeighborhoods(cityCode, districtCode) {
+  /**
+   * List neighborhoods for a Turkish district. **Pass the ids** (`City.id`,
+   * `District.id`) — not the display codes (those 500).
+   */
+  async getTurkeyNeighborhoods(cityId, districtId) {
     return this.neighborhoods(
-      `/integration/member/countries/domestic/TR/cities/${encodeURIComponent(String(cityCode))}/districts/${encodeURIComponent(String(districtCode))}/neighborhoods`
+      `/integration/member/countries/domestic/TR/cities/${encodeURIComponent(String(cityId))}/districts/${encodeURIComponent(String(districtId))}/neighborhoods`
     );
   }
   async getAzerbaijanCities() {
     return this.cities(`/integration/member/countries/domestic/AZ/cities`);
   }
-  async getAzerbaijanDistricts(cityCode) {
+  /** List districts for an Azerbaijani city. **Pass the city `id`** (`City.id`), not `code`. */
+  async getAzerbaijanDistricts(cityId) {
     return this.districts(
-      `/integration/member/countries/domestic/AZ/cities/${encodeURIComponent(String(cityCode))}/districts`
+      `/integration/member/countries/domestic/AZ/cities/${encodeURIComponent(String(cityId))}/districts`
     );
   }
   // ─── International (GULF / CEE) ───────────────────────────────────────
@@ -1033,6 +1051,7 @@ var LocationsResource = class {
       rateLimiter: this.limiter
     });
     return n(data, (node) => ({
+      id: node.id !== void 0 ? String(node.id) : void 0,
       code: String(node.code ?? node.id ?? ""),
       name: node.name,
       countryCode: node.countryCode
@@ -1045,6 +1064,7 @@ var LocationsResource = class {
       rateLimiter: this.limiter
     });
     return n(data, (node) => ({
+      id: node.id !== void 0 ? String(node.id) : void 0,
       code: String(node.code ?? node.id ?? ""),
       name: node.name,
       cityCode: node.cityCode !== void 0 ? String(node.cityCode) : void 0
@@ -1057,6 +1077,7 @@ var LocationsResource = class {
       rateLimiter: this.limiter
     });
     return n(data, (node) => ({
+      id: node.id !== void 0 ? String(node.id) : void 0,
       code: String(node.code ?? node.id ?? ""),
       name: node.name,
       districtCode: node.districtCode !== void 0 ? String(node.districtCode) : void 0