@brydio/manifest 0.1.0-alpha.4 → 0.1.0-alpha.40

package/src/open-schema.js

@@ -0,0 +1,444 @@
+// A copy of Brydio's `apps/api/src/apps/manifest/open-schema.ts`, kept exact so
+// a companion the SDK accepts is one the server accepts, and a value moved by
+// the fake host is moved as the real store moves it. Only the part after
+// "The SDK's own" at the end is not the server's.
+import { FIELD_LIMITS, FIELD_NAME, isSortable, isStructured, parseFieldType, quoted, RESERVED_FIELDS, } from "./field-types.js";
+/**
+ * Open-schema collections (P5).
+ *
+ * A collection flagged `openSchema: { fields: "columns", table?: "table" }`
+ * keeps the fields its manifest declares, and also the fields its companion
+ * collection's records define, per table. This file is the manifest half:
+ * which types a definition may name, what the companion must declare, how a
+ * definition reads as a `FieldType` the store already knows, and how a value
+ * moves when its field changes type. The store half is
+ * `apps/data/open-schema.ts`.
+ */
+/** The types a field definition may name. */
+export const OPEN_TYPES = [
+    'text',
+    'long_text',
+    'number',
+    'currency',
+    'percent',
+    'rating',
+    'date',
+    'datetime',
+    'checkbox',
+    'select',
+    'multi_select',
+    'person',
+    'link',
+    'url',
+    'email',
+    'phone',
+    'attachment',
+];
+export const OPEN_LIMITS = {
+    /** Live rows one table may hold (DB-Q2, owner 30 Sep): measured at this size. */
+    rowsPerTable: 50_000,
+    /** Live field definitions one table may hold. */
+    fieldsPerTable: 200,
+    /** The highest a rating may be. */
+    ratingMax: 10,
+};
+/**
+ * What the companion must declare: the three it must have, and the kinds of
+ * the ones the host reads when they are there. Anything else is the app's own.
+ */
+const REQUIRED_COMPANION = { key: 'string', name: 'string', type: 'enum' };
+const OPTIONAL_COMPANION = {
+    choices: ['string[]'],
+    required: ['boolean'],
+    currency: ['string'],
+    precision: ['number'],
+    linkTo: ['string'],
+    description: ['string', 'text'],
+};
+const kindOf = (raw) => {
+    try {
+        return parseFieldType(raw);
+    }
+    catch {
+        // Its own problem is reported by the field check; nothing to add here.
+        return null;
+    }
+};
+/**
+ * Everything wrong with one collection's `openSchema`, given every
+ * collection's raw schema. Empty when it is right.
+ */
+export function openSchemaProblems(collection, flag, data) {
+    const companion = data[flag.fields];
+    if (!companion || flag.fields === collection) {
+        return [
+            {
+                code: 'data_open_fields_unknown',
+                message: `${collection}.openSchema.fields names ${flag.fields}, which must be another collection of this app.`,
+            },
+        ];
+    }
+    if (companion.openSchema) {
+        return [
+            {
+                code: 'data_open_fields_unknown',
+                message: `${flag.fields} defines ${collection}'s fields, so it cannot have open fields itself.`,
+            },
+        ];
+    }
+    const problems = [];
+    const shape = `${flag.fields} defines ${collection}'s fields`;
+    for (const [field, kind] of Object.entries(REQUIRED_COMPANION)) {
+        const type = field in companion.schema ? kindOf(companion.schema[field]) : null;
+        if (!type || type.kind !== kind || (field !== 'key' && type.optional)) {
+            problems.push({
+                code: 'data_open_fields_shape',
+                field,
+                message: kind === 'enum'
+                    ? `${shape}, so it needs type: a choice of some of ${quoted(OPEN_TYPES)}.`
+                    : `${shape}, so it needs ${field}: "${kind}${field === 'key' ? '?' : ''}".`,
+            });
+            continue;
+        }
+        if (kind === 'enum') {
+            const unknown = (type.values ?? []).find(value => !OPEN_TYPES.includes(value));
+            if (unknown) {
+                problems.push({
+                    code: 'data_open_fields_shape',
+                    field,
+                    message: `${flag.fields}.type offers "${unknown}", which is not an open field type; use some of ${quoted(OPEN_TYPES)}.`,
+                });
+            }
+        }
+    }
+    for (const [field, kinds] of Object.entries(OPTIONAL_COMPANION)) {
+        if (!(field in companion.schema))
+            continue;
+        const type = kindOf(companion.schema[field]);
+        if (type && !kinds.includes(type.kind)) {
+            problems.push({
+                code: 'data_open_fields_shape',
+                field,
+                message: `${flag.fields}.${field} is read by Brydio as ${kinds.join(' or ')}; declare it so.`,
+            });
+        }
+    }
+    if (flag.table !== undefined) {
+        for (const [name, schema] of [
+            [collection, data[collection]?.schema ?? {}],
+            [flag.fields, companion.schema],
+        ]) {
+            const type = flag.table in schema ? kindOf(schema[flag.table]) : null;
+            if (!type || type.kind !== 'string' || type.optional) {
+                problems.push({
+                    code: 'data_open_table_unknown',
+                    field: flag.table,
+                    message: `${collection}.openSchema.table is ${flag.table}, so ${name} needs ${flag.table}: "string", naming each record's table.`,
+                });
+            }
+        }
+    }
+    return problems;
+}
+// ---------------------------------------------------------------------------
+// Definitions
+/** A definition's type as the store's own field type: what `checked` and the list path read. */
+export function fieldTypeOf(field) {
+    switch (field.type) {
+        case 'text':
+        case 'url':
+        case 'email':
+        case 'phone':
+            return { kind: 'string', optional: true };
+        case 'long_text':
+            return { kind: 'text', optional: true };
+        case 'number':
+        case 'currency':
+        case 'percent':
+        case 'rating':
+            return { kind: 'number', optional: true };
+        case 'date':
+        case 'datetime':
+            return { kind: 'date', optional: true };
+        case 'checkbox':
+            return { kind: 'boolean', optional: true };
+        case 'select':
+            return { kind: 'enum', optional: true, values: field.choices };
+        case 'multi_select':
+            return { kind: 'string[]', optional: true, plain: true, values: field.choices };
+        case 'person':
+            return { kind: 'member', optional: true };
+        case 'link':
+            return { kind: 'string[]', optional: true, plain: true };
+        case 'attachment':
+            return { kind: 'string[]', optional: true };
+    }
+}
+/** True for a type whose values a definition must list. */
+export const hasChoices = (type) => type === 'select' || type === 'multi_select';
+/** A definition in a few words, for an answer or a tool: `Amount (deal_size): currency, USD`. */
+export function describeField(field) {
+    const extra = hasChoices(field.type)
+        ? `, one of ${quoted(field.choices)}`
+        : field.type === 'currency' && field.currency
+            ? `, ${field.currency}`
+            : '';
+    return `${field.key} ("${field.name}"): ${field.type.replace('_', ' ')}${extra}${field.required ? ', required' : ''}`;
+}
+/**
+ * A key made from a name: `"Deal size"` → `deal_size`, suffixed when taken.
+ * Always a field name the tools can use, never a reserved one.
+ */
+export function keyFromName(name, taken) {
+    const slug = name
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, FIELD_LIMITS.nameChars - 4) || 'field';
+    const base = /^[a-z]/.test(slug) ? slug : `f_${slug}`.slice(0, FIELD_LIMITS.nameChars - 4);
+    const free = (key) => !taken.has(key) && !RESERVED_FIELDS.has(key);
+    if (free(base))
+        return base;
+    for (let n = 2;; n += 1) {
+        if (free(`${base}_${n}`))
+            return `${base}_${n}`;
+    }
+}
+/** Why a key cannot be a field's key here, or null. */
+export function keyProblem(key, fixed, taken) {
+    if (!FIELD_NAME.test(key) || key.length > FIELD_LIMITS.nameChars) {
+        return `key "${key}" must be letters, digits and _, starting with a lower-case letter, at most ${FIELD_LIMITS.nameChars} characters.`;
+    }
+    if (RESERVED_FIELDS.has(key) || fixed.has(key))
+        return `key "${key}" is a field Brydio or the app already keeps.`;
+    if (taken.has(key))
+        return `key "${key}" is already a field of this table.`;
+    return null;
+}
+/** The choices a definition lists, checked: some, short, distinct. */
+export function choicesProblem(type, choices) {
+    if (!hasChoices(type))
+        return null;
+    if (!choices.length)
+        return `A ${type.replace('_', ' ')} field needs at least one choice.`;
+    if (choices.length > FIELD_LIMITS.enumValues)
+        return `A field may offer at most ${FIELD_LIMITS.enumValues} choices.`;
+    if (choices.some(choice => !choice.trim() || choice.length > FIELD_LIMITS.enumValueChars)) {
+        return `Each choice is 1 to ${FIELD_LIMITS.enumValueChars} characters.`;
+    }
+    if (new Set(choices).size !== choices.length)
+        return 'A field offers the same choice twice.';
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Values
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:\d{2})$/;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PHONE = /^[+()0-9 .\-/]{3,40}$/;
+const isEmpty = (value) => value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0);
+/**
+ * What the store's own field type cannot say about an open value: a web
+ * address, an email, a rating's range, a date with no time, the choices of a
+ * multi-select. Null when it is fine; `checked` then checks the rest.
+ */
+export function openValueProblem(field, value) {
+    if (value === null || value === undefined)
+        return null;
+    const named = `${field.key} ("${field.name}")`;
+    switch (field.type) {
+        case 'url':
+            return typeof value === 'string' && isWebAddress(value) ? null : `${named} must be a web address, starting http:// or https://.`;
+        case 'email':
+            return typeof value === 'string' && EMAIL.test(value) ? null : `${named} must be an email address.`;
+        case 'phone':
+            return typeof value === 'string' && PHONE.test(value) ? null : `${named} must be a phone number.`;
+        case 'rating':
+            return Number.isInteger(value) && value >= 0 && value <= OPEN_LIMITS.ratingMax
+                ? null
+                : `${named} must be a whole number from 0 to ${OPEN_LIMITS.ratingMax}.`;
+        case 'date':
+            return typeof value === 'string' && DATE_ONLY.test(value) && !Number.isNaN(Date.parse(value))
+                ? null
+                : `${named} must be a date, written YYYY-MM-DD.`;
+        case 'datetime':
+            return typeof value === 'string' && DATE_TIME.test(value) && !Number.isNaN(Date.parse(value))
+                ? null
+                : `${named} must be a date and time, written YYYY-MM-DDTHH:MM:SSZ.`;
+        case 'multi_select': {
+            if (!Array.isArray(value))
+                return null;
+            const wrong = value.find(one => typeof one !== 'string' || !field.choices.includes(one));
+            if (wrong !== undefined)
+                return `${named} may hold only ${quoted(field.choices)}.`;
+            return new Set(value).size === value.length ? null : `${named} names the same choice twice.`;
+        }
+        default:
+            return null;
+    }
+}
+/** True when a create leaves a required field out. */
+export const missingRequired = (field, value) => field.required && isEmpty(value);
+function isWebAddress(value) {
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && value.length <= FIELD_LIMITS.stringChars;
+    }
+    catch {
+        return false;
+    }
+}
+const textOf = (value) => {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (Array.isArray(value))
+        return value.map(one => textOf(one) ?? '').filter(Boolean).join(', ');
+    return null;
+};
+const choiceOf = (choices, value) => choices.find(choice => choice === value) ?? choices.find(choice => choice.toLowerCase() === value.trim().toLowerCase());
+/**
+ * One value moved from a field's old definition to its new one (P5 retype):
+ * kept when it is still right, converted when it can be read as the new type,
+ * else cleared. Never invents a choice.
+ */
+export function moveValue(value, from, to) {
+    const moved = convert(value, from, to);
+    if (moved === undefined || isEmpty(moved))
+        return { outcome: 'cleared' };
+    const settled = openValueProblem(to, moved) === null;
+    if (!settled)
+        return { outcome: 'cleared' };
+    return { outcome: JSON.stringify(moved) === JSON.stringify(value) ? 'kept' : 'converted', value: moved };
+}
+function convert(value, from, to) {
+    const text = textOf(value);
+    switch (to.type) {
+        case 'text':
+            return text === null ? undefined : text.slice(0, FIELD_LIMITS.stringChars);
+        case 'long_text':
+            return text === null ? undefined : text.slice(0, FIELD_LIMITS.textChars);
+        case 'url':
+        case 'email':
+        case 'phone':
+            return text === null ? undefined : text.trim();
+        case 'number':
+        case 'currency':
+        case 'percent':
+        case 'rating': {
+            const number = typeof value === 'number'
+                ? value
+                : typeof value === 'boolean'
+                    ? Number(value)
+                    : typeof value === 'string' && value.trim()
+                        ? Number(value.trim().replace(/[\s,%$€£¥]/g, ''))
+                        : Number.NaN;
+            if (!Number.isFinite(number))
+                return undefined;
+            return to.type === 'rating' ? Math.round(number) : number;
+        }
+        case 'checkbox':
+            if (typeof value === 'boolean')
+                return value;
+            if (typeof value === 'number')
+                return value !== 0;
+            if (typeof value === 'string') {
+                if (/^(true|yes|y|1|x|checked|done)$/i.test(value.trim()))
+                    return true;
+                if (/^(false|no|n|0|unchecked)$/i.test(value.trim()))
+                    return false;
+            }
+            return undefined;
+        case 'date':
+        case 'datetime': {
+            if (typeof value !== 'string')
+                return undefined;
+            const head = value.trim();
+            if (to.type === 'date' && /^\d{4}-\d{2}-\d{2}/.test(head))
+                return head.slice(0, 10);
+            const at = Date.parse(DATE_ONLY.test(head) ? `${head}T00:00:00Z` : head);
+            if (Number.isNaN(at))
+                return undefined;
+            return to.type === 'date' ? new Date(at).toISOString().slice(0, 10) : new Date(at).toISOString();
+        }
+        case 'select': {
+            const candidates = Array.isArray(value) ? value : [text ?? ''];
+            for (const one of candidates) {
+                const found = typeof one === 'string' ? choiceOf(to.choices, one) : undefined;
+                if (found)
+                    return found;
+            }
+            return undefined;
+        }
+        case 'multi_select': {
+            const candidates = Array.isArray(value) ? value : (text ?? '').split(',');
+            const found = candidates
+                .map(one => (typeof one === 'string' ? choiceOf(to.choices, one) : undefined))
+                .filter((one) => Boolean(one));
+            return [...new Set(found)];
+        }
+        case 'person':
+            return from.type === 'person' ? value : undefined;
+        case 'link':
+        case 'attachment':
+            return from.type === to.type ? value : undefined;
+    }
+}
+/** Open types whose values are kept in the plain column: filtered, and all but the two lists sorted. */
+export const isPlainOpenType = (type) => !['text', 'long_text', 'url', 'email', 'phone', 'attachment'].includes(type);
+/**
+ * One companion record as a definition, or null when it cannot be one.
+ * `table` is the field naming its table, if the collection has tables.
+ */
+export function definitionOf(id, body, table) {
+    const { key, name, type } = body;
+    if (typeof key !== 'string' || typeof name !== 'string' || !OPEN_TYPES.includes(type)) {
+        return null;
+    }
+    const tableValue = table ? body[table] : null;
+    if (table && typeof tableValue !== 'string')
+        return null;
+    return {
+        id,
+        key,
+        name,
+        type: type,
+        table: tableValue ?? null,
+        choices: Array.isArray(body.choices) ? body.choices.filter((one) => typeof one === 'string') : [],
+        required: body.required === true,
+        ...(typeof body.currency === 'string' ? { currency: body.currency } : {}),
+        ...(typeof body.precision === 'number' ? { precision: body.precision } : {}),
+        ...(typeof body.linkTo === 'string' ? { linkTo: body.linkTo } : {}),
+        ...(typeof body.description === 'string' ? { description: body.description } : {}),
+    };
+}
+/**
+ * The collection's spec with one table's live fields folded in: what a row
+ * is checked against and what a list filters and sorts on. A fixed field
+ * always wins over a definition of the same key.
+ */
+export function openSpec(base, fields) {
+    const added = fields.filter(field => !base.fields[field.key]);
+    const types = Object.fromEntries(added.map(field => [field.key, fieldTypeOf(field)]));
+    const keys = added.map(field => field.key);
+    return {
+        ...base,
+        fields: { ...base.fields, ...types },
+        structured: [...base.structured, ...keys.filter(key => isStructured(types[key]))],
+        sortable: [...base.sortable, ...keys.filter(key => isSortable(types[key]))],
+        search: [...base.search, ...added.filter(field => field.type === 'text' || field.type === 'long_text').map(field => field.key)],
+    };
+}
+/** Why a definition's type and choices don't go together, or null. */
+export function definitionTypeProblem(body) {
+    const type = body.type;
+    if (typeof type !== 'string' || !OPEN_TYPES.includes(type))
+        return null;
+    const choices = Array.isArray(body.choices) ? body.choices.filter((one) => typeof one === 'string') : [];
+    return choicesProblem(type, choices);
+}

package/src/readers.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/**
+ * Record readers (P16): a record only the people it
+ * names may read.
+ *
+ * An app names one of the collection's own `string[]` fields, which holds
+ * user ids. When a record's list is empty, everyone who can read the
+ * instance reads it, as before; when it names anyone, nobody else finds it —
+ * not on a screen, not through a tool, not through the assistant, not on the
+ * co-edit socket. There is no admin past it: an app that wants its admins
+ * in puts them in the list. Brydio keeps the list in plain beside the record
+ * (`app_document.readers`), so every read can be narrowed before anything
+ * is decrypted. Mirrors Brydio's `apps/api/src/apps/manifest/readers.ts`;
+ * the two change together.
+ */
+export declare const readersSchema: z.ZodString;
+export type ReadersProblemCode = 'data_readers_field' | 'data_readers_anonymous';
+/** The most people one record's list may name. */
+export declare const READERS_LIMIT = 1000;
+export declare function readersProblems(collection: string, declared: {
+    schema: Record<string, unknown>;
+    readers?: string;
+    anonymous?: unknown;
+}): {
+    code: ReadersProblemCode;
+    collection: string;
+    field?: string;
+    message: string;
+}[];
+/** The plain list a record is kept with: its readers, or null for everyone who can read the instance. */
+export declare function readersOf(field: string | undefined, body: Record<string, unknown>): string[] | null;
+/**
+ * Record editors (DW06): a record only the people it names may change. The
+ * same shape as readers: one of the collection's own `string[]` fields of
+ * user ids, kept in plain beside the record (`app_document.editors`). Empty,
+ * and anyone who may write the instance may change it; naming anyone, and
+ * only they may — through a tool, a handler, the assistant or the co-edit
+ * socket, where anyone else's connection is read-only. Everyone who may read
+ * the record still reads it.
+ */
+export declare const editorsSchema: z.ZodString;
+export type EditorsProblemCode = 'data_editors_field' | 'data_editors_anonymous';
+export declare function editorsProblems(collection: string, declared: {
+    schema: Record<string, unknown>;
+    editors?: string;
+    anonymous?: unknown;
+}): {
+    code: EditorsProblemCode;
+    collection: string;
+    field?: string;
+    message: string;
+}[];
+/** The plain list a record is kept with: its editors, or null for anyone who may write the instance. */
+export declare const editorsOf: typeof readersOf;

package/src/readers.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { FIELD_LIMITS, parseFieldType } from "./field-types.js";
+/**
+ * Record readers (P16): a record only the people it
+ * names may read.
+ *
+ * An app names one of the collection's own `string[]` fields, which holds
+ * user ids. When a record's list is empty, everyone who can read the
+ * instance reads it, as before; when it names anyone, nobody else finds it —
+ * not on a screen, not through a tool, not through the assistant, not on the
+ * co-edit socket. There is no admin past it: an app that wants its admins
+ * in puts them in the list. Brydio keeps the list in plain beside the record
+ * (`app_document.readers`), so every read can be narrowed before anything
+ * is decrypted. Mirrors Brydio's `apps/api/src/apps/manifest/readers.ts`;
+ * the two change together.
+ */
+export const readersSchema = z.string().min(1).max(FIELD_LIMITS.nameChars);
+/** The most people one record's list may name. */
+export const READERS_LIMIT = 1_000;
+export function readersProblems(collection, declared) {
+    if (!declared.readers)
+        return [];
+    const problems = [];
+    const raw = declared.schema[declared.readers];
+    let listed = false;
+    try {
+        listed = raw !== undefined && parseFieldType(raw).kind === 'string[]';
+    }
+    catch {
+        // Refused as a field type already.
+    }
+    if (!listed) {
+        problems.push({
+            code: 'data_readers_field',
+            collection,
+            field: declared.readers,
+            message: `"${collection}" names "${declared.readers}" as its readers, which must be one of its own string[] fields holding user ids.`,
+        });
+    }
+    // An anonymous answer names nobody; a list of who may read it would.
+    if (declared.anonymous) {
+        problems.push({
+            code: 'data_readers_anonymous',
+            collection,
+            message: `"${collection}" can't be anonymous and name its readers.`,
+        });
+    }
+    return problems;
+}
+/** The plain list a record is kept with: its readers, or null for everyone who can read the instance. */
+export function readersOf(field, body) {
+    if (!field)
+        return null;
+    const value = body[field];
+    if (!Array.isArray(value))
+        return null;
+    const ids = [...new Set(value.filter((one) => typeof one === 'string' && one.length > 0))];
+    return ids.length ? ids.sort() : null;
+}
+/**
+ * Record editors (DW06): a record only the people it names may change. The
+ * same shape as readers: one of the collection's own `string[]` fields of
+ * user ids, kept in plain beside the record (`app_document.editors`). Empty,
+ * and anyone who may write the instance may change it; naming anyone, and
+ * only they may — through a tool, a handler, the assistant or the co-edit
+ * socket, where anyone else's connection is read-only. Everyone who may read
+ * the record still reads it.
+ */
+export const editorsSchema = readersSchema;
+export function editorsProblems(collection, declared) {
+    if (!declared.editors)
+        return [];
+    const problems = [];
+    const raw = declared.schema[declared.editors];
+    let listed = false;
+    try {
+        listed = raw !== undefined && parseFieldType(raw).kind === 'string[]';
+    }
+    catch {
+        // Refused as a field type already.
+    }
+    if (!listed) {
+        problems.push({
+            code: 'data_editors_field',
+            collection,
+            field: declared.editors,
+            message: `"${collection}" names "${declared.editors}" as its editors, which must be one of its own string[] fields holding user ids.`,
+        });
+    }
+    if (declared.anonymous) {
+        problems.push({ code: 'data_editors_anonymous', collection, message: `"${collection}" can't be anonymous and name its editors.` });
+    }
+    return problems;
+}
+/** The plain list a record is kept with: its editors, or null for anyone who may write the instance. */
+export const editorsOf = readersOf;