@sincpro/web-framework 0.0.0-stage → 0.2.0

package/dist/core/present.js

@@ -0,0 +1,165 @@
+import { choiceLabelOf, labelOf, } from "@sincpro/criteria";
+import { frameworkCopy } from "./copy.js";
+import { relatedOf } from "./related.js";
+/** Present when a field is named that the model does not declare: drawn plain, never thrown. */
+const UNKNOWN = {
+    type: "unknown",
+    kind: "scalar",
+    nullable: true,
+    sortable: false,
+    ops: [],
+};
+function fieldOf(meta, name) {
+    return meta?.fields[name] ?? UNKNOWN;
+}
+function helpOf(field, locale) {
+    const help = field.help;
+    if (help === undefined)
+        return undefined;
+    return (locale ? help[locale] : undefined) ?? help["default"];
+}
+export function viewOf(meta, name, locale) {
+    const field = fieldOf(meta, name);
+    return {
+        name,
+        label: labelOf(meta, name, locale),
+        help: helpOf(field, locale),
+        type: field.type,
+        kind: field.kind,
+        numeric: field.type === "integer" || field.type === "number",
+        sortable: field.sortable,
+        required: field.required ?? false,
+        readonly: field.readonly ?? false,
+    };
+}
+/**
+ * The fields a screen shows when it names none: every scalar the model holds, in the order it
+ * declares them. Relations and value objects are left out — they are not a column, they are a
+ * page of their own (`RecordLines`) or a section.
+ */
+export function defaultFields(meta) {
+    if (!meta)
+        return [];
+    return Object.entries(meta.fields)
+        .filter(([, field]) => field.kind === "scalar")
+        .map(([name]) => name);
+}
+/** The bookkeeping every framework entity carries; shown on demand, never by default. */
+export const BOOKKEEPING = new Set(["version", "updated_at"]);
+/** `"2026-03-12"` as a LOCAL date: `new Date("2026-03-12")` is UTC midnight, the day before
+ *  anywhere west of Greenwich. */
+function localDate(text) {
+    const [year, month, day] = text.split("-").map(Number);
+    return new Date(year ?? 0, (month ?? 1) - 1, day ?? 1);
+}
+function decimals(text) {
+    const dot = text.indexOf(".");
+    return dot < 0 ? 0 : text.length - dot - 1;
+}
+/**
+ * One formatter per locale and shape, kept. Building an `Intl` formatter costs far more than
+ * using one: built per cell, 2 000 rows × 8 fields took ~150 ms — a list that stutters on
+ * every page. The set of shapes is tiny (three date/number styles × decimals × locales).
+ */
+const formatters = new Map();
+function dateFormat(locale, withTime) {
+    const key = `d|${locale ?? ""}|${withTime}`;
+    let format = formatters.get(key);
+    if (format === undefined) {
+        format = new Intl.DateTimeFormat(locale, withTime ? { dateStyle: "medium", timeStyle: "short" } : { dateStyle: "medium" });
+        formatters.set(key, format);
+    }
+    return format;
+}
+function numberFormat(locale, kept) {
+    const key = `n|${locale ?? ""}|${kept ?? ""}`;
+    let format = formatters.get(key);
+    if (format === undefined) {
+        format = new Intl.NumberFormat(locale, kept === undefined ? {} : { minimumFractionDigits: kept, maximumFractionDigits: kept });
+        formatters.set(key, format);
+    }
+    return format;
+}
+/** The record a many2one points at, read by the display its definition names. */
+function displayOf(field, value) {
+    const definition = field.definition;
+    const display = definition?.display || undefined;
+    const key = display ?? definition?.identity ?? "id";
+    const shown = value[key] ?? value["display_name"] ?? value["name"] ?? value["id"];
+    return shown === undefined || shown === null ? "" : String(shown);
+}
+/**
+ * The text a value reads as. `null` when there is nothing to read — the caller draws its own
+ * «empty» (a dash in a fact, nothing in a cell).
+ *
+ *     textOf(meta, "state", "paid", "es")            -> "Pagada"     (choice_labels)
+ *     textOf(meta, "active", true, "es")              -> "sí"
+ *     textOf(meta, "due", "2026-03-12", "es")         -> "12 mar 2026"
+ *     textOf(meta, "total", "1150.5", "es")           -> "1150,5"     (exact: digits kept)
+ *     textOf(meta, "lines", {items, count: {value: 30}}) -> "30 elementos"
+ */
+export function textOf(meta, name, value, locale) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const field = fieldOf(meta, name);
+    const copy = frameworkCopy();
+    if (field.choices && field.choices.length > 0)
+        return choiceLabelOf(meta, name, value, locale);
+    switch (field.type) {
+        case "boolean":
+            return value ? copy.value.yes : copy.value.no;
+        case "date":
+            return typeof value === "string"
+                ? dateFormat(locale, false).format(localDate(value))
+                : String(value);
+        case "datetime": {
+            const date = new Date(String(value));
+            return Number.isNaN(date.getTime())
+                ? String(value)
+                : dateFormat(locale, true).format(date);
+        }
+        case "integer":
+        case "number": {
+            const number = Number(value);
+            if (Number.isNaN(number))
+                return String(value);
+            const kept = typeof value === "string" ? decimals(value) : undefined;
+            return numberFormat(locale, kept).format(number);
+        }
+        case "text[]":
+            return Array.isArray(value)
+                ? value.length === 0
+                    ? null
+                    : value.join(", ")
+                : String(value);
+        case "one2many":
+        case "many2many": {
+            const related = relatedOf(value);
+            return copy.value.items(related.count.value, related.count.exact);
+        }
+        case "many2one":
+            return typeof value === "object" ? displayOf(field, value) : String(value);
+        case "embedded":
+            return null;
+        default:
+            return typeof value === "object" ? JSON.stringify(value) : String(value);
+    }
+}
+/**
+ * The value a column orders and groups on: the raw scalar, never the text. ISO dates order
+ * as text; a decimal that travels as text orders as a number.
+ */
+export function sortKeyOf(meta, name, value) {
+    if (value === null || value === undefined)
+        return null;
+    const field = fieldOf(meta, name);
+    if (field.type === "number" || field.type === "integer") {
+        const number = Number(value);
+        return Number.isNaN(number) ? null : number;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (field.type === "one2many" || field.type === "many2many")
+        return relatedOf(value).count.value;
+    return textOf(meta, name, value);
+}

package/dist/core/related.d.ts

@@ -0,0 +1,22 @@
+import type { Count } from "@sincpro/criteria";
+/**
+ * The records a relation holds inside its parent, however the server sent them.
+ *
+ * Context: sincpro_framework answers a one2many of a record as a PAGE of its own —
+ * `{items, count, cursor}` — so a tenant with a thousand members does not answer all of them;
+ * an older answer, or a domain declared by hand, sends a bare array. A screen that reads only
+ * `items` and counts them shows the first page and calls it the total (forge's console did:
+ * `count={repositories.length}`). This reads both shapes and keeps the real count.
+ *
+ *     relatedOf({ items: [a, b], count: { value: 1000, exact: true }, cursor: "x" })
+ *       -> { items: [a, b], count: { value: 1000, exact: true }, cursor: "x", partial: true }
+ *     relatedOf([a, b])  -> { items: [a, b], count: { value: 2, exact: true }, cursor: null, partial: false }
+ */
+export type Related<T> = {
+    items: T[];
+    count: Count;
+    cursor: string | null;
+    /** There are more than `items` holds: the record brought one page of them. */
+    partial: boolean;
+};
+export declare function relatedOf<T>(value: unknown): Related<T>;

package/dist/core/related.js

@@ -0,0 +1,21 @@
+export function relatedOf(value) {
+    if (Array.isArray(value))
+        return {
+            items: value,
+            count: { value: value.length, exact: true },
+            cursor: null,
+            partial: false,
+        };
+    if (typeof value === "object" && value !== null && "items" in value) {
+        const page = value;
+        const items = page.items ?? [];
+        const count = page.count ?? { value: items.length, exact: page.cursor == null };
+        return {
+            items,
+            count,
+            cursor: page.cursor ?? null,
+            partial: count.value > items.length || !count.exact || page.cursor != null,
+        };
+    }
+    return { items: [], count: { value: 0, exact: true }, cursor: null, partial: false };
+}

package/dist/core/relation.d.ts

@@ -0,0 +1,28 @@
+import type { FieldMeta, Meta } from "@sincpro/criteria";
+import type { Entity } from "./entity.js";
+/**
+ * Which record a field of a form is about, read from the model — so a form draws a many2one
+ * as a picker of the right entity without being told.
+ *
+ * Context: sincpro_framework publishes a many2one twice: the RELATION (`customer`, expanded as
+ * the record it points at, read-only) and its scalar KEY (`customer_id`, what is written),
+ * joined by `identified_by`. A form may name either; both mean «the customer». A relation
+ * names the other side by its AGGREGATE («Cliente»), which says nothing about where it is read
+ * — that is the entity the application declared (`entityFor`).
+ */
+export type RelationField = {
+    /** The relation field: `customer`. */
+    relation: string;
+    /** The scalar written for it: `customer_id` (the relation itself when it has none). */
+    key: string;
+    /** The aggregate on the other side: `"Cliente"`. */
+    target: string;
+    many: boolean;
+    field: FieldMeta;
+};
+export declare function relationFieldOf(meta: Meta | null | undefined, name: string): RelationField | undefined;
+/**
+ * The declared entity a relation points at: the one that says it is that aggregate, else the
+ * one whose model definition is, else the one whose key it is (`"ventas:cliente"`).
+ */
+export declare function entityFor(entities: readonly Entity[], target: string, metaOf?: (key: string) => Meta | undefined): Entity | undefined;

package/dist/core/relation.js

@@ -0,0 +1,30 @@
+export function relationFieldOf(meta, name) {
+    if (!meta)
+        return undefined;
+    const of = (relation, field) => field.kind !== "relation" || !field.relation
+        ? undefined
+        : {
+            relation,
+            key: field.identified_by || relation,
+            target: field.relation,
+            many: field.many === true,
+            field,
+        };
+    const own = meta.fields[name];
+    if (own?.kind === "relation")
+        return of(name, own);
+    // A scalar that a relation is identified by: `customer_id` IS the customer.
+    for (const [relation, field] of Object.entries(meta.fields))
+        if (field.kind === "relation" && field.identified_by === name)
+            return of(relation, field);
+    return undefined;
+}
+/**
+ * The declared entity a relation points at: the one that says it is that aggregate, else the
+ * one whose model definition is, else the one whose key it is (`"ventas:cliente"`).
+ */
+export function entityFor(entities, target, metaOf = () => undefined) {
+    return (entities.find((one) => one.aggregate === target) ??
+        entities.find((one) => metaOf(one.key)?.aggregate === target) ??
+        entities.find((one) => one.key === target));
+}

package/dist/core/rest.d.ts

@@ -0,0 +1,30 @@
+import { type Criteria } from "@sincpro/criteria";
+import { type Transport } from "./transport.js";
+/**
+ * The REST wire of sincpro_framework (`FastApiGateway`).
+ *
+ * Context: two things `restSource` from `@sincpro/criteria` 0.3 gets wrong against
+ * sincpro_framework 3.27, both found by forge's console, which had to write its own client:
+ *
+ * - it appends `?criteria=` to the route as it is, which breaks a route that already carries
+ *   its own query (`/projects?tenant_id=acme`) — here the criteria joins that query;
+ * - it sends `pack()` (base64url), and the REST entrypoint reads the parameter as plain JSON
+ *   and refuses anything else («criteria is not JSON») — here it travels as JSON.
+ *
+ * Once criteria fixes both, this keeps only what it adds: `one()`.
+ *
+ *     const transport = restTransport({
+ *       base: "/v1",
+ *       headers: () => ({ Authorization: `Bearer ${session.secret}` }),
+ *     });
+ */
+export type RestOptions = {
+    /** Prepended to every route: `"/v1"`, `"https://forge.sincpro.com.bo/v1"`. */
+    base?: string;
+    /** Sent with every request. A function is called fresh each time — a token that rotates. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Defaults to the global `fetch`. Inject one for tests. */
+    fetch?: typeof fetch;
+};
+export declare function urlOf<T>(base: string, route: string, criteria?: Criteria<T>): string;
+export declare function restTransport(options?: RestOptions): Transport;

package/dist/core/rest.js

@@ -0,0 +1,60 @@
+import { pageFrom, plain, readProblem, } from "@sincpro/criteria";
+import { TransportError, } from "./transport.js";
+/** The keys of an answer that are not the record: what is left is the record's own field. */
+const ENVELOPE = new Set(["cursor", "count", "entity_meta_data", "dropped", "draft"]);
+export function urlOf(base, route, criteria) {
+    const url = `${base}${route}`;
+    if (criteria === undefined)
+        return url;
+    const joiner = url.includes("?") ? "&" : "?";
+    return `${url}${joiner}criteria=${encodeURIComponent(JSON.stringify(criteria))}`;
+}
+export function restTransport(options = {}) {
+    const base = options.base ?? "";
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    async function get(route, url, signal, write) {
+        const own = typeof options.headers === "function" ? options.headers() : (options.headers ?? {});
+        const headers = write
+            ? {
+                ...own,
+                "Content-Type": "application/json",
+                ...(write.key === undefined ? {} : { "Idempotency-Key": write.key }),
+            }
+            : own;
+        const response = await doFetch(url, {
+            headers,
+            ...(write ? { method: write.method, body: JSON.stringify(write.body) } : {}),
+            ...(signal ? { signal } : {}),
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw new TransportError(route, response.status, readProblem(text), undefined);
+        return text ? JSON.parse(text) : null;
+    }
+    return {
+        async list(route, criteria, signal) {
+            const answer = await get(route, urlOf(base, route, plain(criteria)), signal);
+            return pageFrom(answer);
+        },
+        async one(route, signal) {
+            const answer = (await get(route, urlOf(base, route), signal));
+            const own = Object.keys(answer).filter((key) => !ENVELOPE.has(key));
+            const [key] = own;
+            if (own.length !== 1 || key === undefined)
+                throw new TransportError(route, 200, null, `${route} answered ${own.length} fields of its own (${own.join(", ")}); a record answers one`);
+            return {
+                record: answer[key],
+                meta: answer["entity_meta_data"] ?? null,
+                dropped: answer["dropped"] ?? [],
+                draft: answer["draft"] ?? null,
+            };
+        },
+        async send(method, route, body, signal, sending) {
+            return (await get(route, urlOf(base, route), signal, {
+                method,
+                body,
+                key: sending?.idempotencyKey,
+            }));
+        },
+    };
+}

package/dist/core/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `Idempotency-Key` of a gesture: one per thing a person meant to do, the SAME one while
+ * that thing is retried.
+ *
+ * Context: a Command that got no answer — the network dropped, a proxy answered 502 — may have
+ * run. Sending it again with a new key could pay twice; with the same key the server answers
+ * what it already did (sincpro_framework's `@idempotency`). So a key lives until the server
+ * gives a definite answer: done, or refused for a reason a retry does not change. Changing the
+ * body is a different gesture, and gets a new key — the server refuses a key that comes back
+ * with another payload.
+ *
+ *     const keys = retryKeys();
+ *     const key = keys.keyFor(body);          // the same while the previous one went unanswered
+ *     try { await send(…, { idempotencyKey: key }); keys.settle(null); }
+ *     catch (error) { keys.settle(error); }   // kept when nobody knows what happened
+ */
+export type RetryKeys = {
+    keyFor: (body: unknown) => string;
+    /** What the last attempt ended in: `null` when it was answered. */
+    settle: (error: unknown) => void;
+};
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export declare function unanswered(error: unknown): boolean;
+export declare function retryKeys(make?: () => string): RetryKeys;

package/dist/core/retry.js

@@ -0,0 +1,25 @@
+import { TransportError } from "./transport.js";
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export function unanswered(error) {
+    if (!(error instanceof TransportError))
+        return true;
+    if (error.status === null || error.status >= 500)
+        return true;
+    // The same key is still running elsewhere: retry once it completes, with that key.
+    return error.problem?.kind === "in_progress";
+}
+export function retryKeys(make = () => globalThis.crypto.randomUUID()) {
+    let pending = null;
+    return {
+        keyFor: (body) => {
+            const sent = JSON.stringify(body ?? null);
+            if (pending === null || pending.body !== sent)
+                pending = { body: sent, key: make() };
+            return pending.key;
+        },
+        settle: (error) => {
+            if (error === null || !unanswered(error))
+                pending = null;
+        },
+    };
+}

package/dist/core/schema.d.ts

@@ -0,0 +1,46 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * A model definition read from a JSON Schema — what an OpenAPI document holds.
+ *
+ * Context: what sincpro_framework's OpenAPI 3.1 describes and what it does not, checked
+ * against a running forge:
+ *
+ *   - the records a READ answers are invisible: the framework serialises them with its own
+ *     envelope, so `GET /projects` and `GET /projects/{id}` answer schema `{}` and no
+ *     `Project` schema exists. A list's definition comes from `entity_meta_data`, at runtime
+ *     or preloaded (`FrameworkProvider metas`) — not from here;
+ *   - the COMMANDS and the value objects are described well, and better than the meta in one
+ *     place: inside a value object `entity_meta_data` sends a `Literal` and a `list[str]` as
+ *     `unknown`, where the schema says `enum: ["es", "en"]` and `array<string>`.
+ *
+ * So this reads a component schema into a `Meta` — the form of a Command, a value object — and
+ * `completeMeta` fills, from it, what the server's meta left `unknown`.
+ *
+ *     const spec = metaFromSchema("ProjectSpecification", doc.components.schemas);
+ *     const fixed = completeMeta(project.fields.specification.definition, spec);
+ */
+export type JsonSchema = {
+    type?: string | string[];
+    format?: string;
+    enum?: readonly unknown[];
+    items?: JsonSchema;
+    $ref?: string;
+    anyOf?: readonly JsonSchema[];
+    oneOf?: readonly JsonSchema[];
+    properties?: Readonly<Record<string, JsonSchema>>;
+    required?: readonly string[];
+    title?: string;
+    description?: string;
+    default?: unknown;
+};
+export type SchemaComponents = Readonly<Record<string, JsonSchema>>;
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export declare function metaFromSchema(name: string, components: SchemaComponents, options?: {
+    identity?: string;
+}): Meta;
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export declare function completeMeta(meta: Meta, schema: Meta): Meta;

package/dist/core/schema.js

@@ -0,0 +1,128 @@
+import { field } from "./meta.js";
+const UNKNOWN = {
+    type: "unknown",
+    kind: "scalar",
+    nullable: true,
+    sortable: false,
+    ops: [],
+};
+function nameOfRef(ref) {
+    return ref.slice(ref.lastIndexOf("/") + 1);
+}
+/** `anyOf: [X, {type: "null"}]` is `X`, nullable — how pydantic writes `X | None`. */
+function unwrap(schema) {
+    const options = schema.anyOf ?? schema.oneOf;
+    if (options === undefined)
+        return { schema, nullable: false };
+    const real = options.filter((one) => one.type !== "null");
+    const [only] = real;
+    return real.length === 1 && only !== undefined
+        ? { schema: { ...only, ...pick(schema) }, nullable: real.length < options.length }
+        : { schema, nullable: real.length < options.length };
+}
+/** The words of the outer schema win over the ones of what it wraps. */
+function pick(schema) {
+    return {
+        ...(schema.title === undefined ? {} : { title: schema.title }),
+        ...(schema.description === undefined ? {} : { description: schema.description }),
+        ...(schema.default === undefined ? {} : { default: schema.default }),
+    };
+}
+function fieldFrom(raw, required, components, seen) {
+    const { schema: unwrapped, nullable } = unwrap(raw);
+    const target = unwrapped.$ref !== undefined
+        ? { ...components[nameOfRef(unwrapped.$ref)], ...pick(unwrapped) }
+        : unwrapped;
+    const options = {
+        ...(target.title === undefined ? {} : { label: target.title }),
+        ...(target.description === undefined ? {} : { help: target.description }),
+        ...(target.default === undefined ? {} : { default: target.default }),
+        ...(nullable ? { nullable } : {}),
+        required: required && target.default === undefined && !nullable,
+    };
+    if (unwrapped.$ref !== undefined) {
+        const name = nameOfRef(unwrapped.$ref);
+        if (components[name] === undefined || seen.has(name))
+            return UNKNOWN;
+        if (target.properties === undefined)
+            return target.enum ? field.choice(target.enum.map(String), options) : UNKNOWN;
+        return field.embedded(metaOf(name, target, components, new Set([...seen, name])), options);
+    }
+    if (target.enum)
+        return field.choice(target.enum.map(String), options);
+    const type = Array.isArray(target.type)
+        ? target.type.find((t) => t !== "null")
+        : target.type;
+    switch (type) {
+        case "string":
+            if (target.format === "date")
+                return field.date(options);
+            if (target.format === "date-time")
+                return field.datetime(options);
+            return field.text(options);
+        case "integer":
+            return field.integer(options);
+        case "number":
+            return field.number(options);
+        case "boolean":
+            return field.boolean(options);
+        case "array": {
+            const item = target.items === undefined ? undefined : unwrap(target.items).schema;
+            if (item?.$ref !== undefined) {
+                const inner = fieldFrom(item, false, components, seen);
+                return inner.kind === "embedded" && inner.definition
+                    ? field.embedded(inner.definition, { ...options, many: true })
+                    : field.tags(options);
+            }
+            return item?.type === "string" || item?.enum ? field.tags(options) : UNKNOWN;
+        }
+        default:
+            return UNKNOWN;
+    }
+}
+function metaOf(name, schema, components, seen) {
+    const required = new Set(schema.required ?? []);
+    const fields = Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, property]) => [
+        key,
+        fieldFrom(property, required.has(key), components, seen),
+    ]));
+    return {
+        aggregate: name,
+        identity: "",
+        default_order: "",
+        fields,
+        ...(schema.title === undefined ? {} : { name: { default: schema.title } }),
+    };
+}
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export function metaFromSchema(name, components, options = {}) {
+    const schema = components[name];
+    if (schema === undefined)
+        throw new Error(`no schema named ${name}`);
+    const meta = metaOf(name, schema, components, new Set([name]));
+    return options.identity
+        ? { ...meta, identity: options.identity, get_id: options.identity }
+        : meta;
+}
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export function completeMeta(meta, schema) {
+    const fields = Object.fromEntries(Object.entries(meta.fields).map(([name, own]) => {
+        const known = schema.fields[name];
+        if (known === undefined)
+            return [name, own];
+        if (own.type === "unknown")
+            return [name, { ...known, ...labelsOf(own) }];
+        if (own.kind === "embedded" && own.definition && known.definition)
+            return [name, { ...own, definition: completeMeta(own.definition, known.definition) }];
+        return [name, own];
+    }));
+    return { ...meta, fields };
+}
+/** A label the server declared is kept over the schema's generated title. */
+function labelsOf(own) {
+    return own.label && Object.keys(own.label).length > 0 ? { label: own.label } : {};
+}

package/dist/core/summary.d.ts

@@ -0,0 +1,50 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+/**
+ * What is known about ANY record, the same for every entity: its name and, when it has them,
+ * a description, a state, a type, a picture and who made and last changed it.
+ *
+ * Context: a link, a chip, a card, the summary that floats from a name and the header of a
+ * record all say the same few things about a record — only how much of it changes. Read once
+ * here, from the model, they cannot disagree, and a new entity looks right without a line
+ * written for it. What a record does not have is `null`, and nothing is drawn for it.
+ *
+ * Which field plays each part: the one the entity declares (`entity(…, { summary })`), else
+ * the first conventional name the model holds (`description`, `state`/`status`, `created_at`,
+ * …). The name is the model's own `display`. When the backend publishes these parts in its
+ * model definition, they are read from there and the convention steps aside.
+ */
+export type SummaryPart = "description" | "state" | "type" | "image" | "createdAt" | "createdBy" | "updatedAt" | "updatedBy";
+/** Which field of the entity plays each part, when it is not the conventional one.
+ *  `person`: its records are people or companies — a round face, initials without a photo. */
+export type SummaryFields = Partial<Record<SummaryPart, string>> & {
+    person?: boolean;
+};
+export type RecordSummary = {
+    id: string;
+    name: string;
+    description: string | null;
+    state: string | null;
+    type: string | null;
+    /** The picture's address, as the server sent it. */
+    image: string | null;
+    person: boolean;
+    created: {
+        at: string | null;
+        by: string | null;
+    };
+    updated: {
+        at: string | null;
+        by: string | null;
+    };
+};
+/** The field that plays each part. With a model, only fields it declares; without one (a
+ *  record that came alone), the record's own keys. */
+export declare function summaryFieldsOf(meta: Meta | null | undefined, record: AnyRecord, declared?: SummaryFields): Partial<Record<SummaryPart, string>>;
+/**
+ *     summaryOf(meta, invoice, { locale: "es" })
+ *       -> { name: "F-2026-0004", state: "Pagada", created: { at: "4 ene 2026, 14:13", … } }
+ */
+export declare function summaryOf(meta: Meta | null | undefined, record: AnyRecord, options?: {
+    fields?: SummaryFields;
+    locale?: string;
+}): RecordSummary;