@misofm/sdk 0.3.0 → 0.5.0

package/src/read/catalog.ts

@@ -10,13 +10,25 @@
 // credits → recordings); the same work happens once here, inside one datacenter,
 // and every subsequent visitor is served from cache.
 
-import { getDrop, getCurrentDrop, type DropView } from "../drop.ts";
-import { getReleaseCover, type ReleaseCoverView, type CoverImageRef } from "../cover.ts";
-import { getReleaseCredits, getRecordingCredits, type CreditView } from "../credits.ts";
-import { getReleaseById, isNotFound } from "@misonetwork/sdk";
+import { getCurrentDrops, getDrop, type DropView } from "../drop.ts";
+import {
+  getReleaseCoversByIds,
+  parseReleaseCoverContent,
+  releaseCoverFieldId,
+  type ReleaseCoverView,
+  type CoverImageRef,
+} from "../cover.ts";
+import {
+  getReleaseCreditsByIds,
+  parseReleaseCreditsContent,
+  releaseCreditsFieldId,
+  type CreditView,
+} from "../credits.ts";
+import { getTrackCreditsByRecordingIds } from "../catalog.ts";
+import { getReleaseById, getReleasesByIds, isNotFound } from "@misonetwork/sdk";
 import type { Release } from "@misonetwork/sdk";
 import type { MisoClient } from "./client.ts";
-import { getRecordingTitles } from "./works.ts";
+import { getRecordingTitles, parseReleaseObject } from "./works.ts";
 import { gte, int, ms, msOrNull, u64, u64OrNull } from "./internal/scalars.ts";
 import { quiltPatchId, u256ToB64Url } from "./internal/walrus.ts";
 import type {
@@ -41,15 +53,30 @@ import type {
 /** Aggregator URL for a cover image ref, whichever Walrus variant it is. */
 function imageUrl(aggregator: string, ref: CoverImageRef): string {
   const base = aggregator.replace(/\/$/, "");
-  if (ref.kind === "blob") return `${base}/v1/blobs/${u256ToB64Url(ref.blobId)}`;
-  const patch = quiltPatchId(ref.quiltId, ref.version, ref.startIndex, ref.endIndex);
+  if (ref.kind === "blob")
+    return `${base}/v1/blobs/${u256ToB64Url(ref.blobId)}`;
+  const patch = quiltPatchId(
+    ref.quiltId,
+    ref.version,
+    ref.startIndex,
+    ref.endIndex,
+  );
   return `${base}/v1/blobs/by-quilt-patch-id/${patch}`;
 }
 
-function toCover(aggregator: string, view: ReleaseCoverView | null): Cover | null {
+function toCover(
+  aggregator: string,
+  view: ReleaseCoverView | null,
+): Cover | null {
   if (!view) return null;
-  const image = (ref: CoverImageRef): CoverImage => ({ kind: ref.kind, url: imageUrl(aggregator, ref) });
-  return { still: image(view.still), animated: view.animated ? image(view.animated) : null };
+  const image = (ref: CoverImageRef): CoverImage => ({
+    kind: ref.kind,
+    url: imageUrl(aggregator, ref),
+  });
+  return {
+    still: image(view.still),
+    animated: view.animated ? image(view.animated) : null,
+  };
 }
 
 // ── Currency ─────────────────────────────────────────────────────────────────
@@ -61,9 +88,14 @@ function toCover(aggregator: string, view: ReleaseCoverView | null): Cover | nul
  */
 export function currencyInfo(type: string | null): Currency {
   if (!type) return { type: null, symbol: "COIN", decimals: 9 };
-  if (/::fakeusd::/i.test(type)) return { type, symbol: "FAKEUSD", decimals: 6 };
+  if (/::fakeusd::/i.test(type))
+    return { type, symbol: "FAKEUSD", decimals: 6 };
   if (type === "0x2::sui::SUI") return { type, symbol: "SUI", decimals: 9 };
-  return { type, symbol: (type.split("::").pop() ?? "COIN").toUpperCase(), decimals: 9 };
+  return {
+    type,
+    symbol: (type.split("::").pop() ?? "COIN").toUpperCase(),
+    decimals: 9,
+  };
 }
 
 // ── Projections ──────────────────────────────────────────────────────────────
@@ -71,7 +103,10 @@ export function currencyInfo(type: string | null): Currency {
 function toPressingView(drop: DropView): PressingView {
   const quantitySold = u64(drop.quantitySold);
   const maxSupply = u64OrNull(drop.maxSupply);
-  const price: Price = { kind: drop.price.kind, amount: u64(drop.price.amount) };
+  const price: Price = {
+    kind: drop.price.kind,
+    amount: u64(drop.price.amount),
+  };
   return {
     id: drop.id,
     releaseId: drop.releaseId,
@@ -87,29 +122,40 @@ function toPressingView(drop: DropView): PressingView {
 }
 
 function toWorkState(state: Release["state"]): WorkState {
-  return state.type === "Published" ? { type: "Published", timestampMs: state.timestampMs } : { type: "Initialized" };
+  return state.type === "Published"
+    ? { type: "Published", timestampMs: state.timestampMs }
+    : { type: "Initialized" };
 }
 
 function toCredits(credits: CreditView[] | null): Credit[] {
-  return (credits ?? []).map((c) => ({ partyId: c.partyId, displayName: c.displayName, roles: [...c.roles] }));
+  return (credits ?? []).map((c) => ({
+    partyId: c.partyId,
+    displayName: c.displayName,
+    roles: [...c.roles],
+  }));
 }
 
 /** The release's PRIMARY credits, in chain order — a release's artist line. */
 export function primaryArtistNames(credits: Credit[]): string[] {
-  return credits.filter((c) => c.roles.includes("Primary")).map((c) => c.displayName);
+  return credits
+    .filter((c) => c.roles.includes("Primary"))
+    .map((c) => c.displayName);
 }
 
 /**
  * Number the protocol's flat tracklist. Display grouping such as discs belongs
  * to metadata extensions and can be layered onto this projection later.
  */
-function toTracks(release: Release, titles: Record<string, string>): TrackView[] {
+function toTracks(
+  release: Release,
+  titles: Record<string, string>,
+): TrackView[] {
   return release.tracks.map((track, index) => ({
-      no: `${index + 1}`,
-      title: titles[track.recordingId] ?? "Untitled",
-      recordingId: track.recordingId,
-      splitBps: int(track.splitBps.value),
-      disc: 1,
+    no: `${index + 1}`,
+    title: titles[track.recordingId] ?? "Untitled",
+    recordingId: track.recordingId,
+    splitBps: int(track.splitBps.value),
+    disc: 1,
   }));
 }
 
@@ -124,13 +170,105 @@ function toTracks(release: Release, titles: Record<string, string>): TrackView[]
  * simply misses them rather than failing. Ported verbatim from miso-app's
  * `lib/pressing.ts:readReleaseCover`.
  */
-export async function readReleaseCover(client: MisoClient, releaseId: string): Promise<Cover | null> {
+export async function readReleaseCover(
+  client: MisoClient,
+  releaseId: string,
+): Promise<Cover | null> {
   const { releaseCoverArt, legacyReleaseCoverArt } = client.config.protocol;
-  for (const pkg of [releaseCoverArt, ...legacyReleaseCoverArt]) {
-    const cover = await getReleaseCover(client.protocol, releaseId, pkg).catch(() => null);
-    if (cover) return toCover(client.config.walrusAggregatorUrl, cover);
+  const covers = await getReleaseCoversByIds(
+    client.protocol,
+    [releaseId],
+    [releaseCoverArt, ...legacyReleaseCoverArt],
+  ).catch(() => ({}) as Partial<Record<string, ReleaseCoverView>>);
+  return toCover(client.config.walrusAggregatorUrl, covers[releaseId] ?? null);
+}
+
+export type ReleaseResourceInclude = "cover" | "credits";
+
+export interface ReleaseResources {
+  release: Release;
+  cover?: Cover | null;
+  credits?: Credit[];
+}
+
+/**
+ * A release plus selected derived resources in one heterogeneous Core batch.
+ * Every extension id is deterministic, so separate object calls only add
+ * network round trips without discovering anything new.
+ */
+export async function getReleaseResources(
+  client: MisoClient,
+  releaseId: string,
+  include: readonly ReleaseResourceInclude[] = [],
+): Promise<ReleaseResources> {
+  const wantsCover = include.includes("cover");
+  const wantsCredits = include.includes("credits");
+  const coverPackages = wantsCover
+    ? [
+        client.config.protocol.releaseCoverArt,
+        ...client.config.protocol.legacyReleaseCoverArt,
+      ]
+    : [];
+  const coverFieldIds = coverPackages.map((packageId) =>
+    releaseCoverFieldId(releaseId, packageId),
+  );
+  const creditsFieldId = wantsCredits
+    ? releaseCreditsFieldId(releaseId, client.config.protocol.releaseCredits)
+    : null;
+  const objectIds = [
+    releaseId,
+    ...coverFieldIds,
+    ...(creditsFieldId ? [creditsFieldId] : []),
+  ];
+  const { objects } = await client.protocol.core.getObjects({
+    objectIds,
+    include: { content: true, json: true },
+  });
+  const releaseObject = objects[0];
+  if (!releaseObject) throw new Error(`Release not found: ${releaseId}`);
+  if (releaseObject instanceof Error) throw releaseObject;
+  if (!releaseObject.content)
+    throw new Error(`Release has no content: ${releaseId}`);
+  const release = parseReleaseObject(
+    releaseObject.objectId,
+    releaseObject.content,
+    releaseObject.json,
+  );
+
+  let cover: Cover | null | undefined;
+  if (wantsCover) {
+    let view: ReleaseCoverView | null = null;
+    for (let index = 0; index < coverFieldIds.length; index += 1) {
+      const object = objects[index + 1];
+      if (!object || object instanceof Error || !object.content) continue;
+      try {
+        view = parseReleaseCoverContent(object.content);
+      } catch {
+        view = null;
+      }
+      if (view) break;
+    }
+    cover = toCover(client.config.walrusAggregatorUrl, view);
   }
-  return null;
+
+  let credits: Credit[] | undefined;
+  if (wantsCredits) {
+    const object = objects[1 + coverFieldIds.length];
+    let view: CreditView[] = [];
+    if (object && !(object instanceof Error) && object.content) {
+      try {
+        view = parseReleaseCreditsContent(object.content);
+      } catch {
+        view = [];
+      }
+    }
+    credits = toCredits(view);
+  }
+  return {
+    release,
+    ...(wantsCover ? { cover: cover ?? null } : {}),
+    ...(wantsCredits ? { credits: credits ?? [] } : {}),
+  };
 }
 
 // ── Release ──────────────────────────────────────────────────────────────────
@@ -144,64 +282,108 @@ export async function readReleaseCover(client: MisoClient, releaseId: string): P
  * split is inherited from `lib/drops.ts` and is what keeps a half-configured
  * release renderable.
  */
-export async function getReleaseDetail(client: MisoClient, releaseId: string): Promise<ReleaseDetail> {
-  const { releaseCredits } = client.config.protocol;
+export type ReleaseInclude = "trackCredits";
 
-  const [release, cover, credits] = await Promise.all([
-    getReleaseById(client.protocol, releaseId),
-    readReleaseCover(client, releaseId),
-    getReleaseCredits(client.protocol, releaseId, releaseCredits).catch(() => null),
-  ]);
+export interface GetReleaseOptions {
+  include?: readonly ReleaseInclude[];
+}
+
+export async function getReleaseDetail(
+  client: MisoClient,
+  releaseId: string,
+  options: GetReleaseOptions = {},
+): Promise<ReleaseDetail> {
+  const { release, cover, credits } = await getReleaseResources(
+    client,
+    releaseId,
+    ["cover", "credits"],
+  );
 
   const recordingIds = release.tracks.map((track) => track.recordingId);
-  const titles = await getRecordingTitles(client.protocol, client.graphql, recordingIds, client.config.protocol.miso);
+  const [titles, trackCredits] = await Promise.all([
+    getRecordingTitles(
+      client.protocol,
+      client.graphql,
+      recordingIds,
+      client.config.protocol.miso,
+    ),
+    options.include?.includes("trackCredits")
+      ? getTrackCreditsForRecordingIds(client, recordingIds)
+      : Promise.resolve(undefined),
+  ]);
 
-  const creditViews = toCredits(credits);
+  const creditViews = credits ?? [];
   return {
     id: release.id,
     title: release.title,
     subtitle: null,
     state: toWorkState(release.state),
-    publishedAtMs: release.state.type === "Published" ? release.state.timestampMs : null,
-    cover,
+    publishedAtMs:
+      release.state.type === "Published" ? release.state.timestampMs : null,
+    cover: cover ?? null,
     credits: creditViews,
     primaryArtists: primaryArtistNames(creditViews),
     discCount: release.tracks.length > 0 ? 1 : 0,
     tracks: toTracks(release, titles),
+    ...(trackCredits !== undefined ? { trackCredits } : {}),
   };
 }
 
+async function getTrackCreditsForRecordingIds(
+  client: MisoClient,
+  recordingIds: readonly string[],
+): Promise<Record<string, TrackCredits>> {
+  const { compositionCredits, recordingCredits, miso } = client.config.protocol;
+  const tracks = await getTrackCreditsByRecordingIds(
+    client.protocol,
+    client.graphql,
+    recordingIds,
+    {
+      misoPackageId: miso,
+      compositionCreditsPackageId: compositionCredits,
+      recordingCreditsPackageId: recordingCredits,
+    },
+  );
+  return Object.fromEntries(
+    Object.entries(tracks).map(([id, track]) => [
+      id,
+      {
+        compositionCredits: toCredits(track.compositionCredits),
+        recordingCredits: {
+          credits: toCredits(track.recordingCredits.credits),
+          primaryArtistIds: [...track.recordingCredits.primaryArtistIds],
+          featuredArtistIds: [...track.recordingCredits.featuredArtistIds],
+        },
+      } satisfies TrackCredits,
+    ]),
+  );
+}
+
 /**
  * Per-track credits for a release, keyed by recording id. A track with no credits
  * set maps to an empty entry rather than being absent, so a caller can tell
  * "nothing credited" from "no such track".
  */
-export async function getTrackCredits(client: MisoClient, releaseId: string): Promise<Record<string, TrackCredits>> {
-  const { recordingCredits } = client.config.protocol;
+export async function getTrackCredits(
+  client: MisoClient,
+  releaseId: string,
+): Promise<Record<string, TrackCredits>> {
   const release = await getReleaseById(client.protocol, releaseId);
   const recordingIds = release.tracks.map((track) => track.recordingId);
-
-  const entries = await Promise.all(
-    recordingIds.map(async (id) => {
-      const view = await getRecordingCredits(client.protocol, id, recordingCredits).catch(() => null);
-      const credits: TrackCredits = {
-        credits: toCredits(view?.credits ?? null),
-        primaryArtistIds: view?.primaryArtistIds ?? [],
-        featuredArtistIds: view?.featuredArtistIds ?? [],
-      };
-      return [id, credits] as const;
-    }),
-  );
-  return Object.fromEntries(entries);
+  return getTrackCreditsForRecordingIds(client, recordingIds);
 }
 
 // ── Pressing ─────────────────────────────────────────────────────────────────
 
 /** Everything the pressing buy page renders. `null` when no such pressing exists. */
-export async function getPressingDetail(client: MisoClient, pressingId: string): Promise<PressingDetail | null> {
+export async function getPressingDetail(
+  client: MisoClient,
+  pressingId: string,
+  options: GetReleaseOptions = {},
+): Promise<PressingDetail | null> {
   const pressing = await getDrop(client.protocol, pressingId);
   if (!pressing) return null;
-  const release = await getReleaseDetail(client, pressing.releaseId);
+  const release = await getReleaseDetail(client, pressing.releaseId, options);
   return { pressing: toPressingView(pressing), release };
 }
 
@@ -210,17 +392,18 @@ export async function getPressingDetail(client: MisoClient, pressingId: string):
  * object really is a `Drop` before spending reads on it — a release id or a
  * record id pasted by mistake must come back as `null`, not as a half-built card.
  */
-export async function getDropPreview(client: MisoClient, dropId: string): Promise<DropPreview | null> {
-  const { object } = await client.protocol.core.getObject({ objectId: dropId, include: { content: true } }).catch(() => ({ object: null }));
-  if (!object || !/::drop::Drop</.test(object.type ?? "")) return null;
-
+export async function getDropPreview(
+  client: MisoClient,
+  dropId: string,
+): Promise<DropPreview | null> {
   const pressing = await getDrop(client.protocol, dropId);
   if (!pressing?.currencyType) return null;
 
-  const [release, cover] = await Promise.all([
-    getReleaseById(client.protocol, pressing.releaseId),
-    readReleaseCover(client, pressing.releaseId),
-  ]);
+  const { release, cover } = await getReleaseResources(
+    client,
+    pressing.releaseId,
+    ["cover"],
+  );
 
   return {
     pressingId: dropId,
@@ -243,31 +426,51 @@ export async function getDropPreview(client: MisoClient, dropId: string): Promis
  * Following the release's `CurrentDropKey` pointer keeps this list pointing at the
  * live edition without anyone touching the config.
  */
-export async function getDiscoverShelf(client: MisoClient): Promise<DiscoverItem[]> {
-  const items = await Promise.all(client.config.discoverReleaseIds.map((id) => resolveDiscoverItem(client, id)));
-  return items.filter((d): d is DiscoverItem => d !== null);
-}
-
-async function resolveDiscoverItem(client: MisoClient, releaseId: string): Promise<DiscoverItem | null> {
-  const drop = await getCurrentDrop(client.protocol, {
-    releaseId,
-    misoDropPackageId: client.config.protocol.drop,
-  });
-  if (!drop) return null;
-
-  const [release, cover, credits] = await Promise.all([
-    getReleaseById(client.protocol, releaseId),
-    readReleaseCover(client, releaseId),
-    getReleaseCredits(client.protocol, releaseId, client.config.protocol.releaseCredits).catch(() => null),
+export async function getDiscoverShelf(
+  client: MisoClient,
+): Promise<DiscoverItem[]> {
+  const configuredIds = [...client.config.discoverReleaseIds];
+  const drops = await getCurrentDrops(
+    client.protocol,
+    configuredIds,
+    client.config.protocol.drop,
+  );
+  const releaseIds = configuredIds.filter((releaseId) => drops[releaseId]);
+  if (releaseIds.length === 0) return [];
+
+  const [releases, coverViews, credits] = await Promise.all([
+    getReleasesByIds(client.protocol, releaseIds),
+    getReleaseCoversByIds(client.protocol, releaseIds, [
+      client.config.protocol.releaseCoverArt,
+      ...client.config.protocol.legacyReleaseCoverArt,
+    ]).catch(() => ({}) as Partial<Record<string, ReleaseCoverView>>),
+    getReleaseCreditsByIds(
+      client.protocol,
+      releaseIds,
+      client.config.protocol.releaseCredits,
+    ).catch(() => ({}) as Partial<Record<string, CreditView[]>>),
   ]);
 
-  return {
-    pressing: toPressingView(drop),
-    releaseId,
-    title: release.title,
-    artist: primaryArtistNames(toCredits(credits)).join(", "),
-    coverUrl: cover?.still.url ?? null,
-  };
+  return releaseIds.flatMap((releaseId) => {
+    const drop = drops[releaseId];
+    const release = releases[releaseId];
+    if (!drop || !release) return [];
+    const cover = toCover(
+      client.config.walrusAggregatorUrl,
+      coverViews[releaseId] ?? null,
+    );
+    return [
+      {
+        pressing: toPressingView(drop),
+        releaseId,
+        title: release.title,
+        artist: primaryArtistNames(toCredits(credits[releaseId] ?? null)).join(
+          ", ",
+        ),
+        coverUrl: cover?.still.url ?? null,
+      },
+    ];
+  });
 }
 
 // ── Record → release ─────────────────────────────────────────────────────────
@@ -280,12 +483,44 @@ async function resolveDiscoverItem(client: MisoClient, releaseId: string): Promi
  * This answer is IMMUTABLE for the life of the record, which is what lets the
  * endpoint in front of it cache for a year.
  */
-export async function getRecordAlbum(client: MisoClient, recordId: string): Promise<RecordAlbum | null> {
+export type RecordAlbumInclude = "release" | "trackCredits";
+
+export interface GetRecordAlbumOptions {
+  include?: readonly RecordAlbumInclude[];
+}
+
+export async function getRecordAlbum(
+  client: MisoClient,
+  recordId: string,
+  options: GetRecordAlbumOptions = {},
+): Promise<RecordAlbum | null> {
   try {
-    const { object } = await client.protocol.core.getObject({ objectId: recordId, include: { json: true } });
+    const { object } = await client.protocol.core.getObject({
+      objectId: recordId,
+      include: { json: true },
+    });
     const json = (object?.json ?? {}) as Record<string, unknown>;
     const raw = json.release_id ?? json.releaseId;
-    return { recordId, releaseId: typeof raw === "string" && raw ? raw : null };
+    const releaseId = typeof raw === "string" && raw ? raw : null;
+    const includeRelease =
+      options.include?.some(
+        (part) => part === "release" || part === "trackCredits",
+      ) ?? false;
+    const release =
+      includeRelease && releaseId
+        ? await getReleaseDetail(client, releaseId, {
+            include: options.include?.includes("trackCredits")
+              ? ["trackCredits"]
+              : [],
+          })
+        : includeRelease
+          ? null
+          : undefined;
+    return {
+      recordId,
+      releaseId,
+      ...(includeRelease ? { release } : {}),
+    };
   } catch (e) {
     if (isNotFound(e)) return null;
     throw e;

package/src/read/index.ts

@@ -18,7 +18,14 @@ export { createMisoClient } from "./client.ts";
 export type { MisoClient, CreateMisoClientOptions } from "./client.ts";
 
 export { misoConfig, networkFrom } from "./config.ts";
-export type { MisoConfig, MisoConfigOverrides, MoneyIds, Network, PartyIds, ProtocolIds } from "./config.ts";
+export type {
+  MisoConfig,
+  MisoConfigOverrides,
+  MoneyIds,
+  Network,
+  PartyIds,
+  ProtocolIds,
+} from "./config.ts";
 
 export {
   currencyInfo,
@@ -27,12 +34,26 @@ export {
   getPressingDetail,
   getRecordAlbum,
   getReleaseDetail,
+  getReleaseResources,
   getTrackCredits,
   primaryArtistNames,
   readReleaseCover,
 } from "./catalog.ts";
+export type {
+  GetRecordAlbumOptions,
+  GetReleaseOptions,
+  RecordAlbumInclude,
+  ReleaseInclude,
+  ReleaseResourceInclude,
+} from "./catalog.ts";
+export type { ReleaseResources } from "./catalog.ts";
 
-export { getArtistProfile, getFeaturedRelease, getPartySummaries, partyAvatarUrl } from "./artist.ts";
+export {
+  getArtistProfile,
+  getFeaturedRelease,
+  getPartySummaries,
+  partyAvatarUrl,
+} from "./artist.ts";
 export type { ArtistInclude, GetArtistOptions } from "./artist.ts";
 
 export { resolveGenreNames } from "./genres.ts";

package/src/read/types.ts

@@ -21,7 +21,9 @@
 // ── Catalog ──────────────────────────────────────────────────────────────────
 
 /** Lifecycle state shared by compositions, recordings, and releases. */
-export type WorkState = { type: "Initialized" } | { type: "Published"; timestampMs: number };
+export type WorkState =
+  | { type: "Initialized" }
+  | { type: "Published"; timestampMs: number };
 
 /** A cover image's location on Walrus, plus the URL to fetch it from. */
 export interface CoverImage {
@@ -49,12 +51,18 @@ export interface Credit {
  * party, not roles the party performed — a producer can be a featured artist. UI
  * badges the names by intersecting the two.
  */
-export interface TrackCredits {
+export interface RecordingCredits {
   credits: Credit[];
   primaryArtistIds: string[];
   featuredArtistIds: string[];
 }
 
+/** Composition writing credits plus recording performance/production credits. */
+export interface TrackCredits {
+  compositionCredits: Credit[];
+  recordingCredits: RecordingCredits;
+}
+
 /** One track as a tracklist renders it. */
 export interface TrackView {
   /** Display number — `"1"`, or `"1.2"` (disc.track) on a multi-disc set. */
@@ -81,6 +89,8 @@ export interface ReleaseDetail {
   primaryArtists: string[];
   discCount: number;
   tracks: TrackView[];
+  /** Present only when requested via `include`, keyed by recording id. */
+  trackCredits?: Record<string, TrackCredits>;
 }
 
 /** Pricing policy: pay exactly `amount` (fixed), or at least `amount` (floor). */
@@ -137,6 +147,8 @@ export interface RecordAlbum {
   recordId: string;
   /** Null when the record object carries no release id. */
   releaseId: string | null;
+  /** Present only when requested via `include`; null when no release is linked. */
+  release?: ReleaseDetail | null;
 }
 
 /** The confirmation preview shown when an owner pastes a pressing id to pin. */
@@ -229,6 +241,8 @@ export interface ArtistProfile {
   /** Present only when requested via `include` — the owner-editor fields. */
   roles?: string[];
   tags?: string[];
+  /** Present only when requested via `include`; null means nothing is pinned. */
+  featured?: FeaturedRelease | null;
   /** Public avatar URL (miso-api R2 lane; may 404 when unset). */
   avatarUrl: string;
 }