@stainless-api/docs-ui 0.1.0-beta.7 → 0.1.0-beta.70

package/dist/snippets-BehbU3rt.js

@@ -0,0 +1,164 @@
+import { i as useDeclaration, s as useLanguage, u as useSnippet } from "./docs-BmOB2f-I.js";
+import { r as useHighlight } from "./markdown-CTKHMLVr.js";
+import { t as useComponents } from "./use-components-BUz3GbO4.js";
+import { t as style_default } from "./style-HpXpcJ9v.js";
+import * as React$1 from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import clsx from "clsx";
+import { CheckIcon, CircleAlertIcon, CopyIcon } from "lucide-react";
+import { Badge, Button, getHttpMethod } from "@stainless-api/ui-primitives";
+
+//#region src/components/snippets.tsx
+function SnippetCode({ content, language }) {
+	const lang = useLanguage();
+	const highlighted = useHighlight(content, language || lang);
+	return /* @__PURE__ */ jsx("div", {
+		className: style_default.SnippetCode,
+		"data-stldocs-copy-content": true,
+		dangerouslySetInnerHTML: { __html: highlighted }
+	});
+}
+function SnippetContainer({ children }) {
+	return /* @__PURE__ */ jsx("div", {
+		className: clsx(style_default.Snippet),
+		children
+	});
+}
+function SnippetRequestContainer({ children }) {
+	return /* @__PURE__ */ jsx("div", { children });
+}
+function Snippet({ requestTitle, method, transformRequestSnippet }) {
+	const Docs = useComponents();
+	const language = useLanguage();
+	const originalSnippet = useSnippet(method.stainlessPath, void 0, language === "http" ? "curl" : "default");
+	const decl = useDeclaration(method.stainlessPath, false);
+	if (!originalSnippet) {
+		console.warn(`Snippet not found for method '${method.stainlessPath}'`);
+		return null;
+	}
+	const signature = decl && "qualified" in decl ? decl.qualified : void 0;
+	const responses = method.exampleResponses;
+	const snippet = transformRequestSnippet ? transformRequestSnippet({
+		snippet: originalSnippet,
+		language
+	}) : originalSnippet;
+	const httpMethod = getHttpMethod(method.httpMethod);
+	return /* @__PURE__ */ jsxs(Docs.SnippetContainer, {
+		signature,
+		method,
+		children: [snippet && /* @__PURE__ */ jsx(Docs.SnippetRequestContainer, {
+			signature,
+			children: /* @__PURE__ */ jsxs("div", {
+				className: style_default.SnippetRequest,
+				"data-stldocs-copy-parent": true,
+				children: [
+					/* @__PURE__ */ jsxs("div", {
+						className: style_default.SnippetRequestTitle,
+						children: [
+							/* @__PURE__ */ jsxs("div", {
+								className: style_default.SnippetRequestTitleMethod,
+								children: [httpMethod && /* @__PURE__ */ jsx(Badge.HTTP, {
+									method: httpMethod,
+									iconOnly: true
+								}), /* @__PURE__ */ jsx("h3", { children: method.summary || method.title })]
+							}),
+							/* @__PURE__ */ jsx("div", {
+								className: style_default.SnippetRequestTitleContent,
+								children: requestTitle
+							}),
+							/* @__PURE__ */ jsx(Docs.SnippetButtons, { content: snippet })
+						]
+					}),
+					/* @__PURE__ */ jsx(Docs.SnippetCode, {
+						content: snippet,
+						signature
+					}),
+					/* @__PURE__ */ jsx(Docs.SnippetFooter, {})
+				]
+			})
+		}), responses && /* @__PURE__ */ jsx(Docs.SnippetResponse, { responses })]
+	});
+}
+function SnippetButtons({ content }) {
+	const [CopyButtonIcon, setCopyIcon] = React$1.useState(CopyIcon);
+	async function handleCopy() {
+		try {
+			await navigator.clipboard.writeText(content);
+			setCopyIcon(CheckIcon);
+		} catch {
+			setCopyIcon(CircleAlertIcon);
+		}
+		setTimeout(() => setCopyIcon(CopyIcon), 1e3);
+	}
+	return /* @__PURE__ */ jsx(Button, {
+		variant: "outline",
+		"data-stldocs-snippet-copy": true,
+		children: /* @__PURE__ */ jsx(CopyButtonIcon, {
+			size: 16,
+			className: style_default.Icon,
+			onClick: handleCopy
+		})
+	});
+}
+function SnippetFooter() {
+	return null;
+}
+function SnippetResponse({ responses }) {
+	const { SnippetCode } = useComponents();
+	if (!responses) return null;
+	const mappedResponses = Object.keys(responses).map((key) => {
+		const responseContent = responses[key];
+		if (!responseContent) return null;
+		const responseType = Object.keys(responseContent)[0];
+		if (!responseType) return null;
+		const response = responseContent[responseType];
+		if (!response) return null;
+		const examples = response?.examples;
+		if (!examples) return null;
+		const exampleType = Object.keys(examples)[0];
+		if (!exampleType) return null;
+		let value = examples[exampleType]?.value;
+		if (!value) return null;
+		let language = "none";
+		if (responseType === "application/json" || typeof value === "object") {
+			language = "json";
+			value = JSON.stringify(value, null, 2);
+		}
+		return {
+			language,
+			responseCode: key,
+			content: value
+		};
+	}).filter(Boolean);
+	if (mappedResponses.length === 0) return null;
+	return /* @__PURE__ */ jsx("div", {
+		className: style_default.SnippetMultiResponse,
+		children: /* @__PURE__ */ jsxs("div", {
+			className: clsx(style_default.Snippet),
+			children: [/* @__PURE__ */ jsx("div", {
+				className: clsx(style_default.SnippetResponseTab, mappedResponses.length === 1 && style_default.SnippetResponseTabSingleReturn),
+				children: mappedResponses.map(({ responseCode }, index) => /* @__PURE__ */ jsx("div", {
+					"data-snippet-response-tab-id": `snippet-response-tab-${responseCode}-${index}`,
+					className: clsx(style_default.SnippetResponseTabItem, index === 0 && style_default.SnippetResponseTabItemActive),
+					children: /* @__PURE__ */ jsxs(Button, {
+						disabled: mappedResponses.length === 1,
+						variant: "ghost",
+						children: [responseCode, " example"]
+					})
+				}, `snippet-response-tab-item-${responseCode}-${index}`))
+			}), mappedResponses.map(({ responseCode, content, language }, index) => {
+				return /* @__PURE__ */ jsx("div", {
+					className: clsx(style_default.SnippetResponsePane, index === 0 && style_default.SnippetResponsePaneActive),
+					"data-snippet-response-pane-id": `snippet-response-tab-${responseCode}-${index}`,
+					children: /* @__PURE__ */ jsx(SnippetCode, {
+						content,
+						language
+					})
+				}, `snippet-response-${responseCode}-${index}`);
+			})]
+		})
+	});
+}
+
+//#endregion
+export { SnippetFooter as a, SnippetContainer as i, SnippetButtons as n, SnippetRequestContainer as o, SnippetCode as r, SnippetResponse as s, Snippet as t };

package/dist/snippets-Bj7Ey56K.d.ts

@@ -0,0 +1,53 @@
+import { d as Method, o as HasStainlessPath } from "./index-CwjGm9zX.js";
+import { w as TransformRequestSnippetFn } from "./sdk-BvZeXpsj.js";
+import * as React$1 from "react";
+import * as react_jsx_runtime50 from "react/jsx-runtime";
+
+//#region src/components/snippets.d.ts
+type SnippetCodeProps = {
+  content: string;
+  signature?: string;
+  language?: string;
+};
+declare function SnippetCode({
+  content,
+  language
+}: SnippetCodeProps): react_jsx_runtime50.JSX.Element;
+type SnippetProps = {
+  method: Partial<Method> & HasStainlessPath;
+  requestTitle?: React$1.ReactNode;
+  transformRequestSnippet?: TransformRequestSnippetFn;
+};
+type SnippetContainerProps = {
+  method: Partial<Method> & HasStainlessPath;
+  children: React$1.ReactNode;
+  signature?: string;
+};
+declare function SnippetContainer({
+  children
+}: SnippetContainerProps): react_jsx_runtime50.JSX.Element;
+type SnippetRequestContainerProps = {
+  children?: React$1.ReactNode;
+  signature?: string;
+};
+declare function SnippetRequestContainer({
+  children
+}: SnippetRequestContainerProps): react_jsx_runtime50.JSX.Element;
+declare function Snippet({
+  requestTitle,
+  method,
+  transformRequestSnippet
+}: SnippetProps): react_jsx_runtime50.JSX.Element | null;
+declare function SnippetButtons({
+  content
+}: {
+  content: string;
+}): react_jsx_runtime50.JSX.Element;
+declare function SnippetFooter(): React$1.ReactNode;
+declare function SnippetResponse({
+  responses
+}: {
+  responses: Method['exampleResponses'];
+}): react_jsx_runtime50.JSX.Element | null;
+//#endregion
+export { SnippetContainer as a, SnippetProps as c, SnippetResponse as d, SnippetCodeProps as i, SnippetRequestContainer as l, SnippetButtons as n, SnippetContainerProps as o, SnippetCode as r, SnippetFooter as s, Snippet as t, SnippetRequestContainerProps as u };

package/dist/snippets-CQQSDvg2.d.ts

@@ -0,0 +1,53 @@
+import { d as Method, o as HasStainlessPath } from "./index-CwjGm9zX.js";
+import { w as TransformRequestSnippetFn } from "./sdk-GMOw94wL.js";
+import * as React$1 from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/snippets.d.ts
+type SnippetCodeProps = {
+  content: string;
+  signature?: string;
+  language?: string;
+};
+declare function SnippetCode({
+  content,
+  language
+}: SnippetCodeProps): react_jsx_runtime0.JSX.Element;
+type SnippetProps = {
+  method: Partial<Method> & HasStainlessPath;
+  requestTitle?: React$1.ReactNode;
+  transformRequestSnippet?: TransformRequestSnippetFn;
+};
+type SnippetContainerProps = {
+  method: Partial<Method> & HasStainlessPath;
+  children: React$1.ReactNode;
+  signature?: string;
+};
+declare function SnippetContainer({
+  children
+}: SnippetContainerProps): react_jsx_runtime0.JSX.Element;
+type SnippetRequestContainerProps = {
+  children?: React$1.ReactNode;
+  signature?: string;
+};
+declare function SnippetRequestContainer({
+  children
+}: SnippetRequestContainerProps): react_jsx_runtime0.JSX.Element;
+declare function Snippet({
+  requestTitle,
+  method,
+  transformRequestSnippet
+}: SnippetProps): react_jsx_runtime0.JSX.Element | null;
+declare function SnippetButtons({
+  content
+}: {
+  content: string;
+}): react_jsx_runtime0.JSX.Element;
+declare function SnippetFooter(): React$1.ReactNode;
+declare function SnippetResponse({
+  responses
+}: {
+  responses: Method['exampleResponses'];
+}): react_jsx_runtime0.JSX.Element | null;
+//#endregion
+export { SnippetContainer as a, SnippetProps as c, SnippetResponse as d, SnippetCodeProps as i, SnippetRequestContainer as l, SnippetButtons as n, SnippetContainerProps as o, SnippetCode as r, SnippetFooter as s, Snippet as t, SnippetRequestContainerProps as u };

package/dist/spec.d.ts

@@ -0,0 +1,65 @@
+import { _ as Spec, d as Method, f as Model, i as DeclarationNode, m as Resource, v as SpecLanguage } from "./index-CwjGm9zX.js";
+import { t as DocsLanguage } from "./routing-Cm_9XJiQ.js";
+
+//#region src/spec.d.ts
+type SecurityScheme = Spec['security_schemes'][number];
+interface SpecTransforms {
+  resource(resource: Resource): Resource;
+  method(method: Method): Method;
+  model(model: Model): Model;
+  declaration(decl: DeclarationNode, language: SpecLanguage): DeclarationNode;
+  securityScheme(scheme: SecurityScheme): SecurityScheme;
+  snippet(snippet: string, language: string): string;
+  markdown(content?: string): string | undefined;
+}
+declare function defineTransforms(transforms?: Partial<SpecTransforms>): {
+  resource: (resource: Resource) => Resource;
+  method: (method: Method) => Method;
+  model: (model: Model) => Model;
+  declaration: (decl: DeclarationNode, language: SpecLanguage) => DeclarationNode;
+  securityScheme: (scheme: SecurityScheme) => SecurityScheme;
+  snippet: (snippet: string, language: string) => string;
+  markdown: (content?: string) => string | undefined;
+};
+declare function generateNavigation(resource: Partial<Resource>): {
+  title: string | undefined;
+  name: string | undefined;
+  subresources: Record<string, Partial<Resource>> | undefined;
+  methods: Record<string, Partial<Method>> | undefined;
+  models: Record<string, Partial<Model>> | undefined;
+  stainlessPath: string | undefined;
+  terraform: {
+    Name: string;
+    QualifiedName: string;
+  } | undefined;
+};
+declare function generateSpecForResource(spec: Spec, name: string, lang: DocsLanguage, transforms: SpecTransforms): Partial<Spec>;
+declare function transform(spec: Spec, transforms: SpecTransforms): {
+  name: string;
+  lang: "http" | "node" | "python" | "go" | "typescript" | "terraform" | "ruby" | "java" | "kotlin" | "csharp" | "php" | "cli";
+  spec: Partial<Spec>;
+}[];
+declare function split(spec: Spec, transforms?: SpecTransforms): {
+  resources: ReturnType<typeof transform>;
+  navigation: {
+    languages: ("http" | "node" | "python" | "go" | "typescript" | "terraform" | "ruby" | "java" | "kotlin")[] | undefined;
+    resources: {
+      [k: string]: {
+        title: string | undefined;
+        name: string | undefined;
+        subresources: Record<string, Partial<Resource>> | undefined;
+        methods: Record<string, Partial<Method>> | undefined;
+        models: Record<string, Partial<Model>> | undefined;
+        stainlessPath: string | undefined;
+        terraform: {
+          Name: string;
+          QualifiedName: string;
+        } | undefined;
+      };
+    };
+  };
+};
+declare function parseSpec(content: string): Spec | undefined;
+declare function retrieve(apiKey: string, project: string, revision: string): Promise<Spec | undefined>;
+//#endregion
+export { SecurityScheme, SpecTransforms, defineTransforms, generateNavigation, generateSpecForResource, parseSpec, retrieve, split, transform };

package/dist/spec.js

@@ -0,0 +1,167 @@
+import { n as Languages } from "./routing-C64k4fmX.js";
+import { i as isResourceEmpty } from "./utils-DPbkW1Tz.js";
+
+//#region src/spec.ts
+const defaultTransforms = {
+	resource: (resource) => resource,
+	method: (method) => method,
+	model: (model) => model,
+	declaration: (decl) => decl,
+	securityScheme: (scheme) => scheme,
+	snippet: (snippet) => snippet,
+	markdown: (content) => content
+};
+function defineTransforms(transforms = {}) {
+	return {
+		...defaultTransforms,
+		...transforms
+	};
+}
+function removeStudioRefs(obj) {
+	if (typeof obj !== "object" || obj === null) return obj;
+	if (Array.isArray(obj)) return obj.map(removeStudioRefs);
+	const newObj = {};
+	for (const [key, value] of Object.entries(obj)) if (key !== "oasRef" && key !== "configRef") newObj[key] = removeStudioRefs(value);
+	return newObj;
+}
+function mapEntries({ input, fn, filter }) {
+	if (!input) return;
+	const output = {};
+	for (const [name, entry] of Object.entries(input)) {
+		if (filter && !filter(name, entry)) continue;
+		output[name] = fn ? fn(entry) : entry;
+	}
+	return output;
+}
+function transformRecursively(resource, transforms) {
+	return {
+		...transforms.resource(resource),
+		methods: mapEntries({
+			input: resource.methods,
+			fn: (method) => transforms.method(method)
+		}) ?? {},
+		models: mapEntries({
+			input: resource.models,
+			fn: (model) => transforms.model(model)
+		}) ?? {},
+		subresources: mapEntries({
+			input: resource.subresources,
+			fn: (sub) => transformRecursively(sub, transforms)
+		}) ?? {}
+	};
+}
+function generateNavigation(resource) {
+	const { title, name, stainlessPath, terraform } = resource;
+	return {
+		title,
+		name,
+		subresources: mapEntries({
+			input: resource.subresources,
+			fn: generateNavigation
+		}),
+		methods: mapEntries({
+			input: resource.methods,
+			fn: (method) => ({
+				name: method.name,
+				stainlessPath: method.stainlessPath,
+				summary: method.summary,
+				httpMethod: method.httpMethod
+			})
+		}),
+		models: mapEntries({
+			input: resource.models,
+			fn: (model) => ({
+				name: model.name,
+				stainlessPath: model.stainlessPath
+			})
+		}),
+		stainlessPath,
+		terraform
+	};
+}
+function generateSpecForResource(spec, name, lang, transforms) {
+	const resource = spec.resources[name];
+	if (!resource) throw new Error(`Invalid resource: ${name}`);
+	return {
+		resources: {
+			[name]: transformRecursively(resource, transforms),
+			...spec.resources["$shared"] ? { $shared: transformRecursively(spec.resources["$shared"], transforms) } : {}
+		},
+		security_schemes: spec.security_schemes?.map((scheme) => transforms.securityScheme(scheme)),
+		decls: { [lang]: mapEntries({
+			input: spec.decls[lang] ?? {},
+			filter: (name) => name.startsWith(resource.stainlessPath) || name.startsWith("(resource) $shared"),
+			fn: (decl) => transforms.declaration(decl, lang)
+		}) },
+		snippets: mapEntries({
+			input: spec.snippets,
+			filter: (name) => name.startsWith(lang),
+			fn: (snippets) => mapEntries({
+				input: snippets,
+				filter: (name) => name.startsWith(resource.stainlessPath),
+				fn: (snippet) => transforms.snippet(snippet, lang)
+			}) ?? {}
+		})
+	};
+}
+function transform(spec, transforms) {
+	const t = {
+		...transforms,
+		declaration: (decl, lang) => transforms.declaration({
+			...decl,
+			..."docstring" in decl ? { docstring: transforms.markdown(decl.docstring) } : {}
+		}, lang),
+		method: (method) => transforms.method({
+			...method,
+			description: transforms.markdown(method.description),
+			deprecated: typeof method.deprecated === "string" ? transforms.markdown(method.deprecated) : method.deprecated
+		}),
+		securityScheme: (scheme) => transforms.securityScheme({
+			...scheme,
+			description: transforms.markdown(scheme.description)
+		})
+	};
+	const output = [];
+	for (const lang of Languages) for (const [name, resource] of Object.entries(spec.resources)) {
+		if (isResourceEmpty(resource)) continue;
+		output.push({
+			name,
+			lang,
+			spec: generateSpecForResource(spec, name, lang, t)
+		});
+	}
+	return output;
+}
+function split(spec, transforms) {
+	return {
+		resources: transform(spec, transforms ?? defineTransforms()).map(removeStudioRefs),
+		navigation: {
+			languages: spec.docs?.languages,
+			resources: Object.fromEntries(Object.entries(spec.resources).filter(([, res]) => !isResourceEmpty(res)).map(([name, res]) => [name, generateNavigation(res)]))
+		}
+	};
+}
+function parseSpec(content) {
+	const parsed = JSON.parse(content);
+	if (parsed && typeof parsed === "object" && "kind" in parsed && parsed.kind === "spec") return parsed;
+}
+async function retrieve(apiKey, project, revision) {
+	const data = await (await fetch("https://app.stainless.com/api/generate/spec", {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({
+			project,
+			source: {
+				type: "git",
+				revision
+			}
+		})
+	})).json();
+	if (typeof data.spec === "string") return parseSpec(data.spec);
+}
+
+//#endregion
+export { defineTransforms, generateNavigation, generateSpecForResource, parseSpec, retrieve, split, transform };

package/dist/stl-sidebar-CXzs_shz.d.ts

@@ -0,0 +1,58 @@
+import { ReactNode } from "react";
+import * as react_jsx_runtime43 from "react/jsx-runtime";
+
+//#region src/components/stl-sidebar.d.ts
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      /**
+       * Custom element defined by Starlight's <SidebarPersister>.
+       */
+      'sl-sidebar-restore': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+type StlSidebarTarget = {
+  type: 'href';
+  href: string;
+} | {
+  type: 'stainlessPath';
+  stainlessPath: string;
+};
+interface StlSidebarLink {
+  type: 'link';
+  icon?: ReactNode;
+  label: string;
+  /** Current sidebar item is highlighted. */
+  isCurrent?: boolean;
+  target: StlSidebarTarget;
+  /** Additional HTML attributes that will be attached to the anchor element. */
+  attrs?: Record<string, unknown>;
+}
+interface StlSidebarGroup {
+  type: 'group';
+  icon?: ReactNode;
+  label: string;
+  entries: Array<StlSidebarLink | StlSidebarGroup>;
+  /** Defaults to true. */
+  collapsible?: boolean;
+  collapsed?: boolean;
+  /** Current sidebar item is highlighted. */
+  isCurrent?: boolean;
+  target?: StlSidebarTarget;
+}
+type StlSidebarEntry = StlSidebarLink | StlSidebarGroup;
+type StlSidebarProps = {
+  entries: StlSidebarEntry[];
+  /**
+   * If set, add <sl-sidebar-restore> custom elements (as defined by Starlight's SidebarPersister)
+   * which are used to save/restore sidebar state.
+   */
+  withStarlightRestoration?: boolean;
+};
+declare function StlSidebar({
+  entries,
+  withStarlightRestoration
+}: StlSidebarProps): react_jsx_runtime43.JSX.Element;
+//#endregion
+export { StlSidebarProps as a, StlSidebarLink as i, StlSidebarEntry as n, StlSidebarTarget as o, StlSidebarGroup as r, StlSidebar as t };

package/dist/stl-sidebar-DSkUHwcU.d.ts

@@ -0,0 +1,58 @@
+import { ReactNode } from "react";
+import * as react_jsx_runtime56 from "react/jsx-runtime";
+
+//#region src/components/stl-sidebar.d.ts
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      /**
+       * Custom element defined by Starlight's <SidebarPersister>.
+       */
+      'sl-sidebar-restore': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+type StlSidebarTarget = {
+  type: 'href';
+  href: string;
+} | {
+  type: 'stainlessPath';
+  stainlessPath: string;
+};
+interface StlSidebarLink {
+  type: 'link';
+  icon?: ReactNode;
+  label: string;
+  /** Current sidebar item is highlighted. */
+  isCurrent?: boolean;
+  target: StlSidebarTarget;
+  /** Additional HTML attributes that will be attached to the anchor element. */
+  attrs?: Record<string, unknown>;
+}
+interface StlSidebarGroup {
+  type: 'group';
+  icon?: ReactNode;
+  label: string;
+  entries: Array<StlSidebarLink | StlSidebarGroup>;
+  /** Defaults to true. */
+  collapsible?: boolean;
+  collapsed?: boolean;
+  /** Current sidebar item is highlighted. */
+  isCurrent?: boolean;
+  target?: StlSidebarTarget;
+}
+type StlSidebarEntry = StlSidebarLink | StlSidebarGroup;
+type StlSidebarProps = {
+  entries: StlSidebarEntry[];
+  /**
+   * If set, add <sl-sidebar-restore> custom elements (as defined by Starlight's SidebarPersister)
+   * which are used to save/restore sidebar state.
+   */
+  withStarlightRestoration?: boolean;
+};
+declare function StlSidebar({
+  entries,
+  withStarlightRestoration
+}: StlSidebarProps): react_jsx_runtime56.JSX.Element;
+//#endregion
+export { StlSidebarProps as a, StlSidebarLink as i, StlSidebarEntry as n, StlSidebarTarget as o, StlSidebarGroup as r, StlSidebar as t };