@openpkg-ts/sdk

Extract OpenPkg documents from TypeScript source and generate documentation. The SDK of openpkg-ts, the TypeScript reference implementation of the OpenPkg standard.

Install

npm install @openpkg-ts/sdk

TypeScript version support

The sdk drives the TypeScript JS compiler API and declares typescript@^5.0.0 || ^6.0.0 as a regular dependency, so your package manager installs a compatible copy for the sdk automatically — extraction works even if your own project uses a different TypeScript version.

On a TypeScript 7 toolchain? That's fine: TS7's tsc is a native binary and does not conflict with the sdk's nested TS5/6 copy. One caveat: do not force a workspace-wide typescript@7 via overrides/resolutions. The extraction engine needs the JS compiler API, which TypeScript 7 removed — its main export is a version stub with no createProgram. Native TS7-backed extraction is planned as a separate opt-in package; the JS backend remains the default and is fully supported.

Entry Points

// Full SDK (Node.js)
import { listExports, extractSpec, query } from '@openpkg-ts/sdk';

// Browser-safe (no fs, path, etc.)
import { query, loadSpec } from '@openpkg-ts/sdk/browser';

Use @openpkg-ts/sdk/browser in React, Vite, Next.js client components.

Quick Start

import { listExports, getExport, extractSpec, createDocs } from '@openpkg-ts/sdk';

// List all exports
const { exports } = await listExports({ entryFile: './src/index.ts' });

// Get single export details
const { export: spec } = await getExport({ entryFile: './src/index.ts', exportName: 'myFunc' });

// Extract full spec
const { spec } = await extractSpec({ entryFile: './src/index.ts' });

// Generate docs
const docs = createDocs(spec);
const markdown = docs.toMarkdown();

Primitives

Agent-native primitives for composable workflows:

listExports

List exports from entry point with metadata.

const { exports, errors } = await listExports({ entryFile: './src/index.ts' });

// Returns: { name, kind, file, line, description }[]

getExport

Get detailed spec for a single export.

const { export: spec, types, errors } = await getExport({
  entryFile: './src/index.ts',
  exportName: 'createClient'
});

extractSpec

Generate full OpenPkg spec (all exports + types).

const { spec, diagnostics, verification } = await extractSpec({
  entryFile: './src/index.ts',
  maxTypeDepth: 4,
  only: ['use*'],           // filter by pattern
  ignore: ['*Internal'],    // exclude by pattern
  followExternal: ['@ai-sdk/*'], // or true
});

Specs record generation.entryPoint and generation.entryPointSource (types / exports / fallback / explicit / llm).

resolveTarget

Resolve a package and entry from a directory, cwd, intent, or git URL before extracting:

import { resolveTarget, extractSpec } from '@openpkg-ts/sdk';

const resolved = await resolveTarget({ input: '.', intent: 'sdk' });
if (resolved.kind === 'ok') {
  const { spec } = await extractSpec({
    entryFile: resolved.entryFile,
    entryPointSource: resolved.entryPointSource,
  });
}

GitHub URLs clone via gh if present, else git clone --depth 1.

diffSpecs

Compare two specs for breaking changes.

import { diffSpecs } from '@openpkg-ts/sdk';

const diff = diffSpecs(oldSpec, newSpec);
console.log(`Breaking: ${diff.breaking.length}`);

// With options
const diff = diffSpecs(oldSpec, newSpec, {
  includeDocsOnly: false,  // exclude docs-only changes
  kinds: ['function', 'class'],  // filter by kind
});

filterSpec

Immutable spec filtering by criteria.

import { filterSpec } from '@openpkg-ts/sdk';

// Filter by kind
const { spec, matched, total } = filterSpec(fullSpec, {
  kinds: ['function', 'class'],
});

// Filter by tags
filterSpec(spec, { tags: ['public'] });

// Filter deprecated exports
filterSpec(spec, { deprecated: true });

// Search by name/description
filterSpec(spec, { search: 'client' });

// Combine criteria (AND logic)
filterSpec(spec, {
  kinds: ['function'],
  hasDescription: true,
  deprecated: false,
});

Documentation Generation

createDocs / loadSpec

import { createDocs, loadSpec } from '@openpkg-ts/sdk';

// From file path
const docs = createDocs('./openpkg.json');

// From spec object
const docs = loadSpec(spec);

Render Functions

// Full API reference
const markdown = docs.toMarkdown({ frontmatter: true, codeSignatures: true });
const html = docs.toHTML({ fullDocument: true, includeStyles: true });
const json = docs.toJSON();

// Single export
const markdown = docs.toMarkdown({ exportId: 'createClient' });

Navigation

import { toFumadocsMetaJSON, toDocusaurusSidebarJS } from '@openpkg-ts/sdk';

const fumadocsMeta = toFumadocsMetaJSON(spec, { basePath: '/api' });
const docusaurusSidebar = toDocusaurusSidebarJS(spec);

Search Index

import { toSearchIndex, toAlgoliaRecords } from '@openpkg-ts/sdk';

const searchIndex = toSearchIndex(spec);
const algoliaRecords = toAlgoliaRecords(spec, { indexName: 'api_docs' });

QueryBuilder API

Fluent API for querying specs. Available in both Node.js and browser entry points.

import { query } from '@openpkg-ts/sdk';
// or: import { query } from '@openpkg-ts/sdk/browser';

// Chain filters
const functions = query(spec)
  .byKind('function')
  .search('create')
  .find();

// Multiple kinds
const classesAndInterfaces = query(spec)
  .byKind('class', 'interface')
  .find();

// Combine filters
const documented = query(spec)
  .byKind('function')
  .hasDescription()
  .notDeprecated()
  .find();

// Get single export
const createClient = query(spec).byName('createClient').first();

// Search by tags
const publicAPIs = query(spec).byTag('public').find();

QueryBuilder Methods

| Method | Description | |--------|-------------| | .byKind(...kinds) | Filter by export kind | | .byName(...names) | Filter by exact name | | .byId(...ids) | Filter by export ID | | .byTag(...tags) | Filter by tags | | .search(term) | Search name/description | | .hasDescription() | Only with descriptions | | .missingDescription() | Only without descriptions | | .deprecated() | Only deprecated | | .notDeprecated() | Exclude deprecated | | .find() | Return all matches | | .first() | Return first match | | .count() | Return match count |

Query Utilities

import {
  buildSignatureString,
  formatParameters,
  formatReturnType,
  getProperties,
  getMethods,
  resolveTypeRef,
} from '@openpkg-ts/sdk';

Types

import type {
  OpenPkg,
  SpecExport,
  ExtractOptions,
  ExtractResult,
  DocsInstance,
  SimplifiedSpec,
  FilterCriteria,
  FilterResult,
  DiffOptions,
  QueryBuilder,
} from '@openpkg-ts/sdk';

Browser Entry Point

@openpkg-ts/sdk/browser exports only browser-safe utilities:

• query() - QueryBuilder
• loadSpec() - Load spec from object
• filterSpec() - Filter spec by criteria
• buildSignatureString() - Format signatures
• Query utilities (formatParameters, getProperties, etc.)

No Node.js dependencies (fs, path, child_process).

License

MIT