feat(analytics): add getWbWarehousesStock — WB warehouses current inventory

New method getWbWarehousesStock() returns current inventory across all
WB warehouses with warehouseId, regionName, and offset pagination
(up to 250K rows). Replaces deprecated GET /api/v1/supplier/stocks
(disabled June 23, 2026).

- 3 new types: WbWarehousesStockRequest, WbWarehouseStockItem, WbWarehousesStockResponse
- Rate limit: 3 req/min, 20s interval, burst 1
- 6 new unit tests, method count updated 16→17
- JSDoc with deprecation notice and pagination examples

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: salacoste

src/config/analytics-rate-limits.ts

@@ -103,6 +103,12 @@ export const analyticsRateLimits: Record<string, RateLimitConfig> = {
     intervalSeconds: 20,
     burstLimit: 3,
   },
+  // v1 WB Warehouses Inventory (new endpoint, replaces deprecated /api/v1/supplier/stocks)
+  'analytics.postStocksReportWbWarehouses': {
+    requestsPerMinute: 3,
+    intervalSeconds: 20,
+    burstLimit: 1,
+  },
   // v3 Sales Funnel endpoints
   'analytics.postSalesFunnelProducts': {
     requestsPerMinute: 3,

src/modules/analytics/index.ts

@@ -41,6 +41,8 @@ import type {
   TableShippingOfficeResponse,
   TableSizeRequest,
   TableSizeResponse,
+  WbWarehousesStockRequest,
+  WbWarehousesStockResponse,
 } from '../../types/analytics.types';
 
 export class AnalyticsModule {
@@ -522,4 +524,54 @@ export class AnalyticsModule {
       { rateLimitKey: 'analytics.postSalesFunnelGroupedHistory' }
     );
   }
+
+  /**
+   * Текущие остатки на складах WB
+   *
+   * Возвращает актуальные остатки товаров на складах Wildberries.
+   * Данные обновляются раз в 30 минут. Одна строка = один размер на одном складе.
+   * Результаты отсортированы по возрастанию nmId.
+   *
+   * Доступен только для токенов типа Personal и Service.
+   *
+   * **Заменяет устаревший метод** `GET /api/v1/supplier/stocks`,
+   * который будет отключён 23 июня 2026.
+   *
+   * Rate limit: 3 requests per minute, 20-second interval, burst 1
+   *
+   * @param data - Filter and pagination parameters (all optional)
+   * @param data.nmIds - WB articles to filter (0-1000, empty = all)
+   * @param data.chrtIds - Size IDs (only for articles in nmIds)
+   * @param data.limit - Rows in response (max 250000, default 250000)
+   * @param data.offset - Skip N results for pagination (default 0)
+   * @returns Current inventory with warehouse IDs, region names, quantities
+   * @throws {AuthenticationError} When API key is invalid (401/403)
+   * @throws {RateLimitError} When rate limit exceeded (429)
+   * @throws {ValidationError} When request data is invalid (400/422)
+   * @throws {NetworkError} When network request fails or times out
+   * @since 3.4.0
+   * @see {@link https://dev.wildberries.ru/docs/openapi/analytics#tag/Istoriya-ostatkov/operation/postV1StocksReportWbWarehouses}
+   * @example
+   * ```typescript
+   * // Get all inventory
+   * const stock = await sdk.analytics.getWbWarehousesStock();
+   * for (const item of stock.data.items) {
+   *   console.log(`${item.warehouseName} (${item.regionName}): ${item.quantity} шт.`);
+   * }
+   *
+   * // With filters and pagination
+   * const page = await sdk.analytics.getWbWarehousesStock({
+   *   nmIds: [395996251],
+   *   limit: 100,
+   *   offset: 0,
+   * });
+   * ```
+   */
+  async getWbWarehousesStock(data?: WbWarehousesStockRequest): Promise<WbWarehousesStockResponse> {
+    return this.client.post<WbWarehousesStockResponse>(
+      'https://seller-analytics-api.wildberries.ru/api/analytics/v1/stocks-report/wb-warehouses',
+      data ?? {},
+      { rateLimitKey: 'analytics.postStocksReportWbWarehouses' }
+    );
+  }
 }

src/types/analytics.types.ts

@@ -1670,3 +1670,49 @@ export type SalesFunnelGroupedHistoryResponse = {
   /** Валюта (например, "RUB") */
   currency?: string;
 }[];
+
+// ============================================================================
+// WB Warehouses Inventory Types (v1)
+// ============================================================================
+
+/** Request for WB warehouses current inventory
+ * @since 3.4.0 */
+export interface WbWarehousesStockRequest {
+  /** WB articles (0-1000 items). Empty = all products */
+  nmIds?: number[];
+  /** Size IDs. Only used for articles specified in nmIds */
+  chrtIds?: number[];
+  /** Number of rows in response (max 250000, default 250000) */
+  limit?: number;
+  /** How many results to skip (default 0) */
+  offset?: number;
+}
+
+/** Single inventory item — 1 size in 1 WB warehouse
+ * @since 3.4.0 */
+export interface WbWarehouseStockItem {
+  /** WB article ID */
+  nmId: number;
+  /** Size ID */
+  chrtId: number;
+  /** WB warehouse ID */
+  warehouseId: number;
+  /** WB warehouse name */
+  warehouseName: string;
+  /** Region name */
+  regionName: string;
+  /** Current quantity in warehouse */
+  quantity: number;
+  /** Quantity in transit to client */
+  inWayToClient: number;
+  /** Quantity in transit from client (returns) */
+  inWayFromClient: number;
+}
+
+/** Response from POST /api/analytics/v1/stocks-report/wb-warehouses
+ * @since 3.4.0 */
+export interface WbWarehousesStockResponse {
+  data: {
+    items: WbWarehouseStockItem[];
+  };
+}

tests/unit/modules/analytics.test.ts

@@ -2,7 +2,7 @@
  * Unit Tests for Analytics Module (EPIC 41 & 42)
  *
  * Tests cover:
- * - rateLimitKey wiring for all 16 active methods
+ * - rateLimitKey wiring for all 17 active methods
  * - Type fixes (AvailabilityFilters, TableProductItem)
  * - Return type fixes (getDownloadsFile → ArrayBuffer)
  *
@@ -16,6 +16,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { AnalyticsModule } from '../../../src/modules/analytics';
 import type { BaseClient } from '../../../src/client/base-client';
+import { AuthenticationError } from '../../../src/errors/auth-error';
+import { RateLimitError } from '../../../src/errors/rate-limit-error';
 import type {
   AvailabilityFilters,
   TableProductItem,
@@ -402,7 +404,7 @@ describe('AnalyticsModule', () => {
   // ==========================================================================
 
   describe('All module methods exist', () => {
-    it('should have all 16 active methods', () => {
+    it('should have all 17 active methods', () => {
       // CSV Export (4)
       expect(typeof module.getNmReportDownloads).toBe('function');
       expect(typeof module.createNmReportDownload).toBe('function');
@@ -426,9 +428,90 @@ describe('AnalyticsModule', () => {
       expect(typeof module.getSalesFunnelProducts).toBe('function');
       expect(typeof module.getSalesFunnelProductsHistory).toBe('function');
       expect(typeof module.getSalesFunnelGroupedHistory).toBe('function');
+
+      // v1 WB Warehouses Inventory (1)
+      expect(typeof module.getWbWarehousesStock).toBe('function');
     });
 
     // Note: Deprecated v2 wrapper methods (createNmReportDetail, createDetailHistory,
     // createGroupedHistory) have been removed in v3.0.0
   });
+
+  // ============================================================================
+  // getWbWarehousesStock (v1 WB Warehouses Inventory)
+  // ============================================================================
+
+  describe('getWbWarehousesStock()', () => {
+    const WB_WAREHOUSES_URL = `${BASE_URL}/api/analytics/v1/stocks-report/wb-warehouses`;
+
+    it('should return inventory items with warehouse and region data', async () => {
+      const mockResponse = {
+        data: {
+          items: [
+            {
+              nmId: 395996251,
+              chrtId: 572682891,
+              warehouseId: 130744,
+              warehouseName: 'Краснодар',
+              regionName: 'Южный + Северо-Кавказский',
+              quantity: 10,
+              inWayToClient: 3,
+              inWayFromClient: 0,
+            },
+          ],
+        },
+      };
+      mockClient.post.mockResolvedValue(mockResponse);
+
+      const result = await module.getWbWarehousesStock({ nmIds: [395996251] });
+
+      expect(result.data.items).toHaveLength(1);
+      expect(result.data.items[0].warehouseId).toBe(130744);
+      expect(result.data.items[0].warehouseName).toBe('Краснодар');
+      expect(result.data.items[0].regionName).toBe('Южный + Северо-Кавказский');
+      expect(result.data.items[0].quantity).toBe(10);
+    });
+
+    it('should call correct URL and rateLimitKey', async () => {
+      mockClient.post.mockResolvedValue({ data: { items: [] } });
+
+      await module.getWbWarehousesStock({ nmIds: [123], limit: 100, offset: 50 });
+
+      expect(mockClient.post).toHaveBeenCalledWith(
+        WB_WAREHOUSES_URL,
+        { nmIds: [123], limit: 100, offset: 50 },
+        { rateLimitKey: 'analytics.postStocksReportWbWarehouses' }
+      );
+    });
+
+    it('should send empty object when no params provided', async () => {
+      mockClient.post.mockResolvedValue({ data: { items: [] } });
+
+      await module.getWbWarehousesStock();
+
+      expect(mockClient.post).toHaveBeenCalledWith(
+        WB_WAREHOUSES_URL,
+        {},
+        { rateLimitKey: 'analytics.postStocksReportWbWarehouses' }
+      );
+    });
+
+    it('should propagate AuthenticationError', async () => {
+      mockClient.post.mockRejectedValue(new AuthenticationError('Invalid API key'));
+      await expect(module.getWbWarehousesStock()).rejects.toThrow(AuthenticationError);
+    });
+
+    it('should propagate RateLimitError', async () => {
+      mockClient.post.mockRejectedValue(new RateLimitError('Rate limit exceeded', 5000));
+      await expect(module.getWbWarehousesStock()).rejects.toThrow(RateLimitError);
+    });
+
+    it('should handle empty items array', async () => {
+      mockClient.post.mockResolvedValue({ data: { items: [] } });
+
+      const result = await module.getWbWarehousesStock({ nmIds: [999999] });
+
+      expect(result.data.items).toEqual([]);
+    });
+  });
 });