@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/resources/resources-config.shared.schemas.js

@@ -21,6 +21,17 @@ import { z } from 'zod';
 export const DEFAULT_LIST_PAGE_CEILING = 100;
 /** SEARCH ceilings are lower on purpose: a search page is scored and ranked, not scanned. */
 export const DEFAULT_SEARCH_PAGE_CEILING = 50;
+/**
+ * One schema per page ceiling, shared by every operation that declares it (#1587).
+ *
+ * Both pagination factories are pure functions of `maxLimit`, and the DTO builder called the
+ * response one for every collection operation and variant, building an identical four-field object
+ * each time. Zod 4 classic installs ~40 closures on every instance, so the duplicates were a
+ * measurable share of a resource registry's heap. A Zod schema is immutable, and nothing writes to
+ * these after they are built, so one instance per ceiling serves them all.
+ */
+const PAGINATION_RESPONSE_METADATA_SCHEMA_BY_CEILING = new Map();
+const PAGINATION_REQUEST_SCHEMA_BY_CEILING = new Map();
 /**
  * The pagination block a collection RESPONSE echoes back, bounded by the operation's ceiling.
  *
@@ -36,12 +47,17 @@ export const DEFAULT_SEARCH_PAGE_CEILING = 50;
  * governs" — and a fix applied to fewer than all of them just moves which layer says no.
  */
 export function createPaginationResponseMetadataSchema(maxLimit = DEFAULT_LIST_PAGE_CEILING) {
-    return z.object({
+    const cached = PAGINATION_RESPONSE_METADATA_SCHEMA_BY_CEILING.get(maxLimit);
+    if (cached !== undefined)
+        return cached;
+    const built = z.object({
         page: z.number().min(1).default(1),
         limit: z.number().min(1).max(maxLimit).default(20),
         total: z.number().min(0),
         totalPages: z.number().min(0)
     });
+    PAGINATION_RESPONSE_METADATA_SCHEMA_BY_CEILING.set(maxLimit, built);
+    return built;
 }
 /** The default-bounded response metadata. Prefer {@link createPaginationResponseMetadataSchema} where the ceiling is known. */
 export const Resources_PaginationResponseMetadataSchema = createPaginationResponseMetadataSchema();
@@ -57,10 +73,15 @@ export const Resources_PaginationResponseMetadataSchema = createPaginationRespon
  * `maxLimit` defaults to 100 so every existing caller keeps its current contract.
  */
 export function createPaginationRequestSchema(maxLimit = DEFAULT_LIST_PAGE_CEILING) {
-    return z.object({
+    const cached = PAGINATION_REQUEST_SCHEMA_BY_CEILING.get(maxLimit);
+    if (cached !== undefined)
+        return cached;
+    const built = z.object({
         page: z.number().min(1).default(1),
         limit: z.number().min(1).max(maxLimit).default(20)
     });
+    PAGINATION_REQUEST_SCHEMA_BY_CEILING.set(maxLimit, built);
+    return built;
 }
 /** The default-bounded pagination block. Prefer {@link createPaginationRequestSchema} where the operation's ceiling is known. */
 export const Resources_PaginationRequestSchema = createPaginationRequestSchema();
@@ -354,8 +375,8 @@ export var SortOrder;
     SortOrder["DESC"] = "desc";
 })(SortOrder || (SortOrder = {}));
 export const Resources_Filter_DateRangeSchema = z.object({
-    startDate: z.date().optional(),
-    endDate: z.date().optional()
+    startDate: z.date().optional().describe('The earliest date and time to include, inclusive. Omit for no lower bound.'),
+    endDate: z.date().optional().describe('The latest date and time to include, inclusive. Omit for no upper bound.'),
 });
 /**
  * A NUMERIC BOUND PAIR — the number sibling of {@link Resources_Filter_DateRangeSchema}, and the
@@ -406,6 +427,97 @@ export function isResourcesFilterNumberRangeSchema(schema) {
     return keys.length === RESOURCES_FILTER_NUMBER_RANGE_SUBKEYS.length
         && keys.every((key) => RESOURCES_FILTER_NUMBER_RANGE_SUBKEYS.includes(key));
 }
+/**
+ * The target field of every presence filter, keyed by the exact schema object an author declared.
+ *
+ * A WeakMap rather than Zod metadata: `.describe()` and `.meta()` each REPLACE a schema's registry
+ * entry, so a target stored there would be lost the moment anything described the schema. The
+ * translation reads the operation's DECLARED `filterFields` — the objects this map was keyed with —
+ * never the request schema the factory derives from them, so the derived `.optional()` copies do not
+ * need to carry it.
+ */
+const RESOURCES_FILTER_PRESENCE_TARGETS = new WeakMap();
+/**
+ * A boolean filter that asks whether ANOTHER field is set (#1806).
+ *
+ * `hasExpiration` on the API-key and OAuth-client searches was declared as a plain `z.boolean()` and
+ * passed to the database verbatim, where no row has a `hasExpiration` field — so it matched nothing,
+ * with no error to say so. Its meaning was "is `expiresAt` set", and nothing said that anywhere a
+ * machine could read.
+ *
+ * Declare it with the field it asks about:
+ *
+ * ```ts
+ * filterFields: { hasExpiration: createResourcesFilterPresenceSchema('expiresAt') }
+ * ```
+ *
+ * On the wire it is still a plain boolean — the request schema, the published query parameter, MCP and
+ * the filter panel see `z.boolean()` — and {@link translateResourcesPresenceFilters} turns it into a
+ * condition on the target before the filter reaches a repository: `true` → set (`{ $ne: null }`),
+ * `false` → not set (`null`). Those two forms, not `$exists`, because they give the same answer on
+ * both adapters: on MongoDB `$exists: true` also matches a stored `null`, and on PostgreSQL a stored
+ * `null` is `IS NULL`.
+ *
+ * The factory refuses a presence filter whose target is not a field of the resource, exactly as it
+ * refuses a filter key that is not one.
+ *
+ * Call it once per declaration and do not chain onto the result: the target is attached to the exact
+ * object returned, and `.describe()` / `.optional()` return new objects that do not carry it.
+ */
+export function createResourcesFilterPresenceSchema(targetField) {
+    const schema = z
+        .boolean()
+        .describe(`\`true\` returns only the records where \`${targetField}\` is set; \`false\` only the records where it is not.`);
+    RESOURCES_FILTER_PRESENCE_TARGETS.set(schema, targetField);
+    return schema;
+}
+/** The field a presence filter asks about, or `undefined` when `schema` is not a presence filter. */
+export function getResourcesFilterPresenceTarget(schema) {
+    return schema !== null && typeof schema === 'object' ? RESOURCES_FILTER_PRESENCE_TARGETS.get(schema) : undefined;
+}
+/** Every field a presence filter in `filterFields` asks about — the keys a translated filter may carry. */
+export function resourcesFilterPresenceTargets(filterFields) {
+    return Object.values(filterFields ?? {})
+        .map((schema) => getResourcesFilterPresenceTarget(schema))
+        .filter((target) => target !== undefined);
+}
+/**
+ * Replace each presence filter in `filter` with the condition it stands for (see
+ * {@link createResourcesFilterPresenceSchema}).
+ *
+ * Accepts the boolean and its query-string spelling (`'true'` / `'false'`), because a GET collection
+ * query carries raw strings and the collection controller does not coerce them. Any other value is
+ * DROPPED, which is how the collection filter guard already treats a value it does not admit.
+ *
+ * Idempotent — a translated filter no longer carries the presence key, so running it again changes
+ * nothing — which is what lets both the collection controller and each repository's filter sanitizer
+ * call it. When the target already has a condition, the presence condition joins it under `$and`
+ * rather than replacing it.
+ */
+export function translateResourcesPresenceFilters(filter, filterFields) {
+    if (!filter || typeof filter !== 'object' || !filterFields)
+        return filter;
+    let out;
+    for (const [key, schema] of Object.entries(filterFields)) {
+        const target = getResourcesFilterPresenceTarget(schema);
+        if (target === undefined || !(key in filter))
+            continue;
+        out ??= { ...filter };
+        const value = out[key];
+        delete out[key];
+        const present = value === true || value === 'true' ? true : value === false || value === 'false' ? false : undefined;
+        if (present === undefined)
+            continue;
+        const condition = present ? { $ne: null } : null;
+        if (target in out) {
+            out.$and = [...(Array.isArray(out.$and) ? out.$and : []), { [target]: condition }];
+        }
+        else {
+            out[target] = condition;
+        }
+    }
+    return out ?? filter;
+}
 export const Resources_Filter_BaseSchema = z.object({
     searchRequest: z.string().optional(),
     createdAt: Resources_Filter_DateRangeSchema.optional(),
@@ -476,6 +588,15 @@ export var ResourceCollectionExportFormat;
      * types intact. Choose this when the export feeds another system rather than a human.
      */
     ResourceCollectionExportFormat["JSON"] = "json";
+    /**
+     * A DOCUMENT for a person to read, print or send — the rows rendered through a PDF template the
+     * backend binds by {@link ResourceCollectionExportConfig.pdfTemplateId} (#1645).
+     *
+     * Unlike CSV and JSON it is not a copy of the rows: the template decides what is shown and how, so
+     * a declaration must name one. The template receives exactly the rows the listing returns, under the
+     * same access rules, so it cannot show more than the caller could read.
+     */
+    ResourceCollectionExportFormat["PDF"] = "pdf";
 })(ResourceCollectionExportFormat || (ResourceCollectionExportFormat = {}));
 /**
  * WHICH rows a collection export contains.
@@ -501,7 +622,7 @@ export var ResourceCollectionExportRowScope;
     ResourceCollectionExportRowScope["FULL_RESULT_SET"] = "full_result_set";
 })(ResourceCollectionExportRowScope || (ResourceCollectionExportRowScope = {}));
 /**
- * Opt a LIST/SEARCH operation into CSV/JSON export of its own result set.
+ * Opt a LIST/SEARCH operation into CSV, JSON or PDF export of its own result set.
  *
  * ## What declaring this does
  *
@@ -533,7 +654,7 @@ export var ResourceCollectionExportRowScope;
 /**
  * What a collection-export route answers with, described for specs and OpenAPI.
  *
- * ⚠️ The BODY is the exported FILE — a CSV or JSON byte stream, not this object. The controller owns
+ * ⚠️ The BODY is the exported FILE — a CSV, JSON or PDF byte stream, not this object. The controller owns
  * the response for this operation family and streams it, so nothing ever serialises this schema.
  * What it documents is the METADATA CONTRACT, which rides in response headers beside the bytes:
  * `Content-Type`, `Content-Disposition` (carrying the filename) and `X-Wildo-Export-Row-Count`.
@@ -543,11 +664,11 @@ export var ResourceCollectionExportRowScope;
  */
 export const ResourceCollectionExportResponseSchema = z.object({
     /** Mirrors the `filename=` of the `Content-Disposition` header. */
-    filename: z.string(),
-    /** Mirrors `Content-Type`: `text/csv` or `application/json`. */
-    contentType: z.string(),
+    filename: z.string().describe("The downloaded file's name, sent in the `Content-Disposition` header. The response body is the exported file itself, not a JSON object."),
+    /** Mirrors `Content-Type`: `text/csv`, `application/json` or `application/pdf`. */
+    contentType: z.string().describe("The file's format, sent as the `Content-Type` header: `text/csv`, `application/json` or `application/pdf`."),
     /** Mirrors `X-Wildo-Export-Row-Count` — the number of rows actually written. */
-    rowCount: z.number().int().nonnegative(),
+    rowCount: z.number().int().nonnegative().describe("How many rows the file holds, sent in the `X-Wildo-Export-Row-Count` header."),
 });
 /** Runtime guard distinguishing a relational descriptor from an own-field name. */
 export function isSearchableRelationDescriptor(field) {
@@ -589,6 +710,19 @@ export const BULK_OPERATION_SELECTOR_FIELD = '_ids';
  * never written.
  */
 export const BULK_OPERATION_MATCH_FIELD = '_match';
+/**
+ * Every request key the COLLECTION fills for a bulk action — the two selectors — and therefore never
+ * a field a person fills in the action's form.
+ *
+ * One list, because the form hides these keys, the presentation ladder does not count them, and the
+ * execution merge writes them. When only `_ids` was hidden, the bulk "Change status" dialog rendered
+ * `_match` as three empty inputs (Match / Filters / Search) and submitted `_match: {}` — an empty
+ * query that replaced the listing the person had selected from (#1461, #2035 run 2026-09-30).
+ */
+export const BULK_OPERATION_HOST_SUPPLIED_FIELDS = [
+    BULK_OPERATION_SELECTOR_FIELD,
+    BULK_OPERATION_MATCH_FIELD,
+];
 export const BULK_OPERATION_DEFAULT_MAX_SELECTION = 100;
 /**
  * How many rows a BACKGROUND bulk run may be given, when the operation declares a non-inline runtime.
@@ -632,13 +766,13 @@ export function resolveBulkOperationMaxSelection(operation) {
  */
 export const Resources_BulkOperationMatchSelectorSchema = z.object({
     /** The listing's filters, as the LIST request carried them. Re-parsed server-side per resource. */
-    filters: z.record(z.string(), z.unknown()).optional(),
+    filters: z.record(z.string(), z.unknown()).optional().describe("The listing's filters, as its list request sends them. They are checked against this resource's list filters."),
     /** The listing's free-text search, when one was active. */
-    search: z.string().min(1).optional(),
+    search: z.string().min(1).optional().describe("The listing's free-text search, when one was active."),
 });
 export const Resources_BulkOperationBaseSchema = z.object({
-    _ids: z.array(z.string().min(1)).min(1).max(BULK_OPERATION_DEFAULT_MAX_SELECTION).optional(),
-    _match: Resources_BulkOperationMatchSelectorSchema.optional(),
+    _ids: z.array(z.string().min(1)).min(1).max(BULK_OPERATION_DEFAULT_MAX_SELECTION).optional().describe("The ids of the records to act on. Give either `_ids` or `_match`, not both."),
+    _match: Resources_BulkOperationMatchSelectorSchema.optional().describe("Act on every record a listing returns rather than on named ids: the listing's filters and search. The server runs this resource's list with them in the caller's scope, so it reaches only records the caller could list. Give either `_ids` or `_match`, not both."),
 });
 /**
  * The bulk selector schema for a given limit — what an operation declaring its own limit is built with.
@@ -656,8 +790,8 @@ export const Resources_BulkOperationBaseSchema = z.object({
  */
 export function buildBulkOperationSelectorSchema(maxSelection) {
     return z.object({
-        _ids: z.array(z.string().min(1)).min(1).max(maxSelection).optional(),
-        _match: Resources_BulkOperationMatchSelectorSchema.optional(),
+        _ids: z.array(z.string().min(1)).min(1).max(maxSelection).optional().describe("The ids of the records to act on. Give either `_ids` or `_match`, not both."),
+        _match: Resources_BulkOperationMatchSelectorSchema.optional().describe("Act on every record a listing returns rather than on named ids: the listing's filters and search. The server runs this resource's list with them in the caller's scope, so it reaches only records the caller could list. Give either `_ids` or `_match`, not both."),
     });
 }
 /**
@@ -778,7 +912,7 @@ export function stripBulkOperationSelector(payload) {
 export var ResourceGeneratedOperationKind;
 (function (ResourceGeneratedOperationKind) {
     ResourceGeneratedOperationKind["GENERATED_FILE_REGENERATE"] = "generated_file_regenerate";
-    /** The CSV/JSON export companion of a LIST/SEARCH operation — see {@link ResourceCollectionExportConfig}. */
+    /** The file-export companion of a LIST/SEARCH operation — see {@link ResourceCollectionExportConfig}. */
     ResourceGeneratedOperationKind["GENERATED_COLLECTION_EXPORT"] = "generated_collection_export";
 })(ResourceGeneratedOperationKind || (ResourceGeneratedOperationKind = {}));
 /**