@beechcms/core 0.4.0-preview.9 → 0.4.1

package/dist/engine.js

@@ -6,6 +6,7 @@ const BRANCH_TYPE_SQL = {
     json: { sqlType: 'TEXT' }, // JSON serializzato
     richtext: { sqlType: 'TEXT' },
     file: { sqlType: 'TEXT' }, // URL singolo o JSON array di URL
+    tags: { sqlType: 'TEXT' }, // JSON array di stringhe
 };
 const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at']);
 // ---- Private helpers ----
@@ -70,8 +71,8 @@ function normalizeAssetListValue(rawValue) {
 }
 // ---- DDL Generators ----
 /**
- * Genera `CREATE TABLE IF NOT EXISTS content_{slug}` con colonne di sistema
- * + una colonna per ogni Branch. Funzione pura: stesso Seed → stesso SQL.
+ * Generates `CREATE TABLE IF NOT EXISTS content_{slug}` with system columns
+ * + one column per Branch. Pure function: same Seed → same SQL.
  */
 export function generateCreateTable(seed) {
     const table = tableName(seed);
@@ -96,9 +97,9 @@ export function generateCreateTable(seed) {
     return lines.join('\n');
 }
 /**
- * Genera la tabella bozze `content_{slug}_drafts` per i Seed con `allowDrafts: true`.
- * Tutte le colonne branch sono nullable (le bozze sono parziali).
- * Ritorna null se il Seed non ha `allowDrafts: true`.
+ * Generates the drafts table `content_{slug}_drafts` for Seeds with `allowDrafts: true`.
+ * All branch columns are nullable (drafts are partial).
+ * Returns null if the Seed does not have `allowDrafts: true`.
  */
 export function generateDraftTable(seed) {
     if (!seed.allowDrafts)
@@ -113,7 +114,7 @@ export function generateDraftTable(seed) {
     for (const branch of seed.branches) {
         const { sqlType } = BRANCH_TYPE_SQL[branch.type];
         let col = `  ${branch.alias}  ${sqlType}`;
-        // boolean CHECK: in SQLite, NULL IN (0,1) → NULL, che passa il CHECK (solo FALSE lo fallisce)
+        // boolean CHECK: in SQLite, NULL IN (0,1) → NULL, which passes the CHECK (only FALSE fails it)
         if (branch.type === 'boolean')
             col += ` CHECK (${branch.alias} IN (0, 1))`;
         lines.push(col + ',');
@@ -123,16 +124,16 @@ export function generateDraftTable(seed) {
     return lines.join('\n');
 }
 /**
- * Genera `ALTER TABLE content_{slug} ADD COLUMN {alias} {type}`.
- * Nuove colonne sono sempre nullable (limite SQLite su ALTER TABLE).
+ * Generates `ALTER TABLE content_{slug} ADD COLUMN {alias} {type}`.
+ * New columns are always nullable (SQLite limit on ALTER TABLE).
  */
 export function generateAddColumn(seed, branch) {
     const { sqlType } = BRANCH_TYPE_SQL[branch.type];
     return `ALTER TABLE ${tableName(seed)} ADD COLUMN ${branch.alias} ${sqlType};`;
 }
 /**
- * Genera indici B-tree per status, created_at e ogni Branch filtrabile
- * con tipo indicizzabile (text, number, date, boolean).
+ * Generates B-tree indexes for status, created_at and every filterable Branch
+ * with an indexable type (text, number, date, boolean).
  */
 export function generateIndexes(seed) {
     const table = tableName(seed);
@@ -151,8 +152,8 @@ export function generateIndexes(seed) {
     return indexes;
 }
 /**
- * Genera la virtual table FTS5 per i Branch text/richtext indicizzabili.
- * Ritorna null se il Seed non ha branch con search abilitato.
+ * Generates the FTS5 virtual table for indexable text/richtext Branches.
+ * Returns null if the Seed has no branches with search enabled.
  */
 export function generateFtsTable(seed) {
     const rtBranches = indexableSearchBranches(seed);
@@ -169,9 +170,9 @@ export function generateFtsTable(seed) {
     ].join('\n');
 }
 /**
- * Genera i 3 trigger SQLite (insert/update/delete) che mantengono la FTS
- * sincronizzata automaticamente — elimina la necessità di syncFts manuale.
- * Ritorna array vuoto se il Seed non ha branch indicizzabili.
+ * Generates the 3 SQLite triggers (insert/update/delete) that keep the FTS
+ * automatically synchronized — eliminates the need for manual syncFts.
+ * Returns an empty array if the Seed has no indexable branches.
  */
 export function generateFtsTriggers(seed) {
     const rtBranches = indexableSearchBranches(seed);
@@ -207,9 +208,9 @@ export function generateFtsTriggers(seed) {
 }
 // ---- Query Builder ----
 /**
- * Costruisce una SELECT parametrizzata su `content_{slug}`.
- * Non usa mai json_extract — ogni colonna è una colonna reale.
- * Colonne sconosciute nei filtri/orderBy vengono ignorate (fail-closed).
+ * Builds a parameterized SELECT on `content_{slug}`.
+ * Never uses json_extract — every column is a real column.
+ * Unknown columns in filters/orderBy are ignored (fail-closed).
  */
 export function buildSelectQuery(seed, options = {}) {
     const table = tableName(seed);
@@ -277,6 +278,32 @@ export function buildSelectQuery(seed, options = {}) {
     }
     return { sql, bindings };
 }
+function normalizeFilterValue(type, value) {
+    if (value === null || value === undefined)
+        return null;
+    if (type === 'date') {
+        if (typeof value === 'number')
+            return value;
+        if (typeof value === 'string' && value.trim() !== '') {
+            const d = new Date(value);
+            return isNaN(d.getTime()) ? null : Math.floor(d.getTime() / 1000);
+        }
+        return null;
+    }
+    if (type === 'boolean') {
+        return value ? 1 : 0;
+    }
+    if (type === 'number') {
+        if (typeof value === 'number')
+            return value;
+        if (typeof value === 'string' && value.trim() !== '') {
+            const n = Number(value);
+            return isNaN(n) ? null : n;
+        }
+        return null;
+    }
+    return value;
+}
 function buildFilterCondition(col, type, cond, bindings) {
     const { op, value } = cond;
     if (op === 'is_empty') {
@@ -285,30 +312,65 @@ function buildFilterCondition(col, type, cond, bindings) {
     if (op === 'is_not_empty') {
         return type === 'text' ? `(${col} IS NOT NULL AND ${col} != '')` : `${col} IS NOT NULL`;
     }
-    if (value === null || value === undefined)
-        return null;
-    if (op === 'eq') {
-        bindings.push(type === 'boolean' ? (value ? 1 : 0) : value);
-        return `${col} = ?`;
+    if (op === 'in' || op === 'not_in') {
+        if (!Array.isArray(value) || value.length === 0)
+            return null;
+        const normalizedValues = value
+            .map((v) => normalizeFilterValue(type, v))
+            .filter((v) => v !== null);
+        if (normalizedValues.length === 0)
+            return null;
+        const placeholders = normalizedValues.map(() => '?').join(', ');
+        bindings.push(...normalizedValues);
+        return `${col} ${op === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`;
     }
-    if (op === 'contains') {
-        if (type === 'tags') {
-            bindings.push(String(value));
-            return `EXISTS (SELECT 1 FROM json_each(${col}) WHERE value = ?)`;
+    if (op === 'has_tag' || op === 'has_any_tag' || op === 'has_all_tags') {
+        if (type !== 'tags' && type !== 'json')
+            return null;
+        const tags = (op === 'has_tag' ? [value] : Array.isArray(value) ? value : [value])
+            .map(t => String(t));
+        if (tags.length === 0)
+            return null;
+        if (op === 'has_tag' || op === 'has_any_tag') {
+            const placeholders = tags.map(() => '?').join(', ');
+            bindings.push(...tags);
+            return `EXISTS (SELECT 1 FROM json_each(${col}) WHERE value IN (${placeholders}))`;
         }
-        bindings.push(`%${String(value)}%`);
-        return `${col} LIKE ?`;
+        // has_all_tags: each tag must exist
+        const clauses = tags.map(() => `EXISTS (SELECT 1 FROM json_each(${col}) WHERE value = ?)`);
+        bindings.push(...tags);
+        return `(${clauses.join(' AND ')})`;
+    }
+    const normalized = normalizeFilterValue(type, value);
+    if (normalized === null)
+        return null;
+    if (op === 'eq' || op === 'neq') {
+        const sqlOp = op === 'eq' ? '=' : '!=';
+        bindings.push(normalized);
+        return `${col} ${sqlOp} ?`;
+    }
+    if (op === 'contains' || op === 'not_contains' || op === 'starts_with' || op === 'ends_with') {
+        const sqlOp = op === 'not_contains' ? 'NOT LIKE' : 'LIKE';
+        let pattern = String(value);
+        if (op === 'contains' || op === 'not_contains')
+            pattern = `%${pattern}%`;
+        else if (op === 'starts_with')
+            pattern = `${pattern}%`;
+        else if (op === 'ends_with')
+            pattern = `%${pattern}`;
+        bindings.push(pattern);
+        return `${col} ${sqlOp} ?`;
     }
     const mathOps = { gt: '>', gte: '>=', lt: '<', lte: '<=' };
     if (mathOps[op]) {
-        bindings.push(value);
+        bindings.push(normalized);
         return `${col} ${mathOps[op]} ?`;
     }
     return null;
 }
 /**
- * Ritorna la lista di colonne attese per la tabella di un Seed.
- * Usato da `beech seed:load --diff` per confrontare schema attuale vs atteso.
+ * Returns the list of expected columns for a Seed's table.
+ * Used by `beech seed:load --diff` to compare current vs expected schema.
  */
 export function getExpectedColumns(seed) {
     return [
@@ -327,7 +389,7 @@ export function getExpectedColumns(seed) {
 }
 // ---- Serialization / Deserialization ----
 /**
- * Serializza un valore per la scrittura nel DB.
+ * Serializes a value for writing to the DB.
  * boolean → 0/1 | date → Unix timestamp | json/asset-list → JSON string
  */
 export function serializeForDb(branch, value) {
@@ -337,6 +399,7 @@ export function serializeForDb(branch, value) {
         case 'boolean':
             return value ? 1 : 0;
         case 'json':
+        case 'tags':
         case 'richtext':
             return typeof value === 'string' ? value : JSON.stringify(value);
         case 'date': {
@@ -364,7 +427,7 @@ export function serializeForDb(branch, value) {
     }
 }
 /**
- * Deserializza un valore letto dal DB per la risposta API.
+ * Deserializes a value read from the DB for the API response.
  * 0/1 → boolean | Unix timestamp → ISO 8601 | JSON string → object
  */
 export function deserializeFromDb(branch, value) {
@@ -374,6 +437,7 @@ export function deserializeFromDb(branch, value) {
         case 'boolean':
             return value === 1 || value === true;
         case 'json':
+        case 'tags':
         case 'richtext': {
             if (typeof value === 'string') {
                 try {

package/dist/id-generator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Identifier abstraction. Hides direct calls to {@link crypto.randomUUID}
+ * so callers can swap in deterministic generators during tests for stable
+ * snapshot assertions and predictable insert ordering.
+ */
+export interface IIdGenerator {
+    /**
+     * Generates a new universally unique identifier.
+     * Production implementation delegates to crypto.randomUUID().
+     * Test implementations return deterministic values for snapshot assertions.
+     */
+    uuid(): string;
+}
+/**
+ * Production singleton. Delegates to the host runtime CSPRNG-backed UUID
+ * generator. Stateless and therefore safe to share across requests.
+ */
+export declare const SystemIdGenerator: IIdGenerator;
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../src/id-generator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,IAAI,IAAI,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAE/B,CAAA"}

package/dist/id-generator.js

@@ -0,0 +1,7 @@
+/**
+ * Production singleton. Delegates to the host runtime CSPRNG-backed UUID
+ * generator. Stateless and therefore safe to share across requests.
+ */
+export const SystemIdGenerator = {
+    uuid: () => crypto.randomUUID(),
+};

package/dist/idempotency.repository.d.ts

@@ -0,0 +1,13 @@
+export interface IdempotencyRecord {
+    key: string;
+    fingerprint: string;
+    responseStatus: number;
+    responseBody: string;
+    expiresAt: number;
+}
+export interface IdempotencyRepository {
+    lookup(key: string): Promise<IdempotencyRecord | null>;
+    store(record: IdempotencyRecord): Promise<void>;
+    cleanup(now: number): Promise<void>;
+}
+//# sourceMappingURL=idempotency.repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.repository.d.ts","sourceRoot":"","sources":["../src/idempotency.repository.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;IACtD,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC"}

package/dist/idempotency.repository.js

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

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * @beechcms/core - Botanical Engine
  *
- * Pacchetto condiviso del monorepo Beech CMS.
- * In v0.4.0 il Botanical Engine è un compilatore di schema SQL: legge i Seed
- * TypeScript e genera DDL deterministico + query parametrizzate.
+ * Shared package of the Beech CMS monorepo.
+ * In v0.4.0 the Botanical Engine is a SQL schema compiler: it reads TypeScript
+ * Seeds and generates deterministic DDL + parameterized queries.
  *
  * @module @beechcms/core
  */
@@ -15,5 +15,26 @@ export * from './validation.js';
 export * from './richtext.js';
 export * from './richtext-render.js';
 export * from './slug-utils.js';
+export * from './content.repository.js';
+export * from './idempotency.repository.js';
+export * from './media.repository.js';
+export * from './storage.js';
 export * from './policies.js';
+export * from './auth/hash-provider.js';
+export * from './auth/token-service.js';
+export * from './auth/user.repository.js';
+export * from './auth/session.repository.js';
+export * from './auth/password-reset-token.repository.js';
+export * from './rate-limit/rate-limiter.js';
+export * from './observability/activity-logger.js';
+export * from './observability/activity-log.repository.js';
+export * from './observability/analytics.repository.js';
+export * from './notifications/notification.repository.js';
+export * from './notifications/notification-service.js';
+export * from './widget/widget.repository.js';
+export * from './search/search.repository.js';
+export * from './content-scan.repository.js';
+export * from './clock.js';
+export * from './id-generator.js';
+export * from './seed-registry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,yBAAyB,CAAA;AACvC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2CAA2C,CAAA;AACzD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,oCAAoC,CAAA;AAClD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,yCAAyC,CAAA;AACvD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,yCAAyC,CAAA;AACvD,cAAc,+BAA+B,CAAA;AAC7C,cAAc,+BAA+B,CAAA;AAC7C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/dist/index.js

@@ -1,9 +1,9 @@
 /**
  * @beechcms/core - Botanical Engine
  *
- * Pacchetto condiviso del monorepo Beech CMS.
- * In v0.4.0 il Botanical Engine è un compilatore di schema SQL: legge i Seed
- * TypeScript e genera DDL deterministico + query parametrizzate.
+ * Shared package of the Beech CMS monorepo.
+ * In v0.4.0 the Botanical Engine is a SQL schema compiler: it reads TypeScript
+ * Seeds and generates deterministic DDL + parameterized queries.
  *
  * @module @beechcms/core
  */
@@ -15,4 +15,25 @@ export * from './validation.js';
 export * from './richtext.js';
 export * from './richtext-render.js';
 export * from './slug-utils.js';
+export * from './content.repository.js';
+export * from './idempotency.repository.js';
+export * from './media.repository.js';
+export * from './storage.js';
 export * from './policies.js';
+export * from './auth/hash-provider.js';
+export * from './auth/token-service.js';
+export * from './auth/user.repository.js';
+export * from './auth/session.repository.js';
+export * from './auth/password-reset-token.repository.js';
+export * from './rate-limit/rate-limiter.js';
+export * from './observability/activity-logger.js';
+export * from './observability/activity-log.repository.js';
+export * from './observability/analytics.repository.js';
+export * from './notifications/notification.repository.js';
+export * from './notifications/notification-service.js';
+export * from './widget/widget.repository.js';
+export * from './search/search.repository.js';
+export * from './content-scan.repository.js';
+export * from './clock.js';
+export * from './id-generator.js';
+export * from './seed-registry.js';

package/dist/media.repository.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MediaRepository - Interface for tracking media assets in the database.
+ */
+export interface MediaObject {
+    key: string;
+    filename: string;
+    mime_type: string;
+    size_bytes: number;
+    uploaded_by: string;
+    created_at: number;
+}
+export interface MediaRepository {
+    /**
+     * Tracks a new file upload in the database.
+     */
+    trackUpload(media: Omit<MediaObject, 'created_at'>): Promise<void>;
+    /**
+     * Retrieves tracking info for a file by its key.
+     */
+    getByKey(key: string): Promise<MediaObject | null>;
+    /**
+     * Removes tracking info for a file.
+     */
+    untrack(key: string): Promise<void>;
+    /**
+     * Lists all tracked media with pagination.
+     */
+    list(options: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        items: MediaObject[];
+        total: number;
+    }>;
+    /**
+     * Gets the total number of tracked media objects.
+     */
+    count(): Promise<number>;
+}
+/**
+ * SystemStatsRepository - Interface for managing global system metrics.
+ */
+export interface SystemStatsRepository {
+    /**
+     * Increments the total storage counter.
+     */
+    incrementStorage(bytes: number): Promise<void>;
+    /**
+     * Decrements the total storage counter.
+     */
+    decrementStorage(bytes: number): Promise<void>;
+    /**
+     * Sets a specific value for a storage stat (e.g. after a full sync).
+     */
+    setStorage(bytes: number): Promise<void>;
+    /**
+     * Gets the current total storage usage in bytes.
+     */
+    getStorageUsage(): Promise<number>;
+}
+//# sourceMappingURL=media.repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"media.repository.d.ts","sourceRoot":"","sources":["../src/media.repository.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEnD;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnG;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC"}

package/dist/media.repository.js

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

package/dist/notifications/notification-service.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Notification service contract.
+ *
+ * High-level port that callers use to emit a notification without knowing
+ * about the underlying repository, the database, or background scheduling.
+ * Mirrors the email module pattern: handlers depend on the service, the
+ * service depends on the repository, the repository depends on D1.
+ *
+ * @module @beechcms/core/notifications/notification-service
+ */
+import type { NotificationType } from './notification.repository.js';
+export interface CreateNotificationInput {
+    title: string;
+    message: string;
+    type?: NotificationType;
+}
+export interface INotificationService {
+    /**
+     * Emit a notification.
+     *
+     * Implementations decide whether to fire-and-forget (production: schedules
+     * the underlying repository write through `executionCtx.waitUntil`) or to
+     * wait inline (tests). Like the activity logger, this method MUST NOT
+     * throw to the caller: a failed notification must never break the public
+     * request that triggered it.
+     */
+    notify(input: CreateNotificationInput): Promise<void> | void;
+}
+//# sourceMappingURL=notification-service.d.ts.map

package/dist/notifications/notification-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-service.d.ts","sourceRoot":"","sources":["../../src/notifications/notification-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAEpE,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,gBAAgB,CAAA;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC7D"}

package/dist/notifications/notification-service.js

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

package/dist/notifications/notification.repository.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Notification repository contract.
+ *
+ * Persists in-app notifications (admin inbox) and exposes the aggregate stats
+ * the GET /notifications handler needs to build a strong ETag without reading
+ * every row.
+ *
+ * @module @beechcms/core/notifications/notification.repository
+ */
+export type NotificationType = 'info' | 'success' | 'warning' | 'error';
+export interface NotificationRecord {
+    id: string;
+    title: string;
+    message: string;
+    type: NotificationType;
+    isRead: boolean;
+    createdAt: number;
+}
+export interface NotificationStats {
+    totalCount: number;
+    latestCreatedAt: number;
+    readCount: number;
+}
+export interface INotificationRepository {
+    /**
+     * Return the most recent notifications, newest first.
+     *
+     * The `limit` parameter is required to prevent unbounded reads — the inbox
+     * could grow large over time and clients only ever render a window.
+     */
+    list(limit: number): Promise<NotificationRecord[]>;
+    /**
+     * Return aggregate counters used to build the GET /notifications ETag.
+     *
+     * Computing `totalCount`, `latestCreatedAt` and `readCount` on the database
+     * side lets the handler skip serialising the full list when nothing has
+     * changed since the client's last poll, saving bandwidth on the dashboard.
+     */
+    stats(): Promise<NotificationStats>;
+    /**
+     * Insert a new notification and return its generated id so callers (e.g.
+     * the public form submission flow) can correlate the notification with the
+     * triggering request.
+     */
+    create(record: Omit<NotificationRecord, 'id' | 'createdAt' | 'isRead'>): Promise<string>;
+    markRead(notificationId: string): Promise<void>;
+    markUnread(notificationId: string): Promise<void>;
+    markAllRead(): Promise<void>;
+    delete(notificationId: string): Promise<void>;
+}
+//# sourceMappingURL=notification.repository.d.ts.map

package/dist/notifications/notification.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.repository.d.ts","sourceRoot":"","sources":["../../src/notifications/notification.repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,gBAAgB,CAAA;IACtB,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAElD;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAEnC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,GAAG,WAAW,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAExF,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C"}

package/dist/notifications/notification.repository.js

@@ -0,0 +1,10 @@
+/**
+ * Notification repository contract.
+ *
+ * Persists in-app notifications (admin inbox) and exposes the aggregate stats
+ * the GET /notifications handler needs to build a strong ETag without reading
+ * every row.
+ *
+ * @module @beechcms/core/notifications/notification.repository
+ */
+export {};

package/dist/observability/activity-log.repository.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Activity Log read-side repository contract.
+ *
+ * Used by handlers that surface the audit trail back to the user (settings
+ * activity tab, recent activity feed on the dashboard). Kept separate from
+ * {@link IActivityLogger} because writers and readers have different
+ * lifecycles: writes are fire-and-forget background tasks; reads are blocking
+ * request paths that need filters and pagination.
+ *
+ * @module @beechcms/core/observability/activity-log.repository
+ */
+import type { ActivityAction, EntityType } from './activity-logger.js';
+export interface ActivityLogRecord {
+    id: string;
+    userId: string;
+    userEmail: string;
+    userName: string | null;
+    action: ActivityAction;
+    entityType: EntityType;
+    entityId: string;
+    entitySlug: string | null;
+    details: Record<string, unknown> | null;
+    createdAt: number;
+}
+export interface ActivityLogListOptions {
+    /** Restrict the result to a specific user. Used by the per-user activity tab. */
+    userId?: string;
+    /** Restrict the result to a specific content seed. Used by per-seed feeds. */
+    entitySlug?: string;
+    /** Hard upper bound on the number of rows returned. */
+    limit: number;
+}
+export interface CountSinceOptions {
+    action: ActivityAction;
+    entityType: EntityType;
+    /** Lower bound (inclusive) for `createdAt` in seconds since epoch. */
+    sinceTimestamp: number;
+}
+export interface IActivityLogRepository {
+    /**
+     * Return the most recent activity entries matching the given filters.
+     *
+     * The list is always ordered by `createdAt` DESC so callers get newest-first
+     * data without paying extra sort costs in TypeScript. Used by the settings
+     * activity tab (per-user) and by the stats recent-activity feed (global).
+     */
+    list(options: ActivityLogListOptions): Promise<ActivityLogRecord[]>;
+    /**
+     * Count entries with the given `action` and `entityType` whose `createdAt`
+     * is greater-than-or-equal to `sinceTimestamp`.
+     *
+     * Used by the dashboard `/stats/total` widget to surface today/week/month
+     * create-event counts without hardcoding SQL in the handler. Each period
+     * is one call so the repository contract stays narrow and deterministic.
+     */
+    countSince(options: CountSinceOptions): Promise<number>;
+}
+//# sourceMappingURL=activity-log.repository.d.ts.map

package/dist/observability/activity-log.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-log.repository.d.ts","sourceRoot":"","sources":["../../src/observability/activity-log.repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,cAAc,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACvC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;IACtB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAA;IAEnE;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACxD"}

package/dist/observability/activity-log.repository.js

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