@beechcms/core 0.4.0 → 0.4.2

package/dist/validation.js

@@ -227,6 +227,7 @@ function requiredAliases(seed, operation) {
 }
 function buildBranchSchema(branch, options) {
     const nullable = options.allowNull ? z.null() : null;
+    const preprocessEmpty = (schema) => z.preprocess((val) => (val === '' || val === null ? (options.allowNull ? null : undefined) : val), schema.optional());
     switch (branch.type) {
         case 'text': {
             const schema = stringSchema
@@ -265,56 +266,48 @@ function buildBranchSchema(branch, options) {
             return nullable ? z.union([schema, nullable]) : schema;
         }
         case 'number': {
-            const schema = finiteNumberSchema;
+            const schema = preprocessEmpty(finiteNumberSchema);
             return nullable ? z.union([schema, nullable]) : schema;
         }
         case 'boolean': {
-            const schema = booleanSchema;
+            const schema = preprocessEmpty(booleanSchema);
             return nullable ? z.union([schema, nullable]) : schema;
         }
         case 'date': {
-            const schema = stringSchema
+            const schema = preprocessEmpty(stringSchema
                 .transform((value) => sanitizePlainString(value))
-                .refine((value) => isIsoDateString(value), { message: 'Expected date(ISO)' });
+                .refine((value) => isIsoDateString(value), { message: 'Expected date(ISO)' }));
             return nullable ? z.union([schema, nullable]) : schema;
         }
         case 'json':
         case 'tags': {
-            const schema = jsonObjectOrArraySchema;
+            const schema = preprocessEmpty(jsonObjectOrArraySchema);
             return nullable ? z.union([schema, nullable]) : schema;
         }
         case 'file': {
             if (isAssetListBranch(branch)) {
-                const schema = z
-                    .any()
+                const schema = preprocessEmpty(z.any()
                     .transform((rawValue, ctx) => {
                     const normalized = normalizeAssetListValue(rawValue);
                     if (!normalized) {
-                        ctx.addIssue({
-                            code: 'custom',
-                            message: 'Expected url-string[]',
-                        });
+                        ctx.addIssue({ code: 'custom', message: 'Expected url-string[]' });
                         return z.NEVER;
                     }
                     return normalized;
                 })
-                    .pipe(z.array(z.url()));
+                    .pipe(z.array(z.string().url())));
                 return nullable ? z.union([schema, nullable]) : schema;
             }
-            const schema = z
-                .any()
+            const schema = preprocessEmpty(z.any()
                 .transform((rawValue, ctx) => {
                 const normalized = normalizeHttpUrl(rawValue);
                 if (!normalized) {
-                    ctx.addIssue({
-                        code: 'custom',
-                        message: 'Expected url-string',
-                    });
+                    ctx.addIssue({ code: 'custom', message: 'Expected url-string' });
                     return z.NEVER;
                 }
                 return normalized;
             })
-                .pipe(z.url());
+                .pipe(z.string().url()));
             return nullable ? z.union([schema, nullable]) : schema;
         }
         default:
@@ -371,95 +364,21 @@ function makeDetail(field, expected, received) {
 function isIsoDateString(value) {
     if (!/^\d{4}-\d{2}-\d{2}/.test(value))
         return false;
-    return !Number.isNaN(Date.parse(value));
-}
-function validateBranchValue(branch, alias, rawValue, options) {
-    if (rawValue === null) {
-        return options.allowNull
-            ? { ok: true, value: null }
-            : { ok: false, detail: makeDetail(alias, branch.type, rawValue) };
-    }
-    switch (branch.type) {
-        case 'text': {
-            if (!stringSchema.safeParse(rawValue).success) {
-                return { ok: false, detail: makeDetail(alias, 'string', rawValue) };
-            }
-            const sanitized = sanitizePlainString(rawValue);
-            if (sanitized.length > options.maxTextLength) {
-                return { ok: false, detail: makeDetail(alias, `string(max:${options.maxTextLength})`, rawValue) };
-            }
-            return { ok: true, value: sanitized };
-        }
-        case 'richtext': {
-            const sanitized = sanitizeRichtext(rawValue);
-            if (!sanitized.valid) {
-                return { ok: false, detail: makeDetail(alias, 'richtext-json|string', rawValue) };
-            }
-            if (sanitized.size > options.maxTextLength) {
-                return {
-                    ok: false,
-                    detail: makeDetail(alias, `richtext(max:${options.maxTextLength})`, rawValue),
-                };
-            }
-            return { ok: true, value: sanitized.value, dangerous: sanitized.dangerous };
-        }
-        case 'number': {
-            if (!finiteNumberSchema.safeParse(rawValue).success) {
-                return { ok: false, detail: makeDetail(alias, 'number', rawValue) };
-            }
-            return { ok: true, value: rawValue };
-        }
-        case 'boolean': {
-            if (!booleanSchema.safeParse(rawValue).success) {
-                return { ok: false, detail: makeDetail(alias, 'boolean', rawValue) };
-            }
-            return { ok: true, value: rawValue };
-        }
-        case 'date': {
-            if (!stringSchema.safeParse(rawValue).success) {
-                return { ok: false, detail: makeDetail(alias, 'date(ISO)', rawValue) };
-            }
-            const value = sanitizePlainString(rawValue);
-            if (!isIsoDateString(value)) {
-                return { ok: false, detail: makeDetail(alias, 'date(ISO)', rawValue) };
-            }
-            return { ok: true, value };
-        }
-        case 'json':
-        case 'tags': {
-            const isValidJsonLike = (typeof rawValue === 'object' && rawValue !== null) || Array.isArray(rawValue);
-            if (!isValidJsonLike || typeof rawValue === 'string') {
-                return { ok: false, detail: makeDetail(alias, 'object|array', rawValue) };
-            }
-            return { ok: true, value: rawValue };
-        }
-        case 'file': {
-            if (isAssetListBranch(branch)) {
-                const listValue = normalizeAssetListValue(rawValue);
-                if (!listValue) {
-                    return { ok: false, detail: makeDetail(alias, 'url-string[]', rawValue) };
-                }
-                return { ok: true, value: listValue };
-            }
-            const singleUrl = normalizeHttpUrl(rawValue);
-            if (!singleUrl) {
-                return { ok: false, detail: makeDetail(alias, 'url-string', rawValue) };
-            }
-            return { ok: true, value: singleUrl };
-        }
-        default:
-            throw new Error(`Unhandled branch type: ${branch.type}`);
-    }
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        return false;
+    const d = new Date(parsed);
+    return d.toISOString().startsWith(value.substring(0, 10));
 }
 /**
- * Foundation comune per validazione e sanitizzazione payload schema-driven.
- * Usata da Public API e riusabile nel Botanical Engine.
+ * Common foundation for schema-driven validation and sanitization of payloads.
+ * Used by the Public API and reusable in the Botanical Engine.
  *
- * Ordine di esecuzione obbligatorio al momento della scrittura:
+ * Mandatory execution order at the time of writing:
  *   validate raw → hash (privacy policy) → store
- * L'hashing avviene DOPO la validazione, non prima.
- * Questo garantisce che il valore validato sia il valore raw originale,
- * non il digest — evitando false failure su campi con formato (es. email).
+ * Hashing occurs AFTER validation, not before.
+ * This ensures that the validated value is the original raw value,
+ * not the digest — avoiding false failures on fields with formats (e.g., email).
  */
 export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
     const normalizedOptions = {
@@ -508,6 +427,9 @@ export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
                 }
                 continue;
             }
+            if (issue.message === 'Required' && normalizedOptions.enforceRequiredFields) {
+                continue; // Let enforceRequiredFields logic below handle it properly with detailed messages
+            }
             const field = String(issue.path[0] ?? 'payload');
             const receivedValue = filteredPayload[field];
             const expected = typeof issue.message === 'string' && issue.message.startsWith('Expected ')
@@ -535,7 +457,8 @@ export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
                 });
                 continue;
             }
-            if (isMissingRequiredValue(data[branch.alias])) {
+            const valueToCheck = parsed.success ? data[branch.alias] : filteredPayload[branch.alias];
+            if (isMissingRequiredValue(valueToCheck)) {
                 requiredFieldsMissing.push(branch.alias);
                 details.push({
                     field: branch.alias,
@@ -564,7 +487,7 @@ export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
     };
 }
 /**
- * Valida status content supportati dal CMS.
+ * Validates content status supported by the CMS.
  */
 export function isValidContentStatus(value) {
     return statusSchema.safeParse(value).success;

package/dist/widget/widget.repository.d.ts

@@ -0,0 +1,113 @@
+import type { Seed } from '../types.js';
+/**
+ * Discriminated union describing the aggregate to compute over a content table.
+ *
+ * The widget routes accept this shape from the dashboard. Implementations are
+ * responsible for translating each variant into a safe SQL expression and must
+ * never interpolate the column or value fields without prior validation.
+ */
+export type AggregateFormula = {
+    op: 'count';
+} | {
+    op: 'sum';
+    column: string;
+} | {
+    op: 'avg';
+    column: string;
+} | {
+    op: 'min';
+    column: string;
+} | {
+    op: 'max';
+    column: string;
+} | {
+    op: 'countWhere';
+    column: string;
+    value: unknown;
+} | {
+    op: 'percentageOf';
+    numeratorColumn: string;
+    denominatorColumn: string;
+};
+/**
+ * Time range applied as a WHERE filter for widget queries.
+ *
+ * "all" means no temporal restriction. The other values bracket the most recent
+ * 7 days, 1 month, and 1 year respectively, anchored on `created_at`.
+ */
+export type TimeWindow = 'week' | 'month' | 'year' | 'all';
+export interface LeaderboardEntry {
+    id: string;
+    label: string;
+    score: number | string;
+}
+export interface LeaderboardOptions {
+    scoreColumn: string;
+    limit: number;
+    orderDirection: 'ASC' | 'DESC';
+}
+export interface TimeseriesPoint {
+    label: string;
+    value: number;
+}
+export interface WidgetListFilter {
+    column: string;
+    op: string;
+    value: unknown;
+}
+export interface WidgetListOptions {
+    limit: number;
+    offset: number;
+    search?: string;
+    filters?: WidgetListFilter[];
+    orderByColumn?: string;
+    orderDirection?: 'ASC' | 'DESC';
+}
+export interface WidgetListResult {
+    entries: Array<Record<string, unknown>>;
+    totalCount: number;
+}
+export interface GrowthResult {
+    currentValue: number;
+    previousValue: number;
+}
+/**
+ * Read-only data access contract for widget routes.
+ *
+ * Implementations must validate every column alias derived from user input
+ * against the seed before composing SQL, and must bind every user-supplied
+ * value via parameterised statements. SQL keywords (ORDER direction, aggregate
+ * function names) must be selected via hardcoded branches, never interpolated.
+ */
+export interface IWidgetRepository {
+    /**
+     * Returns the formula result for the given time window. Always returns a
+     * number; implementations must return 0 when the query produces no rows.
+     */
+    aggregate(seed: Seed, formula: AggregateFormula, window: TimeWindow): Promise<number>;
+    /**
+     * Evaluates the formula twice — once for the current window period and once
+     * for the equivalent previous period — to support trend calculations.
+     * Implementations must return { currentValue: 0, previousValue: 0 } on
+     * empty results.
+     */
+    growth(seed: Seed, formula: AggregateFormula, window: TimeWindow): Promise<GrowthResult>;
+    /**
+     * Returns entries sorted by scoreColumn, excluding nulls. label resolves
+     * from seed.displayNameAlias; falls back to id when not set.
+     */
+    leaderboard(seed: Seed, options: LeaderboardOptions): Promise<LeaderboardEntry[]>;
+    /**
+     * Paginated read of content entries. Filters and search are applied
+     * server-side. The caller is responsible for deserialising branch values
+     * from the raw Record.
+     */
+    list(seed: Seed, options: WidgetListOptions): Promise<WidgetListResult>;
+    /**
+     * Groups entries by a date bucket derived from groupColumn and aggregates
+     * the formula. Days with no entries are omitted (no zero-fill). Points are
+     * ordered ascending by label.
+     */
+    timeseries(seed: Seed, formula: AggregateFormula, window: TimeWindow, groupColumn: string): Promise<TimeseriesPoint[]>;
+}
+//# sourceMappingURL=widget.repository.d.ts.map

package/dist/widget/widget.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.repository.d.ts","sourceRoot":"","sources":["../../src/widget/widget.repository.ts"],"names":[],"mappings":"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"}

package/dist/widget/widget.repository.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beechcms/core",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -18,18 +18,24 @@
     "build": "tsc",
     "dev": "tsc -w --preserveWatchOutput",
     "lint": "eslint .",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.2.4"
   },
   "dependencies": {
     "@tiptap/core": "^3.22.3",
     "@tiptap/extension-highlight": "^3.22.3",
     "@tiptap/extension-image": "^3.22.3",
     "@tiptap/extension-link": "^3.22.3",
+    "@tiptap/extension-mathematics": "^3.22.3",
     "@tiptap/extension-subscript": "^3.22.3",
     "@tiptap/extension-superscript": "^3.22.3",
     "@tiptap/extension-table": "^3.22.3",
     "@tiptap/extension-text-align": "^3.22.3",
-    "@tiptap/extension-mathematics": "^3.22.3",
     "@tiptap/html": "^3.22.3",
     "@tiptap/starter-kit": "^3.22.3",
     "katex": "^0.16.11",