@apifn/docsfn 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# @apifn/docsfn
+
+docsfn plugin for ApiFn API reference. Turn an OpenAPI document into docsfn content entries and render them as an interactive API reference (React or Svelte) with embedded Try-It consoles and performance metrics.
+
+## Installation
+
+```bash
+npm install @apifn/docsfn
+```
+
+`docsfn` is an **optional** peer dependency — this package defines the minimal `DocsContentProvider` / `RawContentEntry` interfaces itself, so you get correct types even without docsfn installed.
+The package-local build declares its React type dependencies and the file-loading
+tests create their own temporary OpenAPI fixtures. `npm install --workspaces=false`,
+`npm run build`, and `npm test` do not require a sibling CLI checkout or workspace
+type hoisting.
+
+## Features
+
+- **Content provider** — Convert an OpenAPI spec into docsfn `RawContentEntry[]`
+- **Tag splitting** — One page per tag (default) or a single full-spec page
+- **Sidebar generation** — Auto-built navigation with per-endpoint anchors
+- **Reference renderers** — `ApifnApiReference` for React and Svelte, wrapping the `@apifn/react` / `@apifn/svelte` components
+
+---
+
+## createApifnProvider
+
+Create a `DocsContentProvider` — a callable that returns `RawContentEntry[]` (memoized) and carries an `.entries` array.
+
+```typescript
+import { createApifnProvider } from "@apifn/docsfn";
+
+const provider = createApifnProvider({
+  specPath: "./openapi.yml", // or: spec: openApiDocument
+  basePath: "/api",
+  splitByTag: true,
+});
+
+const entries = await provider(); // RawContentEntry[]
+```
+
+### CreateApifnProviderOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `spec` | `OpenAPIDocument` | — | The document (provide this or `specPath`) |
+| `specPath` | `string` | — | Path to a JSON or YAML spec |
+| `basePath` | `string` | `"/api"` | Slug prefix for generated pages |
+| `splitByTag` | `boolean` | `true` | One entry per tag, or a single full-spec entry |
+| `baseUrl` | `string` | — | Base URL embedded in entries (for Try-It) |
+
+With `splitByTag: true`, each tag becomes a `RawContentEntry`. The tag is lowercased and each run of non-alphanumeric characters becomes `-`, so `My Tag Group` produces `${basePath}/my-tag-group`. Sidebar links use the lowercased method followed by the path with each non-alphanumeric character replaced by `-`; for example, `GET /users/{id}` links to `${slug}#get--users--id-`. With `splitByTag: false`, a single entry contains every endpoint. Path-level parameters are merged into each operation.
+
+---
+
+## Rendering the reference
+
+The package root (`@apifn/docsfn`) exports the provider and types. Renderer components are available from framework-specific public subpaths:
+
+- React: `@apifn/docsfn/react`
+- Svelte: `@apifn/docsfn/svelte`
+
+Pass each `RawContentEntry` returned by the provider to the renderer used by your docsfn integration.
+
+React endpoint headers are native disclosure buttons with an expanded-state
+announcement, so collapsed endpoints remain reachable and operable by keyboard.
+
+```tsx
+import { ApifnApiReference } from "@apifn/docsfn/react";
+
+<ApifnApiReference
+  entry={entry}
+  tryIt
+  baseUrl="https://api.example.com"
+  theme="light"
+  performanceMetrics={{
+    "GET /users": { p50Ms: 12, p95Ms: 40, p99Ms: 90, errorRatePct: 0.5, requestsPerMinute: 320 },
+  }}
+/>
+```
+
+The Svelte renderer takes the same props (`entry`, `tryIt`, `baseUrl`, `theme`, `performanceMetrics`):
+
+```svelte
+<script lang="ts">
+  import ApifnApiReference from "@apifn/docsfn/svelte";
+</script>
+
+<ApifnApiReference {entry} tryIt theme="auto" />
+```
+
+### ApifnApiReferenceProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `entry` | `RawContentEntry` | — | A single entry from `createApifnProvider` (required) |
+| `tryIt` | `boolean` | `false` | Show an embedded Try-It console per endpoint |
+| `baseUrl` | `string` | See below | Base URL for Try-It requests |
+| `theme` | `"light" \| "dark" \| "auto"` | `"auto"` | Theme for embedded components |
+| `performanceMetrics` | `Record<string, …>` | — | Per-endpoint metrics keyed `"METHOD /path"` (you supply `p50Ms`/`p95Ms`/`p99Ms`/`errorRatePct`/`requestsPerMinute`) |
+
+Each endpoint renders as a collapsible card with Docs / Try It / Performance tabs, delegating to the `EndpointViewer`, `TryIt`, and `PerformanceOverlay` components from `@apifn/react` / `@apifn/svelte`.
+
+The Try-It base URL is selected in this order: the renderer's `baseUrl` prop, the provider's `baseUrl` embedded in the entry, the first URL in `entry.spec.servers`, then `https://api.example.com` as a placeholder fallback.
+
+---
+
+## How it plugs into docsfn
+
+`createApifnProvider(...)` yields a `DocsContentProvider` suitable for a docsfn content pipeline. Each `RawContentEntry` carries `kind: "api"`, a `sidebar` group for navigation, and the full `spec`. Register the provider and the appropriate `ApifnApiReference` renderer in your docsfn application according to its integration API.
+
+## Exports
+
+```typescript
+export { createApifnProvider }
+export type {
+  DocsContentProvider, RawContentEntry, ApiEndpoint,
+  SidebarItem, SidebarLink, SidebarGroup,
+  CreateApifnProviderOptions, ApifnApiReferenceProps,
+  OpenAPIDocument, OperationObject,
+}
+// React: import { ApifnApiReference } from "@apifn/docsfn/react"
+// Svelte: import ApifnApiReference from "@apifn/docsfn/svelte"
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -18,11 +18,11 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var index_exports = {};
-__export(index_exports, {
+var src_exports = {};
+__export(src_exports, {
   createApifnProvider: () => createApifnProvider
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_exports);
 
 // src/provider.ts
 var import_promises = require("fs/promises");
@@ -45,15 +45,49 @@ function collectEndpoints(spec) {
   const items = [];
   for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
     if (!pathItem) continue;
+    const pathParameters = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
     for (const method of HTTP_METHODS) {
       const op = pathItem[method];
       if (!op) continue;
+      const operation = mergePathParameters(pathParameters, op);
       const tags = op.tags ?? ["default"];
-      items.push({ path, method, operation: op, tag: tags[0] ?? "default" });
+      items.push({ path, method, operation, tag: tags[0] ?? "default" });
     }
   }
   return items;
 }
+function parameterKey(parameter) {
+  if (!parameter || typeof parameter !== "object") {
+    return void 0;
+  }
+  const reference = parameter;
+  if (typeof reference.$ref === "string") {
+    return `$ref:${reference.$ref}`;
+  }
+  const candidate = parameter;
+  if (typeof candidate.name !== "string" || typeof candidate.in !== "string") {
+    return void 0;
+  }
+  return `${candidate.in}:${candidate.name}`;
+}
+function mergePathParameters(pathParameters, operation) {
+  if (pathParameters.length === 0) {
+    return operation;
+  }
+  const operationParameters = Array.isArray(operation.parameters) ? operation.parameters : [];
+  const operationKeys = new Set(operationParameters.map(parameterKey).filter((key) => Boolean(key)));
+  const inheritedParameters = pathParameters.filter((parameter) => {
+    const key = parameterKey(parameter);
+    return !key || !operationKeys.has(key);
+  });
+  if (inheritedParameters.length === 0) {
+    return operation;
+  }
+  return {
+    ...operation,
+    parameters: [...inheritedParameters, ...operationParameters]
+  };
+}
 function buildSidebarGroup(groupLabel, endpoints, slug) {
   const links = endpoints.map((e) => ({
     type: "link",
@@ -80,7 +114,8 @@ function buildEntries(spec, options) {
       title,
       endpoints: allEndpoints,
       sidebar,
-      spec
+      spec,
+      ...baseUrl !== void 0 ? { baseUrl } : {}
     }];
   }
   const tagMap = /* @__PURE__ */ new Map();
@@ -99,7 +134,8 @@ function buildEntries(spec, options) {
       tag,
       endpoints,
       sidebar,
-      spec
+      spec,
+      ...baseUrl !== void 0 ? { baseUrl } : {}
     };
   });
 }

package/dist/index.cjs.map

@@ -1 +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":[]}
+{"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\ntype OperationParameters = NonNullable<OperationObject[\"parameters\"]>;\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        const pathParameters = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];\n        for (const method of HTTP_METHODS) {\n            const op = pathItem[method] as OperationObject | undefined;\n            if (!op) continue;\n            const operation = mergePathParameters(pathParameters, op);\n            const tags = (op.tags as string[]) ?? [\"default\"];\n            items.push({ path, method, operation, tag: tags[0] ?? \"default\" });\n        }\n    }\n    return items;\n}\n\nfunction parameterKey(parameter: unknown): string | undefined {\n    if (!parameter || typeof parameter !== \"object\") {\n        return undefined;\n    }\n\n    const reference = parameter as { $ref?: unknown };\n    if (typeof reference.$ref === \"string\") {\n        return `$ref:${reference.$ref}`;\n    }\n\n    const candidate = parameter as { name?: unknown; in?: unknown };\n    if (typeof candidate.name !== \"string\" || typeof candidate.in !== \"string\") {\n        return undefined;\n    }\n\n    return `${candidate.in}:${candidate.name}`;\n}\n\nfunction mergePathParameters(pathParameters: OperationParameters, operation: OperationObject): OperationObject {\n    if (pathParameters.length === 0) {\n        return operation;\n    }\n\n    const operationParameters: OperationParameters = Array.isArray(operation.parameters) ? operation.parameters : [];\n    const operationKeys = new Set(operationParameters.map(parameterKey).filter((key): key is string => Boolean(key)));\n    const inheritedParameters = pathParameters.filter((parameter) => {\n        const key = parameterKey(parameter);\n        return !key || !operationKeys.has(key);\n    });\n\n    if (inheritedParameters.length === 0) {\n        return operation;\n    }\n\n    return {\n        ...operation,\n        parameters: [...inheritedParameters, ...operationParameters],\n    };\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            ...(baseUrl !== undefined ? { baseUrl } : {}),\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            ...(baseUrl !== undefined ? { baseUrl } : {}),\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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOA,sBAAyB;AACzB,uBAAwB;AACxB,kBAAyE;AAUzE,IAAM,eAAe;AAAA,EACjB;AAAA,EAAO;AAAA,EAAQ;AAAA,EAAO;AAAA,EAAS;AAAA,EAAU;AAAA,EAAQ;AACrD;AAMA,SAAS,UAAU,KAAa,UAA0B;AACtD,QAAM,UAAU,IAAI,YAAY,EAAE,QAAQ,eAAe,GAAG;AAC5D,SAAO,GAAG,SAAS,QAAQ,OAAO,EAAE,CAAC,IAAI,OAAO;AACpD;AAEA,SAAS,iBAAiB,MAAsC;AAC5D,QAAM,QAAuB,CAAC;AAC9B,aAAW,CAAC,MAAM,QAAQ,KAAK,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,GAAG;AAC7D,QAAI,CAAC,SAAU;AACf,UAAM,iBAAiB,MAAM,QAAQ,SAAS,UAAU,IAAI,SAAS,aAAa,CAAC;AACnF,eAAW,UAAU,cAAc;AAC/B,YAAM,KAAK,SAAS,MAAM;AAC1B,UAAI,CAAC,GAAI;AACT,YAAM,YAAY,oBAAoB,gBAAgB,EAAE;AACxD,YAAM,OAAQ,GAAG,QAAqB,CAAC,SAAS;AAChD,YAAM,KAAK,EAAE,MAAM,QAAQ,WAAW,KAAK,KAAK,CAAC,KAAK,UAAU,CAAC;AAAA,IACrE;AAAA,EACJ;AACA,SAAO;AACX;AAEA,SAAS,aAAa,WAAwC;AAC1D,MAAI,CAAC,aAAa,OAAO,cAAc,UAAU;AAC7C,WAAO;AAAA,EACX;AAEA,QAAM,YAAY;AAClB,MAAI,OAAO,UAAU,SAAS,UAAU;AACpC,WAAO,QAAQ,UAAU,IAAI;AAAA,EACjC;AAEA,QAAM,YAAY;AAClB,MAAI,OAAO,UAAU,SAAS,YAAY,OAAO,UAAU,OAAO,UAAU;AACxE,WAAO;AAAA,EACX;AAEA,SAAO,GAAG,UAAU,EAAE,IAAI,UAAU,IAAI;AAC5C;AAEA,SAAS,oBAAoB,gBAAqC,WAA6C;AAC3G,MAAI,eAAe,WAAW,GAAG;AAC7B,WAAO;AAAA,EACX;AAEA,QAAM,sBAA2C,MAAM,QAAQ,UAAU,UAAU,IAAI,UAAU,aAAa,CAAC;AAC/G,QAAM,gBAAgB,IAAI,IAAI,oBAAoB,IAAI,YAAY,EAAE,OAAO,CAAC,QAAuB,QAAQ,GAAG,CAAC,CAAC;AAChH,QAAM,sBAAsB,eAAe,OAAO,CAAC,cAAc;AAC7D,UAAM,MAAM,aAAa,SAAS;AAClC,WAAO,CAAC,OAAO,CAAC,cAAc,IAAI,GAAG;AAAA,EACzC,CAAC;AAED,MAAI,oBAAoB,WAAW,GAAG;AAClC,WAAO;AAAA,EACX;AAEA,SAAO;AAAA,IACH,GAAG;AAAA,IACH,YAAY,CAAC,GAAG,qBAAqB,GAAG,mBAAmB;AAAA,EAC/D;AACJ;AAEA,SAAS,kBACL,YACA,WACA,MACY;AACZ,QAAM,QAAuB,UAAU,IAAI,CAAC,OAAO;AAAA,IAC/C,MAAM;AAAA,IACN,OAAO,GAAG,EAAE,OAAO,YAAY,CAAC,IAAI,EAAE,IAAI;AAAA,IAC1C,MAAM,GAAG,IAAI,IAAI,EAAE,OAAO,YAAY,CAAC,IAAI,EAAE,KAAK,QAAQ,eAAe,GAAG,CAAC;AAAA,EACjF,EAAE;AACF,SAAO,EAAE,MAAM,SAAS,OAAO,YAAY,OAAO,MAAM;AAC5D;AAEA,SAAS,aACL,MACA,SACiB;AACjB,QAAM;AAAA,IACF,WAAW;AAAA,IACX,aAAa;AAAA,IACb;AAAA,EACJ,IAAI;AAEJ,QAAM,OAAO,KAAK;AAClB,QAAM,eAAe,iBAAiB,IAAI;AAE1C,MAAI,CAAC,YAAY;AAEb,UAAM,OAAO,SAAS,QAAQ,OAAO,EAAE,KAAK;AAC5C,UAAM,QAAQ,MAAM,SAAS;AAC7B,UAAM,UAAU,kBAAkB,OAAO,cAAc,IAAI;AAC3D,WAAO,CAAC;AAAA,MACJ,MAAM;AAAA,MACN;AAAA,MACA;AAAA,MACA,WAAW;AAAA,MACX;AAAA,MACA;AAAA,MACA,GAAI,YAAY,SAAY,EAAE,QAAQ,IAAI,CAAC;AAAA,IAC/C,CAAC;AAAA,EACL;AAGA,QAAM,SAAS,oBAAI,IAA2B;AAC9C,aAAW,YAAY,cAAc;AACjC,QAAI,CAAC,OAAO,IAAI,SAAS,GAAG,EAAG,QAAO,IAAI,SAAS,KAAK,CAAC,CAAC;AAC1D,WAAO,IAAI,SAAS,GAAG,EAAG,KAAK,QAAQ;AAAA,EAC3C;AAEA,SAAO,CAAC,GAAG,OAAO,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,SAAS,MAAM;AACnD,UAAM,OAAO,UAAU,KAAK,QAAQ;AACpC,UAAM,QAAQ,GAAG,IAAI,OAAO,CAAC,EAAE,YAAY,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC;AAC3D,UAAM,UAAU,kBAAkB,OAAO,WAAW,IAAI;AACxD,WAAO;AAAA,MACH,MAAM;AAAA,MACN;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAI,YAAY,SAAY,EAAE,QAAQ,IAAI,CAAC;AAAA,IAC/C;AAAA,EACJ,CAAC;AACL;AAWO,SAAS,oBACZ,SACmB;AACnB,MAAI,gBAA0C;AAE9C,iBAAe,WAAqC;AAChD,QAAI,QAAQ,KAAM,QAAO,QAAQ;AACjC,QAAI,QAAQ,UAAU;AAClB,YAAM,UAAM,0BAAQ,QAAQ,QAAQ;AACpC,YAAM,MAAM,UAAM,0BAAS,KAAK,MAAM;AACtC,iBAAO,0BAAa,GAAG;AAAA,IAC3B;AACA,UAAM,IAAI,MAAM,+DAA+D;AAAA,EACnF;AAEA,QAAM,WAAW,YAAwC;AACrD,QAAI,cAAe,QAAO;AAC1B,UAAM,OAAO,MAAM,SAAS;AAC5B,oBAAgB,aAAa,MAAM,OAAO;AAC1C,aAAS,UAAU;AACnB,WAAO;AAAA,EACX;AAEA,WAAS,UAAU,CAAC;AACpB,SAAO;AACX;","names":[]}

package/dist/index.d.cts

@@ -1,98 +1,7 @@
-import { OperationObject, OpenAPIDocument } from '@apifn/core';
+import { C as CreateApifnProviderOptions, D as DocsContentProvider } from './types-D4LTWU9V.cjs';
+export { A as ApiEndpoint, a as ApifnApiReferenceProps, R as RawContentEntry, S as SidebarGroup, b as SidebarItem, c as SidebarLink } from './types-D4LTWU9V.cjs';
 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).
  *
@@ -109,4 +18,4 @@ interface ApifnApiReferenceProps {
  */
 declare function createApifnProvider(options: CreateApifnProviderOptions): DocsContentProvider;
 
-export { type ApiEndpoint, type ApifnApiReferenceProps, type CreateApifnProviderOptions, type DocsContentProvider, type RawContentEntry, type SidebarGroup, type SidebarItem, type SidebarLink, createApifnProvider };
+export { CreateApifnProviderOptions, DocsContentProvider, createApifnProvider };

package/dist/index.d.ts

@@ -1,98 +1,7 @@
-import { OperationObject, OpenAPIDocument } from '@apifn/core';
+import { C as CreateApifnProviderOptions, D as DocsContentProvider } from './types-D4LTWU9V.js';
+export { A as ApiEndpoint, a as ApifnApiReferenceProps, R as RawContentEntry, S as SidebarGroup, b as SidebarItem, c as SidebarLink } from './types-D4LTWU9V.js';
 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).
  *
@@ -109,4 +18,4 @@ interface ApifnApiReferenceProps {
  */
 declare function createApifnProvider(options: CreateApifnProviderOptions): DocsContentProvider;
 
-export { type ApiEndpoint, type ApifnApiReferenceProps, type CreateApifnProviderOptions, type DocsContentProvider, type RawContentEntry, type SidebarGroup, type SidebarItem, type SidebarLink, createApifnProvider };
+export { CreateApifnProviderOptions, DocsContentProvider, createApifnProvider };

package/dist/index.js

@@ -19,15 +19,49 @@ function collectEndpoints(spec) {
   const items = [];
   for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
     if (!pathItem) continue;
+    const pathParameters = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
     for (const method of HTTP_METHODS) {
       const op = pathItem[method];
       if (!op) continue;
+      const operation = mergePathParameters(pathParameters, op);
       const tags = op.tags ?? ["default"];
-      items.push({ path, method, operation: op, tag: tags[0] ?? "default" });
+      items.push({ path, method, operation, tag: tags[0] ?? "default" });
     }
   }
   return items;
 }
+function parameterKey(parameter) {
+  if (!parameter || typeof parameter !== "object") {
+    return void 0;
+  }
+  const reference = parameter;
+  if (typeof reference.$ref === "string") {
+    return `$ref:${reference.$ref}`;
+  }
+  const candidate = parameter;
+  if (typeof candidate.name !== "string" || typeof candidate.in !== "string") {
+    return void 0;
+  }
+  return `${candidate.in}:${candidate.name}`;
+}
+function mergePathParameters(pathParameters, operation) {
+  if (pathParameters.length === 0) {
+    return operation;
+  }
+  const operationParameters = Array.isArray(operation.parameters) ? operation.parameters : [];
+  const operationKeys = new Set(operationParameters.map(parameterKey).filter((key) => Boolean(key)));
+  const inheritedParameters = pathParameters.filter((parameter) => {
+    const key = parameterKey(parameter);
+    return !key || !operationKeys.has(key);
+  });
+  if (inheritedParameters.length === 0) {
+    return operation;
+  }
+  return {
+    ...operation,
+    parameters: [...inheritedParameters, ...operationParameters]
+  };
+}
 function buildSidebarGroup(groupLabel, endpoints, slug) {
   const links = endpoints.map((e) => ({
     type: "link",
@@ -54,7 +88,8 @@ function buildEntries(spec, options) {
       title,
       endpoints: allEndpoints,
       sidebar,
-      spec
+      spec,
+      ...baseUrl !== void 0 ? { baseUrl } : {}
     }];
   }
   const tagMap = /* @__PURE__ */ new Map();
@@ -73,7 +108,8 @@ function buildEntries(spec, options) {
       tag,
       endpoints,
       sidebar,
-      spec
+      spec,
+      ...baseUrl !== void 0 ? { baseUrl } : {}
     };
   });
 }

package/dist/index.js.map

@@ -1 +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":[]}
+{"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\ntype OperationParameters = NonNullable<OperationObject[\"parameters\"]>;\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        const pathParameters = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];\n        for (const method of HTTP_METHODS) {\n            const op = pathItem[method] as OperationObject | undefined;\n            if (!op) continue;\n            const operation = mergePathParameters(pathParameters, op);\n            const tags = (op.tags as string[]) ?? [\"default\"];\n            items.push({ path, method, operation, tag: tags[0] ?? \"default\" });\n        }\n    }\n    return items;\n}\n\nfunction parameterKey(parameter: unknown): string | undefined {\n    if (!parameter || typeof parameter !== \"object\") {\n        return undefined;\n    }\n\n    const reference = parameter as { $ref?: unknown };\n    if (typeof reference.$ref === \"string\") {\n        return `$ref:${reference.$ref}`;\n    }\n\n    const candidate = parameter as { name?: unknown; in?: unknown };\n    if (typeof candidate.name !== \"string\" || typeof candidate.in !== \"string\") {\n        return undefined;\n    }\n\n    return `${candidate.in}:${candidate.name}`;\n}\n\nfunction mergePathParameters(pathParameters: OperationParameters, operation: OperationObject): OperationObject {\n    if (pathParameters.length === 0) {\n        return operation;\n    }\n\n    const operationParameters: OperationParameters = Array.isArray(operation.parameters) ? operation.parameters : [];\n    const operationKeys = new Set(operationParameters.map(parameterKey).filter((key): key is string => Boolean(key)));\n    const inheritedParameters = pathParameters.filter((parameter) => {\n        const key = parameterKey(parameter);\n        return !key || !operationKeys.has(key);\n    });\n\n    if (inheritedParameters.length === 0) {\n        return operation;\n    }\n\n    return {\n        ...operation,\n        parameters: [...inheritedParameters, ...operationParameters],\n    };\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            ...(baseUrl !== undefined ? { baseUrl } : {}),\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            ...(baseUrl !== undefined ? { baseUrl } : {}),\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":[]}