release 0.1.0

2026-08-21 12:15:56 +00:00
parent 2dcda172db
commit 3906c2656a
3295 changed files with 251007 additions and 3 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,104 @@
-# yandex-market-typescript
-
-JavaScript/TypeScript client for Yandex Market Partner API (MIT)
+# @apilki/yandex-market — JavaScript/TypeScript клиент
+
+**Версия: 0.1.0 · API от 2026-08-20** <!-- штампуется пайплайном (github-distro) -->
+
+JavaScript/TypeScript клиент для **Yandex Market Partner API** (продавец-сторона: заказы, каталог, цены, отчёты). Построен на базе `fetch` API. Работает и в Node.js, и в браузере. Публикуется в npm-скоупе `@apilki` (GitHub-орг `apilki`).
+
+## Особенности сборки
+- **Типизация**: Полная поддержка TypeScript (`.d.ts` включены).
+- **Стиль имен**: 
+  - Методы и классы: `camelCase` (например, `orderApi.getOrders`).
+  - Свойства объектов (JSON): **Original** (сохранено именование из спецификации Яндекса, обычно это `camelCase`).
+- **Аргументы методов**: Плоский список (позиционный). Первым параметром в большинстве методов идет `campaignId`.
+
+## Быстрый старт
+
+### 1. Инициализация клиента
+
+Авторизация настраивается один раз через `Configuration`. Ключ передается в заголовке `Api-Key`.
+
+```javascript
+import { Configuration, OrderApi, CampaignsApi } from '@apilki/yandex-market';
+
+const config = new Configuration({
+    basePath: 'https://api.partner.market.yandex.ru',
+    headers: {
+        'Api-Key': 'ACMA:YOUR_SECRET_KEY',
+        'Content-Type': 'application/json'
+    }
+});
+
+const orderApi = new OrderApi(config);
+const campaignsApi = new CampaignsApi(config);
+```
+
+## 2. Работа с несколькими кабинетами или магазинами
+
+В зависимости от метода API Яндекса, первым аргументом может выступать либо **campaignId** (идентификатор магазина), либо **businessId** (идентификатор бизнеса/кабинета). Ключ авторизации `Api-Key` уже находится в заголовках конфигурации, поэтому он не требуется в аргументах.
+
+```javascript
+const campaignId = 12345678; 
+const businessId = 987654;
+
+async function fetchData() {
+    try {
+        // Пример метода с campaignId (Заказы)
+        const orders = await orderApi.getOrders(campaignId, { status: 'PROCESSING' });
+
+        // Пример метода с businessId (Каталог/Цены)
+        const offers = await assortmentApi.getOfferMappings(businessId, { limit: 100 });
+        
+        console.log('Данные получены');
+    } catch (error) {
+        console.error('Yandex API Error:', error);
+    }
+}
+```
+
+### 3. Обработка ошибок
+
+В случае ошибок 4xx/5xx клиент выбрасывает ResponseError. Ответ Яндекса обычно содержит объект с массивом ошибок.
+
+```javascript
+try {
+    await orderApi.getOrders(...);
+} catch (error) {
+    const errorBody = await error.response.json();
+    // Структура ошибки Яндекса: { status: "ERROR", errors: [...] }
+    console.error('Errors:', errorBody.errors);
+}
+```
+
+### 4. Отладка (Middleware)
+
+Для отладки сетевых запросов используйте Middleware:
+
+```javascript
+const config = new Configuration({
+    middleware: [{
+        pre: async (context) => {
+            console.log(`[Yandex Request] ${context.url}`);
+            return context;
+        }
+    }]
+});
+```
+
+### Важные замечания
+
+Порядок аргументов: В большинстве методов Яндекса первым аргументом идет campaignId. Всегда проверяйте сигнатуру метода через автодополнение в IDE.
+
+**Идентификаторы (ID):** Внимательно следите за сигнатурой метода в IDE.
+* Если метод относится к операциям магазина — первым аргументом идет campaignId.
+* Если к настройкам каталога или финтеху — первым аргументом идет businessId.
+
+**JSON:** Мы сохранили оригинальное именование полей. Если поле в документации Яндекса называется deliveryServiceId, в коде оно будет точно таким же.
+
+**Fetch:** В среде Node.js < 18 требуется полифил node-fetch.
+
+**Авторизация:** Если Api-Key не задан в Configuration, он может потребоваться первым аргументом в каждом методе. Проверяйте подсказки IDE.
+
+### Ссылки
+
+* [Официальная документация API Яндекс Маркета для продавцов](https://yandex.ru/dev/market/partner-api/doc/ru/)
+* [Спецификация API Яндекс Маркета для продавцов](https://github.com/yandex-market/yandex-market-partner-api)