v3.8.1 — Documentation overhaul

Documentation

• Fix method counts in 6 module doc pages (removed references to methods no longer in source)
• Add v3.8.0 warnOnce behavior documentation to promotion and finances modules
• Add field union types (SalesReportDetailedField, AcquiringReportDetailedField) to finances docs
• Update README: v3.8.x, 13 modules, 2111 tests, "What's New" section in EN + RU
• Add CHANGELOG entries for v3.3.0 through v3.8.0 (8 missing versions)
• Regenerate TypeDoc API reference with warnOnce/resetDeprecationWarnings docs
• All validation tools clean: 2111 tests, 165 examples, 0 warnings

No code changes — documentation-only patch release.

Full Changelog: v3.8.0...v3.8.1

v3.8.0 — Finance field union types, documentation overhaul

Breaking Changes (type-only, no runtime impact)

• SalesReportDetailedField and AcquiringReportDetailedField union types narrow fields[] parameter from string[] to specific valid field names
• Consumers passing arbitrary strings to fields[] will get TypeScript errors — use valid field names from the union type

New Features

• Field union types for v1 Finance Reports — full autocomplete and type safety for fields[] parameter in getSalesReportsDetailed() and getAcquiringReportsDetailed()
• 6 new regression tests for field type constraints

Documentation

• Complete rewrite of Finances module docs (13 methods, v1/v5 comparison, parseMoneyAmount helper)
• 10 missing guides added to EN sidebar, 7 new sections added to RU sidebar
• All 44 guides linked in guides index with v3.7.0 callout
• RU guides index updated with 10 missing translations + 4 new sections
• Getting Started quickstart updated (13 modules)
• TypeDoc API reference regenerated (0 warnings)
• All validation tools clean: 2107 tests, 0 TypeDoc warnings, 0 validate:examples warnings, 0 broken links

npm deprecation

All versions < 3.7.0 are now marked deprecated on npm with migration guidance (WB API v5 finance method disabled 2026-07-15).

Full Changelog: v3.7.0...v3.8.0

v3.7.0 — Finance Reports v1 migration

Финансовые отчёты v1 — миграция с v5 до 15 июля

Sprint 10 ships 6 new methods, deprecation of the old v5 method, and a comprehensive migration guide.

⚠️ Deadline: 2026-07-15

Wildberries will disable GET /api/v5/supplier/reportDetailByPeriod on 2026-07-15. If your code calls sdk.finances.getSupplierReportDetailByPeriod(), migrate now.

What's new (6 methods)

Sales Reports v1 (replaces deprecated v5):

• getSalesReportsList() — list of reports for a period
• getSalesReportsDetailed() — detailed rows for a period (replaces v5)
• getSalesReportsDetailedByReportId(id, data) — detailed rows by report ID

Acquiring Reports v1 (new endpoint group, RU-only):

• getAcquiringReportsList() — list of acquiring reports
• getAcquiringReportsDetailed() — detailed rows for a period
• getAcquiringReportsDetailedByReportId(id, data) — detailed rows by report ID

All 6 methods:

• Use finance-api.wildberries.ru (not statistics-api)
• Use POST with JSON body (not GET with query params)
• Return money amounts as string (was number) — use the new parseMoneyAmount() helper
• Support fields?: string[] for selective field loading
• Require Personal or Service tokens (NOT Basic/Test)
• Accept reportId as number | bigint | string (BigInt-safe for daily reports)

New helper

import { parseMoneyAmount } from 'daytona-wildberries-typescript-sdk';

const rows = await sdk.finances.getSalesReportsDetailed({ dateFrom, dateTo });
const total = rows.reduce((s, r) => s + parseMoneyAmount(r.forPay), 0);

Deprecation

getSupplierReportDetailByPeriod() and DetailReportItem are marked @deprecated. A one-time runtime warning fires on first call per process, pointing to the migration guide.

Migration guide

Full field mapping table (~70 fields with old snake_case + new camelCase side-by-side), code examples, migration checklist, and pitfalls:

📖 Finance Reports API Migration: snake_case to camelCase (v5 → v1)

Key migration points

• ppvz_for_pay → forPay (common rename)
• rrd_id → rrdId
• sa_name → vendorCode
• barcode → sku
• ppvz_spp_prc → spp
• storage_fee → paidStorage
• assembly_id → orderId
• site_country → country
• is_legal_entity → isB2b
• All money fields are now string — use parseMoneyAmount() for math

Watch out for string concatenation bugs

// ❌ WRONG — concatenates strings
const total = row.forPay + row.acquiringFee;  // "376.99" + "14.89" = "376.9914.89"

// ✅ CORRECT
const total = parseMoneyAmount(row.forPay) + parseMoneyAmount(row.acquiringFee);

Quality

• 2101 tests passing (+21 new)
• TypeScript strict mode, lint, validate:examples all clean
• Bundle: 90.91 kB gzipped (ESM), 36.16 kB (CJS)

Install

npm install daytona-wildberries-typescript-sdk@3.7.0

🤖 Generated with Claude Code

v3.6.2 — kizMarked marking code support for product cards

What's new

Adds kizMarked?: boolean field to product card create/update/list/trash methods, enabling sellers to confirm mandatory marking codes (Честный ЗНАК) via API.

Affected methods

Method	Role	Field added
createCardsUpload	Request variants[]	kizMarked?: boolean
createUploadAdd	Request cardsToAdd[]	kizMarked?: boolean
createCardsUpdate	Request data[]	kizMarked?: boolean
getCardsList	Response cards[]	kizMarked?: boolean
getTrashedCards	Response cards[]	kizMarked?: boolean + needKiz?: boolean (was missing)

Usage

// Confirm marking code applied when creating a product card
await sdk.products.createCardsUpload([{
  subjectID: 105,
  variants: [{
    vendorCode: 'ART-001',
    sizes: [{ techSize: '42', skus: ['1234567890123'] }],
    characteristics: [{ id: 1, value: 'Blue' }],
    kizMarked: true,  // NEW in v3.6.2
  }],
}]);

// Read marking code status from card list
const result = await sdk.products.getCardsList({
  settings: { cursor: { limit: 10 } },
});
console.log(result.cards?.[0].needKiz);    // true if marking required
console.log(result.cards?.[0].kizMarked);  // true if confirmed applied

Bonus fix

getTrashedCards response was missing needKiz?: boolean — added alongside kizMarked (pre-existing gap).

Quality

• 2080 tests passing (5 new regression tests, 0 regressions)
• DX integration test passed (fresh consumer project, tsc --noEmit)
• Code review: 5 issues found and fixed (3 Medium + 2 Low)

Source

WB API update 2026-04-09 — mandatory marking code confirmation via Честный ЗНАК.

npm install daytona-wildberries-typescript-sdk@3.6.2

🤖 Generated with Claude Code

v3.6.1 — Hotfix: type re-exports from module subpaths

v3.6.1 — Hotfix: type re-exports from module subpaths

Release date: 2026-04-08
Type: Patch — non-breaking, only adds new exports
Caught by: DX integration test for v3.6.0 (Sally's exit criterion from Sprint 7 planning)

TL;DR

If you tried to import a type from daytona-wildberries-typescript-sdk/finances (or /analytics, /communications, /reports) in v3.6.0, you got TS2459: declares X locally, but it is not exported. v3.6.1 fixes that. Upgrade and your imports will just work.

// This now works in v3.6.1 (was broken in v3.6.0 and earlier):
import type {
  DetailReportItem,
  AccountBalanceResponse,
} from 'daytona-wildberries-typescript-sdk/finances';

import type {
  WbWarehousesStockResponse,
  MainResponse,
} from 'daytona-wildberries-typescript-sdk/analytics';

import type { PinReviewItem } from 'daytona-wildberries-typescript-sdk/communications';
import type { IncomesItem } from 'daytona-wildberries-typescript-sdk/reports';

The bug

package.json exports defines 4 subpath imports:

"exports": {
  ".": { ... },
  "./finances":      { ... },
  "./analytics":     { ... },
  "./communications": { ... },
  "./reports":       { ... }
}

But each module's index.ts only exported the module class (e.g. FinancesModule), not the type definitions. Types lived in src/types/{module}.types.ts with no public re-export path.

This made the new v3.6.0 substitute article fields (article_substitution, sale_price_affiliated_discount_prc, agency_vat, sale_price_wholesale_discount_prc) inaccessible to TypeScript-strict consumers — they could see the methods but couldn't import the return types.

The bug was pre-existing, not introduced by v3.6.0. Earlier sprints didn't trip on it because no consumer had a strong reason to import these types directly. v3.6.0 added user-facing fields that made the gap visible.

The fix

Added explicit export type { ... } blocks to all 4 module index files:

Module	Types now exported
daytona-wildberries-typescript-sdk/finances	8 types (incl. DetailReportItem, AccountBalanceResponse)
daytona-wildberries-typescript-sdk/analytics	97 types
daytona-wildberries-typescript-sdk/communications	39 types
daytona-wildberries-typescript-sdk/reports	48 types

Also fixed a misleading JSDoc comment in src/index.ts that referenced a non-existent ./types/*.types subpath.

Why explicit lists, not export type *?

The export type * syntax (TypeScript 5.0+) was tried first. The vite-plugin-dts build emitted the statement into the .d.ts output, but downstream TypeScript could not resolve the re-exported names at consumption time. Switching to explicit named lists fixed the issue.

The trade-off is that adding new types to a module now requires updating BOTH the types file AND the module's index re-export list. That's documented as the project contract going forward.

How this was caught

Sally's "DX integration test" exit criterion from Sprint 7 planning explicitly required:

Install v3.6.0 in a fresh consumer project, type sdk.finances.getSupplierReportDetailByPeriod and access the new fields via autocomplete. Time how long it takes a fresh developer to understand what to put in article_substitution. If >5 minutes (excluding doc-reading time), the JSDoc has failed.

The test was carried out post-release in /tmp/wb-sdk-dx-test-v3.6.0/ and immediately surfaced the TS2459 error. The fix was implemented, validated end-to-end (tsc --noEmit + runtime execution against a locally-packed tarball), and shipped.

Validation

Gate	Result
npm run type-check	✅ Zero errors
npm run lint	✅ Zero issues
npm test	✅ 2075 passing, 1 skipped (no regressions)
npm run build	✅ 90.91 kB gzipped ESM, 35.71 kB gzipped CJS
Local DX test (tarball install + tsc + tsx)	✅ End-to-end pass for ALL 4 subpaths

Impact

Non-breaking. Only adds new exports. Existing imports of FinancesModule, AnalyticsModule, CommunicationsModule, ReportsModule continue to work unchanged. Consumers who tried to import types via deep paths (which never worked) now have a public contract.

Install

npm install daytona-wildberries-typescript-sdk@3.6.1

Diff stats

7 files changed, 235 insertions(+), 10 deletions(-)

Acknowledgements

Sprint 7 planning included a 3-round BMad party-mode session with 9 simulated specialist agents. Sally (UX Designer) flagged the DX integration test as a hard exit criterion in Round 3. Without that requirement, this bug would have slipped into v3.6.0 without detection until a user filed an issue. Process > heroics.

🤖 Generated with Claude Code

v3.6.0 — Substitute Article Tracking & Wholesale Discount Fields

v3.6.0 — Substitute Article Tracking & Wholesale Discount Fields

Release date: 2026-04-08
Theme: WB API April 2026 updates round 2 — finance report new fields
Type: Minor (non-breaking, additive type fields + new how-to guide)

What's new

4 new fields on DetailReportItem (finances module)

Wildberries added new fields to the financial report detail endpoint GET /api/v5/supplier/reportDetailByPeriod. The SDK now exposes them as type-safe optional properties:

Field	Type	Source
article_substitution	string	WB news id=11270 — substitute articles with discounts
sale_price_affiliated_discount_prc	number	Substitute article discount %
agency_vat	number	Field present in WB OpenAPI spec; semantics undocumented by WB
sale_price_wholesale_discount_prc	number	WB news id=11226 — wholesale business discount, prep for upcoming progressive discount tool

All fields ship with @example, @see, and @since v3.6.0 JSDoc tags for IDE-driven discoverability.

New guide: Tracking Promotion Channels with Substitute Articles

A production-grade Diataxis how-to guide for the finance reconciliation use case — matching marketing spend to settled revenue using substitute article IDs. Includes:

• Mermaid data-flow diagram (marketing channel → substitute article → purchase → finance report → SDK aggregation)
• Production aggregation pattern using Node 20-compatible inline reduce (NOT Object.groupBy())
• Empty state handling so consumers don't think the SDK is broken
• Complementary callout to analytics search-report endpoints (createSearchReportReport) for real-time marketing tracking
• SEO-optimized frontmatter for discoverability

📖 Read the guide

Code example

import { WildberriesSDK } from 'daytona-wildberries-typescript-sdk';
import type { DetailReportItem } from 'daytona-wildberries-typescript-sdk/finances';

const sdk = new WildberriesSDK({ apiKey: process.env.WB_API_KEY! });

const rows = await sdk.finances.getSupplierReportDetailByPeriod({
  dateFrom: '2026-04-01',
  dateTo: '2026-04-30',
  period: 'weekly',
});

// Filter to substitute article transactions
const substituteRows = rows.filter(
  (r) => r.article_substitution != null && r.article_substitution !== ''
);

// Aggregate by substitute article ID
const buckets = substituteRows.reduce<Record<string, { revenue: number; count: number }>>(
  (acc, row) => {
    const key = row.article_substitution!;
    if (!acc[key]) acc[key] = { revenue: 0, count: 0 };
    acc[key].revenue += row.retail_amount ?? 0;
    acc[key].count += 1;
    return acc;
  },
  {}
);

console.table(buckets);

Research findings (no new SDK code, but informative)

• No public WB API for substitute article management — feature is seller-portal-only as of 2026-04-08. If you need to create/disable substitute articles, you must do it in the seller portal under Рост продаж → Подменные артикулы.
• Analytics module already exposes complementary data — IsSubstitutedSKU field on search-report endpoints for real-time customer-side tracking.
• agency_vat semantics undocumented — field appears in WB spec but neither news articles nor local OpenAPI YAML document its meaning. Verify with WB before relying on values.

Caveats

• sale_price_wholesale_discount_prc is currently always 0. It will populate once Wildberries launches the прогрессирующая скидка для юрлиц и ИП (progressive wholesale discount for legal entities/IP) tool. The SDK is ready in advance.
• agency_vat semantics are undocumented as of 2026-04-08; the SDK exposes the field as number for type safety but consumers should verify with WB before relying on its value.
• Substitute article field persistence behavior on disablement is unverified — assume the field persists in historical reports per typical WB archival behavior.

Quality gates

• ✅ TypeScript strict mode passes
• ✅ ESLint clean
• ✅ 2075 tests passing (1 new regression test added for the 4 new fields)
• ✅ npm run validate:examples clean (32/32 doc files, 148 examples scanned)
• ✅ Bundle size: 90.91 kB gzipped (ESM), 35.71 kB gzipped (CJS)
• ✅ Node 20+ compatible

Sprint context

Sprint 7 was planned through 3 BMad party-mode planning rounds with 9 simulated specialist agents (SM, Dev, QA, Architect, Analyst, Tech Writer, PM, Quick Flow Dev, UX Designer). Decisions made:

• Added Source 0 sprint gate (5-min promotion API grep) to avoid duplicating work
• Soft-coupled task-87 to task-88 with pre-authorized fallback
• Added regression test as a hard AC (Quinn's rule)
• Wired the new guide into validate:examples for permanent CI protection
• Used Diataxis convention (separate how-to guide, not embedded in module page)
• Documented the agency_vat fallback explicitly

Full sprint plan and decision rationale: backlog/sprint-7-plan.md (in repo, gitignored).

Watch list (for future sprints)

• WL-1: Progressive wholesale discount API (when WB releases it, build SDK methods)
• WL-2: Consider bumping minimum Node to 22 LTS (would unlock Object.groupBy() and remove inline-reduce constraint)

Sources

• WB news id=11270 (substitute articles, 2026-04-06)
• WB news id=11226 (wholesale discount, 2026-04-02)
• WB API spec — financial reports

Diff stats

8 files changed, 321 insertions(+), 4 deletions(-)

Install

npm install daytona-wildberries-typescript-sdk@3.6.0

🤖 Generated with Claude Code

v3.5.1 — CI Fix

v3.5.1

Patch release — CI lint fix only, no functional changes.

• Fix @typescript-eslint/no-deprecated error in integration test for legacy meta field
• All tests pass, all CI checks green

Full Changelog: v3.5.0...v3.5.1

For the full v3.5.0 feature release notes, see: https://github.com/salacoste/daytona-wildberries-typescript-sdk/releases/tag/v3.5.0

v3.5.0 — Jam Direct API, Seller Rating, Rate Limit Multipliers

Wildberries SDK v3.5.0

New Methods

getJamSubscription() — General Module

Direct API for Jam subscription details. Replaces the probe-based detection from v3.3.0.

const jam = await sdk.general.getJamSubscription();
if (jam.state === 'active') {
  console.log(`Jam ${jam.level} active until ${jam.till}`);
}

Auth: Service token (any category). No nmIds required, no analytics quota consumed.

getSellerRating() — General Module

Get seller's user rating and review count.

const rating = await sdk.general.getSellerRating();
console.log(`Rating: ${rating.valuation} (${rating.feedbackCount} reviews)`);

Auth: Service token (category: Feedbacks and Questions)

Rate Limit Multipliers (Phase B)

Basic/Test tokens now get correct reduced rate limits automatically via category-level multipliers:

const sdk = new WildberriesSDK({
  apiKey: '...',
  tokenType: 'basic', // Applies reduced limits automatically
});

16 API categories mapped with multipliers from WB's official tables.

FBS Metadata Validation

updateSuppliesDeliver() now returns 409 if order metadata is invalid:

• IMEI validation (since March 31)
• UIN validation (since April 7)
• Marking code for B2B orders (since April 9)

New MetaDetail type with key, value, decision fields. Meta interface marked @deprecated (removal April 30, 2026).

Type Fixes

Change	Module
normquery/stats supports cpc campaigns (views/ctr/cpm optional)	Promotion
updatedAt in error list batch items	Products

Deprecations

• getJamSubscriptionStatus() → use getJamSubscription() instead
• Meta interface → use metaDetails (MetaDetail[]) — removed April 30, 2026

Documentation

8 documentation pages fully updated:

• Module docs: general, orders-fbs, orders-fbw, promotion, analytics, products
• Guides: jam-subscription (direct API as primary), configuration (token types + rate tables)
• Home page: 2075 tests, updated feature highlights

Installation

npm install daytona-wildberries-typescript-sdk@3.5.0

Full Changelog: v3.4.0...v3.5.0

v3.4.0 — New API Methods + Type Alignment

Wildberries SDK v3.4.0

New Methods

getBidsRecommendations() — Promotion Module

Fetch recommended competitive and leader bids for product cards and search clusters by campaign ID and article. cpm campaigns only.

const reco = await sdk.promotion.getBidsRecommendations({
  advertId: 29081652,
  nmId: 148190095,
});
for (const nq of reco.normQueries) {
  console.log(`${nq.normQuery}: min=${nq.reachMin.bidKopecks} med=${nq.reachMedium.bidKopecks} max=${nq.reachMax.bidKopecks}`);
}

getClientInfo() — Orders FBW Module (DBW)

Retrieve buyer information for DBW orders by order IDs.

const result = await sdk.ordersFBW.getClientInfo([987654321]);
for (const order of result.orders ?? []) {
  console.log(`${order.firstName}, +${order.phoneCode}${order.phone}`);
}

Note: Uses marketplace-api.wildberries.ru domain (not supplies-api).

getWbWarehousesStock() — Analytics Module

Query current WB warehouse inventory with warehouse IDs, region names, and offset pagination (up to 250K rows).

const stock = await sdk.analytics.getWbWarehousesStock({ nmIds: [395996251] });
for (const item of stock.data.items) {
  console.log(`${item.warehouseName} (${item.regionName}): ${item.quantity} шт.`);
}

Replaces deprecated GET /api/v1/supplier/stocks — will be disabled June 23, 2026.

Updated Methods

getAdvertsV2() — Promotion Module

• Return type changed from GetAdverts to GetAdvertsV2Response with typed AdvertV2[]
• nm_settings[].bids_kopecks with search and recommendations in kopecks
• bid_type: 'auto' | 'manual' (Type 8 vs Type 9 campaigns)
• JSDoc enriched with data sync timing (3 min DB, 1 min statuses, 30 sec bids)

Type Fixes (Sprint 1 + 3)

Type	Change
SDKConfig.tokenType	New: 'personal' | 'service' | 'basic' | 'test' with init warning for Basic/Test tokens
ResponseCardCreate.additionalErrors	Fixed: Record<string, string> for vendorCode-keyed merging errors
SalesFunnelProductsResponse (×3)	New: currency?: string field
ModelsSupply	New: boxTypeID, isBoxOnPallet fields
ModelsSupplyDetails	New: isBoxOnPallet field
ModelsOptionsResultModel.warehouses[]	New: canBoxOnPallet field
Supply (FBS)	New: isB2b flag (B2B supply segregation since March 19)
CrossBorderStickerItem	New: status: 'awaitingTrackNumber' | 'ready' (effective April 1)
SellerInfoResponse	New: tin field (ИНН)

JSDoc Updates

• deliverBulk() — Warning about 409 ImeiIsNotFilled error and requiredMeta check workflow
• User Management methods — Personal Token (category: Users) requirement, global availability
• All new methods include @since 3.4.0, rate limit tables, and @example with real data

Stats

Metric	Value
New methods	4
Type fixes	9 fields across 5 modules
New unit tests	+23
Code reviews	4 passed

Installation

npm install daytona-wildberries-typescript-sdk@3.4.0

Full Changelog: v3.3.0...v3.4.0

v3.3.0 - Jam Subscription Tier Detection

Wildberries SDK v3.3.0

Added

Jam (Джем) Subscription Detection

New method sdk.general.getJamSubscriptionStatus() that detects the seller's Jam subscription tier (none / standard / advanced) using a probe-based strategy.

Wildberries does not provide a direct API endpoint for checking Jam status. This method probes the analytics search-texts endpoint with specific limit values:

Step	Probe	200 =	400 =
1	limit: 31	Advanced	Continue →
2	limit: 1	Standard	None

const status = await sdk.general.getJamSubscriptionStatus({
  nmIds: [12345678]
});

switch (status.tier) {
  case 'advanced':
    console.log('Advanced Jam — limit up to 50');
    break;
  case 'standard':
    console.log('Standard Jam — limit up to 30');
    break;
  case 'none':
    console.log('No Jam subscription');
    break;
}

// Use tier to set optimal analytics limit
const limit = status.tier === 'advanced' ? 50
            : status.tier === 'standard' ? 30 : 0;

New Types

• JamSubscriptionTier — 'none' | 'standard' | 'advanced'
• JamSubscriptionStatus — { tier, checkedAt, probeCallsMade }
• GetJamSubscriptionStatusParams — { nmIds: number[] }

Documentation

• New guide: Jam Subscription Detection (EN)
• New guide: Определение подписки Джем (RU)
• Updated General Module reference (8 methods)
• Updated home page stats: 2041 tests

Fixed

• Version test assertion updated (3.0.0 → 3.3.0)
• Integration tests now gracefully handle deprecated WB promotion endpoints (404)

Stats

• 15 new unit tests for Jam detection (51 total in General module)
• 2041 total tests across the SDK

Installation

npm install daytona-wildberries-typescript-sdk@3.3.0

Full Changelog: v3.2.0...v3.3.0