@orthacms/utils-server 0.4.2 → 0.5.0

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 export { parseFilterTree } from './lib/filters/parse-filter-tree';
+export { FILTER_MAX_LENGTH } from './lib/filters/budgets';
 export { applyFilterTree, type ApplyFilterTreeOptions, type FilterExtensionResolver } from './lib/filters/tree-to-drizzle';
 export type { DbLike, TableLike } from './lib/filters/table-helpers';
-export { FilterOperator, ScalarFieldType, RelationKind } from './lib/filters/types';
+export { FilterOperator, ScalarFieldType, RelationKind, WithinLastUnit } from './lib/filters/types';
 export { OPERATORS_BY_TYPE, operatorsFor } from './lib/filters/operator-support';
-export type { ScalarFieldSchema, FieldSchema, RelationSchema, RelationScope, FilterSchema, ParsedRule, ParsedGroup, ParsedNode } from './lib/filters/types';
+export type { WithinLastValue, ScalarFieldSchema, FieldSchema, RelationSchema, RelationScope, FilterSchema, ParsedRule, ParsedGroup, ParsedNode } from './lib/filters/types';
 export { FilterException, FilterErrorCode, FilterSchemaException } from './lib/filters/filter-exceptions';
 export { clampInt } from './lib/clamp-int';
 export { isForeignKeyViolation, isUniqueViolation, violatedConstraint } from './lib/pg-errors';
+export { readEnv, requireEnv, readPositiveInt, readOptionalPositiveInt, readList, readOptionalList, readFlag, readTrustProxy, readNodeEnv, isProduction, when, defined, NODE_ENVS, type NodeEnv } from './lib/env';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EACH,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACH,cAAc,EACd,eAAe,EACf,YAAY,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACf,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACR,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,eAAe,EACf,eAAe,EACf,qBAAqB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EACrB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EACH,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACH,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACf,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACR,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,eAAe,EACf,eAAe,EACf,qBAAqB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACH,OAAO,EACP,UAAU,EACV,eAAe,EACf,uBAAuB,EACvB,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,EACP,SAAS,EACT,KAAK,OAAO,EACf,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,14 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.violatedConstraint = exports.isUniqueViolation = exports.isForeignKeyViolation = exports.clampInt = exports.FilterSchemaException = exports.FilterErrorCode = exports.FilterException = exports.operatorsFor = exports.OPERATORS_BY_TYPE = exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = exports.applyFilterTree = exports.parseFilterTree = void 0;
+exports.NODE_ENVS = exports.defined = exports.when = exports.isProduction = exports.readNodeEnv = exports.readTrustProxy = exports.readFlag = exports.readOptionalList = exports.readList = exports.readOptionalPositiveInt = exports.readPositiveInt = exports.requireEnv = exports.readEnv = exports.violatedConstraint = exports.isUniqueViolation = exports.isForeignKeyViolation = exports.clampInt = exports.FilterSchemaException = exports.FilterErrorCode = exports.FilterException = exports.operatorsFor = exports.OPERATORS_BY_TYPE = exports.WithinLastUnit = exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = exports.applyFilterTree = exports.FILTER_MAX_LENGTH = exports.parseFilterTree = void 0;
 var parse_filter_tree_1 = require("./lib/filters/parse-filter-tree");
 Object.defineProperty(exports, "parseFilterTree", { enumerable: true, get: function () { return parse_filter_tree_1.parseFilterTree; } });
+var budgets_1 = require("./lib/filters/budgets");
+Object.defineProperty(exports, "FILTER_MAX_LENGTH", { enumerable: true, get: function () { return budgets_1.FILTER_MAX_LENGTH; } });
 var tree_to_drizzle_1 = require("./lib/filters/tree-to-drizzle");
 Object.defineProperty(exports, "applyFilterTree", { enumerable: true, get: function () { return tree_to_drizzle_1.applyFilterTree; } });
 var types_1 = require("./lib/filters/types");
 Object.defineProperty(exports, "FilterOperator", { enumerable: true, get: function () { return types_1.FilterOperator; } });
 Object.defineProperty(exports, "ScalarFieldType", { enumerable: true, get: function () { return types_1.ScalarFieldType; } });
 Object.defineProperty(exports, "RelationKind", { enumerable: true, get: function () { return types_1.RelationKind; } });
+Object.defineProperty(exports, "WithinLastUnit", { enumerable: true, get: function () { return types_1.WithinLastUnit; } });
 var operator_support_1 = require("./lib/filters/operator-support");
 Object.defineProperty(exports, "OPERATORS_BY_TYPE", { enumerable: true, get: function () { return operator_support_1.OPERATORS_BY_TYPE; } });
 Object.defineProperty(exports, "operatorsFor", { enumerable: true, get: function () { return operator_support_1.operatorsFor; } });
@@ -22,3 +25,17 @@ var pg_errors_1 = require("./lib/pg-errors");
 Object.defineProperty(exports, "isForeignKeyViolation", { enumerable: true, get: function () { return pg_errors_1.isForeignKeyViolation; } });
 Object.defineProperty(exports, "isUniqueViolation", { enumerable: true, get: function () { return pg_errors_1.isUniqueViolation; } });
 Object.defineProperty(exports, "violatedConstraint", { enumerable: true, get: function () { return pg_errors_1.violatedConstraint; } });
+var env_1 = require("./lib/env");
+Object.defineProperty(exports, "readEnv", { enumerable: true, get: function () { return env_1.readEnv; } });
+Object.defineProperty(exports, "requireEnv", { enumerable: true, get: function () { return env_1.requireEnv; } });
+Object.defineProperty(exports, "readPositiveInt", { enumerable: true, get: function () { return env_1.readPositiveInt; } });
+Object.defineProperty(exports, "readOptionalPositiveInt", { enumerable: true, get: function () { return env_1.readOptionalPositiveInt; } });
+Object.defineProperty(exports, "readList", { enumerable: true, get: function () { return env_1.readList; } });
+Object.defineProperty(exports, "readOptionalList", { enumerable: true, get: function () { return env_1.readOptionalList; } });
+Object.defineProperty(exports, "readFlag", { enumerable: true, get: function () { return env_1.readFlag; } });
+Object.defineProperty(exports, "readTrustProxy", { enumerable: true, get: function () { return env_1.readTrustProxy; } });
+Object.defineProperty(exports, "readNodeEnv", { enumerable: true, get: function () { return env_1.readNodeEnv; } });
+Object.defineProperty(exports, "isProduction", { enumerable: true, get: function () { return env_1.isProduction; } });
+Object.defineProperty(exports, "when", { enumerable: true, get: function () { return env_1.when; } });
+Object.defineProperty(exports, "defined", { enumerable: true, get: function () { return env_1.defined; } });
+Object.defineProperty(exports, "NODE_ENVS", { enumerable: true, get: function () { return env_1.NODE_ENVS; } });

package/dist/lib/env.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Reading `process.env` into typed configuration.
+ *
+ * A host's `ortha.config.ts` is the one file allowed to touch the environment,
+ * and every deployment writes the same handful of readers to do it: a required
+ * string, a bounded number, a comma list, `TRUST_PROXY`, `NODE_ENV`. They were
+ * duplicated between this repo's host and the scaffolder's template, where the
+ * copies had already drifted — the template's number reader had no
+ * "optional, no default" form, so a generated app could not express a ceiling
+ * that means "leave the plugin's own default alone".
+ *
+ * Every reader here **throws rather than guesses**. That is the whole point of
+ * the module: the failure mode of environment parsing is silence, and a config
+ * value that is quietly wrong is discovered a session TTL later, or by reading
+ * a `Set-Cookie` header, rather than at boot with the variable named.
+ *
+ * The last two exports — {@link when} and {@link defined} — read nothing. They
+ * are here because they are what a host does with the readers' `undefined`:
+ * plugins merge their settings as `{ ...DEFAULTS, ...config }`, so an unset
+ * value must become an *absent key* rather than an explicit `undefined`, which
+ * would erase the default it was meant to leave alone. Every host writing that
+ * as `...(x ? { key } : {})` at each call site is the duplication this module
+ * exists to end.
+ */
+/**
+ * A trimmed environment value, `undefined` when unset **or empty**.
+ *
+ * The one reader every other reader here is built on, so "empty means not
+ * configured" is decided once. That equivalence matters: `.env.example` ships
+ * keys with no value, and `ANTHROPIC_API_KEY=` has to leave a deployment with
+ * *no* Claude backend rather than one registered with an empty key — a backend
+ * that is in the picker and fails on the first message.
+ */
+export declare function readEnv(name: string): string | undefined;
+/**
+ * Reads a value the app cannot run without, failing at load rather than
+ * several seconds into boot.
+ *
+ * Left to default to `''`, a missing `DATABASE_URL` reaches `pg` as "use the
+ * libpq defaults", and the first thing that touches the database fails with
+ * whatever the local libpq environment happens to produce (measured: `SASL:
+ * SCRAM-SERVER-FIRST-MESSAGE: client password must be a string`). The server
+ * does fail closed, which is the important half, but nothing in that message
+ * names the variable that was never set.
+ *
+ * @param name The environment variable to read.
+ * @param hint Appended to the error, for a deployment-specific instruction —
+ *   which file to copy, which secret store to look in. Omitted, the message
+ *   says only that there is no usable default.
+ */
+export declare function requireEnv(name: string, hint?: string): string;
+/**
+ * Reads a numeric setting: the default when unset or empty, the value when it
+ * is a plain positive decimal integer, and an error otherwise.
+ *
+ * This replaces `Number(process.env[x]) || default`, which was wrong in three
+ * directions at once and silent in all of them. `0` is falsy, so it became the
+ * default — `LOGIN_RATE_LIMIT=0` ("block every login") quietly meant 10. A
+ * negative is truthy, so it was accepted — `SESSION_TTL_SECONDS=-1` issued
+ * every session already expired, login answering `201` and the very next
+ * request `401`. And exponent notation parsed, so `GRAPHQL_MAX_DEPTH=1e9`
+ * removed the cost budget that ADR-0008 calls GraphQL's replacement for REST's
+ * structural bound. Refusing to boot names the variable; the alternative was a
+ * deployment that looked configured and was not.
+ *
+ * Empty is deliberately *not* an error: `.env.example` ships several keys with
+ * no value, and a fresh clone must boot from it unchanged.
+ */
+export declare function readPositiveInt(name: string, fallback: number): number;
+/**
+ * As {@link readPositiveInt}, but `undefined` when unset — no default to fall
+ * back to.
+ *
+ * The form a *ceiling* needs. A plugin that ships its own default cannot be
+ * handed `{ maxSteps: undefined }`, because spreading that overwrites the
+ * default with nothing; the caller conditionally spreads on this instead.
+ */
+export declare function readOptionalPositiveInt(name: string): number | undefined;
+/**
+ * A comma-separated list setting, trimmed and emptied of blanks.
+ *
+ * An explicitly empty value yields an empty list rather than the fallback,
+ * because "allow no origins" is a setting somebody means.
+ */
+export declare function readList(name: string, fallback: string): string[];
+/**
+ * Express's `trust proxy` setting, in the three shapes it accepts.
+ *
+ * Checked in this order: a hop count (`'1'` — the recommended form, and the
+ * only one a client cannot forge past), a boolean (`'true'` trusts the entire
+ * `X-Forwarded-For` chain, `'false'` trusts none), or any other non-empty
+ * string, passed to Express verbatim as a subnet/preset list (`'loopback'`,
+ * `'10.0.0.0/8'`). Unset yields `undefined`, leaving Express's default of
+ * ignoring forwarded headers entirely.
+ *
+ * Returns the union structurally rather than importing `TrustProxySetting`
+ * from `@orthacms/bootstrap-server`: this is a leaf helper package, and the
+ * host importing it must not become a dependency of it. The host's own
+ * `trustProxy?: TrustProxySetting` field is what checks the two agree.
+ */
+export declare function readTrustProxy(name?: string): boolean | number | string | undefined;
+/** The deployment modes an Ortha app recognises. */
+export declare const NODE_ENVS: readonly ["development", "test", "production"];
+/** One of {@link NODE_ENVS}. */
+export type NodeEnv = (typeof NODE_ENVS)[number];
+/**
+ * Reads `NODE_ENV`, rejecting a value that is neither recognised nor empty.
+ *
+ * `NODE_ENV !== 'production'` is the switch behind **two** protections at once
+ * — whether the API reference and GraphiQL are published, and whether the
+ * session cookie carries `Secure` — so any value that is not exactly
+ * `production` turns both off. Unset is a legitimate, and the common, local
+ * state; a *typo* is not, and it is indistinguishable from correct
+ * configuration until you read a `Set-Cookie` header. Measured: `produciton`
+ * serves `/reference/json` to an unauthenticated caller and drops `Secure`
+ * from the session cookie, exactly as if nothing had been set (ORT-137).
+ *
+ * Rejecting the typo costs a deployment that spells it right nothing, and
+ * turns a silent downgrade into a refusal to start.
+ */
+export declare function readNodeEnv(): NodeEnv | undefined;
+/**
+ * True only in a deployment that said `production`, with the spelling checked
+ * by {@link readNodeEnv}.
+ */
+export declare function isProduction(): boolean;
+/**
+ * As {@link readList}, but `undefined` when the variable is unset, so the
+ * consumer's own default list survives rather than being replaced by an empty
+ * one.
+ *
+ * The list counterpart to {@link readOptionalPositiveInt}, and needed for the
+ * same reason: a setting whose owner ships a default cannot be handed an empty
+ * array meaning "the deployment said nothing".
+ */
+export declare function readOptionalList(name: string): string[] | undefined;
+/**
+ * A boolean setting: what the deployment said, or `fallback` when it said
+ * nothing.
+ *
+ * Anything other than `true` reads as false, so a typo turns a switch **off**
+ * rather than on. That direction is deliberate: the switches this reads are
+ * kill switches for surfaces that send content to a third party or open a door
+ * for an external agent, and a misspelling should not open one.
+ */
+export declare function readFlag(name: string, fallback: boolean): boolean;
+/**
+ * The value when the setting was configured, `undefined` when it was not.
+ *
+ * The counterpart to {@link defined}: together they replace
+ * `...(x ? { key: … } : {})` at a config site. `build` is a thunk so its body —
+ * often several further reads — runs only when it applies, which is what lets a
+ * whole provider block sit behind one credential check.
+ */
+export declare function when<T>(configured: unknown, build: () => T): T | undefined;
+/**
+ * The same object with every `undefined`-valued key removed.
+ *
+ * A plugin merges its own defaults as `{ ...DEFAULTS, ...config }`, so an
+ * explicit `{ maxSteps: undefined }` does not leave `DEFAULT_RUN_LIMITS.maxSteps`
+ * in place — it erases it. Dropping the key is what "the deployment did not set
+ * this" has to mean, and saying it once at the end of a builder is why a config
+ * file no longer needs a conditional per optional setting.
+ */
+export declare function defined<T extends object>(value: T): T;
+//# sourceMappingURL=env.d.ts.map

package/dist/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAS9D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcxE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC1B,IAAI,SAAgB,GACrB,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAavC;AAED,oDAAoD;AACpD,eAAO,MAAM,SAAS,gDAAiD,CAAC;AAExE,gCAAgC;AAChC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,IAAI,OAAO,GAAG,SAAS,CAejD;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAQrD"}

package/dist/lib/env.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * Reading `process.env` into typed configuration.
+ *
+ * A host's `ortha.config.ts` is the one file allowed to touch the environment,
+ * and every deployment writes the same handful of readers to do it: a required
+ * string, a bounded number, a comma list, `TRUST_PROXY`, `NODE_ENV`. They were
+ * duplicated between this repo's host and the scaffolder's template, where the
+ * copies had already drifted — the template's number reader had no
+ * "optional, no default" form, so a generated app could not express a ceiling
+ * that means "leave the plugin's own default alone".
+ *
+ * Every reader here **throws rather than guesses**. That is the whole point of
+ * the module: the failure mode of environment parsing is silence, and a config
+ * value that is quietly wrong is discovered a session TTL later, or by reading
+ * a `Set-Cookie` header, rather than at boot with the variable named.
+ *
+ * The last two exports — {@link when} and {@link defined} — read nothing. They
+ * are here because they are what a host does with the readers' `undefined`:
+ * plugins merge their settings as `{ ...DEFAULTS, ...config }`, so an unset
+ * value must become an *absent key* rather than an explicit `undefined`, which
+ * would erase the default it was meant to leave alone. Every host writing that
+ * as `...(x ? { key } : {})` at each call site is the duplication this module
+ * exists to end.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_ENVS = void 0;
+exports.readEnv = readEnv;
+exports.requireEnv = requireEnv;
+exports.readPositiveInt = readPositiveInt;
+exports.readOptionalPositiveInt = readOptionalPositiveInt;
+exports.readList = readList;
+exports.readTrustProxy = readTrustProxy;
+exports.readNodeEnv = readNodeEnv;
+exports.isProduction = isProduction;
+exports.readOptionalList = readOptionalList;
+exports.readFlag = readFlag;
+exports.when = when;
+exports.defined = defined;
+/**
+ * A trimmed environment value, `undefined` when unset **or empty**.
+ *
+ * The one reader every other reader here is built on, so "empty means not
+ * configured" is decided once. That equivalence matters: `.env.example` ships
+ * keys with no value, and `ANTHROPIC_API_KEY=` has to leave a deployment with
+ * *no* Claude backend rather than one registered with an empty key — a backend
+ * that is in the picker and fails on the first message.
+ */
+function readEnv(name) {
+    return process.env[name]?.trim() || undefined;
+}
+/**
+ * Reads a value the app cannot run without, failing at load rather than
+ * several seconds into boot.
+ *
+ * Left to default to `''`, a missing `DATABASE_URL` reaches `pg` as "use the
+ * libpq defaults", and the first thing that touches the database fails with
+ * whatever the local libpq environment happens to produce (measured: `SASL:
+ * SCRAM-SERVER-FIRST-MESSAGE: client password must be a string`). The server
+ * does fail closed, which is the important half, but nothing in that message
+ * names the variable that was never set.
+ *
+ * @param name The environment variable to read.
+ * @param hint Appended to the error, for a deployment-specific instruction —
+ *   which file to copy, which secret store to look in. Omitted, the message
+ *   says only that there is no usable default.
+ */
+function requireEnv(name, hint) {
+    const raw = readEnv(name);
+    if (!raw) {
+        throw new Error(`Missing required environment variable ${name}. ` +
+            (hint ?? 'The server has no usable default for this value.'));
+    }
+    return raw;
+}
+/**
+ * Reads a numeric setting: the default when unset or empty, the value when it
+ * is a plain positive decimal integer, and an error otherwise.
+ *
+ * This replaces `Number(process.env[x]) || default`, which was wrong in three
+ * directions at once and silent in all of them. `0` is falsy, so it became the
+ * default — `LOGIN_RATE_LIMIT=0` ("block every login") quietly meant 10. A
+ * negative is truthy, so it was accepted — `SESSION_TTL_SECONDS=-1` issued
+ * every session already expired, login answering `201` and the very next
+ * request `401`. And exponent notation parsed, so `GRAPHQL_MAX_DEPTH=1e9`
+ * removed the cost budget that ADR-0008 calls GraphQL's replacement for REST's
+ * structural bound. Refusing to boot names the variable; the alternative was a
+ * deployment that looked configured and was not.
+ *
+ * Empty is deliberately *not* an error: `.env.example` ships several keys with
+ * no value, and a fresh clone must boot from it unchanged.
+ */
+function readPositiveInt(name, fallback) {
+    return readOptionalPositiveInt(name) ?? fallback;
+}
+/**
+ * As {@link readPositiveInt}, but `undefined` when unset — no default to fall
+ * back to.
+ *
+ * The form a *ceiling* needs. A plugin that ships its own default cannot be
+ * handed `{ maxSteps: undefined }`, because spreading that overwrites the
+ * default with nothing; the caller conditionally spreads on this instead.
+ */
+function readOptionalPositiveInt(name) {
+    const raw = readEnv(name);
+    if (!raw) {
+        return undefined;
+    }
+    // Plain decimal digits only. `Number` would also take `1e9`, `0x20` and
+    // `Infinity`, none of which anyone means to write in a `.env`.
+    if (!/^\d+$/.test(raw) || Number(raw) <= 0) {
+        throw new Error(`Environment variable ${name} must be a positive whole number ` +
+            `(got "${raw}").`);
+    }
+    return Number(raw);
+}
+/**
+ * A comma-separated list setting, trimmed and emptied of blanks.
+ *
+ * An explicitly empty value yields an empty list rather than the fallback,
+ * because "allow no origins" is a setting somebody means.
+ */
+function readList(name, fallback) {
+    return (process.env[name] ?? fallback)
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+/**
+ * Express's `trust proxy` setting, in the three shapes it accepts.
+ *
+ * Checked in this order: a hop count (`'1'` — the recommended form, and the
+ * only one a client cannot forge past), a boolean (`'true'` trusts the entire
+ * `X-Forwarded-For` chain, `'false'` trusts none), or any other non-empty
+ * string, passed to Express verbatim as a subnet/preset list (`'loopback'`,
+ * `'10.0.0.0/8'`). Unset yields `undefined`, leaving Express's default of
+ * ignoring forwarded headers entirely.
+ *
+ * Returns the union structurally rather than importing `TrustProxySetting`
+ * from `@orthacms/bootstrap-server`: this is a leaf helper package, and the
+ * host importing it must not become a dependency of it. The host's own
+ * `trustProxy?: TrustProxySetting` field is what checks the two agree.
+ */
+function readTrustProxy(name = 'TRUST_PROXY') {
+    const raw = readEnv(name);
+    if (!raw) {
+        return undefined;
+    }
+    const hops = Number(raw);
+    if (Number.isInteger(hops) && hops >= 0) {
+        return hops;
+    }
+    if (raw === 'true' || raw === 'false') {
+        return raw === 'true';
+    }
+    return raw;
+}
+/** The deployment modes an Ortha app recognises. */
+exports.NODE_ENVS = ['development', 'test', 'production'];
+/**
+ * Reads `NODE_ENV`, rejecting a value that is neither recognised nor empty.
+ *
+ * `NODE_ENV !== 'production'` is the switch behind **two** protections at once
+ * — whether the API reference and GraphiQL are published, and whether the
+ * session cookie carries `Secure` — so any value that is not exactly
+ * `production` turns both off. Unset is a legitimate, and the common, local
+ * state; a *typo* is not, and it is indistinguishable from correct
+ * configuration until you read a `Set-Cookie` header. Measured: `produciton`
+ * serves `/reference/json` to an unauthenticated caller and drops `Secure`
+ * from the session cookie, exactly as if nothing had been set (ORT-137).
+ *
+ * Rejecting the typo costs a deployment that spells it right nothing, and
+ * turns a silent downgrade into a refusal to start.
+ */
+function readNodeEnv() {
+    const raw = readEnv('NODE_ENV');
+    if (!raw) {
+        return undefined;
+    }
+    if (!exports.NODE_ENVS.includes(raw)) {
+        throw new Error(`NODE_ENV is "${raw}", which this app does not recognise — expected ` +
+            `one of ${exports.NODE_ENVS.join(', ')}, or nothing at all for local ` +
+            'development. Anything else reads as "not production", which ' +
+            'publishes the API reference and drops `Secure` from the session ' +
+            'cookie.');
+    }
+    return raw;
+}
+/**
+ * True only in a deployment that said `production`, with the spelling checked
+ * by {@link readNodeEnv}.
+ */
+function isProduction() {
+    return readNodeEnv() === 'production';
+}
+/**
+ * As {@link readList}, but `undefined` when the variable is unset, so the
+ * consumer's own default list survives rather than being replaced by an empty
+ * one.
+ *
+ * The list counterpart to {@link readOptionalPositiveInt}, and needed for the
+ * same reason: a setting whose owner ships a default cannot be handed an empty
+ * array meaning "the deployment said nothing".
+ */
+function readOptionalList(name) {
+    return when(readEnv(name), () => readList(name, ''));
+}
+/**
+ * A boolean setting: what the deployment said, or `fallback` when it said
+ * nothing.
+ *
+ * Anything other than `true` reads as false, so a typo turns a switch **off**
+ * rather than on. That direction is deliberate: the switches this reads are
+ * kill switches for surfaces that send content to a third party or open a door
+ * for an external agent, and a misspelling should not open one.
+ */
+function readFlag(name, fallback) {
+    const raw = readEnv(name);
+    return raw === undefined ? fallback : raw === 'true';
+}
+/**
+ * The value when the setting was configured, `undefined` when it was not.
+ *
+ * The counterpart to {@link defined}: together they replace
+ * `...(x ? { key: … } : {})` at a config site. `build` is a thunk so its body —
+ * often several further reads — runs only when it applies, which is what lets a
+ * whole provider block sit behind one credential check.
+ */
+function when(configured, build) {
+    return configured ? build() : undefined;
+}
+/**
+ * The same object with every `undefined`-valued key removed.
+ *
+ * A plugin merges its own defaults as `{ ...DEFAULTS, ...config }`, so an
+ * explicit `{ maxSteps: undefined }` does not leave `DEFAULT_RUN_LIMITS.maxSteps`
+ * in place — it erases it. Dropping the key is what "the deployment did not set
+ * this" has to mean, and saying it once at the end of a builder is why a config
+ * file no longer needs a conditional per optional setting.
+ */
+function defined(value) {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined) {
+            result[key] = item;
+        }
+    }
+    return result;
+}

package/dist/lib/filters/budgets.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Every ceiling the filter engine imposes, in one place.
+ *
+ * The engine's job is to accept a tree a stranger wrote. What stops that tree
+ * from being unbounded work is this file — nothing else. Four of these budgets
+ * count *structure* (how many rules, how deep, how long an `IN` list); the
+ * fifth counts *text*, and it was missing.
+ *
+ * ## What the DTO cap covers, and what it does not
+ *
+ * {@link FILTER_MAX_LENGTH} is the cap a caller's DTO puts on the whole
+ * serialised filter — `@MaxLength(FILTER_MAX_LENGTH)` on `?filter=`. It lives
+ * here rather than in each plugin because it was declared separately in four of
+ * them and one copy had drifted to 8192, so "the filter cap" meant two numbers
+ * depending on which endpoint you asked.
+ *
+ * It is a **transport** guard, and it only guards the paths where the filter
+ * arrives as a string. It does not reach:
+ *
+ * - **Alarm rules.** `CreateAlarmRuleDto.filter` is an already-parsed object
+ *   (`@IsObject()`), because the authority on a filter tree's shape is this
+ *   parser rather than a second copy of the grammar in decorators. `@MaxLength`
+ *   is a string decorator and could not be applied to it.
+ * - **A stored alarm rule replayed from its `jsonb` column** — by the outbox
+ *   subscriber, the periodic sweep, or `POST /rules/:id/rescan`. Nothing
+ *   re-serialises it on the way out of the database, so there is no string to
+ *   measure.
+ * - **The copilot's `admin_content_search` tool.** Its `filter` argument is an
+ *   object too, and the registry's input check deliberately ignores `anyOf`, so
+ *   the tree's contents reach the parser unexamined.
+ * - **GraphQL's entry loader**, which builds an id-`in` tree in code and casts
+ *   past the DTO.
+ *
+ * On those four paths the parser *is* the boundary. That is why
+ * {@link DEFAULT_MAX_VALUE_LENGTH} exists: a budget declared on the DTO
+ * protects the endpoints that happen to have one, and a budget declared here
+ * protects every caller there will ever be.
+ */
+/**
+ * Max length of a serialised filter payload, for the `@MaxLength` a caller
+ * puts on its own `?filter=` / `filter` DTO field.
+ *
+ * A coarse first latch ahead of the engine's own budgets: it refuses an
+ * oversized payload before `JSON.parse` sees it. It is deliberately generous —
+ * roughly a hundred UUID clauses — because it is not the real bound; the node,
+ * depth, list and value budgets below are.
+ *
+ * **The one number, and every DTO imports it from here.** `activity`,
+ * `content` and `users` each declared their own `4096` and `alarms` a `8192`
+ * that was applied to nothing at all; four declarations of one rule is three
+ * chances to answer a caller differently on two endpoints for the same filter.
+ */
+export declare const FILTER_MAX_LENGTH = 4096;
+/** Default `schema.maxDepth` — how many dotted relation hops a path may walk. */
+export declare const DEFAULT_MAX_DEPTH = 3;
+/** Default `schema.maxNodes` — how many groups + rules one tree may hold. */
+export declare const DEFAULT_MAX_NODES = 50;
+/** Default `schema.maxGroupDepth` — how deep `and`/`or` nesting may go. */
+export declare const DEFAULT_MAX_GROUP_DEPTH = 5;
+/** Default `schema.maxInListLength` — how many values one `in`/`nin` may name. */
+export declare const DEFAULT_MAX_IN_LIST = 100;
+/**
+ * Default `schema.maxValueLength` — how long one clause's **string** value may
+ * be, applied to each element of an `in` list as well as to a bare scalar.
+ *
+ * The number is {@link FILTER_MAX_LENGTH} on purpose, and the equality is the
+ * argument for it: a filter that arrives as a string is already capped at that
+ * length in total, so no value inside one can be longer. This budget therefore
+ * cannot refuse anything an HTTP caller could already send — it exists for the
+ * paths listed at the top of this file, which never meet the DTO at all, and
+ * where the alternative bound was the 1 MB body limit.
+ *
+ * What it stops is a single arbitrarily long `LIKE` pattern: `~~` is scanned
+ * against every candidate row, so the cost of one clause is the pattern's
+ * length times the table's, and nothing above the parser was measuring the
+ * first factor.
+ */
+export declare const DEFAULT_MAX_VALUE_LENGTH = 4096;
+//# sourceMappingURL=budgets.d.ts.map

package/dist/lib/filters/budgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgets.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/budgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,OAAoB,CAAC"}

package/dist/lib/filters/budgets.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Every ceiling the filter engine imposes, in one place.
+ *
+ * The engine's job is to accept a tree a stranger wrote. What stops that tree
+ * from being unbounded work is this file — nothing else. Four of these budgets
+ * count *structure* (how many rules, how deep, how long an `IN` list); the
+ * fifth counts *text*, and it was missing.
+ *
+ * ## What the DTO cap covers, and what it does not
+ *
+ * {@link FILTER_MAX_LENGTH} is the cap a caller's DTO puts on the whole
+ * serialised filter — `@MaxLength(FILTER_MAX_LENGTH)` on `?filter=`. It lives
+ * here rather than in each plugin because it was declared separately in four of
+ * them and one copy had drifted to 8192, so "the filter cap" meant two numbers
+ * depending on which endpoint you asked.
+ *
+ * It is a **transport** guard, and it only guards the paths where the filter
+ * arrives as a string. It does not reach:
+ *
+ * - **Alarm rules.** `CreateAlarmRuleDto.filter` is an already-parsed object
+ *   (`@IsObject()`), because the authority on a filter tree's shape is this
+ *   parser rather than a second copy of the grammar in decorators. `@MaxLength`
+ *   is a string decorator and could not be applied to it.
+ * - **A stored alarm rule replayed from its `jsonb` column** — by the outbox
+ *   subscriber, the periodic sweep, or `POST /rules/:id/rescan`. Nothing
+ *   re-serialises it on the way out of the database, so there is no string to
+ *   measure.
+ * - **The copilot's `admin_content_search` tool.** Its `filter` argument is an
+ *   object too, and the registry's input check deliberately ignores `anyOf`, so
+ *   the tree's contents reach the parser unexamined.
+ * - **GraphQL's entry loader**, which builds an id-`in` tree in code and casts
+ *   past the DTO.
+ *
+ * On those four paths the parser *is* the boundary. That is why
+ * {@link DEFAULT_MAX_VALUE_LENGTH} exists: a budget declared on the DTO
+ * protects the endpoints that happen to have one, and a budget declared here
+ * protects every caller there will ever be.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_VALUE_LENGTH = exports.DEFAULT_MAX_IN_LIST = exports.DEFAULT_MAX_GROUP_DEPTH = exports.DEFAULT_MAX_NODES = exports.DEFAULT_MAX_DEPTH = exports.FILTER_MAX_LENGTH = void 0;
+/**
+ * Max length of a serialised filter payload, for the `@MaxLength` a caller
+ * puts on its own `?filter=` / `filter` DTO field.
+ *
+ * A coarse first latch ahead of the engine's own budgets: it refuses an
+ * oversized payload before `JSON.parse` sees it. It is deliberately generous —
+ * roughly a hundred UUID clauses — because it is not the real bound; the node,
+ * depth, list and value budgets below are.
+ *
+ * **The one number, and every DTO imports it from here.** `activity`,
+ * `content` and `users` each declared their own `4096` and `alarms` a `8192`
+ * that was applied to nothing at all; four declarations of one rule is three
+ * chances to answer a caller differently on two endpoints for the same filter.
+ */
+exports.FILTER_MAX_LENGTH = 4096;
+/** Default `schema.maxDepth` — how many dotted relation hops a path may walk. */
+exports.DEFAULT_MAX_DEPTH = 3;
+/** Default `schema.maxNodes` — how many groups + rules one tree may hold. */
+exports.DEFAULT_MAX_NODES = 50;
+/** Default `schema.maxGroupDepth` — how deep `and`/`or` nesting may go. */
+exports.DEFAULT_MAX_GROUP_DEPTH = 5;
+/** Default `schema.maxInListLength` — how many values one `in`/`nin` may name. */
+exports.DEFAULT_MAX_IN_LIST = 100;
+/**
+ * Default `schema.maxValueLength` — how long one clause's **string** value may
+ * be, applied to each element of an `in` list as well as to a bare scalar.
+ *
+ * The number is {@link FILTER_MAX_LENGTH} on purpose, and the equality is the
+ * argument for it: a filter that arrives as a string is already capped at that
+ * length in total, so no value inside one can be longer. This budget therefore
+ * cannot refuse anything an HTTP caller could already send — it exists for the
+ * paths listed at the top of this file, which never meet the DTO at all, and
+ * where the alternative bound was the 1 MB body limit.
+ *
+ * What it stops is a single arbitrarily long `LIKE` pattern: `~~` is scanned
+ * against every candidate row, so the cost of one clause is the pattern's
+ * length times the table's, and nothing above the parser was measuring the
+ * first factor.
+ */
+exports.DEFAULT_MAX_VALUE_LENGTH = exports.FILTER_MAX_LENGTH;

package/dist/lib/filters/filter-exceptions.d.ts

@@ -39,6 +39,13 @@ export declare const FilterErrorCode: {
     readonly EmptyInList: "FILTER_EMPTY_IN_LIST";
     /** `in`/`nin` value list exceeded `schema.maxInListLength` (default 100). */
     readonly MaxInListExceeded: "FILTER_MAX_IN_LIST_EXCEEDED";
+    /**
+     * A single clause's string value exceeded `schema.maxValueLength`
+     * (default 4096) — the engine's only budget over *text* rather than over
+     * the tree's structure. Reported per clause, naming the offending path, so
+     * a client can point at the rule rather than at the whole filter.
+     */
+    readonly ValueTooLong: "FILTER_VALUE_TOO_LONG";
 };
 /** One of the {@link FilterErrorCode} values. */
 export type FilterErrorCode = (typeof FilterErrorCode)[keyof typeof FilterErrorCode];

package/dist/lib/filters/filter-exceptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter-exceptions.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/filter-exceptions.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,mBAAmB,EACnB,4BAA4B,EAC/B,MAAM,gBAAgB,CAAC;AAExB,sDAAsD;AACtD,eAAO,MAAM,eAAe;IACxB,2DAA2D;;IAE3D,mDAAmD;;IAEnD,iDAAiD;;IAEjD,sDAAsD;;IAEtD;;;;;;OAMG;;IAEH,8DAA8D;;IAE9D,oEAAoE;;IAEpE,uEAAuE;;IAEvE,uDAAuD;;IAEvD,2DAA2D;;IAE3D,oDAAoD;;IAEpD,iEAAiE;;IAEjE;;;;OAIG;;IAEH,6EAA6E;;CAEvE,CAAC;AAEX,iDAAiD;AACjD,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,mBAAmB;IACpD,uCAAuC;IACvC,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,yDAAyD;IACzD,SAAgB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAGvD,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAkB5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAsB,SAAQ,4BAA4B;IACnE,wEAAwE;IACxE,SAAgB,IAAI,2BAA2B;gBAEnC,OAAO,EAAE,MAAM;CAQ9B"}
+{"version":3,"file":"filter-exceptions.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/filter-exceptions.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,mBAAmB,EACnB,4BAA4B,EAC/B,MAAM,gBAAgB,CAAC;AAExB,sDAAsD;AACtD,eAAO,MAAM,eAAe;IACxB,2DAA2D;;IAE3D,mDAAmD;;IAEnD,iDAAiD;;IAEjD,sDAAsD;;IAEtD;;;;;;OAMG;;IAEH,8DAA8D;;IAE9D,oEAAoE;;IAEpE,uEAAuE;;IAEvE,uDAAuD;;IAEvD,2DAA2D;;IAE3D,oDAAoD;;IAEpD,iEAAiE;;IAEjE;;;;OAIG;;IAEH,6EAA6E;;IAE7E;;;;;OAKG;;CAEG,CAAC;AAEX,iDAAiD;AACjD,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,mBAAmB;IACpD,uCAAuC;IACvC,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,yDAAyD;IACzD,SAAgB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAGvD,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAkB5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAsB,SAAQ,4BAA4B;IACnE,wEAAwE;IACxE,SAAgB,IAAI,2BAA2B;gBAEnC,OAAO,EAAE,MAAM;CAQ9B"}

package/dist/lib/filters/filter-exceptions.js

@@ -41,7 +41,14 @@ exports.FilterErrorCode = {
      */
     EmptyInList: 'FILTER_EMPTY_IN_LIST',
     /** `in`/`nin` value list exceeded `schema.maxInListLength` (default 100). */
-    MaxInListExceeded: 'FILTER_MAX_IN_LIST_EXCEEDED'
+    MaxInListExceeded: 'FILTER_MAX_IN_LIST_EXCEEDED',
+    /**
+     * A single clause's string value exceeded `schema.maxValueLength`
+     * (default 4096) — the engine's only budget over *text* rather than over
+     * the tree's structure. Reported per clause, naming the offending path, so
+     * a client can point at the rule rather than at the whole filter.
+     */
+    ValueTooLong: 'FILTER_VALUE_TOO_LONG'
 };
 /**
  * Typed 400 exception thrown by the filter parser.

package/dist/lib/filters/operator-support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator-support.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/operator-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAsD1D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAClC,eAAe,EACf,SAAS,cAAc,EAAE,CAQ5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CACxB,IAAI,EAAE,eAAe,GACtB,SAAS,cAAc,EAAE,GAAG,SAAS,CAIvC"}
+{"version":3,"file":"operator-support.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/operator-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAmE1D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAClC,eAAe,EACf,SAAS,cAAc,EAAE,CAQ5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CACxB,IAAI,EAAE,eAAe,GACtB,SAAS,cAAc,EAAE,GAAG,SAAS,CAIvC"}

package/dist/lib/filters/operator-support.js

@@ -47,6 +47,18 @@ const COMPARABLE_OPERATORS = [
     types_1.FilterOperator.Nin,
     types_1.FilterOperator.Null
 ];
+/**
+ * {@link COMPARABLE_OPERATORS} plus the relative window.
+ *
+ * `within_last` is date-only because it compares against `now()` — asking for
+ * "titles within the last 7 days" is not a narrower query, it is a category
+ * error, and Postgres would report it as a type mismatch rather than as
+ * something the client can fix.
+ */
+const DATE_OPERATORS = [
+    ...COMPARABLE_OPERATORS,
+    types_1.FilterOperator.WithinLast
+];
 /** {@link COMPARABLE_OPERATORS} plus the text-only `~~` family. */
 const TEXT_OPERATORS = [
     ...COMPARABLE_OPERATORS,
@@ -67,7 +79,7 @@ exports.OPERATORS_BY_TYPE = {
     [types_1.ScalarFieldType.Number]: COMPARABLE_OPERATORS,
     [types_1.ScalarFieldType.Boolean]: COMPARABLE_OPERATORS,
     [types_1.ScalarFieldType.Uuid]: COMPARABLE_OPERATORS,
-    [types_1.ScalarFieldType.Date]: COMPARABLE_OPERATORS
+    [types_1.ScalarFieldType.Date]: DATE_OPERATORS
 };
 /**
  * The operators `type` accepts, or `undefined` when the type is not one this

package/dist/lib/filters/parse-filter-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-filter-tree.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/parse-filter-tree.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAgB,UAAU,EAAE,MAAM,SAAS,CAAC;AAOtE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC3B,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,YAAY,GACrB,UAAU,GAAG,IAAI,CAoCnB"}
+{"version":3,"file":"parse-filter-tree.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/parse-filter-tree.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAgB,UAAU,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC3B,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,YAAY,GACrB,UAAU,GAAG,IAAI,CAqCnB"}

package/dist/lib/filters/parse-filter-tree.js

@@ -1,12 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseFilterTree = parseFilterTree;
+const budgets_1 = require("./budgets");
 const filter_exceptions_1 = require("./filter-exceptions");
 const resolve_leaf_1 = require("./resolve-leaf");
-const DEFAULT_MAX_DEPTH = 3;
-const DEFAULT_MAX_NODES = 50;
-const DEFAULT_MAX_GROUP_DEPTH = 5;
-const DEFAULT_MAX_IN_LIST = 100;
 /**
  * Parse a `filter` payload into a tree the translator can walk. Two
  * input shapes are accepted:
@@ -44,10 +41,11 @@ function parseFilterTree(rawFilter, schema) {
         return null;
     const ctx = {
         nodeCount: 0,
-        maxNodes: schema.maxNodes ?? DEFAULT_MAX_NODES,
-        maxGroupDepth: schema.maxGroupDepth ?? DEFAULT_MAX_GROUP_DEPTH,
-        maxDepth: schema.maxDepth ?? DEFAULT_MAX_DEPTH,
-        maxInListLength: schema.maxInListLength ?? DEFAULT_MAX_IN_LIST
+        maxNodes: schema.maxNodes ?? budgets_1.DEFAULT_MAX_NODES,
+        maxGroupDepth: schema.maxGroupDepth ?? budgets_1.DEFAULT_MAX_GROUP_DEPTH,
+        maxDepth: schema.maxDepth ?? budgets_1.DEFAULT_MAX_DEPTH,
+        maxInListLength: schema.maxInListLength ?? budgets_1.DEFAULT_MAX_IN_LIST,
+        maxValueLength: schema.maxValueLength ?? budgets_1.DEFAULT_MAX_VALUE_LENGTH
     };
     return walkNode(obj, schema, 0, ctx);
 }
@@ -97,7 +95,7 @@ function walkNode(raw, schema, depth, ctx) {
             throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, 'rule `op` must be a non-empty string');
         }
         const path = field.split('.');
-        const leaf = (0, resolve_leaf_1.resolveLeaf)(path, op, node.value, schema, ctx.maxDepth, ctx.maxInListLength);
+        const leaf = (0, resolve_leaf_1.resolveLeaf)(path, op, node.value, schema, ctx);
         return toRule(leaf);
     }
     throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, 'tree node must have `and`, `or`, or (`field` + `op`)');

package/dist/lib/filters/resolve-leaf.d.ts

@@ -1,8 +1,21 @@
 import type { FilterSchema, ParsedFilter } from './types';
+/**
+ * The per-leaf budgets, passed as one object rather than as a growing tail of
+ * positional numbers — three `number` parameters in a row is a call site where
+ * transposing two of them typechecks.
+ */
+export interface LeafLimits {
+    /** How many dotted relation hops the path may walk. */
+    maxDepth: number;
+    /** How many values one `in`/`nin` may name. */
+    maxInListLength: number;
+    /** How long one string value may be — see `budgets.ts`. */
+    maxValueLength: number;
+}
 /**
  * Walk a single dotted path against the schema, validate the operator,
  * and coerce the value to the declared type. Produces the `ParsedFilter`
  * leaf shape the tree parser tags with `kind: 'rule'`.
  */
-export declare function resolveLeaf(path: string[], op: string, value: unknown, schema: FilterSchema, maxDepth: number, maxInListLength: number): ParsedFilter;
+export declare function resolveLeaf(path: string[], op: string, value: unknown, schema: FilterSchema, limits: LeafLimits): ParsedFilter;
 //# sourceMappingURL=resolve-leaf.d.ts.map

package/dist/lib/filters/resolve-leaf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-leaf.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/resolve-leaf.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAqB,MAAM,SAAS,CAAC;AAQ7E;;;;GAIG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACxB,YAAY,CAkEd"}
+{"version":3,"file":"resolve-leaf.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/resolve-leaf.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACR,YAAY,EACZ,YAAY,EAGf,MAAM,SAAS,CAAC;AAQjB;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACvB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,UAAU,GACnB,YAAY,CA6Dd"}

package/dist/lib/filters/resolve-leaf.js

@@ -13,7 +13,8 @@ const UUID_CANONICAL = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f
  * and coerce the value to the declared type. Produces the `ParsedFilter`
  * leaf shape the tree parser tags with `kind: 'rule'`.
  */
-function resolveLeaf(path, op, value, schema, maxDepth, maxInListLength) {
+function resolveLeaf(path, op, value, schema, limits) {
+    const { maxDepth } = limits;
     if (path.length === 0) {
         throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.EmptyPath, 'empty filter path');
     }
@@ -37,7 +38,7 @@ function resolveLeaf(path, op, value, schema, maxDepth, maxInListLength) {
             return {
                 path,
                 op: op,
-                value: coerce(value, field, op, path, maxInListLength)
+                value: coerce(value, field, op, path, limits)
             };
         }
         const rel = (0, own_property_1.own)(relations, seg);
@@ -69,8 +70,12 @@ function assertOperatorAllowed(field, op, path) {
     }
     throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.OperatorNotAllowed, `operator "${op}" is not available on "${path.join('.')}" (a ${field.type} field)`, { path: path.join('.'), op, fieldType: field.type, allowed });
 }
-function coerce(raw, field, op, path, maxInListLength) {
+function coerce(raw, field, op, path, limits) {
+    const { maxInListLength } = limits;
     const pathStr = path.join('.');
+    if (op === types_1.FilterOperator.WithinLast) {
+        return withinLastValue(raw, pathStr);
+    }
     if (op === types_1.FilterOperator.Null) {
         if (raw === 'true' || raw === true)
             return true;
@@ -96,11 +101,39 @@ function coerce(raw, field, op, path, maxInListLength) {
         if (items.length > maxInListLength) {
             throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.MaxInListExceeded, `${op} value list exceeds max length ${maxInListLength}`, { path: pathStr, op, maxInListLength, length: items.length });
         }
-        return items.map((v) => scalarOf(v, field, pathStr));
+        return items.map((v) => scalarOf(v, field, pathStr, limits));
     }
-    return scalarOf(raw, field, pathStr);
+    return scalarOf(raw, field, pathStr, limits);
 }
-function scalarOf(v, field, pathStr) {
+/** Units a `within_last` window may name, as a set for membership checks. */
+const WITHIN_LAST_UNITS = new Set(Object.values(types_1.WithinLastUnit));
+/**
+ * Coerce a `within_last` value — `{ n, unit }`, the only object-shaped value in
+ * the grammar.
+ *
+ * The bound on `n` is not decoration. `now() - make_interval(days => 1e9)`
+ * overflows Postgres' timestamp range and raises a `22008` the caller sees as a
+ * 500; a client asking for a window that long means to say "all of it", and
+ * should be told so with a 400 rather than a stack trace. Ten years of minutes
+ * is far past any real window and comfortably inside what a timestamp can hold.
+ */
+const MAX_WITHIN_LAST_N = 10_000_000;
+function withinLastValue(raw, pathStr) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, 'within_last expects { n, unit }', { path: pathStr, op: types_1.FilterOperator.WithinLast });
+    }
+    const value = raw;
+    const n = Number(value['n']);
+    const unit = value['unit'];
+    if (!Number.isInteger(n) || n < 1 || n > MAX_WITHIN_LAST_N) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `within_last n must be an integer between 1 and ${MAX_WITHIN_LAST_N}`, { path: pathStr, op: types_1.FilterOperator.WithinLast, value: value['n'] });
+    }
+    if (typeof unit !== 'string' || !WITHIN_LAST_UNITS.has(unit)) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `within_last unit must be one of ${[...WITHIN_LAST_UNITS].join(', ')}`, { path: pathStr, op: types_1.FilterOperator.WithinLast, value: unit });
+    }
+    return { n, unit: unit };
+}
+function scalarOf(v, field, pathStr, limits) {
     // A filter value has to be a scalar. `String(v)` on anything else produces
     // a plausible-looking string that is then MATCHED AGAINST rather than
     // rejected: `null` → `"null"`, a missing `value` key → `"undefined"`,
@@ -117,7 +150,24 @@ function scalarOf(v, field, pathStr) {
             ? 'value is required'
             : 'value must be a string, number or boolean', { path: pathStr, expectedType: field.type });
     }
+    // The only budget that counts *text*. Every other ceiling in this engine
+    // bounds the tree's structure — nodes, hops, group nesting, `in` list
+    // length — and a single clause can carry an arbitrarily long string through
+    // all of them. On the endpoints that own a DTO the `@MaxLength` on the
+    // whole serialised filter caps this first; on the paths that never meet one
+    // (an alarm rule replayed out of its `jsonb` column, the copilot's search
+    // tool, an internally-built tree) this check is the only bound there is,
+    // and the alternative was the 1 MB body limit. Applied to a `number` or
+    // `boolean` too, which is free: their `String(v)` is a handful of
+    // characters and can never trip it.
     const s = typeof v === 'string' ? v : String(v);
+    if (s.length > limits.maxValueLength) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.ValueTooLong, `value exceeds max length ${limits.maxValueLength}`, {
+            path: pathStr,
+            maxValueLength: limits.maxValueLength,
+            length: s.length
+        });
+    }
     switch (field.type) {
         case types_1.ScalarFieldType.String:
             return s;

package/dist/lib/filters/scalar-op.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scalar-op.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/scalar-op.ts"],"names":[],"mappings":"AAAA,OAAO,EAeH,KAAK,SAAS,EACd,KAAK,GAAG,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAiBzC;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAClB,GAAG,EAAE,SAAS,EACd,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,OAAO,GACf,GAAG,CAqCL"}
+{"version":3,"file":"scalar-op.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/scalar-op.ts"],"names":[],"mappings":"AAAA,OAAO,EAgBH,KAAK,SAAS,EACd,KAAK,GAAG,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAkB,MAAM,SAAS,CAAC;AAkBzD;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAClB,GAAG,EAAE,SAAS,EACd,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,OAAO,GACf,GAAG,CAuCL"}

package/dist/lib/filters/scalar-op.js

@@ -54,6 +54,8 @@ function scalar(col, op, value) {
             return negative(col, (0, drizzle_orm_1.notIlike)(col, String(value)));
         case types_1.FilterOperator.Null:
             return value === true ? (0, drizzle_orm_1.isNull)(col) : (0, drizzle_orm_1.isNotNull)(col);
+        case types_1.FilterOperator.WithinLast:
+            return withinLast(col, value);
         default:
             // The parser validates `op` against the vocabulary, so this is
             // unreachable — but falling out of the switch returned `undefined`,
@@ -64,3 +66,27 @@ function scalar(col, op, value) {
             throw new filter_exceptions_1.FilterSchemaException(`no translation for operator "${String(op)}"`);
     }
 }
+/**
+ * `column >= now() - <n> <unit>`.
+ *
+ * The cutoff is computed by **Postgres, at query time** — which is the whole
+ * point of the operator surviving to the server. A cutoff computed here in
+ * JavaScript would be identical for one request and wrong for a stored filter
+ * replayed a month later.
+ *
+ * A `switch` over the three units rather than interpolating the unit into the
+ * SQL: `make_interval`'s argument names cannot be parameterised, so building
+ * the fragment from a variable would mean `sql.raw` on a value that came off
+ * the wire. The parser already restricts the unit to these three, and this way
+ * there is no path by which that could stop being true.
+ */
+function withinLast(col, window) {
+    switch (window.unit) {
+        case types_1.WithinLastUnit.Minutes:
+            return (0, drizzle_orm_1.gte)(col, (0, drizzle_orm_1.sql) `now() - make_interval(mins => ${window.n})`);
+        case types_1.WithinLastUnit.Hours:
+            return (0, drizzle_orm_1.gte)(col, (0, drizzle_orm_1.sql) `now() - make_interval(hours => ${window.n})`);
+        default:
+            return (0, drizzle_orm_1.gte)(col, (0, drizzle_orm_1.sql) `now() - make_interval(days => ${window.n})`);
+    }
+}

package/dist/lib/filters/types.d.ts

@@ -25,6 +25,20 @@ export declare const FilterOperator: {
     readonly Ilike: "ilike";
     readonly Nilike: "nilike";
     readonly Null: "null";
+    /**
+     * `column >= now() - <n> <unit>` — a window measured from **query time**,
+     * not from the moment the filter was written.
+     *
+     * The distinction is invisible in a URL and decisive in a stored one. The
+     * admin's query builder resolves its own `within_last` into a concrete
+     * `gte` cutoff when it serialises a filter into a link, deliberately: a
+     * shared deep link should keep showing the same rows. A filter that is
+     * *stored and replayed* — an alarm rule — must mean the opposite, or
+     * "not updated in 90 days" silently becomes "not updated since the day the
+     * rule was written". So the operator survives to the server, and the caller
+     * chooses which meaning it wants.
+     */
+    readonly WithinLast: "within_last";
 };
 /** Standard REST operator names. Translator maps each to a Drizzle helper. */
 export type FilterOperator = (typeof FilterOperator)[keyof typeof FilterOperator];
@@ -188,6 +202,31 @@ export interface FilterSchema {
      * elements inside one rule's value list).
      */
     maxInListLength?: number;
+    /**
+     * Longest string one clause's value may be — applied to each element of an
+     * `in` list as well as to a bare scalar. Defaults to 4096.
+     *
+     * The engine's only ceiling over **text**. Every other budget here bounds
+     * the tree's *structure*, and a caller that never passes a DTO (an alarm
+     * rule replayed out of storage, the copilot's search tool) can carry a
+     * megabyte-long `LIKE` pattern through all of them.
+     */
+    maxValueLength?: number;
+}
+/** Time units a {@link FilterOperator.WithinLast} window may be measured in. */
+export declare const WithinLastUnit: {
+    readonly Minutes: "minutes";
+    readonly Hours: "hours";
+    readonly Days: "days";
+};
+/** One of the {@link WithinLastUnit} values. */
+export type WithinLastUnit = (typeof WithinLastUnit)[keyof typeof WithinLastUnit];
+/** The coerced value of a `within_last` leaf. */
+export interface WithinLastValue {
+    /** How many units back the window reaches. A positive integer. */
+    n: number;
+    /** The unit `n` is counted in. */
+    unit: WithinLastUnit;
 }
 /** Parser output, one node per URL filter entry. */
 export interface ParsedFilter {

package/dist/lib/filters/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,GAAG,GAAG,SAAS,CAAC;AAEnE,8EAA8E;AAC9E,eAAO,MAAM,cAAc;;;;;;;;;;;;;IAavB;;;;;;;;;;;;OAYG;;CAEG,CAAC;AAEX,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GACtB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEzD,+DAA+D;AAC/D,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAEX,oDAAoD;AACpD,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAC9B,+DAA+D;IAC/D,IAAI,EAAE,eAAe,CAAC;IACtB,uCAAuC;IACvC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,oCAAoC;AACpC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,cAAc,GACpB;IACI,iEAAiE;IACjE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC;IACnC,sCAAsC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,0DAA0D;IAC1D,EAAE,EAAE,SAAS,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,GACD;IACI,mCAAmC;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,oBAAoB;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,mEAAmE;IACnE,EAAE,EAAE,SAAS,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gEAAgE;IAChE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,GACD;IACI,gEAAgE;IAChE,IAAI,EAAE,cAAc,CAAC;IACrB,gCAAgC;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,wDAAwD;IACxD,EAAE,EAAE,SAAS,CAAC;IACd,wDAAwD;IACxD,QAAQ,EAAE,SAAS,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,GACD;IACI,uDAAuD;IACvD,IAAI,EAAE,kBAAkB,CAAC;IACzB,yCAAyC;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,4DAA4D;IAC5D,EAAE,EAAE,SAAS,CAAC;IACd;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C,CAAC;AAER,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IACzB,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,gFAAgF;AAChF,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,gDAAgD;AAChD,MAAM,MAAM,cAAc,GACtB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEzD,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC5B,kEAAkE;IAClE,CAAC,EAAE,MAAM,CAAC;IACV,kCAAkC;IAClC,IAAI,EAAE,cAAc,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IACzB,qEAAqE;IACrE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0BAA0B;IAC1B,EAAE,EAAE,cAAc,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC5C,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,UAAU,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC"}

package/dist/lib/filters/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = void 0;
+exports.WithinLastUnit = exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = void 0;
 /** Named constants for `FilterOperator` — use in switches and comparisons. */
 exports.FilterOperator = {
     Eq: 'eq',
@@ -14,7 +14,21 @@ exports.FilterOperator = {
     Like: 'like',
     Ilike: 'ilike',
     Nilike: 'nilike',
-    Null: 'null'
+    Null: 'null',
+    /**
+     * `column >= now() - <n> <unit>` — a window measured from **query time**,
+     * not from the moment the filter was written.
+     *
+     * The distinction is invisible in a URL and decisive in a stored one. The
+     * admin's query builder resolves its own `within_last` into a concrete
+     * `gte` cutoff when it serialises a filter into a link, deliberately: a
+     * shared deep link should keep showing the same rows. A filter that is
+     * *stored and replayed* — an alarm rule — must mean the opposite, or
+     * "not updated in 90 days" silently becomes "not updated since the day the
+     * rule was written". So the operator survives to the server, and the caller
+     * chooses which meaning it wants.
+     */
+    WithinLast: 'within_last'
 };
 /** Named constants for `ScalarFieldType` — use in switches. */
 exports.ScalarFieldType = {
@@ -33,3 +47,9 @@ exports.RelationKind = {
     ManyToMany: 'many-to-many',
     SelfReferential: 'self-referential'
 };
+/** Time units a {@link FilterOperator.WithinLast} window may be measured in. */
+exports.WithinLastUnit = {
+    Minutes: 'minutes',
+    Hours: 'hours',
+    Days: 'days'
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@orthacms/utils-server",
-    "version": "0.4.2",
+    "version": "0.5.0",
     "description": "@orthacms/utils-server — part of Ortha CMS.",
     "license": "MIT",
     "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/utils/server",