@baruchiro/paperless-mcp 0.5.1 → 2.0.0

package/build/tools/utils/documentQuery.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCUMENT_QUERY_PAPERLESS_FILTER_KEYS = exports.SEARCH_DOCUMENTS_ARGS_SHAPE = exports.QUERY_DOCUMENTS_ARGS_SHAPE = exports.LIST_DOCUMENTS_ARGS_SHAPE = exports.paperlessFiltersSchema = exports.paperlessFilterValueSchema = exports.customFieldQuerySchema = void 0;
+exports.buildDocumentQueryString = buildDocumentQueryString;
+const zod_1 = require("zod");
+const CUSTOM_FIELD_QUERY_GROUP_OPERATORS = ["AND", "OR"];
+const customFieldQueryPrimitiveSchema = zod_1.z.union([
+    zod_1.z.string(),
+    zod_1.z.number(),
+    zod_1.z.boolean(),
+    zod_1.z.null(),
+]);
+const customFieldQueryValueSchema = zod_1.z.union([
+    customFieldQueryPrimitiveSchema,
+    zod_1.z.array(customFieldQueryPrimitiveSchema),
+]);
+function isCustomFieldQueryPrimitive(value) {
+    return (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        value === null);
+}
+function isCustomFieldQueryValue(value) {
+    if (isCustomFieldQueryPrimitive(value)) {
+        return true;
+    }
+    return (Array.isArray(value) && value.every((item) => isCustomFieldQueryPrimitive(item)));
+}
+function isCustomFieldQueryGroupOperator(value) {
+    return (typeof value === "string" &&
+        CUSTOM_FIELD_QUERY_GROUP_OPERATORS.includes(value));
+}
+function isCustomFieldQuery(value) {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    if (value.length === 3 &&
+        (typeof value[0] === "string" || typeof value[0] === "number") &&
+        !isCustomFieldQueryGroupOperator(value[0]) &&
+        typeof value[1] === "string" &&
+        isCustomFieldQueryValue(value[2])) {
+        return true;
+    }
+    if (value.length === 2 &&
+        isCustomFieldQueryGroupOperator(value[0]) &&
+        Array.isArray(value[1]) &&
+        value[1].length >= 1) {
+        return value[1].every((item) => isCustomFieldQuery(item));
+    }
+    return false;
+}
+exports.customFieldQuerySchema = zod_1.z
+    .array(zod_1.z.unknown())
+    .superRefine((value, ctx) => {
+    if (!isCustomFieldQuery(value)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: "Invalid custom_field_query. Use [field_name_or_id, operator, value] or ['AND'|'OR', [clause1, clause2]].",
+        });
+    }
+});
+const paperlessFilterScalarSchema = zod_1.z.union([
+    zod_1.z.string(),
+    zod_1.z.number(),
+    zod_1.z.boolean(),
+]);
+exports.paperlessFilterValueSchema = zod_1.z.union([
+    paperlessFilterScalarSchema,
+    zod_1.z.array(paperlessFilterScalarSchema),
+]);
+exports.paperlessFiltersSchema = zod_1.z.record(exports.paperlessFilterValueSchema);
+const DOCUMENT_QUERY_BASE_ARGS_SHAPE = {
+    page: zod_1.z.number().optional(),
+    page_size: zod_1.z.number().optional(),
+    search: zod_1.z.string().optional(),
+    correspondent: zod_1.z.number().optional(),
+    document_type: zod_1.z.number().optional(),
+    tag: zod_1.z.number().optional(),
+    storage_path: zod_1.z.number().optional(),
+    created__date__gte: zod_1.z.string().optional(),
+    created__date__lte: zod_1.z.string().optional(),
+    ordering: zod_1.z.string().optional(),
+    archive_serial_number: zod_1.z.number().optional(),
+    archive_serial_number__isnull: zod_1.z.boolean().optional(),
+    custom_fields__icontains: zod_1.z.string().min(1).optional(),
+};
+exports.LIST_DOCUMENTS_ARGS_SHAPE = Object.assign(Object.assign({}, DOCUMENT_QUERY_BASE_ARGS_SHAPE), { custom_field_query: zod_1.z.string().min(1).optional() });
+exports.QUERY_DOCUMENTS_ARGS_SHAPE = Object.assign(Object.assign({}, DOCUMENT_QUERY_BASE_ARGS_SHAPE), { query: zod_1.z.string().optional(), more_like_id: zod_1.z.number().optional(), custom_field_query: exports.customFieldQuerySchema
+        .optional()
+        .describe("Paperless custom field query. Use [field_name_or_id, operator, value] for a single clause or ['AND'|'OR', [clause1, clause2]] for grouped clauses."), paperless_filters: exports.paperlessFiltersSchema
+        .optional()
+        .describe("Additional documented /api/documents/ Paperless filters. Keys must match Paperless query parameter names exactly. Prefer first-class arguments when available.") });
+exports.SEARCH_DOCUMENTS_ARGS_SHAPE = {
+    query: zod_1.z.string(),
+};
+const FIRST_CLASS_QUERY_PARAM_MAP = {
+    page: "page",
+    page_size: "page_size",
+    ordering: "ordering",
+    query: "query",
+    search: "search",
+    more_like_id: "more_like_id",
+    correspondent: "correspondent__id",
+    document_type: "document_type__id",
+    tag: "tags__id",
+    storage_path: "storage_path__id",
+    created__date__gte: "created__date__gte",
+    created__date__lte: "created__date__lte",
+    archive_serial_number: "archive_serial_number",
+    archive_serial_number__isnull: "archive_serial_number__isnull",
+    custom_fields__icontains: "custom_fields__icontains",
+};
+// Derived from the documented /api/documents/ query parameters in Paperless_ngx_REST_API.yaml.
+exports.DOCUMENT_QUERY_PAPERLESS_FILTER_KEYS = [
+    "added__date__gt",
+    "added__date__gte",
+    "added__date__lt",
+    "added__date__lte",
+    "added__day",
+    "added__gt",
+    "added__gte",
+    "added__lt",
+    "added__lte",
+    "added__month",
+    "added__year",
+    "archive_serial_number",
+    "archive_serial_number__gt",
+    "archive_serial_number__gte",
+    "archive_serial_number__isnull",
+    "archive_serial_number__lt",
+    "archive_serial_number__lte",
+    "checksum__icontains",
+    "checksum__iendswith",
+    "checksum__iexact",
+    "checksum__istartswith",
+    "content__icontains",
+    "content__iendswith",
+    "content__iexact",
+    "content__istartswith",
+    "correspondent__id",
+    "correspondent__id__in",
+    "correspondent__id__none",
+    "correspondent__isnull",
+    "correspondent__name__icontains",
+    "correspondent__name__iendswith",
+    "correspondent__name__iexact",
+    "correspondent__name__istartswith",
+    "created__date__gt",
+    "created__date__gte",
+    "created__date__lt",
+    "created__date__lte",
+    "created__day",
+    "created__gt",
+    "created__gte",
+    "created__lt",
+    "created__lte",
+    "created__month",
+    "created__year",
+    "custom_field_query",
+    "custom_fields__icontains",
+    "custom_fields__id__all",
+    "custom_fields__id__in",
+    "custom_fields__id__none",
+    "document_type__id",
+    "document_type__id__in",
+    "document_type__id__none",
+    "document_type__isnull",
+    "document_type__name__icontains",
+    "document_type__name__iendswith",
+    "document_type__name__iexact",
+    "document_type__name__istartswith",
+    "fields",
+    "full_perms",
+    "has_custom_fields",
+    "id",
+    "id__in",
+    "is_in_inbox",
+    "is_tagged",
+    "mime_type",
+    "modified__date__gt",
+    "modified__date__gte",
+    "modified__date__lt",
+    "modified__date__lte",
+    "modified__day",
+    "modified__gt",
+    "modified__gte",
+    "modified__lt",
+    "modified__lte",
+    "modified__month",
+    "modified__year",
+    "ordering",
+    "original_filename__icontains",
+    "original_filename__iendswith",
+    "original_filename__iexact",
+    "original_filename__istartswith",
+    "owner__id",
+    "owner__id__in",
+    "owner__id__none",
+    "owner__isnull",
+    "page",
+    "page_size",
+    "query",
+    "search",
+    "shared_by__id",
+    "storage_path__id",
+    "storage_path__id__in",
+    "storage_path__id__none",
+    "storage_path__isnull",
+    "storage_path__name__icontains",
+    "storage_path__name__iendswith",
+    "storage_path__name__iexact",
+    "storage_path__name__istartswith",
+    "tags__id",
+    "tags__id__all",
+    "tags__id__in",
+    "tags__id__none",
+    "tags__name__icontains",
+    "tags__name__iendswith",
+    "tags__name__iexact",
+    "tags__name__istartswith",
+    "title__icontains",
+    "title__iendswith",
+    "title__iexact",
+    "title__istartswith",
+    "title_content",
+];
+const DOCUMENT_QUERY_PAPERLESS_FILTER_KEY_SET = new Set(exports.DOCUMENT_QUERY_PAPERLESS_FILTER_KEYS);
+function hasValue(value) {
+    return value !== undefined && value !== null;
+}
+function setQueryParam(query, key, value, jsonEncode = false) {
+    if (jsonEncode) {
+        query.set(key, JSON.stringify(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        query.set(key, value.map((item) => String(item)).join(","));
+        return;
+    }
+    query.set(key, String(value));
+}
+function buildDocumentQueryString(args) {
+    const query = new URLSearchParams();
+    const firstClassKeys = new Set();
+    for (const [argName, queryParamName] of Object.entries(FIRST_CLASS_QUERY_PARAM_MAP)) {
+        const value = args[argName];
+        if (!hasValue(value)) {
+            continue;
+        }
+        setQueryParam(query, queryParamName, value);
+        firstClassKeys.add(queryParamName);
+    }
+    if (hasValue(args.custom_field_query)) {
+        setQueryParam(query, "custom_field_query", args.custom_field_query, typeof args.custom_field_query !== "string");
+        firstClassKeys.add("custom_field_query");
+    }
+    if (!args.paperless_filters) {
+        return query.toString() ? `?${query.toString()}` : "";
+    }
+    for (const [key, value] of Object.entries(args.paperless_filters)) {
+        if (!DOCUMENT_QUERY_PAPERLESS_FILTER_KEY_SET.has(key)) {
+            throw new Error(`Unsupported paperless_filters key '${key}'. Use documented /api/documents/ query parameter names only.`);
+        }
+        if (firstClassKeys.has(key)) {
+            throw new Error(`Duplicate filter '${key}' provided both as a first-class argument and in paperless_filters.`);
+        }
+        setQueryParam(query, key, value);
+    }
+    return query.toString() ? `?${query.toString()}` : "";
+}

package/build/tools/utils/resourceUri.d.ts

@@ -1,21 +1,26 @@
 /**
  * Resource URI builders for document/thumbnail downloads.
  *
- * URIs mirror the Paperless REST API paths under a custom `paperless://`
- * scheme, so the same identifiers can later back proper MCP resources
- * (`resources/list` / `resources/read`) without a second naming scheme.
+ * URIs mirror document resources under a custom `paperless://` scheme, so the
+ * same identifiers can back MCP resources (`resources/list` / `resources/read`)
+ * without a second naming scheme.
  *
  * The scheme also keeps the URI well-formed regardless of filename
  * content, which Python MCP clients (pydantic-validated) require.
  */
+/**
+ * Optional flags for document download resource URIs.
+ */
+export interface DocumentResourceUriOptions {
+    original?: boolean;
+}
 /**
  * Builds a resource URI for a downloaded document.
  *
- * Mirrors `GET /api/documents/{id}/download/`. The original filename is
- * preserved as a `filename` query parameter (URL-encoded) so clients
- * that need the human-readable name can still recover it.
+ * The MCP resource URI is intentionally canonical and filename-free; filenames
+ * belong in resource metadata, while the URI identifies the fetchable content.
  */
-export declare function buildDocumentResourceUri(id: number, filename: string): string;
+export declare function buildDocumentResourceUri(id: number, optionsOrFilename?: DocumentResourceUriOptions | string): string;
 /**
  * Builds a resource URI for a document thumbnail.
  *

package/build/tools/utils/resourceUri.js

@@ -2,9 +2,9 @@
 /**
  * Resource URI builders for document/thumbnail downloads.
  *
- * URIs mirror the Paperless REST API paths under a custom `paperless://`
- * scheme, so the same identifiers can later back proper MCP resources
- * (`resources/list` / `resources/read`) without a second naming scheme.
+ * URIs mirror document resources under a custom `paperless://` scheme, so the
+ * same identifiers can back MCP resources (`resources/list` / `resources/read`)
+ * without a second naming scheme.
  *
  * The scheme also keeps the URI well-formed regardless of filename
  * content, which Python MCP clients (pydantic-validated) require.
@@ -15,12 +15,17 @@ exports.buildThumbnailResourceUri = buildThumbnailResourceUri;
 /**
  * Builds a resource URI for a downloaded document.
  *
- * Mirrors `GET /api/documents/{id}/download/`. The original filename is
- * preserved as a `filename` query parameter (URL-encoded) so clients
- * that need the human-readable name can still recover it.
+ * The MCP resource URI is intentionally canonical and filename-free; filenames
+ * belong in resource metadata, while the URI identifies the fetchable content.
  */
-function buildDocumentResourceUri(id, filename) {
-    return `paperless://documents/${id}/download?filename=${encodeURIComponent(filename)}`;
+function buildDocumentResourceUri(id, optionsOrFilename) {
+    const options = typeof optionsOrFilename === "string" ? {} : optionsOrFilename || {};
+    const params = new URLSearchParams();
+    if (options.original) {
+        params.set("original", "true");
+    }
+    const query = params.toString();
+    return `paperless://documents/${id}/download${query ? `?${query}` : ""}`;
 }
 /**
  * Builds a resource URI for a document thumbnail.

package/build/tools/utils/resourceUri.test.js

@@ -10,32 +10,32 @@ const resourceUri_1 = require("./resourceUri");
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "doc.pdf");
     strict_1.default.match(uri, /^paperless:\/\/documents\/1\/download(\?|$)/);
 });
-(0, node_test_1.test)("buildDocumentResourceUri puts the filename in a query parameter", () => {
+(0, node_test_1.test)("buildDocumentResourceUri is canonical without filenames", () => {
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "invoice 2026.pdf");
-    strict_1.default.equal(uri, "paperless://documents/1/download?filename=invoice%202026.pdf");
+    strict_1.default.equal(uri, "paperless://documents/1/download");
 });
-(0, node_test_1.test)("buildDocumentResourceUri encodes RFC-3986 reserved chars in the filename", () => {
+(0, node_test_1.test)("buildDocumentResourceUri ignores reserved chars in legacy filename input", () => {
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(42, "weird ?#&=+name.pdf");
     const url = new URL(uri);
-    // The path stays canonical — only the literal `?` that separates
-    // path from query is allowed; nothing from the filename should
-    // bleed into the path or break query parsing.
     strict_1.default.equal(url.pathname, "/42/download");
-    strict_1.default.equal(url.searchParams.get("filename"), "weird ?#&=+name.pdf");
+    strict_1.default.equal(url.search, "");
 });
-(0, node_test_1.test)("buildDocumentResourceUri encodes path separators inside filename", () => {
+(0, node_test_1.test)("buildDocumentResourceUri ignores path separators in legacy filename input", () => {
     // A filename containing a slash must not become an extra path segment.
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(7, "sub/dir/file.pdf");
     const url = new URL(uri);
     strict_1.default.equal(url.pathname, "/7/download");
-    strict_1.default.equal(url.searchParams.get("filename"), "sub/dir/file.pdf");
+    strict_1.default.equal(url.search, "");
 });
-(0, node_test_1.test)("buildDocumentResourceUri preserves unicode filenames", () => {
+(0, node_test_1.test)("buildDocumentResourceUri keeps unicode filenames out of the URI", () => {
     const original = "Rechnüng — März.pdf";
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, original);
-    // Roundtrip via URL parsing should recover the original name.
     const url = new URL(uri);
-    strict_1.default.equal(url.searchParams.get("filename"), original);
+    strict_1.default.equal(url.pathname, "/1/download");
+    strict_1.default.equal(url.search, "");
+});
+(0, node_test_1.test)("buildDocumentResourceUri preserves original download intent", () => {
+    strict_1.default.equal((0, resourceUri_1.buildDocumentResourceUri)(1, { original: true }), "paperless://documents/1/download?original=true");
 });
 (0, node_test_1.test)("buildDocumentResourceUri produces a valid URL", () => {
     const uri = (0, resourceUri_1.buildDocumentResourceUri)(1, "Some File.pdf");

package/build/tools/utils/selectFields.d.ts

@@ -0,0 +1,11 @@
+import { PaperlessAPI } from "../../api/PaperlessAPI";
+import { CustomField, CustomFieldInstanceRequest, CustomFieldValue } from "../../api/types";
+/**
+ * Encoding Paperless expects for a select value: `update_document` takes the
+ * option index; `bulk_edit` writes `value_select` directly so it needs the
+ * stored form (option id on 2.17+, index on pre-2.17 string options).
+ */
+export type SelectValueEncoding = "index" | "stored";
+/** Translates a select value (label, option id, or index) to the `encoding` Paperless expects; throws on no match. */
+export declare function resolveSelectCustomFieldValue(field: CustomField, value: CustomFieldValue, encoding?: SelectValueEncoding): CustomFieldValue;
+export declare function resolveSelectCustomFieldValues(api: PaperlessAPI, customFields: CustomFieldInstanceRequest[] | undefined, encoding?: SelectValueEncoding): Promise<CustomFieldInstanceRequest[] | undefined>;

package/build/tools/utils/selectFields.js

@@ -0,0 +1,91 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSelectCustomFieldValue = resolveSelectCustomFieldValue;
+exports.resolveSelectCustomFieldValues = resolveSelectCustomFieldValues;
+function normalizeSelectOptions(field) {
+    var _a;
+    const rawOptions = (_a = field.extra_data) === null || _a === void 0 ? void 0 : _a.select_options;
+    if (!Array.isArray(rawOptions)) {
+        return [];
+    }
+    return rawOptions.map((option, index) => {
+        if (option && typeof option === "object") {
+            const { id, label } = option;
+            return {
+                index,
+                label: typeof label === "string" ? label : String(label),
+                id: typeof id === "string" ? id : undefined,
+            };
+        }
+        return { index, label: String(option) };
+    });
+}
+function findSelectOption(options, value) {
+    if (typeof value === "string") {
+        const byLabel = options.find((option) => option.label === value);
+        const byId = options.find((option) => option.id === value);
+        if (byLabel && byId && byLabel.index !== byId.index) {
+            throw new Error(`Ambiguous select value ${JSON.stringify(value)}: it matches one ` +
+                `option's label and a different option's id.`);
+        }
+        return byLabel !== null && byLabel !== void 0 ? byLabel : byId;
+    }
+    if (typeof value === "number" && Number.isInteger(value)) {
+        return options.find((option) => option.index === value);
+    }
+    return undefined;
+}
+/** Translates a select value (label, option id, or index) to the `encoding` Paperless expects; throws on no match. */
+function resolveSelectCustomFieldValue(field, value, encoding = "index") {
+    var _a;
+    if (field.data_type !== "select" || value === null) {
+        return value;
+    }
+    const options = normalizeSelectOptions(field);
+    if (options.length === 0) {
+        return value;
+    }
+    const option = findSelectOption(options, value);
+    if (!option) {
+        const optionList = options
+            .map((o) => `${JSON.stringify(o.label)} (index ${o.index})`)
+            .join(", ");
+        throw new Error(`Invalid value ${JSON.stringify(value)} for select custom field ` +
+            `"${field.name}" (id ${field.id}). Pass one of the option labels. ` +
+            `Valid options: ${optionList}.`);
+    }
+    return encoding === "stored" ? (_a = option.id) !== null && _a !== void 0 ? _a : option.index : option.index;
+}
+function resolveSelectCustomFieldValues(api_1, customFields_1) {
+    return __awaiter(this, arguments, void 0, function* (api, customFields, encoding = "index") {
+        if (!customFields || customFields.length === 0) {
+            return customFields;
+        }
+        const uniqueFieldIds = [...new Set(customFields.map((cf) => cf.field))];
+        const definitions = new Map();
+        yield Promise.all(uniqueFieldIds.map((id) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                definitions.set(id, yield api.getCustomField(id));
+            }
+            catch (_a) {
+                // Definition unavailable; leave the value for Paperless to validate.
+            }
+        })));
+        return customFields.map((cf) => {
+            const field = definitions.get(cf.field);
+            if (!field || field.data_type !== "select") {
+                return cf;
+            }
+            return Object.assign(Object.assign({}, cf), { value: resolveSelectCustomFieldValue(field, cf.value, encoding) });
+        });
+    });
+}

package/build/tools/utils/selectFields.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/utils/selectFields.test.js

@@ -0,0 +1,164 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const selectFields_1 = require("./selectFields");
+const LEGACY_SELECT_FIELD = {
+    id: 2,
+    name: "Retention period",
+    data_type: "select",
+    extra_data: { select_options: ["1 year", "7 years", "2 years"], default_currency: null },
+    document_count: 10,
+};
+const OBJECT_SELECT_FIELD = {
+    id: 3,
+    name: "Priority",
+    data_type: "select",
+    extra_data: {
+        select_options: [
+            { id: "abc123", label: "Low" },
+            { id: "def456", label: "High" },
+        ],
+    },
+    document_count: 5,
+};
+const STRING_FIELD = {
+    id: 4,
+    name: "Reference",
+    data_type: "string",
+    document_count: 1,
+};
+(0, node_test_1.describe)("resolveSelectCustomFieldValue", () => {
+    (0, node_test_1.test)("translates a label to its zero-based index (pre-2.17 string options)", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "1 year"), 0);
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "7 years"), 1);
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "2 years"), 2);
+    });
+    (0, node_test_1.test)("translates a label to its zero-based index (2.17+ object options)", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "Low"), 0);
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "High"), 1);
+    });
+    (0, node_test_1.test)("passes through an already-encoded index (pre-2.17)", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, 1), 1);
+    });
+    (0, node_test_1.test)("maps an option id back to its zero-based index (2.17+ round-trip)", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "def456"), 1);
+    });
+    (0, node_test_1.test)("resolves both the label and the option id to the same index", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "Low"), 0);
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "abc123"), 0);
+    });
+    (0, node_test_1.test)("returns null unchanged so the field can be cleared", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, null), null);
+    });
+    (0, node_test_1.test)("leaves non-select field values untouched", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(STRING_FIELD, "1 year"), "1 year");
+    });
+    (0, node_test_1.test)("throws an actionable error listing valid options for an unknown value", () => {
+        strict_1.default.throws(() => (0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "forever"), (err) => {
+            strict_1.default.match(err.message, /forever/);
+            strict_1.default.match(err.message, /Retention period/);
+            strict_1.default.match(err.message, /1 year/);
+            strict_1.default.match(err.message, /7 years/);
+            return true;
+        });
+    });
+    (0, node_test_1.test)("rejects an out-of-range index rather than forwarding it", () => {
+        strict_1.default.throws(() => (0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, 9));
+    });
+    (0, node_test_1.test)("throws on a value that matches one option's label and another's id", () => {
+        const collidingField = {
+            id: 5,
+            name: "Collision",
+            data_type: "select",
+            extra_data: {
+                select_options: [
+                    { id: "High", label: "Low" },
+                    { id: "xyz789", label: "High" },
+                ],
+            },
+            document_count: 0,
+        };
+        strict_1.default.throws(() => (0, selectFields_1.resolveSelectCustomFieldValue)(collidingField, "High"), /Ambiguous/);
+    });
+});
+(0, node_test_1.describe)("resolveSelectCustomFieldValue with stored encoding (bulk_edit path)", () => {
+    (0, node_test_1.test)("translates a label to the option id on 2.17+ object options", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "Low", "stored"), "abc123");
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "High", "stored"), "def456");
+    });
+    (0, node_test_1.test)("translates a label to the index on pre-2.17 string options (no id to store)", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(LEGACY_SELECT_FIELD, "7 years", "stored"), 1);
+    });
+    (0, node_test_1.test)("passes an already-stored option id through unchanged", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, "def456", "stored"), "def456");
+    });
+    (0, node_test_1.test)("maps an option index to its stored id (2.17+)", () => {
+        strict_1.default.equal((0, selectFields_1.resolveSelectCustomFieldValue)(OBJECT_SELECT_FIELD, 1, "stored"), "def456");
+    });
+});
+function apiReturning(fields) {
+    const requestedIds = [];
+    const fieldMap = new Map(fields.map((field) => [field.id, field]));
+    const api = {
+        getCustomField: (id) => __awaiter(this, void 0, void 0, function* () {
+            requestedIds.push(id);
+            const field = fieldMap.get(id);
+            if (!field)
+                throw new Error(`custom field ${id} not found`);
+            return field;
+        }),
+    };
+    return { api, requestedIds };
+}
+(0, node_test_1.describe)("resolveSelectCustomFieldValues", () => {
+    (0, node_test_1.test)("returns undefined/empty input unchanged without fetching definitions", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, requestedIds } = apiReturning([]);
+        strict_1.default.equal(yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, undefined), undefined);
+        strict_1.default.deepEqual(yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, []), []);
+        strict_1.default.deepEqual(requestedIds, []);
+    }));
+    (0, node_test_1.test)("resolves select labels and leaves other fields untouched", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api } = apiReturning([LEGACY_SELECT_FIELD, STRING_FIELD]);
+        const resolved = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [
+            { field: 2, value: "2 years" },
+            { field: 4, value: "INV-001" },
+        ]);
+        strict_1.default.deepEqual(resolved, [
+            { field: 2, value: 2 },
+            { field: 4, value: "INV-001" },
+        ]);
+    }));
+    (0, node_test_1.test)("applies the stored encoding (option id) when requested", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api } = apiReturning([OBJECT_SELECT_FIELD]);
+        const resolved = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [{ field: 3, value: "High" }], "stored");
+        strict_1.default.deepEqual(resolved, [{ field: 3, value: "def456" }]);
+    }));
+    (0, node_test_1.test)("fetches each referenced field definition only once", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api, requestedIds } = apiReturning([LEGACY_SELECT_FIELD]);
+        yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [
+            { field: 2, value: "1 year" },
+            { field: 2, value: "7 years" },
+        ]);
+        strict_1.default.deepEqual(requestedIds, [2]);
+    }));
+    (0, node_test_1.test)("passes the value through when the field definition cannot be fetched", () => __awaiter(void 0, void 0, void 0, function* () {
+        const { api } = apiReturning([]);
+        const resolved = yield (0, selectFields_1.resolveSelectCustomFieldValues)(api, [
+            { field: 99, value: "whatever" },
+        ]);
+        strict_1.default.deepEqual(resolved, [{ field: 99, value: "whatever" }]);
+    }));
+});