@fieldia/core 0.23.0 → 0.25.0

package/src/lib/record/data-source.d.mts

@@ -2,6 +2,7 @@ import type { FilterCondition, Fields, Option, PropertyDefinition } from '../for
 import type { JsonValue } from '../format/json.mjs';
 import type { FileValue, RecordId, RelatedRecord, Values } from './values.mjs';
 import type { RunStop } from './run.mjs';
+import type { DateInterval } from './periods.mjs';
 /**
  * How Fieldia reaches data. Fieldia knows no backend: an app implements this
  * interface for its own (a Flectra adapter, a REST client, a survey store),
@@ -68,6 +69,208 @@ export interface DataSource {
      * size) and is shown as it is.
      */
     upload?(file: UploadFile, request: UploadRequest): Promise<UploadedFile>;
+    /**
+     * The times free to book, for a date and time drawn as booking slots
+     * (`"widget": "slots"`): each day asked — the days of a month, in the
+     * field's time zone — with its state (open, full, closed, a holiday) and
+     * the times a booking may start on it; asked again for the day of a time
+     * picked, so a time someone else took meanwhile is said, never booked.
+     * Without it, such a field is the plain date and time box.
+     */
+    slots?(request: SlotsRequest): Promise<SlotsResult>;
+    /**
+     * Change many records at once, the same value in each field given: a
+     * list's bulk edit, of the rows ticked or of every record the search
+     * finds. Answer with those not changed and why; every other one is taken
+     * as changed. Without it, the list saves each in turn (`save`, `partial`).
+     * Refuse a record this person may not change, or one changed since the
+     * version it was listed at (`versions`), as a save would.
+     */
+    writeMany?(request: WriteManyRequest): Promise<WriteManyResult>;
+    /**
+     * Write a list's export on the server, in place of the browser: for
+     * exports too big for a browser, or files the server words its own way.
+     * Answer with the file — its bytes (`data`: a Blob fits) or its address
+     * (`url`) — for the browser to save; with `{ message }` when the server
+     * hands it over its own way (an email on its way), the list saying it; or
+     * with `false` to let the list write it in the browser after all, as it
+     * does without this (a small export, say).
+     */
+    exportRecords?(request: ExportRequest): Promise<ExportedFile | {
+        message: string;
+    } | false>;
+    /**
+     * Make many records at once, each with its own values: a list's Import of
+     * a file's rows, a thousand at a time. Answer for each record asked for,
+     * in its order: the id it was made with, or why it was not made, in the
+     * person's words. Without it, the list saves each in turn (`save` with no
+     * id).
+     */
+    createMany?(request: CreateManyRequest): Promise<CreateManyResult>;
+    /**
+     * Take a list's Import on the server, in place of the browser: a file too
+     * big for one, or a server that imports its own way. Asked once the person
+     * has matched the file's columns to the page's fields, before a row is
+     * checked: answer `{ message }` when the server takes the file (the list
+     * says it: "Your file is being imported: you will get an email"), or
+     * `false` to let the browser import it after all, as it does without this.
+     */
+    importRecords?(request: ImportRequest): Promise<{
+        message: string;
+    } | false>;
+    /**
+     * Records like the one typed, for a page's possible duplicates (`duplicates`): asked a moment after a person stops
+     * typing in a field it names, as a saved record is opened, and as a record is saved — with the fields it names that
+     * hold a value. Answer with the records that have the same phone, email or id, or a name close enough, each with
+     * the fields it matched on; never the record itself. Without it, nothing is asked and nothing shows.
+     */
+    duplicates?(request: DuplicatesRequest): Promise<DuplicatesResult>;
+    /**
+     * Merge records into one, as a person chose on a possible duplicate's Merge: `keepId` kept, holding the values
+     * picked for each field, and `mergeIds` gone. Moving what was theirs — messages, activities, the records that link
+     * to them — to the one kept is the source's work; the page says it will happen. Refuse with `saveRefused` (a `rule`,
+     * with why) and nothing changes. Without it, possible duplicates offer no Merge.
+     */
+    merge?(request: MergeRequest): Promise<MergeResult | void>;
+}
+/** Many records made at once, each with its own values: a list's Import. */
+export interface CreateManyRequest {
+    model: string;
+    /** Each record's values, in the file's order: what its row fills in, and the page's defaults for the rest. Links as `{ id, label }`. */
+    records: Values[];
+    /** The fields' definitions, as a save gets them. */
+    fields: Fields;
+}
+export interface CreateManyResult {
+    /**
+     * One answer for each record asked for, in the same order: the id it was made with, or why it was not made — and,
+     * where the source has it, the problem as a save would throw it (a field's own words). A record left unanswered is
+     * taken as not made.
+     */
+    records: ({
+        id: RecordId;
+    } | {
+        message: string;
+        problem?: SaveProblem;
+    })[];
+}
+/** A file a list's Import hands to the server, its columns matched to the page's fields. */
+export interface ImportRequest {
+    model: string;
+    /** The file as the person picked it: a browser's File fits. */
+    file: UploadFile;
+    /** Each column of the file, in its order — its header's words, and the field it fills, null where it is left out. */
+    columns: {
+        header: string;
+        field: string | null;
+    }[];
+    /** How many rows it holds under its header. */
+    rows: number;
+    /** The fields' definitions, as a save gets them. */
+    fields: Fields;
+    /** The page's language and the order it writes dates in, so a server reads the cells as the page would. */
+    locale: string;
+    dateOrder: 'dmy' | 'mdy' | 'ymd';
+}
+/** Records like the one typed: what `duplicates` is asked. */
+export interface DuplicatesRequest {
+    model: string;
+    /** The record typed, never its own duplicate; null while it is new. */
+    recordId: RecordId | null;
+    /** Every value of the form, as typed: a phone kept as E.164 where the page reads phones the world over. */
+    values: Values;
+    /** The fields to compare it by, by name: those the page names (`duplicates.fields`) that hold a value now. */
+    fields: string[];
+}
+/** A record like the one typed. */
+export interface DuplicateMatch {
+    id: RecordId;
+    /** Its name, as people know it: "Nile Traders". */
+    name: string;
+    /**
+     * What it matched on: the names of the fields asked that it holds the same (`phone`, `email`), or a name close to
+     * the one typed (the name's field). Each is said under that field's box; words of the source's own ("the same
+     * address") are said as they are.
+     */
+    why: string[];
+    /** How alike, from 0 to 1, where the source tells: the likest first. */
+    score?: number;
+}
+export interface DuplicatesResult {
+    matches: DuplicateMatch[];
+}
+/** Records merged into one: what `merge` is asked. */
+export interface MergeRequest {
+    model: string;
+    /** The record kept. */
+    keepId: RecordId;
+    /** The records merged into it, then gone. */
+    mergeIds: RecordId[];
+    /** The kept record's values, as picked on the merge's screen for each field the records held apart. */
+    values: Values;
+    /** The page's fields, so the source knows each link's model, as a save does. */
+    fields: Fields;
+}
+/** What a merge may tell: words of the source's own about it, said once it is done ("4 messages moved"). */
+export interface MergeResult {
+    message?: string;
+}
+/** The same value written in a field of each record: a list's bulk edit. */
+export interface WriteManyRequest {
+    model: string;
+    ids: RecordId[];
+    /** The fields written and their value, the same in each record: `{ state: 'active' }`. */
+    values: Values;
+    /** Those fields' definitions, as a save gets them. */
+    fields: Fields;
+    /** The version each record was listed at, by its id, where the list knew it: one changed since is refused, as a save over someone else's. */
+    versions?: Record<string, RecordVersion>;
+}
+export interface WriteManyResult {
+    /** Each record not changed, with why in the person's words — and, where the source has it, the problem as a save would throw it (a conflict's who and when). */
+    failed: {
+        id: RecordId;
+        message: string;
+        problem?: SaveProblem;
+    }[];
+}
+/** A list's records to put in a file: those ticked, or every one its search finds. */
+export interface ExportRequest {
+    model: string;
+    format: 'xlsx' | 'csv';
+    /** The list's columns, in its order, each with its header's words. */
+    columns: {
+        field: string;
+        label: string;
+    }[];
+    /** The records ticked, by id; left out, every record `filter` finds. */
+    ids?: RecordId[];
+    /** The list's search, as `list` gets it. */
+    filter: ResolvedFilter[];
+    /** The list's order now. */
+    sort: SortOrder[];
+    /** How many records go. */
+    count: number;
+    /** The file's name, as the list would give it: "Customers 2026-10-16.xlsx". */
+    name: string;
+    /** The page's language, for values written as people there read them. */
+    locale: string;
+}
+/** A file for the browser to save: its bytes, or where to fetch them. */
+export interface ExportedFile {
+    name: string;
+    /** Its media type, when `data` does not say it. */
+    type?: string;
+    /** Its bytes: a Blob, an ArrayBuffer, a typed array, or text. */
+    data?: ExportBytes | ArrayBuffer | ArrayBufferView | string;
+    /** Where the browser fetches it, in place of `data`. */
+    url?: string;
+}
+/** A Blob, as far as an export reads one: core names no DOM types. */
+export interface ExportBytes {
+    readonly size: number;
+    readonly type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
 }
 /**
  * Which state of a record a page opened, as its source keeps it: an etag, a
@@ -207,6 +410,15 @@ export interface SearchRequest {
     /** The field's filter, with every `valueFrom` already replaced by its value. */
     filter?: ResolvedFilter[];
     limit?: number;
+    /**
+     * Only the records named exactly `query`, in any case — not every one whose
+     * name holds it. A box asks so for a name typed when a search's first
+     * answers, cut at their limit, did not hold it ("Nile" after ten "Blue
+     * Nile"s), and to tell whether more than one record has that name. A source
+     * that does not know it searches as ever: the box looks for the name among
+     * what comes.
+     */
+    exact?: boolean;
 }
 export type ResolvedFilterCondition = Omit<FilterCondition, 'valueFrom' | 'value'> & {
     value: JsonValue;
@@ -258,7 +470,23 @@ export interface ListedRecord {
     /** What the person may do with it: its row's buttons and a bulk edit keep to it. */
     can?: RecordPermissions;
 }
-export interface GroupRequest {
+/**
+ * How a date's records are grouped: by the day, week, month, quarter or year
+ * each falls in rather than by its exact value. Each group's `value` is then
+ * the first day of its span — "2026-03-01" for March 2026, "2026-03-09" for
+ * the week from 9 March — the page writing its words ("March 2026", "Week 11,
+ * 2026"); the groups in time order, those with no date last. `spanStart`
+ * counts a value's span as a source should.
+ */
+export interface GroupInterval {
+    /** For a date or a date and time field: group by the span each record falls in. */
+    interval?: DateInterval;
+    /** With `interval: "week"`: the day a week starts on, 0 Sunday to 6 Saturday — the page's language's. */
+    weekStart?: number;
+    /** With `interval`, for a date and time field: the time zone its days are told in (IANA: "Africa/Cairo") — the page's. */
+    timeZone?: string;
+}
+export interface GroupRequest extends GroupInterval {
     model: string;
     field: string;
     filter: ResolvedFilter[];
@@ -271,14 +499,22 @@ export interface Group {
 }
 /** How a field is totalled: added up, averaged, its least or its most, or how many records hold a value in it. */
 export type TotalKind = 'sum' | 'avg' | 'min' | 'max' | 'count';
-export interface TotalsRequest {
+export interface TotalsRequest extends GroupInterval {
     model: string;
     /** The list's search, as `list` gets it. For the ticked rows alone, add `{ field: 'id', op: 'in', value: ids }`. */
     filter: ResolvedFilter[];
     /** What to total, by field: `{ amount: ['sum'], hours: ['sum', 'avg'] }`. */
     totals: Record<string, TotalKind[]>;
-    /** Total under each value of this field as well, grouped as `groups` groups it: a Group By heading's sums. */
+    /** Total under each value of this field as well, grouped as `groups` groups it (by `interval`, for a date): a Group By heading's sums. */
     groupBy?: string;
+    /**
+     * The field holding each amount's currency, by the money field, where each
+     * record keeps its own: `{ amount: 'currency_id' }`. Such an amount is
+     * totalled within one currency only: over records in more than one, its
+     * sum, average, least and most are null — no honest number — and the
+     * result names the currency of those it could total (`currencies`).
+     */
+    currencies?: Record<string, string>;
 }
 /**
  * Each field's totals, by field and then by kind: `totals.amount.sum`. The
@@ -293,9 +529,19 @@ export interface TotalsResult {
     totals: Totals;
     /** With `groupBy`: each value's totals, in the order `groups` gives them. */
     groups?: TotalsGroup[];
+    /**
+     * With `currencies` asked: the currency each money field's totals are in,
+     * by field, as its currency field holds it (a link as `{ id, label }`, a
+     * code as "EGP"); null where its records hold more than one, or none. A
+     * page writes an amount's total only in a currency it knows: the field's
+     * own, or the one named here.
+     */
+    currencies?: Record<string, JsonValue>;
 }
 export interface TotalsGroup extends Group {
     totals: Totals;
+    /** The currency of each money field's totals under this value, as `TotalsResult.currencies` says it. */
+    currencies?: Record<string, JsonValue>;
 }
 /**
  * A file to store: what an upload reads of a browser's `File`. Core names no
@@ -358,6 +604,23 @@ export interface SubmitRequest {
     pageId: string;
     /** The answers to the questions that were shown. Skipped steps are left out. */
     values: Values;
+    /** On a page with a bot check (`botCheck`): what it saw, for the app to decide on. The page never refuses a send for it. */
+    bot?: BotReport;
+}
+/**
+ * What a page's bot check saw as its answers were sent. A person never fills the hidden box and takes longer than a
+ * few seconds; a send that is either is likely a bot's — or a person's whose browser filled every box at once, which is
+ * why the app decides: keep it aside, ask the captcha's service, or refuse it.
+ */
+export interface BotReport {
+    /** The hidden box was filled: no person sees it, reaches it with Tab or hears it read out. */
+    honeypot: boolean;
+    /** Sent sooner than the page's `minSeconds` after it was shown, or started again. */
+    tooFast: boolean;
+    /** Seconds from the page shown (or started again) to this send, to a tenth. */
+    seconds: number;
+    /** The captcha's token, on a page with one (`botCheck.captcha`), for the app to check with its service: null when none came. */
+    captcha?: string | null;
 }
 export interface SubmitResult {
     id?: RecordId;
@@ -444,3 +707,46 @@ export declare function saveRefused(problem: SaveProblem): Error & {
 };
 /** What a failed save tells: its own problem, a failed fetch as the network, anything else as it is. */
 export declare function saveProblemOf(error: unknown): SaveProblem;
+/** What a booking's free times are asked with: the days, the zone they are in, and what the page knows of the booking. */
+export interface SlotsRequest {
+    /** The page's model, for a record page; empty for a responses page. */
+    model: string;
+    /** The date and time field booked. */
+    field: string;
+    /** The record booked, so its own booking counts as free for it; null for a new one. */
+    recordId: RecordId | null;
+    /** The schedule the field's node names (`options.schedule`): a doctor's, a showroom's. The field's name unless it names one. */
+    schedule: string;
+    /** The first and the last day asked, both included, as 2026-10-01: days in `timeZone`. */
+    from: string;
+    to: string;
+    /** The zone the days are in, by its IANA name: the field's, its page's, or the browser's. */
+    timeZone: string;
+    /** The minutes a booking lasts, and those kept free between two, as the page says (`options.length`, `options.between`). */
+    length?: number;
+    between?: number;
+    /** Every value of the form: the doctor, the service, the car to drive. */
+    values: Values;
+}
+/** What a day is for booking: times free on it, all taken, not open, or a holiday. */
+export type SlotDayState = 'open' | 'full' | 'closed' | 'holiday';
+/** One day of a booking's: its state and the times a booking may start on it. */
+export interface SlotDay {
+    state: SlotDayState;
+    /** The times free, as instants (ISO 8601, in UTC or with their offset: 2026-10-15T09:30:00+03:00), earliest first. */
+    free?: string[];
+    /** Words for the day, in the person's language: a holiday's name, why it is closed. */
+    note?: string;
+}
+/** The days asked, each by its date (2026-10-15): a day left out is closed. */
+export interface SlotsResult {
+    days: Record<string, SlotDay>;
+    /** The minutes a booking lasts, when the source knows better than the page: the service's own length. */
+    length?: number;
+}
+/**
+ * A new record's save, made from its values alone — as a list's Import saves a row where the source has no
+ * `createMany`, and a memory source makes each of `createMany`'s: every value in `values`, the links of a many2many
+ * as one `set`, the rest as changes.
+ */
+export declare function newRecordSave(model: string, fields: Fields, values: Values): SaveRequest;