@stainless-api/docs 0.1.0-beta.99 → 1.0.0-beta.140

package/stl-docs/og-image/image-gen/generate-api-reference-og-image.tsx

@@ -0,0 +1,188 @@
+import { ImageResponse } from 'takumi-js/response';
+import { generateDocsRoutes } from '@stainless-api/docs/generate-docs-routes';
+import { DocsLanguage, parseStainlessPath } from '@stainless-api/docs-ui/routing';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
+import { ArrowDownLeft, ArrowUpRight, XIcon } from 'lucide-react';
+import OpenGraphImage from 'virtual:stainless-docs/docs-og-image/components/OpenGraphImage';
+import OpenGraphFunctionSignature from 'virtual:stainless-docs/docs-og-image/components/OpenGraphFunctionSignature';
+import { LanguageDeclNodes, Method } from '@stainless/sdk-json';
+import getLogoDataUrl from './get-logo-url';
+import { notFoundResponse, renderOptions } from '../utils';
+import { OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
+import { darkThemeVars, lightThemeVars } from '../theme';
+import { generateApiBreadcrumbs } from '@stainless-api/docs-ui/components';
+import { getSDKJSONInSSR } from '@stainless-api/docs/specs/fetchSpecSSR';
+import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
+import type * as SDKJSON from '@stainless/sdk-json';
+
+type ApiReferenceRoute = ReturnType<typeof generateDocsRoutes>[number];
+
+export default async function generateApiReferenceOgImage({
+  apiReferenceRoute,
+  slug,
+}: {
+  apiReferenceRoute?: ApiReferenceRoute;
+  slug: string;
+}) {
+  if (!apiReferenceRoute?.props.stainlessPath) return notFoundResponse();
+
+  const spec = await getSDKJSONInSSR(apiReferenceRoute.props.language);
+
+  const parsed = parseStainlessPath(apiReferenceRoute.props.stainlessPath);
+  const resource = getResourceFromSpec(apiReferenceRoute.props.stainlessPath, spec);
+
+  if (!resource || !parsed?.method || !resource.methods[parsed.method]) return notFoundResponse();
+
+  if (apiReferenceRoute.props.kind === 'http_method') {
+    const method = resource.methods[parsed.method]!;
+    return generateApiReferenceMethodOgImage({
+      method,
+      language: apiReferenceRoute.props.language,
+      stainlessPath: apiReferenceRoute.props.stainlessPath,
+      slug: `${RESOLVED_API_REFERENCE_PATH}/${slug}`,
+      spec,
+    });
+  }
+
+  const logoDataUrl = getLogoDataUrl();
+
+  return new ImageResponse(
+    <OpenGraphImage
+      title={resource.title}
+      description={`API Overview - ${apiReferenceRoute.props.language} `}
+      logo={logoDataUrl}
+    />,
+    renderOptions,
+  );
+}
+
+function generateApiReferenceMethodOgImage({
+  method,
+  language,
+  stainlessPath,
+  slug,
+  spec,
+}: {
+  method: Method;
+  language: DocsLanguage;
+  stainlessPath: string;
+  slug: string;
+  spec: SDKJSON.Spec;
+}) {
+  const slugWithoutExtension = slug.replace(/\.[^/.]+$/, '');
+  const endpoint = method.endpoint.slice(method.endpoint.indexOf(' ') + 1);
+  const httpMethod = method.httpMethod.toUpperCase();
+
+  const decl = spec?.decls?.[language]?.[stainlessPath] as LanguageDeclNodes[keyof LanguageDeclNodes];
+
+  if (!decl) {
+    return notFoundResponse();
+  }
+
+  let params: { ident: string; optional?: boolean }[] | undefined = undefined;
+  let qualified: string | undefined = undefined;
+
+  if ('signature' in decl && decl.signature) {
+    params = decl.signature.parameters;
+  } else if ('parameters' in decl && decl.parameters) {
+    // @ts-expect-error TODO: this is breaking builds
+    params = decl.parameters;
+  } else if ('args' in decl && decl.args) {
+    params = decl.args;
+  }
+
+  if ('qualified' in decl && decl.qualified) {
+    qualified = decl.qualified;
+  }
+
+  const logoDataUrl = getLogoDataUrl();
+  const colors = OG_IMAGE_OPTIONS?.theme === 'dark' ? darkThemeVars : lightThemeVars;
+  const httpColors =
+    httpMethod === 'GET'
+      ? { background: colors.greenBackground, text: colors.green }
+      : httpMethod === 'POST'
+        ? { background: colors.blueBackground, text: colors.blue }
+        : httpMethod === 'PUT' || httpMethod === 'PATCH'
+          ? { background: colors.orangeBackground, text: colors.orange }
+          : httpMethod === 'DELETE'
+            ? { background: colors.redBackground, text: colors.red }
+            : { background: colors.foregroundMuted, text: colors.foreground };
+  // remove first and last breadcrumb (API Reference and current page)
+  const breadcrumbs = generateApiBreadcrumbs(
+    slugWithoutExtension,
+    spec,
+    RESOLVED_API_REFERENCE_PATH || '/api',
+  )?.slice(1, -1);
+
+  return new ImageResponse(
+    <OpenGraphImage
+      title={method.summary || method.title}
+      logo={logoDataUrl}
+      theme={OG_IMAGE_OPTIONS?.theme}
+      breadcrumbs={breadcrumbs ? breadcrumbs.map((b) => b.title) : undefined}
+    >
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          fontFamily: 'monospace',
+        }}
+      >
+        <OpenGraphFunctionSignature
+          params={params}
+          fullyQualifiedName={qualified}
+          theme={OG_IMAGE_OPTIONS?.theme}
+        />
+        <div
+          style={{
+            display: 'flex',
+            gap: '8px',
+            alignItems: 'center',
+            fontFamily: 'monospace',
+          }}
+        >
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              paddingLeft: '2px',
+              paddingRight: '6px',
+              paddingTop: '4px',
+              paddingBottom: '4px',
+              borderRadius: '8px',
+              fontWeight: 600,
+              color: httpColors.text,
+              backgroundColor: httpColors.background,
+              lineHeight: '100%',
+              fontSize: '25px',
+              stroke: colors.foreground,
+              fontFamily: 'monospace',
+              flexShrink: 0,
+            }}
+          >
+            {httpMethod === 'GET' && <ArrowDownLeft size={36} color={colors.green} />}
+            {httpMethod === 'POST' && <ArrowUpRight size={36} color={colors.blue} />}
+            {(httpMethod === 'PUT' || httpMethod === 'PATCH') && (
+              <ArrowUpRight size={36} color={colors.orange} />
+            )}
+            {httpMethod === 'DELETE' && <XIcon size={36} color={colors.red} />}
+            {httpMethod}
+          </div>
+          <div
+            style={{
+              lineClamp: 1,
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              color: colors.foregroundMuted,
+              fontFamily: 'monospace',
+            }}
+          >
+            {endpoint}
+          </div>
+        </div>
+      </div>
+    </OpenGraphImage>,
+    renderOptions,
+  );
+}

package/stl-docs/og-image/image-gen/generate-og-image.tsx

@@ -0,0 +1,119 @@
+import { getCollection } from 'astro:content';
+import { z } from 'astro/zod';
+import { ImageResponse } from 'takumi-js/response';
+import { Tabs } from '@stainless-api/docs/docs-config';
+import OpenGraphImage from 'virtual:stainless-docs/docs-og-image/components/OpenGraphImage';
+import { OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
+import { TABS } from 'virtual:stl-docs-virtual-module';
+import getLogoDataUrl from './get-logo-url';
+import { stainlessDocsSchemaExtension } from '../../schema-extension';
+import { notFoundResponse, renderOptions } from '../utils';
+
+type GetcollectionReturnType = Awaited<ReturnType<typeof getCollection<'docs'>>>[number];
+
+type PageEntry = {
+  data: GetcollectionReturnType['data'] & z.infer<typeof stainlessDocsSchemaExtension>;
+};
+
+let contentEntriesCache: { id: string }[] | null = null;
+
+async function getContentEntries(): Promise<{ id: string }[]> {
+  if (contentEntriesCache === null) {
+    contentEntriesCache = await getCollection('docs').then((entries) =>
+      entries.map((entry) => ({ id: entry.id })),
+    );
+  }
+  return contentEntriesCache ?? [];
+}
+
+async function resolveAutogenerateEntry(autogenerate: {
+  directory: string;
+}): Promise<NonNullable<Tabs[0]['sidebar']>> {
+  const entries = await getContentEntries();
+  const directoryPrefix = autogenerate.directory.endsWith('/')
+    ? autogenerate.directory
+    : `${autogenerate.directory}/`;
+
+  const matchingEntries = entries
+    .filter((entry) => {
+      return entry.id === autogenerate.directory || entry.id.startsWith(directoryPrefix);
+    })
+    .map((entry) => entry.id)
+    .sort();
+
+  return matchingEntries;
+}
+
+const findBreadcrumbsInSidebar = async (
+  data: NonNullable<Tabs[0]['sidebar']>,
+  slug: string,
+): Promise<string[] | null> => {
+  for (const entry of data) {
+    if (typeof entry === 'string') {
+      if (entry === slug) {
+        return [];
+      }
+    } else {
+      if ('link' in entry && entry.link === slug) {
+        return [entry.label];
+      }
+
+      if ('autogenerate' in entry && entry.autogenerate) {
+        const resolvedItems = await resolveAutogenerateEntry(entry.autogenerate);
+        const breadcrumbs = await findBreadcrumbsInSidebar(resolvedItems, slug);
+        if (breadcrumbs) {
+          return breadcrumbs;
+        }
+        continue;
+      }
+
+      const children = ('sidebar' in entry && entry.sidebar) || ('items' in entry && entry.items);
+      if (children) {
+        const breadcrumbs = await findBreadcrumbsInSidebar(children as NonNullable<Tabs[0]['sidebar']>, slug);
+        if (breadcrumbs) {
+          return [entry.label!, ...breadcrumbs];
+        }
+      }
+    }
+  }
+  return null;
+};
+
+const findBreadcrumbs = async (data: Tabs, slug: string): Promise<string[] | undefined> => {
+  for (const tab of data) {
+    if (tab.link === slug) {
+      return [tab.label];
+    }
+    if (!tab.sidebar) continue;
+    const breadcrumbs = await findBreadcrumbsInSidebar(tab.sidebar, slug);
+    if (breadcrumbs) {
+      return [tab.label, ...breadcrumbs.map((label) => label)];
+    }
+  }
+  return undefined;
+};
+
+async function generateOgImage({ page, slug }: { page?: PageEntry; slug: string }) {
+  if (!page) {
+    return notFoundResponse();
+  }
+
+  const logoDataUrl = getLogoDataUrl({
+    logo: page.data.ogImageOptions?.logo,
+    theme: page.data.ogImageOptions?.theme || OG_IMAGE_OPTIONS?.theme,
+  });
+
+  const breadcrumbs = page.data.template !== 'splash' ? await findBreadcrumbs(TABS, slug) : undefined;
+  return new ImageResponse(
+    <OpenGraphImage
+      title={page.data.ogImageOptions?.title ?? page.data.title}
+      description={page.data.ogImageOptions?.description ?? page.data.description}
+      logo={logoDataUrl}
+      theme={page.data.ogImageOptions?.theme || OG_IMAGE_OPTIONS?.theme}
+      breadcrumbs={breadcrumbs}
+    />,
+    renderOptions,
+  );
+}
+
+export default generateOgImage;

package/stl-docs/og-image/image-gen/get-logo-url.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { LOGO, OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
+
+export function resolveLocalImageFile(logoPath: string): string | undefined {
+  try {
+    // Remove leading slash and resolve from project root
+    const filePath = join(process.cwd(), logoPath.replace(/^\//, ''));
+    const fileBuffer = readFileSync(filePath);
+
+    // Determine mime type from extension
+    const ext = logoPath.split('.').pop()?.toLowerCase();
+
+    const mimeType = ext === 'svg' ? 'image/svg+xml' : `image/${ext}`;
+
+    return `data:${mimeType};base64,${fileBuffer.toString('base64')}`;
+  } catch (error) {
+    console.warn('Failed to load logo for OG image:', error);
+    return undefined;
+  }
+}
+
+// Convert logo to base64 data URL if it exists
+function getLogoDataUrl({ logo, theme }: { logo?: string; theme?: 'light' | 'dark' } = {}):
+  | string
+  | undefined {
+  const logoConfig = logo ?? OG_IMAGE_OPTIONS?.logo ?? LOGO;
+  if (!logoConfig) return undefined;
+
+  // Handle string path or object with src/light properties
+  let logoPath: string | undefined;
+  if (typeof logoConfig === 'string') {
+    logoPath = logoConfig;
+  } else if ('src' in logoConfig) {
+    logoPath = logoConfig.src;
+  } else if ('dark' in logoConfig && theme === 'dark') {
+    logoPath = logoConfig.dark;
+  } else if ('light' in logoConfig) {
+    logoPath = logoConfig.light;
+  }
+
+  if (!logoPath) return undefined;
+
+  return resolveLocalImageFile(logoPath);
+}
+
+export default getLogoDataUrl;

package/stl-docs/og-image/index.ts

@@ -0,0 +1,135 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import type { NormalizedStainlessDocsConfig } from '../loadStlDocsConfig';
+import { resolveSrcFile } from '../../resolveSrcFile';
+import { resolve } from 'path';
+import type { OGImageConfig } from './config';
+import { buildVirtualModuleString } from '../../shared/virtualModule';
+
+// The '\0' prefix tells Vite "this is a virtual module" and prevents it from being resolved again.
+function resolveVirtualModuleId<T extends string>(id: T): `\0${T}` {
+  return `\0${id}`;
+}
+
+const OG_IMAGE_DIR = '/stl-docs/og-image';
+
+const stainlessComponentDefaults = {
+  OpenGraphImage: resolveSrcFile(OG_IMAGE_DIR, 'components/OpenGraphImage.tsx'),
+  OpenGraphFunctionSignature: resolveSrcFile(OG_IMAGE_DIR, 'components/OpenGraphFunctionSignature.tsx'),
+};
+
+function checkTakumiInstalled(): boolean {
+  try {
+    import.meta.resolve('takumi-js/response');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function ogImageStarlightPlugin(
+  config: OGImageConfig | undefined,
+  stainlessDocsConfig: NormalizedStainlessDocsConfig,
+): StarlightPlugin {
+  return {
+    name: 'stainless-og-image',
+    hooks: {
+      'config:setup': ({ astroConfig, addRouteMiddleware, addIntegration, logger, command }) => {
+        if (command !== 'build' && command !== 'dev') {
+          return;
+        }
+
+        if (!checkTakumiInstalled()) {
+          logger.error(
+            'The "takumi-js" package is required to use OG image generation. ' +
+              'Please install it: npm install takumi-js',
+          );
+          process.exit(1);
+        }
+
+        if (!astroConfig.site) {
+          logger.warn('astro.config.site is not set. Open Graph images will not be generated.');
+          return;
+        }
+        addRouteMiddleware({
+          entrypoint: resolveSrcFile(OG_IMAGE_DIR, 'routes/add-og-image.ts'),
+        });
+
+        addIntegration({
+          name: 'stainless-docs-og-image-astro-integration',
+          hooks: {
+            'astro:config:setup': ({ updateConfig, injectRoute, command, config: astroConfig }) => {
+              const resolvePath = (id: string) =>
+                JSON.stringify(id.startsWith('.') ? resolve(astroConfig.root.pathname, id) : id);
+
+              const userComponents = Object.fromEntries(
+                Object.entries(config?.components ?? {}).flatMap(([key, value]) =>
+                  value !== undefined ? [[key, value]] : [],
+                ),
+              );
+
+              const allComponents: Record<string, string> = {
+                ...stainlessComponentDefaults,
+                ...userComponents,
+              };
+
+              const modules = Object.fromEntries(
+                Object.entries(allComponents).map(([name, path]) => [
+                  `virtual:stainless-docs/docs-og-image/components/${name}`,
+                  `export { default } from ${resolvePath(path)};`,
+                ]),
+              );
+
+              const resolutionMap = Object.fromEntries(
+                Object.keys(modules).map((key) => [resolveVirtualModuleId(key), key]),
+              );
+
+              const virtualId = `virtual:stainless-docs/docs-og-image`;
+
+              updateConfig({
+                vite: {
+                  plugins: [
+                    {
+                      name: '@stainless-api/docs-og-image-vite',
+                      resolveId(id) {
+                        if (id in modules || id == virtualId) {
+                          return resolveVirtualModuleId(id);
+                        }
+                      },
+                      load(id) {
+                        if (id === resolveVirtualModuleId(virtualId)) {
+                          return buildVirtualModuleString({
+                            LOGO: stainlessDocsConfig?.starlightPassThrough?.logo,
+                            OG_IMAGE_OPTIONS: config,
+                          });
+                        }
+                        const resolution = resolutionMap[id];
+                        if (resolution) return modules[resolution];
+                      },
+                    },
+                  ],
+                },
+              });
+
+              injectRoute({
+                pattern: `/og/[...slug].png`,
+                entrypoint: resolveSrcFile(OG_IMAGE_DIR, 'routes/get-og-image.ts'),
+                prerender: command === 'build',
+              });
+
+              if (stainlessDocsConfig.apiReference !== null) {
+                const apiBasePath = stainlessDocsConfig.apiReference?.basePath ?? '/api';
+                const normalizedBasePath = apiBasePath.replace(/^\/+|\/+$/g, '');
+
+                injectRoute({
+                  pattern: `/og/${normalizedBasePath}/[...slug].png`,
+                  entrypoint: resolveSrcFile(OG_IMAGE_DIR, 'routes/get-api-reference-og-image.ts'),
+                  prerender: command === 'build',
+                });
+              }
+            },
+          },
+        });
+      },
+    },
+  };
+}

package/stl-docs/og-image/routes/add-og-image.ts

@@ -0,0 +1,45 @@
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+import path from 'path';
+import { OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
+import { renderOptions } from '../utils';
+
+export const onRequest = defineRouteMiddleware((context) => {
+  const base = OG_IMAGE_OPTIONS?.basePath || '';
+  // Get the URL of the generated image for the current page using its ID and
+  // append the `.png` file extension.
+  const ogImageUrl = new URL(
+    path.posix.join(
+      import.meta.env.BASE_URL ?? '',
+      base,
+      'og',
+      `${context.locals.starlightRoute.id || 'index'}.png`,
+    ),
+    context.site,
+  );
+
+  // Get the array of all tags to include in the `<head>` of the current page.
+  const { head } = context.locals.starlightRoute;
+
+  // Add the `<meta/>` tags for the Open Graph images.
+  head.push({
+    tag: 'meta',
+    attrs: { property: 'og:image', content: ogImageUrl.href },
+  });
+  head.push({
+    tag: 'meta',
+    attrs: { name: 'twitter:image', content: ogImageUrl.href },
+  });
+  head.push({
+    tag: 'meta',
+    attrs: { name: 'twitter:card', content: 'summary_large_image' },
+  });
+
+  head.push({
+    tag: 'meta',
+    attrs: { property: 'og:image:width', content: renderOptions.width.toString() },
+  });
+  head.push({
+    tag: 'meta',
+    attrs: { property: 'og:image:height', content: renderOptions.height.toString() },
+  });
+});

package/stl-docs/og-image/routes/get-api-reference-og-image.ts

@@ -0,0 +1,36 @@
+import { generateAllDocsRoutes } from '@stainless-api/docs/generate-docs-routes';
+import type { APIRoute } from 'astro';
+import generateApiReferenceOgImage from '../image-gen/generate-api-reference-og-image';
+import { notFoundResponse } from '../utils';
+import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
+
+const routes = await generateAllDocsRoutes();
+
+export function getStaticPaths() {
+  return routes.map((route) => ({
+    params: { slug: `${route.params.slug}` },
+    ...route.props,
+  }));
+}
+
+export const GET: APIRoute = async ({ params }) => {
+  const slug = params?.slug;
+  if (!slug) return notFoundResponse();
+
+  // Remove slashes from the start and end of RESOLVED_API_REFERENCE_PATH
+  const apiBasePath = RESOLVED_API_REFERENCE_PATH?.replace(/^\/|\/$/g, '');
+
+  const slugWithoutBasePath = apiBasePath
+    ? slug.startsWith(`${apiBasePath}/`)
+      ? slug.slice(apiBasePath.length + 1)
+      : slug
+    : slug;
+
+  const apiReferenceRoute = routes.find((r) => r.params.slug === slugWithoutBasePath);
+
+  if (apiReferenceRoute) {
+    return generateApiReferenceOgImage({ apiReferenceRoute, slug });
+  }
+
+  return notFoundResponse();
+};

package/stl-docs/og-image/routes/get-og-image.ts

@@ -0,0 +1,28 @@
+import { getCollection } from 'astro:content';
+import type { APIRoute } from 'astro';
+import generateOgImage from '../image-gen/generate-og-image';
+import { notFoundResponse } from '../utils';
+
+const entries = await getCollection('docs');
+// Map the entry array to an object with the page ID as key and the
+// frontmatter data as value.
+const pages = Object.fromEntries(entries.map(({ data, id }) => [id, { data }]));
+
+export function getStaticPaths() {
+  const prosePaths = entries.map((entry) => ({
+    params: { slug: entry.id },
+  }));
+  return [...prosePaths];
+}
+
+export const GET: APIRoute = async ({ params }) => {
+  const slug = params?.slug;
+  if (!slug) return notFoundResponse();
+  const page = pages[slug];
+
+  if (page) {
+    return generateOgImage({ slug, page });
+  }
+
+  return notFoundResponse();
+};

package/stl-docs/og-image/theme.ts

@@ -0,0 +1,43 @@
+const lightThemeVars = {
+  background: '#ffffffff',
+  foreground: '#262626ff',
+  foregroundReduced: `#262626cc`,
+  foregroundMuted: `#26262666`,
+  green: '#16a34a',
+  greenBackground: '#16a34a14',
+  blue: '#155dfc',
+  blueBackground: '#155dfc14',
+  orange: '#ea580c',
+  orangeBackground: '#ea580c14',
+  red: '#d01e22',
+  redBackground: '#d01e2214',
+};
+
+const darkThemeVars = {
+  background: '#0a0a0aff',
+  foreground: '#ffffffff',
+  foregroundReduced: `#ffffffcc`,
+  foregroundMuted: `#ffffff66`,
+  green: '#22c55e',
+  greenBackground: '#22c55e27',
+  blue: '#2b7fff',
+  blueBackground: '#2b80ff27',
+  orange: '#f97316',
+  orangeBackground: '#f9731627',
+  red: '#d01e22',
+  redBackground: '#d01e2227',
+};
+
+const typography = {
+  baseFontSize: '40px',
+  baseLineHeight: '150%',
+  baseLetterSpacing: '-2%',
+  headerFontSize: '56px',
+  headerLineHeight: '120%',
+  headerLetterSpacing: '-3%',
+  breadcrumbFontSize: '32px',
+  breadcrumbLineHeight: '120%',
+  breadcrumbLetterSpacing: '-1%',
+};
+
+export { lightThemeVars, darkThemeVars, typography };

package/stl-docs/og-image/utils.ts

@@ -0,0 +1,14 @@
+import { ImageResponseOptions } from 'takumi-js/response';
+import { OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
+
+const defaultRenderOptions: ImageResponseOptions & { width: number; height: number } = {
+  width: 1200,
+  height: 630,
+};
+
+export const renderOptions = {
+  ...defaultRenderOptions,
+  ...OG_IMAGE_OPTIONS?.renderOptions,
+};
+
+export const notFoundResponse = () => new Response('Not found', { status: 404 });