@contentrail/publisher 0.0.0-stage → 0.2.0

package/dist/providers/r2.js

@@ -0,0 +1,305 @@
+import { createHash } from "node:crypto";
+import { PublishConflictError, PublishError } from "../errors.js";
+import { assertSafeSegment } from "../paths.js";
+function safeIdempotencySegment(key) {
+    return createHash("sha256").update(key).digest("hex").slice(0, 32);
+}
+function prefixKey(prefix, ...parts) {
+    const base = prefix.replaceAll(/^\/+|\/+$/g, "");
+    for (const part of parts) {
+        assertSafeSegment(part, "storage key");
+    }
+    return [base, ...parts].filter((part) => part !== "").join("/");
+}
+/**
+ * R2 / object-storage provider.
+ * Writes immutable version snapshots, then conditionally updates `current.json`.
+ */
+export function createR2PublishProvider(options) {
+    if (options.hasCredential === false) {
+        throw new PublishError("CREDENTIALS", "R2 publish provider requires a configured server-side credential.");
+    }
+    const { client, keyPrefix } = options;
+    const currentKey = (siteId, collection) => prefixKey(keyPrefix, siteId, "collections", collection, "current.json");
+    const versionPrefix = (siteId, collection, version) => prefixKey(keyPrefix, siteId, "collections", collection, "versions", version);
+    const idempotencyKeyPath = (siteId, collection, idempotencyKey) => prefixKey(keyPrefix, siteId, "collections", collection, "idempotency", safeIdempotencySegment(idempotencyKey));
+    return {
+        kind: "r2",
+        async getActiveVersion(siteId, collection) {
+            const current = await client.getObject(currentKey(siteId, collection));
+            if (current === null) {
+                return null;
+            }
+            return JSON.parse(current.body).version;
+        },
+        async readActiveContent(siteId, collection) {
+            const currentObject = await client.getObject(currentKey(siteId, collection));
+            if (currentObject === null) {
+                return null;
+            }
+            const current = JSON.parse(currentObject.body);
+            const base = versionPrefix(siteId, collection, current.version);
+            const manifestObject = await client.getObject(`${base}/manifest.json`);
+            if (manifestObject === null) {
+                throw new PublishError("NOT_FOUND", `Active version "${current.version}" is missing its manifest.`, { siteId, collection });
+            }
+            const manifest = JSON.parse(manifestObject.body);
+            const entries = [];
+            for (const entryId of manifest.entryIds) {
+                const object = await client.getObject(`${base}/entries/${entryId}.json`);
+                if (object === null) {
+                    throw new PublishError("NOT_FOUND", `Active version "${current.version}" is missing entry "${entryId}".`, { siteId, collection });
+                }
+                entries.push({ id: entryId, data: JSON.parse(object.body) });
+            }
+            const snapshot = {
+                version: manifest.version,
+                publicationId: manifest.publicationId,
+                createdAt: manifest.createdAt,
+                entries,
+            };
+            return snapshot;
+        },
+        async readIdempotentResult(siteId, collection, idempotencyKey) {
+            const object = await client.getObject(idempotencyKeyPath(siteId, collection, idempotencyKey));
+            if (object === null) {
+                return null;
+            }
+            return JSON.parse(object.body);
+        },
+        async recoverIdempotentPublish(input) {
+            const prior = await this.readIdempotentResult(input.siteId, input.collection, input.idempotencyKey);
+            if (prior !== null) {
+                return prior;
+            }
+            const active = await this.getActiveVersion(input.siteId, input.collection);
+            if (active !== input.version) {
+                return null;
+            }
+            const manifestObject = await client.getObject(`${versionPrefix(input.siteId, input.collection, input.version)}/manifest.json`);
+            if (manifestObject === null) {
+                return null;
+            }
+            const manifest = JSON.parse(manifestObject.body);
+            const current = await client.getObject(currentKey(input.siteId, input.collection));
+            const result = {
+                success: true,
+                publicationId: input.publicationId,
+                version: input.version,
+                previousVersion: manifest.previousVersion,
+                manifest,
+                provider: {
+                    kind: "r2",
+                    revision: current?.etag ?? input.version,
+                },
+                rebuild: { state: "not_requested" },
+                idempotentReplay: true,
+            };
+            await client.putObject(idempotencyKeyPath(input.siteId, input.collection, input.idempotencyKey), `${JSON.stringify(result, null, 2)}\n`);
+            return result;
+        },
+        async publishSnapshot(input) {
+            const currentObject = await client.getObject(currentKey(input.siteId, input.collection));
+            const current = currentObject
+                ? JSON.parse(currentObject.body)
+                : null;
+            const activeVersion = current?.version ?? null;
+            if (activeVersion !== input.expectedVersion) {
+                throw new PublishConflictError("R2 current pointer does not match expectedVersion.", {
+                    siteId: input.siteId,
+                    collection: input.collection,
+                    publicationId: input.publicationId,
+                    currentVersion: activeVersion,
+                    expectedVersion: input.expectedVersion,
+                });
+            }
+            const createdAt = new Date().toISOString();
+            const manifest = {
+                siteId: input.siteId,
+                collection: input.collection,
+                publicationId: input.publicationId,
+                version: input.version,
+                previousVersion: input.previousVersion,
+                createdAt,
+                entryIds: input.entries.map((entry) => entry.id),
+            };
+            const base = versionPrefix(input.siteId, input.collection, input.version);
+            try {
+                for (const entry of input.entries) {
+                    await client.putObject(`${base}/entries/${entry.id}.json`, `${JSON.stringify(entry.data, null, 2)}\n`);
+                }
+                await client.putObject(`${base}/manifest.json`, `${JSON.stringify(manifest, null, 2)}\n`);
+            }
+            catch (error) {
+                if (isTimeout(error)) {
+                    throw new PublishError("PARTIAL_FAILURE", "R2 timed out while writing version snapshot. Current pointer was not updated.", {
+                        siteId: input.siteId,
+                        collection: input.collection,
+                        publicationId: input.publicationId,
+                        cause: error,
+                    });
+                }
+                throw new PublishError("PARTIAL_FAILURE", "R2 failed while writing version snapshot. Current pointer was not updated.", {
+                    siteId: input.siteId,
+                    collection: input.collection,
+                    publicationId: input.publicationId,
+                    cause: error,
+                });
+            }
+            const pointer = {
+                version: input.version,
+                publicationId: input.publicationId,
+                updatedAt: createdAt,
+            };
+            // Activation uses storage-level conditional writes (S3/R2 If-Match /
+            // If-None-Match mapped by the injected client). Not an unconditional put.
+            let put;
+            try {
+                put =
+                    currentObject === null
+                        ? await client.putObject(currentKey(input.siteId, input.collection), `${JSON.stringify(pointer, null, 2)}\n`, { ifNoneMatch: "*" })
+                        : await client.putObject(currentKey(input.siteId, input.collection), `${JSON.stringify(pointer, null, 2)}\n`, { ifMatch: currentObject.etag });
+            }
+            catch (error) {
+                if (isConflict(error)) {
+                    throw new PublishConflictError("Concurrent R2 activation detected; snapshot may remain unreferenced.", {
+                        siteId: input.siteId,
+                        collection: input.collection,
+                        publicationId: input.publicationId,
+                        cause: error,
+                    });
+                }
+                if (isTimeout(error)) {
+                    throw new PublishError("PARTIAL_FAILURE", "R2 timed out during activation. Snapshot may exist without becoming current.", {
+                        siteId: input.siteId,
+                        collection: input.collection,
+                        publicationId: input.publicationId,
+                        cause: error,
+                    });
+                }
+                throw new PublishError("PROVIDER", "R2 activation failed.", {
+                    siteId: input.siteId,
+                    collection: input.collection,
+                    publicationId: input.publicationId,
+                    cause: error,
+                });
+            }
+            const result = {
+                success: true,
+                publicationId: input.publicationId,
+                version: input.version,
+                previousVersion: input.previousVersion,
+                manifest,
+                provider: { kind: "r2", revision: put.etag },
+                rebuild: { state: "not_requested" },
+                idempotentReplay: false,
+            };
+            if (input.idempotencyKey !== undefined) {
+                try {
+                    await client.putObject(idempotencyKeyPath(input.siteId, input.collection, input.idempotencyKey), `${JSON.stringify(result, null, 2)}\n`);
+                }
+                catch {
+                    // Activation already succeeded. Retries recover via recoverIdempotentPublish.
+                }
+            }
+            return result;
+        },
+        async listVersions(siteId, collection) {
+            const active = await this.getActiveVersion(siteId, collection);
+            const prefix = prefixKey(keyPrefix, siteId, "collections", collection, "versions");
+            const keys = await client.listKeys(`${prefix}/`);
+            const manifests = new Set();
+            for (const key of keys) {
+                if (key.endsWith("/manifest.json")) {
+                    manifests.add(key);
+                }
+            }
+            const summaries = [];
+            for (const key of manifests) {
+                const object = await client.getObject(key);
+                if (object === null) {
+                    continue;
+                }
+                const manifest = JSON.parse(object.body);
+                summaries.push({
+                    version: manifest.version,
+                    publicationId: manifest.publicationId,
+                    createdAt: manifest.createdAt,
+                    active: manifest.version === active,
+                });
+            }
+            return summaries.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        },
+        async rollback(input) {
+            const currentObject = await client.getObject(currentKey(input.siteId, input.collection));
+            const current = currentObject
+                ? JSON.parse(currentObject.body)
+                : null;
+            const activeVersion = current?.version ?? null;
+            if (activeVersion !== input.expectedVersion) {
+                throw new PublishConflictError("Rollback expectedVersion does not match R2 current pointer.", {
+                    siteId: input.siteId,
+                    collection: input.collection,
+                    currentVersion: activeVersion,
+                    expectedVersion: input.expectedVersion,
+                });
+            }
+            const manifestObject = await client.getObject(`${versionPrefix(input.siteId, input.collection, input.targetVersion)}/manifest.json`);
+            if (manifestObject === null) {
+                throw new PublishError("NOT_FOUND", `Unknown publication version "${input.targetVersion}".`, { siteId: input.siteId, collection: input.collection });
+            }
+            const manifest = JSON.parse(manifestObject.body);
+            const publicationId = input.publicationId ?? manifest.publicationId;
+            const updatedAt = new Date().toISOString();
+            const pointer = {
+                version: input.targetVersion,
+                publicationId,
+                updatedAt,
+            };
+            try {
+                const put = currentObject === null
+                    ? await client.putObject(currentKey(input.siteId, input.collection), `${JSON.stringify(pointer, null, 2)}\n`, { ifNoneMatch: "*" })
+                    : await client.putObject(currentKey(input.siteId, input.collection), `${JSON.stringify(pointer, null, 2)}\n`, { ifMatch: currentObject.etag });
+                return {
+                    success: true,
+                    publicationId,
+                    version: input.targetVersion,
+                    previousVersion: activeVersion,
+                    manifest: {
+                        ...manifest,
+                        previousVersion: activeVersion,
+                        publicationId,
+                    },
+                    provider: { kind: "r2", revision: put.etag },
+                    rebuild: { state: "not_requested" },
+                    idempotentReplay: false,
+                };
+            }
+            catch (error) {
+                if (isConflict(error)) {
+                    throw new PublishConflictError("Concurrent R2 update detected during rollback.", {
+                        siteId: input.siteId,
+                        collection: input.collection,
+                        publicationId,
+                        cause: error,
+                    });
+                }
+                throw new PublishError("PROVIDER", "R2 rollback failed.", {
+                    siteId: input.siteId,
+                    collection: input.collection,
+                    publicationId,
+                    cause: error,
+                });
+            }
+        },
+    };
+}
+function isConflict(error) {
+    return (error instanceof Error &&
+        (error.message === "CONFLICT" ||
+            /conflict|precondition/i.test(error.message)));
+}
+function isTimeout(error) {
+    return error instanceof Error && /timeout|timed out/i.test(error.message);
+}
+//# sourceMappingURL=r2.js.map

package/dist/providers/r2.js.map

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

package/dist/rebuild.d.ts

@@ -0,0 +1,34 @@
+import type { RebuildStatus } from "./types.js";
+export interface RebuildHookClient {
+    /**
+     * POSTs to a configured deploy hook. Must not log the secret URL.
+     * Throws Error("timeout") or Error("failed") for simulated failures.
+     */
+    trigger(payload: {
+        siteId: string;
+        collection: string;
+        version: string;
+        publicationId: string;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        detail: string;
+    }>;
+}
+export interface RebuildHookOptions {
+    readonly client: RebuildHookClient;
+    readonly hasSecret?: boolean;
+}
+/**
+ * Optional rebuild trigger. Publication success does not imply rebuild success.
+ */
+export declare function createRebuildHook(options: RebuildHookOptions): {
+    trigger(input: {
+        siteId: string;
+        collection: string;
+        version: string;
+        publicationId: string;
+    }): Promise<RebuildStatus>;
+};
+//# sourceMappingURL=rebuild.d.ts.map

package/dist/rebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuild.d.ts","sourceRoot":"","sources":["../src/rebuild.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG;IAC9D,OAAO,CAAC,KAAK,EAAE;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5B,CAuDA"}

package/dist/rebuild.js

@@ -0,0 +1,51 @@
+import { createHash, randomUUID } from "node:crypto";
+import { PublishError } from "./errors.js";
+/**
+ * Optional rebuild trigger. Publication success does not imply rebuild success.
+ */
+export function createRebuildHook(options) {
+    if (options.hasSecret === false) {
+        throw new PublishError("CREDENTIALS", "Rebuild hook requires a configured server-side secret.");
+    }
+    const seen = new Set();
+    return {
+        async trigger(input) {
+            const dedupe = createHash("sha256")
+                .update(`${input.siteId}:${input.collection}:${input.version}:${input.publicationId}`)
+                .digest("hex");
+            if (seen.has(dedupe)) {
+                return {
+                    state: "pending",
+                    triggerId: dedupe.slice(0, 12),
+                    detail: "Duplicate rebuild trigger suppressed; prior request retained.",
+                };
+            }
+            try {
+                const response = await options.client.trigger(input);
+                const triggerId = randomUUID();
+                seen.add(dedupe);
+                if (!response.ok) {
+                    return {
+                        state: "failed",
+                        triggerId,
+                        detail: response.detail,
+                    };
+                }
+                return {
+                    state: "pending",
+                    triggerId,
+                    detail: "Rebuild hook accepted. Content publication succeeded independently of deploy completion.",
+                };
+            }
+            catch (error) {
+                return {
+                    state: "failed",
+                    detail: error instanceof Error
+                        ? error.message
+                        : "Rebuild hook failed after successful publication.",
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=rebuild.js.map

package/dist/rebuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuild.js","sourceRoot":"","sources":["../src/rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAqB3C;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAQ3D,IAAI,OAAO,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;QAChC,MAAM,IAAI,YAAY,CACpB,aAAa,EACb,wDAAwD,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;iBAChC,MAAM,CACL,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,aAAa,EAAE,CAC9E;iBACA,MAAM,CAAC,KAAK,CAAC,CAAC;YAEjB,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrB,OAAO;oBACL,KAAK,EAAE,SAAS;oBAChB,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;oBAC9B,MAAM,EACJ,+DAA+D;iBAClE,CAAC;YACJ,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACrD,MAAM,SAAS,GAAG,UAAU,EAAE,CAAC;gBAC/B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBACjB,OAAO;wBACL,KAAK,EAAE,QAAQ;wBACf,SAAS;wBACT,MAAM,EAAE,QAAQ,CAAC,MAAM;qBACxB,CAAC;gBACJ,CAAC;gBACD,OAAO;oBACL,KAAK,EAAE,SAAS;oBAChB,SAAS;oBACT,MAAM,EACJ,0FAA0F;iBAC7F,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO;oBACL,KAAK,EAAE,QAAQ;oBACf,MAAM,EACJ,KAAK,YAAY,KAAK;wBACpB,CAAC,CAAC,KAAK,CAAC,OAAO;wBACf,CAAC,CAAC,mDAAmD;iBAC1D,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+import type { ContentCollection, InferEntry } from "@contentrail/core";
+export type RebuildState = "not_requested" | "pending" | "succeeded" | "failed";
+export interface PublishEntryInput {
+    readonly id: string;
+    readonly data: unknown;
+}
+export interface PublishRequest<TCollection extends ContentCollection = ContentCollection> {
+    readonly siteId: string;
+    readonly collection: TCollection;
+    readonly entries: ReadonlyArray<PublishEntryInput>;
+    /**
+     * Required previous version. Use `null` when publishing the first version.
+     * Omit only when the provider allows force (not supported in Phase 3).
+     */
+    readonly expectedVersion: string | null;
+    readonly publicationId?: string;
+    readonly idempotencyKey?: string;
+    readonly message?: string;
+}
+export interface PublicationManifest {
+    readonly siteId: string;
+    readonly collection: string;
+    readonly publicationId: string;
+    readonly version: string;
+    readonly previousVersion: string | null;
+    readonly createdAt: string;
+    readonly entryIds: readonly string[];
+}
+export interface RebuildStatus {
+    readonly state: RebuildState;
+    readonly triggerId?: string;
+    readonly detail?: string;
+}
+export interface PublishSuccess {
+    readonly success: true;
+    readonly publicationId: string;
+    readonly version: string;
+    readonly previousVersion: string | null;
+    readonly manifest: PublicationManifest;
+    readonly provider: {
+        readonly kind: "git" | "r2";
+        readonly revision: string;
+    };
+    readonly rebuild: RebuildStatus;
+    readonly idempotentReplay: boolean;
+}
+export type PublishResult = PublishSuccess;
+export interface PublicationSummary {
+    readonly version: string;
+    readonly publicationId: string;
+    readonly createdAt: string;
+    readonly active: boolean;
+}
+/** Active published snapshot for editor/API reads (ADR 018). */
+export interface ActiveContentSnapshot {
+    readonly version: string;
+    readonly publicationId: string;
+    readonly createdAt: string;
+    readonly entries: ReadonlyArray<{
+        id: string;
+        data: unknown;
+    }>;
+}
+export interface PublishProvider {
+    readonly kind: "git" | "r2";
+    getActiveVersion(siteId: string, collection: string): Promise<string | null>;
+    /**
+     * Load entry bodies for the currently active publication.
+     * Returns `null` when no version is active.
+     */
+    readActiveContent(siteId: string, collection: string): Promise<ActiveContentSnapshot | null>;
+    readIdempotentResult(siteId: string, collection: string, idempotencyKey: string): Promise<PublishSuccess | null>;
+    /**
+     * After a conflict or partial failure on a keyed request, return a completed
+     * result when this operation already activated (or was recorded).
+     */
+    recoverIdempotentPublish(input: {
+        siteId: string;
+        collection: string;
+        idempotencyKey: string;
+        publicationId: string;
+        version: string;
+    }): Promise<PublishSuccess | null>;
+    publishSnapshot(input: {
+        siteId: string;
+        collection: string;
+        publicationId: string;
+        version: string;
+        previousVersion: string | null;
+        expectedVersion: string | null;
+        entries: ReadonlyArray<{
+            id: string;
+            data: unknown;
+        }>;
+        message?: string;
+        idempotencyKey?: string;
+    }): Promise<PublishSuccess>;
+    listVersions(siteId: string, collection: string): Promise<PublicationSummary[]>;
+    rollback(input: {
+        siteId: string;
+        collection: string;
+        targetVersion: string;
+        expectedVersion: string | null;
+        publicationId?: string;
+    }): Promise<PublishSuccess>;
+}
+export type ValidatedEntries<TCollection extends ContentCollection> = Array<{
+    id: string;
+    data: InferEntry<TCollection>;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/version.d.ts

@@ -0,0 +1,13 @@
+export declare function createPublicationId(explicit?: string): string;
+/** Stable publication id derived from an idempotency key so retries share one operation. */
+export declare function publicationIdFromIdempotencyKey(idempotencyKey: string): string;
+export declare function createContentVersion(input: {
+    siteId: string;
+    collection: string;
+    publicationId: string;
+    entries: ReadonlyArray<{
+        id: string;
+        data: unknown;
+    }>;
+}): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAU7D;AAED,4FAA4F;AAC5F,wBAAgB,+BAA+B,CAC7C,cAAc,EAAE,MAAM,GACrB,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvD,GAAG,MAAM,CAUT"}

package/dist/version.js

@@ -0,0 +1,26 @@
+import { createHash, randomUUID } from "node:crypto";
+export function createPublicationId(explicit) {
+    if (explicit !== undefined) {
+        if (explicit.trim() === "") {
+            throw new Error("publicationId must be a non-empty string when provided.");
+        }
+        return explicit;
+    }
+    return randomUUID();
+}
+/** Stable publication id derived from an idempotency key so retries share one operation. */
+export function publicationIdFromIdempotencyKey(idempotencyKey) {
+    return `idem-${createHash("sha256").update(idempotencyKey).digest("hex").slice(0, 32)}`;
+}
+export function createContentVersion(input) {
+    const canonical = JSON.stringify({
+        siteId: input.siteId,
+        collection: input.collection,
+        publicationId: input.publicationId,
+        entries: [...input.entries]
+            .map((entry) => ({ id: entry.id, data: entry.data }))
+            .sort((a, b) => a.id.localeCompare(b.id)),
+    });
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,yDAAyD,CAC1D,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,+BAA+B,CAC7C,cAAsB;IAEtB,OAAO,QAAQ,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAKpC;IACC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAC/B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,OAAO,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;aACxB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;aACpD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;KAC5C,CAAC,CAAC;IACH,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@contentrail/publisher",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "description": "Server-only ContentRail publishing contracts, Git and R2 providers, and rebuild hooks.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "node": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@contentrail/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "5.9.3",
+    "zod": "4.6.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hridhin-k/contentrail.git",
+    "directory": "packages/publisher"
+  },
+  "bugs": {
+    "url": "https://github.com/Hridhin-k/contentrail/issues"
+  },
+  "homepage": "https://github.com/Hridhin-k/contentrail#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && tsc -p tsconfig.test.json && node --test test-dist/**/*.test.js"
+  }
 }