Complete content client reference

shoalrun.content

Module shoalrun.content

Functions

Members

shoalrun.content.ContentAnchor

Type shoalrun.content.ContentAnchor

type ContentAnchor = {
    id: string;
    exportedId: string;
    title?: string;
};

Mapping from a canonical document fragment to its exported HTML ID.

Fields

shoalrun.content.ContentAnchor.exportedId

Property shoalrun.content.ContentAnchor.exportedId

exportedId: string

Type: string

Required

shoalrun.content.ContentAnchor.id

Property shoalrun.content.ContentAnchor.id

id: string

Type: string

Required

shoalrun.content.ContentAnchor.title

Property shoalrun.content.ContentAnchor.title

title?: string | undefined

Type: string | undefined

Optional

shoalrun.content.ContentAsset

Type shoalrun.content.ContentAsset

type ContentAsset = ContentFile & {
    mediaType: string;
};

A content-addressed file with its declared media type.

Fields

shoalrun.content.ContentAsset.mediaType

Property shoalrun.content.ContentAsset.mediaType

mediaType: string

Type: string

Required

shoalrun.content.ContentDeliveryError

Class shoalrun.content.ContentDeliveryError

class ContentDeliveryError extends Error

Delivery failure with a machine-readable code and a human-readable message.

Constructor

new ContentDeliveryError(code: ContentErrorCode, message: string): ContentDeliveryError

Bases: Error

Fields

shoalrun.content.ContentDeliveryError.code

Property shoalrun.content.ContentDeliveryError.code

readonly code: ContentErrorCode

Type: ContentErrorCode

Required

shoalrun.content.ContentDeliveryLimits

Type shoalrun.content.ContentDeliveryLimits

type ContentDeliveryLimits = {
    manifestBytes?: number;
    resourceBytes?: number;
    resources?: number;
};

Positive safe-integer bounds applied when opening and reading content.

Fields

shoalrun.content.ContentDeliveryLimits.manifestBytes

Property shoalrun.content.ContentDeliveryLimits.manifestBytes

manifestBytes?: number | undefined

Maximum manifest or REST inventory bytes. Defaults to 5,000,000.

Type: number | undefined

Optional

shoalrun.content.ContentDeliveryLimits.resourceBytes

Property shoalrun.content.ContentDeliveryLimits.resourceBytes

resourceBytes?: number | undefined

Maximum bytes for an individual representation. Defaults to 8,000,000.

Type: number | undefined

Optional

shoalrun.content.ContentDeliveryLimits.resources

Property shoalrun.content.ContentDeliveryLimits.resources

resources?: number | undefined

Maximum resource count in the inventory. Defaults to 10,000.

Type: number | undefined

Optional

shoalrun.content.ContentErrorCode

Type shoalrun.content.ContentErrorCode

type ContentErrorCode = 'invalid_manifest' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'network_error' | 'invalid_content' | 'disposed';

Stable error categories raised by content-source validation and reads.

shoalrun.content.ContentFile

Type shoalrun.content.ContentFile

type ContentFile = {
    path: string;
    bytes: number;
    digest: string;
};

Export-relative file path, byte length, and SHA-256 digest.

Fields

shoalrun.content.ContentFile.bytes

Property shoalrun.content.ContentFile.bytes

bytes: number

Type: number

Required

shoalrun.content.ContentFile.digest

Property shoalrun.content.ContentFile.digest

digest: string

Type: string

Required

shoalrun.content.ContentFile.path

Property shoalrun.content.ContentFile.path

path: string

Type: string

Required

shoalrun.content.ContentFormat

Type shoalrun.content.ContentFormat

type ContentFormat = 'html' | 'markdown';

Portable representations a content client can request.

shoalrun.content.ContentLink

Type shoalrun.content.ContentLink

type ContentLink = {
    key: string;
    kind: 'resource' | 'canonical' | 'external' | 'asset';
    href: string;
    ref?: ContentRef;
    fragment?: string;
    query?: string;
    asset?: string;
};

Classified link and optional resource identity for application routing.

Fields

shoalrun.content.ContentLink.asset

Property shoalrun.content.ContentLink.asset

asset?: string | undefined

Type: string | undefined

Optional

shoalrun.content.ContentLink.fragment

Property shoalrun.content.ContentLink.fragment

fragment?: string | undefined

Type: string | undefined

Optional

shoalrun.content.ContentLink.href

Property shoalrun.content.ContentLink.href

href: string

Type: string

Required

shoalrun.content.ContentLink.key

Property shoalrun.content.ContentLink.key

key: string

Type: string

Required

shoalrun.content.ContentLink.kind

Property shoalrun.content.ContentLink.kind

kind: "resource" | "canonical" | "external" | "asset"

Type: "resource" | "canonical" | "external" | "asset"

Required

shoalrun.content.ContentLink.query

Property shoalrun.content.ContentLink.query

query?: string | undefined

Type: string | undefined

Optional

shoalrun.content.ContentLink.ref

Property shoalrun.content.ContentLink.ref

ref?: ContentRef | undefined

Type: ContentRef | undefined

Optional

shoalrun.content.ContentManifest

Type shoalrun.content.ContentManifest

type ContentManifest = {
    schemaVersion: 1 | 2;
    kind: 'shoalrun-content-export';
    digest: string;
    publicBase: string;
    publication: ContentPublication;
    review: {
        status: 'ok' | 'required';
        apis: Array<{
            apiId: string;
            digest: string;
        }>;
    };
    resources: ContentResource[];
    assets: ContentAsset[];
    files: ContentFile[];
    diagnostics: Array<{
        code: string;
        documentId?: string;
        message: string;
    }>;
};

One validated, content-addressed export inventory.

Fields

shoalrun.content.ContentManifest.assets

Property shoalrun.content.ContentManifest.assets

assets: ContentAsset[]

Type: ContentAsset[]

Required

shoalrun.content.ContentManifest.diagnostics

Property shoalrun.content.ContentManifest.diagnostics

diagnostics: { code: string; documentId?: string; message: string; }[]

Type: { code: string; documentId?: string; message: string; }[]

Required

shoalrun.content.ContentManifest.digest

Property shoalrun.content.ContentManifest.digest

digest: string

Type: string

Required

shoalrun.content.ContentManifest.files

Property shoalrun.content.ContentManifest.files

files: ContentFile[]

Type: ContentFile[]

Required

shoalrun.content.ContentManifest.kind

Property shoalrun.content.ContentManifest.kind

kind: "shoalrun-content-export"

Type: "shoalrun-content-export"

Required

shoalrun.content.ContentManifest.publicBase

Property shoalrun.content.ContentManifest.publicBase

publicBase: string

Type: string

Required

shoalrun.content.ContentManifest.publication

Property shoalrun.content.ContentManifest.publication

publication: ContentPublication

Type: ContentPublication

Required

shoalrun.content.ContentManifest.resources

Property shoalrun.content.ContentManifest.resources

resources: ContentResource[]

Type: ContentResource[]

Required

shoalrun.content.ContentManifest.review

Property shoalrun.content.ContentManifest.review

review: { status: "ok" | "required"; apis: Array<{ apiId: string; digest: string; }>; }

Type: { status: "ok" | "required"; apis: Array<{ apiId: string; digest: string; }>; }

Required

shoalrun.content.ContentManifest.schemaVersion

Property shoalrun.content.ContentManifest.schemaVersion

schemaVersion: 1 | 2

Type: 1 | 2

Required

shoalrun.content.ContentMount

Type shoalrun.content.ContentMount

type ContentMount = {
    anchors: readonly ContentAnchor[];
    links: readonly ContentLink[];
    unmount(): void;
};

Handles and rewritten routing metadata for one mounted HTML instance.

Fields

Methods

shoalrun.content.ContentMount.anchors

Property shoalrun.content.ContentMount.anchors

anchors: readonly ContentAnchor[]

Anchors after instance-specific ID rewriting.

Type: readonly ContentAnchor[]

Required

shoalrun.content.ContentMount.links

Property shoalrun.content.ContentMount.links

links: readonly ContentLink[]

Typed links, including rewritten local fragments for this instance.

Type: readonly ContentLink[]

Required

shoalrun.content.ContentMount.unmount

Method shoalrun.content.ContentMount.unmount

unmount(): void

Remove nodes that still belong to this mount.

Returns

void

shoalrun.content.ContentPublication

Type shoalrun.content.ContentPublication

type ContentPublication = {
    channel: string;
    version: string;
    language: string;
    product?: string;
};

Exact documentation publication selected by a content source.

Fields

shoalrun.content.ContentPublication.channel

Property shoalrun.content.ContentPublication.channel

channel: string

Type: string

Required

shoalrun.content.ContentPublication.language

Property shoalrun.content.ContentPublication.language

language: string

Type: string

Required

shoalrun.content.ContentPublication.product

Property shoalrun.content.ContentPublication.product

product?: string | undefined

Type: string | undefined

Optional

shoalrun.content.ContentPublication.version

Property shoalrun.content.ContentPublication.version

version: string

Type: string

Required

shoalrun.content.ContentRef

Type shoalrun.content.ContentRef

type ContentRef = {
    kind: 'page';
    documentId: string;
} | {
    kind: 'section';
    documentId: string;
    sectionId: string;
} | {
    kind: 'snippet';
    id: string;
};

Stable identity of a page, a section within a page, or a named snippet instance. A reference is scoped to the publication and revision of the opened snapshot.

shoalrun.content.ContentRepresentation

Type shoalrun.content.ContentRepresentation

type ContentRepresentation = ContentAsset & {
    anchors: ContentAnchor[];
    links: ContentLink[];
};

One portable format, including its file metadata, anchors, and typed links.

Fields

shoalrun.content.ContentRepresentation.anchors

Property shoalrun.content.ContentRepresentation.anchors

anchors: ContentAnchor[]

Type: ContentAnchor[]

Required

shoalrun.content.ContentRepresentation.links

Property shoalrun.content.ContentRepresentation.links

links: ContentLink[]

Type: ContentLink[]

Required

shoalrun.content.ContentResource

Type shoalrun.content.ContentResource

type ContentResource = {
    ref: ContentRef;
    publication: ContentPublication;
    title: string;
    summary: string;
    type: string;
    canonicalUrl?: string;
    source?: {
        documentId?: string;
        snippetId?: string;
        valuesDigest?: string;
    };
    representations: Partial<Record<ContentFormat, ContentRepresentation>>;
    assets: string[];
    externalDependencies: Array<{
        url: string;
        kind: 'image';
    }>;
};

Inventory entry describing one exported document, section, or snippet instance.

Fields

shoalrun.content.ContentResource.assets

Property shoalrun.content.ContentResource.assets

assets: string[]

Type: string[]

Required

shoalrun.content.ContentResource.canonicalUrl

Property shoalrun.content.ContentResource.canonicalUrl

canonicalUrl?: string | undefined

Type: string | undefined

Optional

shoalrun.content.ContentResource.externalDependencies

Property shoalrun.content.ContentResource.externalDependencies

externalDependencies: { url: string; kind: "image"; }[]

Type: { url: string; kind: "image"; }[]

Required

shoalrun.content.ContentResource.publication

Property shoalrun.content.ContentResource.publication

publication: ContentPublication

Exact product, channel, version, and documentation language.

Type: ContentPublication

Required

shoalrun.content.ContentResource.ref

Property shoalrun.content.ContentResource.ref

ref: ContentRef

Stable identity used by ContentSnapshot.get.

Type: ContentRef

Required

shoalrun.content.ContentResource.representations

Property shoalrun.content.ContentResource.representations

representations: Partial<Record<ContentFormat, ContentRepresentation>>

Available portable formats and their files, anchors, and typed links.

Type: Partial<Record<ContentFormat, ContentRepresentation>>

Required

shoalrun.content.ContentResource.source

Property shoalrun.content.ContentResource.source

source?: { documentId?: string; snippetId?: string; valuesDigest?: string; } | undefined

Type: { documentId?: string; snippetId?: string; valuesDigest?: string; } | undefined

Optional

shoalrun.content.ContentResource.summary

Property shoalrun.content.ContentResource.summary

summary: string

Short explanation of the resource's purpose.

Type: string

Required

shoalrun.content.ContentResource.title

Property shoalrun.content.ContentResource.title

title: string

Human-readable resource title.

Type: string

Required

shoalrun.content.ContentResource.type

Property shoalrun.content.ContentResource.type

type: string

Authored document type, or section/snippet for a selected resource.

Type: string

Required

shoalrun.content.ContentRestEntry

Type shoalrun.content.ContentRestEntry

type ContentRestEntry = {
    key: string;
    resource: ContentResource;
};

One resource inventory entry with its REST lookup key.

Fields

shoalrun.content.ContentRestEntry.key

Property shoalrun.content.ContentRestEntry.key

key: string

Type: string

Required

shoalrun.content.ContentRestEntry.resource

Property shoalrun.content.ContentRestEntry.resource

resource: ContentResource

Type: ContentResource

Required

shoalrun.content.ContentRestError

Type shoalrun.content.ContentRestError

type ContentRestError = {
    error: {
        code: ContentRestErrorCode;
        message: string;
    };
};

JSON error envelope returned by the content REST service.

Fields

shoalrun.content.ContentRestError.error

Property shoalrun.content.ContentRestError.error

error: { code: ContentRestErrorCode; message: string; }

Type: { code: ContentRestErrorCode; message: string; }

Required

shoalrun.content.ContentRestErrorCode

Type shoalrun.content.ContentRestErrorCode

type ContentRestErrorCode = 'invalid_request' | 'not_found' | 'unsupported_format' | 'stale_revision' | 'method_not_allowed' | 'internal_error';

Error categories used by the content REST protocol.

shoalrun.content.ContentRestList

Type shoalrun.content.ContentRestList

type ContentRestList = {
    schemaVersion: 1 | 2;
    revision: string;
    publication: ContentPublication;
    resources: ContentRestEntry[];
};

Revision-scoped inventory envelope returned by the content REST service.

Fields

shoalrun.content.ContentRestList.publication

Property shoalrun.content.ContentRestList.publication

publication: ContentPublication

Type: ContentPublication

Required

shoalrun.content.ContentRestList.resources

Property shoalrun.content.ContentRestList.resources

resources: ContentRestEntry[]

Type: ContentRestEntry[]

Required

shoalrun.content.ContentRestList.revision

Property shoalrun.content.ContentRestList.revision

revision: string

Type: string

Required

shoalrun.content.ContentRestList.schemaVersion

Property shoalrun.content.ContentRestList.schemaVersion

schemaVersion: 1 | 2

Type: 1 | 2

Required

shoalrun.content.ContentRestResource

Type shoalrun.content.ContentRestResource

type ContentRestResource = {
    schemaVersion: 1 | 2;
    revision: string;
    publication: ContentPublication;
    key: string;
    resource: ContentResource;
};

Revision-scoped metadata envelope for a single content resource.

Fields

shoalrun.content.ContentRestResource.key

Property shoalrun.content.ContentRestResource.key

key: string

Type: string

Required

shoalrun.content.ContentRestResource.publication

Property shoalrun.content.ContentRestResource.publication

publication: ContentPublication

Type: ContentPublication

Required

shoalrun.content.ContentRestResource.resource

Property shoalrun.content.ContentRestResource.resource

resource: ContentResource

Type: ContentResource

Required

shoalrun.content.ContentRestResource.revision

Property shoalrun.content.ContentRestResource.revision

revision: string

Type: string

Required

shoalrun.content.ContentRestResource.schemaVersion

Property shoalrun.content.ContentRestResource.schemaVersion

schemaVersion: 1 | 2

Type: 1 | 2

Required

shoalrun.content.ContentResult

Type shoalrun.content.ContentResult

type ContentResult = {
    resource: Readonly<ContentResource>;
    representation: Readonly<ContentRepresentation>;
    format: ContentFormat;
    content: string;
    revision: string;
};

A fetched representation together with the metadata needed to render or route it.

Fields

shoalrun.content.ContentResult.content

Property shoalrun.content.ContentResult.content

content: string

Validated UTF-8 HTML or Markdown text.

Type: string

Required

shoalrun.content.ContentResult.format

Property shoalrun.content.ContentResult.format

format: ContentFormat

Representation actually returned by the source.

Type: ContentFormat

Required

shoalrun.content.ContentResult.representation

Property shoalrun.content.ContentResult.representation

representation: Readonly<ContentRepresentation>

File, media type, anchors, and typed links for the selected format.

Type: Readonly<ContentRepresentation>

Required

shoalrun.content.ContentResult.resource

Property shoalrun.content.ContentResult.resource

resource: Readonly<ContentResource>

Inventory entry that was selected by the requested reference.

Type: Readonly<ContentResource>

Required

shoalrun.content.ContentResult.revision

Property shoalrun.content.ContentResult.revision

revision: string

Revision shared by this response and its opened content snapshot.

Type: string

Required

shoalrun.content.ContentSnapshot

Interface shoalrun.content.ContentSnapshot

interface ContentSnapshot

A client pinned to one immutable inventory revision and publication.

Fields

Methods

shoalrun.content.ContentSnapshot.dispose

Method shoalrun.content.ContentSnapshot.dispose

dispose(): void

Cancel pending requests and prevent subsequent reads or inventory access.

Returns

void

shoalrun.content.ContentSnapshot.get

Method shoalrun.content.ContentSnapshot.get

get(ref: ContentRef, options: { format: ContentFormat; signal?: AbortSignal; }): Promise<ContentResult>

Fetch one available representation of a stable content reference.

Parameters

Returns

Promise<ContentResult>

Validated representation text with its routing and revision metadata.

shoalrun.content.ContentSnapshot.list

Method shoalrun.content.ContentSnapshot.list

list(): readonly Readonly<ContentResource>[]

List the resources in the opened inventory without fetching their bodies.

Returns

readonly Readonly<ContentResource>[]

Read-only resource entries for this publication and revision.

shoalrun.content.ContentSnapshot.publication

Property shoalrun.content.ContentSnapshot.publication

readonly publication: Readonly<ContentPublication>

Publication shared by every resource available from this snapshot.

Type: Readonly<ContentPublication>

Required

shoalrun.content.ContentSnapshot.revision

Property shoalrun.content.ContentSnapshot.revision

readonly revision: string

Content digest identifying this inventory revision.

Type: string

Required

shoalrun.content.ManifestContentSourceOptions

Type shoalrun.content.ManifestContentSourceOptions

type ManifestContentSourceOptions = {
    manifestUrl: string | URL;
    fetch?: typeof globalThis.fetch;
    signal?: AbortSignal;
    limits?: ContentDeliveryLimits;
};

Configuration for opening a static content-export manifest.

Fields

shoalrun.content.ManifestContentSourceOptions.fetch

Property shoalrun.content.ManifestContentSourceOptions.fetch

fetch?: ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined

Fetch implementation. Defaults to globalThis.fetch.

Type: ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined

Optional

shoalrun.content.ManifestContentSourceOptions.limits

Property shoalrun.content.ManifestContentSourceOptions.limits

limits?: ContentDeliveryLimits | undefined

Inventory and representation bounds.

Type: ContentDeliveryLimits | undefined

Optional

shoalrun.content.ManifestContentSourceOptions.manifestUrl

Property shoalrun.content.ManifestContentSourceOptions.manifestUrl

manifestUrl: string | URL

Manifest URL; a browser resolves relative URLs against its current location.

Type: string | URL

Required

shoalrun.content.ManifestContentSourceOptions.signal

Property shoalrun.content.ManifestContentSourceOptions.signal

signal?: AbortSignal | undefined

Cancel the opening request. Use get's signal to cancel an individual read.

Type: AbortSignal | undefined

Optional

shoalrun.content.RestContentSourceOptions

Type shoalrun.content.RestContentSourceOptions

type RestContentSourceOptions = {
    baseUrl: string | URL;
    publication: ContentPublication;
    revision?: string;
    fetch?: typeof globalThis.fetch;
    signal?: AbortSignal;
    limits?: ContentDeliveryLimits;
};

Options for a REST inventory and its revision-pinned resource reads.

Fields

shoalrun.content.RestContentSourceOptions.baseUrl

Property shoalrun.content.RestContentSourceOptions.baseUrl

baseUrl: string | URL

REST mount URL, such as /content/v1. Browser requests must use the application's origin.

Type: string | URL

Required

shoalrun.content.RestContentSourceOptions.fetch

Property shoalrun.content.RestContentSourceOptions.fetch

fetch?: ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined

Fetch implementation. Defaults to globalThis.fetch.

Type: ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined

Optional

shoalrun.content.RestContentSourceOptions.limits

Property shoalrun.content.RestContentSourceOptions.limits

limits?: ContentDeliveryLimits | undefined

Inventory and representation bounds.

Type: ContentDeliveryLimits | undefined

Optional

shoalrun.content.RestContentSourceOptions.publication

Property shoalrun.content.RestContentSourceOptions.publication

publication: ContentPublication

Exact publication to request; include product for a product-scoped source.

Type: ContentPublication

Required

shoalrun.content.RestContentSourceOptions.revision

Property shoalrun.content.RestContentSourceOptions.revision

revision?: string | undefined

Expected inventory revision. Omit it to open the current revision.

Type: string | undefined

Optional

shoalrun.content.RestContentSourceOptions.signal

Property shoalrun.content.RestContentSourceOptions.signal

signal?: AbortSignal | undefined

Cancel the inventory-opening request.

Type: AbortSignal | undefined

Optional

shoalrun.content.contentRefKey

Function shoalrun.content.contentRefKey

contentRefKey(ref: ContentRef): string

Serialize a reference to a deterministic key without including publication scope.

Parameters

Returns

string

shoalrun.content.contentResourceKey

Function shoalrun.content.contentResourceKey

contentResourceKey(ref: ContentRef): string

Public identity only: independent of publication, revision, and export filenames.

Parameters

Returns

string

shoalrun.content.mountContent

Function shoalrun.content.mountContent

mountContent(container: Element, result: ContentResult, options?: { instanceId?: string; signal?: AbortSignal; }): ContentMount

Mount trusted compiler HTML with instance-specific anchor and accessibility IDs. This is not a sanitizer. The result must come from trusted compiler output. The mount replaces the container's children and rewrites local routing metadata.

Parameters

Returns

ContentMount

Rewritten anchors, typed links, and an unmount handle.

shoalrun.content.openManifestContentSource

Function shoalrun.content.openManifestContentSource

openManifestContentSource(options: ManifestContentSourceOptions): Promise<ContentSnapshot>

Open and validate one immutable static manifest revision. The caller owns trust in the compiler output and host. Browser URLs must use the application's origin. Requests reject redirects and unexpected content types.

Parameters

Returns

Promise<ContentSnapshot>

A revision-pinned snapshot for listing and reading exported resources.

Examples

const snapshot = await openManifestContentSource({ manifestUrl: '/help/manifest.json' });
const page = await snapshot.get({ kind: 'page', documentId: 'guide.start' }, { format: 'markdown' });
snapshot.dispose();

shoalrun.content.openRestContentSource

Function shoalrun.content.openRestContentSource

openRestContentSource(options: RestContentSourceOptions): Promise<ContentSnapshot>

Open a REST inventory and pin subsequent resource reads to its revision.

Parameters

Returns

Promise<ContentSnapshot>

A snapshot with the same list/get/dispose interface as the manifest source.

shoalrun.content.validateContentManifest

Function shoalrun.content.validateContentManifest

validateContentManifest(value: any, maxResources?: number, maxResourceBytes?: number): asserts value is ContentManifest

Validate a parsed manifest's shape, identities, paths, and resource bounds. This assertion narrows the value but doesn't verify fetched file bytes or trust in a host.

Parameters

Returns

void