@dogsbay/format-fluidtopics-rest 0.2.0-beta.101

package/dist/inline-html.js.map

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

package/dist/khub.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Minimal client for Fluid Topics' public khub REST API.
+ *
+ *   {portal}/api/khub/maps                          → list publications (maps)
+ *   {portal}/api/khub/maps/{id}                     → map metadata
+ *   {portal}/api/khub/maps/{id}/toc                 → the topic tree
+ *   {portal}/api/khub/maps/{id}/topics/{cid}/content→ DITA-OT HTML5 for one topic
+ *
+ * `portal` is the part before `/api/khub` and may be path-scoped
+ * (e.g. `https://www.servicenow.com/docs`, `https://docs.johnsoncontrols.com/bas`,
+ * `https://docs.fluidtopics.com`). Access is per-portal (RBAC) — gated portals
+ * return 401.
+ */
+export interface KhubMap {
+    id: string;
+    title: string;
+    metadata?: Array<{
+        key: string;
+        label?: string;
+        values: string[];
+    }>;
+}
+export interface KhubTocNode {
+    tocId?: string;
+    contentId?: string;
+    title: string;
+    prettyUrl?: string;
+    children?: KhubTocNode[];
+}
+/**
+ * A topic as returned by `/maps/{id}/topics` — unlike the TOC, this carries
+ * per-topic `metadata` (audience, author, Product, the `PBS` "Subject matter"
+ * subjectScheme facet, …). The DITA-OT HTML5 from `/content` has no `<head>`,
+ * so this endpoint is the only source of per-topic metadata.
+ */
+export interface KhubTopic {
+    id: string;
+    title?: string;
+    metadata?: Array<{
+        key: string;
+        label?: string;
+        values: string[];
+    }>;
+}
+export interface KhubClientOptions {
+    fetchImpl?: typeof fetch;
+    userAgent?: string;
+    /** Delay between requests (politeness). Default 150ms. */
+    throttleMs?: number;
+}
+export declare class KhubAuthError extends Error {
+}
+export declare class KhubClient {
+    private readonly khubBase;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private readonly throttleMs;
+    private lastAt;
+    constructor(portal: string, opts?: KhubClientOptions);
+    get base(): string;
+    listMaps(lang?: string): Promise<KhubMap[]>;
+    getMap(id: string): Promise<Record<string, unknown>>;
+    getToc(id: string): Promise<KhubTocNode[]>;
+    getTopicContent(mapId: string, contentId: string): Promise<string>;
+    /**
+     * Per-topic metadata for a whole map in ONE request (no content). Cheap, but
+     * the list returns only the facet keys (Category/Product/PBS/audience/author/…)
+     * — not the technical numerics or dates. For those use `getTopic`.
+     */
+    getTopics(id: string): Promise<KhubTopic[]>;
+    /**
+     * Full metadata for ONE topic (43 keys incl. `ft:wordCount`, `ft:outputSize`,
+     * `ft:lastTechChange`). One request per topic — only used when the caller
+     * opts into per-topic technical metadata.
+     */
+    getTopic(mapId: string, contentId: string): Promise<KhubTopic | undefined>;
+    private throttle;
+    private request;
+    private getJson;
+    private getText;
+}
+/** Accepts a portal root or a full `…/api/khub` URL; returns the khub base. */
+export declare function normalizeKhubBase(portal: string): string;
+/** Flatten a TOC tree to the nodes that have a contentId (i.e. real topics). */
+export declare function tocTopics(nodes: KhubTocNode[]): KhubTocNode[];
+//# sourceMappingURL=khub.d.ts.map

package/dist/khub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"khub.d.ts","sourceRoot":"","sources":["../src/khub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAE3C,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,MAAM,CAAK;gBAEP,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB;IAOxD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAM3C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIpD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAK1C,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIxE;;;;OAIG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAKjD;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;YAOlE,QAAQ;YAMR,OAAO;YAYP,OAAO;YAIP,OAAO;CAGtB;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAU7D"}

package/dist/khub.js

@@ -0,0 +1,111 @@
+/**
+ * Minimal client for Fluid Topics' public khub REST API.
+ *
+ *   {portal}/api/khub/maps                          → list publications (maps)
+ *   {portal}/api/khub/maps/{id}                     → map metadata
+ *   {portal}/api/khub/maps/{id}/toc                 → the topic tree
+ *   {portal}/api/khub/maps/{id}/topics/{cid}/content→ DITA-OT HTML5 for one topic
+ *
+ * `portal` is the part before `/api/khub` and may be path-scoped
+ * (e.g. `https://www.servicenow.com/docs`, `https://docs.johnsoncontrols.com/bas`,
+ * `https://docs.fluidtopics.com`). Access is per-portal (RBAC) — gated portals
+ * return 401.
+ */
+export class KhubAuthError extends Error {
+}
+export class KhubClient {
+    khubBase;
+    fetchImpl;
+    userAgent;
+    throttleMs;
+    lastAt = 0;
+    constructor(portal, opts = {}) {
+        this.khubBase = normalizeKhubBase(portal);
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        this.userAgent = opts.userAgent ?? "dogsbay-format-fluidtopics-rest";
+        this.throttleMs = opts.throttleMs ?? 150;
+    }
+    get base() {
+        return this.khubBase;
+    }
+    async listMaps(lang) {
+        const q = lang ? `?lang=${encodeURIComponent(lang)}` : "";
+        const data = await this.getJson(`/maps${q}`);
+        return Array.isArray(data) ? data : [];
+    }
+    async getMap(id) {
+        return (await this.getJson(`/maps/${id}`));
+    }
+    async getToc(id) {
+        const data = await this.getJson(`/maps/${id}/toc`);
+        return Array.isArray(data) ? data : [];
+    }
+    async getTopicContent(mapId, contentId) {
+        return this.getText(`/maps/${mapId}/topics/${contentId}/content`);
+    }
+    /**
+     * Per-topic metadata for a whole map in ONE request (no content). Cheap, but
+     * the list returns only the facet keys (Category/Product/PBS/audience/author/…)
+     * — not the technical numerics or dates. For those use `getTopic`.
+     */
+    async getTopics(id) {
+        const data = await this.getJson(`/maps/${id}/topics`);
+        return Array.isArray(data) ? data : [];
+    }
+    /**
+     * Full metadata for ONE topic (43 keys incl. `ft:wordCount`, `ft:outputSize`,
+     * `ft:lastTechChange`). One request per topic — only used when the caller
+     * opts into per-topic technical metadata.
+     */
+    async getTopic(mapId, contentId) {
+        const data = await this.getJson(`/maps/${mapId}/topics/${contentId}`);
+        return data && typeof data === "object" ? data : undefined;
+    }
+    // ── internals ───────────────────────────────────────
+    async throttle() {
+        const wait = this.throttleMs - (Date.now() - this.lastAt);
+        if (wait > 0)
+            await new Promise((r) => setTimeout(r, wait));
+        this.lastAt = Date.now();
+    }
+    async request(path) {
+        await this.throttle();
+        const res = await this.fetchImpl(`${this.khubBase}${path}`, {
+            headers: { "User-Agent": this.userAgent, Accept: "application/json, text/html" },
+        });
+        if (res.status === 401 || res.status === 403) {
+            throw new KhubAuthError(`khub ${res.status} for ${path} — portal requires authentication (gated). Use a public portal or supply credentials.`);
+        }
+        if (!res.ok)
+            throw new Error(`khub ${res.status} for ${path}`);
+        return res;
+    }
+    async getJson(path) {
+        return (await this.request(path)).json();
+    }
+    async getText(path) {
+        return (await this.request(path)).text();
+    }
+}
+/** Accepts a portal root or a full `…/api/khub` URL; returns the khub base. */
+export function normalizeKhubBase(portal) {
+    let p = portal.trim().replace(/\/+$/, "");
+    if (/\/api\/khub$/.test(p))
+        return p;
+    return `${p}/api/khub`;
+}
+/** Flatten a TOC tree to the nodes that have a contentId (i.e. real topics). */
+export function tocTopics(nodes) {
+    const out = [];
+    const walk = (ns) => {
+        for (const n of ns) {
+            if (n.contentId)
+                out.push(n);
+            if (n.children?.length)
+                walk(n.children);
+        }
+    };
+    walk(nodes);
+    return out;
+}
+//# sourceMappingURL=khub.js.map

package/dist/khub.js.map

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

package/dist/links.d.ts

@@ -0,0 +1,13 @@
+/** `/r/customer-relationship-management/crm-about-csm-in-crm.html` → `customer-relationship-management/crm-about-csm-in-crm` */
+export declare function slugFromPrettyUrl(prettyUrl: string | undefined): string;
+export declare function routeFromSlug(slug: string, hrefPrefix: string): string;
+/**
+ * Resolve an in-content href to a Dogsbay route. Relative `.html` and reader
+ * (`/r/…`) links resolve into the route space; external/anchor/scheme links
+ * pass through. Returns `{ href, resolved }`.
+ */
+export declare function resolveHref(href: string, fromSlug: string, hrefPrefix?: string): {
+    href: string;
+    resolved: boolean;
+};
+//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAUA,gIAAgI;AAChI,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKvE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAGtE;AAOD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAU,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAqBrC"}

package/dist/links.js

@@ -0,0 +1,55 @@
+/**
+ * Slug + link resolution for FT khub content.
+ *
+ * khub topics carry a `prettyUrl` like `/r/customer-relationship-management/
+ * crm-about-csm-in-crm.html`; we derive a clean route slug from it. In-content
+ * links are DITA-OT `.html` hrefs (relative or reader-absolute) resolved to the
+ * same route space.
+ */
+import { posix } from "node:path";
+/** `/r/customer-relationship-management/crm-about-csm-in-crm.html` → `customer-relationship-management/crm-about-csm-in-crm` */
+export function slugFromPrettyUrl(prettyUrl) {
+    if (!prettyUrl)
+        return "";
+    let s = prettyUrl.split("#")[0].split("?")[0].trim();
+    s = s.replace(/^\/+/, "").replace(/^r\//, "").replace(/\.html?$/i, "");
+    return s.replace(/\/+$/, "").toLowerCase();
+}
+export function routeFromSlug(slug, hrefPrefix) {
+    if (!slug)
+        return hrefPrefix || "/";
+    return `${hrefPrefix}/${slug}`;
+}
+function splitAnchor(s) {
+    const i = s.indexOf("#");
+    return i >= 0 ? [s.slice(0, i), s.slice(i + 1)] : [s, ""];
+}
+/**
+ * Resolve an in-content href to a Dogsbay route. Relative `.html` and reader
+ * (`/r/…`) links resolve into the route space; external/anchor/scheme links
+ * pass through. Returns `{ href, resolved }`.
+ */
+export function resolveHref(href, fromSlug, hrefPrefix = "/docs") {
+    if (!href)
+        return { href, resolved: false };
+    if (href.startsWith("#"))
+        return { href, resolved: true };
+    const [path, anchor] = splitAnchor(href);
+    const withAnchor = (route) => route + (anchor ? `#${anchor}` : "");
+    // Reader-absolute (/r/…) → slug
+    if (path.startsWith("/r/")) {
+        return { href: withAnchor(routeFromSlug(slugFromPrettyUrl(path), hrefPrefix)), resolved: true };
+    }
+    // External / scheme (http, mailto, tel)
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href))
+        return { href, resolved: true };
+    // Relative .html → resolve against the current topic's dir
+    if (/\.html?$/i.test(path) || path === "") {
+        const dir = posix.dirname(fromSlug || "index");
+        const rel = posix.normalize(posix.join(dir, path || ".")).replace(/\.html?$/i, "");
+        const slug = rel.replace(/^\.\/?/, "").replace(/^\/+/, "").toLowerCase();
+        return { href: withAnchor(routeFromSlug(slug, hrefPrefix)), resolved: true };
+    }
+    return { href, resolved: false };
+}
+//# sourceMappingURL=links.js.map

package/dist/links.js.map

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

package/dist/nav.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Build a Dogsbay nav subtree from a khub map TOC (the authoritative DITA map).
+ */
+import type { NavItem } from "@dogsbay/types";
+import type { KhubTocNode } from "./khub.js";
+export declare function tocToNav(nodes: KhubTocNode[], hrefPrefix?: string): NavItem[];
+//# sourceMappingURL=nav.d.ts.map

package/dist/nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.d.ts","sourceRoot":"","sources":["../src/nav.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,UAAU,SAAU,GAAG,OAAO,EAAE,CAU9E"}

package/dist/nav.js

@@ -0,0 +1,15 @@
+import { slugFromPrettyUrl, routeFromSlug } from "./links.js";
+export function tocToNav(nodes, hrefPrefix = "/docs") {
+    const out = [];
+    for (const n of nodes) {
+        const item = { label: n.title };
+        const slug = slugFromPrettyUrl(n.prettyUrl);
+        if (slug)
+            item.href = routeFromSlug(slug, hrefPrefix);
+        if (n.children?.length)
+            item.children = tocToNav(n.children, hrefPrefix);
+        out.push(item);
+    }
+    return out;
+}
+//# sourceMappingURL=nav.js.map

package/dist/nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.js","sourceRoot":"","sources":["../src/nav.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,UAAU,QAAQ,CAAC,KAAoB,EAAE,UAAU,GAAG,OAAO;IACjE,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,GAAY,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACtD,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM;YAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACzE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/single-page.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Single-page (whole-map) assembly.
+ *
+ * FT publishes some books as one continuous page (and many readers *prefer* a
+ * single page over "bitty" per-topic pages — the fragmentation debate). This
+ * mode rolls an entire khub map into ONE Dogsbay page: each TOC node becomes a
+ * heading (level = TOC depth), the topic body nests beneath it, and internal
+ * xrefs resolve to in-page anchors instead of separate routes.
+ *
+ * Heading model: the page title (the book) is the implicit H1, so a top-level
+ * TOC node is H2, its children H3, … (clamped at H6). A topic's own body
+ * headings (DITA section titles, normally H2) are shifted down by `level - 1`
+ * so they sit one rank below their topic's title.
+ *
+ * ── Relationship to `@dogsbay/format-astro`'s `granularity.ts` ──────────────
+ *
+ * That module is the PLATFORM generalization of this algorithm, and the two
+ * deliberately coexist. They differ in WHAT THEY WALK, which is the whole
+ * point:
+ *
+ *   granularity.ts   walks `NavItem[]` — the nav a site already has, so it
+ *                    works for ANY source (Hugo, MkDocs, authored Dogsbay-MD).
+ *                    It runs at EMIT time, after nav exists.
+ *   this module      walks `KhubTocNode[]` — Fluid Topics' own map TOC, at
+ *                    IMPORT time, BEFORE any nav is built. `--single-page`
+ *                    collapses a whole map into one page, so there is no
+ *                    per-topic nav for the generic version to consume.
+ *
+ * `bookHeading`, `shiftHeadings` and `bookSlugFrom` are therefore duplicated
+ * on purpose, with identical semantics. KEEP THEM IN SYNC — a change to the
+ * heading model here needs the same change there, and vice versa.
+ *
+ * The `--single-page-books` flag is the other, preferred path: it annotates
+ * nav nodes with `single-page: yes` and lets granularity.ts do the assembly,
+ * which is the additive "Read as single page" view rather than a whole-site
+ * mode. See plans/granularity-views.md and docs/single-page-view.md.
+ */
+import type { TreeNode, NavItem } from "@dogsbay/types";
+import type { KhubTocNode } from "./khub.js";
+export interface BookAnchor {
+    node: KhubTocNode;
+    depth: number;
+    /** Heading level for this node's title (clamped 2..6). */
+    level: number;
+    /** Stable, page-unique anchor id. */
+    anchor: string;
+}
+export interface BookAnchors {
+    ordered: BookAnchor[];
+    /** tocId → anchor (for xref resolution). */
+    byTocId: Map<string, string>;
+}
+/**
+ * Walk a map TOC in document order, assigning every node a heading level and a
+ * page-unique anchor (derived from its prettyUrl basename, else its title).
+ */
+export declare function buildBookAnchors(toc: KhubTocNode[]): BookAnchors;
+/** A heading node for a TOC entry's title, carrying the explicit anchor id. */
+export declare function bookHeading(level: number, title: string, anchor: string): TreeNode;
+/** Shift every heading in a (topic body) tree down by `offset` ranks (max H6). */
+export declare function shiftHeadings(tree: TreeNode[], offset: number): void;
+/**
+ * Longest common path prefix (slash-segment-wise) of the topic slugs — used as
+ * the book's route (e.g. the FT book base `…/metasys-ui…/16.0`). Falls back to
+ * `fallback` (slugified title) when there's no shared prefix.
+ */
+export declare function bookSlugFrom(slugs: string[], fallback: string): string;
+/** One nav leaf per book → its single page (anchors aren't carried in nav.yml). */
+export declare function bookNavItem(title: string, route: string): NavItem;
+//# sourceMappingURL=single-page.d.ts.map

package/dist/single-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-page.d.ts","sourceRoot":"","sources":["../src/single-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAI7C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,4CAA4C;IAC5C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,WAAW,CAuBhE;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAMlF;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUpE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/single-page.js

@@ -0,0 +1,77 @@
+import { slugFromPrettyUrl } from "./links.js";
+import { slugify } from "./headings.js";
+/**
+ * Walk a map TOC in document order, assigning every node a heading level and a
+ * page-unique anchor (derived from its prettyUrl basename, else its title).
+ */
+export function buildBookAnchors(toc) {
+    const ordered = [];
+    const byTocId = new Map();
+    const seen = new Map();
+    const uniq = (base) => {
+        const b = base || "section";
+        const n = seen.get(b) ?? 0;
+        seen.set(b, n + 1);
+        return n === 0 ? b : `${b}-${n}`;
+    };
+    const walk = (nodes, depth) => {
+        for (const n of nodes) {
+            const seg = n.prettyUrl ? slugFromPrettyUrl(n.prettyUrl).split("/").pop() ?? "" : "";
+            const anchor = uniq(slugify(seg || n.title || "section"));
+            ordered.push({ node: n, depth, level: Math.min(depth + 2, 6), anchor });
+            if (n.tocId)
+                byTocId.set(n.tocId, anchor);
+            if (n.children?.length)
+                walk(n.children, depth + 1);
+        }
+    };
+    walk(toc, 0);
+    return { ordered, byTocId };
+}
+/** A heading node for a TOC entry's title, carrying the explicit anchor id. */
+export function bookHeading(level, title, anchor) {
+    return {
+        type: "heading",
+        props: { level, slug: anchor, text: title },
+        children: [{ type: "prose", inline: [{ type: "text", text: title }] }],
+    };
+}
+/** Shift every heading in a (topic body) tree down by `offset` ranks (max H6). */
+export function shiftHeadings(tree, offset) {
+    if (offset <= 0)
+        return;
+    for (const n of tree) {
+        if (n.type === "heading") {
+            const lvl = n.props?.level ?? 1;
+            if (!n.props)
+                n.props = {};
+            n.props.level = Math.min(lvl + offset, 6);
+        }
+        if (n.children)
+            shiftHeadings(n.children, offset);
+    }
+}
+/**
+ * Longest common path prefix (slash-segment-wise) of the topic slugs — used as
+ * the book's route (e.g. the FT book base `…/metasys-ui…/16.0`). Falls back to
+ * `fallback` (slugified title) when there's no shared prefix.
+ */
+export function bookSlugFrom(slugs, fallback) {
+    const parts = slugs.filter(Boolean).map((s) => s.split("/"));
+    if (!parts.length)
+        return slugify(fallback);
+    const first = parts[0];
+    let i = 0;
+    for (; i < first.length; i++) {
+        const seg = first[i];
+        if (!parts.every((p) => p[i] === seg))
+            break;
+    }
+    const prefix = first.slice(0, i).join("/");
+    return prefix || slugify(fallback);
+}
+/** One nav leaf per book → its single page (anchors aren't carried in nav.yml). */
+export function bookNavItem(title, route) {
+    return { label: title, href: route };
+}
+//# sourceMappingURL=single-page.js.map

package/dist/single-page.js.map

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

package/dist/tree.d.ts

@@ -0,0 +1,2 @@
+export type { TreeNode } from "@dogsbay/types";
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/tree.js

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

package/dist/tree.js.map

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dogsbay/format-fluidtopics-rest",
+  "version": "0.2.0-beta.101",
+  "description": "Fluid Topics REST (khub) importer for Dogsbay — reverse-engineers a live FT portal's DITA-OT HTML5 into TreeNode[] / ExportPage[]",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@dogsbay/format-fluidtopics-markdown": "0.2.0-beta.101"
+  },
+  "dependencies": {
+    "cheerio": "^1.2.0",
+    "yaml": "^2.9.0",
+    "@dogsbay/types": "0.2.0-beta.101"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/format-fluidtopics-rest"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/format-fluidtopics-rest",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "reconcile": "tsx scripts/reconcile.ts"
+  }
+}