@clipwright/core 0.1.0 → 0.3.0

package/dist/errors.d.ts

@@ -0,0 +1,148 @@
+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>;
+/**
+ * На аккаунте висит непогашенный долг.
+ *
+ * ОТДЕЛЬНЫЙ КОД, А НЕ ОТТЕНОК ПРЕДЫДУЩЕГО, и довод у этого ровно один: у счёта
+ * с долгом деньги на балансе БЫВАЮТ. Такое состояние оставляет `topUpHold`
+ * (ветка `deferred_to_debt`) — он наращивает долг, не трогая баланс; два других
+ * производителя долга обнуляют баланс, заводя его. Ответ «недостаточно
+ * кредитов» сказал бы такому счёту заведомую неправду.
+ *
+ * ⚠️ ВТОРАЯ ПОЛОВИНА ПРЕЖНЕГО ДОВОДА — «агента отправило бы покупать кредиты,
+ * которые не снимут блокировку» — СНЯТА КАК ЛОЖНАЯ (clipwright#27): кредиты
+ * снимают. Вывод пережил свою причину, и это стоит сказать прямо: оставь я
+ * старую формулировку, следующий читатель либо слил бы два кода, увидев, что
+ * лечение одно, либо заново вывел бы из неё неверный совет клиенту.
+ */
+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>;
+/**
+ * Аккаунт не допущен в бету (US-620). Ни «пополни», ни «погаси»: доступ выдаёт
+ * владелец, и деньги на это не влияют.
+ *
+ * Отдельный код по тому же доводу, что отделил долг от нехватки: у
+ * недопущенного аккаунта деньги на балансе БЫВАЮТ, и оба денежных ответа
+ * отправили бы его агента совершать действия, которые блокировку не снимут.
+ * Отказ терминальный: повтор того же запроса даст то же самое, пока владелец не
+ * допустит аккаунт командой `admit`.
+ *
+ * ЧИСЕЛ В ТЕЛЕ НЕТ, И ЭТО НЕ ЭКОНОМИЯ. Порядковый номер мы не считаем: доступ
+ * даётся решением человека, а не по счётчику, и назвать номер значило бы
+ * обещать срок, которого никто не давал.
+ *
+ * ПО ТОЙ ЖЕ ПРИЧИНЕ ТЕЛО НЕ НАЗЫВАЕТ НИ СРОКА, НИ НОМЕРА, НИ БЛИЗОСТИ РАЗВЯЗКИ.
+ * Из отказа известно ровно одно: доступа нет. Так же отвечает аккаунт, у
+ * которого доступ СНЯЛИ, — и обещание скорого приёма было бы для него ложью в
+ * самый неподходящий момент. Правило принималось трижды и трижды чинилось по адресу
+ * находки: сперва в совете агенту (`api-failure.ts`), потом в `SKILL.md`, и
+ * только тогда — ЗДЕСЬ, в единственном месте, которое порождает эту строку для
+ * всех остальных. Проверка стоит на этой функции, а не на её производных.
+ *
+ * ПРАВИЛО РАСПРОСТРАНЯЕТСЯ НА ЛЮБУЮ ПОВЕРХНОСТЬ, объясняющую этот отказ, а не
+ * только на те, что существуют сегодня. Ближайшие будущие — страница ключей
+ * (US-608) и лендинг US-614; там соблазн назвать срок сильнее всего. Сторож
+ * (`scripts/docs-consistency.test.ts`) их уже обходит, но HTML он читает как
+ * текст и поймает только то, что стоит рядом с именем кода.
+ */
+export declare const accountNotAdmittedError: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodLiteral<"account_not_admitted">;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AccountNotAdmittedError = z.infer<typeof accountNotAdmittedError>;
+/**
+ * Сборка тела «не хватило кредитов».
+ *
+ * Формулировка живёт ЗДЕСЬ, а не в обработчике, по той же причине, что и
+ * форма: два места, отвечающие 402 (сегодня — создание рана, завтра — любой
+ * другой платный вызов), обязаны объяснять отказ одинаково.
+ */
+export declare function insufficientCreditsBody(args: {
+    balanceCredits: number;
+    requiredCredits: number;
+}): InsufficientCreditsError;
+/** Сборка тела «не допущен в бету». См. довод о формулировке выше. */
+export declare function accountNotAdmittedBody(): AccountNotAdmittedError;
+/** Сборка тела «висит долг». См. довод о формулировке выше. */
+export declare function debtOutstandingBody(args: {
+    debtCredits: number;
+}): DebtOutstandingError;
+/** Во входе есть поле, которое продукт отклоняет. `fields` называет их поимённо: */
+/** агенту чинить нечего, пока он не знает, какое именно убрать. */
+export declare const rejectedFieldError: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodLiteral<"rejected_field">;
+        message: z.ZodString;
+        fields: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RejectedFieldError = z.infer<typeof rejectedFieldError>;
+/** Сборка тела «поле отклонено». Причина берётся из реестра диспозиций. */
+export declare function rejectedFieldBody(hits: readonly {
+    field: string;
+    message: string;
+}[]): RejectedFieldError;
+/** КОДЫ С ГОЛЫМ КОНВЕРТОМ — ОДНИМ РЕЕСТРОМ: перечень §6 `docs/03-api.md` объявлен */
+/** исчерпывающим. Устройство сторожей — `docs/41-api-error-contract.md`. */
+declare const BARE_ERROR_CODES: readonly ["aspect_conflict", "idempotency_key_required", "idempotency_key_reused", "internal_error", "invalid_request", "not_found", "paid_render_disabled", "payload_too_large", "unauthorized", "upstream_error"];
+/** Код отказа, тело которого несёт только `code` и `message`. */
+export type BareApiErrorCode = (typeof BARE_ERROR_CODES)[number];
+/** ВСЕ коды, которые умеет вернуть API: голые плюс типизированные. Значения вторых */
+/** берутся из их схем, поэтому переименование доедет сюда само. */
+export declare const API_ERROR_CODES: readonly string[];
+/** Тело голого отказа. Единственный путь к нему: код вне реестра не компилируется, */
+/** а конверт мимо этой функции валит `scripts/api-error-envelope.test.ts`. */
+export declare function apiErrorBody(args: {
+    code: BareApiErrorCode;
+    message: string;
+}): ApiError;
+export {};

package/dist/errors.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+// Только ради кода 429 в реестре ниже: имя берётся из его схемы, а не пишется
+// здесь литералом (единственный дом формы 429 — `rate-limit.ts`).
+import { rateLimitedError } from "./rate-limit.js";
+/**
+ * ТЕЛА ОТКАЗОВ — СХЕМАМИ, А НЕ `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(),
+    }),
+});
+/**
+ * На аккаунте висит непогашенный долг.
+ *
+ * ОТДЕЛЬНЫЙ КОД, А НЕ ОТТЕНОК ПРЕДЫДУЩЕГО, и довод у этого ровно один: у счёта
+ * с долгом деньги на балансе БЫВАЮТ. Такое состояние оставляет `topUpHold`
+ * (ветка `deferred_to_debt`) — он наращивает долг, не трогая баланс; два других
+ * производителя долга обнуляют баланс, заводя его. Ответ «недостаточно
+ * кредитов» сказал бы такому счёту заведомую неправду.
+ *
+ * ⚠️ ВТОРАЯ ПОЛОВИНА ПРЕЖНЕГО ДОВОДА — «агента отправило бы покупать кредиты,
+ * которые не снимут блокировку» — СНЯТА КАК ЛОЖНАЯ (clipwright#27): кредиты
+ * снимают. Вывод пережил свою причину, и это стоит сказать прямо: оставь я
+ * старую формулировку, следующий читатель либо слил бы два кода, увидев, что
+ * лечение одно, либо заново вывел бы из неё неверный совет клиенту.
+ */
+export const debtOutstandingError = z.object({
+    error: z.object({
+        code: z.literal("debt_outstanding"),
+        message: z.string().min(1),
+        debt_credits: z.number().int().positive(),
+    }),
+});
+/**
+ * Аккаунт не допущен в бету (US-620). Ни «пополни», ни «погаси»: доступ выдаёт
+ * владелец, и деньги на это не влияют.
+ *
+ * Отдельный код по тому же доводу, что отделил долг от нехватки: у
+ * недопущенного аккаунта деньги на балансе БЫВАЮТ, и оба денежных ответа
+ * отправили бы его агента совершать действия, которые блокировку не снимут.
+ * Отказ терминальный: повтор того же запроса даст то же самое, пока владелец не
+ * допустит аккаунт командой `admit`.
+ *
+ * ЧИСЕЛ В ТЕЛЕ НЕТ, И ЭТО НЕ ЭКОНОМИЯ. Порядковый номер мы не считаем: доступ
+ * даётся решением человека, а не по счётчику, и назвать номер значило бы
+ * обещать срок, которого никто не давал.
+ *
+ * ПО ТОЙ ЖЕ ПРИЧИНЕ ТЕЛО НЕ НАЗЫВАЕТ НИ СРОКА, НИ НОМЕРА, НИ БЛИЗОСТИ РАЗВЯЗКИ.
+ * Из отказа известно ровно одно: доступа нет. Так же отвечает аккаунт, у
+ * которого доступ СНЯЛИ, — и обещание скорого приёма было бы для него ложью в
+ * самый неподходящий момент. Правило принималось трижды и трижды чинилось по адресу
+ * находки: сперва в совете агенту (`api-failure.ts`), потом в `SKILL.md`, и
+ * только тогда — ЗДЕСЬ, в единственном месте, которое порождает эту строку для
+ * всех остальных. Проверка стоит на этой функции, а не на её производных.
+ *
+ * ПРАВИЛО РАСПРОСТРАНЯЕТСЯ НА ЛЮБУЮ ПОВЕРХНОСТЬ, объясняющую этот отказ, а не
+ * только на те, что существуют сегодня. Ближайшие будущие — страница ключей
+ * (US-608) и лендинг US-614; там соблазн назвать срок сильнее всего. Сторож
+ * (`scripts/docs-consistency.test.ts`) их уже обходит, но HTML он читает как
+ * текст и поймает только то, что стоит рядом с именем кода.
+ */
+export const accountNotAdmittedError = z.object({
+    error: z.object({
+        code: z.literal("account_not_admitted"),
+        message: z.string().min(1),
+    }),
+});
+/**
+ * Сборка тела «не хватило кредитов».
+ *
+ * Формулировка живёт ЗДЕСЬ, а не в обработчике, по той же причине, что и
+ * форма: два места, отвечающие 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 accountNotAdmittedBody() {
+    return accountNotAdmittedError.parse({
+        error: {
+            code: "account_not_admitted",
+            message: "This account is not admitted to the beta. Nothing was charged and no run was created. " +
+                "Ask the operator about this account; retrying will not change the answer.",
+        },
+    });
+}
+/** Сборка тела «висит долг». См. довод о формулировке выше. */
+export function debtOutstandingBody(args) {
+    return debtOutstandingError.parse({
+        error: {
+            code: "debt_outstanding",
+            message: `An outstanding debt of ${args.debtCredits} credits blocks new paid runs. ` +
+                "Buy credits to clear it: incoming credits pay the debt down before any of them " +
+                "reach the balance. Clearing it lifts this block; a run still needs enough " +
+                "credits of its own, so a purchase equal to the debt adds nothing to the balance.",
+            debt_credits: args.debtCredits,
+        },
+    });
+}
+/** Во входе есть поле, которое продукт отклоняет. `fields` называет их поимённо: */
+/** агенту чинить нечего, пока он не знает, какое именно убрать. */
+export const rejectedFieldError = z.object({
+    error: z.object({
+        code: z.literal("rejected_field"),
+        message: z.string().min(1),
+        fields: z.array(z.string().min(1)).min(1),
+    }),
+});
+/** Сборка тела «поле отклонено». Причина берётся из реестра диспозиций. */
+export function rejectedFieldBody(hits) {
+    return rejectedFieldError.parse({
+        error: {
+            code: "rejected_field",
+            message: hits.map((hit) => hit.message).join("; "),
+            fields: hits.map((hit) => hit.field),
+        },
+    });
+}
+/** КОДЫ С ГОЛЫМ КОНВЕРТОМ — ОДНИМ РЕЕСТРОМ: перечень §6 `docs/03-api.md` объявлен */
+/** исчерпывающим. Устройство сторожей — `docs/41-api-error-contract.md`. */
+const BARE_ERROR_CODES = [
+    "aspect_conflict",
+    "idempotency_key_required",
+    "idempotency_key_reused",
+    "internal_error",
+    "invalid_request",
+    "not_found",
+    "paid_render_disabled",
+    "payload_too_large",
+    "unauthorized",
+    "upstream_error",
+];
+/** ВСЕ коды, которые умеет вернуть API: голые плюс типизированные. Значения вторых */
+/** берутся из их схем, поэтому переименование доедет сюда само. */
+export const API_ERROR_CODES = [
+    ...BARE_ERROR_CODES,
+    rejectedFieldError.shape.error.shape.code.value,
+    insufficientCreditsError.shape.error.shape.code.value,
+    debtOutstandingError.shape.error.shape.code.value,
+    accountNotAdmittedError.shape.error.shape.code.value,
+    rateLimitedError.shape.error.shape.code.value,
+];
+/** Тело голого отказа. Единственный путь к нему: код вне реестра не компилируется, */
+/** а конверт мимо этой функции валит `scripts/api-error-envelope.test.ts`. */
+export function apiErrorBody(args) {
+    return apiError.parse({ error: { code: args.code, message: args.message } });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -3,6 +3,13 @@ export * from "./contract-dispositions.js";
 export * from "./aspect.js";
 export * from "./voices.js";
 export * from "./runs.js";
+export * from "./errors.js";
+export * from "./rate-limit.js";
+export * from "./api-failure.js";
+export * from "./account.js";
 export * from "./pacing.js";
 export * from "./render-backend.js";
 export * from "./tts-backend.js";
+export * from "./vendor-response.js";
+export * from "./public-endpoints.js";
+export * from "./run-static-warnings.js";

package/dist/index.js

@@ -8,8 +8,29 @@ export * from "./contract-dispositions.js";
 export * from "./aspect.js";
 export * from "./voices.js";
 export * from "./runs.js";
+// Тела отказов: форма ответа об ошибке — тоже контракт, и с появлением чисел в
+// теле (402) она перестала быть выводимой из кода ответа.
+export * from "./errors.js";
+// Rate limit: форма 429 и имена заголовков — тот же контракт, что и тела
+// отказов выше, и по той же причине не выводится из кода ответа.
+export * from "./rate-limit.js";
+// Разбор отказа: тела уже описаны выше, здесь — что с ними ДЕЛАТЬ. Живёт в
+// core, потому что решение «ретраить или остановиться» обязано быть общим у
+// SDK, MCP и CLI (US-622).
+export * from "./api-failure.js";
+export * from "./account.js";
 export * from "./pacing.js";
 // Вендор-нейтральные контракты: всё вендорское живёт в адаптерах, не здесь.
 export * from "./render-backend.js";
 export * from "./tts-backend.js";
+// Обязанность реализаций обоих контрактов выше: пометить ошибку кодом ответа,
+// если ответ был. Без неё «вендор отказал» и «ответа не было» неразличимы
+// (US-606a).
+export * from "./vendor-response.js";
+// Публичные адреса и имена пакетов: их печатают SDK, документация и лендинг,
+// поэтому расхождение видит посетитель, а не тест (US-614).
+export * from "./public-endpoints.js";
+// Статические warnings рана выводятся из сохранённого входа — один ответ у API
+// и у кабинета на любом состоянии рана (clipwright#64).
+export * from "./run-static-warnings.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,gFAAgF;AAChF,6EAA6E;AAC7E,2BAA2B;AAC3B,cAAc,4BAA4B,CAAC;AAC3C,4EAA4E;AAC5E,gEAAgE;AAChE,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,4EAA4E;AAC5E,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,gFAAgF;AAChF,6EAA6E;AAC7E,2BAA2B;AAC3B,cAAc,4BAA4B,CAAC;AAC3C,4EAA4E;AAC5E,gEAAgE;AAChE,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,+EAA+E;AAC/E,0DAA0D;AAC1D,cAAc,aAAa,CAAC;AAC5B,yEAAyE;AACzE,iEAAiE;AACjE,cAAc,iBAAiB,CAAC;AAChC,2EAA2E;AAC3E,4EAA4E;AAC5E,2BAA2B;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,4EAA4E;AAC5E,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,8EAA8E;AAC9E,0EAA0E;AAC1E,aAAa;AACb,cAAc,sBAAsB,CAAC;AACrC,6EAA6E;AAC7E,4DAA4D;AAC5D,cAAc,uBAAuB,CAAC;AACtC,+EAA+E;AAC/E,wDAAwD;AACxD,cAAc,0BAA0B,CAAC"}

package/dist/public-endpoints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ПУБЛИЧНЫЕ АДРЕСА ПРОДУКТА — ОДНОЙ КОНСТАНТОЙ НА ВСЕХ (US-614).
+ *
+ * ЗАЧЕМ В `core`, А НЕ В SDK, ГДЕ ОН ЖИЛ. Литерал стоял приватной константой
+ * `DEFAULT_BASE_URL` в `packages/sdk/src/index.ts`, и до лендинга второго
+ * читателя у него не было. С лендингом их стало два: страница печатает команду
+ * `curl`, которую посетитель копирует и запускает, — то есть УТВЕРЖДАЕТ адрес.
+ * Напиши мы его там литералом, и правило проекта №2 нарушилось бы на самом
+ * заметном месте: клиент ходил бы на один адрес, а страница называла другой, и
+ * расхождение обнаружил бы посетитель, а не тест.
+ *
+ * ПОЧЕМУ ЗДЕСЬ АДРЕС ПЛОЩАДКИ, А НЕ `api.clipwright.io`. `spec.md` обещает
+ * второе, и US-613 его заведёт; на 2026-08-09 у `api.clipwright.io` нет ни `A`,
+ * ни `CNAME` (замер `dig`), то есть команда с этим адресом не работает ни у
+ * кого. Напечатать её на странице значило бы продать неработающий пример —
+ * ровно то, что запрещает главное правило брифа лендинга. Смена адреса в
+ * US-613 будет правкой ЭТОЙ строки, и обе поверхности переедут вместе.
+ */
+export declare const PUBLIC_API_BASE_URL = "https://api-production-7e69.up.railway.app";
+/**
+ * Пакеты npm, которыми продукт вызывается. Названия печатает и лендинг, и
+ * `--help`, и документация — значит это тоже контракт, а не текст страницы.
+ */
+export declare const CLI_PACKAGE = "@clipwright/cli";
+export declare const CLI_BIN = "clipwright";
+export declare const MCP_PACKAGE = "@clipwright/mcp-server";
+/** Адрес API ИЗ ОКРУЖЕНИЯ — только `https:`: по нему уходит `Authorization: Bearer */
+/** cw_…`. Программный `baseUrl` встраивателя не трогаем — его выбирает автор кода. */
+export declare function apiBaseUrlFromEnv(raw: string | undefined): string | undefined;

package/dist/public-endpoints.js

@@ -0,0 +1,49 @@
+/**
+ * ПУБЛИЧНЫЕ АДРЕСА ПРОДУКТА — ОДНОЙ КОНСТАНТОЙ НА ВСЕХ (US-614).
+ *
+ * ЗАЧЕМ В `core`, А НЕ В SDK, ГДЕ ОН ЖИЛ. Литерал стоял приватной константой
+ * `DEFAULT_BASE_URL` в `packages/sdk/src/index.ts`, и до лендинга второго
+ * читателя у него не было. С лендингом их стало два: страница печатает команду
+ * `curl`, которую посетитель копирует и запускает, — то есть УТВЕРЖДАЕТ адрес.
+ * Напиши мы его там литералом, и правило проекта №2 нарушилось бы на самом
+ * заметном месте: клиент ходил бы на один адрес, а страница называла другой, и
+ * расхождение обнаружил бы посетитель, а не тест.
+ *
+ * ПОЧЕМУ ЗДЕСЬ АДРЕС ПЛОЩАДКИ, А НЕ `api.clipwright.io`. `spec.md` обещает
+ * второе, и US-613 его заведёт; на 2026-08-09 у `api.clipwright.io` нет ни `A`,
+ * ни `CNAME` (замер `dig`), то есть команда с этим адресом не работает ни у
+ * кого. Напечатать её на странице значило бы продать неработающий пример —
+ * ровно то, что запрещает главное правило брифа лендинга. Смена адреса в
+ * US-613 будет правкой ЭТОЙ строки, и обе поверхности переедут вместе.
+ */
+export const PUBLIC_API_BASE_URL = "https://api-production-7e69.up.railway.app";
+/**
+ * Пакеты npm, которыми продукт вызывается. Названия печатает и лендинг, и
+ * `--help`, и документация — значит это тоже контракт, а не текст страницы.
+ */
+export const CLI_PACKAGE = "@clipwright/cli";
+export const CLI_BIN = "clipwright";
+export const MCP_PACKAGE = "@clipwright/mcp-server";
+/** Петлевые имена — единственное, чему разрешён `http:`: локальный API никуда не */
+/** выходит, и требовать там сертификат значило бы запретить разработку. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/** Адрес API ИЗ ОКРУЖЕНИЯ — только `https:`: по нему уходит `Authorization: Bearer */
+/** cw_…`. Программный `baseUrl` встраивателя не трогаем — его выбирает автор кода. */
+export function apiBaseUrlFromEnv(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`CLIPWRIGHT_API_URL is not a URL: ${raw}`);
+    }
+    if (url.protocol === "https:")
+        return raw;
+    if (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))
+        return raw;
+    throw new Error(`CLIPWRIGHT_API_URL must be https (loopback may be http), got ${url.protocol}//${url.hostname}. ` +
+        "The api key travels in the Authorization header of every request to it.");
+}
+//# sourceMappingURL=public-endpoints.js.map

package/dist/public-endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-endpoints.js","sourceRoot":"","sources":["../src/public-endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,4CAA4C,CAAC;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,CAAC;AACpC,MAAM,CAAC,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAEpD,oFAAoF;AACpF,2EAA2E;AAC3E,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;AAE3E,sFAAsF;AACtF,sFAAsF;AACtF,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACvD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAEtD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IAC1C,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,GAAG,CAAC;IAE7E,MAAM,IAAI,KAAK,CACb,gEAAgE,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,QAAQ,IAAI;QAC/F,yEAAyE,CAC5E,CAAC;AACJ,CAAC"}