API reference

The searchable reference is generated from public TypeScript exports and their JSDoc or TSDoc comments. Website builds regenerate it from source, and local development refreshes it when a public package changes.

Open the generated API reference

Included packages

@norbital-ai/pod

Workspace authoring, client, and Vite APIs.

@norbital-ai/platform-utils

Shared platform contracts, manifests, remotes, storage, and tenant utilities.

@norbital-ai/std

General-purpose schema, result, date, finance, text, and async helpers.

@norbital-ai/ui

Published Svelte component types and supporting utilities.

Documenting an API

Write a /** ... */ comment on the exported declaration. TypeDoc carries summaries, parameter descriptions, examples, return values, remarks, deprecations, and {@link ...} references into the website automatically.

/**
 * Creates an invoice for an existing customer.
 *
 * @param customerId - Stable customer identifier.
 * @param amount - Invoice total in minor currency units.
 * @returns The persisted invoice.
 * @throws When the customer does not exist.
 * @example
 * const invoice = await createInvoice('cus_123', 2500);
 */
export async function createInvoice(customerId: string, amount: number) {
  // ...
}

Only declarations exported by a published package entrypoint are public API. Internal helpers may appear in TypeScript signatures, but are not documented as standalone, importable symbols.

How generation works

1. TypeDoc reads the published entrypoints for pod, platform-utils, std, and ui directly from the monorepo.
2. It extracts exported declarations and their source comments into static, searchable HTML in apps/website/static/api/.
3. The website build runs generation before SvelteKit builds, so deployed reference pages always match the source in that build.
4. CI runs the same generator independently. Any TypeDoc warning or error fails the check.

Local development

Running pnpm --filter website dev generates the reference before the development server starts. The Vite integration then watches package source, TypeDoc configuration, and API styles. A relevant change triggers a debounced rebuild and one browser reload. UI package changes first rebuild its generated Svelte declaration files.

Generate or verify the reference without starting the website:

pnpm docs:api

Generated HTML is ignored by Git. Commit the source declaration, its comment, and any entrypoint export; the website and CI produce the corresponding reference output automatically.