@forge-cms/runtime 0.4.0 → 0.6.0

package/dist/operations.d.ts

@@ -2,6 +2,7 @@ import type { CmsUser, DraftStatus } from '@forge-cms/core';
 import type { DatabaseRecord, DatabaseWhere, SortInput } from '@forge-cms/db';
 import type { OperationContext } from './context.js';
 import { populateRecord, populateRecords } from './populate.js';
+import type { RestoreVersionArgs } from './versions.js';
 /** A page of documents plus everything a paginator needs. */
 export interface PaginatedDocs<TDoc = DatabaseRecord> {
     docs: TDoc[];
@@ -62,6 +63,12 @@ export interface CreateArgs extends BaseOperationArgs {
 export interface UpdateArgs extends BaseOperationArgs {
     id: string;
     data: Record<string, unknown>;
+    /**
+     * Overrides the default (unlabeled) version snapshot's label when this update creates one — used by
+     * {@link restoreVersion} so a restore creates exactly one version, labeled, instead of restoring
+     * through a second bespoke write path (spec 058 §2).
+     */
+    versionLabel?: string;
 }
 export interface DeleteArgs extends BaseOperationArgs {
     id: string;
@@ -80,7 +87,89 @@ export declare function findByID(ctx: OperationContext, args: FindByIDArgs & {
 }): Promise<DatabaseRecord>;
 export declare function count(ctx: OperationContext, args: CountArgs): Promise<number>;
 export declare function create(ctx: OperationContext, args: CreateArgs): Promise<DatabaseRecord>;
+/**
+ * The multipart upload pipeline's create (spec 063 §5) — **package-private**: exported for
+ * `handlers.ts` only, never from the package entry point. `storageKey` is the key Forge itself just
+ * generated and stored the object under; it is merged into the persisted row only, outside caller
+ * `data` and hook `data`, so no caller of the public mutation surface can choose or rewrite it.
+ */
+export declare function createUpload(ctx: OperationContext, args: CreateArgs, upload: {
+    storageKey: string;
+    intentId: string;
+}): Promise<DatabaseRecord>;
+/**
+ * The whole upload create (spec 067) — **package-private**, called by `handleCreate` for a multipart
+ * body: records a durable storage intent, stores the object under a Forge-generated key, then creates
+ * the document with the key and the intent claim in one batch. Any failure after the intent exists
+ * settles it: the object is deleted only while the intent is still there (the document never
+ * committed); otherwise the intent stays for `reconcileStorage()`. The file's `filename`, `url`,
+ * `contentType` and `filesize` fill whichever of those fields the collection declares, under `args.data`.
+ */
+export declare function uploadFile(ctx: OperationContext, args: CreateArgs, file: File): Promise<DatabaseRecord>;
 export declare function update(ctx: OperationContext, args: UpdateArgs): Promise<DatabaseRecord>;
+/**
+ * Restores a document to a specific historical version — spec 058 §2, made atomic by spec 062. The raw
+ * snapshot is read (trusted — restore's authorization gate is `update()`'s own update-access check on
+ * the *current* document, see spec 058 §2) and handed to this module's own update pipeline, which turns
+ * it into a patch of only the fields that differ from the current document (spec 062 §6) and then runs
+ * the normal update-access / row-policy / field-write / validation / hook pipeline. The patch and one
+ * snapshot labeled `Restored from version N` commit in one atomic batch, so a forbidden, invalid or
+ * conflicting restore leaves both the document and its history unchanged.
+ *
+ * System metadata (`id`, `created_at`, `updated_at`, `_storageKey`) is never restored. A full (spec 062)
+ * snapshot sets every currently declared field, so a snapshot that predates a now-required field fails
+ * current validation instead of producing an invalid document.
+ */
+export declare function restoreVersion(ctx: OperationContext, args: RestoreVersionArgs): Promise<DatabaseRecord>;
+/**
+ * Deletes a document together with its whole relation graph (spec 064 §5) — plan, prepare, **one**
+ * `atomicWrite`, finalize:
+ *
+ * 1. **Plan** (reads only): root `beforeOperation`, read, access; then {@link planRelationDelete} walks
+ *    every cascade/set-null/restrict reference to its fixpoint, judges restrict and required set-null
+ *    against the final state, and refuses a plan that cannot fit in one batch — before any `before*`
+ *    hook of the graph and before any write.
+ * 2. **Prepare** (hooks, validation; no writes): root `beforeDelete`; each cascaded document's
+ *    `beforeOperation` + `beforeDelete`; each set-null document through the same {@link prepareUpdate}
+ *    `update()` uses. Dependents run with `overrideAccess: true` — a consequence of an authorized delete,
+ *    like a database's own `ON DELETE CASCADE` (spec 058 §5) — but never skip validation or hooks.
+ * 3. **Commit**: set-null patches (versioned: spec 062's update + snapshot), cascaded deletes guarded by
+ *    the `updated_at` they were planned with, the root delete, and finally one "no reference remains"
+ *    `assertCount` per referring field — all in one batch, so a late failure or a reference created
+ *    concurrently leaves every row unchanged.
+ * 4. **Finalize** (after commit): storage cleanup for deleted upload documents, then after-hooks —
+ *    dependents first, root last.
+ *
+ * Before-hooks are not transactional: a side effect they performed outside the database survives a
+ * rollback of the batch (roadmap D01).
+ */
 export declare function deleteDocument(ctx: OperationContext, args: DeleteArgs): Promise<DatabaseRecord>;
+export interface PreviewArgs extends BaseOperationArgs {
+    data: Record<string, unknown>;
+    id?: string;
+}
+/**
+ * A non-persistent simulation of a permitted create/update — spec 058 §3. Before this fix, preview
+ * read the raw adapter row and merged caller-supplied `data` with **no** access enforcement at all
+ * (no collection/row/field-write check, no draft-visibility check, no field-read projection): any
+ * caller who could reach the endpoint could preview (and see every hidden field of) any document,
+ * and could smuggle a forbidden field into the merged output because it was never persisted.
+ *
+ * Existing-document preview now requires the same **update** access an actual `update()` call would
+ * (row-level policy included) plus the same draft-visibility a normal single-document read applies —
+ * stricter than raw `update()` (which has no draft gate), because preview hands the full merged
+ * document back to the caller to render, unlike a blind write. New-document preview requires **create**
+ * access. Both require field-write access on every field in `data` when untrusted
+ * (`overrideAccess: false`), and project the returned document through the same field-read rules a
+ * normal read would (hidden fields never appear in the output). Depth-1 population forwards the
+ * caller's `user`/`overrideAccess`, so a populated target obeys the §4 population-visibility fix
+ * instead of always resolving as a trusted call.
+ *
+ * Zero adapter writes, zero version creation, zero committed-mutation hooks — unchanged from before
+ * this fix; this function never called `create()`/`update()`/`createVersion()`.  Full
+ * `validateCollection()` is deliberately not run: preview must be able to render an intentionally
+ * incomplete draft, not just a document that would actually pass validation.
+ */
+export declare function preview(ctx: OperationContext, args: PreviewArgs): Promise<DatabaseRecord>;
 export { populateRecord, populateRecords };
 //# sourceMappingURL=operations.d.ts.map

package/dist/operations.d.ts.map

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