@clipwright/core 0.1.0 → 0.2.0

package/dist/api-failure.js

@@ -0,0 +1,450 @@
+import { apiError, debtOutstandingError, insufficientCreditsError } from "./errors.js";
+import { rateLimitedError } from "./rate-limit.js";
+/**
+ * ПОВТОРЯТЬ ИЛИ НЕТ — ОДНОЙ ФУНКЦИЕЙ, а не условием на каждой поверхности.
+ *
+ * Ошибиться здесь можно в обе стороны, и цены разные. Не повторить 429 — это
+ * оборванный `makeUgc` на ране, за который уже заплачено. Повторить 402 — это
+ * агент, крутящий отказ по деньгам в цикле: баланс от повторов не растёт, а
+ * лимит частоты они съедают, и человек получает вместо «пополни счёт» молчание
+ * до самого дедлайна.
+ */
+export function isRetryableFailure(failure) {
+    return failure.kind === "rate_limited" || failure.kind === "server_error";
+}
+/**
+ * Пауза перед повтором, мс. `fallbackMs` — собственный шаг вызывателя (для
+ * поллинга это его интервал): он же и пол, потому что сервер, не назвавший
+ * `Retry-After`, не разрешил долбить чаще обычного.
+ *
+ * Вызывать имеет смысл только после `isRetryableFailure`; на терминальном
+ * отказе результат бессмыслен, и функция не притворяется, что это не так.
+ */
+export function retryDelayMs(failure, fallbackMs) {
+    const fromServer = failure.kind === "rate_limited" || failure.kind === "server_error"
+        ? failure.retryAfterSeconds
+        : undefined;
+    return Math.max(fallbackMs, (fromServer ?? 0) * 1000);
+}
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+const MONTH = MONTHS.join("|");
+const DAY_SHORT = "Mon|Tue|Wed|Thu|Fri|Sat|Sun";
+const DAY_LONG = "Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday";
+/** IMF-fixdate:  `Sun, 06 Nov 1994 08:49:37 GMT` — форма, которую слать ОБЯЗАНЫ. */
+const IMF_FIXDATE = new RegExp(`^(?:${DAY_SHORT}), (\\d{2}) (${MONTH}) (\\d{4}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
+/** RFC 850:  `Sunday, 06-Nov-94 08:49:37 GMT` — устаревшая, но принимать обязаны. */
+const RFC850_DATE = new RegExp(`^(?:${DAY_LONG}), (\\d{2})-(${MONTH})-(\\d{2}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
+/** asctime:  `Sun Nov  6 08:49:37 1994` — тоже устаревшая и тоже обязательная. */
+const ASCTIME_DATE = new RegExp(`^(?:${DAY_SHORT}) (${MONTH}) ([ \\d]\\d) (\\d{2}):(\\d{2}):(\\d{2}) (\\d{4})$`);
+/**
+ * HTTP-date → миллисекунды эпохи. Три формы RFC 9110 §5.6.7, СОБСТВЕННОЙ
+ * сборкой через `Date.UTC`, а не через `Date.parse`.
+ *
+ * ПОЧЕМУ НЕ `Date.parse`. Внешнее ревью показало на его квирках два разных
+ * дефекта, и оба — молчаливые.
+ *
+ *  1. Двузначный год формы RFC 850 V8 разворачивает по своему правилу:
+ *     `29-Jul-75` он читает как 1975 год, тогда как RFC велит считать годом в
+ *     прошлое только то, что оказалось БОЛЕЕ ЧЕМ НА 50 ЛЕТ в будущем, — то есть
+ *     это 2075-й (проверено запуском). Назначенная пауза превращалась в дату из
+ *     прошлого, то есть в ноль, и клиент шёл опрашивать снова своим шагом.
+ *  2. Форма asctime не несёт пояса, и `Date.parse` читает её как МЕСТНОЕ время,
+ *     тогда как HTTP считает её UTC. В поясе UTC+3 пауза «до 15:00:30» давала
+ *     30 секунд вместо трёх часов (проверено запуском с `TZ=Europe/Minsk`):
+ *     повтор уходил почти на три часа раньше разрешённого.
+ *
+ * Сборка из разобранных полей обеих ошибок не имеет: пояс задан явно, век
+ * вычисляется по правилу RFC. Заодно исчезает зависимость поведения от часового
+ * пояса машины, на которой запущен клиент.
+ *
+ * БЛИЗКИЕ, НО НЕ СОВПАДАЮЩИЕ НАПИСАНИЯ ОТВЕРГАЮТСЯ НАМЕРЕННО — `UTC` вместо
+ * `GMT`, нижний регистр, однозначный день в IMF-fixdate. RFC задаёт эти
+ * написания буквально, регистр в том числе, поэтому нестрогое совпадение — уже
+ * не HTTP-date, а догадка о нём. Цена отказа мала и известна: заголовок читается
+ * как «сервер паузы не назвал», и клиент ждёт свой обычный шаг.
+ *
+ * День недели в строке не сверяется с датой: RFC разрешает получателю его
+ * игнорировать, а расхождение не делает дату непонятной.
+ */
+function httpDateToEpochMs(raw, now) {
+    /**
+     * Сборка момента из полей — с ПРОВЕРКОЙ, что поля описывают существующую дату.
+     *
+     * `Date.UTC` невалидные поля не отвергает, а НОРМАЛИЗУЕТ: 32 июля становится
+     * первым августа, 25:00 — часом следующих суток, 29 февраля невисокосного
+     * года — первым марта (внешнее ревью, круг 3). Для нас это не мелочь: мусорный
+     * заголовок превращался бы не в «сервер паузы не назвал», а в паузу на трое
+     * суток, клиент проспал бы весь свой дедлайн и вернул таймаут по рану, который
+     * к тому моменту уже завершился.
+     *
+     * Секунда 60 разрешена НАМЕРЕННО: это координационная секунда, RFC 9110 её
+     * допускает, и отвергать законное значение было бы такой же ошибкой, как
+     * принимать незаконное. `Date.UTC` переносит её на следующую минуту — разница
+     * в одну секунду против паузы, которую всё равно назначил не мы.
+     */
+    const utc = (year, month, day, h, m, s) => {
+        const monthIndex = MONTHS.indexOf(month);
+        const dayNumber = Number.parseInt(day, 10);
+        const hours = Number.parseInt(h, 10);
+        const minutes = Number.parseInt(m, 10);
+        const seconds = Number.parseInt(s, 10);
+        if (hours > 23 || minutes > 59 || seconds > 60)
+            return undefined;
+        if (dayNumber < 1)
+            return undefined;
+        // ГОД МЛАДШЕ 1900 ОТВЕРГАЕТСЯ, И ЭТО НЕ ПРИДИРКА (внешнее ревью, круг 4).
+        // У `Date.UTC` есть наследственный квирк: годы 0–99 он трактует как 1900+год,
+        // поэтому `Sun, 01 Jan 0099 …` превращался в 1999-й (проверено запуском). Дата
+        // уезжала в прошлое, пауза считалась нулевой, и агент получал «подожди 0
+        // секунд» — то есть повторял отбитый запрос немедленно и мог продлить себе
+        // блокировку. Нижняя граница взята из семантики даты RFC 5322, на которую
+        // ссылается RFC 9110: раньше 1900 года HTTP-дат не бывает.
+        if (year < 1900)
+            return undefined;
+        // КАЛЕНДАРЬ СВЕРЯЕТСЯ ОТДЕЛЬНО ОТ ВРЕМЕНИ СУТОК, и это не стилистика.
+        // Сверка на полной дате отвергала бы координационную секунду: `23:59:60`
+        // переносится на следующие сутки, число месяца уезжает, и законное значение
+        // выглядело бы как невалидное. Поэтому число месяца проверяется на полуночи
+        // тех же суток, а время суток — диапазонами выше.
+        const midnight = new Date(Date.UTC(year, monthIndex, dayNumber));
+        if (midnight.getUTCDate() !== dayNumber || midnight.getUTCMonth() !== monthIndex) {
+            return undefined;
+        }
+        return Date.UTC(year, monthIndex, dayNumber, hours, minutes, seconds);
+    };
+    const imf = IMF_FIXDATE.exec(raw);
+    if (imf !== null) {
+        const [, day, month, year, h, m, s] = imf;
+        return utc(Number.parseInt(year, 10), month, day, h, m, s);
+    }
+    const rfc850 = RFC850_DATE.exec(raw);
+    if (rfc850 !== null) {
+        const [, day, month, shortYear, h, m, s] = rfc850;
+        // ПРАВИЛО ВЕКА ИЗ RFC 9110 §5.6.7: берём тот же век, что у текущего года, и
+        // отступаем на сто лет назад, только если получилось больше чем на 50 лет
+        // вперёд. Именно этого правила нет у `Date.parse`.
+        const nowYear = now.getUTCFullYear();
+        let year = Math.floor(nowYear / 100) * 100 + Number.parseInt(shortYear, 10);
+        if (year - nowYear > 50)
+            year -= 100;
+        return utc(year, month, day, h, m, s);
+    }
+    const asctime = ASCTIME_DATE.exec(raw);
+    if (asctime !== null) {
+        const [, month, day, h, m, s, year] = asctime;
+        return utc(Number.parseInt(year, 10), month, day.trim(), h, m, s);
+    }
+    return undefined;
+}
+/**
+ * `Retry-After` в секундах, обе формы RFC 9110.
+ *
+ * ДВЕ ФОРМЫ — НЕ ПЕДАНТИЗМ. Дельту в секундах отдаёт наша мидлвара, а HTTP-дату
+ * — чужие прокси (её разрешает та же RFC, и nginx с облачными edge её ставят).
+ * Клиент, знающий только цифры, на дате получил бы `NaN` и либо не ждал вовсе,
+ * либо ждал бесконечность — обе ветки хуже, чем «подожди свой обычный шаг».
+ *
+ * `now` — параметр, а не `Date.now()` внутри: разбор даты обязан быть проверяем
+ * прогоном, а не зависеть от того, когда его запустили.
+ */
+export function parseRetryAfterSeconds(raw, now) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number.parseInt(trimmed, 10);
+        return Number.isSafeInteger(seconds) ? seconds : undefined;
+    }
+    // ДАТА РАЗБИРАЕТСЯ СОБСТВЕННОЙ ГРАММАТИКОЙ, А НЕ `Date.parse`.
+    //
+    // Легаси-разбор дат в V8 принимает почти всё: `Date.parse("-5")` даёт 30
+    // апреля 2001 года, `Date.parse("7.5")` — 4 июля того же, а
+    // `Date.parse("Mon 1/2/2099")` — 2099-й (всё проверено запуском). Мусор
+    // превращался бы в паузу длиной в десятилетия; клиент обрезал бы её своим
+    // дедлайном, проспал бы его весь и вернул таймаут по рану, который к тому
+    // моменту уже успешно завершился. Разбор и его доводы — в `httpDateToEpochMs`.
+    const at = httpDateToEpochMs(trimmed, now);
+    if (at === undefined || Number.isNaN(at))
+        return undefined;
+    // Прошедшая дата значит «уже можно»: ноль, а не отрицательное число, иначе
+    // `Math.max` ниже по течению получил бы значение, тянущее паузу вниз.
+    return Math.max(0, Math.ceil((at - now.getTime()) / 1000));
+}
+/** Сколько символов чужого тела дотащить до сообщения. */
+const BODY_EXCERPT_LIMIT = 200;
+/**
+ * Однострочная выжимка нечитаемого тела.
+ *
+ * ЗАЧЕМ ОНА ВООБЩЕ. Сообщение «HTTP 429» без единой подробности отправляет
+ * человека читать логи прокси, которых у него нет. Строка «error code: 1015» из
+ * тела Cloudflare отвечает на вопрос сразу. Обрезка обязательна: HTML-страница
+ * ошибки бывает в десятки килобайт, и целиком она не сообщение, а свалка.
+ */
+function excerpt(bodyText) {
+    if (bodyText === undefined)
+        return undefined;
+    const flat = bodyText.replace(/\s+/g, " ").trim();
+    if (flat.length === 0)
+        return undefined;
+    return flat.length > BODY_EXCERPT_LIMIT ? `${flat.slice(0, BODY_EXCERPT_LIMIT)}…` : flat;
+}
+/** `JSON.parse`, который не бросает: тело от прокси нам никто не обещал. */
+function safeJson(bodyText) {
+    if (bodyText === undefined)
+        return undefined;
+    try {
+        return JSON.parse(bodyText);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Коды, за которыми закреплено ПОВЕДЕНИЕ клиента, а не только текст.
+ *
+ * Список выведен из самих схем, а не переписан руками: разъедься он с ними —
+ * и защита ниже перестала бы закрывать то, ради чего написана. Значения берутся
+ * из литералов схем, поэтому переименование кода в `errors.ts` или
+ * `rate-limit.ts` доедет сюда само.
+ */
+const BEHAVIOURAL_CODES = new Set([
+    rateLimitedError.shape.error.shape.code.value,
+    insufficientCreditsError.shape.error.shape.code.value,
+    debtOutstandingError.shape.error.shape.code.value,
+]);
+/**
+ * Статус + тело + заголовок → то, с чем можно ПОСТУПИТЬ.
+ *
+ * ТЕЛО УТОЧНЯЕТ СТАТУС, НО НЕ ОТМЕНЯЕТ ЕГО. Специализированная схема
+ * применяется, только если статус ей СООТВЕТСТВУЕТ: `rate_limited` — на 429,
+ * оба денежных кода — на 402.
+ *
+ * Первая редакция давала телу перевешивать статус, рассуждая так: код объявлен
+ * в теле, а статус по дороге переписывает кто угодно, значит 502 поверх нашего
+ * 402 — это всё ещё «не хватило кредитов». Внешнее ревью показало обратную
+ * сторону того же рассуждения, и она хуже. Кэширующий прокси, отдавший старое
+ * тело `debt_outstanding` с новым статусом 429, делал отказ ТЕРМИНАЛЬНЫМ: агент
+ * бросал бы уже оплаченный ран и требовал погасить долг, которого нет. Зеркально
+ * 402 с телом `rate_limited` становился РЕТРАЙНЫМ, прямо вопреки правилу «любой
+ * 402 останавливает». Получались и внутренне противоречивые отказы вида
+ * `status === 402 && retryable === true`.
+ *
+ * Сочетание статуса и кода из РАЗНЫХ ответов — это не сообщение, а его порча, и
+ * доверять в нём надо тому, что уцелело наверняка. Уцелел статус: он часть
+ * стартовой строки, его не кэшируют отдельно от тела и им управляет тот же
+ * узел, который решил ответить. Поэтому при расхождении класс отказа берётся из
+ * статуса, а текст — из тела: сказать «сервер перегружен, повтори» и оказаться
+ * неправым дешевле, чем бросить оплаченный ран.
+ *
+ * ЧИСЛА `retry_after_seconds` ИЗ ТЕЛА СИЛЬНЕЕ ЗАГОЛОВКА — здесь тело выигрывает
+ * законно, потому что спорят два поля ОДНОГО ответа, а не ответ с самим собой.
+ * Наша мидлвара ставит в оба места одно число, и заголовок переписывают чаще.
+ */
+export function parseApiFailure(input) {
+    const { status, bodyText } = input;
+    const now = input.now ?? new Date();
+    const headerSeconds = parseRetryAfterSeconds(input.retryAfterHeader, now);
+    const body = safeJson(bodyText);
+    const limited = status === 429 ? rateLimitedError.safeParse(body) : undefined;
+    if (limited?.success === true) {
+        const { error } = limited.data;
+        return {
+            kind: "rate_limited",
+            status,
+            message: error.message,
+            retryAfterSeconds: error.retry_after_seconds,
+            limit: error.limit,
+            windowSeconds: error.window_seconds,
+        };
+    }
+    const insufficient = status === 402 ? insufficientCreditsError.safeParse(body) : undefined;
+    if (insufficient?.success === true) {
+        const { error } = insufficient.data;
+        return {
+            kind: "insufficient_credits",
+            status,
+            message: error.message,
+            balanceCredits: error.balance_credits,
+            requiredCredits: error.required_credits,
+        };
+    }
+    const debt = status === 402 ? debtOutstandingError.safeParse(body) : undefined;
+    if (debt?.success === true) {
+        const { error } = debt.data;
+        return {
+            kind: "debt_outstanding",
+            status,
+            message: error.message,
+            debtCredits: error.debt_credits,
+        };
+    }
+    // Дальше тело либо не наше, либо не разобралось вовсе. Общий конверт
+    // (`apiError`) даёт хотя бы текст и код; всё, что не разобралось и им, —
+    // чужое, и сообщение придётся собрать из статуса.
+    const generic = apiError.safeParse(body);
+    const message = generic.success
+        ? generic.data.error.message
+        : messageFromStatus(status, bodyText);
+    // КОД ИЗ ТЕЛА ПРОПУСКАЕТСЯ, ТОЛЬКО ЕСЛИ ОН НЕ ГОВОРЯЩИЙ (внешнее ревью, круг 2).
+    //
+    // Сюда мы попадаем в том числе после несовпадения статуса с телом: 403 с
+    // нашим телом `rate_limited` специализированную схему не прошёл — и правильно
+    // не прошёл. Но общий конверт всё равно вытаскивал из него `code:
+    // "rate_limited"`, и отчёт агенту выходил самопротиворечивым: код, который
+    // SKILL.md связывает с «подожди и повтори», приезжал вместе с `retryable:
+    // false`. Клиент, ветвящийся по коду, повторял бы терминальный отказ;
+    // ветвящийся по флагу — останавливался. Самоописывающий контракт, дающий два
+    // разных ответа на один вопрос, хуже отсутствия контракта.
+    //
+    // Поэтому коды, за которыми закреплено ПОВЕДЕНИЕ, признаются только на своём
+    // статусе. Не признанный здесь код не теряется бесследно: текст тела уходит в
+    // `message` целиком, и человек его увидит.
+    const rawCode = generic.success ? generic.data.error.code : undefined;
+    const code = rawCode !== undefined && BEHAVIOURAL_CODES.has(rawCode) ? undefined : rawCode;
+    if (status === 429) {
+        return {
+            kind: "rate_limited",
+            status,
+            message,
+            retryAfterSeconds: headerSeconds,
+            limit: undefined,
+            windowSeconds: undefined,
+        };
+    }
+    if (status >= 500) {
+        return { kind: "server_error", status, message, retryAfterSeconds: headerSeconds };
+    }
+    return { kind: "client_error", status, message, code };
+}
+/**
+ * Сообщение, когда тело нам ничего не сказало.
+ *
+ * Именно ЭТА ветка чинит падение, названное в US-622: `res.json()` на HTML-теле
+ * от прокси бросал `SyntaxError`, и вызыватель видел «Unexpected token <»
+ * вместо «слишком часто, подожди». Ошибка парсера не только бесполезна — она
+ * УВОДИТ: выглядит как баг клиента там, где сервер честно сказал 429.
+ */
+function messageFromStatus(status, bodyText) {
+    // ИСТОЧНИК ОТКАЗА НЕ ПРИПИСЫВАЕТСЯ ПО ПУСТОМУ МЕСТУ (внешнее ревью, круг 13).
+    // Прежняя редакция объявляла всякий неразобранный 429 отказом прокси — и
+    // ошибалась ровно там, где тело не удалось ПРОЧИТАТЬ: заголовки могли прийти
+    // от нашего же API, а человека отправляли искать несуществующий шлюз вместо
+    // исчерпанного лимита аккаунта.
+    if (bodyText === undefined) {
+        return `HTTP ${status}: the response body could not be read, so the reason is only known by status`;
+    }
+    // ИСТОЧНИК НЕ НАЗЫВАЕТСЯ И ЗДЕСЬ (внешнее ревью, круг 15). Круг 14 вычистил
+    // атрибуцию из `next_action`, но в самом сообщении осталась догадка «обычно
+    // это шлюз или CDN» — тот же класс, просто соседней строкой. Отдать неродное
+    // тело может и наш сервер за балансировщиком, и промежуточный узел; знать
+    // это здесь неоткуда. Всё, что известно достоверно, — код ответа и то, что
+    // тело не наше; выжимка тела ниже даёт человеку самому увидеть, кто ответил.
+    const tail = excerpt(bodyText);
+    const head = status === 429
+        ? "HTTP 429: too many requests, and the body did not carry a Clipwright error object"
+        : `HTTP ${status}: the response body is not a Clipwright error object`;
+    return tail === undefined ? head : `${head}. Body: ${tail}`;
+}
+export function agentFailureReport(failure) {
+    const base = { message: failure.message };
+    switch (failure.kind) {
+        case "rate_limited": {
+            const seconds = failure.retryAfterSeconds;
+            return {
+                ...base,
+                status: "RETRY_LATER",
+                code: "rate_limited",
+                retryable: true,
+                // ПРО ДЕНЬГИ ЗДЕСЬ НЕ УТВЕРЖДАЕТСЯ НИЧЕГО, и это правка после внешнего
+                // ревью (круг 6). Прежняя редакция дописывала «nothing was charged» ко
+                // всякому 429 — а 429 приходит и на ОПРОС СТАТУСА уже запущенного рана,
+                // за который деньги зарезервированы или уже списаны. Агент, повторивший
+                // это человеку, сказал бы неправду о его счёте.
+                //
+                // Точное утверждение про деньги умеет делать только сервер: у него есть
+                // ведро, и `rateLimitedBody` в `rate-limit.ts` формулирует его отдельно
+                // для платных и бесплатных путей. Оно приезжает в `message` целиком.
+                // Дублировать его здесь более слабой и менее верной копией значило бы
+                // завести второй источник правды о деньгах — худший из возможных.
+                next_action: seconds === undefined
+                    ? "Too many requests. Wait a few seconds, then repeat the SAME call — do not start a new one."
+                    : `Too many requests. Wait ${seconds} seconds, then repeat the SAME call — do not start a new one.`,
+                ...(seconds !== undefined && { retry_after_seconds: seconds }),
+                ...(failure.limit !== undefined && { limit: failure.limit }),
+                ...(failure.windowSeconds !== undefined && { window_seconds: failure.windowSeconds }),
+            };
+        }
+        case "insufficient_credits":
+            return {
+                ...base,
+                status: "FAILED",
+                code: "insufficient_credits",
+                retryable: false,
+                // Числа повторены в императиве намеренно: агент показывает человеку
+                // одну строку, и «не хватило кредитов» без цифр не даёт решить, сколько
+                // покупать.
+                next_action: `STOP. Do NOT retry: this account has ${failure.balanceCredits} credits and the call ` +
+                    `needs ${failure.requiredCredits}. Retrying cannot change that. Tell the user to top up ` +
+                    "the balance, then call again. Nothing was charged and no run was created.",
+                balance_credits: failure.balanceCredits,
+                required_credits: failure.requiredCredits,
+            };
+        case "debt_outstanding":
+            return {
+                ...base,
+                status: "FAILED",
+                code: "debt_outstanding",
+                retryable: false,
+                // Отдельный текст, а не оттенок предыдущего: совет «пополни» здесь
+                // неверен — пополнение долг не снимает (см. `errors.ts`).
+                next_action: `STOP. Do NOT retry: an outstanding debt of ${failure.debtCredits} credits blocks new ` +
+                    "paid runs. Tell the user to settle the debt — topping up the balance alone does not " +
+                    "clear it. Nothing was charged and no run was created.",
+                debt_credits: failure.debtCredits,
+            };
+        case "server_error": {
+            const seconds = failure.retryAfterSeconds;
+            return {
+                ...base,
+                status: "RETRY_LATER",
+                code: `http_${failure.status}`,
+                retryable: true,
+                // ИСТОЧНИК ОТКАЗА НЕ НАЗЫВАЕТСЯ (внешнее ревью, круг 14). Прежний текст
+                // утверждал «Clipwright API упал на своей стороне» — а 5xx одинаково
+                // отдают и наш сервер, и корпоративный шлюз, и CDN. Ошибочная
+                // атрибуция отправляет человека разбирать инцидент не в том месте, и
+                // она же противоречила соседнему сообщению, которое честно говорит, что
+                // причина известна только по статусу.
+                next_action: "The call failed with a server-side error. Repeat the SAME call in a few seconds. If it " +
+                    "keeps failing, stop and tell the user; do not start a new run with a different " +
+                    "idempotency key.",
+                ...(seconds !== undefined && { retry_after_seconds: seconds }),
+            };
+        }
+        case "client_error":
+            return {
+                ...base,
+                status: "FAILED",
+                code: failure.code ?? `http_${failure.status}`,
+                retryable: false,
+                next_action: "STOP. Do NOT retry: the request itself was rejected, so repeating it unchanged gives " +
+                    "the same answer. Read the message, fix the call, or tell the user what is wrong.",
+            };
+    }
+}
+//# sourceMappingURL=api-failure.js.map

package/dist/api-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-failure.js","sourceRoot":"","sources":["../src/api-failure.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+/**
+ * ТЕЛА ОТКАЗОВ — СХЕМАМИ, А НЕ `c.json({...})` В ОБРАБОТЧИКЕ.
+ *
+ * До US-602 каждая ошибка API собиралась объектным литералом прямо в
+ * `apps/api/src/app.ts`, и это сходило с рук ровно потому, что все они несли
+ * одну и ту же пару `code`/`message`: разъехаться было нечему. С деньгами это
+ * перестаёт быть правдой — отказ 402 несёт ЧИСЛА, и агент по ним принимает
+ * решение (пополнить и повторить либо остановиться). Литерал в обработчике,
+ * потерявший `balance_credits`, оставил бы агента с сообщением «не хватило
+ * кредитов» без единой цифры, и обнаружилось бы это у клиента.
+ *
+ * Поэтому форма живёт здесь (правило проекта №2), а обработчик обязан пройти
+ * через `.parse()`: тело, собранное мимо схемы, не соберётся вовсе.
+ *
+ * ЧИСЛА ЛЕЖАТ ВНУТРИ `error`, А НЕ РЯДОМ С НИМ. Прецедент задан отказом по
+ * отклонённым полям (`error.fields`) и держится одним доводом: у ответа
+ * ошибки один конверт, и всё, что объясняет отказ, лежит в нём. Разложи числа
+ * по верхнему уровню — и клиенту придётся знать, для каких кодов смотреть в
+ * конверт, а для каких мимо него.
+ */
+/**
+ * Общий конверт ошибки. Толерантен к дополнительным полям внутри `error`:
+ * типизированные отказы ниже — его расширения, и общий разбор не должен
+ * ломаться от того, что конкретный код принёс с собой числа.
+ */
+export declare const apiError: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ApiError = z.infer<typeof apiError>;
+/** Кредитов на балансе меньше веса рана. Значит «пополни». */
+export declare const insufficientCreditsError: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodLiteral<"insufficient_credits">;
+        message: z.ZodString;
+        balance_credits: z.ZodNumber;
+        required_credits: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type InsufficientCreditsError = z.infer<typeof insufficientCreditsError>;
+/**
+ * На аккаунте висит непогашенный долг. Значит «погаси», а не «пополни».
+ *
+ * Отдельный код, а не оттенок предыдущего: у аккаунта с долгом деньги на
+ * балансе могут БЫТЬ, и ответ «недостаточно кредитов» сказал бы клиенту
+ * заведомую неправду, а его агента отправил бы покупать кредиты, которые не
+ * снимут блокировку.
+ */
+export declare const debtOutstandingError: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodLiteral<"debt_outstanding">;
+        message: z.ZodString;
+        debt_credits: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DebtOutstandingError = z.infer<typeof debtOutstandingError>;
+/**
+ * Сборка тела «не хватило кредитов».
+ *
+ * Формулировка живёт ЗДЕСЬ, а не в обработчике, по той же причине, что и
+ * форма: два места, отвечающие 402 (сегодня — создание рана, завтра — любой
+ * другой платный вызов), обязаны объяснять отказ одинаково.
+ */
+export declare function insufficientCreditsBody(args: {
+    balanceCredits: number;
+    requiredCredits: number;
+}): InsufficientCreditsError;
+/** Сборка тела «висит долг». См. довод о формулировке выше. */
+export declare function debtOutstandingBody(args: {
+    debtCredits: number;
+}): DebtOutstandingError;

package/dist/errors.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/**
+ * ТЕЛА ОТКАЗОВ — СХЕМАМИ, А НЕ `c.json({...})` В ОБРАБОТЧИКЕ.
+ *
+ * До US-602 каждая ошибка API собиралась объектным литералом прямо в
+ * `apps/api/src/app.ts`, и это сходило с рук ровно потому, что все они несли
+ * одну и ту же пару `code`/`message`: разъехаться было нечему. С деньгами это
+ * перестаёт быть правдой — отказ 402 несёт ЧИСЛА, и агент по ним принимает
+ * решение (пополнить и повторить либо остановиться). Литерал в обработчике,
+ * потерявший `balance_credits`, оставил бы агента с сообщением «не хватило
+ * кредитов» без единой цифры, и обнаружилось бы это у клиента.
+ *
+ * Поэтому форма живёт здесь (правило проекта №2), а обработчик обязан пройти
+ * через `.parse()`: тело, собранное мимо схемы, не соберётся вовсе.
+ *
+ * ЧИСЛА ЛЕЖАТ ВНУТРИ `error`, А НЕ РЯДОМ С НИМ. Прецедент задан отказом по
+ * отклонённым полям (`error.fields`) и держится одним доводом: у ответа
+ * ошибки один конверт, и всё, что объясняет отказ, лежит в нём. Разложи числа
+ * по верхнему уровню — и клиенту придётся знать, для каких кодов смотреть в
+ * конверт, а для каких мимо него.
+ */
+/**
+ * Общий конверт ошибки. Толерантен к дополнительным полям внутри `error`:
+ * типизированные отказы ниже — его расширения, и общий разбор не должен
+ * ломаться от того, что конкретный код принёс с собой числа.
+ */
+export const apiError = z.object({
+    error: z.object({
+        code: z.string().min(1),
+        message: z.string().min(1),
+    }),
+});
+/** Кредитов на балансе меньше веса рана. Значит «пополни». */
+export const insufficientCreditsError = z.object({
+    error: z.object({
+        code: z.literal("insufficient_credits"),
+        message: z.string().min(1),
+        /** Сколько есть СЕЙЧАС. Ноль — законное значение. */
+        balance_credits: z.number().int().nonnegative(),
+        /** Сколько нужно на этот ран — та же оценка, что вернул `quote`. */
+        required_credits: z.number().int().positive(),
+    }),
+});
+/**
+ * На аккаунте висит непогашенный долг. Значит «погаси», а не «пополни».
+ *
+ * Отдельный код, а не оттенок предыдущего: у аккаунта с долгом деньги на
+ * балансе могут БЫТЬ, и ответ «недостаточно кредитов» сказал бы клиенту
+ * заведомую неправду, а его агента отправил бы покупать кредиты, которые не
+ * снимут блокировку.
+ */
+export const debtOutstandingError = z.object({
+    error: z.object({
+        code: z.literal("debt_outstanding"),
+        message: z.string().min(1),
+        debt_credits: z.number().int().positive(),
+    }),
+});
+/**
+ * Сборка тела «не хватило кредитов».
+ *
+ * Формулировка живёт ЗДЕСЬ, а не в обработчике, по той же причине, что и
+ * форма: два места, отвечающие 402 (сегодня — создание рана, завтра — любой
+ * другой платный вызов), обязаны объяснять отказ одинаково.
+ */
+export function insufficientCreditsBody(args) {
+    return insufficientCreditsError.parse({
+        error: {
+            code: "insufficient_credits",
+            message: `This run needs ${args.requiredCredits} credits, the account has ${args.balanceCredits}. ` +
+                "Top up the balance and retry; nothing was charged and no run was created.",
+            balance_credits: args.balanceCredits,
+            required_credits: args.requiredCredits,
+        },
+    });
+}
+/** Сборка тела «висит долг». См. довод о формулировке выше. */
+export function debtOutstandingBody(args) {
+    return debtOutstandingError.parse({
+        error: {
+            code: "debt_outstanding",
+            message: `An outstanding debt of ${args.debtCredits} credits blocks new paid runs. ` +
+                "Settle the debt and retry; topping up alone does not clear it.",
+            debt_credits: args.debtCredits,
+        },
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KAC3B,CAAC;CACH,CAAC,CAAC;AAGH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC;QACvC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1B,qDAAqD;QACrD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC/C,oEAAoE;QACpE,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;KAC9C,CAAC;CACH,CAAC,CAAC;AAGH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC;QACnC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;KAC1C,CAAC;CACH,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAGvC;IACC,OAAO,wBAAwB,CAAC,KAAK,CAAC;QACpC,KAAK,EAAE;YACL,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EACL,kBAAkB,IAAI,CAAC,eAAe,6BAA6B,IAAI,CAAC,cAAc,IAAI;gBAC1F,2EAA2E;YAC7E,eAAe,EAAE,IAAI,CAAC,cAAc;YACpC,gBAAgB,EAAE,IAAI,CAAC,eAAe;SACvC;KACF,CAAC,CAAC;AACL,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,mBAAmB,CAAC,IAEnC;IACC,OAAO,oBAAoB,CAAC,KAAK,CAAC;QAChC,KAAK,EAAE;YACL,IAAI,EAAE,kBAAkB;YACxB,OAAO,EACL,0BAA0B,IAAI,CAAC,WAAW,iCAAiC;gBAC3E,gEAAgE;YAClE,YAAY,EAAE,IAAI,CAAC,WAAW;SAC/B;KACF,CAAC,CAAC;AACL,CAAC"}