apiuikit 1.1.0 → 1.2.0

package/dist/helpers/llmsTxt.d.ts

@@ -0,0 +1,51 @@
+import { MarkdownTarget } from '../config/config';
+import { DocumentTarget } from './specAdapters';
+export type { DocumentTarget };
+export interface LlmsTxtLink {
+    label: string;
+    url: string;
+    description?: string;
+}
+export interface LlmsTxtOptions {
+    /**
+     * Absolute base URL of the docs site, e.g. `"https://docs.acme.com"`. Used
+     * to build a default URL per entry; ignore it entirely by passing `url`.
+     */
+    baseUrl?: string;
+    /**
+     * The URL serving an entry as Markdown. Return `null` to leave an entry out
+     * of the index. Defaults to `${baseUrl}/${slug}.md`, which is a guess at
+     * your routes: pass this whenever they differ, which is most of the time.
+     */
+    url?: (entry: DocumentTarget) => string | null | undefined;
+    /** Overrides the document's own `info.title`. */
+    title?: string;
+    /** Overrides the document's own `info.description`. */
+    summary?: string;
+    /**
+     * Extra links for the trailing "Optional" section: the source spec, a
+     * changelog, a support page. Serving the raw spec here (e.g.
+     * `https://docs.acme.com/openapi.yaml`) is worth doing, since an agent can
+     * consume it directly instead of reading prose.
+     */
+    optional?: LlmsTxtLink[];
+}
+/** URL-safe slug from a target key: `"get /pets/{petId}"` to `"get-pets-petid"`. */
+export declare function targetSlug(key: string): string;
+/**
+ * Every linkable item in a document: OpenAPI endpoints, AsyncAPI operations.
+ * Each carries the `target` to hand `documentToMarkdown`, so generating a file
+ * per entry is a loop over this list.
+ */
+export declare function listDocumentTargets(document: unknown): DocumentTarget[];
+/**
+ * Serializes a document to Markdown. Pass a `target` from
+ * `listDocumentTargets` for a single endpoint/operation, or omit it for the
+ * whole document.
+ */
+export declare function documentToMarkdown(document: unknown, target?: MarkdownTarget): string;
+/**
+ * Builds an `llms.txt` index for a document, in the llmstxt.org format: an H1
+ * name, a blockquote summary, then one described link per endpoint/operation.
+ */
+export declare function documentToLlmsTxt(document: unknown, options?: LlmsTxtOptions): string;

package/dist/helpers/specAdapters.d.ts

@@ -0,0 +1,32 @@
+import { MarkdownTarget } from '../config/config';
+/** One linkable item in a document: an OpenAPI endpoint, an AsyncAPI operation, ... */
+export interface DocumentTarget {
+    /** Stable identifier, unique within the document. `"get /pets"`, `"sendLightMeasurement"`. */
+    key: string;
+    /** Human-readable label for a link or heading. `"GET /pets"`. */
+    label: string;
+    /** The document's own one-line summary for this item, when it has one. */
+    summary?: string;
+    /** Passed to `documentToMarkdown`, and the same shape `config.markdown.url` receives. */
+    target: MarkdownTarget;
+}
+interface SpecAdapter {
+    /** Spec name, used in error messages. */
+    name: string;
+    /** Whether this adapter handles the document, sniffed from its version key. */
+    matches: (doc: Record<string, unknown>) => boolean;
+    /** What the linkable items are called collectively, e.g. "Endpoints". */
+    sectionTitle: string;
+    title: (doc: unknown) => string;
+    summary: (doc: unknown) => string | undefined;
+    targets: (doc: unknown) => DocumentTarget[];
+    toMarkdown: (doc: unknown, target?: MarkdownTarget) => string;
+}
+/**
+ * Picks the adapter for a document by sniffing its version key (`openapi`,
+ * `swagger`, `asyncapi`), the same discriminant the renderers use to choose a
+ * component. Throws rather than guessing: silently treating an unrecognized
+ * document as one spec would emit confidently wrong output.
+ */
+export declare function adapterFor(document: unknown): SpecAdapter;
+export {};

package/dist/helpers/toMarkdown.d.ts

@@ -1,13 +1,13 @@
 import { AsyncAPIDocumentData } from '../types/schema';
 import { HttpMethod, OpenAPIDocumentData } from '../types/openapi';
-type Deref = (ref: string) => unknown;
-export declare function asyncApiToMarkdown(doc: AsyncAPIDocumentData, deref: Deref): string;
+import { Deref } from './jsonPointer';
+export declare function asyncApiToMarkdown(doc: AsyncAPIDocumentData, deref?: Deref): string;
 /** Builds a self-contained Markdown snippet for a single AsyncAPI operation:
  * doc info + servers, followed by that one operation's section (see
  * `operationSectionToMarkdown`). Used by the per-operation copy button, as
  * opposed to `asyncApiToMarkdown`'s whole-document export. */
-export declare function asyncApiOperationToMarkdown(doc: AsyncAPIDocumentData, key: string, deref: Deref): string;
-export declare function openApiToMarkdown(doc: OpenAPIDocumentData, deref: Deref): string;
+export declare function asyncApiOperationToMarkdown(doc: AsyncAPIDocumentData, key: string, deref?: Deref): string;
+export declare function openApiToMarkdown(doc: OpenAPIDocumentData, deref?: Deref): string;
 /**
  * Builds a self-contained Markdown snippet for a single OpenAPI endpoint:
  * doc info + servers (so the snippet stands alone without the rest of the
@@ -16,5 +16,4 @@ export declare function openApiToMarkdown(doc: OpenAPIDocumentData, deref: Deref
  * Endpoints side panel (Paths.tsx), as opposed to `openApiToMarkdown`'s
  * whole-document export.
  */
-export declare function openApiEndpointToMarkdown(doc: OpenAPIDocumentData, method: HttpMethod, path: string, deref: Deref): string;
-export {};
+export declare function openApiEndpointToMarkdown(doc: OpenAPIDocumentData, method: HttpMethod, path: string, deref?: Deref): string;

package/dist/hooks/useDocumentProviderValue.d.ts

@@ -1,4 +1,5 @@
 import { ConfigInterface } from '../config';
+import { MarkdownUrlResolver } from '../config/config';
 import { SpecType } from '../contexts';
 /**
  * Builds the shared DocumentContext value (deref resolver, portal/root refs,
@@ -13,13 +14,14 @@ export declare function useDocumentProviderValue<S extends SpecType, D extends o
     contextValue: {
         specType: S;
         document: D;
-        deref: (refPath: string) => unknown;
+        deref: import('../helpers/jsonPointer').Deref;
         portalHost: HTMLDivElement | null;
         rootElement: HTMLDivElement | null;
         defaultSchemaExpanded: boolean;
         depthColors: string[];
         showExtensions: boolean;
         showCodeSamples: boolean;
+        markdownUrl: MarkdownUrlResolver | undefined;
     };
     themeVars: Record<string, string>;
     setPortalHost: import('react').Dispatch<import('react').SetStateAction<HTMLDivElement | null>>;