@apifn/docsfn 0.0.1

package/dist/index.cjs

@@ -0,0 +1,131 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createApifnProvider: () => createApifnProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/provider.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_core = require("@apifn/core");
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options"
+];
+function tagToSlug(tag, basePath) {
+  const segment = tag.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return `${basePath.replace(/\/$/, "")}/${segment}`;
+}
+function collectEndpoints(spec) {
+  const items = [];
+  for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+    if (!pathItem) continue;
+    for (const method of HTTP_METHODS) {
+      const op = pathItem[method];
+      if (!op) continue;
+      const tags = op.tags ?? ["default"];
+      items.push({ path, method, operation: op, tag: tags[0] ?? "default" });
+    }
+  }
+  return items;
+}
+function buildSidebarGroup(groupLabel, endpoints, slug) {
+  const links = endpoints.map((e) => ({
+    type: "link",
+    label: `${e.method.toUpperCase()} ${e.path}`,
+    href: `${slug}#${e.method.toLowerCase()}-${e.path.replace(/[^a-z0-9]/gi, "-")}`
+  }));
+  return { type: "group", label: groupLabel, items: links };
+}
+function buildEntries(spec, options) {
+  const {
+    basePath = "/api",
+    splitByTag = true,
+    baseUrl
+  } = options;
+  const info = spec.info;
+  const allEndpoints = collectEndpoints(spec);
+  if (!splitByTag) {
+    const slug = basePath.replace(/\/$/, "") || "/api";
+    const title = info?.title ?? "API Reference";
+    const sidebar = buildSidebarGroup(title, allEndpoints, slug);
+    return [{
+      kind: "api",
+      slug,
+      title,
+      endpoints: allEndpoints,
+      sidebar,
+      spec
+    }];
+  }
+  const tagMap = /* @__PURE__ */ new Map();
+  for (const endpoint of allEndpoints) {
+    if (!tagMap.has(endpoint.tag)) tagMap.set(endpoint.tag, []);
+    tagMap.get(endpoint.tag).push(endpoint);
+  }
+  return [...tagMap.entries()].map(([tag, endpoints]) => {
+    const slug = tagToSlug(tag, basePath);
+    const title = `${tag.charAt(0).toUpperCase()}${tag.slice(1)}`;
+    const sidebar = buildSidebarGroup(title, endpoints, slug);
+    return {
+      kind: "api",
+      slug,
+      title,
+      tag,
+      endpoints,
+      sidebar,
+      spec
+    };
+  });
+}
+function createApifnProvider(options) {
+  let cachedEntries = null;
+  async function loadSpec() {
+    if (options.spec) return options.spec;
+    if (options.specPath) {
+      const abs = (0, import_node_path.resolve)(options.specPath);
+      const raw = await (0, import_promises.readFile)(abs, "utf8");
+      return (0, import_core.parseOpenAPI)(raw);
+    }
+    throw new Error("createApifnProvider: must provide either `spec` or `specPath`");
+  }
+  const provider = async () => {
+    if (cachedEntries) return cachedEntries;
+    const spec = await loadSpec();
+    cachedEntries = buildEntries(spec, options);
+    provider.entries = cachedEntries;
+    return cachedEntries;
+  };
+  provider.entries = [];
+  return provider;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createApifnProvider
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/provider.ts"],"sourcesContent":["/**\n * @apifn/docsfn — public API\n *\n * Provides a DocsContentProvider and API reference renderer components\n * for embedding ApiFn API documentation in docsfn sites.\n */\n\n// Provider\nexport { createApifnProvider } from \"./provider.js\";\n\n// Types\nexport type {\n    DocsContentProvider,\n    RawContentEntry,\n    ApiEndpoint,\n    SidebarItem,\n    SidebarLink,\n    SidebarGroup,\n    CreateApifnProviderOptions,\n    ApifnApiReferenceProps,\n    OpenAPIDocument,\n    OperationObject,\n} from \"./types.js\";\n","/**\n * createApifnProvider — DocsContentProvider implementation (DOCS-001, DOCS-004, DOCS-006).\n *\n * Accepts an OpenAPI document (object or file path), groups endpoints by tag,\n * and returns RawContentEntry[] suitable for docsfn's manifest pipeline.\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { parseOpenAPI, type OpenAPIDocument, type OperationObject } from \"@apifn/core\";\nimport type {\n    CreateApifnProviderOptions,\n    DocsContentProvider,\n    RawContentEntry,\n    ApiEndpoint,\n    SidebarGroup,\n    SidebarLink,\n} from \"./types.js\";\n\nconst HTTP_METHODS = [\n    \"get\", \"post\", \"put\", \"patch\", \"delete\", \"head\", \"options\",\n] as const;\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\nfunction tagToSlug(tag: string, basePath: string): string {\n    const segment = tag.toLowerCase().replace(/[^a-z0-9]+/g, \"-\");\n    return `${basePath.replace(/\\/$/, \"\")}/${segment}`;\n}\n\nfunction collectEndpoints(spec: OpenAPIDocument): ApiEndpoint[] {\n    const items: ApiEndpoint[] = [];\n    for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {\n        if (!pathItem) continue;\n        for (const method of HTTP_METHODS) {\n            const op = pathItem[method] as OperationObject | undefined;\n            if (!op) continue;\n            const tags = (op.tags as string[]) ?? [\"default\"];\n            items.push({ path, method, operation: op, tag: tags[0] ?? \"default\" });\n        }\n    }\n    return items;\n}\n\nfunction buildSidebarGroup(\n    groupLabel: string,\n    endpoints: ApiEndpoint[],\n    slug: string\n): SidebarGroup {\n    const links: SidebarLink[] = endpoints.map((e) => ({\n        type: \"link\",\n        label: `${e.method.toUpperCase()} ${e.path}`,\n        href: `${slug}#${e.method.toLowerCase()}-${e.path.replace(/[^a-z0-9]/gi, \"-\")}`,\n    }));\n    return { type: \"group\", label: groupLabel, items: links };\n}\n\nfunction buildEntries(\n    spec: OpenAPIDocument,\n    options: CreateApifnProviderOptions\n): RawContentEntry[] {\n    const {\n        basePath = \"/api\",\n        splitByTag = true,\n        baseUrl,\n    } = options;\n\n    const info = spec.info as { title?: string; version?: string } | undefined;\n    const allEndpoints = collectEndpoints(spec);\n\n    if (!splitByTag) {\n        // Single full-spec entry\n        const slug = basePath.replace(/\\/$/, \"\") || \"/api\";\n        const title = info?.title ?? \"API Reference\";\n        const sidebar = buildSidebarGroup(title, allEndpoints, slug);\n        return [{\n            kind: \"api\",\n            slug,\n            title,\n            endpoints: allEndpoints,\n            sidebar,\n            spec,\n        }];\n    }\n\n    // Split by tag — one entry per tag (DOCS-006)\n    const tagMap = new Map<string, ApiEndpoint[]>();\n    for (const endpoint of allEndpoints) {\n        if (!tagMap.has(endpoint.tag)) tagMap.set(endpoint.tag, []);\n        tagMap.get(endpoint.tag)!.push(endpoint);\n    }\n\n    return [...tagMap.entries()].map(([tag, endpoints]) => {\n        const slug = tagToSlug(tag, basePath);\n        const title = `${tag.charAt(0).toUpperCase()}${tag.slice(1)}`;\n        const sidebar = buildSidebarGroup(title, endpoints, slug);\n        return {\n            kind: \"api\" as const,\n            slug,\n            title,\n            tag,\n            endpoints,\n            sidebar,\n            spec,\n        };\n    });\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\n/**\n * Creates a DocsContentProvider that produces RawContentEntry[] for docsfn.\n *\n * @example\n * const provider = createApifnProvider({ specPath: \"./openapi.yml\", splitByTag: true });\n * const entries = await provider();\n */\nexport function createApifnProvider(\n    options: CreateApifnProviderOptions\n): DocsContentProvider {\n    let cachedEntries: RawContentEntry[] | null = null;\n\n    async function loadSpec(): Promise<OpenAPIDocument> {\n        if (options.spec) return options.spec;\n        if (options.specPath) {\n            const abs = resolve(options.specPath);\n            const raw = await readFile(abs, \"utf8\");\n            return parseOpenAPI(raw);\n        }\n        throw new Error(\"createApifnProvider: must provide either `spec` or `specPath`\");\n    }\n\n    const provider = async (): Promise<RawContentEntry[]> => {\n        if (cachedEntries) return cachedEntries;\n        const spec = await loadSpec();\n        cachedEntries = buildEntries(spec, options);\n        provider.entries = cachedEntries;\n        return cachedEntries;\n    };\n\n    provider.entries = [] as RawContentEntry[];\n    return provider as DocsContentProvider;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,112 @@
+import { OperationObject, OpenAPIDocument } from '@apifn/core';
+export { OpenAPIDocument, OperationObject } from '@apifn/core';
+
+/**
+ * docsfn integration types for @apifn/docsfn.
+ *
+ * docsfn is an optional peer dependency that may not be installed.
+ * We define the minimal interfaces needed for our provider here so
+ * consumers get correct types even without the full docsfn package.
+ */
+
+/** Sidebar leaf link. */
+interface SidebarLink {
+    type: "link";
+    label: string;
+    href: string;
+}
+/** Sidebar group containing links. */
+interface SidebarGroup {
+    type: "group";
+    label: string;
+    items: Array<SidebarLink | SidebarGroup>;
+}
+type SidebarItem = SidebarLink | SidebarGroup;
+/** A processed endpoint grouped in a docsfn page. */
+interface ApiEndpoint {
+    path: string;
+    method: string;
+    operation: OperationObject;
+    tag: string;
+}
+/**
+ * A single raw content entry produced by a DocsContentProvider.
+ * `kind: "api"` signals to docsfn that this is an API reference page.
+ */
+interface RawContentEntry {
+    kind: "api";
+    /** URL slug for this page (e.g. "/api/users") */
+    slug: string;
+    /** Human-readable page title */
+    title: string;
+    /** Tag name when split by tag */
+    tag?: string;
+    /** Endpoint list for this page */
+    endpoints: ApiEndpoint[];
+    /** Sidebar items generated for this entry */
+    sidebar: SidebarGroup;
+    /** Full OpenAPI spec (so renderers can look up $refs etc.) */
+    spec: OpenAPIDocument;
+}
+/** A DocsContentProvider is a callable that returns RawContentEntry[]. */
+interface DocsContentProvider {
+    (): Promise<RawContentEntry[]>;
+    entries: RawContentEntry[];
+}
+interface CreateApifnProviderOptions {
+    /** OpenAPI document (object) */
+    spec?: OpenAPIDocument;
+    /** File path to a JSON or YAML OpenAPI spec */
+    specPath?: string;
+    /** Base path prefix for slug generation (default: "/api") */
+    basePath?: string;
+    /**
+     * Split the spec into one page per tag.
+     * - `true`  → one RawContentEntry per tag
+     * - `false` → one RawContentEntry with all endpoints
+     * @default true
+     */
+    splitByTag?: boolean;
+    /** Optional base URL to embed in entries (for TryIt) */
+    baseUrl?: string;
+}
+interface PerformanceMetrics {
+    endpoint: string;
+    method: string;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    errorRatePct: number;
+    requestsPerMinute: number;
+    lastUpdated: string;
+}
+interface ApifnApiReferenceProps {
+    /** Single content entry from createApifnProvider */
+    entry: RawContentEntry;
+    /** Show embedded Try-It console per endpoint (DOCS-005) */
+    tryIt?: boolean;
+    /** Base URL for Try-It requests */
+    baseUrl?: string;
+    /** Theme for the embedded components */
+    theme?: "light" | "dark" | "auto";
+    /** Optional watchfn metrics per endpoint key ("METHOD /path") */
+    performanceMetrics?: Record<string, Omit<PerformanceMetrics, "endpoint" | "method" | "lastUpdated">>;
+}
+
+/**
+ * createApifnProvider — DocsContentProvider implementation (DOCS-001, DOCS-004, DOCS-006).
+ *
+ * Accepts an OpenAPI document (object or file path), groups endpoints by tag,
+ * and returns RawContentEntry[] suitable for docsfn's manifest pipeline.
+ */
+
+/**
+ * Creates a DocsContentProvider that produces RawContentEntry[] for docsfn.
+ *
+ * @example
+ * const provider = createApifnProvider({ specPath: "./openapi.yml", splitByTag: true });
+ * const entries = await provider();
+ */
+declare function createApifnProvider(options: CreateApifnProviderOptions): DocsContentProvider;
+
+export { type ApiEndpoint, type ApifnApiReferenceProps, type CreateApifnProviderOptions, type DocsContentProvider, type RawContentEntry, type SidebarGroup, type SidebarItem, type SidebarLink, createApifnProvider };

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+import { OperationObject, OpenAPIDocument } from '@apifn/core';
+export { OpenAPIDocument, OperationObject } from '@apifn/core';
+
+/**
+ * docsfn integration types for @apifn/docsfn.
+ *
+ * docsfn is an optional peer dependency that may not be installed.
+ * We define the minimal interfaces needed for our provider here so
+ * consumers get correct types even without the full docsfn package.
+ */
+
+/** Sidebar leaf link. */
+interface SidebarLink {
+    type: "link";
+    label: string;
+    href: string;
+}
+/** Sidebar group containing links. */
+interface SidebarGroup {
+    type: "group";
+    label: string;
+    items: Array<SidebarLink | SidebarGroup>;
+}
+type SidebarItem = SidebarLink | SidebarGroup;
+/** A processed endpoint grouped in a docsfn page. */
+interface ApiEndpoint {
+    path: string;
+    method: string;
+    operation: OperationObject;
+    tag: string;
+}
+/**
+ * A single raw content entry produced by a DocsContentProvider.
+ * `kind: "api"` signals to docsfn that this is an API reference page.
+ */
+interface RawContentEntry {
+    kind: "api";
+    /** URL slug for this page (e.g. "/api/users") */
+    slug: string;
+    /** Human-readable page title */
+    title: string;
+    /** Tag name when split by tag */
+    tag?: string;
+    /** Endpoint list for this page */
+    endpoints: ApiEndpoint[];
+    /** Sidebar items generated for this entry */
+    sidebar: SidebarGroup;
+    /** Full OpenAPI spec (so renderers can look up $refs etc.) */
+    spec: OpenAPIDocument;
+}
+/** A DocsContentProvider is a callable that returns RawContentEntry[]. */
+interface DocsContentProvider {
+    (): Promise<RawContentEntry[]>;
+    entries: RawContentEntry[];
+}
+interface CreateApifnProviderOptions {
+    /** OpenAPI document (object) */
+    spec?: OpenAPIDocument;
+    /** File path to a JSON or YAML OpenAPI spec */
+    specPath?: string;
+    /** Base path prefix for slug generation (default: "/api") */
+    basePath?: string;
+    /**
+     * Split the spec into one page per tag.
+     * - `true`  → one RawContentEntry per tag
+     * - `false` → one RawContentEntry with all endpoints
+     * @default true
+     */
+    splitByTag?: boolean;
+    /** Optional base URL to embed in entries (for TryIt) */
+    baseUrl?: string;
+}
+interface PerformanceMetrics {
+    endpoint: string;
+    method: string;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    errorRatePct: number;
+    requestsPerMinute: number;
+    lastUpdated: string;
+}
+interface ApifnApiReferenceProps {
+    /** Single content entry from createApifnProvider */
+    entry: RawContentEntry;
+    /** Show embedded Try-It console per endpoint (DOCS-005) */
+    tryIt?: boolean;
+    /** Base URL for Try-It requests */
+    baseUrl?: string;
+    /** Theme for the embedded components */
+    theme?: "light" | "dark" | "auto";
+    /** Optional watchfn metrics per endpoint key ("METHOD /path") */
+    performanceMetrics?: Record<string, Omit<PerformanceMetrics, "endpoint" | "method" | "lastUpdated">>;
+}
+
+/**
+ * createApifnProvider — DocsContentProvider implementation (DOCS-001, DOCS-004, DOCS-006).
+ *
+ * Accepts an OpenAPI document (object or file path), groups endpoints by tag,
+ * and returns RawContentEntry[] suitable for docsfn's manifest pipeline.
+ */
+
+/**
+ * Creates a DocsContentProvider that produces RawContentEntry[] for docsfn.
+ *
+ * @example
+ * const provider = createApifnProvider({ specPath: "./openapi.yml", splitByTag: true });
+ * const entries = await provider();
+ */
+declare function createApifnProvider(options: CreateApifnProviderOptions): DocsContentProvider;
+
+export { type ApiEndpoint, type ApifnApiReferenceProps, type CreateApifnProviderOptions, type DocsContentProvider, type RawContentEntry, type SidebarGroup, type SidebarItem, type SidebarLink, createApifnProvider };

package/dist/index.js

@@ -0,0 +1,104 @@
+// src/provider.ts
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { parseOpenAPI } from "@apifn/core";
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options"
+];
+function tagToSlug(tag, basePath) {
+  const segment = tag.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return `${basePath.replace(/\/$/, "")}/${segment}`;
+}
+function collectEndpoints(spec) {
+  const items = [];
+  for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+    if (!pathItem) continue;
+    for (const method of HTTP_METHODS) {
+      const op = pathItem[method];
+      if (!op) continue;
+      const tags = op.tags ?? ["default"];
+      items.push({ path, method, operation: op, tag: tags[0] ?? "default" });
+    }
+  }
+  return items;
+}
+function buildSidebarGroup(groupLabel, endpoints, slug) {
+  const links = endpoints.map((e) => ({
+    type: "link",
+    label: `${e.method.toUpperCase()} ${e.path}`,
+    href: `${slug}#${e.method.toLowerCase()}-${e.path.replace(/[^a-z0-9]/gi, "-")}`
+  }));
+  return { type: "group", label: groupLabel, items: links };
+}
+function buildEntries(spec, options) {
+  const {
+    basePath = "/api",
+    splitByTag = true,
+    baseUrl
+  } = options;
+  const info = spec.info;
+  const allEndpoints = collectEndpoints(spec);
+  if (!splitByTag) {
+    const slug = basePath.replace(/\/$/, "") || "/api";
+    const title = info?.title ?? "API Reference";
+    const sidebar = buildSidebarGroup(title, allEndpoints, slug);
+    return [{
+      kind: "api",
+      slug,
+      title,
+      endpoints: allEndpoints,
+      sidebar,
+      spec
+    }];
+  }
+  const tagMap = /* @__PURE__ */ new Map();
+  for (const endpoint of allEndpoints) {
+    if (!tagMap.has(endpoint.tag)) tagMap.set(endpoint.tag, []);
+    tagMap.get(endpoint.tag).push(endpoint);
+  }
+  return [...tagMap.entries()].map(([tag, endpoints]) => {
+    const slug = tagToSlug(tag, basePath);
+    const title = `${tag.charAt(0).toUpperCase()}${tag.slice(1)}`;
+    const sidebar = buildSidebarGroup(title, endpoints, slug);
+    return {
+      kind: "api",
+      slug,
+      title,
+      tag,
+      endpoints,
+      sidebar,
+      spec
+    };
+  });
+}
+function createApifnProvider(options) {
+  let cachedEntries = null;
+  async function loadSpec() {
+    if (options.spec) return options.spec;
+    if (options.specPath) {
+      const abs = resolve(options.specPath);
+      const raw = await readFile(abs, "utf8");
+      return parseOpenAPI(raw);
+    }
+    throw new Error("createApifnProvider: must provide either `spec` or `specPath`");
+  }
+  const provider = async () => {
+    if (cachedEntries) return cachedEntries;
+    const spec = await loadSpec();
+    cachedEntries = buildEntries(spec, options);
+    provider.entries = cachedEntries;
+    return cachedEntries;
+  };
+  provider.entries = [];
+  return provider;
+}
+export {
+  createApifnProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider.ts"],"sourcesContent":["/**\n * createApifnProvider — DocsContentProvider implementation (DOCS-001, DOCS-004, DOCS-006).\n *\n * Accepts an OpenAPI document (object or file path), groups endpoints by tag,\n * and returns RawContentEntry[] suitable for docsfn's manifest pipeline.\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { parseOpenAPI, type OpenAPIDocument, type OperationObject } from \"@apifn/core\";\nimport type {\n    CreateApifnProviderOptions,\n    DocsContentProvider,\n    RawContentEntry,\n    ApiEndpoint,\n    SidebarGroup,\n    SidebarLink,\n} from \"./types.js\";\n\nconst HTTP_METHODS = [\n    \"get\", \"post\", \"put\", \"patch\", \"delete\", \"head\", \"options\",\n] as const;\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\nfunction tagToSlug(tag: string, basePath: string): string {\n    const segment = tag.toLowerCase().replace(/[^a-z0-9]+/g, \"-\");\n    return `${basePath.replace(/\\/$/, \"\")}/${segment}`;\n}\n\nfunction collectEndpoints(spec: OpenAPIDocument): ApiEndpoint[] {\n    const items: ApiEndpoint[] = [];\n    for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {\n        if (!pathItem) continue;\n        for (const method of HTTP_METHODS) {\n            const op = pathItem[method] as OperationObject | undefined;\n            if (!op) continue;\n            const tags = (op.tags as string[]) ?? [\"default\"];\n            items.push({ path, method, operation: op, tag: tags[0] ?? \"default\" });\n        }\n    }\n    return items;\n}\n\nfunction buildSidebarGroup(\n    groupLabel: string,\n    endpoints: ApiEndpoint[],\n    slug: string\n): SidebarGroup {\n    const links: SidebarLink[] = endpoints.map((e) => ({\n        type: \"link\",\n        label: `${e.method.toUpperCase()} ${e.path}`,\n        href: `${slug}#${e.method.toLowerCase()}-${e.path.replace(/[^a-z0-9]/gi, \"-\")}`,\n    }));\n    return { type: \"group\", label: groupLabel, items: links };\n}\n\nfunction buildEntries(\n    spec: OpenAPIDocument,\n    options: CreateApifnProviderOptions\n): RawContentEntry[] {\n    const {\n        basePath = \"/api\",\n        splitByTag = true,\n        baseUrl,\n    } = options;\n\n    const info = spec.info as { title?: string; version?: string } | undefined;\n    const allEndpoints = collectEndpoints(spec);\n\n    if (!splitByTag) {\n        // Single full-spec entry\n        const slug = basePath.replace(/\\/$/, \"\") || \"/api\";\n        const title = info?.title ?? \"API Reference\";\n        const sidebar = buildSidebarGroup(title, allEndpoints, slug);\n        return [{\n            kind: \"api\",\n            slug,\n            title,\n            endpoints: allEndpoints,\n            sidebar,\n            spec,\n        }];\n    }\n\n    // Split by tag — one entry per tag (DOCS-006)\n    const tagMap = new Map<string, ApiEndpoint[]>();\n    for (const endpoint of allEndpoints) {\n        if (!tagMap.has(endpoint.tag)) tagMap.set(endpoint.tag, []);\n        tagMap.get(endpoint.tag)!.push(endpoint);\n    }\n\n    return [...tagMap.entries()].map(([tag, endpoints]) => {\n        const slug = tagToSlug(tag, basePath);\n        const title = `${tag.charAt(0).toUpperCase()}${tag.slice(1)}`;\n        const sidebar = buildSidebarGroup(title, endpoints, slug);\n        return {\n            kind: \"api\" as const,\n            slug,\n            title,\n            tag,\n            endpoints,\n            sidebar,\n            spec,\n        };\n    });\n}\n\n// ─── Public API ───────────────────────────────────────────────────────────────\n\n/**\n * Creates a DocsContentProvider that produces RawContentEntry[] for docsfn.\n *\n * @example\n * const provider = createApifnProvider({ specPath: \"./openapi.yml\", splitByTag: true });\n * const entries = await provider();\n */\nexport function createApifnProvider(\n    options: CreateApifnProviderOptions\n): DocsContentProvider {\n    let cachedEntries: RawContentEntry[] | null = null;\n\n    async function loadSpec(): Promise<OpenAPIDocument> {\n        if (options.spec) return options.spec;\n        if (options.specPath) {\n            const abs = resolve(options.specPath);\n            const raw = await readFile(abs, \"utf8\");\n            return parseOpenAPI(raw);\n        }\n        throw new Error(\"createApifnProvider: must provide either `spec` or `specPath`\");\n    }\n\n    const provider = async (): Promise<RawContentEntry[]> => {\n        if (cachedEntries) return cachedEntries;\n        const spec = await loadSpec();\n        cachedEntries = buildEntries(spec, options);\n        provider.entries = cachedEntries;\n        return cachedEntries;\n    };\n\n    provider.entries = [] as RawContentEntry[];\n    return provider as DocsContentProvider;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@apifn/docsfn",
+  "version": "0.0.1",
+  "description": "docsfn plugin for ApiFn API reference",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@apifn/core": "0.0.1",
+    "@apifn/react": "0.0.1",
+    "@apifn/svelte": "0.0.1"
+  },
+  "peerDependencies": {
+    "docsfn": "*"
+  },
+  "peerDependenciesMeta": {
+    "docsfn": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.0"
+  },
+  "author": "21n",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/21nCo/super-functions/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/super-functions.git",
+    "directory": "apifn/docsfn"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ]
+}