@book.dev/sdk 3.10.0 → 3.13.0

package/dist/database.js

@@ -3,7 +3,7 @@
  * StoredPage}. A **database** is a collection of pages (its *rows*) managed by
  * typed *properties* and presented through one or more configurable *views*
  * (table, list, gallery, board, calendar, timeline, map, relationship graph,
- * or a bar/pie chart).
+ * form, or a bar/pie chart).
  *
  * Three ideas make OpenBook databases different from a plain spreadsheet:
  *
@@ -28,6 +28,41 @@
  * record — properties, views, filters — lives in its own `databases` table.
  */
 import { evaluateFormula, FormulaError } from './formula';
+/**
+ * Whether a public form may write a property type in v1. This exhaustive map is
+ * the shared allowlist for builders and the submission validator. Reference,
+ * identity/attestation, computed, and server-managed properties fail closed.
+ */
+export const FORM_PROPERTY_TYPE_WRITABILITY = {
+    text: true,
+    number: true,
+    rating: true,
+    select: true,
+    multi_select: true,
+    status: true,
+    checkbox: true,
+    date: true,
+    url: true,
+    email: true,
+    phone: true,
+    location: true,
+    files: true,
+    relation: false,
+    dependency: false,
+    rollup: false,
+    created_time: false,
+    last_edited_time: false,
+    unique_id: false,
+    expr: false,
+    formula: false,
+    person: false,
+    verification: false,
+    backlinks: false,
+};
+/** True when `type` is safe for a public form fill in v1. */
+export function isFormWritablePropertyType(type) {
+    return FORM_PROPERTY_TYPE_WRITABILITY[type] === true;
+}
 /** Whether each side of a relation cardinality holds a single row. `1:1` is
  *  single both ways; `1:n` links many but each target points back to one; `n:n`
  *  is many both ways. */
@@ -50,6 +85,24 @@ export function asLocation(value) {
         ...(typeof v.address === 'string' && v.address.trim() ? { address: v.address } : {}),
     };
 }
+/** Runtime list for fail-closed decoding of persisted view types. */
+export const KNOWN_DATABASE_VIEW_TYPES = [
+    'table',
+    'list',
+    'gallery',
+    'board',
+    'calendar',
+    'timeline',
+    'map',
+    'graph',
+    'form',
+    'bar',
+    'pie',
+];
+/** True only for view layouts this SDK knows how to interpret. */
+export function isDatabaseViewType(value) {
+    return typeof value === 'string' && KNOWN_DATABASE_VIEW_TYPES.includes(value);
+}
 /** The value-less, relative-to-today date operators. */
 export const RELATIVE_DATE_OPS = [
     'is_today',
@@ -62,6 +115,25 @@ export const RELATIVE_DATE_OPS = [
 export function isFilterGroup(node) {
     return node.conjunction !== undefined;
 }
+/** Stable machine-readable failures returned by {@link validateRowAgainstForm}. */
+export const FORM_ROW_VALIDATION_ERROR_CODES = [
+    'view_type',
+    'unknown_field',
+    'required',
+    'type',
+    'min',
+    'max',
+    'minLength',
+    'maxLength',
+    'pattern',
+    'option',
+    'range',
+    'too_large',
+    'date_format',
+    'email_format',
+    'url_format',
+    'phone_format',
+];
 /**
  * Validate + normalise a database's {@link AutoExpiryConfig} against its schema,
  * returning the rule to apply, or `null` when auto-expiry should do nothing:
@@ -699,6 +771,21 @@ export function defaultDatabaseSchema() {
 /** A fresh view of a given type with sensible defaults for its layout. */
 export function defaultView(type, name, properties) {
     const view = { id: shortId('view'), name, type, filters: [], sorts: [] };
+    if (type === 'form') {
+        // A form's field list is always explicit and fail-closed. Form-only fields
+        // are added as ordinary pageHidden properties by the builder, then appended
+        // here just like any other form-writable database column.
+        view.visiblePropertyIds = [
+            TITLE_PROPERTY_ID,
+            ...properties
+                .filter((property) => property.id !== TITLE_PROPERTY_ID
+                && !property.id.startsWith('sys_')
+                && isFormWritablePropertyType(property.type))
+                .map((property) => property.id),
+        ];
+        view.formFields = {};
+        view.formConfig = { acceptingResponses: true };
+    }
     if (type === 'board' || type === 'bar' || type === 'pie') {
         // Default the grouping to the first categorical property (select/status/
         // relation — kanban columns / chart categories read best off one). With no
@@ -747,10 +834,11 @@ export const STATUS_GROUPS = [
 /**
  * Remove a property from a schema and scrub **every** dangling reference to it:
  * each view's filters (flat list *and* the nested {@link filterRoot} tree),
- * sorts, visible columns, summaries, and the group-by / date / cover config; plus
- * any `rollup` on another property that aggregated through or over it. Pure —
- * returns a fresh schema — so it can be unit-tested and shared by the delete
- * action. (Renders already tolerate stale refs; this keeps the schema clean.)
+ * sorts, visible columns, form-field metadata, summaries, and the group-by /
+ * date / cover config; plus any `rollup` on another property that aggregated
+ * through or over it. Pure — returns a fresh schema — so it can be unit-tested
+ * and shared by the delete action. (Renders already tolerate stale refs; this
+ * keeps the schema clean.)
  */
 export function removeProperty(schema, propertyId) {
     const pruneNode = (node) => {
@@ -777,12 +865,16 @@ export function removeProperty(schema, propertyId) {
             const summaries = v.summaries
                 ? Object.fromEntries(Object.entries(v.summaries).filter(([k]) => k !== propertyId))
                 : undefined;
+            const formFields = v.formFields
+                ? Object.fromEntries(Object.entries(v.formFields).filter(([k]) => k !== propertyId))
+                : undefined;
             return {
                 ...v,
                 filters: (v.filters ?? []).filter((f) => f.propertyId !== propertyId),
                 filterRoot: v.filterRoot ? pruneNode(v.filterRoot) : undefined,
                 sorts: (v.sorts ?? []).filter((s) => s.propertyId !== propertyId),
                 visiblePropertyIds: v.visiblePropertyIds?.filter((id) => id !== propertyId),
+                formFields,
                 summaries,
                 groupByPropertyId: v.groupByPropertyId === propertyId ? undefined : v.groupByPropertyId,
                 subGroupByPropertyId: v.subGroupByPropertyId === propertyId ? undefined : v.subGroupByPropertyId,
@@ -800,6 +892,388 @@ export function removeProperty(schema, propertyId) {
             : t),
     };
 }
+const FORM_EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+const FORM_PHONE_RE = /^\+?[0-9().\-\s]+$/;
+const FORM_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const FORM_DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})?$/;
+function formHasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function validFormCalendarDate(year, month, day) {
+    if (month < 1 || month > 12)
+        return false;
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return day >= 1 && day <= days[month - 1];
+}
+function validFormDate(value, includeTime) {
+    const match = (includeTime ? FORM_DATE_TIME_RE : FORM_DATE_RE).exec(value);
+    if (!match)
+        return false;
+    if (!validFormCalendarDate(Number(match[1]), Number(match[2]), Number(match[3])))
+        return false;
+    if (!includeTime)
+        return true;
+    return Number(match[4]) <= 23 && Number(match[5]) <= 59 && (match[6] === undefined || Number(match[6]) <= 59);
+}
+function formFieldIsEmpty(property, value) {
+    if (value === undefined || value === null)
+        return true;
+    // HTML controls can emit an empty string even when the backing property is
+    // numeric, boolean, or otherwise non-string. Treat it as absence before type
+    // validation so a required blank consistently reports `required`.
+    if (typeof value === 'string' && value.trim() === '')
+        return true;
+    switch (property.type) {
+        case 'multi_select':
+        case 'files':
+            return Array.isArray(value) && value.length === 0;
+        case 'date':
+            if (property.dateRange && typeof value === 'object' && !Array.isArray(value)) {
+                const range = value;
+                return !range.start && !range.end;
+            }
+            return false;
+        default:
+            return false;
+    }
+}
+function validateFormDateValue(property, value) {
+    const validPart = (part) => typeof part === 'string' && validFormDate(part, property.includeTime === true);
+    if (!property.dateRange)
+        return validPart(value) ? null : 'date_format';
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return 'type';
+    const range = value;
+    if (Object.keys(range).some((key) => key !== 'start' && key !== 'end'))
+        return 'type';
+    if (range.start !== null && range.start !== undefined && !validPart(range.start))
+        return 'date_format';
+    if (range.end !== null && range.end !== undefined && !validPart(range.end))
+        return 'date_format';
+    if (!validPart(range.start))
+        return 'date_format';
+    if (validPart(range.end)) {
+        // Date-only values sort chronologically as ISO strings. Date-times do not:
+        // mixed offsets can make a lexically earlier value represent a later instant
+        // (and vice versa), so compare their parsed instants instead.
+        const endBeforeStart = property.includeTime === true
+            ? Date.parse(range.end) < Date.parse(range.start)
+            : range.end < range.start;
+        if (endBeforeStart)
+            return 'range';
+    }
+    return null;
+}
+function validateFormLocation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return 'type';
+    const location = value;
+    if (Object.keys(location).some((key) => !['lat', 'lng', 'label', 'address'].includes(key)))
+        return 'type';
+    if (typeof location.lat !== 'number' || !Number.isFinite(location.lat))
+        return 'type';
+    if (typeof location.lng !== 'number' || !Number.isFinite(location.lng))
+        return 'type';
+    if (location.lat < -90 || location.lat > 90 || location.lng < -180 || location.lng > 180)
+        return 'range';
+    if (location.label !== undefined && typeof location.label !== 'string')
+        return 'type';
+    if (location.address !== undefined && typeof location.address !== 'string')
+        return 'type';
+    return null;
+}
+function validateFormPropertyValue(property, value) {
+    switch (property.type) {
+        case 'text':
+            return typeof value === 'string' ? null : 'type';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value) ? null : 'type';
+        case 'rating': {
+            if (typeof value !== 'number' || !Number.isInteger(value))
+                return 'type';
+            const max = property.numberTarget && property.numberTarget > 0 ? Math.min(10, Math.round(property.numberTarget)) : 5;
+            return value >= 1 && value <= max ? null : 'range';
+        }
+        case 'select':
+        case 'status':
+            if (typeof value !== 'string')
+                return 'type';
+            return property.options?.some((option) => option.id === value) ? null : 'option';
+        case 'multi_select': {
+            if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string'))
+                return 'type';
+            if (new Set(value).size !== value.length)
+                return 'option';
+            const options = new Set((property.options ?? []).map((option) => option.id));
+            return value.every((entry) => options.has(entry)) ? null : 'option';
+        }
+        case 'checkbox':
+            return typeof value === 'boolean' ? null : 'type';
+        case 'date':
+            return validateFormDateValue(property, value);
+        case 'url':
+            if (typeof value !== 'string')
+                return 'type';
+            try {
+                const url = new URL(value);
+                return (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname ? null : 'url_format';
+            }
+            catch {
+                return 'url_format';
+            }
+        case 'email':
+            return typeof value !== 'string' ? 'type' : FORM_EMAIL_RE.test(value) ? null : 'email_format';
+        case 'phone': {
+            if (typeof value !== 'string')
+                return 'type';
+            const digits = value.replace(/\D/g, '').length;
+            return FORM_PHONE_RE.test(value) && digits >= 7 && digits <= 15 ? null : 'phone_format';
+        }
+        case 'location':
+            return validateFormLocation(value);
+        case 'files':
+            return Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.length > 0) ? null : 'type';
+        default:
+            return 'unknown_field';
+    }
+}
+function copyFormValue(value) {
+    if (Array.isArray(value))
+        return [...value];
+    if (value && typeof value === 'object')
+        return { ...value };
+    return value;
+}
+const FORM_TITLE_PROPERTY = {
+    id: TITLE_PROPERTY_ID,
+    name: 'Title',
+    type: 'text',
+};
+/** Resolve the ordered, current, writable field mapping, including row title. */
+function mappedFormProperties(schema, view) {
+    const byId = new Map(schema.properties.map((property) => [property.id, property]));
+    return (view.visiblePropertyIds ?? [])
+        .map((propertyId) => propertyId === TITLE_PROPERTY_ID ? FORM_TITLE_PROPERTY : byId.get(propertyId))
+        .filter((property) => property !== undefined && !property.id.startsWith('sys_') && isFormWritablePropertyType(property.type));
+}
+/** Conservative structural screen for common exponential-backtracking forms. */
+export function formPatternIsUnsafe(pattern) {
+    if (/\\(?:[1-9]|k<)/.test(pattern))
+        return true;
+    const frames = [{ hasAlternation: false, hasQuantifier: false }];
+    let inClass = false;
+    let quantifiers = 0;
+    for (let i = 0; i < pattern.length; i += 1) {
+        const char = pattern[i];
+        if (char === '\\') {
+            i += 1;
+            continue;
+        }
+        if (inClass) {
+            if (char === ']')
+                inClass = false;
+            continue;
+        }
+        if (char === '[') {
+            inClass = true;
+            continue;
+        }
+        if (char === '(') {
+            if (pattern[i + 1] === '?' && pattern[i + 2] !== ':')
+                return true;
+            if (pattern[i + 1] === '?' && pattern[i + 2] === ':')
+                i += 2;
+            frames.push({ hasAlternation: false, hasQuantifier: false });
+            continue;
+        }
+        if (char === '|') {
+            frames[frames.length - 1].hasAlternation = true;
+            continue;
+        }
+        if (char === ')') {
+            if (frames.length === 1)
+                continue;
+            const frame = frames.pop();
+            const next = pattern[i + 1];
+            const quantified = next === '*' || next === '+' || next === '?' || next === '{';
+            if (quantified && (frame.hasAlternation || frame.hasQuantifier))
+                return true;
+            const parent = frames[frames.length - 1];
+            parent.hasAlternation || (parent.hasAlternation = frame.hasAlternation);
+            parent.hasQuantifier || (parent.hasQuantifier = frame.hasQuantifier || quantified);
+            continue;
+        }
+        if (char === '*' || char === '+' || char === '?' || char === '{') {
+            frames[frames.length - 1].hasQuantifier = true;
+            quantifiers += 1;
+            if (quantifiers > 8)
+                return true;
+        }
+    }
+    return inClass;
+}
+function validateFormFieldConstraints(metadata, value) {
+    const validation = metadata?.validation;
+    if (!validation)
+        return [];
+    const errors = [];
+    if (typeof value === 'number') {
+        if (typeof validation.min === 'number' && value < validation.min)
+            errors.push('min');
+        if (typeof validation.max === 'number' && value > validation.max)
+            errors.push('max');
+    }
+    const length = typeof value === 'string' || Array.isArray(value) ? value.length : undefined;
+    if (length !== undefined) {
+        if (typeof validation.minLength === 'number' && length < validation.minLength)
+            errors.push('minLength');
+        if (typeof validation.maxLength === 'number' && length > validation.maxLength)
+            errors.push('maxLength');
+    }
+    if (validation.pattern !== undefined && typeof value === 'string') {
+        const pattern = validation.pattern;
+        if (typeof pattern !== 'string'
+            || pattern.length > 256
+            || value.length > 1024
+            || formPatternIsUnsafe(pattern)) {
+            errors.push('pattern');
+        }
+        else {
+            try {
+                if (!new RegExp(pattern).test(value))
+                    errors.push('pattern');
+            }
+            catch {
+                errors.push('pattern');
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Project only the public rendering contract from a freshly loaded form view.
+ * Returns `null` for a non-form view so callers cannot accidentally serialize a
+ * normal database view through the public endpoint.
+ */
+export function projectDatabaseFormDescriptor(schema, view) {
+    if (view.type !== 'form')
+        return null;
+    const config = view.formConfig;
+    const acceptingResponses = config?.acceptingResponses === true;
+    const fields = mappedFormProperties(schema, view).map((property) => {
+        const metadata = view.formFields && formHasOwn(view.formFields, property.id)
+            ? view.formFields[property.id]
+            : undefined;
+        const field = {
+            propertyId: property.id,
+            type: property.type,
+            label: metadata?.label ?? property.name,
+            help: metadata?.help ?? '',
+            required: metadata?.required === true,
+            placeholder: metadata?.placeholder ?? '',
+        };
+        if (property.type === 'text' && metadata?.multiline !== undefined) {
+            field.multiline = metadata.multiline;
+        }
+        const validation = metadata?.validation;
+        if (validation) {
+            const displayValidation = {
+                ...(validation.min !== undefined ? { min: validation.min } : {}),
+                ...(validation.max !== undefined ? { max: validation.max } : {}),
+                ...(validation.minLength !== undefined ? { minLength: validation.minLength } : {}),
+                ...(validation.maxLength !== undefined ? { maxLength: validation.maxLength } : {}),
+            };
+            if (Object.keys(displayValidation).length > 0)
+                field.validation = displayValidation;
+        }
+        if ((property.type === 'select' || property.type === 'multi_select' || property.type === 'status')
+            && property.options !== undefined) {
+            field.options = property.options.map((option) => ({ ...option }));
+        }
+        if (property.type === 'date') {
+            if (property.includeTime !== undefined)
+                field.includeTime = property.includeTime;
+            if (property.dateRange !== undefined)
+                field.dateRange = property.dateRange;
+        }
+        if ((property.type === 'number' || property.type === 'rating') && property.numberTarget !== undefined) {
+            field.numberTarget = property.numberTarget;
+        }
+        return field;
+    });
+    return {
+        title: config?.title ?? view.name,
+        description: config?.description ?? '',
+        submitLabel: config?.submitLabel ?? 'Submit',
+        acceptingResponses,
+        ...(!acceptingResponses && config?.closedMessage !== undefined
+            ? { closedMessage: config.closedMessage }
+            : {}),
+        fields,
+    };
+}
+/**
+ * Validate an untrusted public fill against the database's current schema and
+ * form mapping. The allowlist is the form's explicit `visiblePropertyIds`
+ * intersected with current form-writable properties. Unknown, deleted,
+ * non-visible, computed, and managed fields are rejected; successful output is
+ * a fresh record containing only validated fields ready for row creation.
+ */
+export function validateRowAgainstForm(schema, view, fields) {
+    if (view.type !== 'form')
+        return { ok: false, errors: [{ propertyId: '', code: 'view_type' }] };
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields)) {
+        return { ok: false, errors: [{ propertyId: '', code: 'type' }] };
+    }
+    const mapped = mappedFormProperties(schema, view);
+    const allowedIds = new Set(mapped.map((property) => property.id));
+    const errors = [];
+    for (const propertyId of Object.keys(fields)) {
+        if (!allowedIds.has(propertyId))
+            errors.push({ propertyId, code: 'unknown_field' });
+    }
+    const validated = {};
+    let name;
+    for (const property of mapped) {
+        const present = formHasOwn(fields, property.id);
+        const value = present ? fields[property.id] : undefined;
+        const metadata = view.formFields && formHasOwn(view.formFields, property.id)
+            ? view.formFields[property.id]
+            : undefined;
+        if (!present || formFieldIsEmpty(property, value)) {
+            if (metadata?.required === true)
+                errors.push({ propertyId: property.id, code: 'required' });
+            if (property.id === TITLE_PROPERTY_ID)
+                name = '';
+            continue;
+        }
+        const code = validateFormPropertyValue(property, value);
+        if (code) {
+            errors.push({ propertyId: property.id, code });
+            continue;
+        }
+        const constraintCodes = validateFormFieldConstraints(metadata, value);
+        if (constraintCodes.length > 0) {
+            for (const constraintCode of constraintCodes)
+                errors.push({ propertyId: property.id, code: constraintCode });
+            continue;
+        }
+        if (property.id === TITLE_PROPERTY_ID) {
+            name = value;
+            continue;
+        }
+        Object.defineProperty(validated, property.id, {
+            value: copyFormValue(value),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return name === undefined ? { ok: true, fields: validated } : { ok: true, name, fields: validated };
+}
 // ── Number formatting ────────────────────────────────────────────────────────
 const FORMAT_PREFIX = { dollar: '$', euro: '€', pound: '£', rupee: '₹' };
 /** Format a numeric value for display per a {@link NumberFormat}. Non-numbers pass through as text. */