yandex-kit-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zinnur Temerbekov
+
+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.md

@@ -0,0 +1,35 @@
+# yandex-kit-core
+
+Типизированный клиент **API Яндекс KIT** — конструктора интернет-магазинов ([kit.yandex.ru](https://kit.yandex.ru)), построенный по официальной OpenAPI-спеке (133 операции). Основа MCP-сервера [`mcp-yandex-kit`](https://www.npmjs.com/package/mcp-yandex-kit), но пригоден и как самостоятельный клиент.
+
+Что внутри:
+
+- **`KitClient`** — Bearer-авторизация, таймаут на попытку, лимитер 3 rps (token bucket), ретраи с бэкоффом на сетевых ошибках, 5xx, 429 и `LIMIT_EXCEEDED` (который KIT возвращает с **HTTP 400**), автопагинация `listAll`, корректные content-type (`merge-patch+json`, `multipart/form-data`) там, где их требует API.
+- **`KitApiError`** — типизированные ошибки API: `status`, `code`, `message`, `trace_id`.
+- **ajv-валидация** — `validateRequestBody` / `resolveOperationSchema` проверяют тела запросов по схемам спеки **до** отправки в сеть.
+- **Сгенерированный реестр операций** — метод, путь, параметры и content-type каждой из 133 операций.
+
+## Использование
+
+```js
+import { KitClient } from "yandex-kit-core";
+
+const client = new KitClient({ token: process.env.YANDEX_KIT_TOKEN });
+
+// Любая операция по её operationId из спеки
+const store = await client.call("GetStore");
+
+// Автопагинация списков (per_page=100, до maxItems элементов)
+const { items } = await client.listAll("GetProducts", {}, { maxItems: 500 });
+```
+
+Требования: Node.js 20+.
+
+## Документация
+
+- [Репозиторий проекта](https://github.com/ztemerbekov/a1-yandex-kit-skills) — полный README, MCP-сервер, агентские скиллы.
+- [Официальная документация Яндекс KIT](https://yandex.ru/dev/kit/ru/) — авторизация, лимиты, ошибки, OpenAPI-справочник.
+
+## Лицензия
+
+MIT — см. [LICENSE](https://github.com/ztemerbekov/a1-yandex-kit-skills/blob/main/LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+export interface KitClientOptions {
+    token: string;
+    /** Default: https://api.kit.yandex.net */
+    baseUrl?: string;
+    /** Requests per second (token bucket capacity). Default: 3. */
+    rps?: number;
+    /** Per-attempt timeout in milliseconds. Default: 30000. */
+    timeoutMs?: number;
+    /** Maximum number of retries after the first attempt. Default: 3. */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in milliseconds. Default: 500. */
+    retryBaseMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface CallParams {
+    pathParams?: Record<string, string | number>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+}
+interface RawRequest {
+    method: string;
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    contentType?: string;
+}
+export declare class KitClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    private readonly fetchImpl;
+    private readonly bucket;
+    constructor(opts: KitClientOptions);
+    /** Execute an operation from the generated registry by its operationId. */
+    call<T = unknown>(operationId: string, params?: CallParams): Promise<T>;
+    /** Low-level request with rate limiting, timeout and retries. */
+    request<T = unknown>(req: RawRequest): Promise<T>;
+    /**
+     * Fetch all pages of a paginated list operation (per_page=100).
+     * Stops on a short page or once maxItems is reached (truncated=true).
+     */
+    listAll<T = unknown>(operationId: string, params?: CallParams, opts?: {
+        maxItems?: number;
+    }): Promise<{
+        items: T[];
+        pages: number;
+        truncated: boolean;
+    }>;
+    private backoffDelayMs;
+    private fetchWithTimeout;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,266 @@
+/**
+ * Fetch-based client for the Yandex KIT API.
+ *
+ * Features (see PLAN.md §2/§6): Bearer auth, per-attempt timeout via
+ * AbortController, token-bucket rate limiter (default 3 rps, gates every
+ * attempt including retries), exponential backoff retries (network/abort,
+ * 429, >=500, and HTTP 400 with code LIMIT_EXCEEDED — KIT returns rate-limit
+ * errors as 400), per-operation content type from the generated registry
+ * (json / merge-patch+json / multipart), and auto-pagination via listAll().
+ */
+import { KitApiError, KitValidationError } from "./errors.js";
+import { getOp } from "./registry.js";
+const DEFAULT_BASE_URL = "https://api.kit.yandex.net";
+const LIST_ALL_PER_PAGE = 100;
+/** Codes of a parsed KIT error body. LIMIT_EXCEEDED arrives with HTTP 400. */
+const RETRYABLE_400_CODE = "LIMIT_EXCEEDED";
+// NOTE: the timer must stay ref'd — an in-flight request awaiting its backoff
+// delay has to keep the event loop (and thus the process) alive.
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Promise-based FIFO token bucket: capacity = rps tokens, refilled
+ * continuously at rps tokens/second. A single pending timer is kept while the
+ * queue is non-empty and cleared as soon as it drains; the timer stays ref'd
+ * so queued requests keep the process alive until they are dispatched.
+ */
+class TokenBucket {
+    rps;
+    tokens;
+    lastRefill;
+    queue = [];
+    timer = null;
+    constructor(rps) {
+        this.rps = rps;
+        this.tokens = rps; // allow an initial burst of up to rps requests
+        this.lastRefill = Date.now();
+    }
+    acquire() {
+        return new Promise((resolve) => {
+            this.queue.push(resolve);
+            this.drain();
+        });
+    }
+    refill() {
+        const now = Date.now();
+        const elapsedSec = (now - this.lastRefill) / 1000;
+        this.lastRefill = now;
+        // Cap at no less than 1 token: with rps < 1 a cap of exactly rps would
+        // never let tokens reach the 1 needed to dispatch (permanent stall).
+        const capacity = Math.max(this.rps, 1);
+        this.tokens = Math.min(capacity, this.tokens + elapsedSec * this.rps);
+    }
+    drain() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.refill();
+        while (this.queue.length > 0 && this.tokens >= 1) {
+            this.tokens -= 1;
+            const release = this.queue.shift();
+            release();
+        }
+        if (this.queue.length > 0) {
+            const waitMs = Math.max(1, Math.ceil(((1 - this.tokens) / this.rps) * 1000));
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                this.drain();
+            }, waitMs);
+        }
+    }
+}
+function buildQueryString(query) {
+    if (!query)
+        return "";
+    const sp = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item === undefined || item === null)
+                    continue;
+                sp.append(key, String(item));
+            }
+        }
+        else {
+            sp.append(key, String(value));
+        }
+    }
+    const s = sp.toString();
+    return s ? `?${s}` : "";
+}
+function parseRetryAfterMs(res) {
+    const header = res.headers.get("retry-after");
+    if (!header)
+        return undefined;
+    const seconds = Number.parseInt(header, 10);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+}
+export class KitClient {
+    token;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    retryBaseMs;
+    fetchImpl;
+    bucket;
+    constructor(opts) {
+        this.token = opts.token;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.maxRetries = opts.maxRetries ?? 3;
+        this.retryBaseMs = opts.retryBaseMs ?? 500;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        const rps = opts.rps ?? 3;
+        if (!Number.isFinite(rps) || rps <= 0) {
+            throw new KitValidationError(`rps must be a positive number, got: ${rps}`);
+        }
+        this.bucket = new TokenBucket(rps);
+    }
+    /** Execute an operation from the generated registry by its operationId. */
+    async call(operationId, params = {}) {
+        const op = getOp(operationId);
+        let path = op.path;
+        for (const name of op.pathParams) {
+            const value = params.pathParams?.[name];
+            if (value === undefined || value === null) {
+                throw new KitValidationError(`Missing path parameter "${name}" for operation ${operationId}`);
+            }
+            path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
+        }
+        return this.request({
+            method: op.method,
+            path,
+            query: params.query,
+            body: params.body,
+            contentType: op.requestContentType ?? undefined,
+        });
+    }
+    /** Low-level request with rate limiting, timeout and retries. */
+    async request(req) {
+        const url = this.baseUrl + req.path + buildQueryString(req.query);
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+        };
+        let body;
+        if (req.body !== undefined) {
+            const contentType = req.contentType ?? "application/json";
+            if (contentType === "multipart/form-data") {
+                // Let fetch set the multipart boundary header itself.
+                body = req.body;
+            }
+            else {
+                headers["Content-Type"] = contentType;
+                body = JSON.stringify(req.body);
+            }
+        }
+        const init = { method: req.method.toUpperCase(), headers, body };
+        for (let attempt = 0;; attempt++) {
+            await this.bucket.acquire();
+            let res;
+            let text;
+            try {
+                const result = await this.fetchWithTimeout(url, init);
+                res = result.res;
+                text = result.text;
+            }
+            catch (err) {
+                // Network failure or per-attempt timeout (abort): retryable.
+                if (attempt < this.maxRetries) {
+                    await sleep(this.backoffDelayMs(attempt));
+                    continue;
+                }
+                throw err;
+            }
+            if (res.ok) {
+                if (res.status === 204 || text.trim() === "")
+                    return undefined;
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    throw new KitApiError(res.status, "INVALID_JSON", `Failed to parse response body as JSON: ${text.slice(0, 500)}`);
+                }
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = undefined;
+            }
+            const retryable = res.status === 429 ||
+                res.status >= 500 ||
+                (res.status === 400 && parsed?.code === RETRYABLE_400_CODE);
+            if (retryable && attempt < this.maxRetries) {
+                const delay = parseRetryAfterMs(res) ?? this.backoffDelayMs(attempt);
+                await sleep(delay);
+                continue;
+            }
+            if (parsed && typeof parsed === "object" && typeof parsed.code === "string") {
+                throw new KitApiError(res.status, parsed.code, parsed.message ?? `HTTP ${res.status}`, parsed.trace_id, parsed);
+            }
+            throw new KitApiError(res.status, "HTTP_ERROR", text.slice(0, 500));
+        }
+    }
+    /**
+     * Fetch all pages of a paginated list operation (per_page=100).
+     * Stops on a short page or once maxItems is reached (truncated=true).
+     */
+    async listAll(operationId, params = {}, opts = {}) {
+        const op = getOp(operationId);
+        if (!op.paginated || !op.itemsProp) {
+            throw new KitValidationError(`Operation ${operationId} is not a paginated list operation`);
+        }
+        const itemsProp = op.itemsProp;
+        const maxItems = opts.maxItems ?? 500;
+        const items = [];
+        let pages = 0;
+        let truncated = false;
+        for (let page = 1;; page++) {
+            const res = await this.call(operationId, {
+                ...params,
+                query: { ...params.query, page, per_page: LIST_ALL_PER_PAGE },
+            });
+            pages++;
+            const raw = res?.[itemsProp];
+            const pageItems = Array.isArray(raw) ? raw : [];
+            const room = maxItems - items.length;
+            if (pageItems.length > room) {
+                items.push(...pageItems.slice(0, room));
+                truncated = true;
+                break;
+            }
+            items.push(...pageItems);
+            if (pageItems.length < LIST_ALL_PER_PAGE)
+                break; // last page
+            if (items.length >= maxItems) {
+                truncated = true; // cap hit exactly on a full page — more may exist
+                break;
+            }
+        }
+        return { items, pages, truncated };
+    }
+    backoffDelayMs(attempt) {
+        const base = this.retryBaseMs * 2 ** attempt;
+        return base + Math.random() * base * 0.25; // +0-25% jitter
+    }
+    async fetchWithTimeout(url, init) {
+        const controller = new AbortController();
+        // Ref'd on purpose (cleared in finally): an unref'd abort timer could let
+        // the process exit mid-request when no other handle keeps the loop alive.
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(url, { ...init, signal: controller.signal });
+            const text = res.status === 204 ? "" : await res.text();
+            return { res, text };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Error types for the Yandex KIT API client.
+ *
+ * The API error contract (verified live) is a JSON body:
+ *   {"code": "...", "message": "...", "trace_id": "..."}
+ */
+/** HTTP-level error returned by the KIT API. */
+export declare class KitApiError extends Error {
+    status: number;
+    code: string;
+    traceId?: string;
+    details?: unknown;
+    constructor(status: number, code: string, message: string, traceId?: string, details?: unknown);
+}
+/** Client-side validation error raised before any network call. */
+export declare class KitValidationError extends Error {
+    errors: string[];
+    constructor(message: string, errors?: string[]);
+}

package/dist/errors.js

@@ -0,0 +1,30 @@
+/**
+ * Error types for the Yandex KIT API client.
+ *
+ * The API error contract (verified live) is a JSON body:
+ *   {"code": "...", "message": "...", "trace_id": "..."}
+ */
+/** HTTP-level error returned by the KIT API. */
+export class KitApiError extends Error {
+    status;
+    code;
+    traceId;
+    details;
+    constructor(status, code, message, traceId, details) {
+        super(message);
+        this.name = "KitApiError";
+        this.status = status;
+        this.code = code;
+        this.traceId = traceId;
+        this.details = details;
+    }
+}
+/** Client-side validation error raised before any network call. */
+export class KitValidationError extends Error {
+    errors;
+    constructor(message, errors = []) {
+        super(message);
+        this.name = "KitValidationError";
+        this.errors = errors.length > 0 ? errors : [message];
+    }
+}