@scalemule/news-publication 0.0.7

package/dist/snapshot-BS4hn1dk.d.cts

@@ -0,0 +1,234 @@
+/** Public identity and behavior for one local news site. */
+type NewsLayoutId = "broadsheet" | (string & {});
+declare const FEATURE_NAMES: readonly ["smile", "comments", "chat", "jobs", "classifieds", "referrals", "coupons"];
+type FeatureName = (typeof FEATURE_NAMES)[number];
+type FeatureFlags = Partial<Record<FeatureName, boolean>>;
+type PublicationTheme = {
+    accent: string;
+    ink: string;
+    paper: string;
+    sponsor: string;
+};
+type CouponOffer = {
+    code: string;
+    label: string;
+    /** Percent off the plan price, 0–100. */
+    percentOff?: number;
+    amountOffCents?: number;
+    months?: number;
+    planSlug?: string;
+};
+type ReferralSettings = {
+    enabled: boolean;
+    /** Query parameter read on the landing URL. Default `ref`. */
+    queryParam: string;
+};
+type CouponSettings = {
+    enabled: boolean;
+    offers: CouponOffer[];
+    /** Site-owned matcher. Used only when coupons are enabled. */
+    resolve?: (code: string, offers: CouponOffer[]) => CouponOffer | null;
+};
+/** Named mounts a paper renders itself. The package records them; it does not render UI. */
+type PublicationModules = {
+    home?: string[];
+    articleEnd?: string[];
+};
+type PublicationInput = {
+    slug: string;
+    name: string;
+    masthead: string[];
+    region: string;
+    regionLabel: string;
+    towns: string[];
+    nearbyTowns?: string[];
+    sections?: string[];
+    description: string;
+    tagline?: string;
+    briefTitle?: string;
+    parent?: boolean;
+    /** Default presentation. Crawlers always receive this layout. */
+    layout?: NewsLayoutId;
+    /** Layouts a reader may choose. The default is always included. */
+    layouts?: NewsLayoutId[];
+    features?: FeatureFlags;
+    theme?: Partial<PublicationTheme>;
+    referrals?: Partial<ReferralSettings>;
+    coupons?: Partial<Omit<CouponSettings, "enabled">> & {
+        enabled?: boolean;
+    };
+    modules?: PublicationModules;
+    /** Extra tag rule owned by the paper, such as Walnut Creek neighborhood keywords. */
+    matchTag?: (article: NewsItem, tag: string) => boolean;
+};
+type NewsPublication = {
+    slug: string;
+    name: string;
+    masthead: string[];
+    region: string;
+    regionLabel: string;
+    towns: string[];
+    nearbyTowns: string[];
+    sections: string[];
+    description: string;
+    tagline: string;
+    briefTitle: string;
+    parent: boolean;
+    layout: NewsLayoutId;
+    layouts: NewsLayoutId[];
+    features: Record<FeatureName, boolean>;
+    theme: PublicationTheme;
+    referrals: ReferralSettings;
+    coupons: CouponSettings;
+    modules: PublicationModules;
+    matchTag?: (article: NewsItem, tag: string) => boolean;
+};
+type TagRef = {
+    id?: string;
+    name: string;
+    slug: string;
+};
+type CategoryRef = {
+    id?: string;
+    name: string;
+    slug: string;
+};
+/** Feed row shape used by Walnut Creek Times. */
+type NewsItem = {
+    id: string;
+    slug: string;
+    title: string;
+    excerpt: string | null;
+    cover_image_url: string | null;
+    published_at: string;
+    updated_at: string;
+    reading_time_minutes: number;
+    no_index: boolean;
+    section: string | null;
+    author_name: string | null;
+    canonical_url?: string | null;
+    tags?: TagRef[];
+    categories?: CategoryRef[];
+};
+type NewsFeed = {
+    items: NewsItem[];
+    next_cursor: string | null;
+    publication: {
+        name: string;
+    };
+};
+type CoverImageMetadata = {
+    alt?: string;
+    focal_point?: {
+        x: number;
+        y: number;
+    };
+    ai_generated?: boolean;
+    label?: string;
+    caption?: string;
+    attribution?: string;
+    credit?: string;
+};
+type ArticleCitation = {
+    url: string;
+    title?: string;
+    publisher?: string;
+};
+type NewsArticle = NewsItem & {
+    content_html: string;
+    subtitle?: string;
+    seo_title?: string;
+    seo_description?: string;
+    og_image_url?: string;
+    audio?: {
+        url?: string;
+        duration_ms?: number | null;
+    };
+    metadata?: {
+        cover_image?: CoverImageMetadata;
+        citations?: ArticleCitation[];
+        resources?: {
+            kind: string;
+            url: string;
+            caption: string;
+            attribution: string;
+            ai_generated: boolean;
+        }[];
+    };
+};
+type StoryDisplay = {
+    display_title?: string;
+    deck?: string;
+    brief?: string;
+    towns?: string[];
+};
+type NearbyUpdate = {
+    slug: string;
+    title: string;
+    summary: string;
+    town: string;
+    starts: string;
+    ends?: string;
+};
+type HomepageSelection = {
+    lead_slug?: string;
+    secondary_slugs?: string[];
+    brief_slugs?: string[];
+    /** ISO timestamp: pinned ordering expires, never silently becomes permanent. */
+    pinned_until?: string;
+    stories?: Record<string, StoryDisplay>;
+    nearby?: NearbyUpdate[];
+};
+type EditorialSection = {
+    name: string;
+    label: string;
+    id: string;
+    items: NewsItem[];
+};
+
+/**
+ * Serializable application config. Code hooks (`matchTag`, `coupons.resolve`)
+ * stay in the site and are attached after the snapshot loads.
+ */
+type PublicationRecord = Omit<PublicationInput, "matchTag" | "coupons"> & {
+    coupons?: Omit<NonNullable<PublicationInput["coupons"]>, "resolve">;
+};
+/** Last config the application accepted. Age never invalidates it. */
+type PublicationSnapshot = {
+    version: 1;
+    syncedAt: string;
+    record: PublicationRecord;
+};
+type SnapshotHooks = {
+    matchTag?: PublicationInput["matchTag"];
+    resolveCoupon?: NonNullable<PublicationInput["coupons"]>["resolve"];
+};
+type SyncSource = "fresh" | "retained";
+type SyncedPublication = {
+    publication: NewsPublication;
+    snapshot: PublicationSnapshot;
+    source: SyncSource;
+    /** How long this snapshot has been the one on disk. Zero for a fresh sync. */
+    ageMs: number;
+};
+declare function publicationRecord(publication: NewsPublication): PublicationRecord;
+declare function snapshotFromRecord(record: PublicationRecord, syncedAt?: string): PublicationSnapshot;
+declare function parseSnapshot(raw: string): PublicationSnapshot | null;
+declare function acceptSnapshot(value: unknown): PublicationSnapshot | null;
+/** A remote payload replaces the snapshot only when it is a complete record for this paper. */
+declare function acceptRemoteRecord(value: unknown, expectedSlug?: string): PublicationRecord | null;
+declare function publicationFromSnapshot(snapshot: PublicationSnapshot, hooks?: SnapshotHooks): NewsPublication;
+/**
+ * Fetch the application config. Any failure, timeout, or malformed body keeps
+ * the previous snapshot. Nothing here expires a snapshot because the API was
+ * unreachable for hours or days.
+ */
+declare function syncPublication(input: {
+    previous: PublicationSnapshot | null;
+    fetchRecord: () => Promise<unknown>;
+    expectedSlug?: string;
+    now?: number;
+    hooks?: SnapshotHooks;
+}): Promise<SyncedPublication>;
+
+export { type ArticleCitation as A, type CouponOffer as C, type EditorialSection as E, type FeatureName as F, type HomepageSelection as H, type NewsPublication as N, type PublicationTheme as P, type ReferralSettings as R, type SnapshotHooks as S, type TagRef as T, type PublicationInput as a, type NearbyUpdate as b, type NewsItem as c, type NewsArticle as d, type CategoryRef as e, type CouponSettings as f, type CoverImageMetadata as g, FEATURE_NAMES as h, type FeatureFlags as i, type NewsFeed as j, type NewsLayoutId as k, type PublicationModules as l, type PublicationRecord as m, type PublicationSnapshot as n, type StoryDisplay as o, type SyncSource as p, type SyncedPublication as q, acceptRemoteRecord as r, acceptSnapshot as s, parseSnapshot as t, publicationFromSnapshot as u, publicationRecord as v, snapshotFromRecord as w, syncPublication as x };

package/dist/snapshot-BS4hn1dk.d.ts

@@ -0,0 +1,234 @@
+/** Public identity and behavior for one local news site. */
+type NewsLayoutId = "broadsheet" | (string & {});
+declare const FEATURE_NAMES: readonly ["smile", "comments", "chat", "jobs", "classifieds", "referrals", "coupons"];
+type FeatureName = (typeof FEATURE_NAMES)[number];
+type FeatureFlags = Partial<Record<FeatureName, boolean>>;
+type PublicationTheme = {
+    accent: string;
+    ink: string;
+    paper: string;
+    sponsor: string;
+};
+type CouponOffer = {
+    code: string;
+    label: string;
+    /** Percent off the plan price, 0–100. */
+    percentOff?: number;
+    amountOffCents?: number;
+    months?: number;
+    planSlug?: string;
+};
+type ReferralSettings = {
+    enabled: boolean;
+    /** Query parameter read on the landing URL. Default `ref`. */
+    queryParam: string;
+};
+type CouponSettings = {
+    enabled: boolean;
+    offers: CouponOffer[];
+    /** Site-owned matcher. Used only when coupons are enabled. */
+    resolve?: (code: string, offers: CouponOffer[]) => CouponOffer | null;
+};
+/** Named mounts a paper renders itself. The package records them; it does not render UI. */
+type PublicationModules = {
+    home?: string[];
+    articleEnd?: string[];
+};
+type PublicationInput = {
+    slug: string;
+    name: string;
+    masthead: string[];
+    region: string;
+    regionLabel: string;
+    towns: string[];
+    nearbyTowns?: string[];
+    sections?: string[];
+    description: string;
+    tagline?: string;
+    briefTitle?: string;
+    parent?: boolean;
+    /** Default presentation. Crawlers always receive this layout. */
+    layout?: NewsLayoutId;
+    /** Layouts a reader may choose. The default is always included. */
+    layouts?: NewsLayoutId[];
+    features?: FeatureFlags;
+    theme?: Partial<PublicationTheme>;
+    referrals?: Partial<ReferralSettings>;
+    coupons?: Partial<Omit<CouponSettings, "enabled">> & {
+        enabled?: boolean;
+    };
+    modules?: PublicationModules;
+    /** Extra tag rule owned by the paper, such as Walnut Creek neighborhood keywords. */
+    matchTag?: (article: NewsItem, tag: string) => boolean;
+};
+type NewsPublication = {
+    slug: string;
+    name: string;
+    masthead: string[];
+    region: string;
+    regionLabel: string;
+    towns: string[];
+    nearbyTowns: string[];
+    sections: string[];
+    description: string;
+    tagline: string;
+    briefTitle: string;
+    parent: boolean;
+    layout: NewsLayoutId;
+    layouts: NewsLayoutId[];
+    features: Record<FeatureName, boolean>;
+    theme: PublicationTheme;
+    referrals: ReferralSettings;
+    coupons: CouponSettings;
+    modules: PublicationModules;
+    matchTag?: (article: NewsItem, tag: string) => boolean;
+};
+type TagRef = {
+    id?: string;
+    name: string;
+    slug: string;
+};
+type CategoryRef = {
+    id?: string;
+    name: string;
+    slug: string;
+};
+/** Feed row shape used by Walnut Creek Times. */
+type NewsItem = {
+    id: string;
+    slug: string;
+    title: string;
+    excerpt: string | null;
+    cover_image_url: string | null;
+    published_at: string;
+    updated_at: string;
+    reading_time_minutes: number;
+    no_index: boolean;
+    section: string | null;
+    author_name: string | null;
+    canonical_url?: string | null;
+    tags?: TagRef[];
+    categories?: CategoryRef[];
+};
+type NewsFeed = {
+    items: NewsItem[];
+    next_cursor: string | null;
+    publication: {
+        name: string;
+    };
+};
+type CoverImageMetadata = {
+    alt?: string;
+    focal_point?: {
+        x: number;
+        y: number;
+    };
+    ai_generated?: boolean;
+    label?: string;
+    caption?: string;
+    attribution?: string;
+    credit?: string;
+};
+type ArticleCitation = {
+    url: string;
+    title?: string;
+    publisher?: string;
+};
+type NewsArticle = NewsItem & {
+    content_html: string;
+    subtitle?: string;
+    seo_title?: string;
+    seo_description?: string;
+    og_image_url?: string;
+    audio?: {
+        url?: string;
+        duration_ms?: number | null;
+    };
+    metadata?: {
+        cover_image?: CoverImageMetadata;
+        citations?: ArticleCitation[];
+        resources?: {
+            kind: string;
+            url: string;
+            caption: string;
+            attribution: string;
+            ai_generated: boolean;
+        }[];
+    };
+};
+type StoryDisplay = {
+    display_title?: string;
+    deck?: string;
+    brief?: string;
+    towns?: string[];
+};
+type NearbyUpdate = {
+    slug: string;
+    title: string;
+    summary: string;
+    town: string;
+    starts: string;
+    ends?: string;
+};
+type HomepageSelection = {
+    lead_slug?: string;
+    secondary_slugs?: string[];
+    brief_slugs?: string[];
+    /** ISO timestamp: pinned ordering expires, never silently becomes permanent. */
+    pinned_until?: string;
+    stories?: Record<string, StoryDisplay>;
+    nearby?: NearbyUpdate[];
+};
+type EditorialSection = {
+    name: string;
+    label: string;
+    id: string;
+    items: NewsItem[];
+};
+
+/**
+ * Serializable application config. Code hooks (`matchTag`, `coupons.resolve`)
+ * stay in the site and are attached after the snapshot loads.
+ */
+type PublicationRecord = Omit<PublicationInput, "matchTag" | "coupons"> & {
+    coupons?: Omit<NonNullable<PublicationInput["coupons"]>, "resolve">;
+};
+/** Last config the application accepted. Age never invalidates it. */
+type PublicationSnapshot = {
+    version: 1;
+    syncedAt: string;
+    record: PublicationRecord;
+};
+type SnapshotHooks = {
+    matchTag?: PublicationInput["matchTag"];
+    resolveCoupon?: NonNullable<PublicationInput["coupons"]>["resolve"];
+};
+type SyncSource = "fresh" | "retained";
+type SyncedPublication = {
+    publication: NewsPublication;
+    snapshot: PublicationSnapshot;
+    source: SyncSource;
+    /** How long this snapshot has been the one on disk. Zero for a fresh sync. */
+    ageMs: number;
+};
+declare function publicationRecord(publication: NewsPublication): PublicationRecord;
+declare function snapshotFromRecord(record: PublicationRecord, syncedAt?: string): PublicationSnapshot;
+declare function parseSnapshot(raw: string): PublicationSnapshot | null;
+declare function acceptSnapshot(value: unknown): PublicationSnapshot | null;
+/** A remote payload replaces the snapshot only when it is a complete record for this paper. */
+declare function acceptRemoteRecord(value: unknown, expectedSlug?: string): PublicationRecord | null;
+declare function publicationFromSnapshot(snapshot: PublicationSnapshot, hooks?: SnapshotHooks): NewsPublication;
+/**
+ * Fetch the application config. Any failure, timeout, or malformed body keeps
+ * the previous snapshot. Nothing here expires a snapshot because the API was
+ * unreachable for hours or days.
+ */
+declare function syncPublication(input: {
+    previous: PublicationSnapshot | null;
+    fetchRecord: () => Promise<unknown>;
+    expectedSlug?: string;
+    now?: number;
+    hooks?: SnapshotHooks;
+}): Promise<SyncedPublication>;
+
+export { type ArticleCitation as A, type CouponOffer as C, type EditorialSection as E, type FeatureName as F, type HomepageSelection as H, type NewsPublication as N, type PublicationTheme as P, type ReferralSettings as R, type SnapshotHooks as S, type TagRef as T, type PublicationInput as a, type NearbyUpdate as b, type NewsItem as c, type NewsArticle as d, type CategoryRef as e, type CouponSettings as f, type CoverImageMetadata as g, FEATURE_NAMES as h, type FeatureFlags as i, type NewsFeed as j, type NewsLayoutId as k, type PublicationModules as l, type PublicationRecord as m, type PublicationSnapshot as n, type StoryDisplay as o, type SyncSource as p, type SyncedPublication as q, acceptRemoteRecord as r, acceptSnapshot as s, parseSnapshot as t, publicationFromSnapshot as u, publicationRecord as v, snapshotFromRecord as w, syncPublication as x };

package/dist/snapshot-file.cjs

@@ -0,0 +1,192 @@
+'use strict';
+
+var crypto = require('crypto');
+var promises = require('fs/promises');
+var path = require('path');
+
+// src/snapshot-file.ts
+
+// src/types.ts
+var FEATURE_NAMES = [
+  "smile",
+  "comments",
+  "chat",
+  "jobs",
+  "classifieds",
+  "referrals",
+  "coupons"
+];
+
+// src/config.ts
+var BROADSHEET_THEME = {
+  accent: "#bb171d",
+  ink: "#171917",
+  paper: "#ffffff",
+  sponsor: "#173d32"
+};
+var DISABLED_FEATURES = {
+  smile: false,
+  comments: false,
+  chat: false,
+  jobs: false,
+  classifieds: false,
+  referrals: false,
+  coupons: false
+};
+function definePublication(input) {
+  if (!input.slug.trim() || !input.name.trim()) throw new Error("A publication needs a slug and a name");
+  if (!input.towns.length) throw new Error("A publication needs at least one covered town");
+  const layout = input.layout ?? "broadsheet";
+  const layouts = [.../* @__PURE__ */ new Set([layout, ...input.layouts ?? ["broadsheet"]])];
+  const referralsEnabled = input.features?.referrals === true || input.referrals?.enabled === true;
+  const couponsEnabled = input.features?.coupons === true || input.coupons?.enabled === true;
+  const features = { ...DISABLED_FEATURES, ...input.features, referrals: referralsEnabled, coupons: couponsEnabled };
+  for (const name of FEATURE_NAMES) features[name] = features[name] === true;
+  return {
+    slug: input.slug,
+    name: input.name,
+    masthead: input.masthead.length ? input.masthead : [input.name],
+    region: input.region,
+    regionLabel: input.regionLabel,
+    towns: input.towns,
+    nearbyTowns: input.nearbyTowns ?? [],
+    sections: input.sections ?? [],
+    description: input.description,
+    tagline: input.tagline ?? "Local stories. Close to home.",
+    briefTitle: input.briefTitle ?? `${input.regionLabel} in Brief`,
+    parent: input.parent === true,
+    layout,
+    layouts,
+    features,
+    theme: { ...BROADSHEET_THEME, ...input.theme },
+    referrals: { queryParam: input.referrals?.queryParam?.trim() || "ref", enabled: referralsEnabled },
+    coupons: { enabled: couponsEnabled, offers: input.coupons?.offers ?? [], resolve: input.coupons?.resolve },
+    modules: input.modules ?? {},
+    matchTag: input.matchTag
+  };
+}
+
+// src/snapshot.ts
+var SNAPSHOT_VERSION = 1;
+function publicationRecord(publication) {
+  return {
+    slug: publication.slug,
+    name: publication.name,
+    masthead: publication.masthead,
+    region: publication.region,
+    regionLabel: publication.regionLabel,
+    towns: publication.towns,
+    nearbyTowns: publication.nearbyTowns,
+    sections: publication.sections,
+    description: publication.description,
+    tagline: publication.tagline,
+    briefTitle: publication.briefTitle,
+    parent: publication.parent,
+    layout: publication.layout,
+    layouts: publication.layouts,
+    features: publication.features,
+    theme: publication.theme,
+    referrals: publication.referrals,
+    coupons: { enabled: publication.coupons.enabled, offers: publication.coupons.offers },
+    modules: publication.modules
+  };
+}
+function snapshotFromRecord(record, syncedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  const publication = definePublication(record);
+  return { version: SNAPSHOT_VERSION, syncedAt, record: publicationRecord(publication) };
+}
+function parseSnapshot(raw) {
+  try {
+    return acceptSnapshot(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+function acceptSnapshot(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const snapshot = value;
+  if (snapshot.version !== SNAPSHOT_VERSION || typeof snapshot.syncedAt !== "string") return null;
+  if (!Number.isFinite(Date.parse(snapshot.syncedAt))) return null;
+  try {
+    return snapshotFromRecord(snapshot.record, snapshot.syncedAt);
+  } catch {
+    return null;
+  }
+}
+function acceptRemoteRecord(value, expectedSlug) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const body = value;
+  const candidate = body.record ?? body.publication ?? value;
+  try {
+    const publication = definePublication(candidate);
+    if (expectedSlug && publication.slug !== expectedSlug) return null;
+    return publicationRecord(publication);
+  } catch {
+    return null;
+  }
+}
+function publicationFromSnapshot(snapshot, hooks = {}) {
+  return definePublication({
+    ...snapshot.record,
+    matchTag: hooks.matchTag,
+    coupons: { ...snapshot.record.coupons, resolve: hooks.resolveCoupon }
+  });
+}
+async function syncPublication(input) {
+  const now = input.now ?? Date.now();
+  try {
+    const remote = acceptRemoteRecord(await input.fetchRecord(), input.expectedSlug);
+    if (remote) {
+      const snapshot = snapshotFromRecord(remote, new Date(now).toISOString());
+      return { publication: publicationFromSnapshot(snapshot, input.hooks), snapshot, source: "fresh", ageMs: 0 };
+    }
+  } catch {
+  }
+  if (!input.previous) {
+    throw new Error("This paper has no synced publication config");
+  }
+  const ageMs = Math.max(0, now - Date.parse(input.previous.syncedAt));
+  return {
+    publication: publicationFromSnapshot(input.previous, input.hooks),
+    snapshot: input.previous,
+    source: "retained",
+    ageMs
+  };
+}
+
+// src/snapshot-file.ts
+async function readSnapshotFile(file) {
+  try {
+    return parseSnapshot(await promises.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writeSnapshotFile(file, snapshot) {
+  const accepted = acceptSnapshot(snapshot);
+  if (!accepted) throw new Error("Refusing to store an incomplete publication snapshot");
+  const temporary = path.join(path.dirname(file), `.publication-snapshot-${crypto.randomBytes(6).toString("hex")}.tmp`);
+  await promises.writeFile(temporary, `${JSON.stringify(accepted)}
+`, "utf8");
+  try {
+    await promises.rename(temporary, file);
+  } catch (error) {
+    await promises.unlink(temporary).catch(() => void 0);
+    throw error;
+  }
+}
+async function syncPublicationFile(input) {
+  const previous = await readSnapshotFile(input.file);
+  const synced = await syncPublication({ ...input, previous });
+  if (synced.source === "fresh") {
+    try {
+      await writeSnapshotFile(input.file, synced.snapshot);
+    } catch {
+    }
+  }
+  return synced;
+}
+
+exports.readSnapshotFile = readSnapshotFile;
+exports.syncPublicationFile = syncPublicationFile;
+exports.writeSnapshotFile = writeSnapshotFile;

package/dist/snapshot-file.d.cts

@@ -0,0 +1,21 @@
+import { n as PublicationSnapshot, S as SnapshotHooks, q as SyncedPublication } from './snapshot-BS4hn1dk.cjs';
+
+declare function readSnapshotFile(file: string): Promise<PublicationSnapshot | null>;
+/**
+ * Replace the snapshot only after the new file is fully written.
+ * A crash or a failed write leaves the previous file in place.
+ */
+declare function writeSnapshotFile(file: string, snapshot: PublicationSnapshot): Promise<void>;
+/**
+ * Read the shipped snapshot, try the application, and write only a good result.
+ * A failed sync returns the file already on disk and does not touch it.
+ */
+declare function syncPublicationFile(input: {
+    file: string;
+    fetchRecord: () => Promise<unknown>;
+    expectedSlug?: string;
+    now?: number;
+    hooks?: SnapshotHooks;
+}): Promise<SyncedPublication>;
+
+export { readSnapshotFile, syncPublicationFile, writeSnapshotFile };

package/dist/snapshot-file.d.ts

@@ -0,0 +1,21 @@
+import { n as PublicationSnapshot, S as SnapshotHooks, q as SyncedPublication } from './snapshot-BS4hn1dk.js';
+
+declare function readSnapshotFile(file: string): Promise<PublicationSnapshot | null>;
+/**
+ * Replace the snapshot only after the new file is fully written.
+ * A crash or a failed write leaves the previous file in place.
+ */
+declare function writeSnapshotFile(file: string, snapshot: PublicationSnapshot): Promise<void>;
+/**
+ * Read the shipped snapshot, try the application, and write only a good result.
+ * A failed sync returns the file already on disk and does not touch it.
+ */
+declare function syncPublicationFile(input: {
+    file: string;
+    fetchRecord: () => Promise<unknown>;
+    expectedSlug?: string;
+    now?: number;
+    hooks?: SnapshotHooks;
+}): Promise<SyncedPublication>;
+
+export { readSnapshotFile, syncPublicationFile, writeSnapshotFile };