canopycms 0.11.1 → 0.12.1

package/dist/api/merge-conflicts.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The conflicts the worker's merges left on a branch (merge-conflicts.ts), for the editor to show
+ * and resolve: the list, one entry's conflicts with the three versions they compare, and the
+ * choices that resolve an entry-level one. A field conflict is resolved by an ordinary save
+ * (`resolvedConflicts`, api/content.ts), through {@link clearFieldConflicts}.
+ */
+import { z } from 'zod';
+import type { BranchContext } from '../types.js';
+import type { ApiResponse } from './types.js';
+import type { DataPathSegment } from '../editor/entry-diff.js';
+import type { FieldConflictKind, SidePaths } from '../merge/entry-merge.js';
+import { type MergeConflictKind, type MergeSides, type ResolvedFieldConflict } from '../merge-conflicts.js';
+import type { ContentId, LogicalPath } from '../paths/types.js';
+import type { EntryChangeSide } from './branch-entry-changes.js';
+/** One entry's open conflicts, as the list names them. */
+export interface MergeConflictListItem {
+    contentId: string;
+    kind: MergeConflictKind;
+    /** Where the file is in the branch, or was, for one the branch deleted. */
+    path: string;
+    /** The entry's logical path; for a collection's settings, the collection's. */
+    logicalPath?: string;
+    /** Fields with a conflict open; 0 for an entry-level conflict. */
+    fieldCount: number;
+    /** The merge that last changed this entry's record. */
+    mergeSha: string;
+}
+export interface MergeConflictsData {
+    conflicts: MergeConflictListItem[];
+    /** Entries with conflicts open that this user may not read: counted, never named. */
+    hiddenCount: number;
+    /** Choices open on the branch, each field and each entry-level conflict, hidden ones included. */
+    openCount: number;
+    /**
+     * The branch's record was damaged and set aside, so Submit and Approve wait until an admin
+     * releases it (`POST /:branch/conflicts/release-hold`); the file it was moved to, for admins.
+     */
+    held?: {
+        at: string;
+        aside?: string;
+    };
+}
+export type MergeConflictsResponse = ApiResponse<MergeConflictsData>;
+/** A version a conflict compares that can't be shown. */
+interface UnavailableConflictSide {
+    unavailable: 'too-large' | 'unreadable' | 'missing' | 'not-an-entry';
+}
+export type ConflictSide = EntryChangeSide | UnavailableConflictSide;
+export interface EntryConflictField {
+    /** The record's name for the place: what `resolvedConflicts` sends back. */
+    key: string;
+    /**
+     * The key the "Show changes" drawer gives the place, under the entry's schema now. It differs from
+     * `key` only for a conflict the worker recorded without the schema.
+     */
+    drawerKey: string;
+    dataPath: DataPathSegment[];
+    /**
+     * Where each of `sides`' versions holds the value, as `versions` reads it; absent for a version
+     * without the place. A list item can read under another key in one version than `dataPath`
+     * names, as one in a list a side left keyless does.
+     */
+    sidePaths: SidePaths;
+    kind: FieldConflictKind;
+    /** A whole list item: resolving it keeps or removes the item. */
+    item?: true;
+    /** Long text merged by line, its conflicting regions found from the three versions. */
+    text?: true;
+    mergeSha: string;
+    /** What the author started from, and the versions of the merge that last found it. */
+    sides: MergeSides;
+}
+export interface EntryConflictData {
+    contentId: string;
+    kind: MergeConflictKind;
+    path: string;
+    logicalPath: string;
+    mergeSha: string;
+    sides: MergeSides;
+    fields: EntryConflictField[];
+    /** Every version a side names, by blob id, read as the editor reads an entry. */
+    versions: Record<string, ConflictSide>;
+}
+export type EntryConflictResponse = ApiResponse<EntryConflictData>;
+/** What an entry-level conflict is resolved by. */
+export type EntryConflictChoice = 'keep' | 'delete' | 'restore' | 'use-latest';
+export type ResolveEntryConflictResponse = ApiResponse<{
+    contentId: string;
+    openCount: number;
+}>;
+/** A save's `resolvedConflicts`: field conflicts the saved values resolve. */
+export declare const resolvedConflictsSchema: z.ZodArray<z.ZodObject<{
+    mergeSha: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    mergeSha: string;
+}, {
+    key: string;
+    mergeSha: string;
+}>, "many">;
+/**
+ * Take the field conflicts `resolved` names off `contentId`'s record, each by its own merge and
+ * key, and resolve those it cleared. A pair the record no longer holds is ignored. For a save to
+ * call once the entry is written, inside its locks: the record's own locks come after them in
+ * the one lock order (docs/concurrency.md).
+ */
+export declare function clearFieldConflicts(branchContext: BranchContext, contentId: string, resolved: readonly ResolvedFieldConflict[]): Promise<ResolvedFieldConflict[]>;
+declare const resolveBodySchema: z.ZodObject<{
+    /** The content id the record names the entry by. */
+    id: z.ZodType<ContentId, z.ZodTypeDef, ContentId>;
+    /** The merge that last changed the record, as the conflict was shown. */
+    mergeSha: z.ZodString;
+    /**
+     * `keep`: leave the branch as it is, for any kind; `delete`: delete the entry the latest
+     * version deleted (`deleted-on-base`); `restore`: put back the entry the branch deleted, as the
+     * latest version has it (`deleted-on-branch`); `use-latest`: replace an entry that can't be merged
+     * field by field with the latest version (`unreadable`).
+     */
+    choice: z.ZodEnum<["keep", "delete", "restore", "use-latest"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string & {
+        readonly __brand: "ContentId";
+    };
+    mergeSha: string;
+    choice: "delete" | "restore" | "keep" | "use-latest";
+}, {
+    id: string & {
+        readonly __brand: "ContentId";
+    };
+    mergeSha: string;
+    choice: "delete" | "restore" | "keep" | "use-latest";
+}>;
+export type ResolveEntryConflictBody = z.infer<typeof resolveBodySchema>;
+export type ReleaseConflictsHoldResponse = ApiResponse<{
+    released: boolean;
+}>;
+export declare const MERGE_CONFLICT_ROUTES: {
+    readonly list: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }>, undefined, MergeConflictsResponse>;
+    readonly releaseHold: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }>, undefined, ReleaseConflictsHoldResponse>;
+    readonly entry: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+        entryPath: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
+        /** The entry's content id, which tells an entry from a collection at the same path. */
+        id: z.ZodOptional<z.ZodType<ContentId, z.ZodTypeDef, ContentId>>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+        id?: ContentId | undefined;
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+        id?: ContentId | undefined;
+    }>, undefined, EntryConflictResponse>;
+    readonly resolveEntry: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+        entryPath: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+    }>, z.ZodObject<{
+        /** The content id the record names the entry by. */
+        id: z.ZodType<ContentId, z.ZodTypeDef, ContentId>;
+        /** The merge that last changed the record, as the conflict was shown. */
+        mergeSha: z.ZodString;
+        /**
+         * `keep`: leave the branch as it is, for any kind; `delete`: delete the entry the latest
+         * version deleted (`deleted-on-base`); `restore`: put back the entry the branch deleted, as the
+         * latest version has it (`deleted-on-branch`); `use-latest`: replace an entry that can't be merged
+         * field by field with the latest version (`unreadable`).
+         */
+        choice: z.ZodEnum<["keep", "delete", "restore", "use-latest"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: string & {
+            readonly __brand: "ContentId";
+        };
+        mergeSha: string;
+        choice: "delete" | "restore" | "keep" | "use-latest";
+    }, {
+        id: string & {
+            readonly __brand: "ContentId";
+        };
+        mergeSha: string;
+        choice: "delete" | "restore" | "keep" | "use-latest";
+    }>, ResolveEntryConflictResponse>;
+};
+export {};