@veruna/api-contracts 19.1.0 → 20.1.0

package/build/v1/plans/schemas/plan-status.enum.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlanStatus = void 0;
+/**
+ * Lifecycle status of a Plan catalogue entry.
+ *
+ * ACTIVE   — available for purchase.
+ * INACTIVE — hidden from public; admin can still see it.
+ * DELETED  — soft-deleted; FK ON DELETE RESTRICT keeps historical records intact.
+ */
 var PlanStatus;
 (function (PlanStatus) {
     PlanStatus["ACTIVE"] = "ACTIVE";

package/build/v1/plans/schemas/plan-status.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-status.enum.js","sourceRoot":"","sources":["../../../../v1/plans/schemas/plan-status.enum.ts"],"names":[],"mappings":";;;AAOA,IAAY,UAIX;AAJD,WAAY,UAAU;IAClB,+BAAiB,CAAA;IACjB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;AACvB,CAAC,EAJW,UAAU,0BAAV,UAAU,QAIrB"}
+{"version":3,"file":"plan-status.enum.js","sourceRoot":"","sources":["../../../../v1/plans/schemas/plan-status.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,IAAY,UAIX;AAJD,WAAY,UAAU;IAClB,+BAAiB,CAAA;IACjB,mCAAqB,CAAA;IACrB,iCAAmB,CAAA;AACvB,CAAC,EAJW,UAAU,0BAAV,UAAU,QAIrB"}

package/build/v1/plans/schemas/plan-type.enum.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Plan type discriminates subscription plans from one-time packages.
+ *
+ * FREE         — no payment; entitlements seeded via welcome/daily mechanisms.
+ * SUBSCRIPTION — recurring billing (1/3/6/12-month terms).
+ * PACKAGE      — one-time purchase; lives 1 year, no rollover.
+ */
 export declare enum PlanType {
     FREE = "FREE",
     SUBSCRIPTION = "SUBSCRIPTION",

package/build/v1/plans/schemas/plan-type.enum.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlanType = void 0;
+/**
+ * Plan type discriminates subscription plans from one-time packages.
+ *
+ * FREE         — no payment; entitlements seeded via welcome/daily mechanisms.
+ * SUBSCRIPTION — recurring billing (1/3/6/12-month terms).
+ * PACKAGE      — one-time purchase; lives 1 year, no rollover.
+ */
 var PlanType;
 (function (PlanType) {
     PlanType["FREE"] = "FREE";

package/build/v1/plans/schemas/plan-type.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-type.enum.js","sourceRoot":"","sources":["../../../../v1/plans/schemas/plan-type.enum.ts"],"names":[],"mappings":";;;AAOA,IAAY,QAIX;AAJD,WAAY,QAAQ;IAChB,yBAAa,CAAA;IACb,yCAA6B,CAAA;IAC7B,+BAAmB,CAAA;AACvB,CAAC,EAJW,QAAQ,wBAAR,QAAQ,QAInB"}
+{"version":3,"file":"plan-type.enum.js","sourceRoot":"","sources":["../../../../v1/plans/schemas/plan-type.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,IAAY,QAIX;AAJD,WAAY,QAAQ;IAChB,yBAAa,CAAA;IACb,yCAA6B,CAAA;IAC7B,+BAAmB,CAAA;AACvB,CAAC,EAJW,QAAQ,wBAAR,QAAQ,QAInB"}

package/build/v1/plans/schemas/plan.schema.d.ts

@@ -4,6 +4,12 @@ import { PlanStatus } from './plan-status.enum';
 import { PlanFeature } from './plan-feature.enum';
 import { Modality } from '../../ai-model/schemas/modality.enum';
 import { ToolId } from '../../ai/tool-id.enum';
+/**
+ * A single AI model node within the plan catalog model tree.
+ * Contains only the display fields needed by the frontend to render the tree
+ * and per-plan availability tooltips. No per-user access field — availability
+ * is per-plan (resolved via plan.models.allModels or plan.models.availableModelIds).
+ */
 export declare const PlanCatalogModelNodeSchema: z.ZodObject<{
     uuid: z.ZodString;
     title: z.ZodString;
@@ -13,6 +19,11 @@ export declare const PlanCatalogModelNodeSchema: z.ZodObject<{
     outputModalities: z.ZodArray<z.ZodEnum<typeof Modality>>;
 }, z.core.$strip>;
 export type PlanCatalogModelNode = z.infer<typeof PlanCatalogModelNodeSchema>;
+/**
+ * A provider group in the plan catalog model tree.
+ * Mirrors PublicProviderWithModelsSchema shape (uuid, title, icon, order + models[])
+ * but uses PlanCatalogModelNodeSchema (lightweight, no per-user access field).
+ */
 export declare const PlanCatalogModelTreeProviderSchema: z.ZodObject<{
     uuid: z.ZodString;
     title: z.ZodString;
@@ -28,6 +39,14 @@ export declare const PlanCatalogModelTreeProviderSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PlanCatalogModelTreeProvider = z.infer<typeof PlanCatalogModelTreeProviderSchema>;
+/**
+ * A single tool node within the plan catalog tool tree.
+ * Display fields the frontend needs to render the tool row + a tool's bound
+ * AI models. No per-user/per-plan access field — tool availability is per-plan
+ * (resolved via plan.tools.allTools or plan.tools.availableToolIds), and the
+ * availability of each model INSIDE a tool reuses the plan's own model gate
+ * (plan.models.allModels || plan.models.availableModelIds.includes(modelUuid)).
+ */
 export declare const PlanCatalogToolNodeSchema: z.ZodObject<{
     uuid: z.ZodString;
     key: z.ZodEnum<typeof ToolId>;
@@ -37,11 +56,20 @@ export declare const PlanCatalogToolNodeSchema: z.ZodObject<{
     modelIds: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type PlanCatalogToolNode = z.infer<typeof PlanCatalogToolNodeSchema>;
+/**
+ * A single price point for a plan (periodMonths=null for PACKAGE — one-time purchase).
+ * price is serialized as string because it represents a BigInt (internal integer units).
+ */
 export declare const PlanPriceSchema: z.ZodObject<{
     periodMonths: z.ZodNullable<z.ZodNumber>;
     price: z.ZodString;
 }, z.core.$strip>;
 export type PlanPrice = z.infer<typeof PlanPriceSchema>;
+/**
+ * Generation estimate entry for a single output modality.
+ * When available=false, min and max are null (no models of this modality in plan).
+ * min/max represent number of content units generatable per monthly grant.
+ */
 export declare const GenerationEstimateEntrySchema: z.ZodObject<{
     modality: z.ZodEnum<typeof Modality>;
     available: z.ZodBoolean;
@@ -49,6 +77,16 @@ export declare const GenerationEstimateEntrySchema: z.ZodObject<{
     max: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 export type GenerationEstimateEntry = z.infer<typeof GenerationEstimateEntrySchema>;
+/**
+ * Model summary attached to each plan in the catalog.
+ * count              — models accessible to this plan (= totalActiveModels when grantsAllModels).
+ * total              — total active models in the catalog (denominator for «X of Y»).
+ * allModels          — true when plan unlocks all active models.
+ * availableModelIds  — UUIDs of models available on this specific plan.
+ *                      Empty array when allModels=true (all models are available).
+ *                      Frontend derives icon row from first N of availableModelIds
+ *                      resolved via the catalog-level modelTree.
+ */
 export declare const PlanModelsSummarySchema: z.ZodObject<{
     count: z.ZodNumber;
     total: z.ZodNumber;
@@ -56,6 +94,15 @@ export declare const PlanModelsSummarySchema: z.ZodObject<{
     availableModelIds: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type PlanModelsSummary = z.infer<typeof PlanModelsSummarySchema>;
+/**
+ * Tool summary attached to each plan in the catalog. Mirrors PlanModelsSummary.
+ * count            — tools accessible to this plan (= totalActiveTools when allTools).
+ * total            — total active tools in the catalog (denominator for «X of Y»).
+ * allTools         — true when the plan unlocks all active tools (legacy default).
+ * availableToolIds — UUIDs of tools available on this specific plan.
+ *                    Empty when allTools=true — frontend uses the full toolTree.
+ *                    Frontend availability check: allTools || availableToolIds.includes(tool.uuid)
+ */
 export declare const PlanToolsSummarySchema: z.ZodObject<{
     count: z.ZodNumber;
     total: z.ZodNumber;
@@ -63,6 +110,11 @@ export declare const PlanToolsSummarySchema: z.ZodObject<{
     availableToolIds: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type PlanToolsSummary = z.infer<typeof PlanToolsSummarySchema>;
+/**
+ * Full plan response returned to both public (list) and admin endpoints.
+ * monthlyGrant is a BigInt value serialized as string.
+ * grantsAllModels=true means the plan unlocks all active AI models.
+ */
 export declare const PlanSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<typeof PlanType>;
@@ -106,6 +158,13 @@ export declare const PlanSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Plan = z.infer<typeof PlanSchema>;
+/**
+ * Public (unauthenticated) plan catalog response.
+ * modelTree — full provider-grouped AI model tree, returned ONCE at top level.
+ *   Frontend uses this to render the per-plan availability tooltip showing every
+ *   model as available or unavailable relative to a given plan.
+ * items     — plans, each carrying its own models.availableModelIds id-set.
+ */
 export declare const PlanListResponseSchema: z.ZodObject<{
     modelTree: z.ZodArray<z.ZodObject<{
         uuid: z.ZodString;
@@ -173,12 +232,32 @@ export declare const PlanListResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PlanListResponse = z.infer<typeof PlanListResponseSchema>;
+/**
+ * Allowed transition kinds for the reg catalog response.
+ * NEW   — user has no active subscription; this plan requires a fresh purchase.
+ * SAME  — this is the user's current plan (already subscribed).
+ */
 export declare enum PlanTransition {
     UPGRADE = "UPGRADE",
     DOWNGRADE = "DOWNGRADE",
     SAME = "SAME",
     NEW = "NEW"
 }
+/**
+ * Extends PlanSchema with per-user subscription context.
+ * Returned by GET /v1/plans for authenticated users.
+ *
+ * currentPlanCode — code of the user's currently active plan; null if no active subscription.
+ * transition      — direction relative to user's current plan; null if no active subscription.
+ * surcharge — proration charge as integer string (×100 of RUB) for an upgrade; "0" for downgrade/same/no-sub.
+ */
+/**
+ * Per-period change preview for one plan: the transition and surcharge the user would get
+ * for each billing period this plan offers. Lets the catalog show the right price before the
+ * user confirms a period. surcharge is an integer string (×100 of RUB); "0" for downgrade/same
+ * (downgrade applies at renewal with no immediate charge). Estimate — the exact amount is
+ * computed server-side at /change time.
+ */
 export declare const PlanPeriodSurchargeSchema: z.ZodObject<{
     periodMonths: z.ZodNumber;
     transition: z.ZodNullable<z.ZodEnum<typeof PlanTransition>>;
@@ -242,6 +321,12 @@ export declare const PlanCatalogItemSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type PlanCatalogItem = z.infer<typeof PlanCatalogItemSchema>;
+/**
+ * Authenticated (reg) plan catalog response.
+ * modelTree — same full provider-grouped AI model tree as the public response.
+ *   Returned once at top level; each plan carries its own models.availableModelIds.
+ * items     — plans enriched with per-user subscription context.
+ */
 export declare const PlanCatalogResponseSchema: z.ZodObject<{
     modelTree: z.ZodArray<z.ZodObject<{
         uuid: z.ZodString;
@@ -322,8 +407,16 @@ export declare const PlanCatalogResponseSchema: z.ZodObject<{
     bonusEligible: z.ZodBoolean;
 }, z.core.$strip>;
 export type PlanCatalogResponse = z.infer<typeof PlanCatalogResponseSchema>;
+/**
+ * Validation limits mirroring blueprint §1 constraints.
+ */
 export declare const PLAN_PERCENT_MAX: 100;
 export declare const PLAN_CHARS_MIN: 1;
+/**
+ * Дефолты пределов работы с файлами для вновь создаваемого тарифа.
+ * Совпадают с DEFAULT колонок в БД — чтобы тариф, заведённый мимо админки,
+ * и тариф, заведённый через неё, вели себя одинаково.
+ */
 export declare const PLAN_MAX_DOCUMENT_PAGES_DEFAULT: 15;
 export declare const PLAN_MAX_FILE_SIZE_MB_DEFAULT = 100;
 export declare const PLAN_MAX_TEXT_TOKENS_DEFAULT: 5000;

package/build/v1/plans/schemas/plan.schema.js

@@ -8,6 +8,15 @@ const plan_status_enum_1 = require("./plan-status.enum");
 const plan_feature_enum_1 = require("./plan-feature.enum");
 const modality_enum_1 = require("../../ai-model/schemas/modality.enum");
 const tool_id_enum_1 = require("../../ai/tool-id.enum");
+// ─────────────────────────────────────────────────────────────────────────────
+// Model tree — one copy at catalog root, shared by both public and reg endpoints
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * A single AI model node within the plan catalog model tree.
+ * Contains only the display fields needed by the frontend to render the tree
+ * and per-plan availability tooltips. No per-user access field — availability
+ * is per-plan (resolved via plan.models.allModels or plan.models.availableModelIds).
+ */
 exports.PlanCatalogModelNodeSchema = zod_1.z.object({
     uuid: zod_1.z.string().regex(shared_1.UUID_REGEX),
     title: zod_1.z.string(),
@@ -16,6 +25,11 @@ exports.PlanCatalogModelNodeSchema = zod_1.z.object({
     inputModalities: zod_1.z.array(zod_1.z.nativeEnum(modality_enum_1.Modality)),
     outputModalities: zod_1.z.array(zod_1.z.nativeEnum(modality_enum_1.Modality)),
 });
+/**
+ * A provider group in the plan catalog model tree.
+ * Mirrors PublicProviderWithModelsSchema shape (uuid, title, icon, order + models[])
+ * but uses PlanCatalogModelNodeSchema (lightweight, no per-user access field).
+ */
 exports.PlanCatalogModelTreeProviderSchema = zod_1.z.object({
     uuid: zod_1.z.string().regex(shared_1.UUID_REGEX),
     title: zod_1.z.string(),
@@ -23,36 +37,106 @@ exports.PlanCatalogModelTreeProviderSchema = zod_1.z.object({
     order: zod_1.z.number().int().nonnegative(),
     models: zod_1.z.array(exports.PlanCatalogModelNodeSchema),
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool tree — one copy at catalog root, shared by both public and reg endpoints
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * A single tool node within the plan catalog tool tree.
+ * Display fields the frontend needs to render the tool row + a tool's bound
+ * AI models. No per-user/per-plan access field — tool availability is per-plan
+ * (resolved via plan.tools.allTools or plan.tools.availableToolIds), and the
+ * availability of each model INSIDE a tool reuses the plan's own model gate
+ * (plan.models.allModels || plan.models.availableModelIds.includes(modelUuid)).
+ */
 exports.PlanCatalogToolNodeSchema = zod_1.z.object({
     uuid: zod_1.z.string().regex(shared_1.UUID_REGEX),
+    /**
+     * Canonical tool identifier (WEB_SEARCH, IMAGE_GEN, …). Stable across
+     * title/icon edits — the frontend switches on this instead of matching
+     * the renameable display title.
+     */
     key: zod_1.z.nativeEnum(tool_id_enum_1.ToolId),
     title: zod_1.z.string(),
     icon: zod_1.z.string(),
     order: zod_1.z.number().int().nonnegative(),
+    /**
+     * UUIDs of AI models bound to this tool (the tool's full model set).
+     * Empty when the tool has no model bindings (e.g. native tools).
+     *
+     * Availability of each model inside the tool is gated by the PLAN's model
+     * entitlement ONLY (intersect with plan.models.allModels / availableModelIds),
+     * NOT by per-user model visibility — identical semantics to the catalog-root
+     * modelTree, which is a per-PLAN availability surface, not a per-USER one.
+     * A subscriber-visibility model may therefore show as available-on-plan here
+     * even though the live runtime gate (calculateModelAccessWithinTool) would
+     * additionally require an active subscription for that specific user.
+     */
     modelIds: zod_1.z.array(zod_1.z.string().regex(shared_1.UUID_REGEX)),
 });
+/**
+ * A single price point for a plan (periodMonths=null for PACKAGE — one-time purchase).
+ * price is serialized as string because it represents a BigInt (internal integer units).
+ */
 exports.PlanPriceSchema = zod_1.z.object({
     periodMonths: zod_1.z.number().int().positive().nullable(),
     price: zod_1.z.string(),
 });
+/**
+ * Generation estimate entry for a single output modality.
+ * When available=false, min and max are null (no models of this modality in plan).
+ * min/max represent number of content units generatable per monthly grant.
+ */
 exports.GenerationEstimateEntrySchema = zod_1.z.object({
     modality: zod_1.z.nativeEnum(modality_enum_1.Modality),
+    /** false when the plan has no models of this modality — show «Недоступно». */
     available: zod_1.z.boolean(),
+    /** Lower bound of content units (cheapest model in set). null when !available. */
     min: zod_1.z.number().int().nonnegative().nullable(),
+    /** Upper bound of content units (cheapest model = most units). null when !available. */
     max: zod_1.z.number().int().nonnegative().nullable(),
 });
+/**
+ * Model summary attached to each plan in the catalog.
+ * count              — models accessible to this plan (= totalActiveModels when grantsAllModels).
+ * total              — total active models in the catalog (denominator for «X of Y»).
+ * allModels          — true when plan unlocks all active models.
+ * availableModelIds  — UUIDs of models available on this specific plan.
+ *                      Empty array when allModels=true (all models are available).
+ *                      Frontend derives icon row from first N of availableModelIds
+ *                      resolved via the catalog-level modelTree.
+ */
 exports.PlanModelsSummarySchema = zod_1.z.object({
     count: zod_1.z.number().int().nonnegative(),
     total: zod_1.z.number().int().nonnegative(),
+    /** true when plan unlocks all active AI models (Max / Custom / PACKAGE). */
     allModels: zod_1.z.boolean(),
+    /**
+     * UUIDs of AI models available on this plan.
+     * Empty when allModels=true — frontend uses the full modelTree in that case.
+     * Frontend availability check: allModels || availableModelIds.includes(model.uuid)
+     */
     availableModelIds: zod_1.z.array(zod_1.z.string().regex(shared_1.UUID_REGEX)),
 });
+/**
+ * Tool summary attached to each plan in the catalog. Mirrors PlanModelsSummary.
+ * count            — tools accessible to this plan (= totalActiveTools when allTools).
+ * total            — total active tools in the catalog (denominator for «X of Y»).
+ * allTools         — true when the plan unlocks all active tools (legacy default).
+ * availableToolIds — UUIDs of tools available on this specific plan.
+ *                    Empty when allTools=true — frontend uses the full toolTree.
+ *                    Frontend availability check: allTools || availableToolIds.includes(tool.uuid)
+ */
 exports.PlanToolsSummarySchema = zod_1.z.object({
     count: zod_1.z.number().int().nonnegative(),
     total: zod_1.z.number().int().nonnegative(),
     allTools: zod_1.z.boolean(),
     availableToolIds: zod_1.z.array(zod_1.z.string().regex(shared_1.UUID_REGEX)),
 });
+/**
+ * Full plan response returned to both public (list) and admin endpoints.
+ * monthlyGrant is a BigInt value serialized as string.
+ * grantsAllModels=true means the plan unlocks all active AI models.
+ */
 exports.PlanSchema = zod_1.z.object({
     id: zod_1.z.string().regex(shared_1.UUID_REGEX),
     type: zod_1.z.nativeEnum(plan_type_enum_1.PlanType),
@@ -62,26 +146,70 @@ exports.PlanSchema = zod_1.z.object({
     displayOrder: zod_1.z.number().int().nonnegative(),
     isHighlighted: zod_1.z.boolean(),
     badge: zod_1.z.string().nullable(),
+    /** Monthly grant amount in internal units (BigInt serialized as string). */
     monthlyGrant: zod_1.z.string(),
+    /** Bonus percentage on top of monthly grant and topups (0–100). */
     bonusPercent: zod_1.z.number().int().min(0).max(100),
+    /** Percentage of remaining SUBSCRIPTION_GRANT bucket rolled over each cycle (0–100). */
     rolloverPercent: zod_1.z.number().int().min(0).max(100),
     maxCharsPerRequest: zod_1.z.number().int().positive(),
+    /** Страниц документа, уезжающих в модель за одно чтение. */
     maxDocumentPages: zod_1.z.number().int().positive(),
+    /** Максимальный размер файла в МБ, как CLIENT_FILE_*_MAX_SIZE_MB. */
     maxFileSizeMb: zod_1.z.number().int().positive(),
+    /**
+     * Токенов текстового файла (txt/md/csv/json/код), уезжающих в модель: файл не больше
+     * лимита — целиком, больший — превью или начало в пределах лимита. Технический потолок —
+     * четверть контекста модели, но не ниже прежнего порога 5000.
+     */
     maxTextTokens: zod_1.z.number().int().positive(),
+    /** true = plan unlocks all active AI models; false = explicit junction set. */
     grantsAllModels: zod_1.z.boolean(),
+    /** true = plan unlocks all active tools (legacy default); false = explicit junction set. */
     grantsAllTools: zod_1.z.boolean(),
     features: zod_1.z.array(zod_1.z.nativeEnum(plan_feature_enum_1.PlanFeature)),
     prices: zod_1.z.array(exports.PlanPriceSchema),
+    /** Model availability summary for this plan. */
     models: exports.PlanModelsSummarySchema,
+    /** Tool availability summary for this plan. */
     tools: exports.PlanToolsSummarySchema,
+    /**
+     * Per-modality generation estimate (TEXT/IMAGE/AUDIO/VIDEO).
+     * Computed server-side; not stored. FILE modality is omitted from this array
+     * as it is not rendered on plan cards.
+     */
     generationEstimate: zod_1.z.array(exports.GenerationEstimateEntrySchema),
 });
+/**
+ * Public (unauthenticated) plan catalog response.
+ * modelTree — full provider-grouped AI model tree, returned ONCE at top level.
+ *   Frontend uses this to render the per-plan availability tooltip showing every
+ *   model as available or unavailable relative to a given plan.
+ * items     — plans, each carrying its own models.availableModelIds id-set.
+ */
 exports.PlanListResponseSchema = zod_1.z.object({
+    /**
+     * Provider-grouped model tree with all active AI models.
+     * Ordered by provider.order then model.order within each provider.
+     * Only providers that have at least one active model are included.
+     */
     modelTree: zod_1.z.array(exports.PlanCatalogModelTreeProviderSchema),
+    /**
+     * Flat list of all active tools with their bound model UUIDs.
+     * Returned once at top level; each plan carries its own tools.availableToolIds.
+     * Ordered by tool.order.
+     */
     toolTree: zod_1.z.array(exports.PlanCatalogToolNodeSchema),
     items: zod_1.z.array(exports.PlanSchema),
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// Authenticated (reg) catalog — plan list enriched with subscription context
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Allowed transition kinds for the reg catalog response.
+ * NEW   — user has no active subscription; this plan requires a fresh purchase.
+ * SAME  — this is the user's current plan (already subscribed).
+ */
 var PlanTransition;
 (function (PlanTransition) {
     PlanTransition["UPGRADE"] = "UPGRADE";
@@ -89,29 +217,88 @@ var PlanTransition;
     PlanTransition["SAME"] = "SAME";
     PlanTransition["NEW"] = "NEW";
 })(PlanTransition || (exports.PlanTransition = PlanTransition = {}));
+/**
+ * Extends PlanSchema with per-user subscription context.
+ * Returned by GET /v1/plans for authenticated users.
+ *
+ * currentPlanCode — code of the user's currently active plan; null if no active subscription.
+ * transition      — direction relative to user's current plan; null if no active subscription.
+ * surcharge — proration charge as integer string (×100 of RUB) for an upgrade; "0" for downgrade/same/no-sub.
+ */
+/**
+ * Per-period change preview for one plan: the transition and surcharge the user would get
+ * for each billing period this plan offers. Lets the catalog show the right price before the
+ * user confirms a period. surcharge is an integer string (×100 of RUB); "0" for downgrade/same
+ * (downgrade applies at renewal with no immediate charge). Estimate — the exact amount is
+ * computed server-side at /change time.
+ */
 exports.PlanPeriodSurchargeSchema = zod_1.z.object({
     periodMonths: zod_1.z.number().int().positive(),
     transition: zod_1.z.nativeEnum(PlanTransition).nullable(),
     surcharge: zod_1.z.string(),
+    /**
+     * Money credit folded into `surcharge` — the unused part of the current
+     * term (remaining grant + unbilled future months of a multi-month term)
+     * converted to money, capped at what was actually paid. Integer string
+     * (×100 of RUB). "0" for downgrade/same.
+     */
     credit: zod_1.z.string(),
+    /** The flat upgrade fee component of `surcharge`. Integer string (×100 of RUB). "0" for downgrade/same. */
     fee: zod_1.z.string(),
 });
 exports.PlanCatalogItemSchema = exports.PlanSchema.extend({
     currentPlanCode: zod_1.z.string().nullable(),
     transition: zod_1.z.nativeEnum(PlanTransition).nullable(),
     surcharge: zod_1.z.string().nullable(),
+    /** Money credit folded into `surcharge` — see PlanPeriodSurchargeSchema. Null if unresolved. */
     credit: zod_1.z.string().nullable(),
+    /** The flat upgrade fee component of `surcharge`. Null if unresolved. */
     fee: zod_1.z.string().nullable(),
+    /** Per-period transition + surcharge. null when no active subscription / non-subscription plan. */
     surchargeByPeriod: zod_1.z.array(exports.PlanPeriodSurchargeSchema).nullable(),
 });
+/**
+ * Authenticated (reg) plan catalog response.
+ * modelTree — same full provider-grouped AI model tree as the public response.
+ *   Returned once at top level; each plan carries its own models.availableModelIds.
+ * items     — plans enriched with per-user subscription context.
+ */
 exports.PlanCatalogResponseSchema = zod_1.z.object({
+    /**
+     * Provider-grouped model tree with all active AI models.
+     * Ordered by provider.order then model.order within each provider.
+     * Only providers that have at least one active model are included.
+     */
     modelTree: zod_1.z.array(exports.PlanCatalogModelTreeProviderSchema),
+    /**
+     * Flat list of all active tools with their bound model UUIDs.
+     * Same shape as the public response; each plan carries its own tools.availableToolIds.
+     */
     toolTree: zod_1.z.array(exports.PlanCatalogToolNodeSchema),
     items: zod_1.z.array(exports.PlanCatalogItemSchema),
+    /**
+     * Owner decision 04.10.2026: catalog-wide (not per-plan) flag — true only while THIS
+     * user is still eligible for the first-purchase plan bonus (never had a paid
+     * subscription order of any kind, including one later refunded). Each item's
+     * `bonusPercent` always carries the plan's nominal bonus; compute the effective bonus
+     * shown to the user as `bonusEligible ? item.bonusPercent : 0`. The public (unreg)
+     * catalog has no such field — an anonymous visitor is always eligible.
+     */
     bonusEligible: zod_1.z.boolean(),
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// Admin request schemas (with i18n keys)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Validation limits mirroring blueprint §1 constraints.
+ */
 exports.PLAN_PERCENT_MAX = 100;
 exports.PLAN_CHARS_MIN = 1;
+/**
+ * Дефолты пределов работы с файлами для вновь создаваемого тарифа.
+ * Совпадают с DEFAULT колонок в БД — чтобы тариф, заведённый мимо админки,
+ * и тариф, заведённый через неё, вели себя одинаково.
+ */
 exports.PLAN_MAX_DOCUMENT_PAGES_DEFAULT = 15;
 exports.PLAN_MAX_FILE_SIZE_MB_DEFAULT = 100;
 exports.PLAN_MAX_TEXT_TOKENS_DEFAULT = 5000;
@@ -120,6 +307,7 @@ exports.PLAN_BADGE_MAX = 100;
 exports.PLAN_CODE_MAX = 50;
 const adminPlanPriceSchema = zod_1.z
     .object({
+    /** null for PACKAGE (one-time purchase) */
     periodMonths: zod_1.z
         .number({ error: 'AdminCreatePlanRequest.prices.periodMonths.invalid' })
         .int({ message: 'AdminCreatePlanRequest.prices.periodMonths.invalid' })
@@ -160,6 +348,7 @@ exports.AdminCreatePlanRequestSchema = zod_1.z
         .nullable()
         .optional()
         .default(null),
+    /** Monthly grant as decimal string (BigInt, internal units). */
     monthlyGrant: zod_1.z
         .string({ error: 'AdminCreatePlanRequest.monthlyGrant.required' })
         .min(1, { message: 'AdminCreatePlanRequest.monthlyGrant.required' })
@@ -180,6 +369,11 @@ exports.AdminCreatePlanRequestSchema = zod_1.z
         .number({ error: 'AdminCreatePlanRequest.maxCharsPerRequest.required' })
         .int({ message: 'AdminCreatePlanRequest.maxCharsPerRequest.invalid' })
         .min(exports.PLAN_CHARS_MIN, { message: 'AdminCreatePlanRequest.maxCharsPerRequest.min' }),
+    /**
+     * Пределы работы с файлами. Заданы с дефолтами, а не обязательны:
+     * иначе каждая существующая админская форма и каждый сохранённый
+     * пресет сломались бы на первом же сохранении тарифа.
+     */
     maxDocumentPages: zod_1.z
         .number({ error: 'AdminCreatePlanRequest.maxDocumentPages.invalid' })
         .int({ message: 'AdminCreatePlanRequest.maxDocumentPages.invalid' })
@@ -195,17 +389,30 @@ exports.AdminCreatePlanRequestSchema = zod_1.z
         .int({ message: 'AdminCreatePlanRequest.maxTextTokens.invalid' })
         .min(1, { message: 'AdminCreatePlanRequest.maxTextTokens.min' })
         .default(exports.PLAN_MAX_TEXT_TOKENS_DEFAULT),
+    /**
+     * When true, the plan unlocks all active AI models.
+     * When false, the explicit model set is determined by modelIds.
+     */
     grantsAllModels: zod_1.z
         .boolean({ error: 'AdminCreatePlanRequest.grantsAllModels.invalid' })
         .default(false),
+    /**
+     * Explicit list of AI model UUIDs bound to this plan.
+     * Ignored when grantsAllModels=true. Each entry must be an existing active model UUID.
+     */
     modelIds: zod_1.z
         .array(zod_1.z
         .string({ error: 'AdminCreatePlanRequest.modelIds.invalid' })
         .regex(shared_1.UUID_REGEX, { message: 'AdminCreatePlanRequest.modelIds.invalid' }), { error: 'AdminCreatePlanRequest.modelIds.invalid' })
         .default([]),
+    /**
+     * When true (default), the plan unlocks all tools — visibility-only gating, the
+     * backward-compatible default. When false, only the tools in toolIds are unlocked.
+     */
     grantsAllTools: zod_1.z
         .boolean({ error: 'AdminCreatePlanRequest.grantsAllTools.invalid' })
         .default(true),
+    /** Tool UUIDs bound to this plan. Ignored when grantsAllTools=true. Each must exist. */
     toolIds: zod_1.z
         .array(zod_1.z
         .string({ error: 'AdminCreatePlanRequest.toolIds.invalid' })
@@ -225,6 +432,7 @@ exports.AdminCreatePlanRequestSchema = zod_1.z
     path: ['toolIds'],
 })
     .refine((v) => {
+    // Validate: if SUBSCRIPTION, periodMonths must not be null
     if (v.type === plan_type_enum_1.PlanType.SUBSCRIPTION) {
         return v.prices.every((p) => p.periodMonths !== null);
     }
@@ -234,6 +442,7 @@ exports.AdminCreatePlanRequestSchema = zod_1.z
     path: ['prices'],
 })
     .refine((v) => {
+    // Validate: if PACKAGE or FREE, periodMonths must be null
     if (v.type === plan_type_enum_1.PlanType.PACKAGE || v.type === plan_type_enum_1.PlanType.FREE) {
         return v.prices.every((p) => p.periodMonths === null);
     }
@@ -300,17 +509,32 @@ exports.AdminUpdatePlanRequestSchema = zod_1.z
         .int({ message: 'AdminUpdatePlanRequest.maxCharsPerRequest.invalid' })
         .min(exports.PLAN_CHARS_MIN, { message: 'AdminUpdatePlanRequest.maxCharsPerRequest.min' })
         .optional(),
+    /**
+     * When true, the plan unlocks all active AI models.
+     * When false, the explicit model set is determined by modelIds.
+     * Optional — omit to leave unchanged.
+     */
     grantsAllModels: zod_1.z
         .boolean({ error: 'AdminUpdatePlanRequest.grantsAllModels.invalid' })
         .optional(),
+    /**
+     * Replacement model ID list. When provided, replaces the entire existing set.
+     * Ignored when grantsAllModels=true. Each entry must be an existing active model UUID.
+     * Optional — omit to leave unchanged.
+     */
     modelIds: zod_1.z
         .array(zod_1.z
         .string({ error: 'AdminUpdatePlanRequest.modelIds.invalid' })
         .regex(shared_1.UUID_REGEX, { message: 'AdminUpdatePlanRequest.modelIds.invalid' }), { error: 'AdminUpdatePlanRequest.modelIds.invalid' })
         .optional(),
+    /** Optional — omit to leave unchanged. */
     grantsAllTools: zod_1.z
         .boolean({ error: 'AdminUpdatePlanRequest.grantsAllTools.invalid' })
         .optional(),
+    /**
+     * Replacement tool ID list. Ignored when grantsAllTools=true. Each must exist.
+     * Optional — omit to leave unchanged.
+     */
     toolIds: zod_1.z
         .array(zod_1.z
         .string({ error: 'AdminUpdatePlanRequest.toolIds.invalid' })
@@ -324,6 +548,7 @@ exports.AdminUpdatePlanRequestSchema = zod_1.z
         .optional(),
 })
     .refine((v) => {
+    // If both are provided, grantsAllModels=true with non-empty modelIds is a conflict
     if (v.grantsAllModels === true && v.modelIds !== undefined && v.modelIds.length > 0) {
         return false;
     }