@fieldia/core 0.30.1 → 0.31.0

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

@@ -1,9 +1,11 @@
 import type { FilterCondition, Fields, Option, PropertyDefinition } from '../format/field.mjs';
+import type { QuizResults } from './quiz.mjs';
 import type { JsonValue } from '../format/json.mjs';
 import type { Page } from '../format/page.mjs';
 import type { FileValue, RecordId, RelatedRecord, Values } from './values.mjs';
 import type { RunStop } from './run.mjs';
 import type { DateInterval } from './periods.mjs';
+import type { Facet } from './search.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),
@@ -35,6 +37,23 @@ export interface DataSource {
     list?(request: ListRequest): Promise<ListResult>;
     /** How many records fall under each value of a field, for a list's Group By. */
     groups?(request: GroupRequest): Promise<Group[]>;
+    /**
+     * The views kept for a list on the app's server: each a name and how the list stands — its search, its order and
+     * its columns — the person's own and those shared with their team, the same on every device. Asked as the list
+     * opens, before its records: it opens on the person's own default view, else the team's. Without it, a person's
+     * searches are kept as favourites in their browser (the viewer's `preferences`), as before.
+     */
+    views?(request: ViewsRequest): Promise<SavedView[]>;
+    /**
+     * Keep a view: a new one (no `id`), or one of the person's own again (its `id`) — its name, how the list stands,
+     * shared with the team or not, the default or not. Answer with it as kept, its `id` given. A view kept as the default
+     * is the only one: the person's own default, or the team's (a shared one) — let go of the one before. Refused
+     * (thrown, its message in the person's words), the menu says so and nothing is kept. Without it, views are listed
+     * and put on, and none is saved.
+     */
+    saveView?(request: SaveViewRequest): Promise<SavedView>;
+    /** Delete one of the person's own views. Without it, the menu deletes none. */
+    deleteView?(request: DeleteViewRequest): Promise<void>;
     /** The choices of one of the app's lists, for a selection with `optionsFrom` — a page's field, or a table's line by its values. */
     options?(request: OptionsRequest): Promise<Option[]>;
     /** The definitions of a properties field with `definitionsFrom`: those the linked record keeps. */
@@ -210,6 +229,59 @@ export interface DataSource {
      * this (a search that finds few, a model your server does not gather). To fail, throw: the map says so.
      */
     clusters?(request: ClustersRequest): Promise<ClustersResult | false>;
+    /**
+     * Send a code that proves the person owns an email or a phone, for a field whose node says `options.verify`: by
+     * email, SMS, WhatsApp — your app's own way (its mail service, Twilio, a WhatsApp gateway); Fieldia sends nothing and
+     * holds no keys. Answer with how long it works, how soon another may be asked for and how many digits it has; throw
+     * `saveRefused({ kind: 'rule', message })` to refuse it in your words ("Too many codes for this number: try in an
+     * hour"). With `checkCode`; without both, no field asks for a code.
+     */
+    sendCode?(request: SendCodeRequest): Promise<SentCode>;
+    /**
+     * Check the code the person typed for the value it was sent to: right, wrong (with the tries left), or expired. Answer
+     * right with a `proof` of your own — a signed token — and every send carries it (`verified`), so your server trusts
+     * the value without asking again. With `sendCode`.
+     */
+    checkCode?(request: CheckCodeRequest): Promise<CodeChecked>;
+    /**
+     * Take a payment the answers wait for (a page's `payment`): a reservation fee, a deposit — your app's own way, through
+     * its own provider (Stripe, Paymob, Fawry, PayPal…); Fieldia holds no keys and no provider's code. Called inside the
+     * person's press of Pay, so you may open the provider's checkout in a window of its own; or draw it in `slot`, an
+     * element in the payment step. Answer once it is over: paid (with the provider's reference, which the send carries),
+     * failed (with why) or cancelled; nothing is sent until it is paid. Stop when `signal` aborts (the person pressed
+     * Cancel, or left). `key` is the same for every try of one response's payment: hand it to your provider as its
+     * idempotency key, so a payment is never taken twice. Without it, no payment is asked and the page sends as before.
+     */
+    pay?(request: PayRequest): Promise<PayResult>;
+    /**
+     * The record templates people saved for a page (`templates` on the page): each by its id, its name and the values it
+     * keeps — this person's own and those the team shares, as the app decides. With `saveTemplate` and `deleteTemplate`,
+     * a template saved and named, or let go, on the app's server; without the three, the viewer keeps them in its
+     * `preferences`, the person's own.
+     */
+    templates?(request: TemplatesRequest): Promise<RecordTemplate[]>;
+    /** Keep a template — a new one, or one again by its `id` (renamed, its values replaced) — answered with it as kept. */
+    saveTemplate?(request: SaveTemplateRequest): Promise<RecordTemplate>;
+    deleteTemplate?(request: TemplateRequest): Promise<void>;
+    /**
+     * Changes to the record shown, pushed as they happen elsewhere — over the app's own socket, server-sent events, a
+     * database's listener: call `push` with each, and return what stops it. Asked as a record is shown (once it has an
+     * id), stopped as another is shown or the form goes. A change arriving while the person has changed nothing is laid
+     * on the record at once, and said; after a change of theirs, it is the conflict a save would meet — who changed it
+     * and when, what both changed, with Reload and Keep mine — and their typing is never touched. Without it, a change
+     * elsewhere is found as the person saves (`versions`).
+     *
+     * The same call as @fieldia/chatter's `subscribe(record, push)` (`{ model, id }`, a push, a stop): one function of
+     * the app's may serve both, pushing every kind of change; each takes only its own `type` — the record's `record`
+     * and `deleted`, the chatter's `message` and `delivery` — and lets the rest go.
+     */
+    subscribe?(record: RecordRequest, push: (change: RecordChange) => void): () => void;
+    /**
+     * Who else has the record shown open, pushed as it changes (the app's socket, a heartbeat): call `push` with the
+     * people — never this person — and return what stops it. Asked as a record is shown, with whether this person is
+     * changing it (`editing`), and asked again as that changes. Without it, nobody else is shown.
+     */
+    presence?(request: PresenceRequest, push: (people: PresentPerson[]) => void): () => void;
 }
 /** Whose approvals are asked: the record shown, and the person, as the app told the form. */
 export interface ApprovalsRequest {
@@ -438,6 +510,169 @@ export interface MapCluster {
     /** With `weight` asked: that field added up over its records. */
     weight?: number;
 }
+/** What `pay` is asked: what is due, what for, the answers it pays for, and where its checkout may be drawn. */
+export interface PayRequest {
+    pageId: string;
+    /** The page's model; empty for a page of responses. */
+    model: string;
+    recordId: RecordId | null;
+    /** How much, in the currency's own units (10000 for EGP 10,000.00). */
+    amount: number;
+    /** ISO 4217: "EGP". */
+    currency: string;
+    /** What it is for, in the page's words: "Reservation fee". */
+    label: string;
+    description?: string;
+    /** The same for every try of this response's payment: the provider's idempotency key. */
+    key: string;
+    /** The answers it pays for, as the send would carry them. */
+    values: Values;
+    /** The page's language, by tag. */
+    language: string;
+    /** Where the provider's checkout may be drawn in the payment step: an element, in a browser. */
+    slot?: unknown;
+    /** Aborts when the person presses Cancel or leaves: stop, and answer cancelled (or reject with an error named AbortError). */
+    signal?: UploadSignal;
+}
+/** How a payment ended. */
+export interface PayResult {
+    status: 'paid' | 'failed' | 'cancelled';
+    /** The provider's reference for a payment taken, sent with the answers. */
+    reference?: string;
+    /** Why it failed, in the person's words, said as it is: "The card was declined." */
+    message?: string;
+}
+/** What a page's payment asks now: the amount, its currency, what for, and its key. */
+export interface PaymentDue {
+    amount: number;
+    currency: string;
+    label: string;
+    description?: string;
+    key: string;
+}
+/** A payment taken, as a send carries it (`payment`). */
+export interface PaidPayment {
+    amount: number;
+    currency: string;
+    key: string;
+    reference?: string;
+}
+/** What `sendCode` is asked: the field, the value to prove, and how the person asked to get the code. */
+export interface SendCodeRequest {
+    pageId: string;
+    /** The page's model; empty for a page of responses. */
+    model: string;
+    /** The record edited; null for a new one or a response. */
+    recordId: RecordId | null;
+    /** The email or phone field, by name. */
+    field: string;
+    /** What it holds now: an email address, or a phone number (E.164 where the page reads phones the world over). */
+    value: string;
+    /** What the value is: an email, or a phone. */
+    kind: 'email' | 'phone';
+    /** The way the person picked to get it — `sms`, `whatsapp`, `call`, `email`, or one of the page's own — where the page offers more than one. */
+    by?: string;
+    /** The page's language, by tag: the code's message is written in it. */
+    language: string;
+}
+/** A code on its way. Each part is told where the app knows it. */
+export interface SentCode {
+    /** When it stops working, as ISO: said ("The code works for 10 minutes"), and after it, a new one is asked for. */
+    expiresAt?: string;
+    /** Seconds before another may be asked for: Send again waits so long, its count said. */
+    retryAfter?: number;
+    /** How many digits it has: its box takes so many, and checks it once they are all typed. 6 unless said. */
+    length?: number;
+    /** Your own id for it, handed back to `checkCode`. */
+    id?: string;
+    /** Words of your own, said as they are: "We sent a code to +20 10 1234 5678 on WhatsApp." */
+    message?: string;
+}
+/** What `checkCode` is asked: the code typed, for the value it was sent to. */
+export interface CheckCodeRequest {
+    pageId: string;
+    model: string;
+    recordId: RecordId | null;
+    field: string;
+    value: string;
+    /** What the person typed, its digits as 0-9, without spaces. */
+    code: string;
+    /** The id `sendCode` gave it, where it gave one. */
+    id?: string;
+}
+/** Whether a code was right. */
+export interface CodeChecked {
+    ok: boolean;
+    /** Right: a proof of your own (a signed token), sent with the answers so your server trusts the value as proved. */
+    proof?: string;
+    /** Wrong: how many tries are left; 0, a new code must be asked for. */
+    triesLeft?: number;
+    /** Too late: the code no longer works, and a new one must be asked for. */
+    expired?: boolean;
+    /** Words of your own, said as they are, in place of Fieldia's. */
+    message?: string;
+}
+/** An email or a phone the person proved they own, by a code: the value proved, and the app's proof of it. */
+export interface VerifiedValue {
+    value: string;
+    proof?: string;
+}
+/** The templates of a page's records, as `templates` is asked. */
+export interface TemplatesRequest {
+    model: string;
+    pageId: string;
+}
+/** One template, by its id. */
+export interface TemplateRequest extends TemplatesRequest {
+    id: RecordId;
+}
+/** A template kept as `saveTemplate` is asked: without `id`, a new one. */
+export interface SaveTemplateRequest extends TemplatesRequest {
+    template: {
+        id?: RecordId;
+        name: string;
+        values: Values;
+    };
+}
+/** A record's values kept by a name, to start a new one from: "Botox package". `by`, who saved it, where it is shared. */
+export interface RecordTemplate {
+    id: RecordId;
+    name: string;
+    values: Values;
+    by?: string;
+}
+/**
+ * A change to a record made elsewhere (`subscribe`): `record`, its version and values now — where it leaves them out,
+ * the form reads the record again (`load`) — and who changed it and when, where no version tells; `deleted`, it is gone.
+ */
+export type RecordChange = {
+    type: 'record';
+    version?: RecordVersion;
+    values?: Values;
+    by?: string;
+    at?: string;
+} | {
+    type: 'deleted';
+    by?: string;
+    at?: string;
+};
+/** The record shown, and this person, as `presence` is asked: whether they have changes not saved in it (`editing`). */
+export interface PresenceRequest {
+    model: string;
+    id: RecordId;
+    user?: {
+        id: RecordId | null;
+        name?: string;
+    };
+    editing: boolean;
+}
+/** Someone else with the record open: their name, whether they are changing it, and their picture's address. */
+export interface PresentPerson {
+    id: RecordId;
+    name: string;
+    editing?: boolean;
+    avatar?: string;
+}
 /** Whose possible duplicates were let be: what `notDuplicates` is asked. */
 export interface NotDuplicatesRequest {
     model: string;
@@ -491,6 +726,10 @@ export interface StoredDraft {
     }>;
     /** The fields the person answered (changed), in the page's order: where they got to. */
     answered?: string[];
+    /** On a page that draws its order or some of its questions: the draw they were answering, kept so it opens the same. */
+    order?: Record<string, string[]>;
+    /** On a page with time limits: when each started, as ISO — the page's under `#form`, a step's by its id. */
+    timers?: Record<string, string>;
     /** When it was kept, as ISO. */
     savedAt: string;
 }
@@ -777,6 +1016,18 @@ export interface SaveRequest {
     version?: RecordVersion;
     /** The key of the draft these changes were kept in on the server (`saveDraft`): the source may let it go. */
     draft?: string;
+    /** The emails and phones proved by a code (`options.verify`), by field: the value and the app's own proof, to trust it by. */
+    verified?: Record<string, VerifiedValue>;
+    /** The payment the answers waited for (a page's `payment`), taken: its amount, currency, key and the provider's reference. */
+    payment?: PaidPayment;
+    /**
+     * A send kept on the device without signal and sent later (a page's `outbox`): its key — the same for every try, so a
+     * server that kept the first can tell a second — and when it was made.
+     */
+    queued?: {
+        key: string;
+        at: string;
+    };
 }
 export interface SaveResult {
     id: RecordId;
@@ -867,6 +1118,57 @@ export interface ListedRecord {
     /** What the person may do with it: its row's buttons and a bulk edit keep to it. */
     can?: RecordPermissions;
 }
+/** Which list's views (`views`, `saveView`, `deleteView`): the page, its model and the list on it. */
+export interface ViewsRequest {
+    pageId: string;
+    model: string;
+    /** The list's id on the page (its layout's `id`): a page may hold more than one. */
+    list: string;
+}
+/** A column as a list keeps it for a person: shown or hidden, in its place in their order, and its width in pixels where they sized it. */
+export interface ColumnState {
+    colId: string;
+    width?: number | null;
+    hide?: boolean;
+}
+/** How a list stands, as a saved view keeps it. */
+export interface ViewState {
+    /** Its search, as the search bar's chips: the filters on, the fields grouped by, a field's values, a person's own conditions. */
+    facets: Facet[];
+    /** The keys chosen from its headers, the first leading; none or left out: the list's own order. */
+    sort?: SortOrder[];
+    /** The columns, in the person's order, those hidden marked — where the list lets a person choose (`optionalColumns`). */
+    columns?: ColumnState[];
+}
+/** A view kept on the app's server: what `views` answers, and `saveView` gives back. */
+export interface SavedView {
+    /** The source's own key for it. */
+    id: string;
+    name: string;
+    state: ViewState;
+    /** Shared with the team: everyone who opens this list is offered it. Else the person's own alone. */
+    shared?: boolean;
+    /** The list opens on it: the person's own default first, else the team's (a shared one). */
+    isDefault?: boolean;
+    /** The person's own: theirs to keep again and delete. Another's shared view is only put on. */
+    mine?: boolean;
+    /** Who made it, said beside another's shared view: "Mona Adel". */
+    by?: string;
+}
+/** A view to keep: new, or one of the person's own by its `id`. */
+export interface SaveViewRequest extends ViewsRequest {
+    view: {
+        id?: string;
+        name: string;
+        state: ViewState;
+        shared?: boolean;
+        isDefault?: boolean;
+    };
+}
+/** One of the person's own views to delete, by its `id`. */
+export interface DeleteViewRequest extends ViewsRequest {
+    id: string;
+}
 /**
  * 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
@@ -1009,6 +1311,30 @@ export interface SubmitRequest {
     bot?: BotReport;
     /** The key of the draft these answers were kept in on the server (`saveDraft`): the source may let it go, or mark it sent. */
     draft?: string;
+    /**
+     * On a page that draws its order or some of its questions (`order: "random"`, `draw`): for each part drawn, its parts'
+     * ids in the order this person was shown — those not drawn left out, their answers not among `values`.
+     */
+    order?: Record<string, string[]>;
+    /**
+     * On a page with a time limit (`timeLimit`): when the person pressed Start, as ISO, and whether the time ran out — the
+     * answers then sent as they stood. A step's limit run out says `timeUp: false` with no `started`. The browser's clock:
+     * a server that must be sure keeps its own.
+     */
+    started?: string;
+    timeUp?: boolean;
+    /** The emails and phones proved by a code (`options.verify`), by field: the value and the app's own proof, to trust it by. */
+    verified?: Record<string, VerifiedValue>;
+    /** The payment the answers waited for (a page's `payment`), taken: its amount, currency, key and the provider's reference. */
+    payment?: PaidPayment;
+    /**
+     * A send kept on the device without signal and sent later (a page's `outbox`): its key — the same for every try, so a
+     * server that kept the first can tell a second — and when it was made.
+     */
+    queued?: {
+        key: string;
+        at: string;
+    };
 }
 /**
  * What a page's bot check saw as its answers were sent. A person never fills the hidden box and takes longer than a
@@ -1034,6 +1360,11 @@ export interface SubmitResult {
      * answers themselves stay as they were sent.
      */
     values?: Values;
+    /**
+     * A quiz's results as the app marked them on its server (`quiz` on the page), shown in place of those the page works
+     * out: for a test that keeps its right answers out of the page. See `QuizResults`.
+     */
+    quiz?: QuizResults;
 }
 /**
  * What changed, using the operation names Odoo gives its x2many commands, so