@beechcms/core 0.8.0 → 0.9.0

package/dist/content.repository.d.ts

@@ -0,0 +1,247 @@
+import { Seed, SelectOptions } from './types.js';
+/**
+ * One row of the cross-seed pending-drafts overview. Aggregates the minimum a
+ * reviewer needs to triage a draft without opening it: which seed it belongs to,
+ * a human title, when it was last touched, and who touched it.
+ */
+export interface DraftSummary {
+    id: string;
+    seedSlug: string;
+    seedLabel: string;
+    title: string;
+    updatedAt: number;
+    lastModifiedBy: {
+        name: string | null;
+        email: string;
+    };
+}
+/**
+ * Base Repository Error
+ */
+export declare class RepositoryError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Thrown when an entry is not found by ID or Slug
+ */
+export declare class EntryNotFoundError extends RepositoryError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a slug already exists for a content type
+ */
+export declare class SlugConflictError extends RepositoryError {
+    constructor(message: string);
+}
+/**
+ * Thrown by publishDraft when a non-null relation value points to a missing
+ * target row. Mapped to 422 Unprocessable Entity by the API problem-mapper.
+ */
+export declare class RelationTargetNotFoundError extends RepositoryError {
+    readonly alias: string;
+    readonly targetSeed: string;
+    readonly value: string;
+    constructor(params: {
+        alias: string;
+        targetSeed: string;
+        value: string;
+    });
+}
+/**
+ * Thrown by lifecycle `before*` hooks to signal a business validation failure.
+ * Mapped to 422 Unprocessable Entity by the API problem-mapper.
+ */
+export declare class HookValidationError extends RepositoryError {
+    readonly fields?: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message: string, fields?: Array<{
+        field: string;
+        message: string;
+    }>);
+}
+export type BulkFieldUpdate = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'array_replace';
+    value: string[];
+} | {
+    kind: 'array_add';
+    value: string[];
+} | {
+    kind: 'array_remove';
+    value: string[];
+};
+/**
+ * Options passed to write operations. Currently carries the acting user
+ * (extracted from the JWT) so lifecycle hooks can attribute changes.
+ */
+export interface RepositoryOptions {
+    actor?: {
+        id: string;
+        role?: string;
+        email?: string;
+    };
+}
+/**
+ * Declarative multi-write operation translated into a single `db.batch` call.
+ * Used for coordinated writes across one or more seeds when D1's lack of
+ * interactive transactions makes a callback-based API impossible.
+ *
+ * NOTE: document-level lifecycle hooks do NOT run for operations inside a
+ * `runBatch` call — they would be non-atomic side-effects.
+ */
+export type BatchWrite = {
+    kind: 'create';
+    seed: Seed;
+    id: string;
+    slug: string;
+    status: string;
+    data: Record<string, any>;
+} | {
+    kind: 'update';
+    seed: Seed;
+    id: string;
+    data: Record<string, any>;
+    status?: string;
+} | {
+    kind: 'mutateField';
+    seed: Seed;
+    id: string;
+    fieldName: string;
+    operation: {
+        type: 'increment' | 'decrement';
+        value: number;
+    };
+    options?: {
+        min?: number;
+        max?: number;
+    };
+};
+/**
+ * Interface defining the standard operations for content persistence.
+ * This is platform-agnostic and should be implemented for specific databases (e.g., D1).
+ */
+export interface ContentRepository {
+    /**
+     * Retrieves a paginated and filtered list of entries.
+     */
+    findMany(seed: Seed, options: SelectOptions): Promise<{
+        items: Record<string, any>[];
+        total: number;
+    }>;
+    /**
+     * Finds a single entry by its unique ID.
+     * Throws EntryNotFoundError if not found.
+     */
+    findById(seed: Seed, id: string): Promise<Record<string, any>>;
+    /**
+     * Finds a single entry by its unique slug.
+     * Throws EntryNotFoundError if not found.
+     */
+    findBySlug(seed: Seed, slug: string): Promise<Record<string, any>>;
+    /**
+     * Computes facets (status counts and distinct tags) for a content type.
+     */
+    getFacets(seed: Seed): Promise<{
+        statuses: Record<string, number>;
+        tagsByColumn: Record<string, string[]>;
+    }>;
+    /**
+     * Creates a new content entry in the live table.
+     * Throws SlugConflictError if the slug is already taken.
+     */
+    create(seed: Seed, id: string, slug: string, status: string, data: Record<string, any>, options?: RepositoryOptions): Promise<void>;
+    /**
+     * Partially updates an existing entry in the live table.
+     * Throws EntryNotFoundError if the ID does not exist.
+     */
+    update(seed: Seed, id: string, data: Record<string, any>, status?: string, options?: RepositoryOptions): Promise<void>;
+    /**
+     * Deletes an entry from the live table.
+     * Returns the deleted row data (useful for media cleanup).
+     * Throws EntryNotFoundError if the ID does not exist.
+     */
+    delete(seed: Seed, id: string, options?: RepositoryOptions): Promise<{
+        row: Record<string, any>;
+    }>;
+    /**
+     * Atomically increments/decrements a numeric field with optional min/max guards.
+     * Bypasses document-level lifecycle hooks — it's a single UPDATE statement,
+     * used to prevent race conditions on counters (stock, balances).
+     * Throws RepositoryError if `fieldName` is not a numeric branch of `seed`, or
+     * if the guard conditions fail / the row does not exist.
+     */
+    mutateField(seed: Seed, id: string, fieldName: string, operation: {
+        type: 'increment' | 'decrement';
+        value: number;
+    }, options?: {
+        min?: number;
+        max?: number;
+    }): Promise<{
+        newValue: number;
+    }>;
+    /**
+     * Atomically applies an axis-value patch AND a kanban_positions upsert in one DB batch (KB-S04e).
+     * `patch` is null for same-column reorders (position only).
+     */
+    updateWithKanbanPosition(seed: Seed, id: string, patch: Record<string, unknown> | null, position: string, axisBranchId: string, ctx: {
+        actor: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Executes a list of write operations atomically via a single `db.batch`.
+     * Document-level lifecycle hooks do NOT run for operations inside this call.
+     */
+    runBatch(operations: BatchWrite[]): Promise<void>;
+    /**
+     * Saves or updates a pending draft in the mirror table.
+     */
+    saveDraft(seed: Seed, entryId: string, data: Record<string, any>): Promise<void>;
+    /**
+     * Retrieves the pending draft for a given entry.
+     * Returns null if no draft exists.
+     */
+    getDraft(seed: Seed, entryId: string): Promise<Record<string, any> | null>;
+    /**
+     * Atomic promotion of a draft to the live table.
+     * Must use a transaction (db.batch) to update live and delete draft.
+     */
+    publishDraft(seed: Seed, entryId: string): Promise<void>;
+    /**
+     * Discards the pending draft.
+     */
+    deleteDraft(seed: Seed, entryId: string): Promise<void>;
+    /**
+     * Checks if a slug is already taken by another entry.
+     */
+    existsSlug(seed: Seed, slug: string, excludeId?: string): Promise<boolean>;
+    /**
+     * Checks if an entry has a pending draft.
+     */
+    hasDraft(seed: Seed, entryId: string): Promise<boolean>;
+    /**
+     * Aggregates pending drafts across every draft-enabled seed in a single round-trip.
+     * Exists so the unified /drafts view never issues one query per seed.
+     * @param seeds The draft-enabled seeds to scan (caller passes seedRegistry.draftEnabled()).
+     * @returns Drafts newest-first; empty array when no seeds or no drafts.
+     */
+    findPendingDrafts(seeds: Seed[]): Promise<DraftSummary[]>;
+    /**
+     * Apply the same field update to many entries. Returns per-id outcome.
+     * Caller is responsible for validation; this method assumes the payload is
+     * already shape-checked against the seed.
+     */
+    bulkUpdate(seedSlug: string, ids: string[], fields: Record<string, BulkFieldUpdate>): Promise<{
+        updated: number;
+        failed: Array<{
+            id: string;
+            reason: string;
+        }>;
+    }>;
+}
+//# sourceMappingURL=content.repository.d.ts.map

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

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

package/dist/content.repository.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Base Repository Error
+ */
+export class RepositoryError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'RepositoryError';
+    }
+}
+/**
+ * Thrown when an entry is not found by ID or Slug
+ */
+export class EntryNotFoundError extends RepositoryError {
+    constructor(message) {
+        super(message);
+        this.name = 'EntryNotFoundError';
+    }
+}
+/**
+ * Thrown when a slug already exists for a content type
+ */
+export class SlugConflictError extends RepositoryError {
+    constructor(message) {
+        super(message);
+        this.name = 'SlugConflictError';
+    }
+}
+/**
+ * Thrown by publishDraft when a non-null relation value points to a missing
+ * target row. Mapped to 422 Unprocessable Entity by the API problem-mapper.
+ */
+export class RelationTargetNotFoundError extends RepositoryError {
+    alias;
+    targetSeed;
+    value;
+    constructor(params) {
+        super(`Relation target not found: field '${params.alias}' references '${params.targetSeed}' id='${params.value}' which does not exist`);
+        this.name = 'RelationTargetNotFoundError';
+        this.alias = params.alias;
+        this.targetSeed = params.targetSeed;
+        this.value = params.value;
+    }
+}
+/**
+ * Thrown by lifecycle `before*` hooks to signal a business validation failure.
+ * Mapped to 422 Unprocessable Entity by the API problem-mapper.
+ */
+export class HookValidationError extends RepositoryError {
+    fields;
+    constructor(message, fields) {
+        super(message);
+        this.name = 'HookValidationError';
+        this.fields = fields;
+    }
+}