@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/computed/validate.js

@@ -0,0 +1,146 @@
+import { parseExpressionShape } from "./schema.js";
+function pathText(path) {
+    let result = '$';
+    for (const segment of path) {
+        result += typeof segment === 'number' ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+    }
+    return result;
+}
+function add(diagnostics, code, path, message, hint) {
+    diagnostics.push({ code, path, jsonPath: pathText(path), message, hint });
+}
+function valueType(kind) {
+    if (['text', 'longText', 'email', 'url', 'phone', 'enum'].includes(kind))
+        return 'string';
+    if (['number', 'integer', 'money'].includes(kind))
+        return 'number';
+    if (kind === 'boolean')
+        return 'boolean';
+    if (kind === 'date' || kind === 'datetime')
+        return 'date';
+    return null;
+}
+function infer(expression, context, path, diagnostics) {
+    if (expression.op === 'literal') {
+        return {
+            type: expression.value === null
+                ? 'null'
+                : typeof expression.value === 'number'
+                    ? 'number'
+                    : typeof expression.value === 'boolean'
+                        ? 'boolean'
+                        : 'string',
+            nullable: expression.value === null,
+        };
+    }
+    if (expression.op === 'field') {
+        const field = context.sourceEntity.fields.find((candidate) => candidate.name === expression.field);
+        if (!field) {
+            add(diagnostics, 'unknown-field', [...path, 'field'], `unknown field "${expression.field}" on "${context.sourceEntity.name}"`, 'Use a field declared on the source entity or add it before referencing it.');
+            return null;
+        }
+        const type = valueType(field.kind);
+        if (!type) {
+            add(diagnostics, 'unsupported-field-type', [...path, 'field'], `field "${expression.field}" has unsupported computed type "${field.kind}"`, 'Reference a scalar text, number, integer, money, boolean, date, datetime or enum field.');
+            return null;
+        }
+        return { type, nullable: !('required' in field && field.required === true) };
+    }
+    if (expression.op === 'aggregate') {
+        const relation = context.sourceEntity.fields.find((candidate) => candidate.name === expression.relation);
+        if (relation?.kind !== 'relation' || !('to' in relation)) {
+            add(diagnostics, 'invalid-relation', [...path, 'relation'], `"${expression.relation}" is not a relation field on "${context.sourceEntity.name}"`, 'Set relation to a relation field declared on the source entity.');
+            return null;
+        }
+        const target = context.entities.find((entity) => entity.name === relation.to);
+        if (!target) {
+            add(diagnostics, 'unknown-relation-target', [...path, 'relation'], `relation "${expression.relation}" targets unknown entity "${relation.to}"`, 'Declare the relation target entity before using an aggregate.');
+            return null;
+        }
+        if (expression.aggregate === 'count') {
+            if (expression.field !== undefined) {
+                add(diagnostics, 'unexpected-aggregate-field', [...path, 'field'], 'count does not take a field', 'Remove field from a count aggregate.');
+                return null;
+            }
+            return { type: 'number', nullable: false };
+        }
+        if (expression.field === undefined) {
+            add(diagnostics, 'missing-aggregate-field', [...path, 'field'], `${expression.aggregate} needs a field`, 'Set field to a supported scalar field on the relation target.');
+            return null;
+        }
+        const field = target.fields.find((candidate) => candidate.name === expression.field);
+        if (!field) {
+            add(diagnostics, 'unknown-field', [...path, 'field'], `unknown field "${expression.field}" on relation target "${target.name}"`, 'Use a field declared on the relation target entity.');
+            return null;
+        }
+        const type = valueType(field.kind);
+        const accepted = expression.aggregate === 'min' || expression.aggregate === 'max'
+            ? type === 'number' || type === 'date'
+            : type === 'number';
+        if (!accepted) {
+            add(diagnostics, 'invalid-aggregate-type', [...path, 'field'], `${expression.aggregate} cannot aggregate field kind "${field.kind}"`, expression.aggregate === 'min' || expression.aggregate === 'max'
+                ? 'Choose a number, integer, money, date or datetime field.'
+                : 'Choose a number, integer or money field.');
+            return null;
+        }
+        return { type: type, nullable: true };
+    }
+    if (expression.op === 'concat') {
+        const children = expression.values.map((value, index) => infer(value, context, [...path, 'values', index], diagnostics));
+        const invalid = children.some((child) => child === null || (child.type !== 'string' && child.type !== 'null'));
+        if (invalid) {
+            add(diagnostics, 'invalid-operand-type', [...path, 'values'], 'concat accepts only string expressions', 'Use text-like fields or string literals in concat.');
+            return null;
+        }
+        return { type: 'string', nullable: children.some((child) => child?.nullable) };
+    }
+    if (expression.op === 'dateDiff') {
+        const start = infer(expression.start, context, [...path, 'start'], diagnostics);
+        const end = infer(expression.end, context, [...path, 'end'], diagnostics);
+        if (start && start.type !== 'date' && start.type !== 'null') {
+            add(diagnostics, 'invalid-operand-type', [...path, 'start'], 'dateDiff start must be a date or datetime expression', 'Use a date or datetime field.');
+        }
+        if (end && end.type !== 'date' && end.type !== 'null') {
+            add(diagnostics, 'invalid-operand-type', [...path, 'end'], 'dateDiff end must be a date or datetime expression', 'Use a date or datetime field.');
+        }
+        if (!start ||
+            !end ||
+            (start.type !== 'date' && start.type !== 'null') ||
+            (end.type !== 'date' && end.type !== 'null'))
+            return null;
+        return { type: 'number', nullable: start.nullable || end.nullable };
+    }
+    const left = infer(expression.left, context, [...path, 'left'], diagnostics);
+    const right = infer(expression.right, context, [...path, 'right'], diagnostics);
+    if (left && left.type !== 'number') {
+        add(diagnostics, 'invalid-operand-type', [...path, 'left'], `${expression.op} left operand must be numeric`, 'Use a number, integer, money field or numeric literal.');
+    }
+    if (right && right.type !== 'number') {
+        add(diagnostics, 'invalid-operand-type', [...path, 'right'], `${expression.op} right operand must be numeric`, 'Use a number, integer, money field or numeric literal.');
+    }
+    if (!left || !right || left.type !== 'number' || right.type !== 'number')
+        return null;
+    return {
+        type: 'number',
+        nullable: left.nullable || right.nullable || expression.op === 'divide',
+    };
+}
+/** Validate AST shape, field references, operator input types and inferred output type. */
+export function validateComputedExpression(input, context) {
+    const parsed = parseExpressionShape(input);
+    if (!parsed.success) {
+        return { valid: false, diagnostics: parsed.diagnostics, resultType: null, nullable: false };
+    }
+    const diagnostics = [];
+    const inferred = infer(parsed.data, context, [], diagnostics);
+    return {
+        valid: diagnostics.length === 0 && inferred !== null,
+        diagnostics,
+        resultType: diagnostics.length === 0 ? (inferred?.type ?? null) : null,
+        nullable: diagnostics.length === 0 ? (inferred?.nullable ?? false) : false,
+    };
+}
+/** Helper for callers that need to use the public entity shape as context. */
+export function computedContext(sourceEntity, entities) {
+    return { sourceEntity, entities };
+}

package/dist/csv-guard.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Spreadsheet formula guard shared by every CSV exporter (blueprint entity
+ * export, crud analytics export). Kept dependency-free and tiny so the main
+ * `@protoyard/blueprint` entry can re-export it without pulling in the codec.
+ */
+/** Limits used by the opt-in CSV shape authoring importer. */
+export declare const CSV_SHAPE_MAX_COLUMNS = 100;
+export declare const CSV_SHAPE_MAX_SAMPLE_ROWS = 100;
+export declare const CSV_SHAPE_MAX_CELL_BYTES: number;
+/** True when `text` would be evaluated as a formula and is not a plain number. */
+export declare function needsCsvFormulaGuard(text: string): boolean;
+/** Prefix formula-like text with `'` so spreadsheets show it as text. */
+export declare function guardCsvFormula(text: string): string;
+/** Inverse of {@link guardCsvFormula}: strips the `'` only when export would have added it. */
+export declare function unguardCsvFormula(text: string): string;

package/dist/csv-guard.js

@@ -0,0 +1,29 @@
+/**
+ * Spreadsheet formula guard shared by every CSV exporter (blueprint entity
+ * export, crud analytics export). Kept dependency-free and tiny so the main
+ * `@protoyard/blueprint` entry can re-export it without pulling in the codec.
+ */
+/**
+ * Leading characters that make Excel, LibreOffice or Sheets read a cell as a
+ * formula: `= + - @` (also after leading whitespace, and their full-width
+ * forms), or a leading tab or carriage return.
+ */
+const FORMULA_TRIGGER = /^(?:[\t\r]|\s*[=+\-@\uFF1D\uFF0B\uFF0D\uFF20])/;
+/** A whole-cell plain number (`-5`, `+1.25`, `.5`, `1e3`): inert in every spreadsheet. */
+const PLAIN_NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+/** Limits used by the opt-in CSV shape authoring importer. */
+export const CSV_SHAPE_MAX_COLUMNS = 100;
+export const CSV_SHAPE_MAX_SAMPLE_ROWS = 100;
+export const CSV_SHAPE_MAX_CELL_BYTES = 16 * 1024;
+/** True when `text` would be evaluated as a formula and is not a plain number. */
+export function needsCsvFormulaGuard(text) {
+    return FORMULA_TRIGGER.test(text) && !PLAIN_NUMBER.test(text);
+}
+/** Prefix formula-like text with `'` so spreadsheets show it as text. */
+export function guardCsvFormula(text) {
+    return needsCsvFormulaGuard(text) ? `'${text}` : text;
+}
+/** Inverse of {@link guardCsvFormula}: strips the `'` only when export would have added it. */
+export function unguardCsvFormula(text) {
+    return text.startsWith("'") && needsCsvFormulaGuard(text.slice(1)) ? text.slice(1) : text;
+}

package/dist/csv.d.ts

@@ -0,0 +1,85 @@
+import type { BlueprintEntity, BlueprintField } from './schema.ts';
+import { type EntityInput } from './validation.ts';
+/**
+ * Dependency-free RFC 4180 CSV codec for blueprint import/export.
+ * Load via `import('@protoyard/blueprint/csv')` so the main blueprint entry
+ * stays free of this code until the user opens import/export.
+ */
+/** Default hard limits — override per call when a larger demo is intentional. */
+export declare const CSV_MAX_BYTES: number;
+export declare const CSV_MAX_ROWS = 10000;
+export { guardCsvFormula, needsCsvFormulaGuard, unguardCsvFormula } from './csv-guard.ts';
+export type CsvErrorCode = 'too-large' | 'too-many-rows' | 'empty' | 'header' | 'parse' | 'columns';
+export declare class CsvError extends Error {
+    readonly code: CsvErrorCode;
+    constructor(code: CsvErrorCode, message: string);
+}
+export interface CsvLimits {
+    maxBytes?: number;
+    /** Data rows only (header is not counted). */
+    maxRows?: number;
+}
+export interface CsvParseOptions extends CsvLimits {
+    /** When false, leave leading BOM in the first cell (default strips it). */
+    keepBom?: boolean;
+}
+export interface CsvSerializeOptions {
+    /**
+     * Prefix cells that start with `= + - @`, a tab or a carriage return with a
+     * single quote so spreadsheets do not treat them as formulas, unless the
+     * whole cell is a plain number such as `-5` or `+1.5` (default true).
+     */
+    guardFormulas?: boolean;
+    /** Line ending (default `\r\n` per RFC 4180). */
+    newline?: '\r\n' | '\n';
+}
+export interface CsvColumn {
+    /** Row / input property (`customerId`, `subject`, …). */
+    property: string;
+    /** Header text written on export / matched on import. */
+    header: string;
+    field?: BlueprintField;
+    /** Geo fields export as two columns, `<name>Lat` and `<name>Lng`. */
+    part?: 'lat' | 'lng';
+}
+export interface CsvRowError {
+    /** 1-based data row index (first row after the header is 1). */
+    row: number;
+    /** Input property or `form` / `row` for whole-row problems. */
+    field: string;
+    message: string;
+}
+export interface CsvValidationResult {
+    headers: string[];
+    columns: CsvColumn[];
+    /** Successfully validated create-shaped rows (coerced). */
+    valid: EntityInput[];
+    errors: CsvRowError[];
+    /** Total data rows seen (valid + invalid). */
+    rowCount: number;
+}
+/**
+ * Parse RFC 4180 CSV into a matrix of cell strings.
+ * Handles quoted fields, escaped quotes (`""`), CRLF / LF / CR, and a leading BOM.
+ */
+export declare function parseCsv(text: string, options?: CsvParseOptions): string[][];
+/** Escape one cell for RFC 4180; optionally neutralize spreadsheet formulas. */
+export declare function escapeCsvCell(value: unknown, options?: CsvSerializeOptions): string;
+/** Serialize a matrix of cells to CSV text (CRLF by default). */
+export declare function serializeCsv(rows: readonly (readonly unknown[])[], options?: CsvSerializeOptions): string;
+/** Format a row value for export (money as major units, tags joined, …). */
+export declare function formatCsvValue(value: unknown, field?: BlueprintField): string;
+/** Columns for an entity: header is label (or name), property is the input key. */
+export declare function entityCsvColumns(entity: BlueprintEntity): CsvColumn[];
+/**
+ * Map header cells to entity columns by case-insensitive match on field name,
+ * input property, or label.
+ */
+export declare function mapCsvHeaders(headers: string[], entity: BlueprintEntity): CsvColumn[];
+/** Serialize entity-shaped records using the entity's column headers. */
+export declare function serializeEntityCsv(entity: BlueprintEntity, records: readonly EntityInput[], options?: CsvSerializeOptions): string;
+/**
+ * Parse CSV text and validate each data row against the entity's create schema.
+ * Unknown columns fail at the header; per-cell issues become `{ row, field, message }`.
+ */
+export declare function validateCsv(entity: BlueprintEntity, text: string, options?: CsvParseOptions): CsvValidationResult;

package/dist/csv.js

@@ -0,0 +1,288 @@
+import { parseInput, ValidationError } from '@protoyard/core';
+import { guardCsvFormula, unguardCsvFormula } from "./csv-guard.js";
+import { deriveInputSchemas, fieldLabel, inputProperty } from "./validation.js";
+/**
+ * Dependency-free RFC 4180 CSV codec for blueprint import/export.
+ * Load via `import('@protoyard/blueprint/csv')` so the main blueprint entry
+ * stays free of this code until the user opens import/export.
+ */
+/** Default hard limits — override per call when a larger demo is intentional. */
+export const CSV_MAX_BYTES = 2 * 1024 * 1024;
+export const CSV_MAX_ROWS = 10_000;
+export { guardCsvFormula, needsCsvFormulaGuard, unguardCsvFormula } from "./csv-guard.js";
+export class CsvError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CsvError';
+        this.code = code;
+    }
+}
+function assertLimits(text, limits = {}) {
+    const maxBytes = limits.maxBytes ?? CSV_MAX_BYTES;
+    const bytes = typeof TextEncoder !== 'undefined' ? new TextEncoder().encode(text).length : text.length;
+    if (bytes > maxBytes) {
+        throw new CsvError('too-large', `CSV is ${bytes.toLocaleString()} bytes; the limit is ${maxBytes.toLocaleString()} bytes`);
+    }
+}
+/**
+ * Parse RFC 4180 CSV into a matrix of cell strings.
+ * Handles quoted fields, escaped quotes (`""`), CRLF / LF / CR, and a leading BOM.
+ */
+export function parseCsv(text, options = {}) {
+    assertLimits(text, options);
+    let source = text;
+    if (!options.keepBom && source.charCodeAt(0) === 0xfeff) {
+        source = source.slice(1);
+    }
+    if (source.length === 0) {
+        throw new CsvError('empty', 'CSV is empty');
+    }
+    const maxRows = options.maxRows ?? CSV_MAX_ROWS;
+    const rows = [];
+    let row = [];
+    let field = '';
+    let i = 0;
+    let inQuotes = false;
+    const pushField = () => {
+        row.push(field);
+        field = '';
+    };
+    const pushRow = () => {
+        // A trailing newline after the last row yields an empty trailing row — drop it.
+        if (row.length === 1 && row[0] === '' && rows.length > 0 && i >= source.length) {
+            row = [];
+            return;
+        }
+        rows.push(row);
+        row = [];
+        // Header + data rows: allow header free, then enforce max data rows.
+        if (rows.length > maxRows + 1) {
+            throw new CsvError('too-many-rows', `CSV has more than ${maxRows.toLocaleString()} data rows; split the file or raise maxRows`);
+        }
+    };
+    while (i < source.length) {
+        const ch = source[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (source[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i += 1;
+                continue;
+            }
+            field += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            inQuotes = true;
+            i += 1;
+            continue;
+        }
+        if (ch === ',') {
+            pushField();
+            i += 1;
+            continue;
+        }
+        if (ch === '\r' || ch === '\n') {
+            pushField();
+            pushRow();
+            if (ch === '\r' && source[i + 1] === '\n')
+                i += 2;
+            else
+                i += 1;
+            continue;
+        }
+        field += ch;
+        i += 1;
+    }
+    if (inQuotes) {
+        throw new CsvError('parse', 'CSV ends inside a quoted field (missing closing quote)');
+    }
+    // Final field/row when the file does not end with a newline.
+    if (field.length > 0 || row.length > 0 || source.endsWith(',')) {
+        pushField();
+        // Avoid double-pushing an empty row when the file ended with a newline
+        // (pushRow already ran) and we have nothing left.
+        if (row.length > 1 || (row.length === 1 && (row[0] !== '' || rows.length === 0))) {
+            pushRow();
+        }
+        else if (row.length === 1 && row[0] === '' && rows.length === 0) {
+            pushRow();
+        }
+    }
+    if (rows.length === 0) {
+        throw new CsvError('empty', 'CSV has no rows');
+    }
+    return rows;
+}
+/** Escape one cell for RFC 4180; optionally neutralize spreadsheet formulas. */
+export function escapeCsvCell(value, options = {}) {
+    let text = value === null || value === undefined ? '' : String(value);
+    const guard = options.guardFormulas !== false;
+    if (guard)
+        text = guardCsvFormula(text);
+    if (/[",\r\n]/.test(text)) {
+        return `"${text.replace(/"/g, '""')}"`;
+    }
+    return text;
+}
+/** Serialize a matrix of cells to CSV text (CRLF by default). */
+export function serializeCsv(rows, options = {}) {
+    const newline = options.newline ?? '\r\n';
+    return rows.map((row) => row.map((cell) => escapeCsvCell(cell, options)).join(',')).join(newline);
+}
+/** Format a row value for export (money as major units, tags joined, …). */
+export function formatCsvValue(value, field) {
+    if (value === null || value === undefined)
+        return '';
+    if (field?.kind === 'money' && typeof value === 'number') {
+        const sign = value < 0 ? '-' : '';
+        const abs = Math.abs(value);
+        return `${sign}${(abs / 100).toFixed(2)}`;
+    }
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (Array.isArray(value))
+        return value.map(String).join(',');
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/** Columns for an entity: header is label (or name), property is the input key. */
+export function entityCsvColumns(entity) {
+    return entity.fields.flatMap((field) => field.kind === 'geo'
+        ? ['lat', 'lng'].map((part) => ({
+            property: inputProperty(field),
+            header: `${field.name}${part === 'lat' ? 'Lat' : 'Lng'}`,
+            field,
+            part,
+        }))
+        : [{ property: inputProperty(field), header: fieldLabel(field), field }]);
+}
+/** Header keys a column answers to (case-insensitive). */
+function columnKeys(col) {
+    if (col.part && col.field) {
+        const suffix = col.part === 'lat' ? 'lat' : 'lng';
+        return [col.header, `${col.field.name} ${suffix}`, `${fieldLabel(col.field)} ${suffix}`];
+    }
+    return [col.property, col.header, col.field?.name, col.field?.label].filter((k) => typeof k === 'string' && k.length > 0);
+}
+const columnId = (col) => (col.part ? `${col.property}.${col.part}` : col.property);
+/**
+ * Map header cells to entity columns by case-insensitive match on field name,
+ * input property, or label.
+ */
+export function mapCsvHeaders(headers, entity) {
+    if (headers.length === 0 || headers.every((h) => h.trim() === '')) {
+        throw new CsvError('header', 'CSV has no header row');
+    }
+    const columns = entityCsvColumns(entity);
+    const byKey = new Map();
+    for (const col of columns) {
+        for (const key of columnKeys(col)) {
+            byKey.set(key.trim().toLowerCase(), col);
+        }
+    }
+    const mapped = [];
+    const seen = new Set();
+    for (const header of headers) {
+        const key = header.trim().toLowerCase();
+        if (!key) {
+            mapped.push({ property: '', header, field: undefined });
+            continue;
+        }
+        const col = byKey.get(key);
+        if (!col) {
+            throw new CsvError('header', `Unknown CSV column "${header}". Expected field names or labels such as ${columns
+                .slice(0, 5)
+                .map((c) => c.header)
+                .join(', ')}`);
+        }
+        if (seen.has(columnId(col))) {
+            throw new CsvError('header', `Duplicate CSV column for "${col.header}"`);
+        }
+        seen.add(columnId(col));
+        mapped.push({ ...col, header });
+    }
+    return mapped;
+}
+/** Serialize entity-shaped records using the entity's column headers. */
+export function serializeEntityCsv(entity, records, options = {}) {
+    const columns = entityCsvColumns(entity);
+    const header = columns.map((c) => c.header);
+    const body = records.map((record) => columns.map((col) => {
+        const value = record[col.property];
+        if (!col.part)
+            return formatCsvValue(value, col.field);
+        const point = value;
+        return formatCsvValue(point?.[col.part]);
+    }));
+    return serializeCsv([header, ...body], options);
+}
+/**
+ * Parse CSV text and validate each data row against the entity's create schema.
+ * Unknown columns fail at the header; per-cell issues become `{ row, field, message }`.
+ */
+export function validateCsv(entity, text, options = {}) {
+    const matrix = parseCsv(text, options);
+    const [headerRow, ...dataRows] = matrix;
+    if (!headerRow) {
+        throw new CsvError('empty', 'CSV has no header row');
+    }
+    const columns = mapCsvHeaders(headerRow, entity);
+    const { create } = deriveInputSchemas(entity);
+    const valid = [];
+    const errors = [];
+    dataRows.forEach((cells, index) => {
+        const rowNumber = index + 1;
+        // Skip fully empty lines (common trailing artifact).
+        if (cells.every((c) => c.trim() === ''))
+            return;
+        const input = {};
+        columns.forEach((col, colIndex) => {
+            if (!col.property)
+                return;
+            // Undo the export formula guard so exported values round-trip exactly.
+            const raw = unguardCsvFormula(cells[colIndex] ?? '');
+            if (col.part) {
+                // Both halves of a geo point land in one `{ lat, lng }` input.
+                const point = (input[col.property] ?? {});
+                input[col.property] = { ...point, [col.part]: raw };
+            }
+            else {
+                input[col.property] = raw;
+            }
+        });
+        try {
+            valid.push(parseInput(create, input));
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                for (const [field, message] of Object.entries(error.issues)) {
+                    errors.push({ row: rowNumber, field, message });
+                }
+            }
+            else {
+                errors.push({
+                    row: rowNumber,
+                    field: 'row',
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    });
+    return {
+        headers: headerRow,
+        columns,
+        valid,
+        errors,
+        rowCount: dataRows.filter((cells) => !cells.every((c) => c.trim() === '')).length,
+    };
+}

package/dist/files.d.ts

@@ -0,0 +1,35 @@
+import { type PrototypeRuntime } from '@protoyard/core';
+import { type Blueprint } from './schema.ts';
+export declare const DEFAULT_FILE_QUOTA_BYTES: number;
+export interface FileUploadProgress {
+    loaded: number;
+    total: number;
+    percent: number;
+}
+export interface BlueprintFileMetadata {
+    id: string;
+    name: string;
+    type: string;
+    size: number;
+    ownerId: string;
+    entity: string;
+    recordId: string;
+    createdAt: string;
+}
+export interface BlueprintFile extends BlueprintFileMetadata {
+    blob: Blob;
+}
+export interface FileService {
+    upload(input: unknown, onProgress?: (progress: FileUploadProgress) => void): Promise<BlueprintFileMetadata>;
+    list(entityName: string, recordId: string, fieldName?: string): Promise<BlueprintFileMetadata[]>;
+    get(id: string): Promise<BlueprintFile | undefined>;
+    remove(id: string): Promise<boolean>;
+}
+export type FileServices = Record<string, FileService>;
+export declare class FileUploadError extends Error {
+    readonly code: 'not-found' | 'size-limit' | 'type-not-allowed' | 'quota-exceeded' | 'files-disabled' | 'data-unavailable';
+    constructor(code: FileUploadError['code'], message: string);
+}
+export declare function createFileServices(runtime: PrototypeRuntime, blueprint: Blueprint, options?: {
+    prototypeQuotaBytes?: number;
+}): FileServices;