@beechcms/core 0.9.6 → 0.9.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flavio De Musso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/auth/login-request.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** Same bounds the setup and reset-password flows enforce, so a password that can be created can log in. */
+export declare const LOGIN_PASSWORD_MIN_LENGTH = 8;
+export declare const LOGIN_PASSWORD_MAX_LENGTH = 128;
+/** bcrypt silently truncates at 72 bytes; refusing longer input stops two passwords sharing a hash. */
+export declare const LOGIN_PASSWORD_MAX_BYTES = 72;
+/**
+ * Body of `POST /auth/login`. The single source of both the runtime check and the type the typed
+ * client sends: the output email is already trimmed and lowercased, the form it is stored in.
+ */
+export declare const loginRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+export type LoginRequest = z.input<typeof loginRequestSchema>;
+//# sourceMappingURL=login-request.d.ts.map

package/dist/auth/login-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-request.d.ts","sourceRoot":"","sources":["../../src/auth/login-request.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,4GAA4G;AAC5G,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAC1C,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;iBAO7B,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA"}

package/dist/auth/login-request.js

@@ -0,0 +1,22 @@
+// 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.
+import { z } from 'zod';
+import { isValidAccountEmail } from './account-email.js';
+/** Same bounds the setup and reset-password flows enforce, so a password that can be created can log in. */
+export const LOGIN_PASSWORD_MIN_LENGTH = 8;
+export const LOGIN_PASSWORD_MAX_LENGTH = 128;
+/** bcrypt silently truncates at 72 bytes; refusing longer input stops two passwords sharing a hash. */
+export const LOGIN_PASSWORD_MAX_BYTES = 72;
+/**
+ * Body of `POST /auth/login`. The single source of both the runtime check and the type the typed
+ * client sends: the output email is already trimmed and lowercased, the form it is stored in.
+ */
+export const loginRequestSchema = z.object({
+    email: z.string().trim().toLowerCase().refine(isValidAccountEmail),
+    password: z
+        .string()
+        .min(LOGIN_PASSWORD_MIN_LENGTH)
+        .max(LOGIN_PASSWORD_MAX_LENGTH)
+        .refine((password) => new TextEncoder().encode(password).length <= LOGIN_PASSWORD_MAX_BYTES),
+});

package/dist/automations-grammar-words.d.ts

@@ -0,0 +1,2 @@
+export declare const AUTOMATION_RESERVED_WORDS: Set<string>;
+//# sourceMappingURL=automations-grammar-words.d.ts.map

package/dist/automations-grammar-words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations-grammar-words.d.ts","sourceRoot":"","sources":["../src/automations-grammar-words.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB,aAKpC,CAAA"}

package/dist/automations-grammar-words.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export const AUTOMATION_RESERVED_WORDS = new Set([
+    'this', 'batch', 'all', 'firstone', 'lastone', 'byid', 'where',
+    'array',
+    'count', 'sum', 'avg', 'min', 'max', 'pluck',
+    'true', 'false', 'null',
+]);

package/dist/automations.repository.interface.d.ts

@@ -0,0 +1,19 @@
+import type { Automation, AutomationAction, AutomationTrigger, AutomationTriggerEvent, WhenNode } from './automations.types.js';
+export interface CreateAutomationInput {
+    seed_slug: string;
+    name: string;
+    triggers: AutomationTrigger[];
+    trigger_conditions: WhenNode | null;
+    actions: AutomationAction[];
+}
+export type UpdateAutomationInput = Partial<CreateAutomationInput>;
+export interface IAutomationRepository {
+    list(seedSlug: string): Promise<Automation[]>;
+    findById(id: string): Promise<Automation | null>;
+    create(input: CreateAutomationInput): Promise<string>;
+    update(id: string, input: UpdateAutomationInput): Promise<void>;
+    toggle(id: string, enabled: boolean): Promise<void>;
+    delete(id: string): Promise<void>;
+    findActive(seedSlug: string, event: AutomationTriggerEvent): Promise<Automation[]>;
+}
+//# sourceMappingURL=automations.repository.interface.d.ts.map

package/dist/automations.repository.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations.repository.interface.d.ts","sourceRoot":"","sources":["../src/automations.repository.interface.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAE/H,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,iBAAiB,EAAE,CAAA;IAC7B,kBAAkB,EAAE,QAAQ,GAAG,IAAI,CAAA;IACnC,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAC5B;AAED,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAElE,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAChD,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACrD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;CACnF"}

package/dist/automations.repository.interface.js

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

package/dist/automations.runner.interface.d.ts

@@ -0,0 +1,10 @@
+import type { AutomationTriggerEvent } from './automations.types.js';
+export interface AutomationEventPayload {
+    seedSlug: string;
+    event: AutomationTriggerEvent;
+    entry: Record<string, unknown>;
+}
+export interface IAutomationRunner {
+    run(payload: AutomationEventPayload): Promise<void>;
+}
+//# sourceMappingURL=automations.runner.interface.d.ts.map

package/dist/automations.runner.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations.runner.interface.d.ts","sourceRoot":"","sources":["../src/automations.runner.interface.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAEpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,sBAAsB,CAAA;IAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpD"}

package/dist/automations.runner.interface.js

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

package/dist/automations.runner.stub.d.ts

@@ -0,0 +1,5 @@
+import type { IAutomationRunner, AutomationEventPayload } from './automations.runner.interface.js';
+export declare class NoOpAutomationRunner implements IAutomationRunner {
+    run(_payload: AutomationEventPayload): Promise<void>;
+}
+//# sourceMappingURL=automations.runner.stub.d.ts.map

package/dist/automations.runner.stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations.runner.stub.d.ts","sourceRoot":"","sources":["../src/automations.runner.stub.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAA;AAElG,qBAAa,oBAAqB,YAAW,iBAAiB;IACtD,GAAG,CAAC,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;CAG3D"}

package/dist/automations.runner.stub.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export class NoOpAutomationRunner {
+    async run(_payload) {
+        // intentionally empty
+    }
+}

package/dist/automations.types.d.ts

@@ -0,0 +1,75 @@
+export type AutomationTriggerEvent = 'create' | 'update' | 'delete' | 'cron';
+export interface AutomationTrigger {
+    event: AutomationTriggerEvent;
+    cron?: string | null;
+}
+export interface TriggerCondition {
+    field: string;
+    op: 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'isempty' | 'isnotempty';
+    value: unknown;
+}
+export type WhenOperand = {
+    kind: 'literal';
+    value: unknown;
+} | {
+    kind: 'ref';
+    key: string;
+};
+export type WhenOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startswith' | 'endswith' | 'in' | 'notin' | 'isempty' | 'isnotempty' | 'matches';
+export interface WhenPredicate {
+    kind: 'predicate';
+    left: WhenOperand;
+    op: WhenOp;
+    right?: WhenOperand;
+}
+export interface WhenGroup {
+    kind: 'group';
+    op: 'AND' | 'OR';
+    children: WhenNode[];
+    negate?: boolean;
+}
+export type WhenNode = WhenPredicate | WhenGroup;
+export interface SetVariableAction {
+    type: 'set_variable';
+    name: string;
+    seed_slug?: string;
+    fixed_id?: string;
+    column?: string;
+    filters?: TriggerCondition[];
+    order_by?: string;
+    order?: 'asc' | 'desc';
+    /** @deprecated Read but ignored at runtime. Removed on next save. */
+    load_type?: 'fruit' | 'branch';
+}
+export type AutomationAction = {
+    type: 'webhook';
+    url: string;
+    method?: 'POST' | 'GET' | 'PUT';
+    headers?: Record<string, string>;
+    body_template?: string;
+} | {
+    type: 'send_mail';
+    to: string;
+    subject_template: string;
+    body_template: string;
+} | {
+    type: 'edit_field';
+    field: string;
+    value: unknown;
+} | {
+    type: 'create_entry';
+    seed_slug: string;
+    field_map: Record<string, string>;
+} | SetVariableAction;
+export interface Automation {
+    id: string;
+    seed_slug: string;
+    name: string;
+    enabled: boolean;
+    triggers: AutomationTrigger[];
+    trigger_conditions: WhenNode | null;
+    actions: AutomationAction[];
+    created_at: number;
+    updated_at: number;
+}
+//# sourceMappingURL=automations.types.d.ts.map

package/dist/automations.types.d.ts.map

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

package/dist/automations.types.js

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

package/dist/clock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Time abstraction. Hides direct calls to {@link Date.now} so callers can
+ * swap in deterministic clocks during tests without resorting to global
+ * timer mocks (e.g. vi.useFakeTimers, sinon, monkey-patching Date).
+ */
+export interface IClock {
+    /**
+     * Returns the current Unix timestamp in milliseconds.
+     * Equivalent to Date.now() in production.
+     * Overridable in tests for deterministic time-sensitive assertions.
+     */
+    now(): number;
+    /**
+     * Returns the current Unix timestamp in whole seconds.
+     * Equivalent to Math.floor(Date.now() / 1000) in production.
+     * Used by JWT issuance, session expiry, and analytics day-bucket computations.
+     */
+    nowSeconds(): number;
+}
+/**
+ * Production singleton. Delegates to the host runtime clock. Stateless and
+ * therefore safe to share across requests.
+ */
+export declare const SystemClock: IClock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,GAAG,IAAI,MAAM,CAAA;IAEb;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAAA;CACrB;AAID;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAGzB,CAAA"}

package/dist/clock.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+const MILLISECONDS_PER_SECOND = 1000;
+/**
+ * Production singleton. Delegates to the host runtime clock. Stateless and
+ * therefore safe to share across requests.
+ */
+export const SystemClock = {
+    now: () => Date.now(),
+    nowSeconds: () => Math.floor(Date.now() / MILLISECONDS_PER_SECOND),
+};

package/dist/content-scan.repository.d.ts

@@ -0,0 +1,9 @@
+import type { Seed } from './types.js';
+export interface IContentScanRepository {
+    /**
+     * Scans across all registered seeds to identify media keys that are currently referenced
+     * by any content entry. Used for orphaned media detection and storage analytics.
+     */
+    getReferencedMediaKeys(seeds: Seed[]): Promise<Set<string>>;
+}
+//# sourceMappingURL=content-scan.repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-scan.repository.d.ts","sourceRoot":"","sources":["../src/content-scan.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;CAC5D"}

package/dist/content-scan.repository.js

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

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;
+    }
+}