ozon-seller-sdk

Auto-generated TypeScript SDK for Ozon Seller API with Zod runtime validation.

• 410 typed API methods, auto-generated from Ozon OpenAPI spec
• Ergonomic bound API — no boilerplate per call
• Non-blocking Zod validation for API drift detection
• Dual ESM/CJS, Node 18+, TypeScript strict

Install

npm install ozon-seller-sdk

Quick Start

import { createOzonApi } from 'ozon-seller-sdk';

const ozon = createOzonApi({
  apiKey: 'your-api-key',
  clientId: 'your-client-id',
});

// List products
const { data } = await ozon.productApiGetProductList({
  filter: { visibility: 'ALL' },
  limit: 100,
});

// Get product info
const { data: info } = await ozon.productApiGetProductInfoList({
  offer_id: ['SKU-001', 'SKU-002'],
});

// Update prices
await ozon.productApiImportProductsPrices({
  prices: [{ offer_id: 'SKU-001', price: '1500', old_price: '2000' }],
});

API

createOzonApi(config) — Recommended

Creates a fully configured API client with 410 typed methods.

const ozon = createOzonApi({
  apiKey: string,        // Required — Ozon API key
  clientId: string,      // Required — Ozon Client-Id
  baseUrl?: string,      // Default: 'https://api-seller.ozon.ru'
  logErrors?: boolean,   // Enable HTTP error logging
  errorLogger?: (entry: ValidationLogEntry) => void,  // Required if logErrors: true
});

All methods accept a typed body object and return Promise<{ data, error, request, response }>.

The client is configured with throwOnError: true — failed requests throw instead of returning error objects.

createOzonClient(config) — Advanced

Low-level client for cases where you need direct control. Same config as above.

import { createOzonClient, productApiGetProductList } from 'ozon-seller-sdk';

const client = createOzonClient({ apiKey: '...', clientId: '...' });

const { data } = await productApiGetProductList({
  client,
  body: { filter: { visibility: 'ALL' }, limit: 100 },
});

validateResponse(data, schema, context) — Zod Validation

Manual response validation against Zod schemas. Non-blocking — always returns original data, logs mismatches.

import { validateResponse } from 'ozon-seller-sdk';
import { zProductApiGetProductListResponse } from 'ozon-seller-sdk/zod';

const { data } = await ozon.productApiGetProductList({ limit: 10 });

validateResponse(data, zProductApiGetProductListResponse, {
  operationId: 'productApiGetProductList',
  path: '/v3/product/list',
  logger: (entry) => console.warn('Validation mismatch:', entry),
});

HTTP Error Logging

const ozon = createOzonApi({
  apiKey: '...',
  clientId: '...',
  logErrors: true,
  errorLogger: (entry) => {
    // entry: { timestamp, operationId, path, issues: [...] }
    console.warn(`[${entry.path}] ${entry.issues[0]?.message}`);
  },
});

SDK Maintenance

Updating When Ozon API Changes

# 1. Download latest Ozon OpenAPI spec
npm run download

# 2. Regenerate SDK (fix spec → generate types → build)
npm run generate

# 3. Run tests — snapshot test will show added/removed methods
npm run test

# 4. If snapshot changed, review and update:
npm run test -- --update

# 5. Bump version, publish
npm version minor
npm publish

Build Pipeline

npm run generate
  ├── npm run fix             # Fix known Ozon spec issues (missing array types, broken refs)
  ├── npm run generate:types  # @hey-api/openapi-ts → src/generated/
  │   ├── post-generate.js    # Add @ts-nocheck to zod.gen.ts (known limitation)
  │   └── generate-bound-api.js  # Generate typed bound API interface
  └── npm run build           # tsc (ESM) → fix imports → esbuild (CJS bundle)

Project Structure

src/
├── index.ts              # Public exports
├── client.ts             # Client factory (auth, config)
├── bound-api.ts          # Ergonomic API wrapper
├── validation.ts         # Zod validation middleware
└── generated/            # AUTO-GENERATED — do not edit
    ├── sdk.gen.ts         # 410 SDK functions
    ├── types.gen.ts       # Request/response TypeScript types
    ├── zod.gen.ts         # Zod schemas for validation
    ├── bound-api.gen.ts   # Typed bound API interface
    ├── client/            # HTTP client infrastructure
    └── core/              # Serialization, auth, utilities
scripts/
├── download-swagger.sh    # Download Ozon OpenAPI spec
├── fix-swagger.ts         # Pre-generation spec fixes
├── generate-bound-api.js  # Post-generation: create bound API
├── post-generate.js       # Post-generation: fix zod.gen.ts
└── fix-esm-imports.js     # Post-build: add .js extensions for ESM

Rule: Edit only src/*.ts and scripts/. Never edit src/generated/ — it is overwritten on each npm run generate.

Troubleshooting

ERR_MODULE_NOT_FOUND at runtime

ESM imports require .js extensions. If you see this after a build, run:

npm run build

The build pipeline automatically adds .js extensions via fix-esm-imports.js.

swagger/swagger.json not found

Run npm run download first. The spec file is not committed to the repo.

Tests fail after regeneration

The snapshot test in bound-api.spec.ts tracks all method names. After regenerating from a new Ozon spec:

# Review changes in the snapshot diff, then:
npm run test -- --update

TypeScript errors in zod.gen.ts

Expected — the file has @ts-nocheck because hey-api's Zod plugin generates code with TS errors on complex Ozon specs (enum defaults, regex patterns). This is a known upstream limitation. sdk.gen.ts and types.gen.ts compile cleanly.

Methods missing from bound API

generate-bound-api.js uses regex to parse sdk.gen.ts. If hey-api changes its output format, methods may be silently dropped. The script has a safety guard — it throws if fewer than 400 methods are found. If you see this error after updating @hey-api/openapi-ts, the regex patterns in the script need updating.

API returns 403 / authentication errors

Check that apiKey and clientId are correct and non-empty. The SDK trims whitespace and throws on blank credentials.