@apimatic/cli 1.5.0 → 2.0.0-beta.1

package/portal-template/src/lib/code-samples.server.ts

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises';
+import type { Document } from 'fumadocs-openapi';
+import { CODE_SAMPLES_EXTENSION } from './code-samples';
+import { isJsonObject, type JsonObject } from './json';
+
+/** Each endpoint's code samples, keyed by path and then by upper-case method, as the CLI writes them. */
+export type CodeSamplesByEndpoint = Record<string, Record<string, unknown[]>>;
+
+const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+
+export async function readCodeSamples(file: string | null): Promise<CodeSamplesByEndpoint> {
+  return file === null ? {} : (JSON.parse(await readFile(file, 'utf8')) as CodeSamplesByEndpoint);
+}
+
+/**
+ * Gives every operation the samples of its endpoint, replacing any it already carries. Placed
+ * after bundling, so an operation behind a path-item `$ref` is reached like an inline one.
+ */
+export function placeCodeSamples(document: Document, samples: CodeSamplesByEndpoint): Document {
+  const paths = (document as JsonObject).paths;
+  if (!isJsonObject(paths)) return document;
+  for (const [path, item] of Object.entries(paths)) {
+    if (isJsonObject(item)) paths[path] = pathItemWithSamples(item, samples[path] ?? {});
+  }
+  return document;
+}
+
+// Rebuilt rather than edited: paths that `$ref` one path item share its operation objects.
+function pathItemWithSamples(item: JsonObject, samplesByMethod: Record<string, unknown[]>): JsonObject {
+  return Object.fromEntries(
+    Object.entries(item).map(([key, value]) =>
+      HTTP_METHODS.has(key) && isJsonObject(value) ? [key, withSamples(value, samplesByMethod[key.toUpperCase()])] : [key, value]
+    )
+  );
+}
+
+function withSamples(operation: JsonObject, samples: unknown[] | undefined): JsonObject {
+  const { [CODE_SAMPLES_EXTENSION]: _, ...rest } = operation;
+  return samples === undefined || samples.length === 0 ? rest : { ...rest, [CODE_SAMPLES_EXTENSION]: samples };
+}

package/portal-template/src/lib/code-samples.ts

@@ -0,0 +1,43 @@
+import { isJsonObject } from './json';
+
+export const CODE_SAMPLES_EXTENSION = 'x-apimatic-codeSamples';
+
+export class CodeSample {
+  private constructor(
+    public readonly lang: string,
+    public readonly label: string,
+    private readonly sources: Map<string, string>
+  ) {}
+
+  public static listIn(operation: unknown): CodeSample[] {
+    const entries = isJsonObject(operation) ? operation[CODE_SAMPLES_EXTENSION] : undefined;
+    return Array.isArray(entries) ? entries.flatMap((entry) => CodeSample.from(entry) ?? []) : [];
+  }
+
+  private static from(entry: unknown): CodeSample | undefined {
+    if (
+      !isJsonObject(entry) ||
+      typeof entry.lang !== 'string' ||
+      typeof entry.label !== 'string' ||
+      !isSources(entry.sources)
+    ) {
+      return undefined;
+    }
+    return new CodeSample(entry.lang, entry.label, new Map(Object.entries(entry.sources)));
+  }
+
+  public sourceFor(exampleId: string | undefined, exampleCount: number): string | undefined {
+    const source = exampleId === undefined ? undefined : this.sources.get(exampleId);
+    return source ?? (exampleCount === 1 ? this.onlySource() : undefined);
+  }
+
+  // The catalog keys a lone snippet `Example` where Fumadocs names the lone example `_default`.
+  private onlySource(): string | undefined {
+    const sources = [...this.sources.values()];
+    return sources.length === 1 ? sources[0] : undefined;
+  }
+}
+
+function isSources(value: unknown): value is Record<string, string> {
+  return isJsonObject(value) && Object.values(value).every((source) => typeof source === 'string');
+}

package/portal-template/src/lib/code-titles.ts

@@ -0,0 +1,29 @@
+// A type alone, so a page naming a title does not load the highlighter the bundle builds.
+import type { BundledLanguage } from './shiki-bundle';
+
+/** What a code block's header calls its language; a shell is named for where the command runs. */
+export const CODE_BLOCK_TITLES: Readonly<Record<BundledLanguage, string>> = {
+  csharp: 'C#',
+  go: 'Go',
+  java: 'Java',
+  php: 'PHP',
+  python: 'Python',
+  ruby: 'Ruby',
+  typescript: 'TypeScript',
+  http: 'HTTP',
+  json: 'JSON',
+  jsonc: 'JSON',
+  shellscript: 'Terminal',
+  shellsession: 'Terminal',
+  xml: 'XML',
+  yaml: 'YAML',
+  css: 'CSS',
+  diff: 'Diff',
+  graphql: 'GraphQL',
+  html: 'HTML',
+  javascript: 'JavaScript',
+  jsx: 'JSX',
+  markdown: 'Markdown',
+  sql: 'SQL',
+  tsx: 'TSX'
+};

package/portal-template/src/lib/install-command.ts

@@ -0,0 +1,13 @@
+const ABSOLUTE = /^https?:\/\//i;
+
+// Quoted, so a `&` or a space in the address stays one argument in any shell a reader pastes it into.
+export function installCommand(path: string, origin: string | null): string {
+  return `npx context-plugins install "${installAddress(path, origin)}"`;
+}
+
+function installAddress(path: string, origin: string | null): string {
+  if (ABSOLUTE.test(path) || origin === null) {
+    return path;
+  }
+  return `${origin.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}

package/portal-template/src/lib/json.ts

@@ -0,0 +1,5 @@
+export type JsonObject = Record<string, unknown>;
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/portal-template/src/lib/layout.shared.tsx

@@ -0,0 +1,41 @@
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+import { portal } from './portal';
+
+export function baseOptions(): BaseLayoutProps {
+  return {
+    nav: {
+      title: (
+        <>
+          <Logo />
+          {/* 45vw is the widest that leaves the rest of the header room at every width from 320px. */}
+          <span className="max-w-[45vw] truncate">{portal.name}</span>
+        </>
+      )
+    },
+    // From lg the header squeezes these into a share of its row; below it they sit in menus, where labels may wrap.
+    links: portal.links.map((link) => ({
+      text: <span className="lg:text-nowrap">{link.label}</span>,
+      url: link.url,
+      external: link.external
+    })),
+    // A portal fixed to one mode has nothing to switch to.
+    themeSwitch: { enabled: portal.colorMode === 'both' }
+  };
+}
+
+// Without max-w-none, Tailwind's image reset lets the header size the title as if the logo had no width.
+const LOGO_SIZE = 'h-6 w-auto max-w-none';
+
+// The name sits beside it, so the image itself says nothing a screen reader needs.
+function Logo() {
+  const { logo } = portal;
+  if (!logo) return null;
+  if (logo.light === logo.dark) return <img src={logo.light} alt="" className={LOGO_SIZE} />;
+  // Both are in the page and CSS shows one, so the right one is there before any script runs.
+  return (
+    <>
+      <img src={logo.light} alt="" className={`${LOGO_SIZE} dark:hidden`} />
+      <img src={logo.dark} alt="" className={`hidden ${LOGO_SIZE} dark:block`} />
+    </>
+  );
+}

package/portal-template/src/lib/layout.tsx

@@ -0,0 +1,16 @@
+import { useMemo, type ReactNode } from 'react';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { DocsLayout as NotebookLayout } from 'fumadocs-ui/layouts/notebook';
+import { baseOptions } from './layout.shared';
+import { portalTabs } from './tabs';
+
+export function PortalLayout({ tree, children }: Readonly<{ tree: PageTree.Root; children: ReactNode }>) {
+  const base = baseOptions();
+  const tabs = useMemo(() => portalTabs(tree), [tree]);
+  // The header spans the page, and `navbar` puts the tab switcher in it rather than the sidebar.
+  return (
+    <NotebookLayout {...base} nav={{ ...base.nav, mode: 'top' }} tabMode="navbar" tree={tree} tabs={tabs}>
+      {children}
+    </NotebookLayout>
+  );
+}

package/portal-template/src/lib/llms.server.ts

@@ -0,0 +1,54 @@
+import { llms } from 'fumadocs-core/source';
+import { stringify } from 'yaml';
+import { getMDXComponents } from '@/components/mdx';
+import { operationLabels } from './openapi-labels';
+import { slimOpenAPIPageProps } from './openapi-slim';
+import { source } from './source.server';
+import { portal } from './portal';
+
+type PortalPage = ReturnType<typeof source.getPages>[number];
+type ReferencePage = Extract<PortalPage, { type: 'openapi' }>;
+
+const index = llms(source);
+
+export async function renderPage(page: PortalPage): Promise<string> {
+  return await render(page, true);
+}
+
+export async function renderIndex(): Promise<string> {
+  return await index.index();
+}
+
+// The specifications stay out: each page's would repeat every schema it shares with the others.
+export async function renderFull(): Promise<string> {
+  const pages = await Promise.all(source.getPages().map((page) => render(page, false)));
+  return pages.join('\n\n');
+}
+
+async function render(page: PortalPage, withSpecification: boolean): Promise<string> {
+  return page.type === 'openapi' ? renderReference(page, withSpecification) : await renderContent(page);
+}
+
+export function renderHome(): string {
+  return `# ${portal.name}\n\n${portal.description ?? ''}`.trimEnd() + '\n';
+}
+
+async function renderContent(page: Exclude<PortalPage, ReferencePage>): Promise<string> {
+  return `# ${page.data.title} (${page.url})\n\n${await page.data.getText('processed', { components: getMDXComponents() })}`;
+}
+
+/** An operation's page, with the part of its specification that page renders: what an assistant reads best. */
+function renderReference(page: ReferencePage, withSpecification: boolean): string {
+  const props = slimOpenAPIPageProps(page.data.getOpenAPIPageProps());
+  const endpoints = operationLabels(props, (signature) => `\`${signature}\``);
+  const sections = [`# ${page.data.title} (${page.url})`, endpoints.join('\n'), page.data.description ?? ''];
+  if (withSpecification) {
+    // Its tags and the document's description are the portal's to show, and would come with every operation.
+    const { info, tags: _tags, ...document } = props.payload.bundled as Record<string, unknown> & {
+      info?: { title?: string; version?: string };
+    };
+    const specification = { ...document, info: { title: info?.title, version: info?.version } };
+    sections.push('```yaml\n' + stringify(specification, { aliasDuplicateObjects: false }) + '```');
+  }
+  return sections.filter((section) => section.length > 0).join('\n\n');
+}

package/portal-template/src/lib/media-adapters.ts

@@ -0,0 +1,34 @@
+import type { MediaAdapter } from 'fumadocs-openapi';
+
+// Fumadocs throws on a request body type it has no adapter for, and matches a wildcard type only as written.
+const UNADAPTED_MEDIA_TYPES = [
+  '*/*',
+  'application/*',
+  'application/*+json',
+  'text/*',
+  'image/*',
+  'audio/*',
+  'video/*',
+  // Fumadocs' own fallback misses "text/plain; charset=utf-8" and quotes the text as JSON.
+  'text/plain',
+  'text/json',
+  'text/html',
+  'text/csv',
+  'text/xml',
+  'application/yaml',
+  'application/pdf',
+  'application/zip',
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/svg+xml'
+];
+
+const asEntered: MediaAdapter = {
+  // An object the playground built from the schema would otherwise be sent as "[object Object]".
+  encode: ({ body }) => (typeof body === 'string' || body instanceof Blob ? body : JSON.stringify(body)),
+  // The portal registers no Fumadocs code generator, so nothing asks for a body example.
+  generateExample: () => undefined
+};
+
+export const mediaAdapters = Object.fromEntries(UNADAPTED_MEDIA_TYPES.map((type) => [type, asEntered]));