@fern-api/fdr-sdk 1.2.42-0c024f5b0d → 1.2.42-23647d2912

package/dist/navigation/ledger-root-builder.js

@@ -60,6 +60,41 @@ function metaStr(metadata, key) {
     }
     return undefined;
 }
+/**
+ * V1 availability values stored in ledger metadata are lowercase (e.g. "deprecated"),
+ * but the latest Availability type uses PascalCase (e.g. "Deprecated"). This map
+ * normalises both formats so the badge component can look up display names correctly.
+ */
+const AVAILABILITY_LOOKUP = {
+    // V1 lowercase values (stored by docsPublishTransform from V1 navigation tree)
+    alpha: FernNavigation.Availability.Alpha,
+    stable: FernNavigation.Availability.Stable,
+    "generally-available": FernNavigation.Availability.GenerallyAvailable,
+    "in-development": FernNavigation.Availability.InDevelopment,
+    "pre-release": FernNavigation.Availability.PreRelease,
+    deprecated: FernNavigation.Availability.Deprecated,
+    beta: FernNavigation.Availability.Beta,
+    preview: FernNavigation.Availability.Preview,
+    legacy: FernNavigation.Availability.Legacy,
+    // Latest PascalCase values (pass-through)
+    Alpha: FernNavigation.Availability.Alpha,
+    Stable: FernNavigation.Availability.Stable,
+    GenerallyAvailable: FernNavigation.Availability.GenerallyAvailable,
+    InDevelopment: FernNavigation.Availability.InDevelopment,
+    PreRelease: FernNavigation.Availability.PreRelease,
+    Deprecated: FernNavigation.Availability.Deprecated,
+    Beta: FernNavigation.Availability.Beta,
+    Preview: FernNavigation.Availability.Preview,
+    Legacy: FernNavigation.Availability.Legacy
+};
+/** Read an availability field from metadata, converting V1 lowercase to latest PascalCase. */
+function metaAvailability(metadata) {
+    const raw = metaStr(metadata, "availability");
+    if (raw == null) {
+        return undefined;
+    }
+    return AVAILABILITY_LOOKUP[raw];
+}
 function metaBool(metadata, key) {
     if (metadata != null && typeof metadata === "object" && key in metadata) {
         const v = metadata[key];
@@ -198,7 +233,7 @@ function artifactToNode(ctx, route) {
                 }),
                 pageId: FernNavigation.PageId(pageId),
                 noindex: metaBool(md, "noindex"),
-                availability: metaStr(md, "availability")
+                availability: metaAvailability(md)
             };
             return node;
         }
@@ -269,7 +304,7 @@ function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
             endpointId: FernNavigation.EndpointId(endpointId),
             apiDefinitionId,
             isResponseStream: metaBool(md, "isResponseStream"),
-            availability: metaStr(md, "availability"),
+            availability: metaAvailability(md),
             playground: undefined
         };
     }
@@ -285,7 +320,7 @@ function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
             method: method,
             webhookId: FernNavigation.WebhookId(webhookId),
             apiDefinitionId,
-            availability: metaStr(md, "availability")
+            availability: metaAvailability(md)
         };
     }
     if (route.type === "asyncapi") {
@@ -298,7 +333,7 @@ function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
             ...meta,
             webSocketId: FernNavigation.WebSocketId(webSocketId),
             apiDefinitionId,
-            availability: metaStr(md, "availability"),
+            availability: metaAvailability(md),
             playground: undefined
         };
     }
@@ -314,7 +349,7 @@ function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
             method: method,
             grpcId: FernNavigation.GrpcId(grpcId),
             apiDefinitionId,
-            availability: metaStr(md, "availability")
+            availability: metaAvailability(md)
         };
     }
     if (route.type === "graphql") {
@@ -330,7 +365,7 @@ function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
             graphqlOperationId: FernNavigation.GraphQlOperationId(graphqlOperationId),
             graphqlOperationIds: undefined,
             apiDefinitionId,
-            availability: metaStr(md, "availability"),
+            availability: metaAvailability(md),
             playground: undefined
         };
     }
@@ -534,6 +569,30 @@ function stripLeadingScopePrefix(section, scopePrefix) {
     }
     return section;
 }
+function computeDuplicateSiblingSortBoundaries(siblings) {
+    const result = new Map();
+    const byPath = new Map();
+    for (const sibling of siblings) {
+        if (metaStr(sibling.seg.metadata, "type") !== "section") {
+            continue;
+        }
+        const group = byPath.get(sibling.seg.section) ?? [];
+        group.push(sibling);
+        byPath.set(sibling.seg.section, group);
+    }
+    for (const [, group] of byPath) {
+        if (group.length <= 1) {
+            continue;
+        }
+        for (let i = 0; i < group.length; i++) {
+            result.set(group[i], {
+                lo: group[i].seg.sortOrder,
+                hi: i + 1 < group.length ? group[i + 1].seg.sortOrder : Number.MAX_SAFE_INTEGER
+            });
+        }
+    }
+    return result;
+}
 /**
  * Merge leaf children and section children by their original V1 tree position.
  * Leaves carry position via `displaySortOrder` (stored in nav routes), sections
@@ -597,7 +656,7 @@ function sectionNode(ctx, scoped, sectionChildren, scopePrefix) {
         noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
         collapsible: metaBool(seg.metadata, "collapsible") ?? (metaCollapsed(seg.metadata) === true ? true : undefined),
         collapsedByDefault: metaBool(seg.metadata, "collapsedByDefault") ?? (metaCollapsed(seg.metadata) === true ? true : undefined),
-        availability: metaStr(seg.metadata, "availability"),
+        availability: metaAvailability(seg.metadata),
         pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
         children: mergeChildrenByPosition(ctx, nav, sectionChildren)
     };
@@ -607,13 +666,16 @@ function sectionNode(ctx, scoped, sectionChildren, scopePrefix) {
  * `parentSectionPath(seg.section) === parentSection`, or is an orphaned segment
  * whose nearest existing ancestor is `parentSection`.
  */
-function directChildApiPackages(parentSection, scopeSegs) {
+function directChildApiPackages(parentSection, scopeSegs, apiDefinitionId) {
     const sectionPaths = new Set(scopeSegs.map((s) => s.seg.section));
     return scopeSegs
         .filter((s) => {
         if (metaStr(s.seg.metadata, "type") !== "apiPackage") {
             return false;
         }
+        if (metaStr(s.seg.metadata, "apiDefinitionId") !== apiDefinitionId) {
+            return false;
+        }
         const parent = parentSectionPath(s.seg.section);
         if (parent === parentSection) {
             return true;
@@ -638,7 +700,7 @@ function buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix)
     // API leaf types.
     const leafNodes = positionedApiLeafChildren(ctx, nav, apiDefinitionId);
     // Build nested ApiPackageNodes from direct child apiPackage segments.
-    const childPackages = directChildApiPackages(seg.section, scopeSegs);
+    const childPackages = directChildApiPackages(seg.section, scopeSegs, apiDefinitionId);
     const packageNodes = childPackages.map((child) => ({
         node: apiPackageChildNode(ctx, child, scopeSegs, apiDefinitionId, scopePrefix),
         childIndex: metaNum(child.seg.metadata, "childIndex")
@@ -686,7 +748,7 @@ function apiPackageChildNode(ctx, scoped, scopeSegs, parentApiDefinitionId, scop
             featureFlags: metaFeatureFlags(seg.metadata)
         }),
         apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefinitionId),
-        availability: metaStr(seg.metadata, "availability"),
+        availability: metaAvailability(seg.metadata),
         overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
         noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
         pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
@@ -796,10 +858,10 @@ function apiReferenceNode(ctx, scoped, scopeSegs, scopePrefix) {
             featureFlags: metaFeatureFlags(seg.metadata)
         }),
         apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefinitionId),
-        availability: metaStr(seg.metadata, "availability"),
+        availability: metaAvailability(seg.metadata),
         overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
         noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
-        paginated: true,
+        paginated: metaBool(seg.metadata, "paginated"),
         showErrors: metaBool(seg.metadata, "showErrors"),
         hideTitle: metaBool(seg.metadata, "hideTitle"),
         pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
@@ -817,7 +879,12 @@ function attachedApiChangelogNode(ctx, scoped, scopeSegs, apiDefinitionId, scope
         }
         return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
     });
-    const changelogSeg = candidates.find((candidate) => parentSectionPath(candidate.seg.section) === seg.section) ?? candidates[0];
+    const apiReferenceCount = scopeSegs.filter((candidate) => {
+        return (metaStr(candidate.seg.metadata, "type") === "apiReference" &&
+            metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId);
+    }).length;
+    const changelogSeg = candidates.find((candidate) => parentSectionPath(candidate.seg.section) === seg.section) ??
+        (apiReferenceCount === 1 ? candidates[0] : undefined);
     return changelogSeg != null ? changelogNode(ctx, changelogSeg, scopePrefix) : undefined;
 }
 function hasOwningApiReference(scoped, scopeSegs) {
@@ -825,12 +892,14 @@ function hasOwningApiReference(scoped, scopeSegs) {
     if (apiDefinitionId == null || metaStr(scoped.seg.metadata, "type") !== "changelog") {
         return false;
     }
-    return scopeSegs.some((candidate) => {
+    const candidates = scopeSegs.filter((candidate) => {
         if (metaStr(candidate.seg.metadata, "type") !== "apiReference") {
             return false;
         }
         return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
     });
+    return (candidates.some((candidate) => parentSectionPath(scoped.seg.section) === candidate.seg.section) ||
+        candidates.length === 1);
 }
 /**
  * True when this segment is an `apiPackage` that will be nested under an in-scope
@@ -1023,6 +1092,7 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
         return false;
     })
         .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
+    const siblingBoundaries = computeDuplicateSiblingSortBoundaries(direct);
     return direct.map((s) => {
         const type = metaStr(s.seg.metadata, "type");
         const childIndex = metaNum(s.seg.metadata, "childIndex");
@@ -1035,7 +1105,11 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
         }
         else {
             // section (or unrecognised) → recurse for nested sections.
-            node = sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section, scopePrefix, changelogScopePrefix), scopePrefix);
+            const boundary = siblingBoundaries.get(s);
+            const childScopeSegs = boundary != null
+                ? scopeSegs.filter((candidate) => candidate.seg.sortOrder >= boundary.lo && candidate.seg.sortOrder < boundary.hi)
+                : scopeSegs;
+            node = sectionNode(ctx, s, buildSectionTree(ctx, childScopeSegs, s.seg.section, scopePrefix, changelogScopePrefix), scopePrefix);
         }
         return { node, childIndex };
     });
@@ -1055,12 +1129,19 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
 function computeSiblingSortBoundaries(ordered) {
     const result = new Map();
     // Collect root-level sections grouped by their section path.
+    // Sections with sec==="" (skip-slug sections) are included: when multiple
+    // skip-slug sections exist at the root, they share path "" and need
+    // boundaries so each only adopts its own children.
     const sectionPaths = new Set(ordered.map((s) => s.seg.section));
     const rootSections = [];
     for (const s of ordered) {
         const type = metaStr(s.seg.metadata, "type");
         const sec = s.seg.section;
-        if (type !== "section" || sec === "") {
+        if (type !== "section") {
+            continue;
+        }
+        if (sec === "") {
+            rootSections.push(s);
             continue;
         }
         const parent = parentSectionPath(sec);
@@ -1109,6 +1190,17 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
     // segments. Both index into the SAME child list at write time, so they
     // interleave directly (e.g. [page 0, page 1, section 2…15, page 16, 17]).
     const annotated = [];
+    // ── Sibling section ownership ────────────────────────────────────────
+    //
+    // Multiple root-level sections can share the same section path (e.g.
+    // three sections all with path equal to the version slug). When this
+    // happens, buildSectionTree would incorrectly give ALL child subsections
+    // to each sibling. We resolve ownership via sortOrder: a section owns
+    // segments whose sortOrder falls between its own and the next sibling's.
+    //
+    // Computed first because hasRootSection (below) uses it to decide
+    // whether bounded skip-slug siblings should activate adoption.
+    const siblingBoundaries = computeSiblingSortBoundaries(ordered);
     // ── Root-section adoption flow ──────────────────────────────────────
     //
     // A scope may contain a "root section" — a segment with type "section"
@@ -1127,15 +1219,20 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
     //          → SKIP — already adopted by (B) via buildSectionTree
     //
     // Without a root section, depth-0 sections are emitted directly.
-    const hasRootSection = ordered.some((s) => metaStr(s.seg.metadata, "type") === "section" && s.seg.section === "");
-    // ── Sibling section ownership ────────────────────────────────────────
     //
-    // Multiple root-level sections can share the same section path (e.g.
-    // three sections all with path equal to the version slug). When this
-    // happens, buildSectionTree would incorrectly give ALL child subsections
-    // to each sibling. We resolve ownership via sortOrder: a section owns
-    // segments whose sortOrder falls between its own and the next sibling's.
-    const siblingBoundaries = computeSiblingSortBoundaries(ordered);
+    // A section with sec=="" AND `childIndex` in its metadata is a sibling
+    // inside a V1 sidebarGroup that has skipUrlSlug — not a true structural
+    // wrapper. `walkNavSubTrees` always passes `childIndex`; direct
+    // sidebarRoot children (true wrappers) never receive one.
+    //
+    // Such siblings only activate adoption when they have sortOrder
+    // boundaries (multiple sec="" sections sharing the same path), which
+    // correctly scope each section's children. A *single* unbounded
+    // skip-slug sibling (e.g. mangopay's "Introduction") must NOT adopt
+    // its depth-0 peers — doing so produces spurious breadcrumb entries.
+    const hasRootSection = ordered.some((s) => metaStr(s.seg.metadata, "type") === "section" &&
+        s.seg.section === "" &&
+        (metaNum(s.seg.metadata, "childIndex") == null || siblingBoundaries.has(s)));
     for (const s of ordered) {
         const type = metaStr(s.seg.metadata, "type");
         const sec = s.seg.section;
@@ -1158,8 +1255,16 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
             continue;
         }
         // (B) Root section wrapper — adopts depth-0 children via buildSectionTree.
-        if (type === "section" && sec === "") {
-            const sectionChildren = buildSectionTree(ctx, scopeSegs, "", scopePrefix);
+        // Only applies to true root wrappers (no childIndex); sibling
+        // sections with skipUrlSlug (have childIndex) fall through to (C).
+        // When multiple sections share sec==="" (skip-slug), scope children
+        // to each section's sortOrder range so subsections aren't duplicated.
+        if (type === "section" && sec === "" && hasRootSection) {
+            const bounds = siblingBoundaries.get(s);
+            const ownedSegs = bounds != null
+                ? scopeSegs.filter((seg) => seg.seg.sortOrder >= bounds.lo && seg.seg.sortOrder < bounds.hi)
+                : scopeSegs;
+            const sectionChildren = buildSectionTree(ctx, ownedSegs, "", scopePrefix, changelogScopePrefix);
             const node = sectionNode(ctx, s, sectionChildren, scopePrefix);
             annotated.push({ node, pos: metaNum(s.seg.metadata, "childIndex"), isLeaf: false });
             continue;
@@ -1190,7 +1295,20 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
                 const ownedSegs = bounds != null
                     ? scopeSegs.filter((seg) => seg.seg.sortOrder >= bounds.lo && seg.seg.sortOrder < bounds.hi)
                     : scopeSegs;
-                node = sectionNode(ctx, s, buildSectionTree(ctx, ownedSegs, sec, scopePrefix, changelogScopePrefix), scopePrefix);
+                // A section with sec="" that reaches here (not adopted as a
+                // root wrapper in case B) is a skipUrlSlug sibling.
+                // When sortOrder boundaries exist (multiple sec="" sections),
+                // the scoped ownedSegs correctly limits which subsections
+                // each section can adopt. When there are NO boundaries
+                // (single sec="" section, e.g. mangopay's "Introduction"),
+                // buildSectionTree("") would re-adopt all depth-0 peers;
+                // pass an empty child list instead — its leaf artifacts are
+                // already in its own segment nav.
+                const isUnboundedSkipSlugSibling = sec === "" && metaNum(s.seg.metadata, "childIndex") != null && bounds == null;
+                const sectionChildren = isUnboundedSkipSlugSibling
+                    ? []
+                    : buildSectionTree(ctx, ownedSegs, sec, scopePrefix, changelogScopePrefix);
+                node = sectionNode(ctx, s, sectionChildren, scopePrefix);
             }
             // Shared/merged sections (paths not rooted in scopePrefix) must not
             // carry childIndex — their source-version positions would sort them
@@ -1260,11 +1378,6 @@ function groupSidebarRootChildren(ctx, children) {
             flushRun();
             out.push(child);
         }
-        else if (child.type === "changelog") {
-            flushRun();
-            run.push(child);
-            flushRun();
-        }
         else {
             run.push(child);
         }
@@ -1431,7 +1544,7 @@ function buildVariantedNode(ctx, variants, scopeSegs, scopePrefix) {
             ? asSlug(FernNavigation.slugjoin(scopePrefix, variantIndividualSlug))
             : scopePrefix;
         const metaPointsTo = metaStr(variant.metadata, "pointsTo");
-        const children = buildSidebarRootChildren(ctx, variantSegs, scopePrefix);
+        const children = buildSidebarRootChildren(ctx, variantSegs, variantSlug);
         return {
             type: "variant",
             ...withMetadataDefaults({
@@ -1967,6 +2080,14 @@ function buildProductGroup(ctx, products, scoped, rootSlug, skipSharedSectionMer
         };
         return node;
     });
+    // Cross-product canonical slug deduplication (V2 parity).
+    // V2's migrator deduplicates pages across products via a global pageId map:
+    // the first product to register a pageId wins, and subsequent products'
+    // pages with the same pageId receive a canonicalSlug pointing to the
+    // canonical (default-product) page. Without this, shared content that is
+    // materialized under every product scope (e.g. merge-api-basics pages)
+    // appears as separate sitemap entries per product.
+    markCrossProductCanonicalSlugs(children);
     return {
         type: "productgroup",
         id: ctx.nodeId("productgroup"),
@@ -1975,5 +2096,43 @@ function buildProductGroup(ctx, products, scoped, rootSlug, skipSharedSectionMer
         children
     };
 }
+/**
+ * Deduplicate pages across products using pageId as a content-identity key.
+ * Pages with the same pageId in different products are the same content
+ * materialized per-scope; the default product's slug becomes canonical and
+ * non-default copies receive `canonicalSlug` so the sitemap collapses them.
+ *
+ * API leaf nodes (endpoints, websockets, etc.) are unaffected — `getPageId`
+ * returns undefined for those types, so product-specific API surface is
+ * never suppressed.
+ */
+function markCrossProductCanonicalSlugs(productNodes) {
+    const pageIdToCanonical = new Map();
+    // Process default product first so its slugs become the canonical targets.
+    const sorted = [...productNodes].sort((a, b) => {
+        if (a.default !== b.default) {
+            return a.default ? -1 : 1;
+        }
+        return 0;
+    });
+    for (const product of sorted) {
+        FernNavigation.traverseDF(product, (child) => {
+            if (FernNavigation.hasMetadata(child) && FernNavigation.isPage(child)) {
+                const pid = FernNavigation.getPageId(child);
+                if (pid == null) {
+                    return;
+                }
+                const key = `pid:${pid}`;
+                const canonical = pageIdToCanonical.get(key);
+                if (canonical != null && !product.default) {
+                    child.canonicalSlug = canonical;
+                }
+                else if (canonical == null) {
+                    pageIdToCanonical.set(key, child.canonicalSlug ?? child.slug);
+                }
+            }
+        });
+    }
+}
 // (root keeps the bare "root" id; it is the single tree root.)
 //# sourceMappingURL=ledger-root-builder.js.map