@beechcms/core 0.8.0 → 0.8.1

package/dist/dashboard-layout.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/dashboard-permissions.d.ts

@@ -0,0 +1,3 @@
+export declare const ROLES_ALLOWED_TO_EDIT_DASHBOARD: ReadonlyArray<string>;
+export declare function canEditDashboard(role: string | undefined | null): boolean;
+//# sourceMappingURL=dashboard-permissions.d.ts.map

package/dist/dashboard-permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-permissions.d.ts","sourceRoot":"","sources":["../src/dashboard-permissions.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,+BAA+B,EAAE,aAAa,CAAC,MAAM,CAAa,CAAA;AAE/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAGzE"}

package/dist/dashboard-permissions.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+// NOTE: change this list to extend write-access to other roles
+// (e.g. add 'editor', or introduce a fine-grained 'dashboard:edit' permission).
+// Single source of truth — used by both API guards and dashboard buttons.
+export const ROLES_ALLOWED_TO_EDIT_DASHBOARD = ['admin'];
+export function canEditDashboard(role) {
+    if (!role)
+        return false;
+    return ROLES_ALLOWED_TO_EDIT_DASHBOARD.includes(role);
+}

package/dist/dashboard-scopes.d.ts

@@ -0,0 +1,12 @@
+/** Roles that may have their own dashboard layout. Single source of truth —
+ *  extend this list if a new role is introduced. */
+export declare const KNOWN_DASHBOARD_ROLES: ReadonlyArray<string>;
+export declare const DEFAULT_DASHBOARD_SCOPE = "default";
+/** Builds the per-role scope string, e.g. `roleScope('editor') === 'role:editor'`. */
+export declare function roleScope(role: string): string;
+/** Whether `scope` is one of the closed set: `'default' | 'role:<known role>'`. */
+export declare function isValidDashboardScope(scope: string): boolean;
+/** Read-resolution order for a caller's role: `['role:<role>', 'default']`,
+ *  or just `['default']` for unknown/missing roles. */
+export declare function resolveDashboardScopeChain(role: string | undefined | null): string[];
+//# sourceMappingURL=dashboard-scopes.d.ts.map

package/dist/dashboard-scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-scopes.d.ts","sourceRoot":"","sources":["../src/dashboard-scopes.ts"],"names":[],"mappings":"AAOA;oDACoD;AACpD,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAuB,CAAA;AAE/E,eAAO,MAAM,uBAAuB,YAAY,CAAA;AAEhD,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED;uDACuD;AACvD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,CAKpF"}

package/dist/dashboard-scopes.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+// ---------------------------------------------------------------------------
+// Dashboard layout scopes (Sprint 06: role-based dashboards)
+// ---------------------------------------------------------------------------
+/** Roles that may have their own dashboard layout. Single source of truth —
+ *  extend this list if a new role is introduced. */
+export const KNOWN_DASHBOARD_ROLES = ['admin', 'editor'];
+export const DEFAULT_DASHBOARD_SCOPE = 'default';
+/** Builds the per-role scope string, e.g. `roleScope('editor') === 'role:editor'`. */
+export function roleScope(role) {
+    return `role:${role}`;
+}
+/** Whether `scope` is one of the closed set: `'default' | 'role:<known role>'`. */
+export function isValidDashboardScope(scope) {
+    if (scope === DEFAULT_DASHBOARD_SCOPE)
+        return true;
+    const match = /^role:(.+)$/.exec(scope);
+    if (!match)
+        return false;
+    return KNOWN_DASHBOARD_ROLES.includes(match[1]);
+}
+/** Read-resolution order for a caller's role: `['role:<role>', 'default']`,
+ *  or just `['default']` for unknown/missing roles. */
+export function resolveDashboardScopeChain(role) {
+    if (role && KNOWN_DASHBOARD_ROLES.includes(role)) {
+        return [roleScope(role), DEFAULT_DASHBOARD_SCOPE];
+    }
+    return [DEFAULT_DASHBOARD_SCOPE];
+}

package/dist/define-seed.d.ts

@@ -0,0 +1,3 @@
+import type { Seed } from './types.js';
+export declare function defineSeed(seed: Seed): Seed;
+//# sourceMappingURL=define-seed.d.ts.map

package/dist/define-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-seed.d.ts","sourceRoot":"","sources":["../src/define-seed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE3C"}

package/dist/define-seed.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export function defineSeed(seed) {
+    return seed;
+}

package/dist/demo-data.repository.d.ts

@@ -0,0 +1,5 @@
+export interface IDemoDataRepository {
+    /** Executes the compiled demo dataset SQL against the database. */
+    loadDemoData(): Promise<void>;
+}
+//# sourceMappingURL=demo-data.repository.d.ts.map

package/dist/demo-data.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-data.repository.d.ts","sourceRoot":"","sources":["../src/demo-data.repository.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9B"}

package/dist/demo-data.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/email.provider.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The resolved email message that the provider receives and sends.
+ * Constructed by the service by combining call parameters with template builder output.
+ */
+export interface OutboundEmail {
+    /** Sender address in RFC 5321 format (e.g., "Beech CMS <noreply@beechcms.dev>"). */
+    from: string;
+    /** List of recipient addresses. Must contain at least one element. */
+    to: string[];
+    subject: string;
+    /** Complete HTML body. Must be a valid HTML document (see templates/shell.ts). */
+    html: string;
+}
+/**
+ * Formal contract for email sending providers.
+ *
+ * Every implementation (Resend, SMTP, …) must comply with this interface.
+ * It is the only point of coupling between the email module and any external service.
+ *
+ * To add a new provider: create a class in apps/api/src/shared/email/providers/
+ * that implements this interface, then wire it in email.service.ts.
+ */
+export interface EmailProvider {
+    /**
+     * Sends a single transactional email.
+     *
+     * @throws {Error} If the provider rejects the request. The caller is responsible
+     *                 for catching and handling this error appropriately.
+     */
+    send(email: OutboundEmail): Promise<void>;
+}
+//# sourceMappingURL=email.provider.d.ts.map

package/dist/email.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.provider.d.ts","sourceRoot":"","sources":["../src/email.provider.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,EAAE,EAAE,MAAM,EAAE,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C"}

package/dist/email.provider.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+export {};

package/dist/engine/ddl/ddl.d.ts

@@ -0,0 +1,216 @@
+import type { Seed, Branch } from '../types.js';
+/**
+ * Helper function to determine if a branch requires a blind index column.
+ * Returns true if storage classification is 'encrypt' and filtering is not explicitly disabled.
+ */
+export declare function hasBlindIndex(branch: Branch): boolean;
+/**
+ * System-defined columns that exist on all content tables.
+ */
+export declare const SYSTEM_COLUMNS: Set<string>;
+/**
+ * Returns the SQL table name for a given Seed.
+ *
+ * @param seed The seed definition.
+ * @returns The table name.
+ */
+export declare function tableName(seed: Seed): string;
+/**
+ * Returns the FTS (Full-Text Search) virtual table name for a given Seed.
+ *
+ * @param seed The seed definition.
+ * @returns The FTS table name.
+ */
+export declare function ftsTableName(seed: Seed): string;
+/**
+ * Returns the vector table name for a given Seed.
+ *
+ * @param seed The seed definition.
+ * @returns The vector table name.
+ */
+export declare function vectorTableName(seed: Seed): string;
+/**
+ * Determines whether a column is valid for a given Seed (either system column or branch alias).
+ *
+ * @param seed The seed definition.
+ * @param col The column name to check.
+ * @returns True if the column is valid, false otherwise.
+ */
+export declare function isValidColumn(seed: Seed, col: string): boolean;
+/**
+ * Filters the branches of a Seed to return only the ones that are indexable for full-text search.
+ *
+ * @param seed The seed definition.
+ * @returns An array of indexable branches.
+ */
+export declare function indexableSearchBranches(seed: Seed): Branch[];
+/**
+ * Generates the SQL `CREATE TABLE IF NOT EXISTS content_{slug}` statement
+ * with system columns and one column per branch.
+ *
+ * @param seed The seed definition.
+ * @returns The CREATE TABLE SQL statement.
+ */
+export declare function generateCreateTable(seed: Seed): string;
+/**
+ * Generates the SQL `CREATE TABLE IF NOT EXISTS content_{slug}_drafts` statement
+ * for seeds that allow drafts.
+ *
+ * @param seed The seed definition.
+ * @returns The draft table CREATE TABLE SQL statement, or null if drafts are disabled.
+ */
+export declare function generateDraftTable(seed: Seed): string | null;
+/**
+ * Generates the SQL `ALTER TABLE content_{slug} ADD COLUMN {alias} {type}` statement.
+ *
+ * @param seed The seed definition.
+ * @param branch The branch definition for the new column.
+ * @returns The ALTER TABLE SQL statement.
+ */
+export declare function generateAddColumn(seed: Seed, branch: Branch): string;
+/**
+ * Generates the `ALTER TABLE content_{slug}_drafts ADD COLUMN live_snapshot_at INTEGER` statement
+ * for a draft table provisioned before the column existed.
+ *
+ * System column, not a branch — `generateAddColumn` iterates `seed.branches` and can never emit it.
+ * NOT idempotent: `ADD COLUMN` fails when the column is already present and `ISchemaMutator.execDdl`
+ * aborts the whole batch on the first failing statement, so the caller MUST check the physical
+ * columns first (see `planExtendSeed`).
+ *
+ * @param seed The seed definition. Caller must have verified `seed.allowDrafts`.
+ * @returns The ALTER TABLE statement.
+ */
+export declare function generateAddDraftSnapshotColumn(seed: Seed): string;
+/**
+ * Generates SQL index statements for system fields (status, created_at)
+ * and indexable branch columns.
+ *
+ * @param seed The seed definition.
+ * @returns An array of CREATE INDEX SQL statements.
+ */
+export declare function generateIndexes(seed: Seed): string[];
+/**
+ * Generates the FTS5 virtual table definition for indexable text/richtext branches.
+ *
+ * @param seed The seed definition.
+ * @returns The CREATE VIRTUAL TABLE SQL statement, or null if no branches are indexable.
+ */
+export declare function generateFtsTable(seed: Seed): string | null;
+/**
+ * Generates FTS5 triggers (insert, update, delete) to keep the FTS virtual table synchronized.
+ *
+ * @param seed The seed definition.
+ * @returns An array of CREATE TRIGGER SQL statements.
+ */
+export declare function generateFtsTriggers(seed: Seed): string[];
+/**
+ * Generates the SQL `CREATE TABLE IF NOT EXISTS vector_{slug}` statement
+ * for indexable text/richtext branches.
+ *
+ * @param seed The seed definition.
+ * @returns The CREATE TABLE SQL statement, or null if no branches are indexable.
+ */
+export declare function generateVectorTable(seed: Seed): string | null;
+/**
+ * Expected database schema column interface.
+ */
+export interface SchemaColumn {
+    /** Column name. */
+    name: string;
+    /** SQLite storage type. */
+    sqlType: 'TEXT' | 'REAL' | 'INTEGER';
+    /** Whether the column is NOT NULL. */
+    notNull: boolean;
+    /** Whether the column is the PRIMARY KEY. */
+    isPk: boolean;
+}
+/**
+ * Returns the list of expected columns for a Seed's table.
+ * Used to compare current vs expected schema (diffing).
+ *
+ * @param seed The seed definition.
+ * @returns The array of expected schema columns.
+ */
+export declare function getExpectedColumns(seed: Seed): SchemaColumn[];
+/**
+ * Returns the junction table name for a many-to-many relation branch.
+ * Format: `rel_<seedSlug>_<branchAlias>`.
+ *
+ * @param seedSlug The slug of the parent Seed.
+ * @param branchAlias The alias of the relation branch.
+ * @returns The junction table name.
+ */
+export declare function junctionTableName(seedSlug: string, branchAlias: string): string;
+/**
+ * Generates `CREATE TABLE IF NOT EXISTS rel_<seed>_<alias>` statement for a multi-relation branch.
+ *
+ * @param seed The parent seed definition.
+ * @param branch The multi-relation branch definition.
+ * @throws {Error} If called on a non-multi-relation branch or if `targetSeed` is missing.
+ * @returns The CREATE TABLE SQL statement.
+ */
+export declare function generateJunctionTable(seed: Seed, branch: Branch): string;
+/**
+ * Generates the two B-tree indexes for a junction table:
+ * one on `parent_id` (listing entries by parent) and one on `target_id` (handling cascade checks from target side).
+ *
+ * @param seed The parent seed definition.
+ * @param branch The multi-relation branch definition.
+ * @returns An array of CREATE INDEX SQL statements.
+ */
+export declare function generateJunctionIndexes(seed: Seed, branch: Branch): string[];
+/**
+ * Generates the drafts junction table `rel_<seed>_<alias>_drafts` for a many-to-many relation branch.
+ *
+ * @param seed The parent seed definition.
+ * @param branch The multi-relation branch definition.
+ * @returns The CREATE TABLE SQL statement, or null if drafts are disabled.
+ */
+export declare function generateJunctionDraftTable(seed: Seed, branch: Branch): string | null;
+/**
+ * Returns every `DROP TABLE IF EXISTS` needed to fully remove a content type:
+ * the main table, the drafts table (if drafts enabled), full-text search table/triggers, and junction tables.
+ *
+ * @param seed The seed definition.
+ * @returns An array of DROP TABLE / DROP TRIGGER SQL statements.
+ */
+export declare function generateDropTable(seed: Seed): string[];
+/**
+ * Returns the `DROP COLUMN` SQL statements for removing a single field.
+ * Drops the junction table for multi-relations, or alters the tables to drop the column.
+ *
+ * @param seed The seed definition.
+ * @param alias The alias of the branch to drop.
+ * @returns An array of SQL statements.
+ */
+export declare function generateDropColumn(seed: Seed, alias: string): string[];
+/**
+ * Returns the `RENAME COLUMN` SQL statements for renaming a field's alias.
+ * For a multi-relation branch, renames the junction table (+ drafts junction table) instead.
+ *
+ * @param seed The seed definition.
+ * @param from The old alias.
+ * @param to The new alias.
+ * @returns An array of SQL statements.
+ */
+export declare function generateRenameColumn(seed: Seed, from: string, to: string): string[];
+/**
+ * Returns the statements that change a column's SQL type in place using CAST, bypassing SQLite rebuild limitations.
+ *
+ * @param seed The seed definition.
+ * @param branch The target branch definition (carrying the new type).
+ * @throws {Error} If called on a multi-relation branch.
+ * @returns An array of SQL statements.
+ */
+export declare function generateRetypeColumn(seed: Seed, branch: Branch): string[];
+/**
+ * Additive statements that turn soft delete on for a table that already exists.
+ *
+ * The partial unique index is emitted for correctness on tables that were CREATED with
+ * `softDelete: true`. On a pre-existing table the inline `slug … UNIQUE` survives as a
+ * sqlite_autoindex that SQLite cannot drop via ALTER; there the partial index is redundant
+ * and a trashed slug stays reserved until the table is rebuilt (see ROADMAP deferral).
+ * Returns [] when the seed does not opt in.
+ */
+export declare function generateEnableSoftDelete(seed: Seed): string[];
+//# sourceMappingURL=ddl.d.ts.map

package/dist/engine/ddl/ddl.d.ts.map

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