@inneropen/marvin-astro 1.0.0-next.1

package/dist/index.d.ts

@@ -0,0 +1,576 @@
+import { MarkedOptions } from 'marked';
+import { MarvinContentEntry, ApiSite, ApiSeo, ApiSiteChrome, ApiNavigationLink, ApiSocialLink, AssetSelectOptions, ApiImage, ApiResourceLink, SectionLanding } from './types.js';
+export { ApiActionVariant, ApiHero, ApiHeroAction, ApiPageAction } from './types.js';
+import * as _inneropen_marvin_sdk from '@inneropen/marvin-sdk';
+import { MarvinClient, MarvinEntry, Entry, PublishedCollectionSummary, Collection, CollectionEntry, MarvinSite, Workspace, MarvinAsset, MarvinResource } from '@inneropen/marvin-sdk';
+
+type MarkdownOptions = MarkedOptions;
+type MarkdownRenderer = (markdown: string | string[] | null | undefined) => Promise<string>;
+/**
+ * A markdown renderer with its own `marked` instance — options are per-site, not global, so two
+ * `createMarvinContent()` instances in one process can't clobber each other's settings.
+ *
+ * `breaks: false` is the default because CMS body copy is authored as prose: a soft-wrapped
+ * paragraph should render as one paragraph. Where authored line breaks must survive (a landing
+ * intro, an address block), pass `breaks: true` or pre-convert with a trailing double space.
+ */
+declare function createMarkdownRenderer(options?: MarkdownOptions): MarkdownRenderer;
+/** Turn single newlines into hard breaks, leaving paragraph breaks alone. */
+declare function preserveSoftBreaks(source: string): string;
+
+/**
+ * Configuration + environment resolution.
+ *
+ * Precedence for every value: explicit option → `import.meta.env` → `process.env`.
+ * Astro exposes server-side env through `import.meta.env`; a plain Node script
+ * (a smoke test, a build hook) only has `process.env`. Both work, unchanged.
+ */
+
+type MarvinLogger = {
+    log: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+};
+declare const ENV_KEYS: {
+    readonly apiUrl: "MARVIN_API_URL";
+    readonly siteClientToken: "MARVIN_SITE_CLIENT_TOKEN";
+    readonly workspaceSlug: "MARVIN_WORKSPACE_SLUG";
+    readonly debug: "MARVIN_DEBUG";
+};
+/** Dev default for the network-failure latch: retry a downed backend after 30s. */
+declare const DEFAULT_DEV_RETRY_MS = 30000;
+type MarvinAstroConfig = {
+    apiUrl?: string;
+    siteClientToken?: string;
+    workspaceSlug?: string;
+    /** Log the resolved env once at startup, and enable SDK request logging. */
+    debug?: boolean;
+    /**
+     * How long the network-failure latch stays closed before the backend is retried.
+     * Defaults to 30s in dev and `Infinity` in production — a build should fail fast and
+     * consistently rather than half-succeed with some pages live and some pages static.
+     */
+    retryAfterMs?: number;
+    logger?: MarvinLogger;
+    /** Markdown rendering options; defaults to `{ gfm: true, breaks: false }`. */
+    markdown?: MarkdownOptions;
+    /** Explicit env source. Highest priority after direct options — mainly a test seam. */
+    env?: Record<string, string | undefined>;
+    /** Injectable clock, so latch expiry is testable without waiting. */
+    now?: () => number;
+    /** Injectable SDK client factory — a test seam; defaults to the SDK's `createMarvinClient`. */
+    createClient?: (config: MarvinClientOptions) => unknown;
+};
+type MarvinClientOptions = {
+    apiUrl: string;
+    siteClientToken: string;
+    workspaceSlug: string;
+    debug: boolean;
+};
+type ResolvedConfig = {
+    apiUrl: string;
+    siteClientToken: string;
+    workspaceSlug: string;
+    debug: boolean;
+    retryAfterMs: number;
+    logger: MarvinLogger;
+    markdown?: MarkdownOptions;
+    now: () => number;
+    createClient?: (config: MarvinClientOptions) => unknown;
+    /** True when all three connection values are present. */
+    configured: boolean;
+};
+/** Read one env var, honouring the documented precedence. */
+declare function readEnv(key: string, override?: Record<string, string | undefined>): string | undefined;
+declare function resolveConfig(options?: MarvinAstroConfig): ResolvedConfig;
+/** One-line summary of the resolved env, with the token masked. For `debug` logging. */
+declare function describeConfig(config: ResolvedConfig): Record<string, unknown>;
+
+/**
+ * SDK client construction and the network-failure latch.
+ *
+ * The latch exists because a static build asks for content once per path. When the backend is
+ * down, that is N failed requests with N timeouts before the build gives up. The latch trips on
+ * the first network failure and short-circuits the rest.
+ *
+ * Unlike the hand-rolled original it is *retryable*: it expires after `retryAfterMs` so a dev
+ * server recovers on its own when the backend comes back, instead of serving stale static data
+ * until someone restarts it. Production keeps the permanent latch — a build should fail fast and
+ * consistently rather than half-succeed.
+ */
+
+declare function errorMessage(error: unknown): string;
+/**
+ * A network failure means "the backend is unreachable", not "this request was bad". Only the
+ * former should trip the latch — a 404 on one entry says nothing about the next one.
+ */
+declare function isNetworkFailure(error: unknown): boolean;
+type MarvinBackend = {
+    readonly config: ResolvedConfig;
+    /** True when Marvin is configured AND not currently latched out. */
+    hasBackend(): boolean;
+    /** The SDK client. Throws when Marvin is not configured. */
+    client(): MarvinClient;
+    /** Trip the latch if this error indicates the backend is unreachable. */
+    remember(error: unknown): void;
+    /** True while the latch is closed (backend considered unreachable). */
+    isLatched(): boolean;
+    /** Manually re-open the latch, e.g. after a deploy. */
+    clearLatch(): void;
+    warn(message: string): void;
+};
+declare function createBackend(options?: MarvinAstroConfig): MarvinBackend;
+
+/**
+ * Every call into Marvin, wrapped the same way: skip when there's no backend, catch, remember
+ * network failures for the latch, warn once, and return an empty value the caller can fall
+ * back from. Nothing here throws.
+ */
+
+/** An entry that carries `data_json` — i.e. schema fields are readable. */
+type HydratedEntry = MarvinEntry | Entry;
+type MarvinFetcher = ReturnType<typeof createFetcher>;
+declare function createFetcher(backend: MarvinBackend): {
+    backend: MarvinBackend;
+    collections(): Promise<PublishedCollectionSummary[]>;
+    collection(slug: string): Promise<Collection | null>;
+    collectionEntries(slug: string): Promise<CollectionEntry[]>;
+    /** Try each collection slug in order; return the first that yields entries. */
+    collectionEntriesFallback(slugs: string[]): Promise<CollectionEntry[]>;
+    hydratedCollectionEntries(slug: string): Promise<HydratedEntry[]>;
+    hydratedCollectionEntriesFallback(slugs: string[]): Promise<HydratedEntry[]>;
+    hydrate: (entries: MarvinContentEntry[]) => Promise<HydratedEntry[]>;
+    entry: (slug: string) => Promise<Entry | null>;
+    site(): Promise<MarvinSite | null>;
+    workspace(): Promise<Workspace | null>;
+    assets(type?: string): Promise<MarvinAsset[]>;
+    asset(slugOrId: string): Promise<MarvinAsset | null>;
+    resources(resourceType?: string): Promise<MarvinResource[]>;
+};
+
+/**
+ * Site identity + SEO.
+ *
+ * Marvin's site configuration is optional almost everywhere; a template that had to guard every
+ * field would be unreadable. This resolves it once into an `ApiSite` where title, description,
+ * siteName, locale and timezone are always present, and where brand asset slugs have already
+ * become URLs.
+ */
+
+type SiteOptions = {
+    /**
+     * Static identity to fall back to, field by field, when Marvin is unreachable or leaves a
+     * value unset. Anything omitted here falls through to a neutral default.
+     */
+    fallback?: Partial<ApiSite> | (() => Partial<ApiSite>);
+    /** Default locale when neither Marvin nor the fallback sets one. Default `'en-US'`. */
+    defaultLocale?: string;
+    /** Default timezone when neither Marvin nor the fallback sets one. Default `'UTC'`. */
+    defaultTimezone?: string;
+};
+/**
+ * Build resolved SEO from Marvin's raw SiteSeo block, applying identity fallbacks so title,
+ * description and siteName are never empty. Absent → sensible defaults (robots `index,follow`;
+ * og type `website`; large-image Twitter card).
+ */
+declare function buildSeo(raw: Record<string, unknown> | undefined, identity: {
+    title: string;
+    description: string;
+    canonicalUrl?: string;
+    siteName: string;
+}): ApiSeo;
+/** The offline site: the caller's fallback, with neutral defaults under it. */
+declare function buildFallbackSite(options?: SiteOptions): ApiSite;
+type SiteLoader = {
+    get(): Promise<ApiSite>;
+    reset(): void;
+};
+declare function createSiteLoader(fetcher: MarvinFetcher, options?: SiteOptions): SiteLoader;
+
+/**
+ * Site chrome: main nav, footer columns, legal strip, social links, inquiry link.
+ *
+ * All of it comes from ordinary Marvin collections, so a workspace can reorder its own
+ * navigation without a deploy. Every piece has a static fallback for when the backend is down.
+ */
+
+type NavigationContext = 'main' | 'footer';
+type HrefContext = {
+    /** Where this link is being rendered. */
+    context: NavigationContext;
+    /** The nav collection the entry was read from. */
+    collectionSlug: string;
+    slug: string;
+    /** Every collection the entry belongs to, nav collections included. */
+    collections: string[];
+    /** The collection slugs treated as navigation, i.e. not route prefixes. */
+    navCollections: Set<string>;
+};
+type ResolveHref = (entry: MarvinContentEntry, context: HrefContext) => string;
+/** A link authored in site code rather than in the CMS. */
+type NavigationLinkInput = {
+    label: string;
+    href: string;
+    description?: string;
+    role?: string;
+};
+type SocialLinkInput = NavigationLinkInput & {
+    icon: string;
+};
+type ChromeOptions = {
+    /** Collection holding the main nav. Default `'main-navigation'`. */
+    mainCollection?: string;
+    /** Collection holding the footer nav. Default `'footer-navigation'`. */
+    footerCollection?: string;
+    /**
+     * Route for a nav entry that carries no explicit `href`/`url`/`path` field.
+     *
+     * The default prefixes the entry's own (non-navigation) collection: an entry in
+     * `workshop-reference` becomes `/workshop-reference/<slug>`, and an entry in no other
+     * collection becomes `/<slug>`. Override when routes don't mirror collections.
+     */
+    resolveHref?: ResolveHref;
+    /** Membership role that marks a footer link as legal (Terms, Privacy…). Default `'legal'`. */
+    legalRole?: string;
+    /** Footer links per column once split. Columns are only created above this count. */
+    footerColumnThreshold?: number;
+    fallback?: {
+        mainNavigation?: NavigationLinkInput[];
+        footerNavigation?: NavigationLinkInput[][];
+        legalLinks?: NavigationLinkInput[];
+        socialLinks?: SocialLinkInput[];
+        inquiry?: NavigationLinkInput;
+    };
+};
+declare function toNavigationLink(link: NavigationLinkInput): ApiNavigationLink;
+/** Collection-prefixed routing: `/<owning-collection>/<slug>`, else `/<slug>`. */
+declare const defaultResolveHref: ResolveHref;
+/** A `{label, href}` object stored loose in site metadata (e.g. `metadata.inquiry`). */
+declare function metadataLink(value: unknown): ApiNavigationLink | undefined;
+declare function socialLinkFromKey(key: string, href: string): ApiSocialLink;
+type ChromeLoader = {
+    get(): Promise<ApiSiteChrome>;
+    reset(): void;
+};
+declare function createChromeLoader(fetcher: MarvinFetcher, siteLoader: SiteLoader, options?: ChromeOptions): ChromeLoader;
+
+/**
+ * The field accessor handed to a repository's `transform`.
+ *
+ * Every reader defaults to the documented precedence — `data_json` first, `metadata_json`
+ * second — so a transform reads like a field list instead of a pile of coalescing operators.
+ */
+
+type ImageFieldOptions = Omit<AssetSelectOptions, 'type' | 'types'> & {
+    /**
+     * Exact roles to prefer, in order, before the looser role/usage match. Use for derived
+     * variants — e.g. `['hero-grade']` to prefer a colour-graded hero over the raw upload.
+     */
+    preferRoles?: string[];
+    /** `metadata_json` key holding a hand-authored `{src, alt, focalPoint}`. */
+    metadataKey?: string | false;
+    /** Alt text when the asset carries none. Defaults to the entry title. */
+    alt?: string;
+    /** Fall back to the list item's `featuredAsset`. Default `true`. */
+    fallbackToFeatured?: boolean;
+};
+type IconFieldOptions = {
+    roles?: string[];
+    /** Fall back to the list item's `featuredAsset` when no icon asset is attached. */
+    fallbackToFeatured?: boolean;
+};
+type MarkdownFieldOptions = {
+    /** Keep authored single newlines as hard breaks. Default `false`. */
+    softBreaks?: boolean;
+};
+type ResourceFieldOptions = {
+    /** Keep only these resource types, e.g. `['material', 'construction']`. */
+    types?: string[];
+    /** Keep only resources attached with this role. */
+    role?: string;
+    /** Build an href from the resource slug. */
+    href?: (slug: string) => string;
+};
+type FieldAccessor = ReturnType<typeof createFieldAccessor>;
+type FieldAccessorContext = {
+    renderMarkdown: MarkdownRenderer;
+    /** The route this entry resolves to, if the repository was given an `href` builder. */
+    href?: string;
+    /** The collection the entry was loaded from, when it came from one. */
+    collection?: string;
+};
+declare function createFieldAccessor(entry: MarvinContentEntry, context: FieldAccessorContext): {
+    /** The entry itself, for anything the accessor doesn't cover. */
+    entry: MarvinContentEntry;
+    /** The route this entry resolves to (from the repository's `href` option). */
+    href: string | undefined;
+    collection: string | undefined;
+    /** `data_json` → `metadata_json`, untyped. */
+    raw(key: string): unknown;
+    string(key: string): string | undefined;
+    number(key: string): number | undefined;
+    /** Booleans authored as strings (`"true"`, `"1"`, `"yes"`) read as booleans. */
+    bool(key: string): boolean;
+    /** A string array, tolerating a single string authored in place of a list. */
+    list(key: string): string[] | undefined;
+    /**
+     * An enum-guarded read: the value if it's in `allowed`, else `fallback`. Replaces the
+     * per-field `normalizeStatus`/`normalizeCategory`/`normalizeTone` guards that every site
+     * ends up writing.
+     */
+    oneOf<T extends string>(key: string, allowed: readonly T[] | Set<T>, fallback: T): T;
+    /** A field read as a display date ("Mon DD, YYYY"); already-formatted values pass through. */
+    date(key: string): string | undefined;
+    /** The raw ISO publish timestamp, if any. */
+    publishedAt(): string | undefined;
+    /**
+     * Render a markdown field to HTML. Falls back to the entry's `contentMarkdown` when the
+     * named field is absent. Returns `undefined` when there is nothing to render, so the
+     * caller can omit the property rather than emit an empty string.
+     */
+    markdown(key?: string, options?: MarkdownFieldOptions): Promise<string | undefined>;
+    /**
+     * The entry's primary image. Checks, in order: a hand-authored `metadata_json.featuredImage`,
+     * the exact `preferRoles`, a role/usage match over the entry's image assets, and finally the
+     * list item's `featuredAsset`.
+     */
+    image(options?: ImageFieldOptions): ApiImage | undefined;
+    /** URL of the entry's icon asset (`role: icon`, SVG preferred). */
+    icon(options?: IconFieldOptions): string | undefined;
+    /** The raw asset placement matching `options` — when you need more than src/alt/focal. */
+    asset(options?: AssetSelectOptions): Record<string, unknown> | undefined;
+    /** The asset whose role is EXACTLY one of `roles`, in preference order. */
+    assetByRole(...roles: string[]): Record<string, unknown> | undefined;
+    /** All asset placements on the entry. */
+    assets(): Record<string, unknown>[];
+    /** Every image asset resolved, filtered by role/usage — support/detail galleries. */
+    images(options?: ImageFieldOptions): (ApiImage & {
+        usage?: string;
+    })[];
+    /** Attached resources, normalized to name/type/role/href. */
+    resources(options?: ResourceFieldOptions): ApiResourceLink[];
+    /** The first attached resource matching `options`. */
+    resource(options?: ResourceFieldOptions): ApiResourceLink | undefined;
+    /** The `metadata_json` blob. */
+    metadata(): Record<string, unknown>;
+    /** The `data_json` blob. Empty on a list item that was not hydrated. */
+    data(): Record<string, unknown>;
+    /** Slugs of every collection the entry belongs to. */
+    collections(): string[];
+    /** The entry's membership role within `collectionSlug`. */
+    role(collectionSlug: string): string | undefined;
+};
+
+/**
+ * The repository factory.
+ *
+ * `getAll` / `getBySlug` / `getFeatured` is the same forty lines of try / fallback / memoize
+ * around every content type on every site. Only the transform differs. This holds the forty
+ * lines; the site writes the transform.
+ */
+
+type RepositoryOptions<T> = {
+    /** Collection slug to load from. */
+    collection?: string;
+    /**
+     * Collection slugs tried in order; the first one that yields entries wins. Lets a site work
+     * against workspaces that named the same thing `bench-notes`, `journal`, or `blog`.
+     */
+    collections?: string[];
+    /**
+     * Fetch each list item as a full entry before transforming.
+     *
+     * The collection endpoint returns `PublishedEntryListItem`, which omits `data_json`; the
+     * single-entry endpoint returns `PublishedEntryRead`, which includes it. So if the transform
+     * reads ANY schema-defined field — anything not title/slug/summary/metadata — this must be
+     * `true` or those fields come back `undefined`. It costs one request per entry.
+     */
+    hydrate?: boolean;
+    /** Build the resolved item from an entry. May be async (e.g. to render markdown). */
+    transform: (entry: MarvinContentEntry, fields: FieldAccessor) => T | Promise<T>;
+    /** Static data to serve when Marvin is unreachable or the collection is empty. */
+    fallback?: () => T[] | Promise<T[]>;
+    /** Applied to Marvin and fallback results alike, so ordering doesn't depend on the source. */
+    sort?: (a: T, b: T) => number;
+    /** Applied to Marvin and fallback results alike. */
+    filter?: (item: T) => boolean;
+    /** The route an entry resolves to; exposed to the transform as `fields.href`. */
+    href?: (slug: string, entry: MarvinContentEntry) => string;
+    /** How to read an item's slug for `bySlug`. Defaults to `item.slug`. */
+    slugOf?: (item: T) => string | undefined;
+    /** How to tell whether an item is featured. Defaults to `item.featured`. */
+    isFeatured?: (item: T) => boolean;
+};
+type Repository<T> = {
+    /** Every item, resolved once per process. */
+    all(): Promise<T[]>;
+    /** One item by slug — a direct entry fetch, falling back to a scan of `all()`. */
+    bySlug(slug: string): Promise<T | undefined>;
+    /** The first featured item, or the first item when none is marked. */
+    featured(): Promise<T | undefined>;
+    /** Every featured item, in `all()` order. */
+    allFeatured(): Promise<T[]>;
+    /** Drop the memoized results. Next call re-fetches. */
+    reset(): void;
+};
+type RepositoryContext = {
+    fetcher: MarvinFetcher;
+    renderMarkdown: MarkdownRenderer;
+};
+declare function createRepository<T>(context: RepositoryContext, options: RepositoryOptions<T>): Repository<T>;
+
+type SectionLandingOptions = {
+    /** Asset role to use as the hero image. Default `'hero'`. */
+    heroRole?: string;
+    /** Field holding the intro copy. Default `'body'`, falling back to the entry summary. */
+    bodyField?: string;
+};
+/**
+ * Resolve a section-landing header from a Marvin `page` entry with the given slug.
+ *
+ * The intro is rendered with authored line breaks preserved — landing copy is written as a few
+ * deliberate lines, not a soft-wrapped paragraph, and losing those breaks changes the layout.
+ */
+declare function loadSectionLanding(fetcher: MarvinFetcher, slug: string, renderMarkdown?: MarkdownRenderer, options?: SectionLandingOptions): Promise<SectionLanding>;
+
+/**
+ * Format a date value for display as "Mon DD, YYYY".
+ *
+ * ISO dates/timestamps (e.g. a raw `publishedAt` like "2026-07-21T21:22:42.045708Z") are read in
+ * UTC — via the date part only, so there's no off-by-one day shift from the viewer's timezone.
+ * Values that are already human-readable (e.g. a hand-entered "Jul 02, 2024") pass through
+ * unchanged, and empty input returns `undefined` so callers can omit the field.
+ */
+declare function formatDisplayDate(value: string | null | undefined): string | undefined;
+/**
+ * Pick `count` items deterministically from `items`, seeded by `pageSlug`.
+ *
+ * Same page → same selection on every build, different pages → different selections. Use for
+ * rotating pull-quotes, value bands, related links: variety across the site without the
+ * hydration mismatch a random pick would cause.
+ */
+declare function selectValuesForPage<T>(items: T[], pageSlug: string, count?: number): T[];
+
+/**
+ * Reading Marvin payloads.
+ *
+ * The published API returns the same logical value in several shapes depending on which
+ * endpoint produced it (list item vs full read, SDK `Entry` wrapper vs raw JSON, placement
+ * metadata vs asset metadata). Every reader here is total: it takes `unknown`, checks, and
+ * returns `undefined` rather than throwing.
+ */
+
+/** A non-empty string, or `undefined`. Empty/whitespace strings are treated as absent. */
+declare function asString(value: unknown): string | undefined;
+declare function asRecord(value: unknown): Record<string, unknown>;
+declare function asNumber(value: unknown): number | undefined;
+declare function asStringArray(value: unknown): string[] | undefined;
+/** `metadata_json` — the free-form blob every entry carries, whatever its schema. */
+declare function entryMetadata(entry: MarvinContentEntry): Record<string, unknown>;
+/** `data_json` — the schema-defined fields. Absent on list items until hydrated. */
+declare function entryData(entry: MarvinContentEntry): Record<string, unknown>;
+/**
+ * Read a schema field (`data_json`) from an entry, through the SDK's `Entry` accessor when
+ * present and off the raw payload otherwise.
+ */
+declare function entryField<T = unknown>(entry: MarvinContentEntry, key: string): T | undefined;
+/**
+ * The precedence rule: structured schema field first (`data_json`), legacy blob second
+ * (`metadata_json`).
+ *
+ * An empty string counts as absent, which matters more than it sounds — an entry type that
+ * declares a field the author left blank stores `""`, and without this the legacy value that
+ * *is* set would never surface.
+ */
+declare function field<T = unknown>(entry: MarvinContentEntry, key: string): T | undefined;
+/**
+ * Read a value off a published asset placement, checking every level the API might have put it
+ * at: the placement itself, its metadata blobs, then the underlying asset and its blobs.
+ */
+declare function assetField<T = unknown>(asset: unknown, key: string): T | undefined;
+/** Same layered read as {@link assetField}, for resource relationships. */
+declare function resourceField<T = unknown>(resource: unknown, key: string): T | undefined;
+/**
+ * The entry's collection memberships as slugs. Collections arrive as bare slugs on list items,
+ * flat `{slug}` objects, or the SDK's nested `{collection: {slug}}` — all three are read here.
+ */
+declare function collectionSlugs(entry: MarvinContentEntry): string[];
+/**
+ * The entry's membership role within one specific collection (e.g. `'legal'` in
+ * `footer-navigation`). A hydrated entry carries all of its memberships; this finds the one for
+ * the given collection.
+ */
+declare function collectionRole(entry: MarvinContentEntry, collectionSlug: string): string | undefined;
+/**
+ * A CSS `object-position` value from a focal point. Marvin stores these either pre-formatted
+ * (`"40% 60%"`) or as `{x, y}` in 0–1 or 0–100 units.
+ */
+declare function focalPoint(value: unknown): string | undefined;
+declare function entryAssets(entry: MarvinContentEntry): Record<string, unknown>[];
+declare function entryResources(entry: MarvinContentEntry): Record<string, unknown>[];
+declare function selectEntryAsset(entry: MarvinContentEntry, options?: AssetSelectOptions): Record<string, unknown> | undefined;
+/**
+ * Match on role ALONE, exactly. `selectEntryAsset` ORs role against a vacuously-true usage
+ * check, so `{roles: ['hero-grade']}` there matches the entry's first asset whatever its role.
+ * When you mean "the asset whose role is exactly this", use this.
+ */
+declare function selectAssetByRole(entry: MarvinContentEntry, ...roles: string[]): Record<string, unknown> | undefined;
+/** The list-item shorthand: `featuredAsset` is present on collection entries. */
+declare function selectFeaturedAsset(entry: MarvinContentEntry): Record<string, unknown> | undefined;
+declare function selectImageAsset(entry: MarvinContentEntry, options?: Omit<AssetSelectOptions, 'type' | 'types'>): Record<string, unknown> | undefined;
+declare function selectIconAsset(entry: MarvinContentEntry): Record<string, unknown> | undefined;
+declare function assetUrl(asset: unknown): string | undefined;
+declare function assetAlt(asset: unknown, fallback?: string): string | undefined;
+declare function resourceRole(resource: unknown): string | undefined;
+declare function isExternalHref(href: string): boolean;
+
+type MarvinContentOptions = MarvinAstroConfig & {
+    site?: SiteOptions;
+    chrome?: ChromeOptions;
+};
+type MarvinContent = ReturnType<typeof createMarvinContent>;
+/**
+ * Build the content layer for one Marvin workspace.
+ *
+ * Connection settings come from `MARVIN_API_URL`, `MARVIN_SITE_CLIENT_TOKEN` and
+ * `MARVIN_WORKSPACE_SLUG` unless passed explicitly. Everything returned degrades to its static
+ * fallback when the backend is unreachable, so a site still builds offline.
+ */
+declare function createMarvinContent(options?: MarvinContentOptions): {
+    /** The resolved configuration, with the token still in place — don't log it. */
+    config: ResolvedConfig;
+    /** Latch control and the raw SDK client. */
+    backend: MarvinBackend;
+    /** Guarded, never-throwing wrappers around every published endpoint. */
+    fetch: {
+        backend: MarvinBackend;
+        collections(): Promise<_inneropen_marvin_sdk.PublishedCollectionSummary[]>;
+        collection(slug: string): Promise<_inneropen_marvin_sdk.Collection | null>;
+        collectionEntries(slug: string): Promise<_inneropen_marvin_sdk.CollectionEntry[]>;
+        collectionEntriesFallback(slugs: string[]): Promise<_inneropen_marvin_sdk.CollectionEntry[]>;
+        hydratedCollectionEntries(slug: string): Promise<HydratedEntry[]>;
+        hydratedCollectionEntriesFallback(slugs: string[]): Promise<HydratedEntry[]>;
+        hydrate: (entries: MarvinContentEntry[]) => Promise<HydratedEntry[]>;
+        entry: (slug: string) => Promise<_inneropen_marvin_sdk.Entry | null>;
+        site(): Promise<_inneropen_marvin_sdk.MarvinSite | null>;
+        workspace(): Promise<_inneropen_marvin_sdk.Workspace | null>;
+        assets(type?: string): Promise<_inneropen_marvin_sdk.MarvinAsset[]>;
+        asset(slugOrId: string): Promise<_inneropen_marvin_sdk.MarvinAsset | null>;
+        resources(resourceType?: string): Promise<_inneropen_marvin_sdk.MarvinResource[]>;
+    };
+    renderMarkdown: MarkdownRenderer;
+    /** True when Marvin is configured and not currently latched out as unreachable. */
+    hasBackend: () => boolean;
+    /** Resolved site identity, SEO and brand assets. Memoized per process. */
+    getSite(): Promise<ApiSite>;
+    /** Navigation, footer, legal, social and inquiry links. Memoized per process. */
+    getSiteChrome(): Promise<ApiSiteChrome>;
+    /** Title/intro/hero for an index page, driven by a `page` entry of the same slug. */
+    getSectionLanding(slug: string, sectionOptions?: SectionLandingOptions): Promise<SectionLanding>;
+    /** A collection-backed content repository: `all()` / `bySlug()` / `featured()`. */
+    repository<T>(repositoryOptions: RepositoryOptions<T>): Repository<T>;
+    /** Drop every memoized result and re-open the failure latch. */
+    reset(): void;
+};
+
+export { ApiImage, ApiNavigationLink, ApiResourceLink, ApiSeo, ApiSite, ApiSiteChrome, ApiSocialLink, AssetSelectOptions, type ChromeLoader, type ChromeOptions, DEFAULT_DEV_RETRY_MS, ENV_KEYS, type FieldAccessor, type HrefContext, type HydratedEntry, type IconFieldOptions, type ImageFieldOptions, type MarkdownFieldOptions, type MarkdownOptions, type MarkdownRenderer, type MarvinAstroConfig, type MarvinBackend, type MarvinContent, MarvinContentEntry, type MarvinContentOptions, type MarvinFetcher, type MarvinLogger, type NavigationContext, type NavigationLinkInput, type Repository, type RepositoryContext, type RepositoryOptions, type ResolveHref, type ResolvedConfig, type ResourceFieldOptions, SectionLanding, type SectionLandingOptions, type SiteLoader, type SiteOptions, type SocialLinkInput, asNumber, asRecord, asString, asStringArray, assetAlt, assetField, assetUrl, buildFallbackSite, buildSeo, collectionRole, collectionSlugs, createBackend, createChromeLoader, createFetcher, createFieldAccessor, createMarkdownRenderer, createMarvinContent, createRepository, createSiteLoader, defaultResolveHref, describeConfig, entryAssets, entryData, entryField, entryMetadata, entryResources, errorMessage, field, focalPoint, formatDisplayDate, isExternalHref, isNetworkFailure, loadSectionLanding, metadataLink, preserveSoftBreaks, readEnv, resolveConfig, resourceField, resourceRole, selectAssetByRole, selectEntryAsset, selectFeaturedAsset, selectIconAsset, selectImageAsset, selectValuesForPage, socialLinkFromKey, toNavigationLink };