vocs 2.0.17 → 2.1.2

package/src/internal/openapi/openrpc.test.ts

@@ -0,0 +1,239 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import * as OpenApi from './openapi.js'
+import { expand } from './openrpc.js'
+import { parse } from './parser.js'
+import { codeSamples } from './sample.js'
+
+const openrpc = {
+  openrpc: '1.2.4',
+  info: { title: 'Demo JSON-RPC', version: '1.0.0' },
+  components: {
+    schemas: {
+      address: { type: 'string', title: 'hex address' },
+      uint: { type: 'string', title: 'hex uint' },
+    },
+  },
+  methods: [
+    {
+      name: 'eth_blockNumber',
+      summary: 'Returns the current block number.',
+      params: [],
+      result: { name: 'Block number', schema: { $ref: '#/components/schemas/uint' } },
+      examples: [{ name: 'ex', params: [], result: { name: 'r', value: '0x10' } }],
+    },
+    {
+      name: 'eth_getBalance',
+      summary: 'Returns the balance of an account.',
+      params: [
+        { name: 'Address', required: true, schema: { $ref: '#/components/schemas/address' } },
+        { name: 'Block', required: true, schema: { $ref: '#/components/schemas/uint' } },
+      ],
+      result: { name: 'Balance', schema: { $ref: '#/components/schemas/uint' } },
+      examples: [
+        {
+          name: 'ex',
+          params: [
+            { name: 'Address', value: '0xabc' },
+            { name: 'Block', value: 'latest' },
+          ],
+          result: { name: 'Balance', value: '0x1' },
+        },
+      ],
+    },
+  ],
+}
+
+const host = {
+  id: 'rpc-request',
+  method: 'POST',
+  path: '/v1/rpc',
+  summary: 'Query RPC',
+  parameters: [],
+  responses: [],
+}
+
+describe('expand', () => {
+  test('expands one operation per JSON-RPC method', async () => {
+    const { operations, examples } = await expand(host, openrpc)
+
+    expect(operations.map((operation) => operation.summary)).toEqual([
+      'eth_blockNumber',
+      'eth_getBalance',
+    ])
+
+    // Each operation tags the host request example to preselect when trying it,
+    // and a matching named example is emitted for injection onto the host.
+    expect(operations.map((operation) => operation.rpcExample)).toEqual([
+      'eth_blockNumber',
+      'eth_getBalance',
+    ])
+    expect(Object.keys(examples)).toEqual(['eth_blockNumber', 'eth_getBalance'])
+    expect(examples['eth_getBalance']?.value).toEqual({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'eth_getBalance',
+      params: ['0xabc', 'latest'],
+    })
+
+    const balance = operations[1]
+    if (!balance) throw new Error('expected eth_getBalance operation')
+    // All methods reuse the host transport (POST /v1/rpc).
+    expect(balance.method).toBe('POST')
+    expect(balance.path).toBe('/v1/rpc')
+    expect(balance.id).toBe('eth_getbalance')
+    expect(balance.description).toContain('balance')
+
+    // Params are surfaced like path/query params, with refs dereferenced.
+    expect(balance.parameters.map((p) => [p.name, p.in, p.example])).toEqual([
+      ['Address', 'rpc', '0xabc'],
+      ['Block', 'rpc', 'latest'],
+    ])
+    expect(balance.parameters[0]?.schema).toMatchObject({ type: 'string' })
+
+    // The request body is the JSON-RPC envelope, hidden from its own section.
+    expect(balance.requestBody?.hidden).toBe(true)
+    expect(balance.requestBody?.content[0]?.example).toEqual({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'eth_getBalance',
+      params: ['0xabc', 'latest'],
+    })
+
+    // The result is wrapped in a JSON-RPC response envelope.
+    expect(balance.responses[0]?.status).toBe('200')
+    expect(balance.responses[0]?.content[0]?.example).toEqual({
+      jsonrpc: '2.0',
+      id: 1,
+      result: '0x1',
+    })
+  })
+
+  test('generates an accurate JSON-RPC request code sample', async () => {
+    const { operations } = await expand(host, openrpc)
+    const balance = operations[1]
+    if (!balance) throw new Error('expected eth_getBalance operation')
+    const samples = codeSamples(balance, 'https://api.example.com')
+    const curl = samples.find((sample) => sample.id === 'shell/curl')
+    expect(curl?.code).toContain('https://api.example.com/v1/rpc')
+    expect(curl?.code).toContain('"method": "eth_getBalance"')
+    expect(curl?.code).toContain('"params"')
+  })
+})
+
+describe('parse with x-openrpc', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  const spec = {
+    openapi: '3.1.0',
+    info: { title: 'API', version: '1.0.0' },
+    tags: [{ name: 'RPC', description: 'JSON-RPC passthrough.' }],
+    paths: {
+      '/v1/rpc': {
+        post: {
+          operationId: 'rpcRequest',
+          summary: 'Query RPC',
+          tags: ['RPC'],
+          'x-openrpc': openrpc,
+          responses: { '200': { description: 'ok' } },
+        },
+      },
+    },
+  }
+
+  test('replaces the host operation with expanded methods', async () => {
+    const ir = await parse(OpenApi.from({ spec, path: '/api' }))
+    const group = ir.groups.find((candidate) => candidate.name === 'RPC')
+    expect(group?.operations.map((operation) => operation.summary)).toEqual([
+      'eth_blockNumber',
+      'eth_getBalance',
+    ])
+  })
+
+  test('resolves a relative x-openrpc URL against baseUrl', async () => {
+    const relativeSpec = {
+      ...spec,
+      paths: {
+        '/v1/rpc': {
+          post: {
+            operationId: 'rpcRequest',
+            summary: 'Query RPC',
+            tags: ['RPC'],
+            'x-openrpc': '/openrpc.json',
+            responses: { '200': { description: 'ok' } },
+          },
+        },
+      },
+    }
+
+    const fetchMock = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(
+        new Response(JSON.stringify(openrpc), { headers: { 'content-type': 'application/json' } }),
+      )
+
+    const ir = await parse(OpenApi.from({ spec: relativeSpec, path: '/api' }), {
+      baseUrl: 'https://cadent.tempo.xyz',
+    })
+
+    expect(fetchMock).toHaveBeenCalledWith('https://cadent.tempo.xyz/openrpc.json')
+    const group = ir.groups.find((candidate) => candidate.name === 'RPC')
+    expect(group?.operations.map((operation) => operation.summary)).toEqual([
+      'eth_blockNumber',
+      'eth_getBalance',
+    ])
+  })
+
+  test('falls back to the host operation when a relative x-openrpc has no base', async () => {
+    const relativeSpec = {
+      ...spec,
+      paths: {
+        '/v1/rpc': {
+          post: {
+            operationId: 'rpcRequest',
+            summary: 'Query RPC',
+            tags: ['RPC'],
+            'x-openrpc': '/openrpc.json',
+            responses: { '200': { description: 'ok' } },
+          },
+        },
+      },
+    }
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const ir = await parse(OpenApi.from({ spec: relativeSpec, path: '/api' }))
+
+    const group = ir.groups.find((candidate) => candidate.name === 'RPC')
+    expect(group?.operations.map((operation) => operation.summary)).toEqual(['Query RPC'])
+    expect(warn).toHaveBeenCalled()
+  })
+
+  test('injects per-method request examples into the client document', async () => {
+    const ir = await parse(OpenApi.from({ spec, path: '/api' }))
+    // The interactive client must receive the augmented document (not a bare
+    // URL) so it can select each method's example.
+    if (!('content' in ir.client)) throw new Error('expected inline client content')
+    const content = ir.client.content as {
+      paths: Record<
+        string,
+        {
+          post: {
+            requestBody: {
+              content: Record<string, { examples: Record<string, { value: unknown }> }>
+            }
+          }
+        }
+      >
+    }
+    const media = content.paths['/v1/rpc']?.post.requestBody.content['application/json']
+    const examples = media?.examples ?? {}
+    expect(Object.keys(examples)).toEqual(['eth_blockNumber', 'eth_getBalance'])
+    expect(examples['eth_getBalance']?.value).toEqual({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'eth_getBalance',
+      params: ['0xabc', 'latest'],
+    })
+  })
+})

package/src/internal/openapi/openrpc.ts

@@ -0,0 +1,295 @@
+import { dereference } from '@scalar/openapi-parser'
+import GithubSlugger from 'github-slugger'
+import type { IrOperation, IrParameter } from './parser.js'
+
+/**
+ * Minimal structural typing for the OpenRPC documents we expand. Only the
+ * fields consumed during expansion are modeled; everything else is ignored.
+ *
+ * @see https://spec.open-rpc.org
+ */
+export type Document = {
+  openrpc?: string
+  info?: { title?: string; version?: string; description?: string }
+  methods?: Method[]
+  components?: { schemas?: Record<string, unknown> }
+}
+
+export type Method = {
+  name: string
+  summary?: string
+  description?: string
+  deprecated?: boolean
+  params?: ContentDescriptor[]
+  result?: ContentDescriptor
+  examples?: Example[]
+}
+
+type ContentDescriptor = {
+  name?: string
+  summary?: string
+  description?: string
+  required?: boolean
+  deprecated?: boolean
+  schema?: Record<string, unknown>
+}
+
+type Example = {
+  name?: string
+  params?: { name?: string; value?: unknown }[]
+  result?: { name?: string; value?: unknown }
+}
+
+/**
+ * Expands an OpenRPC document into one {@link IrOperation} per JSON-RPC method,
+ * modeled after a single host HTTP operation (the JSON-RPC endpoint).
+ *
+ * JSON-RPC methods all POST the same envelope to one endpoint, which OpenAPI
+ * cannot express as distinct path items. Expanding at the IR level instead lets
+ * each method become its own sidebar entry and page section while keeping the
+ * shared transport: every generated operation reuses the host operation's
+ * `method` (POST) and `path`, so request code samples target the real endpoint.
+ *
+ * Each method maps to:
+ * - `summary` → the method name (the sidebar/section title)
+ * - `description` → the method summary + description
+ * - `parameters` (`in: 'rpc'`) → the JSON-RPC params, rendered like path/query
+ *   params
+ * - `requestBody` → the JSON-RPC request envelope, `hidden` from the body
+ *   section but used to generate an accurate request code sample
+ * - a `200` response → the JSON-RPC response envelope wrapping the method result
+ */
+export async function expand(
+  host: IrOperation,
+  document: Document | string,
+  options: expand.Options = {},
+): Promise<expand.Result> {
+  const resolved = await resolve(document, options)
+  const methods = resolved.methods ?? []
+  const slugger = new GithubSlugger()
+
+  // Named request examples (keyed by method name) injected onto the host
+  // operation so the interactive client (Scalar) can prefill the JSON-RPC
+  // envelope for each method. JSON-RPC methods all share one path+verb, so the
+  // client distinguishes them by selecting the matching named example.
+  const examples: Record<string, expand.RpcExample> = {}
+
+  const operations = methods.map((method) => {
+    const example = method.examples?.[0]
+
+    const parameters: IrParameter[] = (method.params ?? []).map((param, index) => ({
+      name: param.name ?? `param${index}`,
+      in: 'rpc',
+      required: param.required,
+      deprecated: param.deprecated,
+      description: param.description ?? param.summary,
+      schema: param.schema,
+      example: paramExample(param, index, example),
+    }))
+
+    // The wire-format example values (positional `params` array) used for the
+    // request code sample and to fill in any params the examples omit.
+    const paramValues = parameters.map((parameter) =>
+      parameter.example !== undefined ? parameter.example : sampleFromSchema(parameter.schema),
+    )
+
+    const requestExample = {
+      jsonrpc: '2.0',
+      id: 1,
+      method: method.name,
+      params: paramValues,
+    }
+    examples[method.name] = { summary: method.summary, value: requestExample }
+
+    const resultSchema = method.result?.schema
+    const resultValue =
+      example?.result?.value !== undefined ? example.result.value : sampleFromSchema(resultSchema)
+    const responseExample = { jsonrpc: '2.0', id: 1, result: resultValue }
+
+    const description = [method.summary, method.description].filter(Boolean).join('\n\n')
+
+    return {
+      id: slugger.slug(method.name),
+      method: host.method,
+      path: host.path,
+      // Name of the host operation's request example to select in the
+      // interactive client (matches the key added to `examples` above).
+      rpcExample: method.name,
+      summary: method.name,
+      description: description || undefined,
+      deprecated: method.deprecated,
+      parameters,
+      requestBody: {
+        required: true,
+        // Hidden from the rendered "Request Body" section: the params already
+        // appear in the "Parameters" section and the literal envelope shows in
+        // the request code sample. The body is still used to build that sample.
+        hidden: true,
+        content: [
+          {
+            mediaType: 'application/json',
+            schema: requestEnvelopeSchema(method),
+            example: requestExample,
+          },
+        ],
+      },
+      responses: [
+        {
+          status: '200',
+          description: method.result?.description ?? 'JSON-RPC response.',
+          content: [
+            {
+              mediaType: 'application/json',
+              schema: responseEnvelopeSchema(resultSchema),
+              example: responseExample,
+            },
+          ],
+          headers: [],
+        },
+      ],
+    } satisfies IrOperation
+  })
+
+  return { operations, examples }
+}
+
+export declare namespace expand {
+  type Options = {
+    /**
+     * Base URL relative `x-openrpc` URLs (e.g. `/openrpc.json`) resolve against:
+     * the spec URL when the spec was loaded from a URL, or the request origin in
+     * the standalone server handler.
+     */
+    baseUrl?: string | undefined
+  }
+  /** A named JSON-RPC request example to inject onto the host operation. */
+  type RpcExample = { summary?: string | undefined; value: unknown }
+  type Result = {
+    /** One IR operation per JSON-RPC method. */
+    operations: IrOperation[]
+    /** Request examples keyed by method name, for the host operation. */
+    examples: Record<string, RpcExample>
+  }
+}
+
+/**
+ * Resolves an OpenRPC source (URL, raw JSON, or object) to a dereferenced doc.
+ *
+ * A string is treated as raw JSON when it begins with `{`; otherwise it's a
+ * URL. Absolute (`http(s)://`) URLs are fetched directly. Relative URLs (e.g.
+ * `/openrpc.json`, the host-relative link an OpenAPI document commonly uses) are
+ * resolved against `baseUrl` — the spec URL when the spec was loaded from a URL,
+ * or the request origin in the standalone server handler — then fetched.
+ */
+async function resolve(
+  document: Document | string,
+  options: expand.Options = {},
+): Promise<Document> {
+  let raw: unknown = document
+  if (typeof document === 'string') {
+    const trimmed = document.trimStart()
+    if (trimmed.startsWith('{')) {
+      raw = JSON.parse(trimmed)
+    } else {
+      const url =
+        trimmed.startsWith('http://') || trimmed.startsWith('https://')
+          ? trimmed
+          : options.baseUrl
+            ? new URL(trimmed, options.baseUrl).toString()
+            : undefined
+      if (!url)
+        throw new Error(`Cannot resolve relative OpenRPC document "${trimmed}" without a base URL.`)
+      const response = await fetch(url)
+      if (!response.ok)
+        throw new Error(`Failed to fetch OpenRPC document from ${url}: ${response.statusText}`)
+      raw = await response.json()
+    }
+  }
+  // Dereference internal `$ref`s (`#/components/schemas/...`) so the renderer
+  // sees concrete schemas, matching how the OpenAPI parser dereferences specs.
+  const { schema } = await dereference(raw as never)
+  return (schema ?? raw) as Document
+}
+
+/** JSON-RPC request envelope schema for a method (used only for code samples). */
+function requestEnvelopeSchema(method: Method): Record<string, unknown> {
+  return {
+    type: 'object',
+    properties: {
+      jsonrpc: { type: 'string', const: '2.0' },
+      id: { type: 'integer' },
+      method: { type: 'string', const: method.name },
+      params: {
+        type: 'array',
+        prefixItems: (method.params ?? []).map((param) => param.schema ?? {}),
+      },
+    },
+    required: ['jsonrpc', 'method'],
+  }
+}
+
+/** JSON-RPC response envelope schema wrapping a method's result schema. */
+function responseEnvelopeSchema(
+  resultSchema: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  return {
+    type: 'object',
+    properties: {
+      jsonrpc: { type: 'string', const: '2.0' },
+      id: { type: 'integer' },
+      ...(resultSchema ? { result: resultSchema } : {}),
+    },
+  }
+}
+
+/** Looks up the example value for a param, by name then position. */
+function paramExample(
+  param: ContentDescriptor,
+  index: number,
+  example: Example | undefined,
+): unknown {
+  const entries = example?.params ?? []
+  const byName = param.name ? entries.find((entry) => entry.name === param.name) : undefined
+  const entry = byName ?? entries[index]
+  return entry?.value
+}
+
+/**
+ * Derives a representative value from a JSON Schema for methods/params that lack
+ * authored examples. Intentionally small — prefers authored `example`/`default`/
+ * `enum` values and otherwise falls back to a type-based placeholder.
+ */
+function sampleFromSchema(schema: Record<string, unknown> | undefined): unknown {
+  if (!schema || typeof schema !== 'object') return undefined
+  if ('example' in schema) return schema['example']
+  if (Array.isArray(schema['examples']) && schema['examples'].length > 0)
+    return schema['examples'][0]
+  if ('default' in schema) return schema['default']
+  if ('const' in schema) return schema['const']
+  if (Array.isArray(schema['enum']) && schema['enum'].length > 0) return schema['enum'][0]
+
+  const type = Array.isArray(schema['type']) ? schema['type'][0] : schema['type']
+  switch (type) {
+    case 'string':
+      return 'string'
+    case 'integer':
+    case 'number':
+      return 0
+    case 'boolean':
+      return true
+    case 'array': {
+      const items = schema['items'] as Record<string, unknown> | undefined
+      const item = sampleFromSchema(items)
+      return item === undefined ? [] : [item]
+    }
+    case 'object': {
+      const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined
+      if (!properties) return {}
+      const result: Record<string, unknown> = {}
+      for (const [key, value] of Object.entries(properties)) result[key] = sampleFromSchema(value)
+      return result
+    }
+    default:
+      return undefined
+  }
+}