@zackbart/connecta 0.25.0 → 0.26.1

package/dist/artifacts/module.js

@@ -0,0 +1,60 @@
+// artifacts(): the typed module a deployment passes as `ConnectaConfig.artifacts`.
+import { artifactsConnector } from "./connector.js";
+import { ArtifactOperations } from "./operations.js";
+import { artifactRoutes } from "./routes.js";
+import { ArtifactRefreshService } from "./refresh.js";
+import { resolveAllowlist, resolveLimits } from "./validate.js";
+const STORE_METHODS = [
+    "head",
+    "swapHead",
+    "heads",
+    "putBody",
+    "body",
+    "putVersion",
+    "versions",
+    "putRun",
+    "runs",
+    "refreshScanCursor",
+    "setRefreshScanCursor",
+];
+const OPTIONS = new Set(["store", "allowlist", "limits", "renderCheck"]);
+export function artifacts(options) {
+    if (!options || typeof options !== "object") {
+        throw new TypeError("artifacts() needs options with a store");
+    }
+    for (const key of Object.keys(options)) {
+        if (!OPTIONS.has(key))
+            throw new TypeError(`artifacts(): unknown option "${key}"`);
+    }
+    const store = options.store;
+    if (!store ||
+        typeof store !== "object" ||
+        STORE_METHODS.some((method) => typeof store[method] !== "function")) {
+        throw new TypeError("artifacts(): store must be an ArtifactStore, e.g. kvArtifactStore(storage)");
+    }
+    if (options.renderCheck !== undefined && typeof options.renderCheck !== "function") {
+        throw new TypeError("artifacts(): renderCheck must be a function");
+    }
+    const allowlist = resolveAllowlist(options.allowlist);
+    const limits = resolveLimits(options.limits);
+    const operations = new ArtifactOperations({
+        store: options.store,
+        allowlist,
+        limits,
+    });
+    const refresh = new ArtifactRefreshService(operations);
+    const connector = artifactsConnector({
+        operations,
+        refresh,
+        allowlist,
+        limits,
+        ...(options.renderCheck ? { renderCheck: options.renderCheck } : {}),
+    });
+    return Object.freeze({
+        connector,
+        handle: artifactRoutes({ operations, allowlist }),
+        bindRefresh: (runtime) => refresh.bind(runtime),
+        refresh: (id, by) => refresh.run(id, { manual: by }),
+        runDue: () => refresh.runDue(),
+    });
+}

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