@clipwright/core 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dimantika LLC
+Copyright (c) 2026 Dimantika Sp. z o.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/account.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+/**
+ * ТЕЛО `GET /v1/account` (US-602).
+ *
+ * ПУТЬ ОБЪЯВЛЕН ДАВНО, ТЕЛО — НЕТ. `docs/03-api.md` обещает этот маршрут с
+ * телом `{plan, credits_balance, renews_at}`. Путь берётся объявленный, тело —
+ * честное: `plan` и `renews_at` мертвы по ADR-012 (тарифных планов и продлений
+ * в продукте нет), и отдавать их означало бы поддерживать поля, за которыми
+ * ничего не стоит. Обещание снимается из документа отдельной стори (US-623).
+ *
+ * ЧЕТЫРЕ ЧИСЛА, А НЕ ОДНО, И КАЖДОЕ ОТВЕЧАЕТ НА СВОЙ ВОПРОС:
+ *  - `balance_credits` — сколько денег есть;
+ *  - `debt_credits` — сколько должен (блокирует новые раны отдельным кодом);
+ *  - `holds_credits` — сколько заморожено под уже идущими ранами;
+ *  - `daily_remaining_credits` — сколько ещё пропустит НАШ суточный
+ *    предохранитель.
+ *
+ * Последнее — НЕ деньги, и потому названо отдельно, а не вычтено из баланса.
+ * Смешай их — и клиент с деньгами на счету, упёршийся в наш операционный
+ * лимит, прочтёт это как «кончились кредиты» и пойдёт покупать ещё. Ровно то
+ * же различение держат два разных кода отказа (`errors.ts`).
+ */
+/**
+ * Начисление. `source` — z.string(), а не enum: перечень источников живёт в
+ * базе и пополняется (промо, партнёрка), а read-контракт обязан переживать
+ * новое значение у уже установленного клиента — та же асимметрия чтения и
+ * записи, что у стадий рана (`runRead`).
+ */
+export declare const creditGrant: z.ZodObject<{
+    amount: z.ZodNumber;
+    source: z.ZodString;
+    expires_at: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type CreditGrant = z.infer<typeof creditGrant>;
+export declare const account: z.ZodObject<{
+    account_id: z.ZodString;
+    balance_credits: z.ZodNumber;
+    debt_credits: z.ZodNumber;
+    holds_credits: z.ZodNumber;
+    daily_remaining_credits: z.ZodNumber;
+    grants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        amount: z.ZodNumber;
+        source: z.ZodString;
+        expires_at: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Account = z.infer<typeof account>;

package/dist/account.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * ТЕЛО `GET /v1/account` (US-602).
+ *
+ * ПУТЬ ОБЪЯВЛЕН ДАВНО, ТЕЛО — НЕТ. `docs/03-api.md` обещает этот маршрут с
+ * телом `{plan, credits_balance, renews_at}`. Путь берётся объявленный, тело —
+ * честное: `plan` и `renews_at` мертвы по ADR-012 (тарифных планов и продлений
+ * в продукте нет), и отдавать их означало бы поддерживать поля, за которыми
+ * ничего не стоит. Обещание снимается из документа отдельной стори (US-623).
+ *
+ * ЧЕТЫРЕ ЧИСЛА, А НЕ ОДНО, И КАЖДОЕ ОТВЕЧАЕТ НА СВОЙ ВОПРОС:
+ *  - `balance_credits` — сколько денег есть;
+ *  - `debt_credits` — сколько должен (блокирует новые раны отдельным кодом);
+ *  - `holds_credits` — сколько заморожено под уже идущими ранами;
+ *  - `daily_remaining_credits` — сколько ещё пропустит НАШ суточный
+ *    предохранитель.
+ *
+ * Последнее — НЕ деньги, и потому названо отдельно, а не вычтено из баланса.
+ * Смешай их — и клиент с деньгами на счету, упёршийся в наш операционный
+ * лимит, прочтёт это как «кончились кредиты» и пойдёт покупать ещё. Ровно то
+ * же различение держат два разных кода отказа (`errors.ts`).
+ */
+/**
+ * Начисление. `source` — z.string(), а не enum: перечень источников живёт в
+ * базе и пополняется (промо, партнёрка), а read-контракт обязан переживать
+ * новое значение у уже установленного клиента — та же асимметрия чтения и
+ * записи, что у стадий рана (`runRead`).
+ */
+export const creditGrant = z.object({
+    amount: z.number().int(),
+    source: z.string(),
+    /** `null` — грант бессрочный. */
+    expires_at: z.string().datetime().nullable(),
+    created_at: z.string().datetime(),
+});
+export const account = z.object({
+    account_id: z.string(),
+    balance_credits: z.number().int().nonnegative(),
+    debt_credits: z.number().int().nonnegative(),
+    holds_credits: z.number().int().nonnegative(),
+    daily_remaining_credits: z.number().int().nonnegative(),
+    /** Только НЕИСТЁКШИЕ: истёкший грант в баланс не входит и в списке не лжёт. */
+    grants: z.array(creditGrant).default([]),
+});
+//# sourceMappingURL=account.js.map

package/dist/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,iCAAiC;IACjC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC/C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC7C,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACvD,+EAA+E;IAC/E,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACzC,CAAC,CAAC"}

package/dist/api-failure.d.ts

@@ -0,0 +1,174 @@
+/**
+ * РАЗБОР ОТКАЗА API — ОДИН НА ВСЕ КЛИЕНТСКИЕ ПОВЕРХНОСТИ (US-622).
+ *
+ * ЧТО БЫЛО. `packages/sdk` сводил ЛЮБОЙ не-2xx к плоскому `new Error(message)`:
+ * ни статуса, ни кода, ни `Retry-After`. Пока API отвечал одними четырёхсотыми
+ * «поле не то», разницы не было — отказ был один, и делать с ним было нечего,
+ * кроме как показать текст. Фаза 1 добавила три кода, с которыми надо
+ * ПОСТУПАТЬ по-разному: 429 — подождать и повторить, 402 — остановиться и
+ * сказать человеку числа, 5xx — повторить без паузы от сервера. Плоский `Error`
+ * делает все три неразличимыми, и клиент выбирает худший вариант из трёх:
+ * первый же 429 на поллинге убивает `makeUgc` целиком.
+ *
+ * ПОЧЕМУ РАЗБОР ЖИВЁТ ЗДЕСЬ, А НЕ В SDK. Поверхностей, читающих отказ, три —
+ * SDK, MCP-форматтер и CLI, — и решение «ретраить или нет» обязано быть у них
+ * общим. Разъедься оно, и MCP советовал бы агенту ждать там, где SDK уже сдался.
+ * Тот же довод, что и у самих схем (правило проекта №2): формы отказов уже
+ * лежат в `errors.ts` и `rate-limit.ts`, здесь — только их РАЗБОР и вывод.
+ *
+ * ЧЕГО ЭТОТ МОДУЛЬ НЕ ДЕЛАЕТ. Он не ходит в сеть и не знает про `fetch`:
+ * вход — статус, текст тела и заголовок. Поэтому его можно прогнать на всех
+ * формах ответа, включая те, которые живой сервер отдать не может, а прокси
+ * между ним и клиентом — вполне (HTML-страница про перегрузку).
+ */
+/** Отказ по частоте: 429 либо наш, либо чужой (прокси, edge тарифа). */
+export interface RateLimitedFailure {
+    kind: "rate_limited";
+    status: number;
+    message: string;
+    /** Через сколько секунд повторять. `undefined` — сервер не сказал. */
+    retryAfterSeconds: number | undefined;
+    /** Потолок ведра. Есть только у НАШЕГО тела; у прокси его нет. */
+    limit: number | undefined;
+    windowSeconds: number | undefined;
+}
+/** Кредитов меньше веса рана. Терминально: повтор не изменит баланс. */
+export interface InsufficientCreditsFailure {
+    kind: "insufficient_credits";
+    status: number;
+    message: string;
+    balanceCredits: number;
+    requiredCredits: number;
+}
+/** Висит долг. Тоже терминально, но лечится погашением, а не пополнением. */
+export interface DebtOutstandingFailure {
+    kind: "debt_outstanding";
+    status: number;
+    message: string;
+    debtCredits: number;
+}
+/** 5xx: сервер обещает, что дело в нём. Повторять можно. */
+export interface ServerFailure {
+    kind: "server_error";
+    status: number;
+    message: string;
+    retryAfterSeconds: number | undefined;
+}
+/** Всё остальное (4xx): повтор того же запроса даст то же самое. */
+export interface ClientFailure {
+    kind: "client_error";
+    status: number;
+    message: string;
+    /** Код из тела, если тело вообще было контрактным. */
+    code: string | undefined;
+}
+export type ApiFailure = RateLimitedFailure | InsufficientCreditsFailure | DebtOutstandingFailure | ServerFailure | ClientFailure;
+/**
+ * ПОВТОРЯТЬ ИЛИ НЕТ — ОДНОЙ ФУНКЦИЕЙ, а не условием на каждой поверхности.
+ *
+ * Ошибиться здесь можно в обе стороны, и цены разные. Не повторить 429 — это
+ * оборванный `makeUgc` на ране, за который уже заплачено. Повторить 402 — это
+ * агент, крутящий отказ по деньгам в цикле: баланс от повторов не растёт, а
+ * лимит частоты они съедают, и человек получает вместо «пополни счёт» молчание
+ * до самого дедлайна.
+ */
+export declare function isRetryableFailure(failure: ApiFailure): boolean;
+/**
+ * Пауза перед повтором, мс. `fallbackMs` — собственный шаг вызывателя (для
+ * поллинга это его интервал): он же и пол, потому что сервер, не назвавший
+ * `Retry-After`, не разрешил долбить чаще обычного.
+ *
+ * Вызывать имеет смысл только после `isRetryableFailure`; на терминальном
+ * отказе результат бессмыслен, и функция не притворяется, что это не так.
+ */
+export declare function retryDelayMs(failure: ApiFailure, fallbackMs: number): number;
+/**
+ * `Retry-After` в секундах, обе формы RFC 9110.
+ *
+ * ДВЕ ФОРМЫ — НЕ ПЕДАНТИЗМ. Дельту в секундах отдаёт наша мидлвара, а HTTP-дату
+ * — чужие прокси (её разрешает та же RFC, и nginx с облачными edge её ставят).
+ * Клиент, знающий только цифры, на дате получил бы `NaN` и либо не ждал вовсе,
+ * либо ждал бесконечность — обе ветки хуже, чем «подожди свой обычный шаг».
+ *
+ * `now` — параметр, а не `Date.now()` внутри: разбор даты обязан быть проверяем
+ * прогоном, а не зависеть от того, когда его запустили.
+ */
+export declare function parseRetryAfterSeconds(raw: string | null | undefined, now: Date): number | undefined;
+export interface ApiFailureInput {
+    status: number;
+    /**
+     * Сырой текст тела. Именно текст: `res.json()` на HTML бросает парсером.
+     *
+     * `undefined` — тело ПРОЧИТАТЬ НЕ УДАЛОСЬ (соединение оборвалось после
+     * заголовков). Это НЕ то же самое, что пустое или чужое тело, и путать их
+     * нельзя: по пустой строке нельзя судить, кто ответил (внешнее ревью, круг 13).
+     */
+    bodyText: string | undefined;
+    /** Значение заголовка `Retry-After`, как его отдал сервер. */
+    retryAfterHeader?: string | null | undefined;
+    /** Точка отсчёта для формы HTTP-date. */
+    now?: Date;
+}
+/**
+ * Статус + тело + заголовок → то, с чем можно ПОСТУПИТЬ.
+ *
+ * ТЕЛО УТОЧНЯЕТ СТАТУС, НО НЕ ОТМЕНЯЕТ ЕГО. Специализированная схема
+ * применяется, только если статус ей СООТВЕТСТВУЕТ: `rate_limited` — на 429,
+ * оба денежных кода — на 402.
+ *
+ * Первая редакция давала телу перевешивать статус, рассуждая так: код объявлен
+ * в теле, а статус по дороге переписывает кто угодно, значит 502 поверх нашего
+ * 402 — это всё ещё «не хватило кредитов». Внешнее ревью показало обратную
+ * сторону того же рассуждения, и она хуже. Кэширующий прокси, отдавший старое
+ * тело `debt_outstanding` с новым статусом 429, делал отказ ТЕРМИНАЛЬНЫМ: агент
+ * бросал бы уже оплаченный ран и требовал погасить долг, которого нет. Зеркально
+ * 402 с телом `rate_limited` становился РЕТРАЙНЫМ, прямо вопреки правилу «любой
+ * 402 останавливает». Получались и внутренне противоречивые отказы вида
+ * `status === 402 && retryable === true`.
+ *
+ * Сочетание статуса и кода из РАЗНЫХ ответов — это не сообщение, а его порча, и
+ * доверять в нём надо тому, что уцелело наверняка. Уцелел статус: он часть
+ * стартовой строки, его не кэшируют отдельно от тела и им управляет тот же
+ * узел, который решил ответить. Поэтому при расхождении класс отказа берётся из
+ * статуса, а текст — из тела: сказать «сервер перегружен, повтори» и оказаться
+ * неправым дешевле, чем бросить оплаченный ран.
+ *
+ * ЧИСЛА `retry_after_seconds` ИЗ ТЕЛА СИЛЬНЕЕ ЗАГОЛОВКА — здесь тело выигрывает
+ * законно, потому что спорят два поля ОДНОГО ответа, а не ответ с самим собой.
+ * Наша мидлвара ставит в оба места одно число, и заголовок переписывают чаще.
+ */
+export declare function parseApiFailure(input: ApiFailureInput): ApiFailure;
+/**
+ * ОТКАЗ, РАЗВЁРНУТЫЙ ДЛЯ АГЕНТА, — ОДНОЙ ФУНКЦИЕЙ НА ВСЕ ПОВЕРХНОСТИ (US-622).
+ *
+ * ПОЧЕМУ НЕ «ПРОСТО ТЕКСТ ОШИБКИ». Отказ по деньгам — это не сбой, а РАЗВИЛКА,
+ * и агент обязан её пройти, а не ретраить: 402 повторами не лечится, баланс от
+ * них не растёт. Значит ответ обязан нести три вещи, которых в строке нет:
+ * числа (сколько есть, сколько нужно), императив («останови и скажи человеку»)
+ * и признак, что повторять бессмысленно. Форма скопирована с `next_action` из
+ * ADR-009 ровно потому, что она уже работает: `make_ugc` и `get_run` говорят с
+ * агентом так же, и отказ, говорящий иначе, читался бы как другой продукт.
+ *
+ * ПОЧЕМУ ЗДЕСЬ, А НЕ В MCP-ФОРМАТТЕРЕ. Поверхностей три, и разъехаться им
+ * нельзя: MCP отдаёт этот объект агенту, CLI печатает те же числа человеку, а
+ * SDK держит их в типизированной ошибке. Собери форму в MCP — и CLI пришлось бы
+ * собирать её ВТОРОЙ раз, то есть завести второй источник правды о том, что
+ * значит отказ (правило проекта №2).
+ */
+export interface AgentFailureReport {
+    /** Императив: повторять этот же вызов позже или прекратить. */
+    status: "RETRY_LATER" | "FAILED";
+    /** Машиночитаемая причина. Для чужих тел — `http_<status>`. */
+    code: string;
+    message: string;
+    /** Дубль `status` для условия в коде: строку легко сравнить неверно. */
+    retryable: boolean;
+    next_action: string;
+    retry_after_seconds?: number;
+    limit?: number;
+    window_seconds?: number;
+    balance_credits?: number;
+    required_credits?: number;
+    debt_credits?: number;
+}
+export declare function agentFailureReport(failure: ApiFailure): AgentFailureReport;