@veruna/api-contracts 19.1.0 → 20.1.0

package/build/v1/client-file/schemas/client-file-status.enum.d.ts

@@ -1,7 +1,25 @@
+/**
+ * Lifecycle status of a `client_file_objects` row.
+ *
+ * Persisted as UPPERCASE strings in PostgreSQL (`status` column,
+ * VARCHAR(20)). Use this enum for any contract-level filtering or
+ * response shape — never raw string literals.
+ */
 export declare enum ClientFileStatus {
+    /**
+     * Reserved row inserted before the S3 PUT. Counts toward the
+     * owner's quota so concurrent uploads cannot race past the cap;
+     * excluded from user-visible listings until the upload finalises.
+     * A stale UPLOADING row (process crash / S3 timeout) is reaped by
+     * the periodic cleanup worker.
+     */
     UPLOADING = "UPLOADING",
+    /** Uploaded, not yet attached to a message. Default state after PUT upload. */
     PENDING = "PENDING",
+    /** Attached to a sent message; counts toward the user's chat history. */
     ATTACHED = "ATTACHED",
+    /** Generated by the assistant (image / file tool). Counts toward user quota — assistant outputs occupy real storage. */
     AI_GENERATED = "AI_GENERATED",
+    /** Soft-deleted by the user. Excluded from default listings and quota math. */
     DELETED = "DELETED"
 }

package/build/v1/client-file/schemas/client-file-status.enum.js

@@ -1,12 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientFileStatus = void 0;
+/**
+ * Lifecycle status of a `client_file_objects` row.
+ *
+ * Persisted as UPPERCASE strings in PostgreSQL (`status` column,
+ * VARCHAR(20)). Use this enum for any contract-level filtering or
+ * response shape — never raw string literals.
+ */
 var ClientFileStatus;
 (function (ClientFileStatus) {
+    /**
+     * Reserved row inserted before the S3 PUT. Counts toward the
+     * owner's quota so concurrent uploads cannot race past the cap;
+     * excluded from user-visible listings until the upload finalises.
+     * A stale UPLOADING row (process crash / S3 timeout) is reaped by
+     * the periodic cleanup worker.
+     */
     ClientFileStatus["UPLOADING"] = "UPLOADING";
+    /** Uploaded, not yet attached to a message. Default state after PUT upload. */
     ClientFileStatus["PENDING"] = "PENDING";
+    /** Attached to a sent message; counts toward the user's chat history. */
     ClientFileStatus["ATTACHED"] = "ATTACHED";
+    /** Generated by the assistant (image / file tool). Counts toward user quota — assistant outputs occupy real storage. */
     ClientFileStatus["AI_GENERATED"] = "AI_GENERATED";
+    /** Soft-deleted by the user. Excluded from default listings and quota math. */
     ClientFileStatus["DELETED"] = "DELETED";
 })(ClientFileStatus || (exports.ClientFileStatus = ClientFileStatus = {}));
 //# sourceMappingURL=client-file-status.enum.js.map

package/build/v1/client-file/schemas/client-file-status.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-file-status.enum.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/client-file-status.enum.ts"],"names":[],"mappings":";;;AAOA,IAAY,gBAiBX;AAjBD,WAAY,gBAAgB;IAQxB,2CAAuB,CAAA;IAEvB,uCAAmB,CAAA;IAEnB,yCAAqB,CAAA;IAErB,iDAA6B,CAAA;IAE7B,uCAAmB,CAAA;AACvB,CAAC,EAjBW,gBAAgB,gCAAhB,gBAAgB,QAiB3B"}
+{"version":3,"file":"client-file-status.enum.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/client-file-status.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,IAAY,gBAiBX;AAjBD,WAAY,gBAAgB;IACxB;;;;;;OAMG;IACH,2CAAuB,CAAA;IACvB,+EAA+E;IAC/E,uCAAmB,CAAA;IACnB,yEAAyE;IACzE,yCAAqB,CAAA;IACrB,wHAAwH;IACxH,iDAA6B,CAAA;IAC7B,+EAA+E;IAC/E,uCAAmB,CAAA;AACvB,CAAC,EAjBW,gBAAgB,gCAAhB,gBAAgB,QAiB3B"}

package/build/v1/client-file/schemas/client-file-upload-query.schema.d.ts

@@ -1,5 +1,13 @@
 import { z } from 'zod';
 import { ClientFileMark } from './client-file-mark.enum';
+/**
+ * Optional upload-time query string. The frontend uses `marks` to flag
+ * the file before persistence — currently only `PASTED` is meaningful,
+ * the field stays an array so future flags don't require a schema bump.
+ *
+ * Accepts either a single value (`?marks=PASTED`) or a repeated key
+ * (`?marks=PASTED&marks=FOO`); both are normalised to `ClientFileMark[]`.
+ */
 export declare const ClientFileUploadQuerySchema: z.ZodObject<{
     marks: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof ClientFileMark>, z.ZodArray<z.ZodEnum<typeof ClientFileMark>>]>>, z.ZodTransform<ClientFileMark[], ClientFileMark.PASTED | ClientFileMark.PASTED[] | undefined>>;
 }, z.core.$strip>;

package/build/v1/client-file/schemas/client-file-upload-query.schema.js

@@ -3,6 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientFileUploadQuerySchema = void 0;
 const zod_1 = require("zod");
 const client_file_mark_enum_1 = require("./client-file-mark.enum");
+/**
+ * Optional upload-time query string. The frontend uses `marks` to flag
+ * the file before persistence — currently only `PASTED` is meaningful,
+ * the field stays an array so future flags don't require a schema bump.
+ *
+ * Accepts either a single value (`?marks=PASTED`) or a repeated key
+ * (`?marks=PASTED&marks=FOO`); both are normalised to `ClientFileMark[]`.
+ */
 exports.ClientFileUploadQuerySchema = zod_1.z.object({
     marks: zod_1.z
         .union([zod_1.z.enum(client_file_mark_enum_1.ClientFileMark), zod_1.z.array(zod_1.z.enum(client_file_mark_enum_1.ClientFileMark))])

package/build/v1/client-file/schemas/client-file-upload-query.schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-file-upload-query.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/client-file-upload-query.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,mEAAyD;AAU5C,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,OAAC;SACH,KAAK,CAAC,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC,CAAC,CAAC,CAAC;SAChE,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAoB,EAAE;QACnC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC,CAAC;CACT,CAAC,CAAC"}
+{"version":3,"file":"client-file-upload-query.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/client-file-upload-query.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,mEAAyD;AAEzD;;;;;;;GAOG;AACU,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,OAAC;SACH,KAAK,CAAC,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC,CAAC,CAAC,CAAC;SAChE,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAoB,EAAE;QACnC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC,CAAC;CACT,CAAC,CAAC"}

package/build/v1/client-file/schemas/index.d.ts

@@ -19,3 +19,4 @@ export * from './user-file-item-response.schema';
 export * from './user-files-list-request.schema';
 export * from './user-files-list-response.schema';
 export * from './user-files-stats-response.schema';
+export * from './client-file-pages.schema';

package/build/v1/client-file/schemas/index.js

@@ -35,4 +35,5 @@ __exportStar(require("./user-file-item-response.schema"), exports);
 __exportStar(require("./user-files-list-request.schema"), exports);
 __exportStar(require("./user-files-list-response.schema"), exports);
 __exportStar(require("./user-files-stats-response.schema"), exports);
+__exportStar(require("./client-file-pages.schema"), exports);
 //# sourceMappingURL=index.js.map

package/build/v1/client-file/schemas/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC;AACxC,4DAA0C;AAC1C,0DAAwC;AACxC,gEAA8C;AAC9C,mEAAiD;AACjD,oEAAkD;AAClD,qEAAmD;AACnD,qEAAmD;AACnD,uEAAqD;AACrD,oEAAkD;AAClD,uEAAqD;AACrD,sEAAoD;AACpD,uEAAqD;AACrD,uEAAqD;AACrD,wEAAsD;AACtD,2DAAyC;AACzC,6DAA2C;AAC3C,mEAAiD;AACjD,mEAAiD;AACjD,oEAAkD;AAClD,qEAAmD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC;AACxC,4DAA0C;AAC1C,0DAAwC;AACxC,gEAA8C;AAC9C,mEAAiD;AACjD,oEAAkD;AAClD,qEAAmD;AACnD,qEAAmD;AACnD,uEAAqD;AACrD,oEAAkD;AAClD,uEAAqD;AACrD,sEAAoD;AACpD,uEAAqD;AACrD,uEAAqD;AACrD,wEAAsD;AACtD,2DAAyC;AACzC,6DAA2C;AAC3C,mEAAiD;AACjD,mEAAiD;AACjD,oEAAkD;AAClD,qEAAmD;AACnD,6DAA2C"}

package/build/v1/client-file/schemas/processing-category.enum.d.ts

@@ -1,6 +1,15 @@
+/**
+ * Category assigned to an uploaded file at upload time.
+ * Determines how the file is processed (Gotenberg, inline text, as-is)
+ * and how it is presented in the LLM context.
+ */
 export declare enum FileProcessingCategory {
+    /** Text-native files (csv, json, txt, md, code) — raw text inline, no PDF conversion */
     TEXT_NATIVE = "TEXT_NATIVE",
+    /** Visual documents (docx, pptx, xlsx, html) — Gotenberg PDF conversion, layout matters */
     VISUAL_DOC = "VISUAL_DOC",
+    /** PDF files — passed as-is, no conversion needed */
     PDF = "PDF",
+    /** Image files — passed as image_url to LLM */
     IMAGE = "IMAGE"
 }

package/build/v1/client-file/schemas/processing-category.enum.js

@@ -1,11 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileProcessingCategory = void 0;
+/**
+ * Category assigned to an uploaded file at upload time.
+ * Determines how the file is processed (Gotenberg, inline text, as-is)
+ * and how it is presented in the LLM context.
+ */
 var FileProcessingCategory;
 (function (FileProcessingCategory) {
+    /** Text-native files (csv, json, txt, md, code) — raw text inline, no PDF conversion */
     FileProcessingCategory["TEXT_NATIVE"] = "TEXT_NATIVE";
+    /** Visual documents (docx, pptx, xlsx, html) — Gotenberg PDF conversion, layout matters */
     FileProcessingCategory["VISUAL_DOC"] = "VISUAL_DOC";
+    /** PDF files — passed as-is, no conversion needed */
     FileProcessingCategory["PDF"] = "PDF";
+    /** Image files — passed as image_url to LLM */
     FileProcessingCategory["IMAGE"] = "IMAGE";
 })(FileProcessingCategory || (exports.FileProcessingCategory = FileProcessingCategory = {}));
 //# sourceMappingURL=processing-category.enum.js.map

package/build/v1/client-file/schemas/processing-category.enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"processing-category.enum.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/processing-category.enum.ts"],"names":[],"mappings":";;;AAKA,IAAY,sBASX;AATD,WAAY,sBAAsB;IAE9B,qDAA2B,CAAA;IAE3B,mDAAyB,CAAA;IAEzB,qCAAW,CAAA;IAEX,yCAAe,CAAA;AACnB,CAAC,EATW,sBAAsB,sCAAtB,sBAAsB,QASjC"}
+{"version":3,"file":"processing-category.enum.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/processing-category.enum.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,IAAY,sBASX;AATD,WAAY,sBAAsB;IAC9B,wFAAwF;IACxF,qDAA2B,CAAA;IAC3B,2FAA2F;IAC3F,mDAAyB,CAAA;IACzB,qDAAqD;IACrD,qCAAW,CAAA;IACX,+CAA+C;IAC/C,yCAAe,CAAA;AACnB,CAAC,EATW,sBAAsB,sCAAtB,sBAAsB,QASjC"}

package/build/v1/client-file/schemas/user-file-item-response.schema.d.ts

@@ -3,6 +3,14 @@ import { ClientFileType } from './client-file-type.enum';
 import { ClientFileStatus } from './client-file-status.enum';
 import { ClientFileMark } from './client-file-mark.enum';
 import { FileProcessingCategory } from './processing-category.enum';
+/**
+ * Single row in the cross-chat user file listing.
+ *
+ * Superset of `ClientFileItemResponseSchema`: adds lifecycle status, the
+ * owning chat reference (id only — FE resolves the title locally), an
+ * optional message reference, the processing category, and ISO-8601
+ * timestamps.
+ */
 export declare const UserFileItemResponseSchema: z.ZodObject<{
     uuid: z.ZodString;
     type: z.ZodEnum<typeof ClientFileType>;

package/build/v1/client-file/schemas/user-file-item-response.schema.js

@@ -7,6 +7,14 @@ const client_file_type_enum_1 = require("./client-file-type.enum");
 const client_file_status_enum_1 = require("./client-file-status.enum");
 const client_file_mark_enum_1 = require("./client-file-mark.enum");
 const processing_category_enum_1 = require("./processing-category.enum");
+/**
+ * Single row in the cross-chat user file listing.
+ *
+ * Superset of `ClientFileItemResponseSchema`: adds lifecycle status, the
+ * owning chat reference (id only — FE resolves the title locally), an
+ * optional message reference, the processing category, and ISO-8601
+ * timestamps.
+ */
 exports.UserFileItemResponseSchema = zod_1.z.object({
     uuid: zod_1.z.string().regex(shared_1.UUID_REGEX),
     type: zod_1.z.enum(client_file_type_enum_1.ClientFileType),

package/build/v1/client-file/schemas/user-file-item-response.schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-file-item-response.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-file-item-response.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,mEAAyD;AACzD,uEAA6D;AAC7D,mEAAyD;AACzD,yEAAoE;AAUvD,QAAA,0BAA0B,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;IAClC,IAAI,EAAE,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC;IAC5B,MAAM,EAAE,OAAC,CAAC,IAAI,CAAC,0CAAgB,CAAC;IAChC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACvB,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACpC,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,OAAO,EAAE,OAAC,CAAC,MAAM,CAAC;QACd,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;KACnC,CAAC;IACF,UAAU,EAAE,OAAC;SACR,MAAM,CAAC;QACJ,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;KACnC,CAAC;SACD,QAAQ,EAAE;IACf,kBAAkB,EAAE,OAAC,CAAC,IAAI,CAAC,iDAAsB,CAAC,CAAC,QAAQ,EAAE;IAC7D,KAAK,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC,CAAC;IACtC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC"}
+{"version":3,"file":"user-file-item-response.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-file-item-response.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,4CAA6C;AAC7C,mEAAyD;AACzD,uEAA6D;AAC7D,mEAAyD;AACzD,yEAAoE;AAEpE;;;;;;;GAOG;AACU,QAAA,0BAA0B,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;IAClC,IAAI,EAAE,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC;IAC5B,MAAM,EAAE,OAAC,CAAC,IAAI,CAAC,0CAAgB,CAAC;IAChC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACvB,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACpC,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,mBAAmB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,OAAO,EAAE,OAAC,CAAC,MAAM,CAAC;QACd,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;KACnC,CAAC;IACF,UAAU,EAAE,OAAC;SACR,MAAM,CAAC;QACJ,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mBAAU,CAAC;KACnC,CAAC;SACD,QAAQ,EAAE;IACf,kBAAkB,EAAE,OAAC,CAAC,IAAI,CAAC,iDAAsB,CAAC,CAAC,QAAQ,EAAE;IAC7D,KAAK,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,CAAC,CAAC;IACtC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC"}

package/build/v1/client-file/schemas/user-files-list-request.schema.d.ts

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 import { ClientFileStatus } from './client-file-status.enum';
 import { ClientFileType } from './client-file-type.enum';
+/**
+ * Query string for `GET /file-api/v1/client/files`.
+ *
+ * - `cursor` is opaque (encoded `(updatedAt, uuid)` tuple from the server).
+ * - `limit` is clamped to [1, 100], defaults to 50.
+ * - `status` / `type` are repeatable and act as inclusive filters.
+ *   The DELETED status is always excluded server-side regardless of the
+ *   filter — there is no `includeDeleted` toggle.
+ *
+ * Error keys: `UserFilesListRequest.<field>.<rule>`.
+ */
 export declare const UserFilesListRequestSchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;

package/build/v1/client-file/schemas/user-files-list-request.schema.js

@@ -4,8 +4,25 @@ exports.UserFilesListRequestSchema = void 0;
 const zod_1 = require("zod");
 const client_file_status_enum_1 = require("./client-file-status.enum");
 const client_file_type_enum_1 = require("./client-file-type.enum");
+/**
+ * Cardinality of each enum, derived once so the array `.max(...)`
+ * caps don't drift when a new status / type is introduced. The cap is
+ * defensive only — it stops a caller from blowing up the SQL `IN (...)`
+ * list with duplicates, not a business rule.
+ */
 const STATUS_FILTER_MAX = Object.values(client_file_status_enum_1.ClientFileStatus).length;
 const TYPE_FILTER_MAX = Object.values(client_file_type_enum_1.ClientFileType).length;
+/**
+ * Query string for `GET /file-api/v1/client/files`.
+ *
+ * - `cursor` is opaque (encoded `(updatedAt, uuid)` tuple from the server).
+ * - `limit` is clamped to [1, 100], defaults to 50.
+ * - `status` / `type` are repeatable and act as inclusive filters.
+ *   The DELETED status is always excluded server-side regardless of the
+ *   filter — there is no `includeDeleted` toggle.
+ *
+ * Error keys: `UserFilesListRequest.<field>.<rule>`.
+ */
 exports.UserFilesListRequestSchema = zod_1.z.object({
     cursor: zod_1.z
         .string({ error: 'UserFilesListRequest.cursor.invalid' })

package/build/v1/client-file/schemas/user-files-list-request.schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-files-list-request.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-files-list-request.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,uEAA6D;AAC7D,mEAAyD;AAQzD,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,0CAAgB,CAAC,CAAC,MAAM,CAAC;AACjE,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,sCAAc,CAAC,CAAC,MAAM,CAAC;AAahD,QAAA,0BAA0B,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,MAAM,EAAE,OAAC;SACJ,MAAM,CAAC,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC;SACxD,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;SACxD,QAAQ,EAAE;IACf,KAAK,EAAE,OAAC,CAAC,MAAM;SACV,MAAM,CAAC,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;SACvD,GAAG,CAAC,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;SAClD,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;SACrD,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;SACvD,OAAO,CAAC,EAAE,CAAC;IAChB,MAAM,EAAE,OAAC;SACJ,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,0CAAgB,EAAE,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC,CAAC;SACjF,GAAG,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;SACtE,QAAQ,EAAE;IACf,IAAI,EAAE,OAAC;SACF,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,EAAE,EAAE,KAAK,EAAE,mCAAmC,EAAE,CAAC,CAAC;SAC7E,GAAG,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC;SAClE,QAAQ,EAAE;CAClB,CAAC,CAAC"}
+{"version":3,"file":"user-files-list-request.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-files-list-request.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,uEAA6D;AAC7D,mEAAyD;AAEzD;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,0CAAgB,CAAC,CAAC,MAAM,CAAC;AACjE,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,sCAAc,CAAC,CAAC,MAAM,CAAC;AAE7D;;;;;;;;;;GAUG;AACU,QAAA,0BAA0B,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/C,MAAM,EAAE,OAAC;SACJ,MAAM,CAAC,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC;SACxD,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;SACxD,QAAQ,EAAE;IACf,KAAK,EAAE,OAAC,CAAC,MAAM;SACV,MAAM,CAAC,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;SACvD,GAAG,CAAC,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;SAClD,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;SACrD,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;SACvD,OAAO,CAAC,EAAE,CAAC;IAChB,MAAM,EAAE,OAAC;SACJ,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,0CAAgB,EAAE,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC,CAAC;SACjF,GAAG,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;SACtE,QAAQ,EAAE;IACf,IAAI,EAAE,OAAC;SACF,KAAK,CAAC,OAAC,CAAC,IAAI,CAAC,sCAAc,EAAE,EAAE,KAAK,EAAE,mCAAmC,EAAE,CAAC,CAAC;SAC7E,GAAG,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC;SAClE,QAAQ,EAAE;CAClB,CAAC,CAAC"}

package/build/v1/client-file/schemas/user-files-list-response.schema.d.ts

@@ -1,4 +1,11 @@
 import { z } from 'zod';
+/**
+ * Cursor-paginated page of user files across all chats.
+ *
+ * `nextCursor` is null iff `hasMore` is false — the server uses a
+ * "fetch limit + 1" pattern, so the two flags are derived from the same
+ * computation and stay in sync.
+ */
 export declare const UserFilesListResponseSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         uuid: z.ZodString;

package/build/v1/client-file/schemas/user-files-list-response.schema.js

@@ -3,6 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.UserFilesListResponseSchema = void 0;
 const zod_1 = require("zod");
 const user_file_item_response_schema_1 = require("./user-file-item-response.schema");
+/**
+ * Cursor-paginated page of user files across all chats.
+ *
+ * `nextCursor` is null iff `hasMore` is false — the server uses a
+ * "fetch limit + 1" pattern, so the two flags are derived from the same
+ * computation and stay in sync.
+ */
 exports.UserFilesListResponseSchema = zod_1.z.object({
     items: zod_1.z.array(user_file_item_response_schema_1.UserFileItemResponseSchema),
     nextCursor: zod_1.z.string().nullable(),

package/build/v1/client-file/schemas/user-files-list-response.schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-files-list-response.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-files-list-response.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,qFAA8E;AASjE,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,OAAC,CAAC,KAAK,CAAC,2DAA0B,CAAC;IAC1C,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;CACvB,CAAC,CAAC"}
+{"version":3,"file":"user-files-list-response.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-files-list-response.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,qFAA8E;AAE9E;;;;;;GAMG;AACU,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,OAAC,CAAC,KAAK,CAAC,2DAA0B,CAAC;IAC1C,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;CACvB,CAAC,CAAC"}

package/build/v1/client-file/schemas/user-files-stats-response.schema.d.ts

@@ -1,4 +1,25 @@
 import { z } from 'zod';
+/**
+ * Aggregate stats for the current user's file storage.
+ *
+ * `totalBytes` sums every active row (`status <> DELETED`), including
+ * UPLOADING reservations and AI_GENERATED outputs — both occupy real
+ * S3 storage and count toward the quota.
+ *
+ * `byStatus` / `byType` carry the row-count breakdown.
+ * `bytesByStatus` / `bytesByType` carry the byte-sum breakdown for the
+ * same buckets — both maps sum to `totalBytes` (modulo bigint coercion).
+ * The bytes maps are what the donut chart renders; the count maps stay
+ * around for "X files in Y status" labels.
+ *
+ * `UPLOADING` is exposed as its own bucket so the donut invariant
+ * (`pending + attached + aiGenerated + uploading = totalBytes`)
+ * holds without smearing semantics across buckets. In normal use the
+ * UPLOADING slice is near zero — uploads finalize within seconds.
+ *
+ * `DELETED` is intentionally absent everywhere — the API never exposes
+ * deletion data in this surface.
+ */
 export declare const UserFilesStatsResponseSchema: z.ZodObject<{
     totalFiles: z.ZodNumber;
     totalBytes: z.ZodNumber;

package/build/v1/client-file/schemas/user-files-stats-response.schema.js

@@ -4,6 +4,27 @@ exports.UserFilesStatsResponseSchema = void 0;
 const zod_1 = require("zod");
 const client_file_status_enum_1 = require("./client-file-status.enum");
 const client_file_type_enum_1 = require("./client-file-type.enum");
+/**
+ * Aggregate stats for the current user's file storage.
+ *
+ * `totalBytes` sums every active row (`status <> DELETED`), including
+ * UPLOADING reservations and AI_GENERATED outputs — both occupy real
+ * S3 storage and count toward the quota.
+ *
+ * `byStatus` / `byType` carry the row-count breakdown.
+ * `bytesByStatus` / `bytesByType` carry the byte-sum breakdown for the
+ * same buckets — both maps sum to `totalBytes` (modulo bigint coercion).
+ * The bytes maps are what the donut chart renders; the count maps stay
+ * around for "X files in Y status" labels.
+ *
+ * `UPLOADING` is exposed as its own bucket so the donut invariant
+ * (`pending + attached + aiGenerated + uploading = totalBytes`)
+ * holds without smearing semantics across buckets. In normal use the
+ * UPLOADING slice is near zero — uploads finalize within seconds.
+ *
+ * `DELETED` is intentionally absent everywhere — the API never exposes
+ * deletion data in this surface.
+ */
 exports.UserFilesStatsResponseSchema = zod_1.z.object({
     totalFiles: zod_1.z.number().int().nonnegative(),
     totalBytes: zod_1.z.number().int().nonnegative(),

package/build/v1/client-file/schemas/user-files-stats-response.schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-files-stats-response.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-files-stats-response.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,uEAA6D;AAC7D,mEAAyD;AAuB5C,QAAA,4BAA4B,GAAG,OAAC,CAAC,MAAM,CAAC;IACjD,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACvC,QAAQ,EAAE,OAAC,CAAC,MAAM,CAAC;QACf,CAAC,0CAAgB,CAAC,SAAS,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC5D,CAAC,0CAAgB,CAAC,OAAO,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC1D,CAAC,0CAAgB,CAAC,QAAQ,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC3D,CAAC,0CAAgB,CAAC,YAAY,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KAClE,CAAC;IACF,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC;QACb,CAAC,sCAAc,CAAC,KAAK,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACtD,CAAC,sCAAc,CAAC,GAAG,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACvD,CAAC;IACF,aAAa,EAAE,OAAC,CAAC,MAAM,CAAC;QACpB,CAAC,0CAAgB,CAAC,SAAS,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC5D,CAAC,0CAAgB,CAAC,OAAO,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC1D,CAAC,0CAAgB,CAAC,QAAQ,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC3D,CAAC,0CAAgB,CAAC,YAAY,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KAClE,CAAC;IACF,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC;QAClB,CAAC,sCAAc,CAAC,KAAK,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACtD,CAAC,sCAAc,CAAC,GAAG,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACvD,CAAC;CACL,CAAC,CAAC"}
+{"version":3,"file":"user-files-stats-response.schema.js","sourceRoot":"","sources":["../../../../v1/client-file/schemas/user-files-stats-response.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,uEAA6D;AAC7D,mEAAyD;AAEzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACU,QAAA,4BAA4B,GAAG,OAAC,CAAC,MAAM,CAAC;IACjD,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACvC,QAAQ,EAAE,OAAC,CAAC,MAAM,CAAC;QACf,CAAC,0CAAgB,CAAC,SAAS,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC5D,CAAC,0CAAgB,CAAC,OAAO,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC1D,CAAC,0CAAgB,CAAC,QAAQ,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC3D,CAAC,0CAAgB,CAAC,YAAY,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KAClE,CAAC;IACF,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC;QACb,CAAC,sCAAc,CAAC,KAAK,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACtD,CAAC,sCAAc,CAAC,GAAG,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACvD,CAAC;IACF,aAAa,EAAE,OAAC,CAAC,MAAM,CAAC;QACpB,CAAC,0CAAgB,CAAC,SAAS,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC5D,CAAC,0CAAgB,CAAC,OAAO,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC1D,CAAC,0CAAgB,CAAC,QAAQ,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC3D,CAAC,0CAAgB,CAAC,YAAY,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KAClE,CAAC;IACF,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC;QAClB,CAAC,sCAAc,CAAC,KAAK,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACtD,CAAC,sCAAc,CAAC,GAAG,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACvD,CAAC;CACL,CAAC,CAAC"}

package/build/v1/client-file/upload-magic-bytes.d.ts

@@ -1,22 +1,94 @@
+/**
+ * Content sniffing for uploads: what the BYTES say a file is, as opposed to
+ * what its sender claimed.
+ *
+ * The upload path used to decide entirely on the multipart `Content-Type`
+ * header — a value the client writes itself. That made the allowlist advisory:
+ * `Content-Type: text/plain` on any bytes at all was admitted, and from there
+ * the routing table decided which pipeline received them. Sniffing turns the
+ * declared type into a claim that has to agree with the content.
+ *
+ * Deliberately narrow. It answers "which of the families we accept does this
+ * look like", plus "is this obviously an executable", and returns UNKNOWN for
+ * everything else. It is not a format validator and must not grow into one:
+ * a sniffer that tries to be clever starts accepting things on a guess, which
+ * is the failure it exists to prevent.
+ */
 export declare enum UploadMagicType {
     PNG = "PNG",
     JPEG = "JPEG",
     GIF = "GIF",
     WEBP = "WEBP",
     PDF = "PDF",
+    /** ZIP container. Every OOXML document (docx/xlsx/pptx) is one. */
     ZIP = "ZIP",
+    /** OLE2 compound file — legacy .doc/.xls/.ppt. */
     OLE2 = "OLE2",
     RTF = "RTF",
+    /** Windows PE, ELF, Mach-O, or a shebang script. Never uploadable. */
     EXECUTABLE = "EXECUTABLE",
+    /** No signature matched. Plain text has none, so this is not by itself a verdict. */
     UNKNOWN = "UNKNOWN"
 }
+/** Bytes the classifier needs. OLE2 needs 8; read at least this many. */
 export declare const UPLOAD_MAGIC_PROBE_BYTES = 16;
+/**
+ * Classify a byte prefix. Never guesses: anything unrecognised is UNKNOWN, and
+ * the caller decides what that means for the declared type.
+ */
 export declare function detectUploadMagicType(bytes: Uint8Array): UploadMagicType;
+/**
+ * Signatures a declared content type is allowed to carry.
+ *
+ * A type absent from this map is one whose bytes we cannot verify — plain text,
+ * csv, json, markdown, source code. Those legitimately have no signature, so
+ * the rule for them is inverted: any RECOGNISED signature is a contradiction
+ * (a PDF or a ZIP announced as `text/plain` is not plain text), while UNKNOWN
+ * is expected and fine.
+ */
 export declare const EXPECTED_MAGIC_BY_CONTENT_TYPE: Readonly<Record<string, readonly UploadMagicType[]>>;
+/**
+ * Let the BYTES name the type — but only inside the image family, and only
+ * between types we already accept.
+ *
+ * The case this exists for came from our own pipeline. A KIE CDN served a
+ * generated picture as `Content-Type: image/png` with a WebP body; the
+ * downloader trusted the header, so the object was stored under a `.png` name
+ * and handed to the person that way. Re-uploading it — our own artifact —
+ * failed, because the sniffer correctly saw WebP where PNG was declared. The
+ * same thing happens to any file saved from a site that serves WebP behind a
+ * `.png` URL, which browsers do constantly.
+ *
+ * Why this is not the "trust the payload" mistake the module warns about: it
+ * re-routes NOTHING. All three formats are handled by one image branch, so the
+ * pipeline is identical whichever of them wins. The only things that change are
+ * the stored extension and content type, and they change from wrong to right.
+ * An uploader gains nothing either — they could declare `image/webp` outright.
+ *
+ * Everything else keeps the old rule. A ZIP announced as `text/plain` still
+ * contradicts its declaration, and cross-family correction is exactly where
+ * honouring content over declaration WOULD hand someone a pipeline of their
+ * choosing — the converter that resolves what a document points at.
+ *
+ * Returns the content type the caller should proceed with: the detected one
+ * when both it and the declaration are accepted image types, otherwise the
+ * declaration untouched.
+ */
 export declare function reconcileImageContentType(declaredContentType: string, bytes: Uint8Array): string;
 export declare enum MagicVerdict {
+    /** Bytes match the declared type, or carry no signature where none is expected. */
     OK = "OK",
+    /** Bytes are an executable. Rejected whatever was declared. */
     EXECUTABLE = "EXECUTABLE",
+    /** Bytes contradict the declared type. */
     MISMATCH = "MISMATCH"
 }
+/**
+ * Does the content agree with what the uploader claimed it is.
+ *
+ * A mismatch is a rejection, never a correction. Re-routing a file to the
+ * pipeline its bytes suggest would mean honouring content over declaration —
+ * the same trust-the-payload mistake in a new direction, and it hands the
+ * uploader a way to pick their pipeline by crafting a header.
+ */
 export declare function verifyDeclaredContentType(declaredContentType: string, bytes: Uint8Array): MagicVerdict;