@fern-api/fdr-sdk 1.2.35-07f6dfd14f → 1.2.35-09eb5b04f6

package/dist/orpc-client/docs-ledger/contract.js

@@ -0,0 +1,742 @@
+import { oc } from "@orpc/contract";
+import * as z from "zod";
+// ── Register ───────────────────────────────────────────────────────────
+export const MissingContentSchema = z.object({
+    hash: z.string(),
+    uploadUrl: z.string()
+});
+/**
+ * Register response: the deployment hash and any blobs the server still needs.
+ * An empty `missingContent` array means all content is already in CAS —
+ * the client can proceed directly to finish without uploading anything.
+ */
+export const RegisterResponseSchema = z.object({
+    deploymentHash: z.string(),
+    missingContent: z.array(MissingContentSchema)
+});
+// ── Finish ─────────────────────────────────────────────────────────────
+export const FinishResponseSchema = z.object({
+    deploymentId: z.string(),
+    /** ID of the canonical (fern URL) site row. */
+    siteId: z.string(),
+    /**
+     * IDs of any additional site rows created for `customDomains` URLs
+     * (ADR 0010). Empty when the publish has no `customDomains`. One ID
+     * per parsed customDomain, in the same order as the input.
+     */
+    additionalSiteIds: z.array(z.string()).default([]),
+    deploymentHash: z.string(),
+    reusedDeployment: z.boolean(),
+    /**
+     * Per-locale segment counts when `translations[]` was supplied on the
+     * finish input. Absent when no translations were included.
+     */
+    translationsProcessed: z.array(z.object({ locale: z.string(), segmentsAdded: z.number() })).optional()
+});
+// ── Archive ────────────────────────────────────────────────────────────
+export const ArchiveSiteInputSchema = z.object({
+    siteId: z.string()
+});
+export const ArchiveSiteResponseSchema = z.object({
+    status: z.enum(["archived", "already_archived", "not_found"])
+});
+// ── Publish input (next-gen: server-side decomposition) ───────────────
+/** Reference to a CAS blob: hash + content metadata for upload. */
+export const BlobRefSchema = z.object({
+    hash: z.string(),
+    contentType: z.string(),
+    contentLength: z.number()
+});
+export const PageBlobRefSchema = z.object({
+    /** SHA-256 hex of the page content bytes. */
+    hash: z.string(),
+    contentType: z.string().default("text/markdown"),
+    contentLength: z.number()
+});
+/** Entry in the file manifest: a CAS blob ref with rendering metadata. */
+export const FileManifestEntrySchema = z.object({
+    /** SHA-256 hex of the file bytes (= CAS content hash). */
+    hash: z.string(),
+    contentType: z.string(),
+    contentLength: z.number(),
+    /** Original filename (e.g. "logo.png"). Used for Content-Disposition and URL cosmetics. */
+    filename: z.string(),
+    /** Image width in pixels (images only). */
+    width: z.number().optional(),
+    /** Image height in pixels (images only). */
+    height: z.number().optional(),
+    /** Base64-encoded blur placeholder (images only). */
+    blurDataURL: z.string().optional()
+});
+// ── Ledger config schema (validated server-side, replaces opaque blob) ─
+/** A file reference with image dimensions for next/image layout reservation. */
+export const ImageRefSchema = z.object({
+    path: z.string(),
+    width: z.number(),
+    height: z.number()
+});
+/** A file reference or external URL. Replaces FileIdOrUrl. */
+export const PathOrUrlSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("path"), value: z.string() }),
+    z.object({ type: z.literal("url"), value: z.string() })
+]);
+const RgbaSchema = z.object({ r: z.number(), g: z.number(), b: z.number(), a: z.number().optional() });
+const BackgroundColorSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("solid"), ...RgbaSchema.shape }),
+    z.object({ type: z.literal("gradient") })
+]);
+const LedgerThemeConfigSchema = z.object({
+    logo: ImageRefSchema.optional(),
+    backgroundImage: z.string().optional(),
+    accentPrimary: RgbaSchema,
+    background: BackgroundColorSchema.optional(),
+    border: RgbaSchema.optional(),
+    sidebarBackground: RgbaSchema.optional(),
+    headerBackground: RgbaSchema.optional(),
+    cardBackground: RgbaSchema.optional(),
+    accent1: RgbaSchema.optional(),
+    accent2: RgbaSchema.optional(),
+    accent3: RgbaSchema.optional(),
+    accent4: RgbaSchema.optional(),
+    accent5: RgbaSchema.optional(),
+    accent6: RgbaSchema.optional(),
+    accent7: RgbaSchema.optional(),
+    accent8: RgbaSchema.optional(),
+    accent9: RgbaSchema.optional(),
+    accent10: RgbaSchema.optional(),
+    accent11: RgbaSchema.optional(),
+    accent12: RgbaSchema.optional()
+});
+const LedgerColorsConfigSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("dark"), ...LedgerThemeConfigSchema.shape }),
+    z.object({ type: z.literal("light"), ...LedgerThemeConfigSchema.shape }),
+    z.object({
+        type: z.literal("darkAndLight"),
+        dark: LedgerThemeConfigSchema,
+        light: LedgerThemeConfigSchema
+    })
+]);
+const LedgerFontVariantSchema = z.object({
+    fontFile: z.string(),
+    weight: z.array(z.string()).optional(),
+    style: z.array(z.enum(["normal", "italic"])).optional()
+});
+const LedgerFontConfigSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("custom"),
+        name: z.string(),
+        variants: z.array(LedgerFontVariantSchema),
+        display: z.enum(["auto", "block", "swap", "fallback", "optional"]).optional(),
+        fallback: z.array(z.string()).optional(),
+        fontVariationSettings: z.string().optional()
+    })
+]);
+const LedgerTypographySchema = z.object({
+    headingsFont: LedgerFontConfigSchema.optional(),
+    bodyFont: LedgerFontConfigSchema.optional(),
+    codeFont: LedgerFontConfigSchema.optional()
+});
+const LedgerJsFileSchema = z.object({
+    path: z.string(),
+    strategy: z.enum(["beforeInteractive", "afterInteractive", "lazyOnload"]).optional()
+});
+const LedgerJsConfigSchema = z.object({
+    remote: z
+        .array(z.object({
+        url: z.string(),
+        strategy: z.enum(["beforeInteractive", "afterInteractive", "lazyOnload"]).optional()
+    }))
+        .optional(),
+    files: z.array(LedgerJsFileSchema).optional(),
+    inline: z.array(z.string()).optional()
+});
+const LedgerMetadataConfigSchema = z.record(z.string(), z.unknown()).and(z.object({
+    "og:image": PathOrUrlSchema.optional(),
+    "og:logo": PathOrUrlSchema.optional(),
+    "twitter:image": PathOrUrlSchema.optional(),
+    "og:background-image": PathOrUrlSchema.optional(),
+    "og:dynamic:background-image": PathOrUrlSchema.optional()
+}));
+const LedgerAgentsConfigSchema = z.object({
+    pageDirective: z.string().optional(),
+    pageDescriptionSource: z.enum(["description", "subtitle"]).optional(),
+    siteDescription: z.string().optional()
+});
+/**
+ * Ledger-native config schema. Validated server-side on register/finish.
+ *
+ * Key differences from the classic DocsConfig:
+ * - No FileId references — file references use fullPath strings
+ * - Logo uses ImageRef (path + width + height) for next/image layout
+ * - Well-known files (favicon, robots.txt, llms.txt, context7.json) are
+ *   served by convention via file artifact lookup, not config fields
+ * - navigation/root excluded — the nav tree is a separate field on DocsPublishInput
+ */
+export const LedgerConfigSchema = z.object({
+    title: z.string().optional(),
+    defaultLanguage: z.string().optional(),
+    translations: z
+        .object({
+        defaultLocale: z.string(),
+        translations: z.array(z.string()).optional()
+    })
+        .optional(),
+    announcement: z.object({ text: z.string() }).optional(),
+    navbarLinks: z.array(z.unknown()).optional(),
+    footerLinks: z.array(z.unknown()).optional(),
+    logoHeight: z.number().optional(),
+    logoHref: z.string().optional(),
+    logoRightText: z.string().optional(),
+    agents: LedgerAgentsConfigSchema.optional(),
+    metadata: LedgerMetadataConfigSchema.optional(),
+    redirects: z
+        .array(z.object({ source: z.string(), destination: z.string(), permanent: z.boolean().optional() }))
+        .optional(),
+    colorsV3: LedgerColorsConfigSchema.optional(),
+    layout: z.record(z.string(), z.unknown()).optional(),
+    theme: z.record(z.string(), z.unknown()).optional(),
+    settings: z.record(z.string(), z.unknown()).optional(),
+    typographyV2: LedgerTypographySchema.optional(),
+    analyticsConfig: z.record(z.string(), z.unknown()).optional(),
+    integrations: z
+        .object({
+        intercom: z.string().optional()
+    })
+        .optional(),
+    css: z.object({ inline: z.array(z.string()).optional() }).optional(),
+    js: LedgerJsConfigSchema.optional(),
+    aiChatConfig: z.record(z.string(), z.unknown()).optional(),
+    pageActions: z.record(z.string(), z.unknown()).optional(),
+    editThisPageLaunch: z.enum(["github", "dashboard"]).optional(),
+    header: z.string().optional(),
+    footer: z.string().optional()
+});
+// ── Publish input (next-gen: server-side decomposition) ───────────────
+/**
+ * Git provenance for a docs-ledger deployment (ADR 0012 / FER-10489).
+ *
+ * Captured server-side from the CLI publish input so the read path can
+ * synthesise `editThisPageUrl = ${repoUrl}/edit/${branch}/${filename}`
+ * without an additional round-trip. All three fields are deployment-
+ * scoped (one value per `docs_ledger_deployments` row), nullable for
+ * back-compat with deployments published before this field existed.
+ */
+export const DocsPublishGitInputSchema = z.object({
+    /** Full HTTPS URL of the repo (e.g. `https://github.com/acme/docs`). */
+    repoUrl: z.string(),
+    /** Branch the publish ran from. Used to build the edit-this-page URL. */
+    branch: z.string(),
+    /**
+     * Optional commit SHA captured when the CLI knows it. Currently surfaced
+     * on `versionMetadata` for diagnostics but not used in URL synthesis.
+     */
+    commitSha: z.string().optional()
+});
+/**
+ * Content fields shared by DocsPublishInput and LedgerPreviewRegisterInput.
+ * Extracted so that new content-layer fields (e.g. cssFiles) are picked up
+ * everywhere automatically.
+ */
+export const DocsContentFieldsSchema = z.object({
+    root: z.unknown(),
+    pages: z.record(z.string(), PageBlobRefSchema),
+    apiManifest: BlobRefSchema.nullish(),
+    config: LedgerConfigSchema.optional(),
+    /**
+     * Content-addressable file manifest: maps fullPath → file metadata + CAS blob ref.
+     * Each entry becomes a file/image artifact in the ledger with nav routing by fullPath.
+     */
+    fileManifest: z.record(z.string(), FileManifestEntrySchema).optional(),
+    // TODO: jsFiles is a single blob containing all custom React component bundles.
+    // These should eventually be individual artifacts so they can be loaded/cached
+    // independently rather than as a monolithic bundle.
+    jsFiles: BlobRefSchema.nullish(),
+    redirects: BlobRefSchema.nullish(),
+    locale: z.string().default("en"),
+    version: z.string().nullish(),
+    repo: z.string().nullish(),
+    /**
+     * Git provenance for the deployment (ADR 0012 / FER-10489). Optional —
+     * older CLI versions don't send it and the columns stay NULL. When
+     * present, captured onto `docs_ledger_deployments` and surfaced on
+     * `versionMetadata` so the read path can synthesise `editThisPageUrl`.
+     */
+    git: DocsPublishGitInputSchema.optional()
+});
+/**
+ * A single locale entry in the `locales[]` array on `DocsPublishInputSchema`.
+ * Overrides `locale` to be required (no default) — the caller must specify
+ * the target locale explicitly. Content fields come from `DocsContentFieldsSchema`.
+ */
+export const LocaleEntrySchema = DocsContentFieldsSchema.extend({
+    /** Locale identifier (e.g. "en", "es", "ja"). Required — no default. */
+    locale: z.string()
+});
+/**
+ * Wire format for the docs-ledger publish endpoints (register + finish).
+ *
+ * The client sends a flat `locales[]` array where each entry contains a
+ * V1 navigation tree, page content as blob refs, and optional global blob
+ * refs for one locale. `defaultLocale` identifies which locale is the
+ * primary/fallback. The server processes every locale through the same
+ * pipeline (transform → presigned URLs / HeadObject → persist).
+ */
+export const DocsPublishInputSchema = z
+    .object({
+    orgId: z.string(),
+    domain: z.string(),
+    basepath: z.string().default(""),
+    /**
+     * Additional URLs the deployment should be served from (e.g. a customer's
+     * vanity hostname `docs.example.com` alongside the canonical fern URL).
+     * Each entry is parsed via `ParsedBaseUrl`, so a value like
+     * `"docs.example.com/v2"` produces a `(domain, basepath)` site row of
+     * `("docs.example.com", "/v2")` — multi-domain + per-domain subpath is
+     * supported in one field. Defaults to `[]`.
+     *
+     * See ADR 0010.
+     */
+    customDomains: z.array(z.string()).default([]),
+    previewId: z.string().nullish(),
+    /** The primary/fallback locale for this deployment (e.g. "en"). */
+    defaultLocale: z.string().default("en"),
+    /**
+     * All locales for this deployment. Each locale goes through the same
+     * transform → upload → verify → persist pipeline.
+     */
+    locales: z.array(LocaleEntrySchema).min(1)
+})
+    .refine((data) => data.locales.some((l) => l.locale === data.defaultLocale), {
+    message: "defaultLocale must match one of the locales in the locales array",
+    path: ["defaultLocale"]
+});
+// ── Preview register (FER-10491) ──────────────────────────────────────
+/**
+ * Wire input for `POST /preview/init`. Mirrors V2's `startDocsPreviewRegister`
+ * — `domain` is server-generated (`{orgId}-preview-{sanitizedId}.{suffix}`),
+ * `customDomains` are explicitly disallowed (preview is single-URL), and
+ * the entitlement / ownership / lock branches are bypassed in the handler.
+ *
+ * Otherwise the input mirrors `DocsPublishInputSchema` so the existing
+ * decomposition pipeline (`transformPublishInput`) can run unchanged.
+ */
+export const LedgerPreviewRegisterInputSchema = DocsContentFieldsSchema.extend({
+    orgId: z.string(),
+    /**
+     * Optional caller-supplied identifier for the preview hostname. Sanitized
+     * server-side (`[a-z0-9-]+`, no leading/trailing dashes). When absent,
+     * the server uses a fresh UUIDv7 — produces a hard-to-guess URL but
+     * defeats the round-trip use case where the CLI prints the predicted
+     * URL before the publish completes. CLIs should always send this.
+     */
+    previewId: z.string().nullish(),
+    /**
+     * Optional path segment appended after the server-generated host.
+     * Mirrors V2's `basePath` — most preview publishes leave this empty,
+     * but explicit subpath previews (`/v2`) are supported.
+     */
+    basePath: z.string().default("")
+});
+/**
+ * Wire output for `POST /preview/init`. Same shape as `RegisterResponseSchema`
+ * plus the server-generated `previewUrl` so the CLI can surface it to the
+ * user without a round-trip to derive the host.
+ */
+export const LedgerPreviewRegisterResponseSchema = z.object({
+    deploymentHash: z.string(),
+    missingContent: z.array(MissingContentSchema),
+    /** Canonical preview URL, e.g. `https://acme-preview-feature-x.docs.buildwithfern.com`. */
+    previewUrl: z.string(),
+    /** Server-generated host portion of `previewUrl` (no scheme, no basepath). */
+    domain: z.string(),
+    /** Echoed `basePath` (normalised — empty string when absent). */
+    basepath: z.string(),
+    /** Sanitized identifier the server actually used to compose the host. */
+    previewId: z.string()
+});
+// ── Write-side contract ────────────────────────────────────────────────
+export const docsLedgerContract = {
+    register: oc
+        .route({ method: "POST", path: "/register" })
+        .input(DocsPublishInputSchema)
+        .output(RegisterResponseSchema),
+    previewRegister: oc
+        .route({ method: "POST", path: "/preview/init" })
+        .input(LedgerPreviewRegisterInputSchema)
+        .output(LedgerPreviewRegisterResponseSchema),
+    finish: oc
+        .route({ method: "POST", path: "/register/finish" })
+        .input(DocsPublishInputSchema)
+        .output(FinishResponseSchema),
+    archiveSite: oc
+        .route({ method: "POST", path: "/archive" })
+        .input(ArchiveSiteInputSchema)
+        .output(ArchiveSiteResponseSchema)
+};
+// ── Read-side schemas ──────────────────────────────────────────────────
+export const CurrentVersionInputSchema = z.object({
+    domain: z.string(),
+    basepath: z.string().default("")
+});
+export const CurrentPreviewInputSchema = CurrentVersionInputSchema.extend({
+    previewId: z.string()
+});
+export const CurrentVersionResponseSchema = z.object({
+    orgId: z.string(),
+    domain: z.string(),
+    basepath: z.string(),
+    deploymentId: z.string(),
+    deploymentHash: z.string(),
+    siteId: z.string(),
+    assignedAt: z.string(),
+    assignedBy: z.string().nullable()
+});
+const ContentRefSchema = z.object({
+    hash: z.string(),
+    s3Key: z.string(),
+    contentType: z.string(),
+    url: z.string()
+});
+/**
+ * Full detail metadata for one segment dimension (product / version /
+ * variant / tab). Carries everything `docs_ledger_segment_details` stores —
+ * not just name + icon — so the read path can reconstruct switcher chrome
+ * and navigation nodes (slug, default flag, pointsTo, href, etc. live in
+ * {@link metadata}) without fetching a monolithic root.
+ */
+export const SegmentDetailSchema = z.object({
+    id: z.string(),
+    displayName: z.string(),
+    icon: z.string().nullable(),
+    sortOrder: z.number(),
+    hidden: z.boolean(),
+    viewers: z.array(z.string()),
+    orphaned: z.boolean(),
+    featureFlags: z.array(z.string()),
+    /** Type-specific fields: slug, default, subtitle, href, target, image, availability, pointsTo, tab_type. */
+    metadata: z.unknown()
+});
+const SegmentSchema = z.object({
+    segmentId: z.string(),
+    segmentHash: z.string(),
+    section: z.string(),
+    locale: z.string(),
+    /** Sidebar order across segments (docs_ledger_deployment_segments.sort_order). */
+    sortOrder: z.number(),
+    /** Whether the segment is hidden from the sidebar. */
+    hidden: z.boolean(),
+    /** Segment type descriptor (seg.metadata): { type, title, icon, apiDefinitionId, overviewPageId, pointsTo, ... }. */
+    metadata: z.unknown(),
+    /** Full product/version/variant/tab detail metadata, or null when the dimension is absent. */
+    product: SegmentDetailSchema.nullable(),
+    version: SegmentDetailSchema.nullable(),
+    variant: SegmentDetailSchema.nullable(),
+    tab: SegmentDetailSchema.nullable(),
+    // ── Flat name/icon retained for back-compat (derivable from the
+    // detail objects above). ──
+    productId: z.string().nullable(),
+    productName: z.string().nullable(),
+    productIcon: z.string().nullable(),
+    versionId: z.string().nullable(),
+    versionName: z.string().nullable(),
+    versionIcon: z.string().nullable(),
+    variantId: z.string().nullable(),
+    variantName: z.string().nullable(),
+    variantIcon: z.string().nullable(),
+    tabId: z.string().nullable(),
+    tabName: z.string().nullable(),
+    tabIcon: z.string().nullable()
+});
+export const VersionMetadataInputSchema = z.object({
+    deploymentId: z.string(),
+    locale: z.string().optional()
+});
+export const VersionMetadataResponseSchema = z.object({
+    deploymentId: z.string(),
+    version: z.string().nullable(),
+    /**
+     * Inline structural config (ADR 0009). Contains everything from
+     * {@link LedgerConfigSchema} except `header`, `footer`, `css.inline`,
+     * `js.inline` — those four fields are returned separately via
+     * {@link header}, {@link footer}, {@link cssInline}, {@link jsInline}
+     * as content-addressed `ContentRef`s. The render path returns this
+     * inline so initial page chrome doesn't require an S3 hop.
+     */
+    configJson: LedgerConfigSchema.nullable(),
+    /** CAS ref for the extracted `config.header` blob (raw MDX). */
+    header: ContentRefSchema.nullable(),
+    /** CAS ref for the extracted `config.footer` blob (raw MDX). */
+    footer: ContentRefSchema.nullable(),
+    /** CAS ref for the joined `config.css.inline` blob (`\n`-separated CSS). */
+    cssInline: ContentRefSchema.nullable(),
+    /** CAS ref for the joined `config.js.inline` blob (`\n`-separated JS). */
+    jsInline: ContentRefSchema.nullable(),
+    jsFiles: ContentRefSchema.nullable(),
+    segments: z.array(SegmentSchema),
+    /** Mapping from human-readable API name slug to API definition UUID. */
+    apiNameToId: z.record(z.string(), z.string()),
+    /**
+     * Git provenance for the deployment (ADR 0012 / FER-10489). Optional —
+     * nullable on CLIs that don't send `git` on the publish input. When
+     * present, the docs loader synthesises `editThisPageUrl` from `repoUrl`,
+     * `branch`, and the page `filename` server-side.
+     */
+    git: z
+        .object({
+        repoUrl: z.string(),
+        branch: z.string(),
+        commitSha: z.string().nullable().optional()
+    })
+        .optional(),
+    /**
+     * Docs deployment status from the legacy `docs_sites` table, resolved
+     * via Kysely join in the DAO. Null when no matching row exists.
+     */
+    docsStatus: z.enum(["PUBLISHING", "LIVE", "UNPUBLISHED", "ERROR"]).nullable().optional()
+});
+export const PageContentInputSchema = z.object({
+    deploymentId: z.string(),
+    fullPath: z.string().optional(),
+    pageId: z.string().optional()
+});
+export const PageContentResponseSchema = z.object({
+    s3Key: z.string(),
+    segmentHash: z.string(),
+    url: z.string()
+});
+export const BatchPageContentInputSchema = z.object({
+    deploymentId: z.string(),
+    pageIds: z.array(z.string()).min(1).max(2000)
+});
+export const BatchPageContentItemSchema = z.object({
+    pageId: z.string(),
+    s3Key: z.string(),
+    url: z.string()
+});
+export const BatchPageContentResponseSchema = z.object({
+    items: z.array(BatchPageContentItemSchema)
+});
+export const NavInputSchema = z.object({
+    segmentHash: z.string()
+});
+const NavRouteSchema = z.object({
+    fullPath: z.string().nullable(),
+    artifactId: z.string(),
+    type: z.string(),
+    /** Whether the artifact is hidden from the sidebar. */
+    hidden: z.boolean(),
+    metadata: z.unknown()
+});
+export const NavResponseSchema = z.object({
+    routes: z.array(NavRouteSchema)
+});
+// ── Route context (route/segment-first hot path) ──────────────────────
+/**
+ * Resolve a single request path to its page content + the segment it lives
+ * in, without fetching the whole navigation root. This is the hot-path read
+ * for a page render: the loader resolves the route here, then fetches the
+ * segment's local sidebar via {@link docsLedgerReadContract.nav} and the
+ * top-level chrome via {@link docsLedgerReadContract.topLevelNavigation}.
+ */
+export const RouteContextInputSchema = z.object({
+    deploymentId: z.string(),
+    fullPath: z.string(),
+    locale: z.string().optional()
+});
+export const RouteContextResponseSchema = z.object({
+    /** Hash of the segment that owns the matched route — feed to `nav`. */
+    segmentHash: z.string(),
+    /** Section path of the owning segment (e.g. "models/command"). */
+    section: z.string(),
+    locale: z.string(),
+    /** The artifact matched at `fullPath`. */
+    artifactId: z.string(),
+    artifactType: z.string(),
+    artifactMetadata: z.unknown(),
+    /**
+     * Page content reference, or null for non-page artifacts (links/redirects)
+     * and route-only aliases that carry no content blob.
+     */
+    page: z
+        .object({
+        s3Key: z.string(),
+        url: z.string()
+    })
+        .nullable(),
+    /** Identity of the owning segment, for switchers + breadcrumbs. */
+    product: SegmentDetailSchema.nullable(),
+    version: SegmentDetailSchema.nullable(),
+    variant: SegmentDetailSchema.nullable(),
+    tab: SegmentDetailSchema.nullable()
+});
+// ── Top-level navigation (products / versions / variants / tabs) ──────
+/**
+ * Distinct product/version/variant/tab dimensions for a deployment, with
+ * full detail metadata + ordering. Drives the product switcher, version
+ * dropdown, and tab bar without materialising the full navigation root.
+ */
+export const TopLevelNavigationInputSchema = z.object({
+    deploymentId: z.string(),
+    locale: z.string().optional()
+});
+export const TopLevelNavigationResponseSchema = z.object({
+    products: z.array(SegmentDetailSchema),
+    versions: z.array(SegmentDetailSchema),
+    variants: z.array(SegmentDetailSchema),
+    tabs: z.array(SegmentDetailSchema)
+});
+// ── Version-switch targets (cross-version context preservation) ───────
+/**
+ * Resolve, for every version of a deployment, the route equivalent to the
+ * current page (`fullPath`). Drives the version switcher's cross-version
+ * context preservation (`withVersionSwitcherInfo`) without shipping a
+ * site-wide slug map to the client. This is inherently cross-version data
+ * the route-scoped tree cannot supply — out-of-scope version sidebars are
+ * empty — so it queries the flat `docs_ledger_nav` table directly.
+ */
+export const VersionSwitchTargetsInputSchema = z.object({
+    deploymentId: z.string(),
+    fullPath: z.string(),
+    locale: z.string().optional()
+});
+export const VersionSwitchTargetSchema = z.object({
+    /** The version detail id (matches a `SegmentDetail.id` from `versionMetadata`). */
+    versionId: z.string(),
+    /**
+     * Slug to navigate to when switching to this version — the equivalent
+     * route in the target version, or that version's landing/root slug when
+     * no equivalent exists. The current version maps to `fullPath` itself.
+     */
+    targetSlug: z.string()
+});
+export const VersionSwitchTargetsResponseSchema = z.object({
+    targets: z.array(VersionSwitchTargetSchema)
+});
+// ── API Definition schemas ─────────────────────────────────────────────
+export const ApiDefinitionInputSchema = z.object({
+    deploymentId: z.string(),
+    apiDefinitionId: z.string()
+});
+export const ApiDefinitionResponseSchema = z.object({
+    s3Key: z.string(),
+    contentType: z.string(),
+    url: z.string()
+});
+// ── Pruned API Definition schemas ─────────────────────────────────────
+/**
+ * Look up a pre-pruned, per-endpoint API definition blob from the ledger.
+ *
+ * The finish handler prunes each endpoint/websocket/webhook from the full
+ * API manifest at publish time and stores the result as a CAS blob linked
+ * to the nav artifact. This endpoint resolves that blob by artifact
+ * metadata, avoiding the need to fetch the full (multi-MB) definition.
+ */
+export const PrunedApiDefinitionInputSchema = z.object({
+    deploymentId: z.string(),
+    apiDefinitionId: z.string(),
+    /** Discriminator matching PruningNodeType.type → artifact metadata field. */
+    nodeType: z.enum(["endpoint", "webSocket", "webhook", "grpc", "graphql"]),
+    /** The node ID value (endpointId, webSocketId, etc.). */
+    nodeId: z.string()
+});
+export const PrunedApiDefinitionResponseSchema = z.object({
+    s3Key: z.string(),
+    contentType: z.string(),
+    url: z.string()
+});
+// ── File artifact schemas ─────────────────────────────────────────────
+export const FileArtifactInputSchema = z.object({
+    deploymentId: z.string(),
+    fullPath: z.string()
+});
+export const FileArtifactResponseSchema = z.object({
+    fullPath: z.string(),
+    type: z.enum(["file", "image"]),
+    contentType: z.string(),
+    filename: z.string(),
+    url: z.string(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    blurDataURL: z.string().optional()
+});
+// ── Presigned file download schemas ──────────────────────────────────
+export const PresignedFileDownloadInputSchema = z.object({
+    /** S3 object key in the public docs bucket (format: `{domain}/{hash}/{path}`). */
+    s3Key: z.string().regex(/^[a-zA-Z0-9._-]+(?:\/[^/]+){2,}$/)
+});
+export const PresignedFileDownloadResponseSchema = z.object({
+    /** Presigned S3 GET URL with long expiry (7 days). */
+    url: z.string()
+});
+// ── File metadata schemas (metadata-only, no presigned URL) ──────────
+export const FileMetadataInputSchema = z.object({
+    deploymentId: z.string(),
+    fullPath: z.string()
+});
+export const FileMetadataResponseSchema = z.object({
+    /** Content hash — used by the loader to construct CDN URLs. */
+    hash: z.string(),
+    /** Domain under which the file bytes were uploaded in the docs files bucket. */
+    domain: z.string(),
+    contentType: z.string(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    blurDataURL: z.string().optional()
+});
+// ── Read-side contract ─────────────────────────────────────────────────
+export const docsLedgerReadContract = {
+    currentVersion: oc
+        .route({ method: "GET", path: "/current-version" })
+        .input(CurrentVersionInputSchema)
+        .output(CurrentVersionResponseSchema),
+    currentPreview: oc
+        .route({ method: "GET", path: "/current-preview" })
+        .input(CurrentPreviewInputSchema)
+        .output(CurrentVersionResponseSchema),
+    versionMetadata: oc
+        .route({ method: "GET", path: "/version-metadata/{deploymentId}" })
+        .input(VersionMetadataInputSchema)
+        .output(VersionMetadataResponseSchema),
+    pageContent: oc
+        .route({ method: "GET", path: "/page-content/{deploymentId}" })
+        .input(PageContentInputSchema)
+        .output(PageContentResponseSchema),
+    batchPageContent: oc
+        .route({ method: "POST", path: "/batch-page-content/{deploymentId}" })
+        .input(BatchPageContentInputSchema)
+        .output(BatchPageContentResponseSchema),
+    nav: oc.route({ method: "GET", path: "/nav/{segmentHash}" }).input(NavInputSchema).output(NavResponseSchema),
+    routeContext: oc
+        .route({ method: "GET", path: "/route-context/{deploymentId}" })
+        .input(RouteContextInputSchema)
+        .output(RouteContextResponseSchema),
+    topLevelNavigation: oc
+        .route({ method: "GET", path: "/top-level-navigation/{deploymentId}" })
+        .input(TopLevelNavigationInputSchema)
+        .output(TopLevelNavigationResponseSchema),
+    versionSwitchTargets: oc
+        .route({ method: "GET", path: "/version-switch-targets/{deploymentId}" })
+        .input(VersionSwitchTargetsInputSchema)
+        .output(VersionSwitchTargetsResponseSchema),
+    apiDefinition: oc
+        .route({ method: "GET", path: "/api-definition/{deploymentId}/{apiDefinitionId}" })
+        .input(ApiDefinitionInputSchema)
+        .output(ApiDefinitionResponseSchema),
+    prunedApiDefinition: oc
+        .route({ method: "GET", path: "/pruned-api/{deploymentId}/{apiDefinitionId}" })
+        .input(PrunedApiDefinitionInputSchema)
+        .output(PrunedApiDefinitionResponseSchema),
+    fileArtifact: oc
+        .route({ method: "GET", path: "/file/{deploymentId}" })
+        .input(FileArtifactInputSchema)
+        .output(FileArtifactResponseSchema),
+    fileMetadata: oc
+        .route({ method: "GET", path: "/file-metadata/{deploymentId}" })
+        .input(FileMetadataInputSchema)
+        .output(FileMetadataResponseSchema),
+    presignedFileDownload: oc
+        .route({ method: "POST", path: "/presigned-file-download" })
+        .input(PresignedFileDownloadInputSchema)
+        .output(PresignedFileDownloadResponseSchema)
+};
+//# sourceMappingURL=contract.js.map