@misofm/sdk 0.2.1 → 0.4.0

package/src/read/catalog.ts

@@ -0,0 +1,293 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Catalog reads: pressings, releases, covers, credits, tracklists, and the
+// Discover shelf. Everything here is PUBLIC — no address is involved and no two
+// callers get different answers, which is what makes this layer edge-cacheable.
+//
+// The composition of these reads is the point. A pressing page used to cost the
+// browser five sequential round-trips to the chain (drop → release → cover →
+// 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 type { Release } from "@misonetwork/sdk";
+import type { MisoClient } from "./client.ts";
+import { getRecordingTitles } from "./works.ts";
+import { gte, int, ms, msOrNull, u64, u64OrNull } from "./internal/scalars.ts";
+import { quiltPatchId, u256ToB64Url } from "./internal/walrus.ts";
+import type {
+  Cover,
+  CoverImage,
+  Credit,
+  Currency,
+  DiscoverItem,
+  DropPreview,
+  PressingDetail,
+  PressingView,
+  Price,
+  RecordAlbum,
+  ReleaseDetail,
+  TrackCredits,
+  TrackView,
+  WorkState,
+} from "./types.ts";
+
+// ── Walrus URLs ──────────────────────────────────────────────────────────────
+
+/** 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);
+  return `${base}/v1/blobs/by-quilt-patch-id/${patch}`;
+}
+
+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 };
+}
+
+// ── Currency ─────────────────────────────────────────────────────────────────
+
+/**
+ * Symbol + decimals for a coin type. FakeUsd (the testnet dollar) is 6dp; SUI is
+ * 9dp; anything else falls back to its module name at 9dp, which is the Sui
+ * default and the honest guess for a coin we have no table entry for.
+ */
+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 (type === "0x2::sui::SUI") return { type, symbol: "SUI", decimals: 9 };
+  return { type, symbol: (type.split("::").pop() ?? "COIN").toUpperCase(), decimals: 9 };
+}
+
+// ── Projections ──────────────────────────────────────────────────────────────
+
+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) };
+  return {
+    id: drop.id,
+    releaseId: drop.releaseId,
+    edition: int(drop.edition),
+    price,
+    currency: currencyInfo(drop.currencyType),
+    quantitySold,
+    maxSupply,
+    startTimestampMs: ms(drop.startTimestampMs),
+    endTimestampMs: msOrNull(drop.endTimestampMs),
+    soldOut: maxSupply !== null && gte(quantitySold, maxSupply),
+  };
+}
+
+function toWorkState(state: Release["state"]): WorkState {
+  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] }));
+}
+
+/** 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);
+}
+
+/**
+ * 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[] {
+  return release.tracks.map((track, index) => ({
+      no: `${index + 1}`,
+      title: titles[track.recordingId] ?? "Untitled",
+      recordingId: track.recordingId,
+      splitBps: int(track.splitBps.value),
+      disc: 1,
+  }));
+}
+
+// ── Cover ────────────────────────────────────────────────────────────────────
+
+/**
+ * A release's cover, trying the current `release_cover_art` package and then each
+ * legacy one in turn.
+ *
+ * Covers set before the cover_art package split live under a different
+ * `CoverArtKey` TYPE (different package address), so a current-package read
+ * 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> {
+  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);
+  }
+  return null;
+}
+
+// ── Release ──────────────────────────────────────────────────────────────────
+
+/**
+ * A release with its cover, credits, and resolved tracklist.
+ *
+ * Identity (the release object) is HARD — a failure here is a failed read.
+ * Decoration (cover, credits) is SOFT: a release with no cover extension set is a
+ * normal state, not a broken page, so those reads swallow their errors. That
+ * 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;
+
+  const [release, cover, credits] = await Promise.all([
+    getReleaseById(client.protocol, releaseId),
+    readReleaseCover(client, releaseId),
+    getReleaseCredits(client.protocol, releaseId, releaseCredits).catch(() => null),
+  ]);
+
+  const recordingIds = release.tracks.map((track) => track.recordingId);
+  const titles = await getRecordingTitles(client.protocol, client.graphql, recordingIds, client.config.protocol.miso);
+
+  const creditViews = toCredits(credits);
+  return {
+    id: release.id,
+    title: release.title,
+    subtitle: null,
+    state: toWorkState(release.state),
+    publishedAtMs: release.state.type === "Published" ? release.state.timestampMs : null,
+    cover,
+    credits: creditViews,
+    primaryArtists: primaryArtistNames(creditViews),
+    discCount: release.tracks.length > 0 ? 1 : 0,
+    tracks: toTracks(release, titles),
+  };
+}
+
+/**
+ * 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;
+  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);
+}
+
+// ── Pressing ─────────────────────────────────────────────────────────────────
+
+/** Everything the pressing buy page renders. `null` when no such pressing exists. */
+export async function getPressingDetail(client: MisoClient, pressingId: string): Promise<PressingDetail | null> {
+  const pressing = await getDrop(client.protocol, pressingId);
+  if (!pressing) return null;
+  const release = await getReleaseDetail(client, pressing.releaseId);
+  return { pressing: toPressingView(pressing), release };
+}
+
+/**
+ * The confirmation preview behind "paste a pressing id to pin it". Verifies the
+ * 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;
+
+  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),
+  ]);
+
+  return {
+    pressingId: dropId,
+    currency: currencyInfo(pressing.currencyType),
+    title: release.title,
+    subtitle: null,
+    coverUrl: cover?.still.url ?? null,
+    price: { kind: pressing.price.kind, amount: u64(pressing.price.amount) },
+    trackCount: release.tracks.length,
+  };
+}
+
+// ── Discover ─────────────────────────────────────────────────────────────────
+
+/**
+ * The records currently on sale.
+ *
+ * Configured by RELEASE id, never by drop id: a release id is permanent, while a
+ * drop is superseded (and the old `Drop` destroyed) whenever a new edition opens.
+ * 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),
+  ]);
+
+  return {
+    pressing: toPressingView(drop),
+    releaseId,
+    title: release.title,
+    artist: primaryArtistNames(toCredits(credits)).join(", "),
+    coverUrl: cover?.still.url ?? null,
+  };
+}
+
+// ── Record → release ─────────────────────────────────────────────────────────
+
+/**
+ * A record's parent release. Both live `Record` struct layouts expose it — card
+ * checkout's `{ release_id, number }` and the SDK view's
+ * `{ release_id, edition, variant }` — so we probe both spellings.
+ *
+ * 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> {
+  try {
+    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 };
+  } catch (e) {
+    if (isNotFound(e)) return null;
+    throw e;
+  }
+}

package/src/read/client.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The one client every read in this SDK goes through.
+//
+// Two transports, because Sui splits the job:
+//   core (gRPC)  the data plane — objects by id, objects by owner, balances,
+//                transactions. Everything cheap and current.
+//   graphql      the two questions gRPC cannot answer: "which object has type X"
+//                (share type → work id, for the studio catalog and the receipt's
+//                royalty hop) and "what did this pruned transaction do".
+//
+// It also carries the resolved `MisoConfig`, so a read function takes ONE argument
+// and never has a package id threaded through its signature.
+//
+// The casts below are load-bearing and deliberate: @misonetwork/miso-protocol and
+// @misonetwork/miso-party each type against their own installed copy of
+// @mysten/sui. Those copies are structurally identical but nominally distinct
+// (private class fields), so TypeScript refuses the assignment even though the
+// runtime object is the same one. miso-app solved this with a cast at each call
+// site (`lib/pressing.ts:25`, `lib/party.ts:55`); here it happens ONCE, and
+// nothing downstream of this file casts anything.
+
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { SuiGraphQLClient } from "@mysten/sui/graphql";
+import type { SuiClientRegistration } from "@mysten/sui/client";
+import { party, type PartyClient } from "@misonetwork/miso-party/client";
+import { misoConfig, networkFrom, type MisoConfig, type MisoConfigOverrides, type Network } from "./config.ts";
+
+/**
+ * The structural slice of a Sui client the protocol SDK's read helpers want. They
+ * declare `ClientWithCoreApi` against their own @mysten/sui; this alias names the
+ * same shape from our side so the one cast in `createMisoClient` is explicit
+ * rather than an `any` smeared across the codebase.
+ */
+export type ProtocolClient = Parameters<typeof import("@misonetwork/sdk").getReleaseById>[0];
+
+/** A GraphQL client in the shape the protocol SDK's type-discovery queries want. */
+export type ProtocolGraphQLClient = SuiGraphQLClient;
+
+export interface MisoClient {
+  config: MisoConfig;
+  /** gRPC data plane, extended with the party read API (`sui.party.getPartyById(…)`). */
+  sui: SuiGrpcClient & { party: PartyClient };
+  /** The same client, typed for the protocol SDK's read helpers. */
+  protocol: ProtocolClient;
+  /** GraphQL RPC, typed for the protocol SDK's type-discovery queries. */
+  graphql: ProtocolGraphQLClient;
+  /** The raw GraphQL client, for this SDK's own queries (the pruned-transaction read). */
+  graphqlRaw: SuiGraphQLClient;
+}
+
+export interface CreateMisoClientOptions extends MisoConfigOverrides {
+  /** "testnet" | "mainnet". A bare string (e.g. a Worker's `NETWORK` var) is accepted. */
+  network?: Network | string;
+}
+
+/**
+ * Build the client for a network. Endpoint overrides let a deployment point at a
+ * private fullnode or an indexer without forking the config.
+ */
+export function createMisoClient(options: CreateMisoClientOptions = {}): MisoClient {
+  const { network, ...overrides } = options;
+  const config = misoConfig(networkFrom(network), overrides);
+
+  const grpc = new SuiGrpcClient({ baseUrl: config.grpcUrl, network: config.network });
+  const graphqlRaw = new SuiGraphQLClient({ url: config.graphqlUrl, network: config.network });
+
+  const registration = party(config.party) as unknown as SuiClientRegistration<typeof grpc, "party", PartyClient>;
+  const sui = grpc.$extend(registration);
+
+  return {
+    config,
+    sui,
+    protocol: sui as unknown as ProtocolClient,
+    graphql: graphqlRaw as unknown as ProtocolGraphQLClient,
+    graphqlRaw,
+  };
+}

package/src/read/config.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Per-network on-chain identity: which packages the reads address, which objects
+// they read, and which endpoints they read through. Every id that used to be a
+// hard-coded constant inside miso-app (`lib/party.ts`, `lib/release.ts`,
+// `lib/money.ts`, `lib/drops.ts`) lives here instead, so a redeploy is a change
+// in ONE file that every surface picks up.
+//
+// Testnet values are the deployed ones (verified against chain 2026-08-09).
+// Mainnet is deliberately EMPTY: `misoConfig("mainnet")` throws rather than
+// silently reading testnet ids on a mainnet deployment.
+
+export type Network = "testnet" | "mainnet";
+
+/** Anything but "mainnet" — including unset — is testnet. Mirrors miso-api's `networkFromEnv`. */
+export function networkFrom(value: string | undefined): Network {
+  return value === "mainnet" ? "mainnet" : "testnet";
+}
+
+/** Package ids for the miso protocol core and the extensions the read layer touches. */
+export interface ProtocolIds {
+  /** `miso` core — Composition / Recording / Release, and the origin of every derived admin cap. */
+  miso: string;
+  /** `miso_drop` — `drop::buy` and the `Drop` objects the pressing pages read. */
+  drop: string;
+  /** `miso_record` shared `Settings` object — the mint witness authorizer. */
+  recordSettings: string;
+  /** `release_cover_art` — the release cover extension currently written to. */
+  releaseCoverArt: string;
+  /**
+   * Cover-art packages from before the `cover_art` package split. A cover set
+   * under one of these is invisible to a current-package read, so cover reads
+   * fall back through this list in order. Drop an entry once every cover it
+   * holds has been re-set under `releaseCoverArt`.
+   */
+  legacyReleaseCoverArt: readonly string[];
+  /** `composition_credits` / `recording_credits` / `release_credits` extensions. */
+  compositionCredits: string;
+  recordingCredits: string;
+  releaseCredits: string;
+  /** `miso_credit` — the shared `Credit<Role>` value type credits are built from. */
+  credit: string;
+}
+
+/** Package ids for PartyOS core and every party extension the artist page reads. */
+export interface PartyIds {
+  partyPackageId: string;
+  partyProfilePackageId: string;
+  countryCodePackageId: string;
+  languageCodePackageId: string;
+  partyMediaPackageId: string;
+  partyRolesPackageId: string;
+  partyTagsPackageId: string;
+  partyGenrePackageId: string;
+  partyCtaPackageId: string;
+  partyPlatformLinkPackageId: string;
+  partySocialPackageId: string;
+  partyMusicPackageId: string;
+  partyProLinkPackageId: string;
+  partyFeaturedDropPackageId: string;
+  genrePackageId: string;
+}
+
+/** The currency the app prices records in, and where test dollars come from. */
+export interface MoneyIds {
+  /** Coin type balances, drops, and purchases are denominated in. */
+  usdCoinType: string;
+  usdDecimals: number;
+}
+
+export interface MisoConfig {
+  network: Network;
+  protocol: ProtocolIds;
+  party: PartyIds;
+  money: MoneyIds;
+  /** Sui gRPC-web endpoint the data plane reads through. */
+  grpcUrl: string;
+  /**
+   * Sui GraphQL RPC endpoint. Needed for the two things gRPC cannot answer:
+   * "which object has type X" (share type → work id) and reading a transaction
+   * the fullnode has already pruned.
+   */
+  graphqlUrl: string;
+  /** Walrus aggregator serving cover art and party media for this network. */
+  walrusAggregatorUrl: string;
+  /**
+   * Public origin of the Miso API, used to build avatar URLs (`/media/avatar/…`).
+   * Avatars are an R2-backed API lane, not on-chain data, so the SDK needs the
+   * public host to hand back a URL a browser can actually fetch.
+   */
+  apiBaseUrl: string;
+  /** Releases the Discover shelf lists, in display order. Resolved to their live drop at read time. */
+  discoverReleaseIds: readonly string[];
+}
+
+const TESTNET: MisoConfig = {
+  network: "testnet",
+  protocol: {
+    miso: "0x648c9dfba8c800ebd5e608599551f51e1a157942e29d59a1c35e14c44367acf0",
+    drop: "0xfc2b51f068dee9d5482d39fa017164f6a8c3601cabb59084a518de5f609ef1c7",
+    recordSettings: "0xadf53b5be0d9eea43712b0c73d0ce55d1fb990ba06e35e12a9a371b2dfe3fd35",
+    releaseCoverArt: "0x1ee2cae0da7595d7973c310c912434ef531589b468cc57839296810c1385f7f6",
+    legacyReleaseCoverArt: ["0x7d4a205a68f8e768a408c9f4c45a4d4076722c5edeba9068c0ac058f554e964e"],
+    compositionCredits: "0x25ba72b5737cac577ca8c92d0f1962efbe5d688a1088cfdc580740605086b366",
+    recordingCredits: "0xd272b1960e5fae15ae2a5425b910a96619727c85acd0c0095b6089531fdb32a9",
+    releaseCredits: "0xed764634b9c9a6af04e3c7f60f657c8e2129baf9b43fb9aee6f3523a423228e4",
+    credit: "0x96c82da135bbd534850ca0a2445fdd2531dd4e0947ffa14645a2eb6636d83646",
+  },
+  party: {
+    partyPackageId: "0xd1c0253f837c57bd0a572673a28374e32c118059356e0c9db26784897175197e",
+    partyProfilePackageId: "0x6f8841bb252d3ba0f59f9027546be7a0e0a59d84757214df216eb14ef8a9719e",
+    countryCodePackageId: "0x6c3a53f228ccd089825d0fb5ee1f0465a4b7a438bc1b1735b4e2f01df8d056e9",
+    languageCodePackageId: "0xa18b786807cfc45488691f93aa647800b77cf9993e420d110afd7024c5b15948",
+    partyMediaPackageId: "0xc04dbdc05076f642fa8dc79257de9d45ee71fc8fee4a4fe1c05c6bb27e8982ee",
+    partyRolesPackageId: "0x18e6d59fe3a6496bd42273fd97e6e4b0ae7d3a8a876a6bbe4f6ae1b6057a6f38",
+    partyTagsPackageId: "0x5a5ed50aac1146b34490949ab33fd29dc2ba13ddf1b8f90b4797e67e1301609d",
+    partyGenrePackageId: "0x2d489291ce41392ae887e2e048f752a9bd6bea9f540b2c3d2356e36f0e624e29",
+    partyCtaPackageId: "0xbf4b04afa5b9c87b7385c6a1f116165a6e3f9bed3e16ea064fed7be4da14db7f",
+    partyPlatformLinkPackageId: "0x2bf95053493e640e3641abef2a9d6080ac563da62a5ca8e878e6d3459fdf27c8",
+    partySocialPackageId: "0x24bdc5f4cdf68d5cbd6f2b4b791f8b0311060a7fac7e54c10d3a101aa7d6b56d",
+    partyMusicPackageId: "0x40d8c48aa7cd8ade4ccfc7eb68de958403b08a897589934c191993b25961c453",
+    partyProLinkPackageId: "0xe2f0160eeac627378538b82209c2cd58b6a73827dae46f5f92368a6c7e84ee8d",
+    partyFeaturedDropPackageId: "0x5205a9f88702ed2dadd95e4d0096c691a40c96d8bb05d77127f1a62a6eb72cf7",
+    genrePackageId: "0x7ee69a2f1440152ecdacad997364fb28fe1fc140fd720e4c6d37ad78e29a376d",
+  },
+  money: {
+    usdCoinType: "0x77774cb7b8cb5622b4ef2658101bf5f1e965418297fe874b683df8f760b6e749::fakeusd::FakeUsd",
+    usdDecimals: 6,
+  },
+  grpcUrl: "https://fullnode.testnet.sui.io",
+  graphqlUrl: "https://graphql.testnet.sui.io/graphql",
+  walrusAggregatorUrl: "https://aggregator.walrus-testnet.walrus.space",
+  apiBaseUrl: "https://api.testnet.miso.fm",
+  discoverReleaseIds: [
+    // AMIANGELIKA — BLCK SUN
+    "0xa16e7ef7af5104690117321c749995db1164db668a5559cf6a0706b26141c327",
+    // Gateway Girl — Between the Doors
+    "0x7144600de3bb037f23b9371a2bcd5c0d84a80abc381a9d03b00ff7e03f412623",
+  ],
+};
+
+/** Fields a deployment may override without forking the whole config (endpoints, shelf). */
+export type MisoConfigOverrides = Partial<
+  Pick<MisoConfig, "grpcUrl" | "graphqlUrl" | "walrusAggregatorUrl" | "apiBaseUrl" | "discoverReleaseIds">
+>;
+
+/**
+ * The config for `network`. Mainnet throws until its packages are deployed and
+ * filled in here — a mainnet worker must fail loudly, never read testnet ids.
+ */
+export function misoConfig(network: Network, overrides: MisoConfigOverrides = {}): MisoConfig {
+  if (network === "mainnet") {
+    throw new Error(
+      "@misofm/sdk/read: no mainnet configuration yet. Deploy the Move packages, then fill in the mainnet block in src/read/config.ts.",
+    );
+  }
+  return { ...TESTNET, ...stripUndefined(overrides) };
+}
+
+/** `{ a: undefined }` must not clobber a real default when spread. */
+function stripUndefined<T extends object>(o: T): Partial<T> {
+  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>;
+}

package/src/read/genres.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Genre name resolution. `party.getGenres` returns `Genre` OBJECT IDS; each Genre
+// object carries a screaming-snake name ("HIP_HOP"). There is no id→name table
+// anywhere off-chain, so the names are read from the objects and humanized.
+
+import type { MisoClient } from "./client.ts";
+
+/** "HIP_HOP" → "Hip Hop". */
+function humanize(name: string): string {
+  return name
+    .split("_")
+    .filter(Boolean)
+    .map((w) => w.charAt(0) + w.slice(1).toLowerCase())
+    .join(" ");
+}
+
+/**
+ * Resolve `Genre` object ids to display names. Best-effort: an id that fails to
+ * read is dropped rather than failing the artist page around it.
+ */
+export async function resolveGenreNames(client: MisoClient, ids: string[]): Promise<string[]> {
+  if (ids.length === 0) return [];
+  try {
+    const { objects } = await client.protocol.core.getObjects({ objectIds: ids, include: { json: true } });
+    const out: string[] = [];
+    for (const o of objects) {
+      if (o instanceof Error) continue;
+      const name = (o.json as { name?: unknown } | null)?.name;
+      if (typeof name === "string" && name) out.push(humanize(name));
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}

package/src/read/index.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// @misofm/sdk/read — Miso's high-level platform read surface.
+//
+// One place that knows how to turn Sui objects into the things Miso talks about:
+// a pressing, a release, an artist, a library, a receipt. It composes
+// @misonetwork/miso-protocol and @misonetwork/miso-party, owns the per-network id
+// manifest, and returns view types that survive JSON.
+//
+// Browser- and server-compatible. The HTTP API is a thin cached transport over
+// this same surface; direct clients can use it without going through the API.
+//
+//   const miso = createMisoClient({ network: "testnet" })
+//   const pressing = await getPressingDetail(miso, pressingId)
+
+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 {
+  currencyInfo,
+  getDiscoverShelf,
+  getDropPreview,
+  getPressingDetail,
+  getRecordAlbum,
+  getReleaseDetail,
+  getTrackCredits,
+  primaryArtistNames,
+  readReleaseCover,
+} from "./catalog.ts";
+
+export { getArtistProfile, getFeaturedRelease, getPartySummaries, partyAvatarUrl } from "./artist.ts";
+export type { ArtistInclude, GetArtistOptions } from "./artist.ts";
+
+export { resolveGenreNames } from "./genres.ts";
+
+export {
+  RECORD_TYPE_SUFFIX,
+  getBalance,
+  getOwnedParties,
+  getOwnedRecords,
+  getOwnedWorks,
+  getWorkByCap,
+  ownsParty,
+  ownsRecord,
+} from "./wallet.ts";
+
+export { breakdown, getPurchaseReceipt } from "./receipts.ts";
+
+export type * from "./types.ts";