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.ContentAsset

Type shoalrun.content.ContentAsset

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

A content-addressed file with its declared media type.

Fields

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.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.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.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.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.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.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.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.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.ContentRestEntry

Type shoalrun.content.ContentRestEntry

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

One resource inventory entry with its REST lookup key.

Fields

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.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.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.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.ContentSnapshot

Interface shoalrun.content.ContentSnapshot

interface ContentSnapshot

A client pinned to one immutable inventory revision and publication.

Fields

Methods

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.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.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