@fern-api/fdr-sdk 1.2.40-5c4b71a67c → 1.2.40-777f8723e0

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

@@ -0,0 +1,1097 @@
+import { oc } from "@orpc/contract";
+import * as z from "zod";
+import { AIChatConfigSchema, AnalyticsConfigSchema, DocsLayoutConfigSchema, DocsSettingsConfigSchema, DocsThemeConfigSchema, FooterLinkSchema, NavbarLinkSchema, PageActionsConfigSchema } from "../../client/docs-types/shared.js";
+import { AvailabilitySchema, GraphQlOperationTypeSchema, GrpcMethodSchema } from "../api/shared.js";
+import { HttpMethodSchema } from "../shared.js";
+// ── 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(),
+    /**
+     * Bare `fullPath`s of the file/image artifacts this page's rendered
+     * markdown references (the `<fullPath>` of each `file:<fullPath>` token).
+     * Captured CLI-side from the already-rewritten page markdown (same `file:`
+     * regex the bundle serializer uses) so FDR can materialise the page→file
+     * join into the route shards without re-fetching or re-parsing content
+     * (ADR 0016, "File metadata on the render path"). Optional — older CLIs
+     * omit it and the page simply contributes no shard-side file identities.
+     */
+    referencedFiles: z.array(z.string()).optional()
+});
+/** 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 ACCENT_SCALE_KEYS = [
+    "accent1",
+    "accent2",
+    "accent3",
+    "accent4",
+    "accent5",
+    "accent6",
+    "accent7",
+    "accent8",
+    "accent9",
+    "accent10",
+    "accent11",
+    "accent12"
+];
+/** Radix-style 12-step accent scale, all optional. */
+// Cast is safe: Object.fromEntries cannot preserve the literal key union.
+const accentScaleShape = Object.fromEntries(ACCENT_SCALE_KEYS.map((key) => [key, RgbaSchema.optional()]));
+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(),
+    ...accentScaleShape
+});
+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()
+}));
+// The shared docs-config schemas below are annotated as `z.ZodType<NamedType>`
+// so declaration emit references the named types instead of inlining their full
+// structural shape — without this, the inferred type of the publish router
+// exceeds tsc's serialization limit (TS7056).
+const NavbarLinksFieldSchema = z.array(NavbarLinkSchema);
+const FooterLinksFieldSchema = z.array(FooterLinkSchema);
+const LayoutFieldSchema = DocsLayoutConfigSchema;
+const ThemeFieldSchema = DocsThemeConfigSchema;
+const SettingsFieldSchema = DocsSettingsConfigSchema;
+const AnalyticsFieldSchema = AnalyticsConfigSchema;
+const AIChatFieldSchema = AIChatConfigSchema;
+const PageActionsFieldSchema = PageActionsConfigSchema;
+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
+ * - Config-referenced files (favicon, logo, OG images, fonts, JS) carry their
+ *   fullPath strings and are retained in the pointer's `files` map
+ *   (see collectConfigFilePaths); robots.txt/llms.txt/context7.json remain
+ *   well-known files served by convention via file artifact lookup
+ * - navigation/root excluded — the nav tree is a separate field on DocsPublishInput
+ */
+export const LedgerConfigSchema = z.object({
+    title: z.string().optional(),
+    rootSlug: 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: NavbarLinksFieldSchema.optional(),
+    footerLinks: FooterLinksFieldSchema.optional(),
+    logoHeight: z.number().optional(),
+    logoHref: z.string().optional(),
+    logoRightText: z.string().optional(),
+    /** fullPath of the favicon file artifact (any extension: .svg/.png/.ico). */
+    favicon: z.string().nullish(),
+    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: LayoutFieldSchema.optional(),
+    theme: ThemeFieldSchema.optional(),
+    settings: SettingsFieldSchema.optional(),
+    typographyV2: LedgerTypographySchema.optional(),
+    analyticsConfig: AnalyticsFieldSchema.optional(),
+    integrations: z
+        .object({
+        intercom: z.string().optional()
+    })
+        .optional(),
+    css: z.object({ inline: z.array(z.string()).optional() }).optional(),
+    js: LedgerJsConfigSchema.optional(),
+    aiChatConfig: AIChatFieldSchema.optional(),
+    pageActions: PageActionsFieldSchema.optional(),
+    editThisPageLaunch: z.enum(["github", "dashboard"]).optional(),
+    header: z.string().optional(),
+    footer: z.string().optional()
+});
+// ── Ledger metadata schemas ───────────────────────────────────────────
+const MetadataStringArraySchema = z.array(z.string());
+const FeatureFlagMetadataSchema = z.array(z.union([
+    z.string(),
+    z.object({
+        flag: z.string(),
+        fallbackValue: z.unknown().optional(),
+        match: z.unknown().optional()
+    })
+]));
+const LinkTargetSchema = z.enum(["_blank", "_self", "_parent", "_top"]);
+const CollapsedSchema = z.union([z.boolean(), z.literal("open-by-default")]);
+const LedgerAvailabilitySchema = z.union([
+    AvailabilitySchema,
+    z.enum([
+        "alpha",
+        "stable",
+        "generally-available",
+        "in-development",
+        "pre-release",
+        "beta",
+        "preview",
+        "deprecated",
+        "legacy"
+    ])
+]);
+export const LedgerArtifactTypeSchema = z.enum([
+    "markdown",
+    "page",
+    "rest",
+    "asyncapi",
+    "webhook",
+    "grpc",
+    "graphql",
+    "changelog",
+    "link",
+    "file",
+    "image",
+    "redirect"
+]);
+const LedgerMetadataBaseSchema = z.object({}).passthrough();
+const NodeMetadataFields = {
+    title: z.string().optional(),
+    slug: z.string().optional(),
+    icon: z.string().optional(),
+    authed: z.boolean().optional(),
+    viewers: MetadataStringArraySchema.optional(),
+    orphaned: z.boolean().optional(),
+    featureFlags: FeatureFlagMetadataSchema.optional()
+};
+// Read-model guarantee: the FDR transform always writes apiDefinitionId
+// (and the per-type ID fields below), so the read schemas require them.
+const ApiNodeMetadataFields = {
+    ...NodeMetadataFields,
+    apiDefinitionId: z.string(),
+    availability: LedgerAvailabilitySchema.optional()
+};
+const LedgerSegmentDetailMetadataObjectSchema = LedgerMetadataBaseSchema.extend({
+    slug: z.string().optional(),
+    default: z.boolean().optional(),
+    subtitle: z.string().optional(),
+    href: z.string().optional(),
+    url: z.string().optional(),
+    target: LinkTargetSchema.optional(),
+    image: z.string().optional(),
+    pointsTo: z.string().optional(),
+    availability: LedgerAvailabilitySchema.optional(),
+    tab_type: z.enum(["tab", "link", "changelog"]).optional()
+});
+export const LedgerSegmentDetailMetadataSchema = LedgerSegmentDetailMetadataObjectSchema.nullable();
+const LedgerSegmentMetadataObjectSchema = z.discriminatedUnion("type", [
+    LedgerMetadataBaseSchema.extend({
+        type: z.literal("tabRoot")
+    }),
+    LedgerMetadataBaseSchema.extend({
+        type: z.literal("section"),
+        title: z.string().optional(),
+        icon: z.string().optional(),
+        authed: z.boolean().optional(),
+        collapsed: CollapsedSchema.optional(),
+        collapsible: z.boolean().optional(),
+        collapsedByDefault: z.boolean().optional(),
+        availability: LedgerAvailabilitySchema.optional(),
+        overviewPageId: z.string().optional(),
+        noindex: z.boolean().optional(),
+        pointsTo: z.string().optional(),
+        viewers: MetadataStringArraySchema.optional(),
+        orphaned: z.boolean().optional(),
+        featureFlags: FeatureFlagMetadataSchema.optional()
+    }),
+    LedgerMetadataBaseSchema.extend({
+        type: z.literal("apiReference"),
+        title: z.string().optional(),
+        icon: z.string().optional(),
+        authed: z.boolean().optional(),
+        apiDefinitionId: z.string().optional(),
+        overviewPageId: z.string().optional(),
+        noindex: z.boolean().optional(),
+        availability: LedgerAvailabilitySchema.optional(),
+        pointsTo: z.string().optional(),
+        paginated: z.boolean().optional(),
+        showErrors: z.boolean().optional(),
+        hideTitle: z.boolean().optional(),
+        viewers: MetadataStringArraySchema.optional(),
+        orphaned: z.boolean().optional(),
+        featureFlags: FeatureFlagMetadataSchema.optional()
+    }),
+    LedgerMetadataBaseSchema.extend({
+        type: z.literal("apiPackage"),
+        title: z.string().optional(),
+        icon: z.string().optional(),
+        authed: z.boolean().optional(),
+        apiDefinitionId: z.string().optional(),
+        overviewPageId: z.string().optional(),
+        noindex: z.boolean().optional(),
+        availability: LedgerAvailabilitySchema.optional(),
+        pointsTo: z.string().optional(),
+        viewers: MetadataStringArraySchema.optional(),
+        orphaned: z.boolean().optional(),
+        featureFlags: FeatureFlagMetadataSchema.optional()
+    }),
+    LedgerMetadataBaseSchema.extend({
+        type: z.literal("changelog"),
+        title: z.string().optional(),
+        icon: z.string().optional(),
+        overviewPageId: z.string().optional(),
+        apiDefinitionId: z.string().optional(),
+        noindex: z.boolean().optional(),
+        authed: z.boolean().optional(),
+        viewers: MetadataStringArraySchema.optional(),
+        orphaned: z.boolean().optional(),
+        featureFlags: FeatureFlagMetadataSchema.optional()
+    }),
+    LedgerMetadataBaseSchema.extend({
+        type: z.literal("files")
+    }),
+    LedgerMetadataBaseSchema.extend({
+        type: z.literal("redirects")
+    })
+]);
+export const LedgerSegmentMetadataSchema = LedgerSegmentMetadataObjectSchema;
+export const LedgerMarkdownMetadataSchema = LedgerMetadataBaseSchema.extend({
+    ...NodeMetadataFields,
+    pageId: z.string().optional(),
+    isOverview: z.boolean().optional(),
+    noindex: z.boolean().optional()
+});
+export const LedgerRestMetadataSchema = LedgerMetadataBaseSchema.extend({
+    ...ApiNodeMetadataFields,
+    endpointId: z.string(),
+    method: HttpMethodSchema,
+    isResponseStream: z.boolean().optional(),
+    endpointPairKey: z.string().optional()
+});
+export const LedgerWebSocketMetadataSchema = LedgerMetadataBaseSchema.extend({
+    ...ApiNodeMetadataFields,
+    webSocketId: z.string()
+});
+export const LedgerWebhookMetadataSchema = LedgerMetadataBaseSchema.extend({
+    ...ApiNodeMetadataFields,
+    webhookId: z.string(),
+    // V1.WebhookNode carries the full HttpMethod union, so the read model must accept it too.
+    method: HttpMethodSchema
+});
+export const LedgerGrpcMetadataSchema = LedgerMetadataBaseSchema.extend({
+    ...ApiNodeMetadataFields,
+    grpcId: z.string(),
+    method: GrpcMethodSchema
+});
+export const LedgerGraphQlMetadataSchema = LedgerMetadataBaseSchema.extend({
+    ...ApiNodeMetadataFields,
+    graphqlOperationId: z.string(),
+    operationType: GraphQlOperationTypeSchema
+});
+export const LedgerChangelogEntryMetadataSchema = LedgerMetadataBaseSchema.extend({
+    ...NodeMetadataFields,
+    pageId: z.string(),
+    noindex: z.boolean().optional(),
+    date: z.string().optional(),
+    tags: MetadataStringArraySchema.optional()
+});
+export const LedgerLinkMetadataSchema = LedgerMetadataBaseSchema.extend({
+    title: z.string().optional(),
+    slug: z.string().optional(),
+    icon: z.string().optional(),
+    url: z.string(),
+    target: LinkTargetSchema.optional()
+});
+export const LedgerFileArtifactMetadataSchema = LedgerMetadataBaseSchema.extend({
+    contentType: z.string(),
+    contentLength: z.number().optional(),
+    filename: z.string(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    blurDataURL: z.string().optional()
+});
+export const LedgerRedirectMetadataSchema = LedgerMetadataBaseSchema.extend({
+    href: z.string().optional()
+});
+export const LedgerArtifactMetadataSchema = z.union([
+    LedgerMarkdownMetadataSchema,
+    LedgerRestMetadataSchema,
+    LedgerWebSocketMetadataSchema,
+    LedgerWebhookMetadataSchema,
+    LedgerGrpcMetadataSchema,
+    LedgerGraphQlMetadataSchema,
+    LedgerChangelogEntryMetadataSchema,
+    LedgerLinkMetadataSchema,
+    LedgerFileArtifactMetadataSchema,
+    LedgerRedirectMetadataSchema
+]);
+/**
+ * Single source of truth for the artifactType → metadata schema pairing.
+ * Every discriminated union over artifact types (nav routes, manifest
+ * routes, route-context responses) is derived from this map, so adding a
+ * type added to one but not the other fails to compile.
+ */
+export const LEDGER_ARTIFACT_METADATA_SCHEMAS = {
+    markdown: LedgerMarkdownMetadataSchema,
+    page: LedgerMarkdownMetadataSchema,
+    rest: LedgerRestMetadataSchema,
+    asyncapi: LedgerWebSocketMetadataSchema,
+    webhook: LedgerWebhookMetadataSchema,
+    grpc: LedgerGrpcMetadataSchema,
+    graphql: LedgerGraphQlMetadataSchema,
+    changelog: LedgerChangelogEntryMetadataSchema,
+    link: LedgerLinkMetadataSchema,
+    file: LedgerFileArtifactMetadataSchema,
+    image: LedgerFileArtifactMetadataSchema,
+    redirect: LedgerRedirectMetadataSchema
+};
+/**
+ * Extends `base` with the canonical `{ artifactType, artifactMetadata }`
+ * pair for one artifact type. The indexed access into
+ * {@link LEDGER_ARTIFACT_METADATA_SCHEMAS} preserves the exact per-type
+ * metadata schema, so unions built from tuples of these calls stay
+ * precisely typed with zero casts.
+ */
+export function artifactTypeVariant(base, type) {
+    return base.extend({
+        artifactType: z.literal(type),
+        artifactMetadata: LEDGER_ARTIFACT_METADATA_SCHEMAS[type]
+    });
+}
+const NavRouteBaseSchema = z.object({
+    fullPath: z.string().nullable(),
+    artifactId: z.string(),
+    hidden: z.boolean(),
+    displaySortOrder: z.number().nullable().optional()
+});
+/** Like {@link artifactTypeVariant} but for nav routes, whose discriminator/metadata keys are `type`/`metadata`. */
+function navRouteVariant(type) {
+    return NavRouteBaseSchema.extend({
+        type: z.literal(type),
+        metadata: LEDGER_ARTIFACT_METADATA_SCHEMAS[type]
+    });
+}
+export const LedgerNavRouteSchema = z.discriminatedUnion("type", [
+    navRouteVariant("markdown"),
+    navRouteVariant("page"),
+    navRouteVariant("rest"),
+    navRouteVariant("asyncapi"),
+    navRouteVariant("webhook"),
+    navRouteVariant("grpc"),
+    navRouteVariant("graphql"),
+    navRouteVariant("changelog"),
+    navRouteVariant("link"),
+    navRouteVariant("file"),
+    navRouteVariant("image"),
+    navRouteVariant("redirect")
+]);
+/** Compile-time proof that the nav-route union covers every artifact type. */
+const _navRouteUnionIsExhaustive = true;
+// ── 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`.
+ */
+const LocaleEntrySchemaInternal = DocsContentFieldsSchema.extend({
+    /** Locale identifier (e.g. "en", "es", "ja"). Required — no default. */
+    locale: z.string()
+});
+// Annotated as `z.ZodType` with named input/output types so declaration emit
+// references the aliases instead of inlining the structural shape — keeps the
+// publish router's inferred type under tsc's serialization limit (TS7056).
+export const LocaleEntrySchema = LocaleEntrySchemaInternal;
+/**
+ * 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).
+ */
+const DocsPublishInputSchemaInternal = 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"]
+});
+// See LocaleEntrySchema — same TS7056 mitigation.
+export const DocsPublishInputSchema = DocsPublishInputSchemaInternal;
+// ── 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.
+ */
+const LedgerPreviewRegisterInputSchemaInternal = DocsContentFieldsSchema.partial()
+    .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(""),
+    /** The primary/fallback locale for this preview deployment. */
+    defaultLocale: z.string().optional(),
+    /**
+     * All locales for this preview deployment. Preferred over the legacy
+     * single-locale content fields above.
+     */
+    locales: z.array(LocaleEntrySchema).min(1).optional()
+})
+    .superRefine((data, ctx) => {
+    if (data.locales == null) {
+        if (data.root == null || data.pages == null) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Either locales or legacy single-locale content fields must be provided",
+                path: ["locales"]
+            });
+        }
+        return;
+    }
+    const defaultLocale = data.defaultLocale ?? data.locales[0]?.locale;
+    if (defaultLocale == null || !data.locales.some((locale) => locale.locale === defaultLocale)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "defaultLocale must match one of the locales in the locales array",
+            path: ["defaultLocale"]
+        });
+    }
+});
+// See LocaleEntrySchema — same TS7056 mitigation.
+export const LedgerPreviewRegisterInputSchema = LedgerPreviewRegisterInputSchemaInternal;
+/**
+ * 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: LedgerSegmentDetailMetadataSchema
+});
+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: LedgerSegmentMetadataSchema,
+    /** 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(),
+    locale: z.string().optional()
+});
+export const PageContentResponseSchema = z.object({
+    s3Key: z.string(),
+    segmentHash: z.string(),
+    url: z.string(),
+    pageId: z.string().optional()
+});
+export const BatchPageContentInputSchema = z.object({
+    deploymentId: z.string(),
+    pageIds: z.array(z.string()).min(1).max(2000),
+    locale: z.string().optional()
+});
+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()
+});
+export const NavResponseSchema = z.object({
+    routes: z.array(LedgerNavRouteSchema)
+});
+// ── 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. The ledger loader resolves
+ * the route from the `routes` map, then reads the segment's local sidebar
+ * (`nav`) and the top-level chrome from the same manifest (ADR 0016).
+ */
+export const RouteContextInputSchema = z.object({
+    deploymentId: z.string(),
+    fullPath: z.string(),
+    locale: z.string().optional()
+});
+const RouteContextResponseBaseSchema = z.object({
+    artifactId: z.string(),
+    /** 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(),
+    /**
+     * 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()
+});
+export const RouteContextResponseSchema = z.discriminatedUnion("artifactType", [
+    artifactTypeVariant(RouteContextResponseBaseSchema, "markdown"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "page"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "rest"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "asyncapi"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "webhook"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "grpc"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "graphql"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "changelog"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "link"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "file"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "image"),
+    artifactTypeVariant(RouteContextResponseBaseSchema, "redirect")
+]);
+/** Compile-time proof that the route-context union covers every artifact type. */
+const _routeContextUnionIsExhaustive = true;
+// ── 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(),
+    contentLength: z.number().optional(),
+    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(),
+    contentLength: z.number().optional(),
+    filename: z.string().optional(),
+    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