@heyo-sh/heyo-cms 0.0.0-stage → 0.1.0

package/dist/engine/documents.d.ts

@@ -0,0 +1,81 @@
+import type { Actor } from "../types/actor";
+import type { ResolvedCollection } from "../types/config";
+import type { ColumnValue, Row } from "../types/query";
+import type { JsonObject, JsonValue } from "../types/json";
+import { type LocaleContext } from "./locales";
+/**
+ * The columns the engine owns on every document.
+ *
+ * They are accepted in an input object and ignored rather than rejected, so
+ * `update({ id, data: doc })` — reading a document, editing one field and
+ * writing the whole thing back — works without the caller having to strip
+ * them first.
+ */
+export declare const systemDocumentFields: readonly ["id", "revision", "createdAt", "updatedAt", "updatedBy", "deletedAt", "purgeAfter", "scheduledAt", "scheduledPatch", "_fallback", "_localeFields"];
+/**
+ * Turns a stored row into the document a caller sees.
+ *
+ * One locale is resolved here, once, so nothing downstream — hook, event,
+ * REST response, template — ever has to know which fields are translated
+ * (section 9).
+ */
+export declare function rowToDocument(row: Row, collection: ResolvedCollection, locale: LocaleContext): JsonObject;
+export interface StoredData {
+    /** The full document body as it will be written to the `data` column. */
+    data: JsonObject;
+    /** Field names the caller actually wrote, in declaration order. */
+    touched: string[];
+}
+/**
+ * Folds a caller's input into the stored body.
+ *
+ * The caller speaks one locale and the storage speaks all of them, so this is
+ * where a flat `{ title: "Hello" }` becomes `{ title: { en: "Hello" } }`
+ * without disturbing the other translations.
+ */
+export declare function toStoredData(collection: ResolvedCollection, input: JsonObject, locale: LocaleContext, previous?: JsonObject): StoredData;
+/**
+ * Validates the fields a write touched, with the field's own zod schema.
+ *
+ * Only the touched ones: a localized field is required per locale, and
+ * demanding every translation before a German draft can be saved would make
+ * partial translations impossible — which section 9 says are the norm. A
+ * create touches everything, so `required` is still enforced where it matters.
+ */
+export declare function validateFields(collection: ResolvedCollection, data: JsonObject, locale: LocaleContext, fields: string[]): void;
+/** Field names whose resolved value differs between two documents. */
+export declare function changedFields(collection: ResolvedCollection, previous: JsonObject, next: JsonObject): string[];
+/**
+ * A system table row as JSON.
+ *
+ * System tables use real columns and therefore snake_case, which is a storage
+ * detail. A `depth` expansion that handed a template `storage_key` would be
+ * leaking it (a `media` relation is resolved through this).
+ */
+export declare function systemRowToJson(row: Row): JsonObject;
+/**
+ * A scheduled change as it is stored.
+ *
+ * The locale travels with the patch because a patch is written in one
+ * language: applying `{ title: "Hallo" }` next Friday has to write the German
+ * title, not the default one (section 9). The actor travels with it because
+ * the change is applied as an ordinary update and therefore has to pass the
+ * same access control a human write would.
+ */
+export interface ScheduledPatch {
+    data: JsonObject;
+    locale: string;
+    actor: Actor | null;
+}
+export declare function scheduledPatch(row: Row): ScheduledPatch | null;
+/**
+ * The stored revision, defaulting to 1.
+ *
+ * A row written before the column existed reads as revision 1 rather than as
+ * `null`: the number means "how many times this has changed", and a document
+ * that has never changed since the column arrived has changed once.
+ */
+export declare function toRevision(value: ColumnValue | undefined): number;
+export declare function toIso(value: ColumnValue | undefined): string | null;
+export declare function asObject(value: ColumnValue | JsonValue | undefined): JsonObject;
+//# sourceMappingURL=documents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/engine/documents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,WAAW,CAAC;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,YAC/B,IAAI,EACJ,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,eAAe,CACP,CAAC;AAIX;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,GAAG,EACR,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,aAAa,GACpB,UAAU,CA2DZ;AAED,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,IAAI,EAAE,UAAU,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,aAAa,EACrB,QAAQ,CAAC,EAAE,UAAU,GACpB,UAAU,CA+BZ;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,kBAAkB,EAC9B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EAAE,GACf,IAAI,CA6BN;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,UAAU,GACf,MAAM,EAAE,CAIV;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAWpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,GAAG,IAAI,CAQ9D;AAsBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAGjE;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAInE;AAED,wBAAgB,QAAQ,CACtB,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,GACzC,UAAU,CAKZ"}

package/dist/engine/engine.d.ts

@@ -0,0 +1,276 @@
+import type { CollectionApi, GlobalApi } from "../types/api";
+import type { ResolvedCmsConfig, ResolvedCollection } from "../types/config";
+import type { DatabaseAdapter } from "../types/database";
+import type { CmsInstance } from "../types/instance";
+import type { JsonObject } from "../types/json";
+import type { Tx } from "../types/query";
+import type { CmsTrash } from "../types/trash";
+import { JobRunner } from "./jobs";
+import { type BufferedEvent, type EventDispatch, type OutboxEntryMeta } from "./outbox";
+export interface EngineOptions {
+    config: ResolvedCmsConfig;
+    /** Resolved lazily: a D1 binding only exists inside a request. */
+    database: () => Promise<DatabaseAdapter>;
+    dispatch: EventDispatch;
+}
+/**
+ * What one write means.
+ *
+ * `operation` in the hook contract is CRUD and stays CRUD (section 5); this
+ * is the finer question the engine has to answer anyway — which event to
+ * emit, what the activity log should say, whether the `delete` hooks have
+ * already run. Keeping the two apart is what lets the trash exist without
+ * adding a fourth hook family nobody asked for.
+ */
+export type WriteIntent = "create" | "update" | "trash" | "restore" | "purge" | "schedule" | "unschedule";
+/**
+ * The engine: one read path, one write path.
+ *
+ * Every document write in the product — local API, REST, the panel, a job,
+ * the scheduler — goes through `runWrite`. That is a deliberate constraint
+ * rather than tidiness: hooks, the outbox, the activity log and the future
+ * versions plugin all attach at one point, and a second write path would be a
+ * second place for each of them to be forgotten (stage 3).
+ */
+export declare class CmsEngine {
+    private readonly options;
+    private cms;
+    private readonly pipelines;
+    /** Collections and globals by name, for relation targets. */
+    private readonly byName;
+    /** The same by storage slug: a stored row knows its slug, not its name. */
+    private readonly bySlug;
+    /**
+     * Which collections can point at a file at all.
+     *
+     * Answered once per collection, because the alternative is three extra
+     * queries on every write to a collection that has no images — which is most
+     * of them.
+     */
+    private readonly media;
+    private outbox;
+    private delivery;
+    constructor(options: EngineOptions);
+    /**
+     * Hands the engine the instance hooks receive as `ctx.cms`.
+     *
+     * Separate from the constructor because the two refer to each other: the
+     * instance exposes `api`, and `api` has to be able to call back into the
+     * instance with access control enforced.
+     */
+    bind(cms: CmsInstance): void;
+    /** `cms.api`, built once: one entry per declared collection. */
+    buildApi(): Record<string, CollectionApi<JsonObject>>;
+    /** `cms.globals`: the same machinery, one row, no `find` and no `create`. */
+    buildGlobals(): Record<string, GlobalApi<JsonObject>>;
+    /** `cms.trash`: deleted documents across every collection at once. */
+    buildTrash(): CmsTrash;
+    /** `cms.jobs`: the sweeps. Returned concrete so media can register its own. */
+    buildJobs(): JobRunner;
+    /**
+     * Delivers everything the outbox owes.
+     *
+     * A commit already schedules a delivery in the background; this is how a
+     * caller waits for it — a test, a CLI, or a serverless runtime that is
+     * about to freeze the process. Returns what this call delivered, which may
+     * be zero because the background pass got there first.
+     */
+    drainEvents(limit?: number): Promise<number>;
+    /** Waits for in-flight deliveries. Called by `cms.close()`. */
+    settle(): Promise<void>;
+    /**
+     * Writes events for an operation that is not a document write.
+     *
+     * Auth is the first caller: an invitation or a role change has to reach a
+     * webhook the same way a document change does — inside the transaction that
+     * caused it, delivered after the commit — and giving it a second mechanism
+     * would give it a second set of failure modes (section 5).
+     */
+    appendEvents(tx: Tx, events: BufferedEvent[], meta: OutboxEntryMeta): Promise<void>;
+    /** Delivers what the last committed transaction queued, in the background. */
+    deliverSoon(): void;
+    private collectionApi;
+    private find;
+    private findOne;
+    private findById;
+    private count;
+    private create;
+    private update;
+    /**
+     * The delete an editor performs.
+     *
+     * With the trash on it is a soft delete and the row keeps serving every
+     * query that asks for `includeTrashed`; with it off, or with
+     * `permanent: true`, the row goes. Either way the `delete` hooks run here
+     * and only here: the document is leaving the live set, which is the moment
+     * a hook was written for. A later purge does not run them again, because a
+     * hook that decrements a counter must not decrement it twice for one
+     * document.
+     */
+    private remove;
+    private restore;
+    /**
+     * The permanent delete.
+     *
+     * Also the only operation that cleans up what pointed at the document:
+     * media usages survive the trash on purpose — an image used by a document
+     * an editor may still restore is not unused — so this is where they stop
+     * (section 6).
+     */
+    private purge;
+    /**
+     * Records a change to apply later.
+     *
+     * The patch is checked now — access, field-level write access, validation —
+     * and applied later as an ordinary update, so the question "may this person
+     * schedule a publication" is answered by the same rules that answer "may
+     * this person publish". The alternative, checking only at apply time, would
+     * accept a schedule in the panel and fail silently on a Friday night.
+     */
+    private schedule;
+    private unschedule;
+    private globalApi;
+    /**
+     * A global that nobody has saved yet reads as its defaults.
+     *
+     * No row is written: a read that writes cannot run on a replica, cannot run
+     * in a Worker that only has a read binding, and turns an anonymous page view
+     * into a database mutation.
+     */
+    private globalGet;
+    /**
+     * Makes sure the singleton has a row, and reports its id.
+     *
+     * The id is derived from the slug rather than generated, which is what makes
+     * this safe to call concurrently: two first saves race to insert the same
+     * primary key, one of them loses, and losing means the row it wanted is
+     * already there.
+     */
+    private ensureGlobalRow;
+    /**
+     * The defaults row: what a global is before anybody saves it.
+     *
+     * `created` is `null` for the copy `get()` invents and a date for the copy
+     * that is actually inserted. A global nobody has saved has no creation time,
+     * and inventing one would make "has this ever been configured" unanswerable.
+     */
+    private emptyGlobalRow;
+    /**
+     * Applies one due scheduled change, as an ordinary update.
+     *
+     * Claim first, then write. The claim is a conditional update — the same
+     * portable trick the outbox uses — so two overlapping cron invocations
+     * cannot both apply the same patch, on any of the three engines and without
+     * a lock.
+     */
+    private applyScheduled;
+    /** Purges one expired trash entry, as the system rather than as a person. */
+    private purgeExpired;
+    private clearSchedule;
+    /**
+     * Records a failed job item and tells the world about it.
+     *
+     * In the `jobs` table rather than only in a log: `job.failed` is in the
+     * event catalogue (section 7) because an operator has to be able to be
+     * paged for it, and a payload that only exists in stdout cannot be retried.
+     */
+    private recordFailure;
+    /**
+     * The one place a document is written.
+     *
+     * Transaction, hooks, events, activity — in that order, every time. The
+     * operation-specific part is the `step` callback and nothing else, which is
+     * what makes the later versions plugin a single attachment point rather
+     * than three (stage 3, section 4).
+     */
+    private runWrite;
+    /**
+     * The answer a repeated write already has.
+     *
+     * Only consulted when the caller supplied a key, so an ordinary save pays
+     * nothing for it. The stored document is returned verbatim: re-reading the
+     * row would describe the world now rather than what this call did, and a
+     * retry that reports somebody else's later edit as its own result is worse
+     * than no idempotency at all.
+     */
+    private replay;
+    private recordIdempotency;
+    private runAfter;
+    /**
+     * The events the engine itself owes, in the order a consumer expects them.
+     *
+     * `document.field.changed` is one event per field that actually changed,
+     * which is what makes "tell me when `status` becomes `published`" a
+     * subscription rather than a diff the consumer has to compute (section 7).
+     */
+    private emitDocumentEvents;
+    /**
+     * Keeps `media_usages` in step with what the document now contains.
+     *
+     * This is the whole of the media lifecycle's accounting. Nothing counts
+     * references at read time or at delete time; the count is maintained here,
+     * once, and `media-gc` only ever acts on what it says.
+     */
+    private syncMedia;
+    private referencesMedia;
+    /**
+     * The activity log, written by the engine inside the transaction.
+     *
+     * Built in rather than a plugin (section 11): an audit trail that can be
+     * switched off, or that commits separately from the change it describes, is
+     * not an audit trail.
+     */
+    private writeActivity;
+    /** Collection, trash and access filters, combined the only legal way. */
+    private scope;
+    private load;
+    /**
+     * Writes system columns on one row and reports the row as it now stands.
+     *
+     * Also the one place `revision` moves. Every write that reaches here changed
+     * the row, so every write bumps it — there is no "minor" update that a
+     * concurrent editor would not want to know about, and a token that only
+     * sometimes advances is a token nobody can rely on.
+     *
+     * `expected` turns the write into a compare-and-set. The comparison is in
+     * the `WHERE` clause rather than in a read before it: two requests that both
+     * read revision 17 must not both find it acceptable, and only the database
+     * can decide which of them wins.
+     */
+    private patch;
+    private assertAllowed;
+    private requireCollection;
+    /** When a document deleted now should be purged, or `null` if never. */
+    private purgeAt;
+    private expand;
+    /**
+     * Drops the fields this actor may not read.
+     *
+     * Skipped entirely when the collection declares no field rules, which is
+     * the overwhelmingly common case and the difference between a check and a
+     * cost.
+     */
+    private redact;
+    private pipeline;
+    private outboxMeta;
+    private outboxWorker;
+    /**
+     * Delivery after the commit, never during it.
+     *
+     * Chained rather than fired in parallel so events keep their order, and
+     * swallowed because a failed delivery is the outbox's problem — it is
+     * recorded, retried, and must not turn a successful write into a thrown
+     * error (section 5).
+     */
+    private scheduleDelivery;
+    private instance;
+}
+/**
+ * A singleton's row id, derived from its slug.
+ *
+ * Deterministic because it has to be: the row is created on first save, and a
+ * generated id would let two concurrent saves produce two rows for a document
+ * the configuration says there is exactly one of.
+ */
+export declare function globalRowId(global: ResolvedCollection): string;
+//# sourceMappingURL=engine.d.ts.map

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

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

package/dist/engine/field-access.d.ts

@@ -0,0 +1,21 @@
+import type { Actor } from "../types/actor";
+import type { ResolvedCollection } from "../types/config";
+import type { JsonObject } from "../types/json";
+export declare function hasFieldAccessRules(collection: ResolvedCollection): boolean;
+/**
+ * Removes the fields this actor may not read, in place.
+ *
+ * In place because the caller owns the document: it was just built from a
+ * row, and copying every document of every page to delete a key from one of
+ * them would be the wrong trade.
+ */
+export declare function applyFieldReadAccess(document: JsonObject, collection: ResolvedCollection, actor: Actor | null, locale: string | null): JsonObject;
+/**
+ * Refuses a write that touches a field the actor may not write.
+ *
+ * Refuses rather than drops: silently ignoring half a form is how an editor
+ * ends up believing they published something. The error names the fields, so
+ * a panel can mark them.
+ */
+export declare function assertFieldWriteAccess(collection: ResolvedCollection, input: JsonObject, actor: Actor | null, locale: string | null, record?: JsonObject): void;
+//# sourceMappingURL=field-access.d.ts.map

package/dist/engine/field-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-access.d.ts","sourceRoot":"","sources":["../../src/engine/field-access.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAiDhD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAG3E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,UAAU,CAuBZ;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,KAAK,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,MAAM,CAAC,EAAE,UAAU,GAClB,IAAI,CAmBN"}

package/dist/engine/hooks.d.ts

@@ -0,0 +1,58 @@
+import type { ResolvedCmsConfig } from "../types/config";
+import type { CreateHookInput, HookContext, HookResult, MaybePromise, UpdateHookInput, UpdateHookOutput } from "../types/hooks";
+import type { HookPipelineEntry } from "../types/instance";
+import type { JsonObject } from "../types/json";
+/** Where a hook came from and when it runs, carried so `inspect()` can say. */
+interface Registered {
+    source: string;
+    priority: number;
+}
+export interface BeforeEntry<TInput> extends Registered {
+    run: (input: TInput, context: HookContext) => MaybePromise<HookResult<JsonObject>>;
+}
+export interface AfterEntry<TOutput> extends Registered {
+    run: (output: TOutput, context: HookContext) => MaybePromise<void>;
+}
+/**
+ * Every hook that can run on one collection, already in execution order.
+ *
+ * Built once per collection at start-up rather than looked up per write: the
+ * order is a property of the configuration, so computing it on every request
+ * would be work that cannot change its own answer.
+ */
+export interface CollectionHookPipeline {
+    createBefore: BeforeEntry<CreateHookInput<JsonObject>>[];
+    createAfter: AfterEntry<JsonObject>[];
+    updateBefore: BeforeEntry<UpdateHookInput<JsonObject>>[];
+    updateAfter: AfterEntry<UpdateHookOutput<JsonObject>>[];
+    deleteBefore: BeforeEntry<JsonObject>[];
+    deleteAfter: AfterEntry<JsonObject>[];
+}
+/**
+ * Assembles the pipeline for one collection.
+ *
+ * Plugin hooks run first in `priority` order, the configuration's own hooks
+ * always run last. A user who installed a plugin can therefore always have
+ * the final word over it, without the plugin having to anticipate that
+ * (section 5).
+ */
+export declare function buildHookPipeline(config: ResolvedCmsConfig, collection: string): CollectionHookPipeline;
+/**
+ * Runs the `before` chain and reports what the operation should do next.
+ *
+ * One return contract for every hook, which is the part Payload gets wrong:
+ * `undefined` continue, `{ data }` continue with a replacement, `false` stop
+ * silently, `throw` stop with a status. `apply` is how a replacement folds
+ * back into an operation-shaped input.
+ */
+export declare function runBeforeHooks<TInput>(entries: BeforeEntry<TInput>[], input: TInput, context: HookContext, apply: (input: TInput, data: JsonObject) => TInput): Promise<TInput | false>;
+export declare function runAfterHooks<TOutput>(entries: AfterEntry<TOutput>[], output: TOutput, context: HookContext): Promise<void>;
+/**
+ * The pipeline as `cms.inspect()` prints it.
+ *
+ * Derived from the same builder the engine runs, so the printed order cannot
+ * drift from the executed one — which is the entire value of printing it.
+ */
+export declare function hookPipelineEntries(config: ResolvedCmsConfig): HookPipelineEntry[];
+export {};
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/engine/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAEV,eAAe,EACf,WAAW,EAEX,UAAU,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,+EAA+E;AAC/E,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW,CAAC,MAAM,CAAE,SAAQ,UAAU;IACrD,GAAG,EAAE,CACH,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,KACjB,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,UAAU,CAAC,OAAO,CAAE,SAAQ,UAAU;IACrD,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,WAAW,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;IACzD,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;IACtC,YAAY,EAAE,WAAW,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;IACzD,WAAW,EAAE,UAAU,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;IACxD,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;IACxC,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,MAAM,GACjB,sBAAsB,CA0ExB;AAyCD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EACzC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,MAAM,GACjD,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,CAUzB;AAED,wBAAsB,aAAa,CAAC,OAAO,EACzC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,EAC9B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,GACxB,iBAAiB,EAAE,CAkCrB"}

package/dist/engine/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The engine: the local API, the hook pipeline and the transactional outbox.
+ *
+ * Nothing here is HTTP-aware. The router in stage 7 calls exactly the same
+ * functions the local API does, which is the only way `cms.api.posts.find()`
+ * and `GET /api/heyo-cms/posts` can be guaranteed to behave identically
+ * (section 10).
+ */
+export { CmsEngine, globalRowId, type EngineOptions, type WriteIntent, } from "./engine";
+export { JobRunner, type JobDefinition, type JobHost } from "./jobs";
+export { listTrashed, type ListTrashedOptions } from "./trash";
+export { EventBuffer, Outbox, type EventDispatch } from "./outbox";
+export { buildHookPipeline, hookPipelineEntries, runAfterHooks, runBeforeHooks, type CollectionHookPipeline, } from "./hooks";
+export { localeContext, resolveLocalized, type LocaleContext } from "./locales";
+export { rowToDocument, scheduledPatch, toStoredData, validateFields, type ScheduledPatch, } from "./documents";
+export { applyFieldReadAccess, assertFieldWriteAccess, hasFieldAccessRules, } from "./field-access";
+export { RelationLoader, relationTarget } from "./relations";
+export { scopedDb } from "./scoped-db";
+export { cursorWhere, encodeCursor } from "./cursor";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,SAAS,EACT,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,KAAK,sBAAsB,GAC5B,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/engine/jobs.d.ts

@@ -0,0 +1,63 @@
+import type { ResolvedCmsConfig } from "../types/config";
+import type { DatabaseAdapter } from "../types/database";
+import type { CmsJobs, JobFailure, JobFailureArgs, JobRunArgs, JobRunReport } from "../types/jobs";
+import type { JsonObject } from "../types/json";
+import type { Row } from "../types/query";
+/**
+ * What a sweep needs from the engine.
+ *
+ * Narrow on purpose: a job may ask which rows are due and may ask the engine
+ * to act on one of them, and it may not write a document itself. Every write
+ * in the product goes through one function (stage 3), and a background worker
+ * is exactly the kind of caller that would quietly grow a second one.
+ */
+export interface JobHost {
+    config: ResolvedCmsConfig;
+    database(): Promise<DatabaseAdapter>;
+    applyScheduled(row: Row): Promise<void>;
+    purgeExpired(row: Row): Promise<void>;
+    recordFailure(type: string, payload: JsonObject, error: unknown): Promise<void>;
+}
+/**
+ * One sweep.
+ *
+ * Split into "what is due" and "act on one of them" so the runner owns the
+ * batching, the counting and the failure record, and a job only has to know
+ * its own question. Exported because `media-gc` is registered through it, and
+ * a plugin will eventually register its own the same way.
+ */
+export interface JobDefinition {
+    name: string;
+    /** Rows this job would act on, oldest obligation first. */
+    due(host: JobHost, now: Date, limit: number): Promise<Row[]>;
+    run(host: JobHost, row: Row, now: Date): Promise<void>;
+    /** What a failure is recorded as in the `jobs` table. */
+    failureType: string;
+    failurePayload(row: Row): JsonObject;
+}
+/**
+ * `cms.jobs`.
+ *
+ * A registry rather than hard-coded calls: `media-gc` joins the two below only
+ * when the configuration has an `uploads` section, a plugin will eventually
+ * add its own, and `cms.inspect().jobs` has to print what will actually run
+ * rather than what the package happens to contain.
+ */
+export declare class JobRunner implements CmsJobs {
+    private readonly host;
+    private readonly jobs;
+    constructor(host: JobHost);
+    list(): string[];
+    /** Adds a sweep. Used by the media lifecycle, and later by plugins. */
+    register(job: JobDefinition): void;
+    /**
+     * One pass over everything that is due.
+     *
+     * A failing item never stops the sweep: one document whose scheduled change
+     * no longer validates must not keep every other publication waiting. Each
+     * failure is recorded with its payload and emitted as `job.failed`.
+     */
+    run(args?: JobRunArgs): Promise<JobRunReport>;
+    failures(args?: JobFailureArgs): Promise<JobFailure[]>;
+}
+//# sourceMappingURL=jobs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../src/engine/jobs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,cAAc,EAEd,UAAU,EACV,YAAY,EACb,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAM1C;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACrC,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7D,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAAC;CACtC;AAgFD;;;;;;;GAOG;AACH,qBAAa,SAAU,YAAW,OAAO;IAG3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmD;IAExE,YAA6B,IAAI,EAAE,OAAO,EAAI;IAE9C,IAAI,IAAI,MAAM,EAAE,CAEf;IAED,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAEjC;IAED;;;;;;OAMG;IACG,GAAG,CAAC,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CA2CtD;IAEK,QAAQ,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAsB/D;CACF"}

package/dist/engine/locales.d.ts

@@ -0,0 +1,40 @@
+import type { LocaleArgs } from "../types/api";
+import type { ResolvedCmsConfig } from "../types/config";
+import type { JsonObject, JsonValue } from "../types/json";
+/**
+ * Everything a read needs to know about language, resolved once per call.
+ *
+ * Fallback is decided here and nowhere else: a field that resolves one way in
+ * the REST layer and another way in a hook would make `_fallback` a claim
+ * nobody could rely on.
+ */
+export interface LocaleContext {
+    /** The locale the caller asked for. */
+    locale: string;
+    /** The order values are looked up in, starting with `locale` itself. */
+    chain: string[];
+}
+/**
+ * One rule, not a configuration section: a field with no value in the
+ * requested language is answered from `i18n.defaultLocale`, and the response
+ * says which fields those were. A caller that wants the gaps instead of the
+ * substitution passes `fallbackLocale: false` for that one call — which is
+ * exactly what the panel does while somebody is filling translations in.
+ */
+export declare function localeContext(config: ResolvedCmsConfig, args?: LocaleArgs): LocaleContext;
+export interface ResolvedValue {
+    value: JsonValue;
+    /** The locale the value actually came from, `null` when nothing matched. */
+    from: string | null;
+}
+/**
+ * Picks one locale's value out of a stored `{ [locale]: value }` map.
+ *
+ * Fallback is per field, not per document: partial translations are the norm,
+ * so a document with a translated title and an untranslated body has to be
+ * expressible (section 9).
+ */
+export declare function resolveLocalized(stored: JsonValue | undefined, locale: LocaleContext): ResolvedValue;
+/** Writes one locale into a stored map, leaving the other languages alone. */
+export declare function writeLocalized(stored: JsonValue | undefined, locale: string, value: JsonValue): JsonObject;
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../src/engine/locales.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,EACzB,IAAI,GAAE,UAAe,GACpB,aAAa,CAGf;AAmBD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,MAAM,EAAE,aAAa,GACpB,aAAa,CAOf;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,GACf,UAAU,CAIZ"}