artefactby-ozon-seller-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 artefactby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,196 @@
+# artefactby-ozon-seller-api
+
+Unofficial typed [Ozon Seller API](https://docs.ozon.ru/api/seller/) client for
+TypeScript and JavaScript.
+
+[README на русском](./README.md)
+
+```ts
+import { OzonClient } from 'artefactby-ozon-seller-api';
+
+const client = new OzonClient({
+  clientId: process.env.OZON_CLIENT_ID!,
+  apiKey: process.env.OZON_API_KEY!,
+});
+
+// `items` is typed from the path literal — no generics, no casts
+const { items } = await client.request('/v5/product/info/prices', {
+  cursor: '',
+  limit: 100,
+  filter: { visibility: 'ALL' },
+});
+```
+
+- **The whole API, not a curated subset.** Types are generated from the official
+  OpenAPI spec (API version 2.1): 458 operations, 2083 schemas. Every path is called
+  the same way, with the request body and response inferred from the path literal.
+- **Zero runtime dependencies.** Native `fetch` only. Node.js >= 18, CJS and ESM.
+- **A built-in rate limiter that knows Ozon's limits** — 50 rps per Client-Id plus the
+  per-method rates from the spec — as a separate subpath: skip it and it costs nothing.
+- **Careful retries.** Nearly every Ozon operation is a POST, so only calls rejected
+  with 429 or "Circle is open" are retried: those the API demonstrably did not process.
+  Retrying "just in case" is deliberately not a thing this client does.
+
+Status: 0.x — the public API may still change between minor releases. Not affiliated
+with Ozon.
+
+## Installation
+
+```bash
+npm install artefactby-ozon-seller-api
+```
+
+One client instance is bound to one Client-Id. The package never reads credentials from
+the environment on its own — pass them to the constructor explicitly.
+
+## Rate limiting
+
+Ozon answers 429 with `Retry-After` when a limit is exceeded and blocks a method for a
+few minutes ("Circle is open") after a burst. The client honours `Retry-After` on its
+own and repeats a rejected call up to `maxRetries` times (2 by default). To avoid
+hitting the limits at all, install the built-in limiter — it paces calls in advance:
+
+```ts
+import { OzonClient } from 'artefactby-ozon-seller-api';
+import { TokenBucketLimiter } from 'artefactby-ozon-seller-api/limiter';
+
+const client = new OzonClient({
+  clientId,
+  apiKey,
+  limiter: new TokenBucketLimiter({
+    // The defaults are exactly what Ozon documents: 50 rps globally plus the
+    // per-method rates from the spec (e.g. /v2/products/stocks — 80 per minute).
+    // Add limits you have measured yourself:
+    perPath: { '/v3/product/list': { limit: 20, intervalMs: 1_000 } },
+    maxSize: 5_000, // reject calls once the queue is this deep
+    waitTimeoutMs: 30_000, // reject calls that wait longer
+    hooks: {
+      onEnqueue: ({ size }) => metrics.gauge('ozon.queue', size),
+      onRateLimited: ({ path, until }) => log.warn({ path, until }, 'ozon 429'),
+      onCircuitOpen: ({ path, until }) => log.error({ path, until }, 'circle is open'),
+    },
+  }),
+});
+```
+
+Calls are served by priority (`priority` in the call options, higher first), then by
+arrival. A path stuck at its own limit does not block the others. Backpressure surfaces
+as a typed `OzonQueueError` with a `reason` of `queue-full`, `wait-timeout`, or
+`aborted`.
+
+The limiter is in-process. Several processes sharing one Client-Id each get their own
+budget — for a limit that spans instances, implement the `OzonRateLimiter` interface
+over shared storage:
+
+```ts
+import type { OzonRateLimiter } from 'artefactby-ozon-seller-api';
+
+const redisLimiter: OzonRateLimiter = {
+  async acquire({ path, priority, signal }) {
+    /* wait for a slot in Redis */
+  },
+  notify({ path, status, retryAfterMs, circuitOpen }) {
+    /* record the backoff so every instance sees it */
+  },
+};
+```
+
+## Error handling
+
+A non-2xx response throws an `OzonApiError`; transport failures (DNS, TLS, dropped
+connections) propagate untouched — the package does not wrap them.
+
+```ts
+import { isOzonApiError } from 'artefactby-ozon-seller-api';
+
+try {
+  await client.request('/v1/product/import/prices', { prices });
+} catch (error) {
+  if (isOzonApiError(error)) {
+    error.status; // HTTP status, e.g. 429
+    error.code; // Ozon's own error code, when the response carried one
+    error.retryAfterMs; // parsed Retry-After, when present
+    error.body; // response payload (object, or the raw text)
+  }
+  throw error;
+}
+```
+
+## Options
+
+```ts
+const client = new OzonClient({
+  clientId,
+  apiKey,
+  baseUrl: 'https://api-seller.ozon.ru', // default
+  fetch: customFetch, // default: the global fetch
+  headers: { 'User-Agent': 'my-app/1.0' }, // sent with every request
+  timeoutMs: 30_000, // off by default
+});
+
+await client.request('/v1/actions', undefined, {
+  signal: controller.signal,
+  timeoutMs: 5_000, // overrides the client-level timeout; 0 disables it
+  headers: { 'X-Request-Id': id },
+  priority: 10, // for the limiter: higher goes first
+});
+```
+
+The injectable `fetch` is the seam for tests: pass your own implementation to record
+and replay traffic. The package ships no mocks of its own.
+
+## Requests beyond the types
+
+`request()` covers the JSON operations. For everything else there is `requestRaw()` —
+it returns the untouched `Response` and does not throw on a non-2xx status:
+
+```ts
+// PDF with posting labels
+const response = await client.requestRaw('/v2/posting/fbs/package-label', {
+  posting_number: ['0001-1'],
+});
+const pdf = await response.blob();
+
+// The spec's single templated path needs an explicit method: with the guid
+// substituted, the URL no longer matches the spec literal
+const label = await client.requestRaw(`/v1/cargoes-label/file/${guid}`, undefined, {
+  method: 'GET',
+});
+```
+
+`multipart/form-data` (pass a `FormData`), binary bodies and `ReadableStream`s go
+through as-is; anything else is serialized as JSON. A stream is never retried — it is
+consumed by the first attempt that sends it.
+
+## Pagination is yours
+
+The package deliberately stops at the transport line: one call is one logical API
+request. Pagination loops, dataset assembly and batch splitting are your code, and the
+typed core leaves them very little to do:
+
+```ts
+const items = [];
+let cursor = '';
+do {
+  const page = await client.request('/v5/product/info/prices', {
+    cursor,
+    limit: 1000,
+    filter: { visibility: 'ALL' },
+  });
+  items.push(...(page.items ?? []));
+  cursor = page.cursor ?? '';
+} while (cursor !== '');
+```
+
+## Known limitations
+
+- The types are exactly as accurate as Ozon's spec. Where it diverges from reality,
+  `requestRaw()` is the way out.
+- The spec is updated in the package manually — brand-new API methods may lag behind.
+- The root entry's type declarations weigh about 3 MB (that is the entire spec); the
+  type checker's first pass will notice. The `/limiter` subpath is free of them.
+- The built-in limiter does not share its budget across processes (see above).
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,196 @@
+# artefactby-ozon-seller-api
+
+Неофициальный типизированный клиент [Ozon Seller API](https://docs.ozon.ru/api/seller/)
+для TypeScript и JavaScript.
+
+[README in English](./README.en.md)
+
+```ts
+import { OzonClient } from 'artefactby-ozon-seller-api';
+
+const client = new OzonClient({
+  clientId: process.env.OZON_CLIENT_ID!,
+  apiKey: process.env.OZON_API_KEY!,
+});
+
+// `items` типизирован из литерала пути — без generics и приведения типов
+const { items } = await client.request('/v5/product/info/prices', {
+  cursor: '',
+  limit: 100,
+  filter: { visibility: 'ALL' },
+});
+```
+
+- **Покрыт весь API, а не выборка методов.** Типы сгенерированы из официальной
+  OpenAPI-спеки (версия API 2.1): 458 операций, 2083 схемы. Любой путь спеки
+  вызывается одинаково, тело запроса и ответ выводятся из литерала пути.
+- **Ноль зависимостей в рантайме.** Только нативный `fetch`. Node.js >= 18, CJS и ESM.
+- **Встроенный rate limiter со знанием лимитов Ozon** — 50 rps на Client-Id плюс
+  пометодные лимиты из спеки — отдельным сабпатом: не подключили — не платите ничего.
+- **Осторожные ретраи.** Почти все операции Ozon — POST, поэтому повторяются только
+  запросы, отклонённые с 429 или «Circle is open»: их API гарантированно не обработал.
+  «Повторить на всякий случай» клиент не умеет намеренно.
+
+Статус: 0.x — публичный API может меняться между минорными версиями. Пакет не
+аффилирован с Ozon.
+
+## Установка
+
+```bash
+npm install artefactby-ozon-seller-api
+```
+
+Один экземпляр клиента привязан к одному Client-Id. Пакет никогда не читает ключи из
+окружения сам — передавайте их явно в конструктор.
+
+## Ограничение частоты запросов
+
+Ozon отвечает 429 с `Retry-After` при превышении лимита и блокирует метод на несколько
+минут («Circle is open») при шквале запросов. Клиент сам выдерживает `Retry-After` и
+повторяет отклонённый запрос до `maxRetries` раз (по умолчанию 2). Чтобы не упираться
+в лимиты вовсе, подключите встроенный лимитер — он выстраивает вызовы заранее:
+
+```ts
+import { OzonClient } from 'artefactby-ozon-seller-api';
+import { TokenBucketLimiter } from 'artefactby-ozon-seller-api/limiter';
+
+const client = new OzonClient({
+  clientId,
+  apiKey,
+  limiter: new TokenBucketLimiter({
+    // Дефолты — ровно то, что документирует Ozon: 50 rps глобально плюс
+    // пометодные лимиты из спеки (например, /v2/products/stocks — 80 в минуту).
+    // Сюда можно добавить лимиты, измеренные вами самостоятельно:
+    perPath: { '/v3/product/list': { limit: 20, intervalMs: 1_000 } },
+    maxSize: 5_000, // отклонять вызовы, когда очередь глубже
+    waitTimeoutMs: 30_000, // отклонять вызовы, ждущие дольше
+    hooks: {
+      onEnqueue: ({ size }) => metrics.gauge('ozon.queue', size),
+      onRateLimited: ({ path, until }) => log.warn({ path, until }, 'ozon 429'),
+      onCircuitOpen: ({ path, until }) => log.error({ path, until }, 'circle is open'),
+    },
+  }),
+});
+```
+
+Вызовы обслуживаются по приоритету (`priority` в опциях вызова, выше — раньше), внутри
+приоритета — по очереди. Путь, упёршийся в собственный лимит, не блокирует остальные.
+Backpressure приходит типизированной ошибкой `OzonQueueError` с `reason`:
+`queue-full`, `wait-timeout` или `aborted`.
+
+Лимитер работает в пределах одного процесса. Несколько процессов с одним Client-Id
+получат каждый свой бюджет — для общего лимита реализуйте интерфейс `OzonRateLimiter`
+поверх разделяемого хранилища:
+
+```ts
+import type { OzonRateLimiter } from 'artefactby-ozon-seller-api';
+
+const redisLimiter: OzonRateLimiter = {
+  async acquire({ path, priority, signal }) {
+    /* дождаться слота в Redis */
+  },
+  notify({ path, status, retryAfterMs, circuitOpen }) {
+    /* записать backoff, чтобы его увидели все инстансы */
+  },
+};
+```
+
+## Обработка ошибок
+
+Не-2xx ответ — это `OzonApiError`; транспортные сбои (DNS, TLS, обрыв) пролетают как
+есть, их пакет не заворачивает.
+
+```ts
+import { isOzonApiError } from 'artefactby-ozon-seller-api';
+
+try {
+  await client.request('/v1/product/import/prices', { prices });
+} catch (error) {
+  if (isOzonApiError(error)) {
+    error.status; // HTTP-статус, например 429
+    error.code; // код ошибки Ozon, если был в ответе
+    error.retryAfterMs; // разобранный Retry-After, если был
+    error.body; // тело ответа (объект или сырой текст)
+  }
+  throw error;
+}
+```
+
+## Опции
+
+```ts
+const client = new OzonClient({
+  clientId,
+  apiKey,
+  baseUrl: 'https://api-seller.ozon.ru', // по умолчанию
+  fetch: customFetch, // по умолчанию — глобальный fetch
+  headers: { 'User-Agent': 'my-app/1.0' }, // добавляются к каждому запросу
+  timeoutMs: 30_000, // выключен по умолчанию
+});
+
+await client.request('/v1/actions', undefined, {
+  signal: controller.signal,
+  timeoutMs: 5_000, // важнее клиентского; 0 отключает
+  headers: { 'X-Request-Id': id },
+  priority: 10, // для лимитера: выше — раньше
+});
+```
+
+Инжектируемый `fetch` — это шов для тестов: подставьте свою реализацию для записи и
+воспроизведения трафика. Собственных моков пакет не содержит.
+
+## Запросы мимо типов
+
+`request()` покрывает JSON-операции. Для остального есть `requestRaw()` — он возвращает
+нетронутый `Response` и не бросает на не-2xx статусе:
+
+```ts
+// PDF с этикетками отправлений
+const response = await client.requestRaw('/v2/posting/fbs/package-label', {
+  posting_number: ['0001-1'],
+});
+const pdf = await response.blob();
+
+// Единственный путь спеки с параметром в URL требует явного метода:
+// подставленный guid уже не совпадает с литералом из спеки
+const label = await client.requestRaw(`/v1/cargoes-label/file/${guid}`, undefined, {
+  method: 'GET',
+});
+```
+
+`multipart/form-data` (передайте `FormData`), бинарные тела и `ReadableStream`
+уходят как есть; всё остальное сериализуется в JSON. Стрим не ретраится никогда —
+его потребляет первая же попытка отправки.
+
+## Пагинация — на вашей стороне
+
+Пакет сознательно заканчивается на границе транспорта: один вызов — один логический
+запрос к API. Циклы пагинации, сборка датасетов, нарезка на батчи — это ваш код,
+которому типизированное ядро оставляет совсем немного работы:
+
+```ts
+const items = [];
+let cursor = '';
+do {
+  const page = await client.request('/v5/product/info/prices', {
+    cursor,
+    limit: 1000,
+    filter: { visibility: 'ALL' },
+  });
+  items.push(...(page.items ?? []));
+  cursor = page.cursor ?? '';
+} while (cursor !== '');
+```
+
+## Известные ограничения
+
+- Типы ровно настолько точны, насколько точна спека Ozon. Там, где она расходится с
+  реальностью, выручает `requestRaw()`.
+- Спека обновляется в пакете вручную — новые методы API могут появляться с задержкой.
+- Декларации типов корневого входа весят около 3 МБ (это вся спека): первый проход
+  тайпчекера их заметит. Сабпат `/limiter` от этого свободен.
+- Встроенный лимитер не разделяет бюджет между процессами (см. выше).
+
+## Лицензия
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1 @@
+export * from './index.js';