@inneropen/marvin-astro 1.1.1 → 1.2.1

package/src/components/renderers/ArticleRenderer.astro

@@ -0,0 +1,56 @@
+---
+import type { RendererEntry } from '../../renderers/types.js';
+import { extractBody, getFeaturedAsset } from '../../renderers/resolve.js';
+import { entryEmbeds } from '../../embeds.js';
+import type { MarkdownRenderer } from '../../markdown.js';
+import { defaultRenderMarkdown } from '../markdown.js';
+
+interface Props {
+  entry: RendererEntry;
+  config?: Record<string, unknown>;
+  class?: string;
+  /** The site's renderer (`marvin.renderMarkdown`) so its markdown options apply. */
+  renderMarkdown?: MarkdownRenderer;
+}
+
+const { entry, config, class: className, renderMarkdown = defaultRenderMarkdown } = Astro.props;
+
+// The body is markdown: render it (with the entry's media embeds) rather than inject it raw.
+const source = extractBody(entry);
+const body = source ? await renderMarkdown(source, { embeds: entryEmbeds(entry) }) : undefined;
+const featuredAsset = getFeaturedAsset(entry);
+const typeSlug = entry.entryTypeInfo?.slug ?? 'article';
+---
+
+<article
+  data-renderer="article"
+  data-entry-type={typeSlug}
+  class={className}
+>
+  {featuredAsset?.publicUrl && (
+    <figure data-role="featured-asset">
+      <img
+        src={featuredAsset.publicUrl}
+        alt={featuredAsset.altText ?? entry.title}
+        width={featuredAsset.width}
+        height={featuredAsset.height}
+      />
+    </figure>
+  )}
+
+  <header data-role="header">
+    <h1 data-role="title">{entry.title}</h1>
+    {entry.summary && <p data-role="summary">{entry.summary}</p>}
+    {entry.publishedAt && (
+      <time data-role="published-at" datetime={entry.publishedAt}>
+        {new Date(entry.publishedAt).toLocaleDateString()}
+      </time>
+    )}
+  </header>
+
+  {body && (
+    <div data-role="body" set:html={body} />
+  )}
+
+  <slot />
+</article>

package/src/components/renderers/FaqRenderer.astro

@@ -0,0 +1,26 @@
+---
+import type { RendererEntry } from '../../renderers/types.js';
+
+interface Props {
+  entry: RendererEntry;
+  config?: Record<string, unknown>;
+  class?: string;
+}
+
+const { entry, config, class: className } = Astro.props;
+
+const typeSlug = entry.entryTypeInfo?.slug ?? 'faq';
+---
+
+<section
+  data-renderer="faq"
+  data-entry-type={typeSlug}
+  class={className}
+>
+  <h2 data-role="title">{entry.title}</h2>
+  {entry.summary && (
+    <p data-role="summary">{entry.summary}</p>
+  )}
+
+  <slot />
+</section>

package/src/components/renderers/NavigationRenderer.astro

@@ -0,0 +1,27 @@
+---
+import type { RendererEntry } from '../../renderers/types.js';
+import { extractField } from '../../renderers/resolve.js';
+
+interface Props {
+  entry: RendererEntry;
+  config?: Record<string, unknown>;
+  class?: string;
+}
+
+const { entry, config, class: className } = Astro.props;
+
+const href = extractField<string>(entry, 'href') ?? '#';
+const openInNewTab = extractField<boolean>(entry, 'openInNewTab') ?? false;
+const typeSlug = entry.entryTypeInfo?.slug ?? 'navigation-item';
+---
+
+<a
+  data-renderer="navigation"
+  data-entry-type={typeSlug}
+  class={className}
+  href={href}
+  {...openInNewTab ? { target: '_blank', rel: 'noopener noreferrer' } : {}}
+>
+  {entry.title}
+  <slot />
+</a>

package/src/components/renderers/PageRenderer.astro

@@ -0,0 +1,51 @@
+---
+import type { RendererEntry } from '../../renderers/types.js';
+import { extractBody, getFeaturedAsset } from '../../renderers/resolve.js';
+import { entryEmbeds } from '../../embeds.js';
+import type { MarkdownRenderer } from '../../markdown.js';
+import { defaultRenderMarkdown } from '../markdown.js';
+
+interface Props {
+  entry: RendererEntry;
+  config?: Record<string, unknown>;
+  class?: string;
+  /** The site's renderer (`marvin.renderMarkdown`) so its markdown options apply. */
+  renderMarkdown?: MarkdownRenderer;
+}
+
+const { entry, config, class: className, renderMarkdown = defaultRenderMarkdown } = Astro.props;
+
+// The body is markdown: render it (with the entry's media embeds) rather than inject it raw.
+const source = extractBody(entry);
+const body = source ? await renderMarkdown(source, { embeds: entryEmbeds(entry) }) : undefined;
+const featuredAsset = getFeaturedAsset(entry);
+const typeSlug = entry.entryTypeInfo?.slug ?? 'page';
+---
+
+<article
+  data-renderer="page"
+  data-entry-type={typeSlug}
+  class={className}
+>
+  {featuredAsset?.publicUrl && (
+    <figure data-role="featured-asset">
+      <img
+        src={featuredAsset.publicUrl}
+        alt={featuredAsset.altText ?? entry.title}
+        width={featuredAsset.width}
+        height={featuredAsset.height}
+      />
+    </figure>
+  )}
+
+  <header data-role="header">
+    <h1 data-role="title">{entry.title}</h1>
+    {entry.summary && <p data-role="summary">{entry.summary}</p>}
+  </header>
+
+  {body && (
+    <div data-role="body" set:html={body} />
+  )}
+
+  <slot />
+</article>

package/src/config.ts

@@ -0,0 +1,149 @@
+/**
+ * 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.
+ */
+
+import type { MarkdownOptions } from './markdown.js';
+
+export type MarvinLogger = {
+  log: (message: string, ...args: unknown[]) => void;
+  warn: (message: string, ...args: unknown[]) => void;
+  error: (message: string, ...args: unknown[]) => void;
+};
+
+export const ENV_KEYS = {
+  apiUrl: 'MARVIN_API_URL',
+  siteClientToken: 'MARVIN_SITE_CLIENT_TOKEN',
+  workspaceSlug: 'MARVIN_WORKSPACE_SLUG',
+  debug: 'MARVIN_DEBUG',
+} as const;
+
+/** Dev default for the network-failure latch: retry a downed backend after 30s. */
+export const DEFAULT_DEV_RETRY_MS = 30_000;
+
+/** How many entry reads `hydrate` keeps in flight at once. */
+export const DEFAULT_HYDRATE_CONCURRENCY = 6;
+
+export 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;
+  /**
+   * Maximum entry reads in flight at once while hydrating a collection. Firing every read at
+   * once makes a large collection time out on itself; the default of 6 keeps a 280-entry
+   * hydration well inside the SDK's per-request timeout.
+   */
+  hydrateConcurrency?: 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;
+};
+
+export type MarvinClientOptions = {
+  apiUrl: string;
+  siteClientToken: string;
+  workspaceSlug: string;
+  debug: boolean;
+};
+
+export type ResolvedConfig = {
+  apiUrl: string;
+  siteClientToken: string;
+  workspaceSlug: string;
+  debug: boolean;
+  retryAfterMs: number;
+  hydrateConcurrency: number;
+  logger: MarvinLogger;
+  markdown?: MarkdownOptions;
+  now: () => number;
+  createClient?: (config: MarvinClientOptions) => unknown;
+  /** True when all three connection values are present. */
+  configured: boolean;
+};
+
+function metaEnv(): Record<string, unknown> | undefined {
+  try {
+    return (import.meta as unknown as { env?: Record<string, unknown> }).env;
+  } catch {
+    return undefined;
+  }
+}
+
+function processEnv(): Record<string, string | undefined> | undefined {
+  try {
+    return typeof process !== 'undefined' ? process.env : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function nonEmpty(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+
+/** Read one env var, honouring the documented precedence. */
+export function readEnv(
+  key: string,
+  override?: Record<string, string | undefined>
+): string | undefined {
+  return nonEmpty(override?.[key]) ?? nonEmpty(metaEnv()?.[key]) ?? nonEmpty(processEnv()?.[key]);
+}
+
+function isProduction(override?: Record<string, string | undefined>): boolean {
+  const prodFlag = metaEnv()?.PROD;
+  if (typeof prodFlag === 'boolean') return prodFlag;
+  const mode = readEnv('NODE_ENV', override) ?? readEnv('MODE', override);
+  return mode === 'production';
+}
+
+export function resolveConfig(options: MarvinAstroConfig = {}): ResolvedConfig {
+  const env = options.env;
+  const apiUrl = options.apiUrl ?? readEnv(ENV_KEYS.apiUrl, env) ?? '';
+  const siteClientToken = options.siteClientToken ?? readEnv(ENV_KEYS.siteClientToken, env) ?? '';
+  const workspaceSlug = options.workspaceSlug ?? readEnv(ENV_KEYS.workspaceSlug, env) ?? '';
+  const debug = options.debug ?? readEnv(ENV_KEYS.debug, env) === 'true';
+
+  return {
+    apiUrl,
+    siteClientToken,
+    workspaceSlug,
+    debug,
+    retryAfterMs:
+      options.retryAfterMs ??
+      (isProduction(env) ? Number.POSITIVE_INFINITY : DEFAULT_DEV_RETRY_MS),
+    hydrateConcurrency: Math.max(1, Math.floor(options.hydrateConcurrency ?? DEFAULT_HYDRATE_CONCURRENCY)),
+    logger: options.logger ?? console,
+    markdown: options.markdown,
+    now: options.now ?? (() => Date.now()),
+    createClient: options.createClient,
+    configured: Boolean(apiUrl && siteClientToken && workspaceSlug),
+  };
+}
+
+/** One-line summary of the resolved env, with the token masked. For `debug` logging. */
+export function describeConfig(config: ResolvedConfig): Record<string, unknown> {
+  const token = config.siteClientToken;
+  return {
+    [ENV_KEYS.apiUrl]: config.apiUrl || 'MISSING',
+    [ENV_KEYS.siteClientToken]: token ? `${token.slice(0, 12)}${'*'.repeat(20)}` : 'MISSING',
+    [ENV_KEYS.workspaceSlug]: config.workspaceSlug || 'MISSING',
+    hasAll: config.configured,
+  };
+}

package/src/embeds.ts

@@ -0,0 +1,137 @@
+/**
+ * Media embeds: the published shapes Marvin hands a site, read tolerantly.
+ *
+ * Marvin resolves a pasted provider link (YouTube, Vimeo, Spotify, …) on the server and publishes
+ * the result next to the entry as `entry.embeds`, keyed by the URL exactly as the author wrote it.
+ * Stored markdown is never rewritten: a site that knows about embeds swaps the link for the
+ * player; an older site just shows the link.
+ *
+ * These types are declared here rather than imported from `@inneropen/marvin-sdk` so the package
+ * works with SDKs that predate embeds. Kind and status are open-ended so a newer server value
+ * doesn't break an older site's types.
+ */
+
+import { asRecord, asString } from './normalize.js';
+
+export type MarvinEmbedKind = 'video' | 'audio' | 'podcast' | 'playlist';
+export type MarvinEmbedStatus = 'ok' | 'link' | 'unavailable';
+export type MarvinEmbedMode = 'direct' | 'click_to_load';
+
+/**
+ * A Marvin-built iframe. Every value comes from Marvin's provider registry. Exactly one of
+ * `aspectRatio` / `height` is set; the other is `null`.
+ */
+export type MarvinEmbedIframe = {
+  src: string;
+  title: string;
+  allow?: string | null;
+  sandbox?: string | null;
+  referrerpolicy?: string | null;
+  /** CSS aspect ratio for video players, e.g. `"16/9"` (`"9/16"` for Shorts); `null` otherwise. */
+  aspectRatio?: string | null;
+  /** Fixed pixel height for audio / podcast / playlist players; `null` for video. */
+  height?: number | null;
+};
+
+/** The plain link every embed falls back to. */
+export type MarvinEmbedLink = {
+  href: string;
+  title: string;
+  providerName: string;
+};
+
+/** Optional fields arrive as `null` rather than omitted; every reader here treats both alike. */
+export type MarvinEmbed = {
+  /** The URL exactly as written in the content. */
+  url: string;
+  canonicalUrl?: string | null;
+  /** Provider key, e.g. `youtube`. */
+  provider: string;
+  /** Display name, e.g. `YouTube`. */
+  providerName: string;
+  kind: MarvinEmbedKind | (string & {});
+  /** `ok` has an iframe; `link` and `unavailable` render as a link card. */
+  status: MarvinEmbedStatus | (string & {});
+  title?: string | null;
+  authorName?: string | null;
+  thumbnailUrl?: string | null;
+  iframe?: MarvinEmbedIframe | null;
+  link: MarvinEmbedLink;
+  /** Marvin-built HTML for the site's embed mode (an iframe, a click-to-load facade, or a link). */
+  html: string;
+};
+
+/** `entry.embeds`: every resolved embed on the entry, keyed by the URL as written. */
+export type MarvinEmbeds = Record<string, MarvinEmbed>;
+
+/**
+ * `site.embeds` (next to `site.seo`): the site's embed privacy mode, consent text (`{provider}`
+ * already substituted per embed in the published `html`) and the frame sources a CSP must allow.
+ */
+export type MarvinSiteEmbeds = {
+  mode: MarvinEmbedMode;
+  consentText: string;
+  /** Origins/hosts the site's embeds may frame — feed these into a `frame-src` directive. */
+  frameSources: string[];
+};
+
+const EMBED_MODES = new Set<string>(['direct', 'click_to_load']);
+
+function readEmbedsField(entry: unknown): unknown {
+  if (!entry || typeof entry !== 'object') return undefined;
+  const direct = (entry as { embeds?: unknown }).embeds;
+  if (direct !== undefined) return direct;
+  // The SDK's `Entry` class keeps the payload private; its `toJSON()` hands it back.
+  const toJSON = (entry as { toJSON?: unknown }).toJSON;
+  if (typeof toJSON === 'function') {
+    return asRecord(toJSON.call(entry)).embeds;
+  }
+  return undefined;
+}
+
+/**
+ * The entry's `embeds` map, or `undefined` when it has none (an older server, or no embeds).
+ * Values that aren't objects carrying a URL are dropped.
+ */
+export function entryEmbeds(entry: unknown): MarvinEmbeds | undefined {
+  const raw = readEmbedsField(entry);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+
+  const embeds: MarvinEmbeds = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      embeds[key] = value as MarvinEmbed;
+    }
+  }
+  return Object.keys(embeds).length > 0 ? embeds : undefined;
+}
+
+/** The embed for `url` as written, tolerating surrounding whitespace. */
+export function findEmbed(
+  embeds: MarvinEmbeds | null | undefined,
+  url: string | null | undefined
+): MarvinEmbed | undefined {
+  if (!embeds || !url) return undefined;
+  const key = url.trim();
+  if (!key) return undefined;
+  return Object.prototype.hasOwnProperty.call(embeds, key) ? embeds[key] : undefined;
+}
+
+/** Normalize `site.embeds`; `undefined` when the server doesn't send it. */
+export function siteEmbeds(raw: unknown): MarvinSiteEmbeds | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const value = asRecord(raw);
+  const mode = asString(value.mode);
+  const frameSources = Array.isArray(value.frameSources)
+    ? value.frameSources.filter(
+        (source): source is string => typeof source === 'string' && source.trim().length > 0
+      )
+    : [];
+
+  return {
+    // Unknown or missing mode → the privacy-preserving default.
+    mode: mode && EMBED_MODES.has(mode) ? (mode as MarvinEmbedMode) : 'click_to_load',
+    consentText: asString(value.consentText) ?? '',
+    frameSources,
+  };
+}

package/src/env.d.ts

@@ -0,0 +1,5 @@
+declare module '*.astro' {
+  type AstroComponentFactory = import('astro/runtime/server/index.js').AstroComponentFactory;
+  const component: AstroComponentFactory;
+  export default component;
+}

package/src/fetch.ts

@@ -0,0 +1,208 @@
+/**
+ * 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.
+ */
+
+import type {
+  Collection,
+  CollectionEntry,
+  Entry,
+  MarvinAsset,
+  MarvinEntry,
+  MarvinResource,
+  MarvinSite,
+  PublishedCollectionSummary,
+  Workspace,
+} from '@inneropen/marvin-sdk';
+import { errorMessage, type MarvinBackend } from './client.js';
+import type { MarvinContentEntry } from './types.js';
+
+/** An entry that carries `data_json` — i.e. schema fields are readable. */
+export type HydratedEntry = MarvinEntry | Entry;
+
+export type MarvinFetcher = ReturnType<typeof createFetcher>;
+
+/**
+ * True for a full entry (`PublishedEntryRead`), false for a list item (`PublishedEntryListItem`).
+ *
+ * `data` doesn't tell them apart: list items carry it too now. What differs is attachments. A full
+ * read has `assets[]` and `resources[]` (placement objects, always present, possibly empty); a list
+ * item has only `assetSlugs` / `resourceSlugs` and a `featuredAsset`. The SDK's `Entry` wrapper
+ * only ever comes from the single-entry read.
+ */
+export function isFullEntry(item: unknown): boolean {
+  if (!item || typeof item !== 'object') return false;
+  if (typeof (item as { field?: unknown }).field === 'function') return true;
+  const raw = item as Record<string, unknown>;
+  if ('assetSlugs' in raw || 'resourceSlugs' in raw) return false;
+  return Array.isArray(raw.assets) || Array.isArray(raw.resources);
+}
+
+/** A failed hydration read is retried this many times in total, backing off from this base. */
+export const HYDRATE_ATTEMPTS = 3;
+export const HYDRATE_BACKOFF_MS = 500;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** `Promise.all(items.map(run))` with at most `limit` calls in flight. Order is preserved. */
+async function mapWithConcurrency<T, R>(
+  items: T[],
+  limit: number,
+  run: (item: T) => Promise<R>
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+
+  async function worker(): Promise<void> {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await run(items[index]);
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(limit, items.length) }, worker);
+  await Promise.all(workers);
+  return results;
+}
+
+export function createFetcher(backend: MarvinBackend) {
+  async function guarded<T>(label: string, empty: T, run: () => Promise<T>): Promise<T> {
+    if (!backend.hasBackend()) return empty;
+    try {
+      return await run();
+    } catch (error) {
+      backend.remember(error);
+      backend.warn(`${label} unavailable: ${errorMessage(error)}`);
+      return empty;
+    }
+  }
+
+  async function entry(slug: string): Promise<Entry | null> {
+    return guarded(`Entry "${slug}"`, null, () => backend.client().entry(slug));
+  }
+
+  /**
+   * One entry read that survives a transient failure.
+   *
+   * `entry()` can't be used here: `guarded` swallows the error and trips the latch, and a
+   * tripped latch turns every remaining item into a silent null. So retry with backoff,
+   * re-opening the latch first in case a sibling read tripped it, and only remember the
+   * failure — and warn — once the attempts are spent.
+   */
+  async function entryForHydration(slug: string): Promise<Entry | null> {
+    if (!backend.hasBackend()) return null;
+
+    let failure: unknown;
+    for (let attempt = 1; attempt <= HYDRATE_ATTEMPTS; attempt++) {
+      if (attempt > 1) {
+        await sleep(HYDRATE_BACKOFF_MS * 2 ** (attempt - 2));
+        if (backend.isLatched()) backend.clearLatch();
+      }
+      try {
+        return await backend.client().entry(slug);
+      } catch (error) {
+        failure = error;
+      }
+    }
+
+    backend.remember(failure);
+    backend.warn(
+      `Entry "${slug}" dropped after ${HYDRATE_ATTEMPTS} attempts: ${errorMessage(failure)}`
+    );
+    return null;
+  }
+
+  /**
+   * Turn list items into full entries.
+   *
+   * The collection endpoint returns `PublishedEntryListItem`: core fields, `metadata_json` and
+   * (on current servers) `data`, but only asset/resource *slugs* — no `assets[]` placements (so
+   * no roles: no `hero-grade` image) and no `resources[]`. `PublishedEntryRead` (the single-entry
+   * endpoint) has all of it. Only items that are already full entries ({@link isFullEntry}) are
+   * passed through; everything else is re-read, even when it carries `data`.
+   *
+   * Reads run at most `config.hydrateConcurrency` at a time. Unbounded, a 280-entry collection
+   * fired 280 requests at once, most of which timed out and were dropped — and the first
+   * timeout latched the backend off for the rest of the build.
+   */
+  async function hydrate(entries: MarvinContentEntry[]): Promise<HydratedEntry[]> {
+    const hydrated = await mapWithConcurrency(
+      entries,
+      backend.config.hydrateConcurrency,
+      async (item) => {
+        if (isFullEntry(item)) return item as HydratedEntry;
+        return entryForHydration(item.slug ?? '');
+      }
+    );
+
+    return hydrated.filter((item): item is HydratedEntry => Boolean(item));
+  }
+
+  return {
+    backend,
+
+    collections(): Promise<PublishedCollectionSummary[]> {
+      return guarded('Collections', [], () => backend.client().collections.list());
+    },
+
+    async collection(slug: string): Promise<Collection | null> {
+      return guarded(`Collection "${slug}"`, null, async () => {
+        const found = await backend.client().collections.get(slug);
+        return Array.isArray(found) ? null : found;
+      });
+    },
+
+    collectionEntries(slug: string): Promise<CollectionEntry[]> {
+      return guarded(`Collection entries "${slug}"`, [], () =>
+        backend.client().collections.entries(slug)
+      );
+    },
+
+    /** Try each collection slug in order; return the first that yields entries. */
+    async collectionEntriesFallback(slugs: string[]): Promise<CollectionEntry[]> {
+      for (const slug of slugs) {
+        const entries = await this.collectionEntries(slug);
+        if (entries.length > 0) return entries;
+      }
+      return [];
+    },
+
+    async hydratedCollectionEntries(slug: string): Promise<HydratedEntry[]> {
+      return hydrate(await this.collectionEntries(slug));
+    },
+
+    async hydratedCollectionEntriesFallback(slugs: string[]): Promise<HydratedEntry[]> {
+      for (const slug of slugs) {
+        const entries = await this.hydratedCollectionEntries(slug);
+        if (entries.length > 0) return entries;
+      }
+      return [];
+    },
+
+    hydrate,
+    entry,
+
+    site(): Promise<MarvinSite | null> {
+      return guarded('Site', null, () => backend.client().getSite());
+    },
+
+    workspace(): Promise<Workspace | null> {
+      return guarded('Workspace', null, () => backend.client().getWorkspace());
+    },
+
+    assets(type?: string): Promise<MarvinAsset[]> {
+      return guarded('Assets', [], () => backend.client().assets.list({ type }));
+    },
+
+    asset(slugOrId: string): Promise<MarvinAsset | null> {
+      return guarded(`Asset "${slugOrId}"`, null, () => backend.client().assets.get(slugOrId));
+    },
+
+    resources(resourceType?: string): Promise<MarvinResource[]> {
+      return guarded('Resources', [], () => backend.client().resources.list({ resourceType }));
+    },
+  };
+}