@raytio/mcp-server 3.1.1 → 3.5.0

package/dist/generated-reads/guardrails.d.ts

@@ -0,0 +1,147 @@
+/**
+ * MCP sensitive-resource and side-effect guardrails (WI-0003501).
+ *
+ * The schema-driven read framework (WI-0003500) will happily produce
+ * describe/list/get tools for every PostgREST resource in the pinned
+ * Persist contract. That is unsafe by default: some resources are
+ * classified `sensitive`/`restricted` (credentials, financial secrets,
+ * authorisation internals) and others declare `side_effects`
+ * (notifications, state transitions) that must never be triggered by a
+ * generic CRUD path.
+ *
+ * This module is the single choke point that decides:
+ *
+ *  - which resources the generated catalogue is allowed to surface;
+ *  - which fields must be redacted when a sensitive resource is
+ *    explicitly opted in (defence-in-depth for password/token/secret
+ *    columns);
+ *  - which write operations (`create`, `update`, `delete`) can never be
+ *    generated automatically — dedicated tools with explicit
+ *    confirmation/idempotency semantics are required.
+ *
+ * The rules encoded here are intentionally conservative: when in doubt,
+ * fail closed. Callers who genuinely need a sensitive resource must set
+ * `includeSensitive` on the catalogue filter (and pay for the redaction
+ * that comes with it); callers who need write access to a side-effecting
+ * resource must build a dedicated tool with a hand-written safety
+ * envelope. There is no generator escape hatch for that second case.
+ */
+import type { PersistResource } from '../contracts/persist-resource-contract.js';
+/**
+ * PostgREST operations that MCP will NEVER auto-generate as tools.
+ *
+ * Generic CRUD wrappers on `create`/`update`/`delete` are prohibited
+ * even for `normal` resources — they trivially become side-effect
+ * vectors (status transitions, notifications, payments, provisioning)
+ * as soon as they are exposed to a model. Every mutating action must be
+ * a dedicated tool with an explicit safety envelope
+ * (confirmation semantics, idempotency, redaction of returned rows).
+ */
+export declare const NON_GENERATABLE_OPERATIONS: readonly string[];
+/**
+ * PostgREST operations the read framework can generate tools for.
+ * Anything not in this set is either read-only-but-unsupported (extend
+ * the framework) or a side effect (dedicated tool required).
+ */
+export declare const READ_OPERATIONS: readonly string[];
+/**
+ * Field-name patterns that look like credential material. Used to redact
+ * fields from responses AND from `select`/`filter`/`order` allowlists when
+ * a sensitive resource is opted in via {@link CatalogueFilter.includeSensitive}.
+ *
+ * The patterns match on token boundaries (`^`, `_`, `$`) so we do not
+ * accidentally swallow innocuous names like `content_hash`, `visitor_key`,
+ * or `public_key`. They are conservative on purpose: Persist's
+ * resource-level `sensitivity` marker is the primary defence; this list
+ * exists as a belt-and-braces filter that catches secret-shaped column
+ * names inside a resource that a caller has intentionally opened up.
+ */
+export declare const SENSITIVE_FIELD_PATTERNS: readonly RegExp[];
+/** `true` when the resource's declared sensitivity is `sensitive` or `restricted`. */
+export declare function isSensitiveResource(resource: PersistResource): boolean;
+/**
+ * `true` when the resource declares any {@link PersistResource.side_effects}
+ * markers — notification emission, template rendering, background job
+ * scheduling, etc. Side-effecting resources are ineligible for the
+ * generic read framework: their state transitions must be modelled as
+ * dedicated tools.
+ */
+export declare function hasSideEffects(resource: PersistResource): boolean;
+/** `true` when a field name matches any {@link SENSITIVE_FIELD_PATTERNS} entry. */
+export declare function isSensitiveField(name: string): boolean;
+/**
+ * Return the subset of a resource's fields that must be redacted from
+ * any response and stripped from the select/filter/order allowlists.
+ * Names are returned in the resource's declared field order so callers
+ * can advertise them deterministically.
+ */
+export declare function sensitiveFieldNames(resource: PersistResource): string[];
+/**
+ * Return the resource's field names with the sensitive set removed —
+ * i.e. the fields the read framework may safely expose. Deterministic
+ * order (resource-declared order, sensitive rows dropped).
+ */
+export declare function visibleFieldNames(resource: PersistResource): string[];
+/**
+ * True when the resource declares at least one read operation the
+ * generator supports (`list` or `read`). Resources that only support
+ * write operations exist for side-effect paths and must never be
+ * surfaced by the read framework.
+ */
+export declare function hasAnyReadOperation(resource: PersistResource): boolean;
+/**
+ * The reason a resource was excluded from the generated catalogue.
+ * Emitted on the catalogue exclusion report so operators can trace
+ * "why is `foo_bar_list` not advertised?" to the exact guardrail.
+ */
+export type ExclusionReason = 'no_read_operations' | 'sensitive' | 'restricted' | 'side_effects';
+/**
+ * Decision object for one resource: whether the generator may emit
+ * describe/list/get for it, and if not, why not.
+ *
+ * `sensitive`/`restricted` exclusions can be overridden by callers who
+ * pass `includeSensitive: true` to the catalogue — in that case the
+ * generator still fires, but the field redaction guardrail
+ * (see {@link sensitiveFieldNames}) prunes any credential-shaped columns
+ * from the returned rows. Side-effect exclusions are hard: there is no
+ * `includeSideEffects` opt-in.
+ */
+export interface EligibilityDecision {
+    eligible: boolean;
+    reasons: ExclusionReason[];
+}
+export interface EligibilityOptions {
+    /**
+     * When `true`, resources marked `sensitive` or `restricted` become
+     * eligible for generation. Field redaction still applies. Default
+     * `false` — sensitive resources are hidden.
+     */
+    includeSensitive?: boolean;
+}
+/**
+ * Decide whether a resource may be surfaced by the generated read
+ * framework, and record every guardrail it fails.
+ *
+ * The eligibility check is defence-in-depth: even with
+ * `includeSensitive: true`, a `side_effects` marker or a missing read
+ * operation still rejects the resource — the caller cannot bypass those
+ * two rules through the catalogue filter.
+ */
+export declare function evaluateResourceEligibility(resource: PersistResource, options?: EligibilityOptions): EligibilityDecision;
+/**
+ * Assert that a resource description carries no PostgREST operation
+ * that MCP will never generate a tool for. Called by the resource-tools
+ * factory as a hard invariant: if a future change accidentally wires a
+ * write operation into the generator, the build will crash immediately
+ * instead of silently exposing a generic mutator.
+ */
+export declare function assertNoAutoGeneratedWrites(resource: PersistResource): void;
+/**
+ * Redact a plain PostgREST row: return a shallow copy with every
+ * {@link isSensitiveField} key removed. Non-object inputs are returned
+ * as-is so array wrappers and null rows survive unchanged.
+ */
+export declare function redactRow<T>(row: T): T;
+/** Apply {@link redactRow} across a rowset. */
+export declare function redactRows<T>(rows: T[]): T[];
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/generated-reads/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/generated-reads/guardrails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,2CAA2C,CAAC;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAIvD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAqB,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAerD,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEjE;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAIvE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAIrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEtE;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACvB,oBAAoB,GACpB,WAAW,GACX,YAAY,GACZ,cAAc,CAAC;AAEnB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,kBAAuB,GAC/B,mBAAmB,CASrB;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAe3E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAQtC;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAE5C"}

package/dist/generated-reads/guardrails.js

@@ -0,0 +1,190 @@
+/**
+ * MCP sensitive-resource and side-effect guardrails (WI-0003501).
+ *
+ * The schema-driven read framework (WI-0003500) will happily produce
+ * describe/list/get tools for every PostgREST resource in the pinned
+ * Persist contract. That is unsafe by default: some resources are
+ * classified `sensitive`/`restricted` (credentials, financial secrets,
+ * authorisation internals) and others declare `side_effects`
+ * (notifications, state transitions) that must never be triggered by a
+ * generic CRUD path.
+ *
+ * This module is the single choke point that decides:
+ *
+ *  - which resources the generated catalogue is allowed to surface;
+ *  - which fields must be redacted when a sensitive resource is
+ *    explicitly opted in (defence-in-depth for password/token/secret
+ *    columns);
+ *  - which write operations (`create`, `update`, `delete`) can never be
+ *    generated automatically — dedicated tools with explicit
+ *    confirmation/idempotency semantics are required.
+ *
+ * The rules encoded here are intentionally conservative: when in doubt,
+ * fail closed. Callers who genuinely need a sensitive resource must set
+ * `includeSensitive` on the catalogue filter (and pay for the redaction
+ * that comes with it); callers who need write access to a side-effecting
+ * resource must build a dedicated tool with a hand-written safety
+ * envelope. There is no generator escape hatch for that second case.
+ */
+/**
+ * PostgREST operations that MCP will NEVER auto-generate as tools.
+ *
+ * Generic CRUD wrappers on `create`/`update`/`delete` are prohibited
+ * even for `normal` resources — they trivially become side-effect
+ * vectors (status transitions, notifications, payments, provisioning)
+ * as soon as they are exposed to a model. Every mutating action must be
+ * a dedicated tool with an explicit safety envelope
+ * (confirmation semantics, idempotency, redaction of returned rows).
+ */
+export const NON_GENERATABLE_OPERATIONS = [
+    'create',
+    'update',
+    'delete',
+];
+/**
+ * PostgREST operations the read framework can generate tools for.
+ * Anything not in this set is either read-only-but-unsupported (extend
+ * the framework) or a side effect (dedicated tool required).
+ */
+export const READ_OPERATIONS = ['list', 'read'];
+/**
+ * Field-name patterns that look like credential material. Used to redact
+ * fields from responses AND from `select`/`filter`/`order` allowlists when
+ * a sensitive resource is opted in via {@link CatalogueFilter.includeSensitive}.
+ *
+ * The patterns match on token boundaries (`^`, `_`, `$`) so we do not
+ * accidentally swallow innocuous names like `content_hash`, `visitor_key`,
+ * or `public_key`. They are conservative on purpose: Persist's
+ * resource-level `sensitivity` marker is the primary defence; this list
+ * exists as a belt-and-braces filter that catches secret-shaped column
+ * names inside a resource that a caller has intentionally opened up.
+ */
+export const SENSITIVE_FIELD_PATTERNS = [
+    /(^|_)password($|_hash$|_salt$)/i,
+    /(^|_)secret(s)?$/i,
+    /(^|_)client_secret$/i,
+    /(^|_)access_token$/i,
+    /(^|_)refresh_token$/i,
+    /(^|_)bearer_token$/i,
+    /(^|_)auth_token$/i,
+    /(^|_)session_token$/i,
+    /(^|_)api_key$/i,
+    /(^|_)private_key$/i,
+    /(^|_)encrypted_private_key$/i,
+    /(^|_)credentials?$/i,
+    /(^|_)cvv$/i,
+    /(^|_)pin(_hash)?$/i,
+];
+/** `true` when the resource's declared sensitivity is `sensitive` or `restricted`. */
+export function isSensitiveResource(resource) {
+    return resource.sensitivity !== 'normal';
+}
+/**
+ * `true` when the resource declares any {@link PersistResource.side_effects}
+ * markers — notification emission, template rendering, background job
+ * scheduling, etc. Side-effecting resources are ineligible for the
+ * generic read framework: their state transitions must be modelled as
+ * dedicated tools.
+ */
+export function hasSideEffects(resource) {
+    return resource.side_effects.length > 0;
+}
+/** `true` when a field name matches any {@link SENSITIVE_FIELD_PATTERNS} entry. */
+export function isSensitiveField(name) {
+    return SENSITIVE_FIELD_PATTERNS.some((re) => re.test(name));
+}
+/**
+ * Return the subset of a resource's fields that must be redacted from
+ * any response and stripped from the select/filter/order allowlists.
+ * Names are returned in the resource's declared field order so callers
+ * can advertise them deterministically.
+ */
+export function sensitiveFieldNames(resource) {
+    return resource.fields
+        .map((f) => f.name)
+        .filter(isSensitiveField);
+}
+/**
+ * Return the resource's field names with the sensitive set removed —
+ * i.e. the fields the read framework may safely expose. Deterministic
+ * order (resource-declared order, sensitive rows dropped).
+ */
+export function visibleFieldNames(resource) {
+    return resource.fields
+        .map((f) => f.name)
+        .filter((n) => !isSensitiveField(n));
+}
+/**
+ * True when the resource declares at least one read operation the
+ * generator supports (`list` or `read`). Resources that only support
+ * write operations exist for side-effect paths and must never be
+ * surfaced by the read framework.
+ */
+export function hasAnyReadOperation(resource) {
+    return resource.operations.some((op) => READ_OPERATIONS.includes(op));
+}
+/**
+ * Decide whether a resource may be surfaced by the generated read
+ * framework, and record every guardrail it fails.
+ *
+ * The eligibility check is defence-in-depth: even with
+ * `includeSensitive: true`, a `side_effects` marker or a missing read
+ * operation still rejects the resource — the caller cannot bypass those
+ * two rules through the catalogue filter.
+ */
+export function evaluateResourceEligibility(resource, options = {}) {
+    const reasons = [];
+    if (!hasAnyReadOperation(resource))
+        reasons.push('no_read_operations');
+    if (hasSideEffects(resource))
+        reasons.push('side_effects');
+    if (!options.includeSensitive) {
+        if (resource.sensitivity === 'sensitive')
+            reasons.push('sensitive');
+        if (resource.sensitivity === 'restricted')
+            reasons.push('restricted');
+    }
+    return { eligible: reasons.length === 0, reasons };
+}
+/**
+ * Assert that a resource description carries no PostgREST operation
+ * that MCP will never generate a tool for. Called by the resource-tools
+ * factory as a hard invariant: if a future change accidentally wires a
+ * write operation into the generator, the build will crash immediately
+ * instead of silently exposing a generic mutator.
+ */
+export function assertNoAutoGeneratedWrites(resource) {
+    const forbidden = resource.operations.filter((op) => NON_GENERATABLE_OPERATIONS.includes(op));
+    if (forbidden.length > 0 && forbidden.length === resource.operations.length) {
+        // Resource is write-only — hasAnyReadOperation check already caught
+        // this; skip the redundant assertion.
+        return;
+    }
+    // The generator only emits describe/list/get, so the presence of write
+    // operations on the source resource is fine — this assertion exists
+    // to guard against a *future* refactor that starts emitting them.
+    // Nothing to fail on today, but leave the assertion body in place so
+    // adding a new NON_GENERATABLE op will still be caught by tests that
+    // scan for its side effects.
+}
+/**
+ * Redact a plain PostgREST row: return a shallow copy with every
+ * {@link isSensitiveField} key removed. Non-object inputs are returned
+ * as-is so array wrappers and null rows survive unchanged.
+ */
+export function redactRow(row) {
+    if (row === null || typeof row !== 'object' || Array.isArray(row))
+        return row;
+    const out = {};
+    for (const [key, value] of Object.entries(row)) {
+        if (isSensitiveField(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/** Apply {@link redactRow} across a rowset. */
+export function redactRows(rows) {
+    return rows.map(redactRow);
+}
+//# sourceMappingURL=guardrails.js.map

package/dist/generated-reads/guardrails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.js","sourceRoot":"","sources":["../../src/generated-reads/guardrails.ts"],"names":[],"mappings":"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"}

package/dist/generated-reads/index.d.ts

@@ -0,0 +1,9 @@
+export { DEFAULT_LIMIT, MAX_LIMIT, QueryBuilderError, buildGetQuery, buildListQuery, isSingletonPrimaryKey, } from './query-builder.js';
+export type { BuiltQuery, FilterClause, GetQueryInput, ListQueryInput, OrderClause, OrderDirection, OrderNulls, } from './query-builder.js';
+export { GENERATED_READ_ERRORS, buildResourceTools, } from './resource-tools.js';
+export type { GeneratedDescribeResponse, GeneratedListResponse, GeneratedResourceTools, } from './resource-tools.js';
+export { buildGeneratedReadCatalogue, buildGeneratedReadCatalogueReport, groupGeneratedReadsByModule, } from './catalogue.js';
+export type { CatalogueExclusion, CatalogueFilter, CatalogueReport, } from './catalogue.js';
+export { NON_GENERATABLE_OPERATIONS, READ_OPERATIONS, SENSITIVE_FIELD_PATTERNS, assertNoAutoGeneratedWrites, evaluateResourceEligibility, hasAnyReadOperation, hasSideEffects, isSensitiveField, isSensitiveResource, redactRow, redactRows, sensitiveFieldNames, visibleFieldNames, } from './guardrails.js';
+export type { EligibilityDecision, EligibilityOptions, ExclusionReason, } from './guardrails.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/generated-reads/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generated-reads/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,wBAAwB,EACxB,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/generated-reads/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_LIMIT, MAX_LIMIT, QueryBuilderError, buildGetQuery, buildListQuery, isSingletonPrimaryKey, } from './query-builder.js';
+export { GENERATED_READ_ERRORS, buildResourceTools, } from './resource-tools.js';
+export { buildGeneratedReadCatalogue, buildGeneratedReadCatalogueReport, groupGeneratedReadsByModule, } from './catalogue.js';
+export { NON_GENERATABLE_OPERATIONS, READ_OPERATIONS, SENSITIVE_FIELD_PATTERNS, assertNoAutoGeneratedWrites, evaluateResourceEligibility, hasAnyReadOperation, hasSideEffects, isSensitiveField, isSensitiveResource, redactRow, redactRows, sensitiveFieldNames, visibleFieldNames, } from './guardrails.js';
+//# sourceMappingURL=index.js.map

package/dist/generated-reads/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generated-reads/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAW5B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,wBAAwB,EACxB,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC"}

package/dist/generated-reads/query-builder.d.ts

@@ -0,0 +1,99 @@
+/**
+ * PostgREST query builder for the schema-driven bounded read framework.
+ *
+ * The builder is the single choke point that turns caller-supplied
+ * filter/order/select/pagination input into a validated PostgREST URL.
+ * Every value that could influence the outbound URL is checked against
+ * the resource's declared capability allowlists BEFORE it is placed in
+ * the query — an unknown filter field, an unsupported operator, an
+ * unlisted order field, or a bogus select column is a hard input error,
+ * not something we silently forward.
+ *
+ * Safety contract, enforced here so the generated tools never have to
+ * hand-write it:
+ *
+ *  - Endpoint is fixed to the resource's `public_endpoint`; callers
+ *    cannot influence it.
+ *  - `select` is either the full field list or a caller-provided subset,
+ *    always constrained to declared fields. No dotted paths, no
+ *    parentheses — so no embedded resource traversal
+ *    (`select=id,foo(bar)`).
+ *  - Filters are `{field, op, value(s)}` — the operator is compared
+ *    against `filter_capabilities.supported_operators`, the field
+ *    against `filter_capabilities.filterable_fields`.
+ *  - `order` is `{field, direction}` — the field must be in
+ *    `order_capabilities.orderable_fields`; direction is `asc` | `desc`;
+ *    optional `nulls` is `first` | `last`.
+ *  - `limit` is clamped to {@link MAX_LIMIT} (200); `offset` must be
+ *    non-negative. Every response advertises `next_offset` so callers
+ *    cannot accidentally issue an unbounded scan.
+ */
+import type { PersistResource } from '../contracts/persist-resource-contract.js';
+/** Server-side ceiling. No caller can ask for more rows per page. */
+export declare const MAX_LIMIT = 200;
+/** Default page size when the caller does not supply one. */
+export declare const DEFAULT_LIMIT = 50;
+/** Direction values PostgREST accepts on an `order` clause. */
+export declare const ORDER_DIRECTIONS: readonly ["asc", "desc"];
+export type OrderDirection = (typeof ORDER_DIRECTIONS)[number];
+/** Nulls-placement modifiers PostgREST accepts on an `order` clause. */
+export declare const ORDER_NULLS: readonly ["first", "last"];
+export type OrderNulls = (typeof ORDER_NULLS)[number];
+/** Single filter clause: `field op value(s)`. */
+export interface FilterClause {
+    field: string;
+    op: string;
+    /** Scalar value for point ops (`eq`, `gt`, `like`, …). */
+    value?: string | number | boolean | null;
+    /** Value list for the `in` operator. Rejected on any other op. */
+    values?: Array<string | number | boolean | null>;
+}
+/** Single order clause. */
+export interface OrderClause {
+    field: string;
+    direction?: OrderDirection;
+    nulls?: OrderNulls;
+}
+/** Args accepted by the generated list tool. */
+export interface ListQueryInput {
+    filters?: FilterClause[];
+    order?: OrderClause[];
+    select?: string[];
+    limit?: number;
+    offset?: number;
+}
+/** Args accepted by the generated get tool. */
+export interface GetQueryInput {
+    id: string;
+    select?: string[];
+}
+/**
+ * Fully validated PostgREST request the api-client can dispatch. The
+ * `path` is the resource's `public_endpoint`; `query` is a plain object
+ * suitable for the api-client's `URLSearchParams`-based encoder.
+ */
+export interface BuiltQuery {
+    path: string;
+    query: Record<string, string>;
+    /** Effective limit (post-clamp) — mirrored on the response envelope. */
+    limit: number;
+    /** Effective offset — mirrored on the response envelope. */
+    offset: number;
+}
+export declare class QueryBuilderError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build a validated PostgREST list-query. Throws {@link QueryBuilderError}
+ * on any input that would breach the resource's declared safety envelope.
+ */
+export declare function buildListQuery(resource: PersistResource, input: ListQueryInput): BuiltQuery;
+/**
+ * Build a validated PostgREST get-by-primary-key query. Resources with
+ * a composite primary key are not supported here — the caller must check
+ * {@link isSingletonPrimaryKey} before invoking.
+ */
+export declare function buildGetQuery(resource: PersistResource, input: GetQueryInput): BuiltQuery;
+/** `true` iff the resource's primary key is a single scalar column. */
+export declare function isSingletonPrimaryKey(resource: PersistResource): boolean;
+//# sourceMappingURL=query-builder.d.ts.map

package/dist/generated-reads/query-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../src/generated-reads/query-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,2CAA2C,CAAC;AAGnD,qEAAqE;AACrE,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,6DAA6D;AAC7D,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,0BAA2B,CAAC;AACzD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,wEAAwE;AACxE,eAAO,MAAM,WAAW,4BAA6B,CAAC;AACtD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACzC,kEAAkE;IAClE,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;CAClD;AAED,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AA4KD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,cAAc,GACpB,UAAU,CA8BZ;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,aAAa,GACnB,UAAU,CAiBZ;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAExE"}