@xano/sdk 1.0.0

package/dist/response-HlXahv4K.d.ts

@@ -0,0 +1,925 @@
+import { V as Value, i as FilterXdo, S as StackItemXdo, r as ResultItemXdo } from './xdo-CxDr2Q1C.js';
+
+/**
+ * A statement's per-test MOCK — the value a step returns instead of doing its
+ * work, when one specific test runs.
+ *
+ * Authored keyed by TEST NAME, which is what the Xano editor shows and what
+ * XanoScript spells. The stored form is keyed by test ID; the rewrite happens
+ * at kind-encode time, the only place that knows both the stack and the test
+ * list (see `../kinds/test-mocks.js`).
+ *
+ * A mock applies ONLY while its test runs. It has no effect on a normal
+ * request, so mocking a step does not change what the deployed endpoint does.
+ */
+
+/**
+ * One mock: a value, or a value plus `enabled`.
+ *
+ * The bare form means enabled. The object form exists so a mock can be kept
+ * around switched off — the editor stores a disabled mock rather than deleting
+ * it, and dropping it on encode would lose an authored artefact.
+ */
+type MockEntry = Value | {
+    value: Value;
+    enabled?: boolean;
+};
+/** A statement's mocks, keyed by the name of the test each applies to. */
+type MockMap = Record<string, MockEntry>;
+/** The stored `mvp_test_mock` shape. */
+interface MockXdo {
+    value: string;
+    tag: string;
+    filters: unknown[];
+    enabled: boolean;
+}
+
+/**
+ * Statement model, base envelope encoder, and registry (the extensibility
+ * seam).
+ *
+ * The real stored statement shape (from the golden fixture's `run[0]`) is lean:
+ * `{name, as?, context, input}`. The base encoder fills the common envelope
+ * (`input: []` default) so each concrete statement factory only declares its
+ * `name`, optional `as`, and `context`. The registry maps statement name →
+ * factory so the eventual ~500-statement catalog plugs in here.
+ */
+
+/**
+ * The type-level contract linking a branded db statement (the **producer** —
+ * `db.get`/`db.query`/`db.add`/`db.edit`/`db.patch`/`db.add_or_edit`/`db.has`/
+ * `db.bulk.patch`/`db.bulk.delete`, each returning `Statement & AsShapeBrand<…>`)
+ * to `InferResponse`'s single-variable trace (the **consumer** — `TraceVar`,
+ * which destructures this shape). Both `__as` (the stack variable the statement
+ * binds) and `__shape` (the row shape it produces) are phantom carriers — never
+ * present at runtime. Naming the contract here keeps producer and consumer
+ * compiler-linked, so any further branded statement joins the trace by extending
+ * this type with zero edits to the trace logic.
+ */
+type AsShapeBrand<As extends string, Shape> = {
+    readonly __as: As;
+    readonly __shape: Shape;
+};
+/**
+ * The type-level mark of a statement that PROVES the stack variable `Name` is
+ * non-null by the time the next statement runs — `guard.found` (and
+ * `guard.owner`'s first step), which raise before continuing on a null binding.
+ * `InferResponse`'s trace drops `| null` from `Name`'s shape when one follows its
+ * binding. Phantom like {@link AsShapeBrand}: never present at runtime.
+ */
+type FoundBrand<Name extends string> = {
+    readonly __found: Name;
+};
+/**
+ * The type-level mark of a statement whose sub-stack `Body` ALWAYS runs, in
+ * place — `db.transaction`, `group`, and `try_catch`'s `finally`.
+ * `InferResponse`'s trace reads `Body` as if it sat inline, so a binding made
+ * inside one is visible. A conditional body carries none. Phantom: never
+ * present at runtime.
+ */
+type BodyBrand<Body extends readonly unknown[]> = {
+    readonly __body: Body;
+};
+/**
+ * The type-level mark of a sub-stack that MAY run — a loop body, a conditional
+ * branch, a switch case. A re-binding inside it unions with the binding from
+ * before it (it may never happen), and an {@link AppendBrand} inside it widens
+ * the list it appends to. Phantom.
+ */
+type MaybeBodyBrand<Body extends readonly unknown[]> = {
+    readonly __maybe: Body;
+};
+/**
+ * The type-level mark of an in-place list mutator (`array.push`/`unshift`, and
+ * `merge` spreading a list): stack variable `Name` gains `Value`'s type as an
+ * element, so an accumulator seeded with `c.array([])` traces to that element's
+ * list instead of the empty tuple it was bound as. Phantom.
+ */
+type AppendBrand<Name extends string, V, Spread extends boolean = false> = {
+    readonly __append: readonly [Name, V, Spread];
+};
+/**
+ * The type-level mark of a `try_catch`. `try` runs in place but may stop at any
+ * statement, and `catch` may run in place of the rest of it: a name `try`
+ * re-binds unions with its binding from before, and a name BOTH bind is either
+ * one after it. Phantom: never present at runtime.
+ */
+type CatchBrand<Try extends readonly unknown[], Catch extends readonly unknown[]> = {
+    readonly __catch: [Try, Catch];
+};
+/**
+ * The type-level mark of a statement that runs EXACTLY ONE of `Branches` — a
+ * `conditional`'s `then`, each `elif` and `else`, or a `switch`'s cases and
+ * `default`. When every branch re-binds a name at its top level the value from
+ * before is gone, so `InferResponse` traces the union of the branches alone. A
+ * missing `else`/`default` is an empty branch, which re-binds nothing. Phantom.
+ */
+type BranchesBrand<Branches extends readonly (readonly unknown[])[]> = {
+    readonly __branches: Branches;
+};
+/**
+ * The type-level mark of a dotted `s.update_var("row.title", …)`: member `Path`
+ * of stack variable `Name` now holds `Shape`, so `InferResponse` sets that
+ * member's type (a union with the old one where the update may not run). Phantom.
+ */
+type MemberUpdateBrand<Name extends string, Path extends string, Shape> = {
+    readonly __memberUpdate: readonly [Name, Path, Shape];
+};
+/**
+ * The two envelope members every stack item carries, whatever it does.
+ *
+ * They are editor affordances rather than statement arguments — `disabled` is
+ * how a step is commented out (it stays in the stack; the run engine skips it),
+ * and `description` is the note shown on the step. `encodeStatement` writes both
+ * for every statement, so every factory accepts them: the generated ones as two
+ * more optional fields on their argument object, the positional specials as a
+ * trailing options argument.
+ *
+ * Both are elided at their defaults on both sides of a round trip, so setting one
+ * to `false`/`""` is the same bytes as omitting it.
+ */
+interface StatementAnnotations {
+    /** Leave the step in the stack but skip it at runtime — Xano's "disable step". */
+    disabled?: boolean;
+    /** Free-text note on the step, shown in the editor beside it. */
+    description?: string;
+    /**
+     * Per-test MOCKS — what this step returns instead of running, keyed by the
+     * name of the test the mock applies to.
+     *
+     * `{ "happy path": c.int(1) }` makes the step return `1` while the test named
+     * "happy path" runs, and changes nothing about a normal request. Wrap an
+     * entry as `{ value, enabled: false }` to keep a mock switched off.
+     *
+     * Every name must match a test declared on the object this statement belongs
+     * to; an unmatched name throws at encode time, because the engine silently
+     * ignores a mock whose key is not a real test id.
+     */
+    mock?: MockMap;
+}
+/**
+ * {@link StatementAnnotations} plus the result-filter option, for the statements
+ * that bind an `as` variable.
+ *
+ * Split from the annotations rather than folded into them so `asFilters` is only
+ * offered where there is a binding to attach it to: a statement that returns
+ * nothing (`precondition`, `switch`, `while`, …) should not surface the option
+ * in autocomplete at all. The runtime guard in {@link assertBindsAs} still
+ * backs this up for callers that reach past the types.
+ */
+interface StatementOptions extends StatementAnnotations {
+    /**
+     * Filters piped onto the result before it is bound — the editor's
+     * `return as token | upper`.
+     *
+     * Authored from the same `fl.*` catalog as value filters and applied in
+     * order, so `asFilters: [fl.trim(), fl.upper()]` trims and then upper-cases.
+     *
+     * The bound variable is RETYPED by the chain: `InferResponse` folds each
+     * filter's declared result, so a `db.query` bound through `[fl.count()]` is a
+     * `number`. Filters the engine declares as returning `any` (`get`, `set`,
+     * `json_decode`, …) fold to `unknown` — see `values/filter-result.ts`.
+     */
+    asFilters?: FilterXdo[];
+}
+/**
+ * Apply {@link StatementOptions} to a built statement.
+ *
+ * Only members that were actually authored are copied, so a factory's own
+ * `description` (a few statements route one) is not clobbered by an absent key.
+ *
+ * `asFilters` merges into the `output` envelope rather than replacing it: a db
+ * statement's column selection (`output.items`) and its result filters live in
+ * the same block, and dropping one to write the other would silently discard
+ * whichever the factory set first.
+ */
+declare function annotate<T extends Statement>(stmt: T, a?: StatementOptions): T;
+/** What a statement factory returns before base-envelope encoding. */
+interface Statement {
+    name: string;
+    as?: string;
+    context: unknown;
+    input?: unknown[];
+    /** `output` envelope. Lean (`{filters:[]}`) or rich (`{customize,filters,items}`) forms are both accepted and normalized to the full rich form. */
+    output?: unknown;
+    /** Statement description (defaults to `""`). */
+    description?: string;
+    /** Settings-registry bindings (defaults to `null`). */
+    settings_registry?: unknown[] | null;
+    /** Attached addons (defaults to `[]`). */
+    addon?: unknown[];
+    /** Async/runtime block (e.g. `mvp:call_agent`'s `{ mode }`); defaults to `null`. */
+    runtime?: unknown;
+    /**
+     * Encoded per-test mocks, keyed by test NAME until the owning kind rewrites
+     * the keys to test ids. Authored via the `mock` option, not set directly.
+     */
+    mocks?: Record<string, MockXdo> | unknown;
+    /** Whether the statement is disabled in the stack (defaults to `false`). */
+    disabled?: boolean;
+}
+/**
+ * Return a statement sequence from a helper **without losing the tuple**.
+ *
+ * `InferResponse` traces the `as` binding a `response` names by walking the
+ * stack's TUPLE type. Spreading anything typed `Statement[]` widens the whole
+ * array, and every binding — including ones declared *after* the spread —
+ * becomes invisible, so the response silently resolves to
+ * {@link StackTupleWidened}. A helper that emits more than one statement has to
+ * return an array, so any shared helper triggers it:
+ *
+ * ```ts
+ * // ✗ widens: every `as` in the calling stack stops being traceable
+ * function assertOk(v: string): Statement[] { return [s.lambda({…}), s.precondition({…})]; }
+ *
+ * // ✓ tuple survives the spread
+ * function assertOk(v: string) { return statements(s.lambda({…}), s.precondition({…})); }
+ * ```
+ *
+ * Type-level only — the returned array is the arguments verbatim, so there is no
+ * encoder involvement and no cost.
+ *
+ * **Fixed arity only.** A helper that builds its array in a loop cannot be a
+ * tuple; declare `responseShape` on the calling def instead.
+ */
+declare function statements<const T extends readonly Statement[]>(...items: T): T;
+/** True when a statement name has a registered factory. */
+declare function isRegisteredStatement(name: string): boolean;
+/** Look up a registered factory, throwing a clear error when absent. */
+declare function getStatementFactory(name: string): (...args: any[]) => Statement;
+declare function encodeStatement(stmt: Statement): StackItemXdo;
+
+/**
+ * Shared field encoder. Function inputs and table columns are nearly
+ * the same stored shape; this encoder fills the common defaults and is
+ * parameterized by a `FieldContext` for the three spots where they differ:
+ * `customize` (`""` vs `{}`), `market_item` id types (string vs numeric), and
+ * whether `description` is emitted.
+ */
+
+/** Field visibility — the engine's `access` enum. */
+type FieldAccess = "public" | "private" | "internal";
+/** Valid `format` values for text fields (per the engine's text-field schema). */
+type TextFormat = "" | "plaintext" | "yaml" | "html" | "xml" | "markdown";
+/** Field cardinality — `"single"` (scalar) or `"list"` (array column). */
+type FieldStyleType = "single" | "list";
+interface FieldOptions {
+    required?: boolean;
+    nullable?: boolean;
+    /**
+     * Default value. Authored as a `string`, `number`, or `boolean` for
+     * ergonomics (`default: 0`, `default: false`); the engine stores it as a
+     * string, so it's coerced at encode time (`0` → `"0"`, `false` → `"false"`).
+     *
+     * On a **table column** the default must stay within the Basic Multilingual
+     * Plane: a 4-byte character (codepoint > U+FFFF — emoji, CJK-extension glyphs)
+     * is mangled into an invalid UTF-8 sequence by the engine's default pipeline
+     * and is rejected at export/encode time rather than 500ing at deploy with
+     * Postgres `22021`. BMP characters (accents, `€`, most CJK) store
+     * fine. A *function/endpoint input* default binds at runtime and has no limit.
+     */
+    default?: string | number | boolean;
+    /**
+     * Persist **no `default` key at all** for this field, rather than the empty
+     * `default: ""` every other field carries.
+     *
+     * Set on a table's `uuid` PRIMARY KEY, which is the one column the engine
+     * stores this way — its value is engine-generated, so there is nothing for a
+     * default to mean, and absent vs empty are different stored bytes. Applied
+     * automatically by `idType: "uuid"`; you rarely set it by hand.
+     *
+     * NOT a property of `uuid` in general: an ordinary (non-key) `uuid` column
+     * does carry `default: ""`. Mutually exclusive with {@link default}.
+     */
+    noDefault?: boolean;
+    description?: string;
+    /**
+     * Methods/filters applied at bind time. Each entry is either a bare name
+     * (`"trim"`), a colon-form string with args (`"min:8"` → `{name:"min",
+     * arg:["8"]}`), or an explicit `{ name, arg }` object.
+     */
+    methods?: MethodSpec[];
+    /** Enum values (for `type:"enum"` fields), e.g. `["draft","live"]`. */
+    values?: Array<string | number>;
+    mode?: string;
+    /** Text-field display format (text fields only; the engine drops it elsewhere). */
+    format?: TextFormat;
+    sensitive?: boolean;
+    /**
+     * Merge the referenced object's fields into this one rather than nesting them.
+     *
+     * **Leave this unset** unless reproducing a pulled field. It defaults to `false`,
+     * which is what every field this SDK authors from scratch wants; it is here so a
+     * pulled workspace's field can be recovered as a readable `f.*` call instead of
+     * degrading to `rawField()`. Paired with {@link hidden} in the wild — 584 fields
+     * across the sweep carry `merge: true` with a `hidden` list beside it.
+     */
+    merge?: boolean;
+    /**
+     * Names to hide from this field's expansion (e.g. `["created_at"]`).
+     *
+     * **Leave this unset** unless reproducing a pulled field; it defaults to `[]`.
+     * Each entry is resolved as a name and removed from the expanded shape, so an
+     * entry naming nothing hides nothing — a stored `[""]` is a real spelling that
+     * appears in the wild and round-trips verbatim here rather than being guessed at.
+     */
+    hidden?: readonly string[];
+    /** Field visibility in API output. Defaults to `"public"`. */
+    access?: FieldAccess;
+    style?: {
+        type: FieldStyleType;
+    };
+    /**
+     * Length bounds for an array field. Both members are `json`-typed in the
+     * engine, not numeric — the editor declares them as `json` and every consumer
+     * reads them through a numeric coercion (`+list.max`) — so a bound can arrive
+     * as `5` or as `"5"` and neither spelling is wrong.
+     *
+     * That is also why "unset" has no single spelling: an empty `json` control
+     * serializes to `""` on 8,814 fields in the sweep and to `{}` on two. Codegen
+     * elides the block whenever every member is blank in either form (see
+     * `hasNoListBounds`), so only a bound that is actually SET reaches this type.
+     */
+    list?: {
+        min?: string | number;
+        max?: string | number;
+    };
+    vector?: {
+        size: number;
+    };
+    /**
+     * Array/list field — stored as `style:{type:"list"}` (e.g. `int[]`, `object[]`).
+     * Ignored when an explicit `style` is given.
+     */
+    array?: boolean;
+    /** Nested fields for `type:"obj"` columns; each is itself a named, typed field. */
+    children?: NestedField[];
+    /**
+     * Per-column overrides applied to this field's EXPANSION, keyed by the
+     * expanded column's name. Meaningful on a merged field — an
+     * {@link input.dbLink} — where the engine expands a table's columns into
+     * request inputs and consults this map for each one.
+     *
+     * **Leave this unset** unless reproducing a pulled field; it defaults to `{}`.
+     * Xano's own CRUD scaffold writes it, so it is the common shape in a pulled
+     * workspace, not an edge case.
+     */
+    customize?: Readonly<Record<string, FieldCustomization>>;
+}
+/**
+ * One expanded column's override inside a merged field's {@link
+ * FieldOptions.customize} map.
+ *
+ * Every member restates what the column already declares, so an omitted member
+ * is not "inherit" — it is the stored default (`hidden:false`, `required:false`,
+ * `default:""`, no methods). Author the ones you mean to change and accept the
+ * rest, which is what the editor writes.
+ */
+interface FieldCustomization {
+    /** Drop this column from the expansion entirely. */
+    hidden?: boolean;
+    /** Whether the expanded input is required. */
+    required?: boolean;
+    /** Default for the expanded input; stored as a string (`0` → `"0"`). */
+    default?: string | number | boolean;
+    /** Methods/filters appended to the column's own, in the same spellings as {@link FieldOptions.methods}. */
+    methods?: readonly MethodSpec[];
+    /** Overrides for an object column's OWN children, keyed by child name. */
+    customize?: Readonly<Record<string, FieldCustomization>>;
+}
+/** A nested field inside an object column's `children` — a named, typed `FieldOptions`. */
+interface NestedField extends FieldOptions {
+    name: string;
+    type: string;
+}
+/**
+ * Stored types a COLUMN is nullable by default: files, geo, uuid and vector.
+ * Pass `nullable: false` to override. The value types read the same list, so a
+ * column nullable by default infers `T | null`.
+ */
+declare const COLUMN_NULLABLE_TYPES: readonly ["blob", "blob_img", "blob_video", "blob_audio", "geo_point", "geo_multipoint", "geo_linestring", "geo_multilinestring", "geo_polygon", "geo_multipolygon", "uuid", "vector"];
+/**
+ * Stored types an INPUT is nullable by default: the column list plus `file`,
+ * `date` and `epochms`, so an omitted optional one binds `null`. Pass
+ * `nullable: false` to override.
+ */
+declare const INPUT_NULLABLE_TYPES: readonly ["blob", "blob_img", "blob_video", "blob_audio", "geo_point", "geo_multipoint", "geo_linestring", "geo_multilinestring", "geo_polygon", "geo_multipolygon", "uuid", "vector", "file", "date", "epochms"];
+/**
+ * A field method/filter: a bare name (`"trim"`), a colon-form string carrying
+ * args (`"min:8"`, `"min:8:foo"` — first segment is the name, the rest are
+ * args), or an explicit `{ name, arg }` object. A method whose argument is text
+ * (`startsWith`, `pattern`, `ok`, `salt`) takes everything after the first `:`
+ * as that one argument (`"startsWith:https://"`); `pattern`'s error text needs
+ * `{ name: "pattern", arg: [regex, errorText] }`.
+ */
+type MethodSpec = string | {
+    name: string;
+    arg?: Array<string | number>;
+};
+/**
+ * A type-narrowed {@link MethodSpec} for a field constructor: a bare method name
+ * from the field type's valid set `N` (`"trim"`), the colon-form carrying args
+ * (`"min:8"`), or the explicit `{ name, arg }` object — which stays a universal
+ * escape hatch for any name the per-type union doesn't enumerate. The per-type
+ * `N` unions live in `fields/generated/field-methods.generated.ts`.
+ */
+type MethodArg<N extends string> = N | `${N}:${string}` | {
+    name: string;
+    arg?: Array<string | number>;
+};
+/**
+ * An options type `T` with its `methods` array widened to `readonly`. Field/input
+ * constructors capture their options via a `const` type parameter so literal
+ * flags (`required`/`nullable`/`array`) survive for `InferInput`; `const` also
+ * makes any inline `methods: [...]` a readonly tuple, so a constructor's options
+ * constraint must accept readonly arrays. The runtime cast back to `FieldOptions`
+ * is safe — the encoder only ever reads (`.map`) the methods.
+ */
+type ReadonlyMethods<T, N extends string> = Omit<T, "methods"> & {
+    methods?: readonly MethodArg<N>[];
+};
+
+/**
+ * Value-type algebra for the typed descriptor layer.
+ *
+ * Input and column constructors (`input.*`, `f.*`) return a runtime descriptor
+ * of exactly `{ type, options }`. This module adds a **phantom brand** to those
+ * return types that carries, at the TYPE LEVEL only, the field's value type `V`
+ * and the literal options object `O` the caller passed. The brand props are
+ * optional and never assigned at runtime, so the emitted object is unchanged and
+ * every branded descriptor stays structurally assignable to the un-branded
+ * `FieldDescriptor` / `InputDescriptor` — existing consumers are unaffected.
+ *
+ * `InferInput` (see `../inputs/infer.ts`) reads these brands to turn a query's
+ * declared `input` map into the request-payload TS type. The same algebra powers
+ * nested-object inference, since object `children` are built from `f.*`.
+ */
+
+/**
+ * Opaque runtime value of a file input/column. The request payload carries a
+ * resource reference (path/metadata), not the raw bytes — model it structurally
+ * rather than as `unknown` so a consumer at least sees an object shape.
+ */
+interface XanoFileRef {
+    /** Vault path, e.g. `/vault/<…>/<name>`. Join it to your base URL — see {@link import("./file-url.js").fileUrl}. */
+    path?: string;
+    name?: string;
+    type?: string;
+    size?: number;
+    /** Storage visibility as stored on the column (`"public"` / `"private"`). */
+    access?: string;
+    /** Type-specific metadata — e.g. `{ width, height }` on an image. */
+    meta?: unknown;
+    /**
+     * ⚠ The engine's own absolute URL, which on a tenant-scoped environment omits
+     * the `/tenant/<name>` segment and 404s. Do NOT read it directly: pass the
+     * file to `fileUrl(file, baseUrl)`, which joins the correct `path` to the base
+     * URL your client already has.
+     */
+    url?: string;
+}
+/**
+ * Opaque runtime value of a raw file **upload** (`input.file()`).
+ *
+ * Distinct from {@link XanoFileRef}, and the distinction matters: this is the
+ * bytes as they arrive on the request (multipart, base64, or a fetched URI). It
+ * is not yet stored anywhere and cannot be written to a file column. Pass it to
+ * a `s.storage.create_*` statement (`create_image`, `create_attachment`, …) to
+ * store it and get back the {@link XanoFileRef} a column holds.
+ */
+interface XanoFileUpload {
+    readonly __fileUpload?: never;
+}
+/**
+ * Marker value of a database-link input (`input.dbLink()`).
+ *
+ * Opaque on purpose: a dblink input does not bind a value of its own. The engine
+ * EXPANDS it into one input per column of the linked table, so a table with
+ * three columns turns one dblink entry into three request inputs. Read those by
+ * their own column names — `inp("email")`, not `inp("user__")`.
+ */
+interface XanoDbLink {
+    readonly __dbLink?: never;
+}
+/** One `{ lng, lat }` position, as the engine both accepts and returns. */
+interface XanoGeoPosition {
+    lng: number;
+    lat: number;
+}
+/**
+ * The `data` nesting for each geo `type` name. The names are the engine's own
+ * and the ONLY spellings it takes — `"multipoint"`, `"linestring"`,
+ * `"multipoly"` and the other guessable names are refused with a 400.
+ *
+ * | column                  | `type`   | `data`                 |
+ * |-------------------------|----------|------------------------|
+ * | `f.geo.point`           | `point`  | one position           |
+ * | `f.geo.multipoint`      | `points` | positions              |
+ * | `f.geo.linestring`      | `path`   | positions              |
+ * | `f.geo.multilinestring` | `paths`  | arrays of positions    |
+ * | `f.geo.polygon`         | `poly`   | positions (ring closed for you) |
+ * | `f.geo.multipolygon`    | `polys`  | arrays of positions    |
+ */
+interface XanoGeoData {
+    point: XanoGeoPosition;
+    points: XanoGeoPosition[];
+    path: XanoGeoPosition[];
+    paths: XanoGeoPosition[][];
+    poly: XanoGeoPosition[];
+    polys: XanoGeoPosition[][];
+}
+/** A geo `type` name: `point`, `points`, `path`, `paths`, `poly`, `polys`. */
+type XanoGeoType = keyof XanoGeoData;
+/**
+ * The value of an `f.geo.*` column: `{ type, data }`, NOT GeoJSON (no
+ * `coordinates`, no `"Point"`/`"MultiPoint"` keywords).
+ *
+ * The same shape goes in and comes back: `{ type: "point", data: { lng: 1,
+ * lat: 2 } }` reads back identical, and a `poly` ring reads back closed. Each
+ * column's row type narrows `T` to its own name, so `f.geo.multipoint` reads as
+ * `XanoGeoValue<"points">`. With no argument this is the union of all six.
+ *
+ * Raw WKT text (`c.text("POINT(1 2)")`) is also accepted wherever a value is
+ * taken — it is just not the typed path, because a read never returns one.
+ */
+type XanoGeoValue<T extends XanoGeoType = XanoGeoType> = {
+    [K in T]: {
+        type: K;
+        data: XanoGeoData[K];
+    };
+}[T];
+/**
+ * Which surface a field is read on. Inputs and columns share one stored shape but
+ * not one set of `nullable` defaults, so the value type of the SAME descriptor
+ * can differ: `f.date()` is `string` as a column and `string | null` inside an
+ * input object.
+ */
+type ValueSurface = "input" | "column";
+/** Stored types nullable by default on surface `Sf` — the encoder's own lists. */
+type NullableByDefault<Sf extends ValueSurface> = Sf extends "column" ? (typeof COLUMN_NULLABLE_TYPES)[number] : (typeof INPUT_NULLABLE_TYPES)[number];
+/**
+ * Phantom brand intersected onto a descriptor's return type. `V` is the field's
+ * base value type; `O` is the literal options object captured via a `const` type
+ * parameter at the call site; `T` is the stored type (`"date"`, `"blob_img"`, …),
+ * which decides the `nullable` default. All props are optional and never present
+ * at runtime.
+ */
+interface TypeBrand<V, O, T extends string = string> {
+    readonly __value?: V;
+    readonly __opts?: O;
+    readonly __type?: T;
+}
+/**
+ * The value of an object field, kept unresolved until a surface reads it: its
+ * children's `nullable` defaults depend on whether the object is an input or a
+ * column. Type-level only.
+ */
+interface ObjectOf<C> {
+    readonly __objectOf: C;
+}
+/** Resolve an {@link ObjectOf} value against surface `Sf`; any other value is unchanged. */
+type ResolveValue<V, Sf extends ValueSurface> = V extends ObjectOf<infer C> ? FromFieldMap<C, Sf> : V;
+/** A branded descriptor's value exactly as branded — objects still unresolved. */
+type RawBrandValue<D> = D extends TypeBrand<infer V, unknown> ? V : unknown;
+/** The base value type carried by a branded descriptor `D` (before array/nullable), read on surface `Sf`. */
+type BrandValue<D, Sf extends ValueSurface = "input"> = ResolveValue<RawBrandValue<D>, Sf>;
+/** The literal options object captured on a branded descriptor `D`. */
+type BrandOpts<D> = D extends TypeBrand<unknown, infer O> ? O : object;
+/** The stored type carried by a branded descriptor `D`; `string` when unbranded. */
+type BrandType<D> = D extends TypeBrand<unknown, unknown, infer T> ? T : string;
+type ApplyArray<T, O> = O extends {
+    array: true;
+} ? T[] : T;
+/**
+ * `| null` when the field can hold null: an explicit `nullable: true`, a
+ * `nullable` flag that is not a literal `false`, or no flag on a type the
+ * surface makes nullable by default.
+ */
+type ApplyNullable<T, O, St extends string, Sf extends ValueSurface> = O extends {
+    nullable: false;
+} ? T : O extends {
+    nullable: boolean;
+} ? T | null : [St] extends [NullableByDefault<Sf>] ? T | null : T;
+/**
+ * The full value type of a single branded descriptor `D` read on surface `Sf`:
+ * its base value with `array` and `nullable` applied, `nullable` defaulting per
+ * stored type exactly as the encoder does. (Optionality of the *key* is a
+ * map-level concern handled by {@link FromFieldMap}.)
+ */
+type ValueOf<D, Sf extends ValueSurface> = ApplyNullable<ApplyArray<BrandValue<D, Sf>, BrandOpts<D>>, BrandOpts<D>, BrandType<D>, Sf>;
+/** Keys whose descriptor options declare `required: true`. */
+type RequiredKeys<M> = {
+    [K in keyof M]: BrandOpts<M[K]> extends {
+        required: true;
+    } ? K : never;
+}[keyof M];
+/** Keys without `required: true` — optional in the produced payload type. */
+type OptionalKeys<M> = Exclude<keyof M, RequiredKeys<M>>;
+/**
+ * Turn a named map of branded descriptors into an object type: required inputs
+ * become required keys, everything else becomes an optional (`?`) key. Used for
+ * a query's top-level `input` map (surface `"input"`), a seed row (`"column"`),
+ * and nested `object` children (the enclosing field's surface).
+ */
+type FromFieldMap<M, Sf extends ValueSurface = "input"> = Prettify<{
+    [K in RequiredKeys<M>]: ValueOf<M[K], Sf>;
+} & {
+    [K in OptionalKeys<M>]?: ProtoKeySafe<K, ValueOf<M[K], Sf>>;
+}>;
+/**
+ * The value type of an OPTIONAL key named after an `Object.prototype` member
+ * (`constructor`, `toString`, `valueOf`, …). TypeScript checks an object
+ * literal's inherited member against such a key even when the literal omits it,
+ * so `{ name: "x" }` failed against `{ constructor?: number }` with "Function is
+ * not assignable". Widening only those keys to also admit the inherited member
+ * lets a literal omit the column; every other key is untouched.
+ */
+type ProtoKeySafe<K, V> = K extends keyof Object ? V | Object[K] : V;
+/**
+ * Turn a named map of branded descriptors into a **row** type — the read shape
+ * of a table. Unlike {@link FromFieldMap} (a request payload, where `required`
+ * gates key optionality), every declared column is present on a returned row, so
+ * all keys are required here; `nullable`/`array` still apply via {@link ValueOf}.
+ * Powers `InferRow<typeof table>` (see `../kinds/table.ts`) on surface
+ * `"column"`, and an agent's structured output on `"input"`.
+ */
+type RowFromFieldMap<M, Sf extends ValueSurface = "column"> = Prettify<{
+    [K in keyof M]: ValueOf<M[K], Sf>;
+}>;
+/** Flatten an intersection into a single object literal for readable hovers. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * A const-inferred record `T` checked against the keys of `Shape`: every key
+ * `Shape` does not declare is retyped to a record naming the `Allowed` keys, so
+ * a misspelling (`perPage`, `filter`, `temprature`) is a compile error on that
+ * key. A generic parameter is inferred FROM the literal, so without this it
+ * widens to include the typo and TypeScript's excess-property check never runs.
+ * An object, not a string, so intersecting a literal (`5 & …`) is not `never`.
+ */
+type NoExtraKeys<T, Shape, Allowed extends string> = NoInfer<{
+    [K in Exclude<keyof T, keyof Shape>]: {
+        "unknown key; expected one of": Allowed;
+    };
+}>;
+
+declare const REFERENCEABLE_KINDS: Set<string>;
+/**
+ * A reference to another workspace object: its def handle, or a bare name.
+ *
+ * A def may carry an explicit `guid` (its Xano identity). When present it's used
+ * verbatim; otherwise the guid is derived from `name`. Pass def handles (which
+ * carry the `guid`) rather than bare names when an object sets an explicit guid,
+ * so the reference and the target agree on the *same* guid.
+ */
+type ObjectRef = string | {
+    name: string;
+    guid?: string;
+};
+/**
+ * The guid for a `(type, name)` pair. A seeded `xano.lock` override wins (the
+ * lock freezes identity across renames — see lock/store.ts); otherwise the
+ * deterministic 32-char hex derivation. Every reference and every emitted
+ * target flows through here, so a lock override propagates everywhere by
+ * construction — including guids embedded inside strings at authoring time.
+ */
+declare function deriveGuid(type: string, name: string): string;
+/**
+ * Resolve a reference target (def handle or name) to the referenced object's guid.
+ *
+ * `where` names the argument for the failure (`Statement "s.db.get": argument
+ * "table"`); without it the message still names the reference by its SDK kind.
+ * `kindLabel` overrides that kind where one stored type serves two — an agent is
+ * stored as a `toolset`, a word the author never typed.
+ */
+declare function resolveRef(type: string, target: ObjectRef, where?: string, kindLabel?: string): string;
+
+/**
+ * Per-field-type method-name unions, distilled from the engine's column-create
+ * API schema (the per-type field-schema definitions). Each
+ * `f.<type>` / `input.<type>` constructor types its `methods` against the
+ * matching union so only names valid for that field type are accepted (the
+ * explicit `{ name, arg }` form remains a universal escape hatch).
+ */
+/** Per-field-type method metadata (method name → colon-form arg type; `bool` = flag, no arg). */
+declare const FIELD_METHODS: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** Field methods valid on `decimal` fields. */
+type DecimalMethod = "max" | "min";
+/** Field methods valid on `email` fields. */
+type EmailMethod = "lower" | "trim";
+/** Field methods valid on `int` fields. */
+type IntMethod = "max" | "min";
+/** Field methods valid on `password` fields. */
+type PasswordMethod = "max" | "min" | "minAlpha" | "minDigit" | "minLowerAlpha" | "minSymbol" | "minUpperAlpha" | "salt";
+/** Field methods valid on `tableRef` fields. */
+type TableRefMethod = "max" | "min";
+/** Field methods valid on `text` fields. */
+type TextMethod = "alphaOk" | "digitOk" | "lower" | "max" | "min" | "ok" | "pattern" | "startsWith" | "trim" | "upper";
+/** Field methods valid on `vector` fields. */
+type VectorMethod = "max" | "min";
+
+/** A typed field, ready to attach to a column/input name. */
+interface FieldDescriptor {
+    /** The **stored** type string (post-mapping), e.g. `blob_img`, `epochms`. */
+    type: string;
+    options: FieldOptions;
+}
+/** A named map of fields — used for table schemas and object children. */
+type FieldMap = Record<string, FieldDescriptor>;
+/** Options accepted by every catalog constructor (no `values`/`children`/`vector` — those are positional). */
+type FieldOpts = Omit<FieldOptions, "values" | "children" | "vector">;
+/**
+ * {@link FieldOpts} with `methods` narrowed to the field type's valid method set
+ * `N` (see {@link MethodArg}). Types with no engine-declared methods use
+ * `MethodOpts<never>`, leaving only the `{ name, arg }` escape hatch.
+ */
+type MethodOpts<N extends string> = Omit<FieldOpts, "methods"> & {
+    methods?: MethodArg<N>[];
+};
+/** {@link MethodOpts} made safe to capture under a `const` type parameter (see {@link ReadonlyMethods}). */
+type ConstMethodOpts<N extends string> = ReadonlyMethods<MethodOpts<N>, N>;
+/**
+ * An enum's `default` must be one of its `values` (or `""`, no default): the
+ * engine stores any text, and a default outside the list is a value no request
+ * can send back.
+ */
+type EnumDefault<V extends ReadonlyArray<string | number>, O = unknown> = NoInfer<O extends {
+    default: infer D;
+} ? [D] extends [V[number] | `${V[number]}` | ""] ? unknown : {
+    default: {
+        "default must be one of": `${V[number]}`;
+    };
+} : unknown>;
+/** Convert a named field map into the encoder's `NestedField[]` form. */
+declare function toNestedFields(map: FieldMap): NestedField[];
+/**
+ * The stored scalar type of a `tableRef` FK, derived from its `type` option: a
+ * `uuid`-keyed reference stores a `string`, everything else (the default `int`)
+ * stores a `number`. Keeps `InferRow` honest — a FK column is the referenced
+ * table's PK value, never the loose `string | number`.
+ */
+type TableRefValue<T, O> = TableRefType<T, O> extends "uuid" ? string : number;
+/**
+ * The stored type of a `tableRef` FK: the `type` option when given, else the
+ * handle's own `idType` (a uuid-keyed `table()` makes a uuid column), else `int`.
+ */
+type TableRefType<T, O> = O extends {
+    type: infer K extends "int" | "uuid";
+} ? K : T extends {
+    readonly __row?: infer R;
+} ? R extends {
+    id: infer I;
+} ? [I] extends [string] ? "uuid" : "int" : "int" : "int";
+/** The rich field-type catalog. */
+declare const f: {
+    readonly text: <const O extends ConstMethodOpts<TextMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O, "text">;
+    readonly int: <const O extends ConstMethodOpts<IntMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<number, O, "int">;
+    readonly decimal: <const O extends ConstMethodOpts<DecimalMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<number, O, "decimal">;
+    readonly bool: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<boolean, O, "bool">;
+    readonly uuid: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O, "uuid">;
+    readonly date: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O, "date">;
+    readonly email: <const O extends ConstMethodOpts<EmailMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O, "email">;
+    /** Password field; defaults to `access:"internal"` (the engine's stored default). */
+    readonly password: <const O extends ConstMethodOpts<PasswordMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O, "password">;
+    /**
+     * JSON column. Accepts an optional nested `children` schema — the structure the
+     * editor shows when a `json` field is expanded, and what a pulled workspace
+     * carries.
+     *
+     * `children` is spelled as an ARRAY of named, typed fields rather than the
+     * `FieldMap` {@link FieldCatalog.object} takes positionally. The two are not
+     * interchangeable: an object column's children are the column's own schema,
+     * while a json column's are a description of the shape stored inside it, which
+     * the engine persists in the order given. That order is part of the stored
+     * bytes, and a map does not preserve it.
+     *
+     * Without this there is no way to author a structured JSON column at all.
+     */
+    readonly json: <const O extends ConstMethodOpts<never> & {
+        children?: readonly NestedField[];
+    } = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<unknown, O, "json">;
+    /** Epoch-millisecond timestamp (authored as `timestamp`). */
+    readonly timestamp: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<number, O, "epochms">;
+    /** Image file resource (stored `blob_img`). */
+    readonly image: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O, "blob_img">;
+    /** Video file resource (stored `blob_video`). */
+    readonly video: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O, "blob_video">;
+    /** Audio file resource (stored `blob_audio`). */
+    readonly audio: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O, "blob_audio">;
+    /** Generic file attachment (stored `blob`). */
+    readonly attachment: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O, "blob">;
+    readonly geo: {
+        /** Value `{ type: "point", data: { lng, lat } }`. */
+        readonly point: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<{
+            type: "point";
+            data: XanoGeoPosition;
+        }, O, "geo_point">;
+        /** Value `{ type: "points", data: [{ lng, lat }, …] }`. */
+        readonly multipoint: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<{
+            type: "points";
+            data: XanoGeoPosition[];
+        }, O, "geo_multipoint">;
+        /** Value `{ type: "path", data: [{ lng, lat }, …] }`. */
+        readonly linestring: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<{
+            type: "path";
+            data: XanoGeoPosition[];
+        }, O, "geo_linestring">;
+        /** Value `{ type: "paths", data: [[{ lng, lat }, …], …] }`. */
+        readonly multilinestring: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<{
+            type: "paths";
+            data: XanoGeoPosition[][];
+        }, O, "geo_multilinestring">;
+        /** Value `{ type: "poly", data: [{ lng, lat }, …] }` — the ring is closed for you. */
+        readonly polygon: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<{
+            type: "poly";
+            data: XanoGeoPosition[];
+        }, O, "geo_polygon">;
+        /** Value `{ type: "polys", data: [[{ lng, lat }, …], …] }`. */
+        readonly multipolygon: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<{
+            type: "polys";
+            data: XanoGeoPosition[][];
+        }, O, "geo_multipolygon">;
+    };
+    /**
+     * Enum field. `values` may be empty — that is an enum column added in the
+     * editor and not yet given its options, which the engine stores and which
+     * appears in the survey corpus. Refusing it made the SDK stricter than the
+     * engine and cost a real table its readable form.
+     *
+     * An empty `values` brands the column `never` — an enum permitting nothing can
+     * hold nothing. Note what that becomes downstream: `InferRow` surfaces the
+     * column as `undefined`, not `never`, so a read-time narrow written against
+     * `never` (`if (row.e === "x")`) is dead differently than it looks.
+     */
+    readonly enum: <const V extends ReadonlyArray<string | number>, const O extends ConstMethodOpts<never> = Record<string, never>>(values: V, options?: O & EnumDefault<V, O>) => FieldDescriptor & TypeBrand<V[number], O, "enum">;
+    /** Vector field; `size` (>= 1) is the embedding dimensionality. */
+    readonly vector: <const O extends ConstMethodOpts<VectorMethod> = Record<string, never>>(size: number, options?: O) => FieldDescriptor & TypeBrand<number[], O, "vector">;
+    /** Nested object field (stored `obj`); `children` is a named field map. */
+    readonly object: <const C extends FieldMap, const O extends ConstMethodOpts<never> = Record<string, never>>(children: C, options?: O) => FieldDescriptor & TypeBrand<ObjectOf<C>, O, "obj">;
+    /**
+     * Table-reference (foreign-key) field — the column holds the referenced
+     * table's primary key. The engine persists the link as a trailing `@` method
+     * carrying the target table's id (`{name:"@", arg:["dbo=<guid>"]}`); on import
+     * it parses that back into the column's `tableref_id`. The reference resolves to the
+     * table's deterministic guid via the shared cross-object resolver, so it
+     * agrees with the target table's payload `guid` with no shared registry.
+     *
+     * The column takes the target handle's key type (`idType`), else `int`; pass
+     * `{ type: "uuid" }` for a uuid-keyed table named by bare string. A reference
+     * column may only be `int` or `uuid` — the two valid primary-key types.
+     *
+     * @param table The referenced table (a `table()` def handle or its bare name).
+     *   For a **self-reference** (e.g. `tweets.reply_to → tweets`), the table's
+     *   `const` binding isn't assigned yet inside its own initializer — using the
+     *   handle throws a "used before declaration" error. Pass the **bare name**
+     *   instead: `f.tableRef("tweets", { type: "int" })`. Identity guids derive
+     *   from `(type, name)`, so the name form resolves to the same guid.
+     *
+     * Byte-verified whole-object against a persisted table readback: the `@`
+     * method carries
+     * `disabled:false`, sits last in `methods`, and its `dbo=` arg is the target
+     * table's payload guid.
+     *
+     * The engine asserts the referenced table's primary-key type matches
+     * (int↔int, uuid↔uuid). When the target is passed as a **def handle** its
+     * `idType` is in hand, so a mismatch throws here instead of surfacing as an
+     * import failure. The bare-name form (self-references) carries no schema —
+     * there is nothing to check against, and it is not guessed at.
+     */
+    readonly tableRef: <const T extends ObjectRef, const O extends ConstMethodOpts<TableRefMethod> & {
+        type?: "int" | "uuid";
+    } = Record<string, never>>(table: T, options?: O) => FieldDescriptor & TypeBrand<TableRefValue<T, O>, O, TableRefType<T, O>>;
+};
+
+/**
+ * Response → `result[]` mapping, shared by every response-bearing kind
+ * (function, query, tool, middleware, and the response-bearing triggers).
+ * Extracted from the MVP's compile.ts so kinds beyond function can reuse it.
+ */
+
+/**
+ * A member of a record response — a {@link Value}, or a nested plain object
+ * literal which is auto-wrapped via {@link obj} (so `response: { user: { id:
+ * ref(x) } }` just works instead of failing tsc against `TaggedValue`).
+ * A nested record refuses at the type level the values `obj()` refuses
+ * (`caught()`, `toolset()`, `resp()`, `out()`); a top-level key carries them.
+ */
+type ResponseMember = Value | ResponseRecord;
+/** A nested response record: an `ObjInput` whose members are never `NotObjMember`s. */
+interface ResponseRecord {
+    [key: string]: ResponseRecordMember;
+}
+type ResponseRecordMember = (Value & {
+    readonly __notObjMember?: NestedRecordRefusal;
+}) | string | number | boolean | ResponseRecord | ResponseRecordMember[];
+/** What a nested response record says to a value it cannot carry. */
+type NestedRecordRefusal = "a nested response record cannot carry this value — bind it with s.set_var first and ref() the variable, or move it to a top-level response key";
+/** A single `Value` response, or a record of named result items. */
+type ResponseDef = Value | Record<string, ResponseMember>;
+/** Map a response into `result[]`: one unnamed item for a single value, or
+ * one named item per key for a record. A record member that is a nested plain
+ * object is auto-wrapped via {@link obj} (a dynamic `const:expr2` value). */
+declare function encodeResponse(response: ResponseDef | undefined): ResultItemXdo[];
+
+export { type XanoGeoType as $, type AppendBrand as A, type BodyBrand as B, type CatchBrand as C, type DecimalMethod as D, type EmailMethod as E, type FieldAccess as F, type RowFromFieldMap as G, type StatementAnnotations as H, type IntMethod as I, type StatementOptions as J, type TextFormat as K, type TextMethod as L, type MaybeBodyBrand as M, type NoExtraKeys as N, type ObjectOf as O, type PasswordMethod as P, type TypeBrand as Q, type RawBrandValue as R, type Statement as S, type TableRefMethod as T, type VectorMethod as U, type ValueOf as V, type XanoFileRef as W, type XanoDbLink as X, type XanoFileUpload as Y, type XanoGeoData as Z, type XanoGeoPosition as _, type AsShapeBrand as a, type XanoGeoValue as a0, annotate as a1, f as a2, statements as a3, FIELD_METHODS as a4, REFERENCEABLE_KINDS as a5, deriveGuid as a6, encodeResponse as a7, encodeStatement as a8, getStatementFactory as a9, isRegisteredStatement as aa, resolveRef as ab, toNestedFields as ac, type BranchesBrand as b, type BrandOpts as c, type BrandType as d, type BrandValue as e, type ConstMethodOpts as f, type EnumDefault as g, type FieldDescriptor as h, type FieldMap as i, type FieldOptions as j, type FieldOpts as k, type FieldStyleType as l, type FoundBrand as m, type FromFieldMap as n, type MemberUpdateBrand as o, type MethodArg as p, type MethodOpts as q, type MethodSpec as r, type MockEntry as s, type MockMap as t, type MockXdo as u, type ObjectRef as v, type Prettify as w, type ProtoKeySafe as x, type ReadonlyMethods as y, type ResponseDef as z };