@flaredev/core 0.11.0 → 0.12.1

package/dist/{policy-DaK3dWQ_.d.ts → policy-b4FXN3ZJ.d.ts}

@@ -1,3 +1,120 @@
+import { b as RateLimitConfig } from './rate-limit-ClbdZioJ.js';
+
+/**
+ * One shape for every error the API returns.
+ *
+ * There used to be four: `{ error }`, `{ error, field }`, `{ error, issues }` with a
+ * `path` in each issue, and `{ error, issues }` with a `param` in each issue instead —
+ * plus a plain-text `Access denied.` from the security layer. A client had to handle all
+ * of them, and which one it got depended on which guard happened to refuse the request.
+ *
+ * Now there is one:
+ *
+ * ```json
+ * {
+ *   "error": "Number is already taken.",
+ *   "code": "unique_violation",
+ *   "issues": [{ "path": "number", "message": "Number is already taken.", "code": "unique" }]
+ * }
+ * ```
+ *
+ * `error` is for a person — it is the sentence a form or a log shows, and it is the only
+ * field whose wording may change between releases. `code` is for a program: it is stable,
+ * so a client can translate it, branch on it, or decide whether retrying is worth it.
+ * `issues` says which fields, and is present whenever the answer is about fields at all —
+ * one issue for a unique conflict, one per failed rule for a validation error, one per
+ * bad parameter for a query. A client that only wants to put messages under inputs can
+ * read `issues` and ignore everything else.
+ */
+/**
+ * Why a request failed, as a value a program can depend on.
+ *
+ * Add to this rather than inventing a string at a call site: the point of a code is that
+ * it is a closed set a client can switch over.
+ */
+declare const PROBLEM_CODES: {
+    /** The body broke a field's rules. `issues` says which fields. */
+    readonly validationFailed: "validation_failed";
+    /** A unique column already holds this value. `issues` names the column. */
+    readonly uniqueViolation: "unique_violation";
+    /** Deleting this would orphan rows that point at it. */
+    readonly stillReferenced: "still_referenced";
+    /** A relation field names a record that does not exist. */
+    readonly relatedRecordMissing: "related_record_missing";
+    /** A value outside what its column accepts — an enum option that is not one. */
+    readonly valueNotAllowed: "value_not_allowed";
+    /** No such record, or none this request may see. */
+    readonly notFound: "not_found";
+    /** A query parameter is wrong. `issues` names the parameters. */
+    readonly invalidQuery: "invalid_query";
+    /** The body was not JSON. */
+    readonly invalidJson: "invalid_json";
+    /** The request did not say `Content-Type: application/json`. */
+    readonly unsupportedMediaType: "unsupported_media_type";
+    /** A write from another origin: the CSRF guard. */
+    readonly crossOriginBlocked: "cross_origin_blocked";
+    /** No session and no API key. */
+    readonly unauthenticated: "unauthenticated";
+    /** Signed in, but this role may not do this. */
+    readonly forbidden: "forbidden";
+    /** Refused by the security layer before the app saw it. */
+    readonly accessDenied: "access_denied";
+    /** Too many requests. */
+    readonly rateLimited: "rate_limited";
+    /** A signed storage URL that is missing, malformed, expired, or not for this operation. */
+    readonly invalidToken: "invalid_token";
+    /** An upload past the limit the signed URL allows. */
+    readonly payloadTooLarge: "payload_too_large";
+    /** An upload with no Content-Length, which cannot be checked against that limit. */
+    readonly lengthRequired: "length_required";
+    /** A request that is wrong in a way none of the others describes. */
+    readonly badRequest: "bad_request";
+    /** Something went wrong that the server does not explain. */
+    readonly internal: "internal";
+};
+type ProblemCode = (typeof PROBLEM_CODES)[keyof typeof PROBLEM_CODES];
+/**
+ * Why one field is wrong.
+ *
+ * `path` is the field key, dotted for a nested one (`address.city`), or the parameter
+ * name for a query issue. `code` is optional only because a rule that has no better
+ * answer than "invalid" should not be forced to invent one.
+ */
+interface ProblemIssue {
+    path: string;
+    message: string;
+    code?: IssueCode;
+}
+/** Why one field is wrong, as a value a program can depend on. */
+declare const ISSUE_CODES: {
+    /** Broke the field's own rules: a format, a length, a required value. */
+    readonly invalid: "invalid";
+    /** A unique column already holds this. */
+    readonly unique: "unique";
+    /** Set once and not changeable — an ownership column, for instance. */
+    readonly immutable: "immutable";
+    /** A query parameter rather than a body field. */
+    readonly invalidParameter: "invalid_parameter";
+};
+type IssueCode = (typeof ISSUE_CODES)[keyof typeof ISSUE_CODES];
+/** The body of every error response. */
+interface ProblemBody {
+    error: string;
+    code: ProblemCode;
+    issues?: ProblemIssue[];
+}
+/**
+ * Whether this caller wants JSON.
+ *
+ * Used where a guard answers both browsers and programs — the security layer sits in
+ * front of pages as well as the API — because a browser navigation that renders a page of
+ * JSON is worse than one that renders a sentence. An `Accept` header asking for JSON, or
+ * a path under `/api/`, means a program is asking.
+ */
+declare function wantsJson(request: Request): boolean;
+/** An error response in the one shape. */
+declare function problemResponse(status: number, error: string, code: ProblemCode, issues?: ProblemIssue[], init?: ResponseInit): Response;
+
 /**
  * Fields that only apply sometimes.
  *
@@ -72,6 +189,20 @@ interface CommonOptions<T> {
      * time. `required` then means "required *when it applies*" rather than "never null".
      */
     showWhen?: FieldCondition;
+    /**
+     * This field used to be called something else, and the column holds data worth keeping:
+     *
+     *     fullName: field.string({ rename: { from: "name" } })
+     *
+     * Without it a rename is a drop and an add, which empties the column. The descriptor
+     * knows the two names are the same column; the migration should too.
+     *
+     * It applies once. Once the column has been renamed the declaration does nothing, so it
+     * is safe to leave in place and safe to delete on the next edit.
+     */
+    rename?: {
+        from: string;
+    };
 }
 /**
  * What a string holds. Each format is still a text column; the format decides
@@ -351,7 +482,7 @@ interface ResourceConfig<Fields extends Record<string, Field>> {
     /** Field used to represent a record in lists and relation pickers. Default: first string field. */
     titleField?: FieldKey<Fields>;
     defaultSort?: {
-        field: FieldKey<Fields> | "createdAt" | "updatedAt";
+        field: FieldKey<Fields> | "id" | "createdAt" | "updatedAt";
         direction: "asc" | "desc";
     };
     /** Page size for list endpoints and tables. Default 25. */
@@ -370,6 +501,18 @@ interface ResourceConfig<Fields extends Record<string, Field>> {
      * decision rather than an accident.
      */
     softDelete?: boolean;
+    /**
+     * How often each action may be called, per signed-in account (or per IP when there is
+     * nobody signed in):
+     *
+     *     rateLimit: { create: "10/min", "*": "120/min" }
+     *
+     * The named action wins over `*`. Enforced in the generated route, before the store is
+     * touched, so a refused call costs nothing but the count. Worth setting on the actions
+     * that cost something — a create that sends an email, an export that reads the whole
+     * table — rather than on everything.
+     */
+    rateLimit?: RateLimitConfig;
     /**
      * Your logic, beside the fields it belongs to. Every write — the REST API, the
      * dashboard's forms, a seed, an import — goes through the same store, so a hook here
@@ -436,6 +579,8 @@ interface Resource<Fields extends Record<string, Field> = Record<string, Field>>
     perPage: number;
     /** Deleted records are kept and hidden, not removed. See ResourceConfig.softDelete. */
     softDelete: boolean;
+    /** How often each action may be called. See ResourceConfig.rateLimit. */
+    rateLimit?: RateLimitConfig;
     /** Fields with labels filled in. */
     fields: Fields & Record<string, Field & {
         label: string;
@@ -557,4 +702,4 @@ declare function ownershipFilter(policy: Policy | undefined | null, user: {
 /** Actions `role` may perform, for hiding UI it can't use. */
 declare function allowedActions(policy: Policy | undefined | null, role: string | null | undefined): Record<Exclude<PolicyAction, "list">, boolean>;
 
-export { fileMaxBytes as $, type TextField as A, type BelongsToField as B, type CreateInput as C, DEFAULT_FILE_MAX_BYTES as D, type EnumField as E, type Field as F, type TextFormat as G, type HasManyField as H, type IntField as I, type JsonField as J, allowedActions as K, can as L, type MultiSelectField as M, NUMBER_FORMATS as N, clientResource as O, type Policy as P, columnName as Q, type Resource as R, type StoredField as S, TEXT_FORMATS as T, type UpdateInput as U, conditionHolds as V, defaultFieldLabel as W, definePolicy as X, defineResource as Y, describeCondition as Z, field as _, type BooleanField as a, mimeTypesFor as a0, ownershipFilter as a1, storedFields as a2, type ClientResource as b, type DateField as c, type DateTimeField as d, FILE_CATEGORIES as e, type FieldCondition as f, type FieldKind as g, type FieldValue as h, type FileCategory as i, type FileField as j, type FloatField as k, type JsonOptions as l, type NumberFormat as m, type PolicyAction as n, type PolicyConfig as o, PolicyError as p, type PolicyOwnership as q, RESERVED_FIELD_NAMES as r, type RecordOf as s, type ResourceConfig as t, ResourceDefinitionError as u, STRING_FORMATS as v, type StringField as w, type StringFormat as x, type TagsField as y, type TagsOptions as z };
+export { clientResource as $, type RecordOf as A, type BelongsToField as B, type CreateInput as C, DEFAULT_FILE_MAX_BYTES as D, type EnumField as E, type Field as F, type ResourceConfig as G, type HasManyField as H, ISSUE_CODES as I, type JsonField as J, ResourceDefinitionError as K, STRING_FORMATS as L, type MultiSelectField as M, NUMBER_FORMATS as N, type StringField as O, type ProblemCode as P, type StringFormat as Q, type Resource as R, type StoredField as S, TEXT_FORMATS as T, type UpdateInput as U, type TagsField as V, type TagsOptions as W, type TextField as X, type TextFormat as Y, allowedActions as Z, can as _, type ProblemIssue as a, columnName as a0, conditionHolds as a1, defaultFieldLabel as a2, definePolicy as a3, defineResource as a4, describeCondition as a5, field as a6, fileMaxBytes as a7, mimeTypesFor as a8, ownershipFilter as a9, storedFields as aa, type Policy as b, type IssueCode as c, PROBLEM_CODES as d, type ProblemBody as e, type BooleanField as f, type ClientResource as g, type DateField as h, type DateTimeField as i, FILE_CATEGORIES as j, type FieldCondition as k, type FieldKind as l, type FieldValue as m, type FileCategory as n, type FileField as o, problemResponse as p, type FloatField as q, type IntField as r, type JsonOptions as s, type NumberFormat as t, type PolicyAction as u, type PolicyConfig as v, wantsJson as w, PolicyError as x, type PolicyOwnership as y, RESERVED_FIELD_NAMES as z };

package/dist/rate-limit/server.d.ts

@@ -0,0 +1,44 @@
+import { DurableObject } from 'cloudflare:workers';
+import { R as Rate, a as RateLimitDecision } from '../rate-limit-ClbdZioJ.js';
+
+/**
+ * The Cloudflare half of rate limiting: a Durable Object that holds the counters.
+ *
+ * **One instance per resource and action, not per caller.** A Durable Object is a billed
+ * request, so a counter per signed-in user per endpoint would be an invoice rather than a
+ * feature. Instead one object holds a map of caller → count for a single
+ * resource-and-action pair, which is one request per limited call and a handful of
+ * objects for the whole app.
+ *
+ * **Counters live in memory.** If the object is evicted the window restarts, which lets a
+ * caller through earlier than the limit says. That is the right trade here: this is for
+ * stopping one account hammering one endpoint, and the alternative is a storage write on
+ * every request to make the boundary exact. A limit that must hold across an eviction —
+ * a paid quota, say — belongs in the database with the thing it is metering.
+ *
+ * The alarm is what keeps memory flat: every window, whatever has expired is dropped.
+ */
+
+declare class RateLimitCounter extends DurableObject {
+    private counters;
+    /**
+     * Count one call against `key` and say whether it was within `rate`.
+     *
+     * Called through the stub, so the arguments cross a serialization boundary: plain data
+     * only, which is why the rate is passed in rather than configured on the object.
+     */
+    hit(key: string, rate: Rate): Promise<RateLimitDecision>;
+    /** Drop what has expired, and keep sweeping only while something is left. */
+    alarm(): Promise<void>;
+}
+/** What the generated `AppEnv` calls this binding. */
+declare const RATE_LIMIT_BINDING = "FLARE_RATE_LIMIT";
+/** The shape of the binding, so an app can type it without importing the Workers types. */
+interface RateLimitNamespace {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        hit(key: string, rate: Rate): Promise<RateLimitDecision>;
+    };
+}
+
+export { RATE_LIMIT_BINDING, RateLimitCounter, type RateLimitNamespace };

package/dist/rate-limit/server.js

@@ -0,0 +1,45 @@
+import {
+  fixedWindow
+} from "../chunk-I2HSIPCF.js";
+
+// src/rate-limit/server.ts
+import { DurableObject } from "cloudflare:workers";
+var SWEEP_INTERVAL = 6e4;
+var RateLimitCounter = class extends DurableObject {
+  counters = /* @__PURE__ */ new Map();
+  /**
+   * Count one call against `key` and say whether it was within `rate`.
+   *
+   * Called through the stub, so the arguments cross a serialization boundary: plain data
+   * only, which is why the rate is passed in rather than configured on the object.
+   */
+  async hit(key, rate) {
+    const decision = await fixedWindow(rate, async (windowSeconds) => {
+      const now = Date.now();
+      const existing = this.counters.get(key);
+      if (!existing || existing.expires <= now) {
+        const counter = { count: 1, expires: now + windowSeconds * 1e3 };
+        this.counters.set(key, counter);
+        return { count: 1, ttl: windowSeconds };
+      }
+      existing.count += 1;
+      return { count: existing.count, ttl: (existing.expires - now) / 1e3 };
+    });
+    const alarm = await this.ctx.storage.getAlarm();
+    if (alarm === null) await this.ctx.storage.setAlarm(Date.now() + SWEEP_INTERVAL);
+    return decision;
+  }
+  /** Drop what has expired, and keep sweeping only while something is left. */
+  async alarm() {
+    const now = Date.now();
+    for (const [key, counter] of this.counters) {
+      if (counter.expires <= now) this.counters.delete(key);
+    }
+    if (this.counters.size > 0) await this.ctx.storage.setAlarm(now + SWEEP_INTERVAL);
+  }
+};
+var RATE_LIMIT_BINDING = "FLARE_RATE_LIMIT";
+export {
+  RATE_LIMIT_BINDING,
+  RateLimitCounter
+};

package/dist/rate-limit-ClbdZioJ.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Rate limiting per resource and per action.
+ *
+ * A descriptor says how often each action may be called:
+ *
+ * ```ts
+ * rateLimit: { create: "10/min", "*": "120/min" }
+ * ```
+ *
+ * and the generated route enforces it before the store is touched. The point is the
+ * actions that cost something — a create that sends an email, an export that reads the
+ * whole table — not a blanket limit on everything, which is what the edge already does.
+ *
+ * **Why not the platform's own limiter.** Cloudflare has a rate-limiting binding and it
+ * is cheaper than anything here, but its window may only be 10 or 60 seconds and its
+ * limit is fixed in the Worker's configuration rather than per call. A descriptor that
+ * said `"500/hour"` would work on one stack and not the other, and a descriptor that
+ * behaves differently per stack is the one thing Flare does not do. So the counter is
+ * Flare's: a Durable Object on Cloudflare, Redis on Next.js, the same arithmetic on both.
+ *
+ * The edge limiter is still worth having and is unaffected — `flare gen security`
+ * configures it. It stops floods; this stops one signed-in account from calling one
+ * endpoint too often, which is a different question.
+ */
+/** A limit, once parsed: so many calls per so many seconds. */
+interface Rate {
+    limit: number;
+    seconds: number;
+}
+declare class RateSyntaxError extends Error {
+    constructor(message: string);
+}
+/**
+ * `"10/min"` → `{ limit: 10, seconds: 60 }`.
+ *
+ * Also takes a count, as in `"30/5min"`, for the windows between the named ones. Throws
+ * rather than guessing: a rate limit that silently parsed as something else is worse than
+ * one that refuses to generate.
+ */
+declare function parseRate(spec: string): Rate;
+/** Actions a rate limit can be set on, plus `*` for the rest. */
+type RateLimitedAction = "list" | "read" | "create" | "update" | "delete" | "*";
+/** What a descriptor may say about how often it can be called. */
+type RateLimitConfig = Partial<Record<RateLimitedAction, string>>;
+/**
+ * The rate that applies to one action, or undefined when none does.
+ *
+ * The named action wins over `*`, so `{ create: "10/min", "*": "120/min" }` reads as "ten
+ * creates a minute, a hundred and twenty of anything else" rather than both at once.
+ */
+declare function rateFor(config: RateLimitConfig | undefined, action: RateLimitedAction): Rate | undefined;
+/** Every rate a config declares, by action, with its spec — for validation and for docs. */
+declare function ratesIn(config: RateLimitConfig | undefined): {
+    action: RateLimitedAction;
+    spec: string;
+    rate: Rate;
+}[];
+/** What a counter says when it is asked. */
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Calls left in this window, never below zero. */
+    remaining: number;
+    /** Seconds until the window resets — what goes in `Retry-After`. */
+    retryAfter: number;
+}
+/**
+ * Somewhere to keep the counters.
+ *
+ * One method, because that is all a fixed window needs: count this call, and say whether
+ * it was within the limit. Implemented over a Durable Object on Cloudflare and over Redis
+ * on Next.js; both are in the app, in `lib/rate-limit.ts`, and both are yours to replace.
+ */
+interface RateLimitStore {
+    hit(key: string, rate: Rate): Promise<RateLimitDecision>;
+}
+/**
+ * The key a limit is counted against: one bucket per resource, action and caller.
+ *
+ * The caller is the signed-in account where there is one and the IP otherwise, so a limit
+ * on `create` is a limit on that person rather than on everyone sharing an office
+ * connection. Anonymous callers behind one address do share a bucket, which is the right
+ * trade for an endpoint that does not know who is calling.
+ */
+declare const rateLimitKey: (resource: string, action: string, caller: string) => string;
+/**
+ * A fixed-window count, given somewhere to keep a number.
+ *
+ * Shared by both backends so the arithmetic — and the off-by-one at the boundary — is
+ * written once. `increment` returns the count *after* this call and the seconds left in
+ * the window it belongs to.
+ */
+declare function fixedWindow(rate: Rate, increment: (windowSeconds: number) => Promise<{
+    count: number;
+    ttl: number;
+}>): Promise<RateLimitDecision>;
+
+export { type Rate as R, type RateLimitDecision as a, type RateLimitConfig as b, type RateLimitStore as c, type RateLimitedAction as d, RateSyntaxError as e, fixedWindow as f, rateLimitKey as g, ratesIn as h, parseRate as p, rateFor as r };

package/dist/security/worker.js

@@ -1,3 +1,8 @@
+import {
+  PROBLEM_CODES,
+  problemResponse,
+  wantsJson
+} from "../chunk-7NQIVWGG.js";
 import {
   clientIp,
   detectorMatches,
@@ -31,6 +36,12 @@ var SecurityMonitor = class extends DurableObject {
     await this.ctx.storage.deleteAll();
   }
 };
+function refuse(request, status, message, code, extraHeaders = {}) {
+  const headers = { "cache-control": "no-store", ...extraHeaders };
+  if (wantsJson(request)) return problemResponse(status, message, code, void 0, { headers });
+  return new Response(`${message}
+`, { status, headers: { "content-type": "text/plain; charset=utf-8", ...headers } });
+}
 function createSecurity(options) {
   const { config, bans } = options;
   const allowed = new Set(config.allow ?? []);
@@ -93,15 +104,12 @@ function createSecurity(options) {
     if (remembered !== void 0 && remembered <= Date.now()) recentBans.delete(ip);
     if (remembered !== void 0 && remembered > Date.now() || await bans.get(`${BAN_PREFIX}${ip}`)) {
       ctx.waitUntil(monitor(ip).blocked());
-      return new Response("Access denied.", { status: 403, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" } });
+      return refuse(request, 403, "Access denied.", PROBLEM_CODES.accessDenied);
     }
     if (options.rateLimiter && config.rateLimit?.paths.test(new URL(request.url).pathname)) {
       const { success } = await options.rateLimiter.limit({ key: ip });
       if (!success) {
-        return new Response("Too many requests. Slow down and try again shortly.", {
-          status: 429,
-          headers: { "content-type": "text/plain; charset=utf-8", "retry-after": "60", "cache-control": "no-store" }
-        });
+        return refuse(request, 429, "Too many requests. Slow down and try again shortly.", PROBLEM_CODES.rateLimited, { "retry-after": "60" });
       }
     }
     const response = await next();

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
 import { BaseSQLiteDatabase, SQLiteTable, SQLiteColumn } from 'drizzle-orm/sqlite-core';
-import { S as StoredField, R as Resource, F as Field, P as Policy } from './policy-DaK3dWQ_.js';
+import { P as ProblemCode, a as ProblemIssue, R as Resource, F as Field, S as StoredField, b as Policy } from './policy-b4FXN3ZJ.js';
+export { I as ISSUE_CODES, c as IssueCode, d as PROBLEM_CODES, e as ProblemBody, p as problemResponse, w as wantsJson } from './policy-b4FXN3ZJ.js';
+import './rate-limit-ClbdZioJ.js';
 
 /**
  * The handful of things a resource store needs a database to do.
@@ -86,59 +88,6 @@ declare function drizzleRows(table: SQLiteTable, getDb: () => AnyDatabase): Reso
     columns: Record<string, SQLiteColumn>;
 };
 
-interface ListQuery {
-    page: number;
-    perPage: number;
-    sort: {
-        field: string;
-        direction: "asc" | "desc";
-    };
-    q?: string;
-    /** Field key → coerced value; `null` means IS NULL. */
-    filters: Record<string, string | number | boolean | null>;
-    /**
-     * Where to carry on from, instead of counting rows to skip. `OFFSET 500000` makes
-     * SQLite walk half a million index entries before it reads anything (8s at a million
-     * rows); a cursor turns that into a range scan (~100ms).
-     */
-    cursor?: Cursor;
-}
-/** The last row of the page you came from, and which way you're going. */
-interface Cursor {
-    /** The sort field's value on that row. */
-    value: string | number | boolean | null;
-    id: string;
-    direction: "after" | "before";
-}
-interface QueryIssue {
-    param: string;
-    message: string;
-}
-declare function isSortable(def: StoredField): boolean;
-declare function isFilterable(def: StoredField): boolean;
-declare function isSearchable(def: StoredField): boolean;
-/**
- * Parse `?page=2&perPage=50&sort=-createdAt&q=ada&filter[status]=lead` against a
- * resource. Only fields the descriptor marks sortable/filterable/searchable are
- * accepted, so clients can't probe arbitrary columns.
- */
-declare function parseListQuery(resource: Resource, params: URLSearchParams, 
-/**
- * The largest page this caller may ask for.
- *
- * The cap exists to stop a request from the outside asking for ten thousand rows at
- * once. Server-side callers that page through everything deliberately — the CSV
- * export — pass their own, which is why this is an argument rather than a constant
- * everything obeys.
- */
-options?: {
-    maxPerPage?: number;
-}): {
-    query: ListQuery;
-} | {
-    issues: QueryIssue[];
-};
-
 type ResourceAction = "list" | "read" | "create" | "update" | "delete";
 interface FieldIssue {
     /** Dotted field path; "" for the whole body (e.g. unknown keys). */
@@ -148,13 +97,18 @@ interface FieldIssue {
 type Failure = {
     ok: false;
     status: 400 | 404 | 409 | 422;
+    /** The sentence a person reads. Its wording is not part of the contract. */
     error: string;
-    /** Validation issues per field. */
-    issues?: FieldIssue[];
-    /** Invalid query parameters. */
-    queryIssues?: QueryIssue[];
-    /** Field that caused a conflict (e.g. a unique violation). */
-    field?: string;
+    /** Why, as a value a program can switch on. See PROBLEM_CODES. */
+    code: ProblemCode;
+    /**
+     * Which fields, whenever the answer is about fields at all: one issue for a unique
+     * conflict, one per failed rule for a validation error, one per bad parameter for a
+     * query. There used to be three different ways of saying this — `issues` with a
+     * `path`, `issues` with a `param`, and a bare `field` — and a client had to handle all
+     * of them depending on which guard refused it.
+     */
+    issues?: ProblemIssue[];
 };
 type Result<T> = {
     ok: true;
@@ -298,6 +252,59 @@ declare function createResourceHandlers(options: ResourceHandlerOptions): {
     };
 };
 
+interface ListQuery {
+    page: number;
+    perPage: number;
+    sort: {
+        field: string;
+        direction: "asc" | "desc";
+    };
+    q?: string;
+    /** Field key → coerced value; `null` means IS NULL. */
+    filters: Record<string, string | number | boolean | null>;
+    /**
+     * Where to carry on from, instead of counting rows to skip. `OFFSET 500000` makes
+     * SQLite walk half a million index entries before it reads anything (8s at a million
+     * rows); a cursor turns that into a range scan (~100ms).
+     */
+    cursor?: Cursor;
+}
+/** The last row of the page you came from, and which way you're going. */
+interface Cursor {
+    /** The sort field's value on that row. */
+    value: string | number | boolean | null;
+    id: string;
+    direction: "after" | "before";
+}
+interface QueryIssue {
+    param: string;
+    message: string;
+}
+declare function isSortable(def: StoredField): boolean;
+declare function isFilterable(def: StoredField): boolean;
+declare function isSearchable(def: StoredField): boolean;
+/**
+ * Parse `?page=2&perPage=50&sort=-createdAt&q=ada&filter[status]=lead` against a
+ * resource. Only fields the descriptor marks sortable/filterable/searchable are
+ * accepted, so clients can't probe arbitrary columns.
+ */
+declare function parseListQuery(resource: Resource, params: URLSearchParams, 
+/**
+ * The largest page this caller may ask for.
+ *
+ * The cap exists to stop a request from the outside asking for ten thousand rows at
+ * once. Server-side callers that page through everything deliberately — the CSV
+ * export — pass their own, which is why this is an argument rather than a constant
+ * everything obeys.
+ */
+options?: {
+    maxPerPage?: number;
+}): {
+    query: ListQuery;
+} | {
+    issues: QueryIssue[];
+};
+
 /**
  * {@link ResourceRows} over Prisma and Postgres — the Next.js stack's half.
  *
@@ -327,7 +334,7 @@ interface PrismaDelegate {
     update(args: any): Promise<any>;
     delete(args: any): Promise<any>;
 }
-declare function prismaRows(delegate: PrismaDelegate, client: unknown): ResourceRows;
+declare function prismaRows(delegate: PrismaDelegate, client: unknown, resource?: Resource): ResourceRows;
 
 /**
  * An OpenAPI 3.1 document for an app's generated REST API, built at request time
@@ -356,4 +363,4 @@ interface OpenApiOptions {
 declare function fieldJsonSchema(def: StoredField): Schema;
 declare function openApiDocument(options: OpenApiOptions): Schema;
 
-export { type AnyDatabase, type Authorize, type AuthorizeContext, type ChangeEvent, type ConstraintHit, type Failure, type FieldIssue, type ListQuery, type ListResult, type OpenApiOptions, type PrismaDelegate, type QueryIssue, type ResourceAction, type ResourceHandlerOptions, type ResourceRows, type ResourceStore, type ResourceStoreOptions, type Result, type Row, type RowsQuery, createResourceHandlers, createResourceStore, drizzleRows, fieldJsonSchema, isFilterable, isSearchable, isSortable, openApiDocument, parseListQuery, prismaRows };
+export { type AnyDatabase, type Authorize, type AuthorizeContext, type ChangeEvent, type ConstraintHit, type Failure, type FieldIssue, type ListQuery, type ListResult, type OpenApiOptions, type PrismaDelegate, ProblemCode, ProblemIssue, type QueryIssue, type ResourceAction, type ResourceHandlerOptions, type ResourceRows, type ResourceStore, type ResourceStoreOptions, type Result, type Row, type RowsQuery, createResourceHandlers, createResourceStore, drizzleRows, fieldJsonSchema, isFilterable, isSearchable, isSortable, openApiDocument, parseListQuery, prismaRows };