@zackbart/connecta 0.25.0 → 0.26.0

package/dist/artifacts/operations.d.ts

@@ -0,0 +1,195 @@
+import { type CheckContext } from "./validate.js";
+import type { ArtifactActor, ArtifactHeadRecord, ArtifactIssue, ArtifactKind, ArtifactStore, ArtifactValidation, ArtifactVersionRecord, ArtifactRefreshSchedule, ArtifactRunRecord } from "./types.js";
+type ArtifactFailureCode = "conflict" | "invalid_args" | "not_found" | "unavailable";
+export interface ArtifactFailure {
+    ok: false;
+    code: ArtifactFailureCode;
+    message: string;
+    /** On a conflict: where each stream stands now. */
+    current?: Record<string, number>;
+    /** On invalid content: what validation found. */
+    validation?: ArtifactValidation;
+}
+type Result<T> = ({
+    ok: true;
+} & T) | ArtifactFailure;
+/**
+ * A deployment's render check, bound to one call: it gets the page as the
+ * write would leave it — the prospective head, its source, and every live
+ * document's stored JSON — and answers with warnings or a failure.
+ */
+export type RenderPage = (page: {
+    id: string;
+    head: ArtifactHeadRecord;
+    source: string;
+    data: Record<string, string>;
+}) => Promise<{
+    ok: true;
+    warnings: ArtifactIssue[];
+} | ArtifactFailure>;
+export interface OperationsOptions extends CheckContext {
+    store: ArtifactStore;
+    /** Epoch milliseconds. Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * A validation refusal. The message lists every finding — each names a line
+ * and a fix — so an agent can repair the page from the error alone; it stays
+ * under the guest error bound, pointing at `validate_artifact` for the rest.
+ */
+export declare function invalidContent(what: string, validation: ArtifactValidation): ArtifactFailure;
+export interface PatchEdit {
+    find: string;
+    replace: string;
+}
+export declare class ArtifactOperations {
+    #private;
+    constructor(options: OperationsOptions);
+    get store(): ArtifactStore;
+    get context(): CheckContext;
+    create(input: {
+        id: string;
+        title: string;
+        kind: ArtifactKind;
+        source: string;
+        documents?: Record<string, unknown>;
+        by: ArtifactActor;
+        render?: RenderPage;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        warnings: ArtifactIssue[];
+    }>>;
+    update(input: {
+        id: string;
+        baseVersion: number;
+        source: string;
+        title?: string;
+        by: ArtifactActor;
+        render?: RenderPage;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        warnings: ArtifactIssue[];
+    }>>;
+    patch(input: {
+        id: string;
+        baseVersion: number;
+        edits: PatchEdit[];
+        by: ArtifactActor;
+        render?: RenderPage;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        warnings: ArtifactIssue[];
+    }>>;
+    setDocuments(input: {
+        id: string;
+        documents: Record<string, {
+            baseVersion: number;
+            value: unknown;
+        }>;
+        by: ArtifactActor;
+        op?: "set" | "refresh";
+        runId?: string;
+        /** A refresh result may publish only while its own claim still holds. */
+        programVersion?: number;
+        render?: RenderPage;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        warnings: ArtifactIssue[];
+    }>>;
+    /** Configure one versioned program. A concurrent document edit is absorbed. */
+    setRefresh(input: {
+        id: string;
+        program: string;
+        document: string;
+        schedule: ArtifactRefreshSchedule;
+        baseVersion: number;
+        by: ArtifactActor;
+        owner?: {
+            identity: import("../types.js").AuthenticatedIdentity;
+            pool?: string;
+        };
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+    }>>;
+    refreshConfig(id: string): Promise<Result<{
+        head: ArtifactHeadRecord;
+        program: string | undefined;
+    }>>;
+    claimRefresh(id: string, runId: string, trigger: ArtifactRunRecord["trigger"], dueOnly: boolean, claimMs: number): Promise<Result<{
+        head: ArtifactHeadRecord;
+        program: string;
+        run: ArtifactRunRecord;
+    }> | {
+        ok: false;
+        skipped: true;
+    }>;
+    finishRefresh(id: string, run: ArtifactRunRecord): Promise<void>;
+    rollback(input: {
+        id: string;
+        target: "view" | "document";
+        name?: string;
+        version: number;
+        baseVersion: number;
+        by: ArtifactActor;
+        render?: RenderPage;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        warnings: ArtifactIssue[];
+    }>>;
+    setArchived(input: {
+        id: string;
+        baseRevision: number;
+        archived: boolean;
+        by: ArtifactActor;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        warnings: ArtifactIssue[];
+    }>>;
+    get(id: string, options?: {
+        version?: number;
+        includeSource?: boolean;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        view: ArtifactVersionRecord;
+        source?: string;
+        history: ArtifactVersionRecord[];
+    }>>;
+    getDocument(id: string, name: string, version?: number): Promise<Result<{
+        head: ArtifactHeadRecord;
+        record: ArtifactVersionRecord;
+        value: unknown;
+        history: ArtifactVersionRecord[];
+    }>>;
+    /** The page a viewer renders: a view version and exactly the documents asked for (all current ones by default). */
+    page(id: string, pin?: {
+        view?: number;
+        documents?: Record<string, number>;
+    }): Promise<Result<{
+        head: ArtifactHeadRecord;
+        view: ArtifactVersionRecord;
+        source: string;
+        documents: Record<string, {
+            record: ArtifactVersionRecord;
+            value: unknown;
+        }>;
+    }>>;
+    list(options: {
+        query?: string;
+        includeArchived?: boolean;
+        limit: number;
+        cursor?: string;
+    }): Promise<Result<{
+        items: {
+            id: string;
+            head: ArtifactHeadRecord;
+        }[];
+        nextCursor?: string;
+    }>>;
+}
+/**
+ * Apply every edit to `source` at once, each against the original text: every
+ * `find` must occur exactly once and no two may overlap. Returns the new text,
+ * or every reason it could not.
+ */
+export declare function applyPatch(source: string, edits: readonly PatchEdit[]): string | string[];
+export {};