@misofm/api-client 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# `@misofm/api-client`
+
+Typed client, schemas, and response contracts for the Miso API read layer.
+
+```ts
+import { MisoApiClient } from "@misofm/api-client";
+
+const client = new MisoApiClient({ baseUrl: "https://api.testnet.miso.fm" });
+```
+
+The package is maintained in the [`misofm/api`](https://github.com/misofm/api)
+repository. Its Zod schemas are the source of truth for responses shared by the
+read service and browser clients.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@misofm/api-client",
+  "version": "0.1.0",
+  "description": "Typed client and response contract for the Miso API read layer. The one definition of what a Miso read returns.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/misofm/api.git",
+    "directory": "packages/api-client"
+  },
+  "homepage": "https://github.com/misofm/api/tree/main/packages/api-client#readme",
+  "bugs": {
+    "url": "https://github.com/misofm/api/issues"
+  },
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./schemas": "./src/schemas.ts",
+    "./types": "./src/types.ts",
+    "./cache": "./src/cache.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cache.test.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The cache table is a policy document that happens to be executable, so it gets
+// tested as one: the exact header per class, and the invariants that make the
+// classes coherent with each other.
+
+import { describe, expect, test } from "bun:test";
+import { CACHE_POLICIES, cacheControl, workCacheClass, type CacheClass } from "./cache.ts";
+
+describe("cacheControl", () => {
+  const expected: Record<CacheClass, string> = {
+    immutable: "public, max-age=31536000, s-maxage=31536000, immutable",
+    published: "public, max-age=300, s-maxage=3600, stale-while-revalidate=86400",
+    draft: "public, max-age=0, s-maxage=60, stale-while-revalidate=300",
+    artist: "public, max-age=30, s-maxage=60, stale-while-revalidate=600",
+    sale: "public, max-age=0, s-maxage=60, stale-while-revalidate=300",
+    private: "private, no-store",
+  };
+
+  for (const [cls, header] of Object.entries(expected)) {
+    test(`${cls} → ${header}`, () => {
+      expect(cacheControl(cls as CacheClass)).toBe(header);
+    });
+  }
+
+  test("private never reaches a shared cache", () => {
+    const header = cacheControl("private");
+    expect(header).not.toContain("public");
+    expect(header).not.toContain("s-maxage");
+    expect(header).toContain("no-store");
+  });
+});
+
+describe("policy invariants", () => {
+  const publicClasses = (Object.keys(CACHE_POLICIES) as CacheClass[]).filter((c) => c !== "private");
+
+  test("the edge always holds a response at least as long as a browser does", () => {
+    // Otherwise the browser outlives the shared copy and the edge cache is
+    // pointless — every client revalidation would miss.
+    for (const cls of publicClasses) {
+      const p = CACHE_POLICIES[cls];
+      expect(p.sMaxAge!).toBeGreaterThanOrEqual(p.maxAge);
+    }
+  });
+
+  test("staleTime mirrors the browser lifetime, so the client never refetches what it already holds fresh", () => {
+    for (const cls of publicClasses) {
+      const p = CACHE_POLICIES[cls];
+      if (Number.isFinite(p.staleTimeMs)) expect(p.staleTimeMs).toBe(p.maxAge * 1000);
+    }
+    expect(CACHE_POLICIES.immutable.staleTimeMs).toBe(Number.POSITIVE_INFINITY);
+  });
+
+  test("live sale data is among the shortest public TTLs", () => {
+    // No longer strictly the shortest: a pressing is UNCAPPED, so its
+    // copies-sold counter gates nothing and a minute of staleness is cosmetic.
+    // `draft` now ties it, because an editor really must see their own change.
+    const others = publicClasses.filter((c) => c !== "sale");
+    for (const cls of others) {
+      expect(CACHE_POLICIES.sale.sMaxAge!).toBeLessThanOrEqual(CACHE_POLICIES[cls].sMaxAge!);
+    }
+  });
+
+  test("a draft is cached far more briefly than a published work", () => {
+    expect(CACHE_POLICIES.draft.sMaxAge!).toBeLessThan(CACHE_POLICIES.published.sMaxAge!);
+    // An editor must see their own change land.
+    expect(CACHE_POLICIES.draft.maxAge).toBe(0);
+  });
+
+  test("private carries no shared lifetime at all", () => {
+    expect(CACHE_POLICIES.private.sMaxAge).toBeNull();
+    expect(CACHE_POLICIES.private.staleWhileRevalidate).toBeNull();
+    expect(CACHE_POLICIES.private.staleTimeMs).toBe(0);
+  });
+});
+
+describe("workCacheClass", () => {
+  test("published work caches long, draft caches short", () => {
+    expect(workCacheClass({ type: "Published" })).toBe("published");
+    expect(workCacheClass({ type: "Initialized" })).toBe("draft");
+  });
+
+  test("an unknown or missing state is treated as a draft", () => {
+    // Fail toward freshness: over-caching a work that is still moving is the
+    // worse error, because the artist edits and nothing happens.
+    expect(workCacheClass(null)).toBe("draft");
+    expect(workCacheClass(undefined)).toBe("draft");
+  });
+});

package/src/cache.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// How long each kind of read stays good. ONE table, shared by both ends:
+//
+//   miso-read-service  turns a class into `Cache-Control` and a Cache API entry
+//   this client        turns the same class into a TanStack Query `staleTime`
+//
+// They live together because a client that refetches every 30s in front of an
+// edge that caches for 60s is just serving itself the cached body twice. Reading
+// the same numbers keeps the browser's idea of "fresh" and the edge's identical.
+//
+// The classes are chosen by WHAT MOVES THE DATA, not by route:
+//
+//   immutable   nothing can change it, ever. A record's parent release is fixed
+//               at mint; a settled transaction is settled. Cache for a year.
+//   published   a published work. Its metadata only moves when an artist
+//               deliberately re-sets an extension — rare, and a minute of
+//               staleness costs nobody anything.
+//   draft       the same work before publication: actively being edited in
+//               studio, so the editor must see their own change land.
+//   artist      a profile page. Owner edits should surface within a minute.
+//   sale        a live pressing. The only field that moves between reads is the
+//               copies-sold counter — and a pressing is UNCAPPED (one open run,
+//               no editions, no supply cap, no sold-out state), so that counter
+//               gates nothing. It is a display number, not a stock level, which
+//               is why a minute of staleness is cosmetic rather than a
+//               correctness problem.
+//   private     address-scoped. Never enters a shared cache — the failure mode is
+//               serving one user's library to another.
+//
+// THERE IS NO INVALIDATION. These TTLs are the whole freshness story: the cache
+// is an optimization, never a source of truth, and the chain stays
+// authoritative. A writer who must see their OWN change immediately appends a
+// cache-buster param, which mints one throwaway entry instead of evicting the
+// one everybody else is reading.
+
+export type CacheClass = "immutable" | "published" | "draft" | "artist" | "sale" | "private";
+
+export interface CachePolicy {
+  /** Shared-cache lifetime in seconds (`s-maxage`). `null` for private. */
+  sMaxAge: number | null;
+  /**
+   * How long past `sMaxAge` the edge may serve the stale body while it
+   * revalidates behind the request. This is where the latency win lives: a
+   * visitor after expiry gets the old body instantly instead of waiting on a
+   * chain round-trip.
+   */
+  staleWhileRevalidate: number | null;
+  /** Browser lifetime (`max-age`). Deliberately shorter than the edge's. */
+  maxAge: number;
+  /** TanStack Query `staleTime`, in ms. Mirrors `maxAge`. */
+  staleTimeMs: number;
+}
+
+export const CACHE_POLICIES: Record<CacheClass, CachePolicy> = {
+  immutable: { sMaxAge: 31_536_000, staleWhileRevalidate: null, maxAge: 31_536_000, staleTimeMs: Number.POSITIVE_INFINITY },
+  published: { sMaxAge: 3_600, staleWhileRevalidate: 86_400, maxAge: 300, staleTimeMs: 300_000 },
+  draft: { sMaxAge: 60, staleWhileRevalidate: 300, maxAge: 0, staleTimeMs: 0 },
+  artist: { sMaxAge: 60, staleWhileRevalidate: 600, maxAge: 30, staleTimeMs: 30_000 },
+  sale: { sMaxAge: 60, staleWhileRevalidate: 300, maxAge: 0, staleTimeMs: 0 },
+  private: { sMaxAge: null, staleWhileRevalidate: null, maxAge: 0, staleTimeMs: 0 },
+};
+
+/**
+ * The `Cache-Control` header for a class.
+ *
+ * `private, no-store` on the private class is doing real work: `private` alone
+ * would still let a browser (or a misconfigured intermediary) retain the body,
+ * and these responses describe one wallet's holdings.
+ */
+export function cacheControl(cls: CacheClass): string {
+  const p = CACHE_POLICIES[cls];
+  if (p.sMaxAge === null) return "private, no-store";
+
+  const parts = ["public", `max-age=${p.maxAge}`, `s-maxage=${p.sMaxAge}`];
+  if (p.staleWhileRevalidate !== null) parts.push(`stale-while-revalidate=${p.staleWhileRevalidate}`);
+  if (cls === "immutable") parts.push("immutable");
+  return parts.join(", ");
+}
+
+/** TanStack Query options for a class — spread straight into `useQuery`. */
+export function queryPolicy(cls: CacheClass): { staleTime: number } {
+  return { staleTime: CACHE_POLICIES[cls].staleTimeMs };
+}
+
+/**
+ * A work's class from its own state. This is why the middleware picks TTL from
+ * the RESPONSE rather than the route: the same `/releases/:id` path is a
+ * year-stable published record for one id and a live draft for another.
+ */
+export function workCacheClass(state: { type: string } | null | undefined): CacheClass {
+  return state?.type === "Published" ? "published" : "draft";
+}

package/src/checkout.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The card-checkout contract (Stripe on-ramp for records). Served by
+// miso-platform-service under `/platform/checkout`, not by the read service — it
+// is a WRITE surface with its own Durable Object payment gate — but it lives in
+// this package so an app has one API dependency rather than two.
+//
+// Lifted from miso-app's `lib/checkout-client.ts`, which was hand-written against
+// the backend and had no way to notice the backend changing.
+//
+//   quote → sign → session → redirect to Stripe → poll the receipt
+
+import { z } from "zod";
+import { MisoApiError } from "./client.ts";
+
+export const checkoutQuoteSchema = z.object({
+  /** The signed payload the buyer signs to prove intent. */
+  payload: z.string(),
+  nonce: z.string(),
+  /** What the card will actually be charged, in USD cents (price + card fee). */
+  cardAmountCents: z.number().int(),
+  expiresAt: z.string(),
+  priceDisplay: z.string(),
+});
+
+export const checkoutSessionSchema = z.object({
+  /** Stripe Checkout URL to redirect to. */
+  url: z.string().url(),
+  orderId: z.string(),
+});
+
+export const orderStateSchema = z.enum([
+  "awaiting_payment",
+  "paid",
+  "fulfilling",
+  "under_review",
+  "fulfilled",
+  "fulfill_failed",
+  "refund_pending",
+  "refunded",
+  "expired",
+]);
+
+export const receiptLineItemSchema = z.object({
+  description: z.string(),
+  amountCents: z.number().int(),
+  /** ISO-4217, lowercase (always "usd"). */
+  currency: z.string(),
+  quantity: z.number().int(),
+});
+
+export const orderReceiptSchema = z.object({
+  state: orderStateSchema,
+  /** The Sui address the record is/was delivered to. */
+  buyerAddress: z.string(),
+  lineItems: z.array(receiptLineItemSchema),
+  /** The minted record's object id once fulfilled — the target of "Mix it now". */
+  recordObjectId: z.string().optional(),
+  txDigest: z.string().optional(),
+  network: z.enum(["testnet", "mainnet"]),
+  failureReason: z.string().optional(),
+});
+
+export type CheckoutQuote = z.infer<typeof checkoutQuoteSchema>;
+export type CheckoutSession = z.infer<typeof checkoutSessionSchema>;
+export type OrderState = z.infer<typeof orderStateSchema>;
+export type ReceiptLineItem = z.infer<typeof receiptLineItemSchema>;
+export type OrderReceipt = z.infer<typeof orderReceiptSchema>;
+
+/**
+ * Terminal "you can't see this": the order uuid + session_id capability pair did
+ * not resolve — unknown order, wrong or expired session, or a malformed link. The
+ * API returns an identical 404 for all of these so nothing leaks about whether
+ * the order exists, which means the client can't tell them apart either.
+ *
+ * **Stop polling on this.** Any other non-2xx is transient and safe to retry.
+ */
+export class CheckoutNotFoundError extends MisoApiError {
+  constructor(message: string) {
+    super(404, "not_found", message);
+    this.name = "CheckoutNotFoundError";
+  }
+}
+
+export interface CheckoutClientOptions {
+  baseUrl: string;
+  fetch?: typeof globalThis.fetch;
+  /** Where the platform service is mounted on `baseUrl`. */
+  prefix?: string;
+}
+
+export function createCheckoutClient(options: CheckoutClientOptions) {
+  const base = options.baseUrl.replace(/\/$/, "");
+  const prefix = options.prefix ?? "/platform/checkout";
+  const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+
+  async function parseError(res: Response): Promise<MisoApiError> {
+    const body = (await res.json().catch(() => null)) as { error?: string | { message?: string } } | null;
+    const raw = body?.error;
+    const message = typeof raw === "string" ? raw : (raw?.message ?? `Request failed (${res.status})`);
+    return new MisoApiError(res.status, "checkout_error", message);
+  }
+
+  async function post<T>(schema: z.ZodType<T>, path: string, body: unknown): Promise<T> {
+    const res = await doFetch(`${base}${prefix}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw await parseError(res);
+    return schema.parse(await res.json());
+  }
+
+  return {
+    /** Price + signed-payload quote for a drop, for a given recipient. */
+    getQuote: (dropId: string, recipient: string): Promise<CheckoutQuote> =>
+      post(checkoutQuoteSchema, "/quote", { dropId, recipient }),
+
+    /** Verify the signature + Enoki identity, then open a Stripe session. */
+    createSession: (params: {
+      payload: string;
+      signature: string;
+      address: string;
+      nonce: string;
+      jwt: string;
+      recordName?: string;
+    }): Promise<CheckoutSession> => post(checkoutSessionSchema, "/session", params),
+
+    /**
+     * The buyer-scoped receipt for the post-purchase page. Requires the order
+     * uuid AND the Stripe session id from the success redirect — a capability
+     * pair, not an id lookup. A 404/400 throws {@link CheckoutNotFoundError}.
+     */
+    getReceipt: async (orderId: string, sessionId: string): Promise<OrderReceipt> => {
+      const res = await doFetch(
+        `${base}${prefix}/orders/${orderId}/receipt?session_id=${encodeURIComponent(sessionId)}`,
+      );
+      if (res.status === 404 || res.status === 400) throw new CheckoutNotFoundError((await parseError(res)).message);
+      if (!res.ok) throw await parseError(res);
+      return orderReceiptSchema.parse(await res.json());
+    },
+  };
+}
+
+export type CheckoutClient = ReturnType<typeof createCheckoutClient>;

package/src/client.test.ts

@@ -0,0 +1,201 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, test } from "bun:test";
+import { cacheBuster, createMisoApiClient, MisoApiContractError, MisoApiError, READ_CACHE_CLASS } from "./client.ts";
+
+/** A fetch that records the URL it was called with and replays a canned response. */
+function stubFetch(response: { status?: number; body?: unknown }) {
+  const calls: string[] = [];
+  const fetch = (async (input: string | URL) => {
+    calls.push(String(input));
+    return new Response(response.body === undefined ? "" : JSON.stringify(response.body), {
+      status: response.status ?? 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as unknown as typeof globalThis.fetch;
+  return { fetch, calls };
+}
+
+const BASE = "https://api.testnet.miso.fm";
+
+const balance = {
+  address: "0xabc",
+  coinType: "0x7777::fakeusd::FakeUsd",
+  balance: "100000000",
+  decimals: 6,
+};
+
+describe("URL construction", () => {
+  test("mounts reads under the gateway's read prefix", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    await createMisoApiClient({ baseUrl: BASE, fetch }).getBalance("0xabc");
+    expect(calls[0]).toBe(`${BASE}/read/v1/wallets/0xabc/balance`);
+  });
+
+  test("tolerates a trailing slash on the base URL", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    await createMisoApiClient({ baseUrl: `${BASE}/`, fetch }).getBalance("0xabc");
+    expect(calls[0]).toBe(`${BASE}/read/v1/wallets/0xabc/balance`);
+  });
+
+  test("omits empty query params rather than sending them blank", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    await createMisoApiClient({ baseUrl: BASE, fetch }).getBalance("0xabc", undefined);
+    expect(calls[0]).not.toContain("coinType");
+  });
+
+  test("sends an explicit coin type when given one", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    await createMisoApiClient({ baseUrl: BASE, fetch }).getBalance("0xabc", "0x2::sui::SUI");
+    expect(calls[0]).toContain("coinType=0x2%3A%3Asui%3A%3ASUI");
+  });
+
+  test("joins the artist include list into one param", async () => {
+    const { fetch, calls } = stubFetch({ status: 404 });
+    await createMisoApiClient({ baseUrl: BASE, fetch }).getArtist("0xp", { include: ["roles", "tags"] });
+    expect(calls[0]).toContain("include=roles%2Ctags");
+  });
+
+  test("a custom prefix is honored (self-hosted / direct-to-service)", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    await createMisoApiClient({ baseUrl: BASE, fetch, prefix: "/v1" }).getBalance("0xabc");
+    expect(calls[0]).toBe(`${BASE}/v1/wallets/0xabc/balance`);
+  });
+});
+
+describe("not-found handling", () => {
+  test("a superseded pressing is null, not an error", async () => {
+    const { fetch } = stubFetch({ status: 404, body: { error: { code: "not_found", message: "gone" } } });
+    expect(await createMisoApiClient({ baseUrl: BASE, fetch }).getPressing("0xdead")).toBeNull();
+  });
+
+  test("an unknown artist is null", async () => {
+    const { fetch } = stubFetch({ status: 404, body: { error: { code: "not_found", message: "gone" } } });
+    expect(await createMisoApiClient({ baseUrl: BASE, fetch }).getArtist("0xdead")).toBeNull();
+  });
+
+  test("an empty id list short-circuits without a request", async () => {
+    const { fetch, calls } = stubFetch({ body: [] });
+    expect(await createMisoApiClient({ baseUrl: BASE, fetch }).getArtists([])).toEqual([]);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("error handling", () => {
+  test("surfaces the server's error code and message", async () => {
+    const { fetch } = stubFetch({ status: 429, body: { error: { code: "rate-limited", message: "Too many requests." } } });
+    const api = createMisoApiClient({ baseUrl: BASE, fetch });
+    await expect(api.getDiscover()).rejects.toThrow(MisoApiError);
+    try {
+      await api.getDiscover();
+    } catch (e) {
+      expect(e).toBeInstanceOf(MisoApiError);
+      expect((e as MisoApiError).status).toBe(429);
+      expect((e as MisoApiError).code).toBe("rate-limited");
+      expect((e as MisoApiError).message).toBe("Too many requests.");
+    }
+  });
+
+  test("an error body in an unexpected shape still throws a usable error", async () => {
+    const { fetch } = stubFetch({ status: 500, body: { oops: true } });
+    try {
+      await createMisoApiClient({ baseUrl: BASE, fetch }).getDiscover();
+      throw new Error("should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(MisoApiError);
+      expect((e as MisoApiError).code).toBe("unknown");
+    }
+  });
+
+  test("a 404 on an endpoint that must return a body is an error, not null", async () => {
+    const { fetch } = stubFetch({ status: 404, body: { error: { code: "not_found", message: "gone" } } });
+    await expect(createMisoApiClient({ baseUrl: BASE, fetch }).getWalletRecords("0xabc")).rejects.toThrow(MisoApiError);
+  });
+});
+
+describe("contract validation", () => {
+  test("a response missing a required field fails loudly at the boundary", async () => {
+    const { fetch } = stubFetch({ body: { address: "0xabc", coinType: "0x2::sui::SUI" } }); // no balance
+    await expect(createMisoApiClient({ baseUrl: BASE, fetch }).getBalance("0xabc")).rejects.toThrow(
+      MisoApiContractError,
+    );
+  });
+
+  test("a u64 sent as a NUMBER is rejected — the precision bug this contract exists to prevent", async () => {
+    const { fetch } = stubFetch({ body: { ...balance, balance: 100000000 } });
+    const err = await createMisoApiClient({ baseUrl: BASE, fetch })
+      .getBalance("0xabc")
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(MisoApiContractError);
+  });
+
+  test("the contract error names the field and points at version skew", async () => {
+    const { fetch } = stubFetch({ body: { ...balance, balance: "not-a-number" } });
+    try {
+      await createMisoApiClient({ baseUrl: BASE, fetch }).getBalance("0xabc");
+      throw new Error("should have thrown");
+    } catch (e) {
+      expect((e as Error).message).toContain("balance");
+      expect((e as Error).message).toContain("different versions");
+    }
+  });
+
+  test("a valid response parses through to typed data", async () => {
+    const { fetch } = stubFetch({ body: balance });
+    const result = await createMisoApiClient({ baseUrl: BASE, fetch }).getBalance("0xabc");
+    expect(result).toEqual(balance);
+  });
+});
+
+describe("READ_CACHE_CLASS", () => {
+  test("every wallet-scoped read is private", () => {
+    for (const [method, cls] of Object.entries(READ_CACHE_CLASS)) {
+      if (method.startsWith("getWallet") || method.startsWith("owns") || method === "getBalance" || method === "getWork") {
+        expect(cls).toBe("private");
+      }
+    }
+  });
+
+  test("reads whose answer can never change are immutable", () => {
+    expect(READ_CACHE_CLASS.getRecordAlbum).toBe("immutable");
+    expect(READ_CACHE_CLASS.getReceipt).toBe("immutable");
+  });
+
+  test("live sale reads are the sale class", () => {
+    expect(READ_CACHE_CLASS.getDiscover).toBe("sale");
+    expect(READ_CACHE_CLASS.getPressing).toBe("sale");
+  });
+});
+
+describe("cache buster", () => {
+  test("no `v` is sent until something has been written", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    await createMisoApiClient({ baseUrl: BASE, fetch }).getBalance("0xabc");
+    expect(calls[0]).not.toContain("v=");
+  });
+
+  test("a supplied version rides on every read as ?v=", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    const api = createMisoApiClient({ baseUrl: BASE, fetch, version: () => "1699999999" });
+    await api.getBalance("0xabc");
+    expect(calls[0]).toContain("v=1699999999");
+  });
+
+  test("the version is read per request, so one client can be bumped in place", async () => {
+    const { fetch, calls } = stubFetch({ body: balance });
+    let v: string | undefined;
+    const api = createMisoApiClient({ baseUrl: BASE, fetch, version: () => v });
+    await api.getBalance("0xabc");
+    v = "42";
+    await api.getBalance("0xabc");
+    expect(calls[0]).not.toContain("v=");
+    expect(calls[1]).toContain("v=42");
+  });
+
+  test("cacheBuster is per-SECOND, so a burst after one write shares an entry", () => {
+    // Millisecond granularity would mint a fresh cache entry per read.
+    expect(cacheBuster(1_700_000_000_123)).toBe(cacheBuster(1_700_000_000_900));
+    expect(cacheBuster(1_700_000_000_000)).not.toBe(cacheBuster(1_700_000_001_000));
+  });
+});

package/src/client.ts

@@ -0,0 +1,272 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The typed client for the Miso read API. One of these per app.
+//
+//   const api = createMisoApiClient({ baseUrl: "https://api.testnet.miso.fm" })
+//   const shelf = await api.getDiscover()
+//
+// Every method returns a PARSED, validated body. Validation on the client is not
+// paranoia about our own server — it is what turns a silent contract break into a
+// loud one at the boundary that noticed, instead of a `Cannot read property of
+// undefined` three components deep.
+//
+// Reads that can legitimately find nothing (a pressing that was superseded, a
+// party with no pin) return `null` on 404 rather than throwing. Everything else
+// throws `MisoApiError` carrying the server's `{ error: { code, message } }`.
+
+import type { z } from "zod";
+import * as s from "./schemas.ts";
+import { queryPolicy, type CacheClass } from "./cache.ts";
+import type {
+  ArtistProfile,
+  Balance,
+  DiscoverShelf,
+  DropPreview,
+  FeaturedRelease,
+  OwnedParty,
+  OwnedRecord,
+  OwnedWork,
+  Ownership,
+  PartySummary,
+  PressingDetail,
+  PurchaseReceipt,
+  RecordAlbum,
+  ReleaseDetail,
+  ReleaseTrackCredits,
+  WorkDetail,
+} from "./types.ts";
+
+export class MisoApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.name = "MisoApiError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/**
+ * The server said something this client cannot describe. Distinct from
+ * `MisoApiError` because the fix is different: an API error is an expected
+ * outcome to render, a contract error is a version skew to deploy past.
+ */
+export class MisoApiContractError extends Error {
+  readonly issues: z.core.$ZodIssue[];
+
+  constructor(path: string, issues: z.core.$ZodIssue[]) {
+    const first = issues[0];
+    super(
+      `Response from ${path} did not match the expected contract` +
+        (first ? `: ${first.path.join(".")} — ${first.message}` : "") +
+        ". The API and @misofm/api-client are likely different versions.",
+    );
+    this.name = "MisoApiContractError";
+    this.issues = issues;
+  }
+}
+
+export interface MisoApiClientOptions {
+  /** Public API origin, e.g. `https://api.testnet.miso.fm`. */
+  baseUrl: string;
+  /**
+   * Cache buster appended to every read as `?v=`. There is no purge layer — the
+   * edge cache is an optimization, not a source of truth — so a surface that has
+   * just WRITTEN something and needs to see its own change before the TTL
+   * expires supplies a fresh value here (see {@link cacheBuster}).
+   *
+   * Returns a value rather than taking one so a single long-lived client can be
+   * bumped in place. Returning `undefined` (the default) sends no `v` at all,
+   * which is what every read should do until something is written.
+   */
+  version?: () => string | undefined;
+  /** Injectable for tests, Workers, and anything with its own fetch. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Path the read endpoints are mounted under on `baseUrl`. The gateway routes
+   * `/read/*` to the read service, whose own routes are rooted at `/v1`.
+   */
+  prefix?: string;
+}
+
+type QueryValue = string | number | boolean | undefined | null;
+
+export function createMisoApiClient(options: MisoApiClientOptions) {
+  const base = options.baseUrl.replace(/\/$/, "");
+  const prefix = options.prefix ?? "/read/v1";
+  const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+
+  function url(path: string, query: Record<string, QueryValue> = {}): string {
+    const u = new URL(`${base}${prefix}${path}`);
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== null && v !== "") u.searchParams.set(k, String(v));
+    }
+    const v = options.version?.();
+    if (v) u.searchParams.set("v", v);
+    return u.toString();
+  }
+
+  async function request<T>(
+    schema: z.ZodType<T>,
+    path: string,
+    query: Record<string, QueryValue> = {},
+    opts: { nullOn404?: boolean } = {},
+  ): Promise<T | null> {
+    const target = url(path, query);
+    const res = await doFetch(target, { headers: { Accept: "application/json" } });
+
+    if (res.status === 404 && opts.nullOn404) return null;
+
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      const parsed = s.apiErrorSchema.safeParse(body);
+      throw parsed.success
+        ? new MisoApiError(res.status, parsed.data.error.code, parsed.data.error.message)
+        : new MisoApiError(res.status, "unknown", `Request to ${path} failed (${res.status})`);
+    }
+
+    const json = await res.json().catch(() => {
+      throw new MisoApiError(res.status, "bad_response", `Response from ${path} was not JSON`);
+    });
+
+    const parsed = schema.safeParse(json);
+    if (!parsed.success) throw new MisoApiContractError(path, parsed.error.issues);
+    return parsed.data;
+  }
+
+  /** Same as `request`, for endpoints that always return a body. */
+  async function required<T>(schema: z.ZodType<T>, path: string, query?: Record<string, QueryValue>): Promise<T> {
+    return (await request(schema, path, query)) as T;
+  }
+
+  return {
+    // ── Catalog ─────────────────────────────────────────────────────────────
+    /** The records currently on sale. */
+    getDiscover: (): Promise<DiscoverShelf> => required(s.discoverShelfSchema, "/discover"),
+
+    /** A pressing and everything its buy page renders. `null` when there is no such pressing. */
+    getPressing: (pressingId: string): Promise<PressingDetail | null> =>
+      request(s.pressingDetailSchema, `/pressings/${pressingId}`, {}, { nullOn404: true }),
+
+    /** A release with its cover, credits, and resolved tracklist. */
+    getRelease: (releaseId: string): Promise<ReleaseDetail | null> =>
+      request(s.releaseDetailSchema, `/releases/${releaseId}`, {}, { nullOn404: true }),
+
+    /** Per-track credits for a release, keyed by recording id. */
+    getReleaseTrackCredits: (releaseId: string): Promise<ReleaseTrackCredits> =>
+      required(s.releaseTrackCreditsSchema, `/releases/${releaseId}/credits`),
+
+    /** A record's parent release. Immutable for the life of the record. */
+    getRecordAlbum: (recordId: string): Promise<RecordAlbum | null> =>
+      request(s.recordAlbumSchema, `/records/${recordId}/album`, {}, { nullOn404: true }),
+
+    /** Confirmation preview for a pasted pressing id. `null` when it isn't a pressing. */
+    getDropPreview: (dropId: string): Promise<DropPreview | null> =>
+      request(s.dropPreviewSchema, `/drops/${dropId}/preview`, {}, { nullOn404: true }),
+
+    // ── Artist ──────────────────────────────────────────────────────────────
+    /** An artist page. `include` adds the owner-editor fields (roles, tags). */
+    getArtist: (partyId: string, opts: { include?: readonly ("roles" | "tags")[] } = {}): Promise<ArtistProfile | null> =>
+      request(
+        s.artistProfileSchema,
+        `/artists/${partyId}`,
+        { include: opts.include?.join(",") },
+        { nullOn404: true },
+      ),
+
+    /** The party's pinned pressing, resolved. `null` when nothing is pinned. */
+    getArtistFeatured: (partyId: string): Promise<FeaturedRelease | null> =>
+      request(s.featuredReleaseSchema.nullable(), `/artists/${partyId}/featured`) as Promise<FeaturedRelease | null>,
+
+    /** Name + kind for many parties at once. */
+    getArtists: (ids: readonly string[]): Promise<PartySummary[]> =>
+      ids.length === 0
+        ? Promise.resolve([])
+        : required(s.partySummariesSchema, "/artists", { ids: ids.join(",") }),
+
+    // ── Wallet-scoped ───────────────────────────────────────────────────────
+    /** The records this wallet holds. */
+    getWalletRecords: (address: string): Promise<OwnedRecord[]> =>
+      required(s.ownedRecordsSchema, `/wallets/${address}/records`),
+
+    /** The parties this wallet administers. */
+    getWalletParties: (address: string): Promise<OwnedParty[]> =>
+      required(s.ownedPartiesSchema, `/wallets/${address}/parties`),
+
+    /** The works this wallet administers, keyed by admin cap. */
+    getWalletWorks: (address: string): Promise<OwnedWork[]> =>
+      required(s.ownedWorksSchema, `/wallets/${address}/works`),
+
+    /** One administered work, by its admin cap id. */
+    getWork: (capId: string): Promise<WorkDetail | null> =>
+      request(s.workDetailSchema, `/works/${capId}`, {}, { nullOn404: true }),
+
+    /** Spendable balance. Defaults to the app's dollar when `coinType` is omitted. */
+    getBalance: (address: string, coinType?: string): Promise<Balance> =>
+      required(s.balanceSchema, `/wallets/${address}/balance`, { coinType }),
+
+    /** Whether the wallet holds this party's admin cap. Carries the cap id. */
+    ownsParty: (address: string, partyId: string): Promise<Ownership> =>
+      required(s.ownershipSchema, `/wallets/${address}/owns`, { party: partyId }),
+
+    /** Whether the wallet owns this record. */
+    ownsRecord: (address: string, recordId: string): Promise<Ownership> =>
+      required(s.ownershipSchema, `/wallets/${address}/owns`, { record: recordId }),
+
+    // ── Receipts ────────────────────────────────────────────────────────────
+    /** What one record sale was, re-derived from its transaction. */
+    getReceipt: (pressingId: string, txDigest: string): Promise<PurchaseReceipt | null> =>
+      request(s.purchaseReceiptSchema, `/receipts/${pressingId}/${txDigest}`, {}, { nullOn404: true }),
+  };
+}
+
+export type MisoApiClient = ReturnType<typeof createMisoApiClient>;
+
+/**
+ * A cache-buster value for {@link MisoApiClientOptions.version}.
+ *
+ * Bump this after a write lands on-chain and the writer's next read mints a
+ * fresh cache entry instead of being served the pre-write one. It is deliberately
+ * coarse — seconds, not milliseconds — so a burst of reads right after one write
+ * shares a single entry rather than minting one each.
+ *
+ * Request-side revalidation is NOT an alternative: measured against the deployed
+ * edge on 2026-08-09, both `?fresh=1` and a raw `Cache-Control: no-cache`
+ * request header returned cache hits (~50ms) against a ~350ms origin fill.
+ * Workers Cache does not honour them, so the buster has to be in the key.
+ */
+export function cacheBuster(nowMs: number = Date.now()): string {
+  return String(Math.floor(nowMs / 1000));
+}
+
+/**
+ * The cache class each read belongs to, so a caller can align its own query
+ * options with the edge's TTL: `useQuery({ ...queryPolicy(READ_CACHE_CLASS.getPressing), … })`.
+ *
+ * `getRelease` is absent on purpose — a release's class depends on whether it is
+ * published, which is a property of the response, not the route. Callers derive
+ * it with `workCacheClass(release.state)`.
+ */
+export const READ_CACHE_CLASS = {
+  getDiscover: "sale",
+  getPressing: "sale",
+  getDropPreview: "sale",
+  getReleaseTrackCredits: "published",
+  getRecordAlbum: "immutable",
+  getReceipt: "immutable",
+  getArtist: "artist",
+  getArtistFeatured: "artist",
+  getArtists: "artist",
+  getWalletRecords: "private",
+  getWalletParties: "private",
+  getWalletWorks: "private",
+  getWork: "private",
+  getBalance: "private",
+  ownsParty: "private",
+  ownsRecord: "private",
+} as const satisfies Record<string, CacheClass>;
+
+export { queryPolicy };

package/src/index.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// @misofm/api-client — the typed client and response contract for the
+// Miso read API.
+//
+// This package is what every Miso frontend reads through: the PWA, the CLI,
+// agents. It carries no chain code and no Sui dependency — a browser importing it
+// gets zod and a fetch wrapper, not a blockchain SDK.
+//
+//   import { createMisoApiClient } from "@misofm/api-client";
+//   const api = createMisoApiClient({ baseUrl: "https://api.testnet.miso.fm" });
+
+export { createMisoApiClient, cacheBuster, MisoApiError, MisoApiContractError, READ_CACHE_CLASS, queryPolicy } from "./client.ts";
+export type { MisoApiClient, MisoApiClientOptions } from "./client.ts";
+
+export { CACHE_POLICIES, cacheControl, workCacheClass } from "./cache.ts";
+export type { CacheClass, CachePolicy } from "./cache.ts";
+
+export * as schemas from "./schemas.ts";
+export type * from "./types.ts";
+
+// Card checkout lives in miso-platform-service, not the read service, but it is
+// the same API to a caller — one package, one base URL, one error type.
+export * from "./checkout.ts";

package/src/schemas.ts

@@ -0,0 +1,356 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The response contract for every Miso read. This file is the SOURCE OF TRUTH:
+//
+//   · @misofm/api-client infers its types from it
+//   · miso-read-service generates its OpenAPI document from it
+//   · a contract test in that service parses every handler's real output through
+//     it, so a change in @misonetwork/sdk that these schemas don't describe fails CI
+//     rather than reaching a client
+//
+// Schemas, not hand-written interfaces, precisely so that third clause is
+// possible. Agents, the CLI, and any future surface read the same OpenAPI.
+//
+// SCALARS: every u64/u128 is a DECIMAL STRING (`u64Schema`), never a number.
+// Prices, supply counts, and balances routinely exceed 2^53, and JSON has no
+// integer type that holds them. Millisecond timestamps stay numbers — they are
+// inside Number.MAX_SAFE_INTEGER and callers want to pass them to `new Date()`.
+
+import { z } from "zod";
+
+/** A u64/u128 in base units, as a decimal string. See the file header. */
+export const u64Schema = z
+  .string()
+  .regex(/^\d+$/, "expected a decimal integer string");
+
+/** A 0x-prefixed 32-byte Sui object id or address, in canonical form. */
+export const suiIdSchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{1,64}$/, "expected a Sui object id");
+
+// ── Shared ───────────────────────────────────────────────────────────────────
+
+export const workStateSchema = z.union([
+  z.object({ type: z.literal("Initialized") }),
+  z.object({ type: z.literal("Published"), timestampMs: z.number().int() }),
+]);
+
+export const coverImageSchema = z.object({
+  kind: z.enum(["blob", "quiltPatch"]),
+  /** Aggregator URL — the only field a renderer needs. */
+  url: z.string().url(),
+});
+
+export const coverSchema = z.object({
+  still: coverImageSchema,
+  animated: coverImageSchema.nullable(),
+});
+
+export const creditSchema = z.object({
+  partyId: suiIdSchema,
+  displayName: z.string(),
+  roles: z.array(z.string()),
+});
+
+export const trackViewSchema = z.object({
+  /** Display number — "1", or "1.2" (disc.track) on a multi-disc set. */
+  no: z.string(),
+  title: z.string(),
+  recordingId: suiIdSchema,
+  /** This track's share of the release's revenue, in basis points. */
+  splitBps: z.number().int().min(0).max(10_000),
+  disc: z.number().int().min(1),
+});
+
+// ── Catalog ──────────────────────────────────────────────────────────────────
+
+export const releaseDetailSchema = z.object({
+  id: suiIdSchema,
+  title: z.string(),
+  subtitle: z.string().nullable(),
+  state: workStateSchema,
+  publishedAtMs: z.number().int().nullable(),
+  cover: coverSchema.nullable(),
+  credits: z.array(creditSchema),
+  /** The release's primary artists in chain order — its artist line. */
+  primaryArtists: z.array(z.string()),
+  discCount: z.number().int().min(0),
+  tracks: z.array(trackViewSchema),
+});
+
+export const priceSchema = z.object({
+  /** `fixed` — pay exactly this. `floor` — pay at least this. */
+  kind: z.enum(["fixed", "floor"]),
+  amount: u64Schema,
+});
+
+export const currencySchema = z.object({
+  type: z.string().nullable(),
+  symbol: z.string(),
+  decimals: z.number().int().min(0).max(18),
+});
+
+export const pressingViewSchema = z.object({
+  id: suiIdSchema,
+  releaseId: suiIdSchema,
+  edition: z.number().int().min(0),
+  price: priceSchema,
+  currency: currencySchema,
+  quantitySold: u64Schema,
+  /** Null = uncapped (an open edition). */
+  maxSupply: u64Schema.nullable(),
+  startTimestampMs: z.number().int(),
+  /** Null = evergreen. */
+  endTimestampMs: z.number().int().nullable(),
+  soldOut: z.boolean(),
+});
+
+export const pressingDetailSchema = z.object({
+  pressing: pressingViewSchema,
+  release: releaseDetailSchema,
+});
+
+export const discoverItemSchema = z.object({
+  pressing: pressingViewSchema,
+  releaseId: suiIdSchema,
+  title: z.string(),
+  /** Primary artists joined for display. Empty when no credits are set. */
+  artist: z.string(),
+  coverUrl: z.string().url().nullable(),
+});
+
+export const discoverShelfSchema = z.array(discoverItemSchema);
+
+export const recordAlbumSchema = z.object({
+  recordId: suiIdSchema,
+  releaseId: suiIdSchema.nullable(),
+});
+
+export const dropPreviewSchema = z.object({
+  pressingId: suiIdSchema,
+  currency: currencySchema,
+  title: z.string(),
+  subtitle: z.string().nullable(),
+  coverUrl: z.string().url().nullable(),
+  price: priceSchema,
+  trackCount: z.number().int().min(0),
+});
+
+/** A recording's work-role credits and recording billing positions. */
+export const recordingCreditsSchema = z.object({
+  credits: z.array(creditSchema),
+  primaryArtistIds: z.array(suiIdSchema),
+  featuredArtistIds: z.array(suiIdSchema),
+});
+
+/** Per-track credits for a release. Composition writing and recording
+ * performance/production credits remain separate. */
+export const trackCreditsSchema = z.union([
+  z.object({
+    compositionCredits: z.array(creditSchema),
+    recordingCredits: recordingCreditsSchema,
+  }),
+  // Keep already-deployed recording-only responses usable while the read service
+  // rolls out the composition-credit projection.
+  recordingCreditsSchema.transform((recordingCredits) => ({
+    compositionCredits: [],
+    recordingCredits,
+  })),
+]);
+
+/** Per-track work credits for a release, keyed by recording id. */
+export const releaseTrackCreditsSchema = z.object({
+  tracks: z.record(suiIdSchema, trackCreditsSchema),
+});
+
+// ── Artist ───────────────────────────────────────────────────────────────────
+
+export const partyMemberSchema = z.object({
+  id: suiIdSchema,
+  name: z.string(),
+});
+
+/**
+ * Every external platform the party link extensions know how to build a URL for,
+ * spanning social, music, and professional payloads. Enumerated rather than left
+ * as `string` so a renderer's icon/label switch is exhaustive at compile time —
+ * adding a platform on-chain should break the UI that has no icon for it.
+ */
+export const platformKeySchema = z.enum([
+  // Social (party_social)
+  "x",
+  "instagram",
+  "threads",
+  "tiktok",
+  "youtube",
+  "discord",
+  "telegram",
+  "reddit",
+  "twitch",
+  "facebook",
+  // Music (party_music)
+  "spotify",
+  "bandcamp",
+  "soundcloud",
+  "appleMusic",
+  "deezer",
+  "tidal",
+  "amazonMusic",
+  "audiomack",
+  // Professional / industry (party_pro_link)
+  "website",
+  "bookingPage",
+  "managementPage",
+  "publisherPage",
+  "labelPage",
+  "epk",
+  "patreon",
+  "substack",
+  "kofi",
+]);
+
+export const partyLinkSchema = z.object({
+  platform: platformKeySchema,
+  /** The platform-native identifier stored on-chain (handle / id / subdomain / URL). */
+  value: z.string(),
+  /** The public profile URL, rebuilt client-side from `value`. */
+  url: z.string(),
+});
+
+export const partyCtaSchema = z.object({ label: z.string(), url: z.string() });
+
+export const artistProfileSchema = z.object({
+  id: suiIdSchema,
+  kind: z.enum(["individual", "group"]),
+  name: z.string(),
+  createdAtMs: z.number().int(),
+  bioShort: z.string().nullable(),
+  bioLong: z.string().nullable(),
+  country: z.string().nullable(),
+  languages: z.array(z.string()),
+  /** Display names, already humanized from the on-chain HIP_HOP form. */
+  genres: z.array(z.string()),
+  links: z.array(partyLinkSchema),
+  ctas: z.array(partyCtaSchema),
+  members: z.array(partyMemberSchema),
+  /** Present only when requested via `include` — the owner-editor fields. */
+  roles: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+  avatarUrl: z.string().url(),
+});
+
+export const featuredReleaseSchema = z.object({
+  pressingId: suiIdSchema,
+  releaseId: suiIdSchema,
+  title: z.string(),
+  artist: z.string(),
+  coverUrl: z.string().url().nullable(),
+});
+
+export const partySummarySchema = z.object({
+  id: suiIdSchema,
+  name: z.string(),
+  kind: z.enum(["individual", "group"]),
+});
+
+export const partySummariesSchema = z.array(partySummarySchema);
+
+// ── Wallet-scoped ────────────────────────────────────────────────────────────
+
+export const ownedRecordSchema = z.object({
+  id: suiIdSchema,
+  type: z.string(),
+  releaseId: suiIdSchema.nullable(),
+  /** This copy's number in its run. */
+  number: z.number().int().nullable(),
+});
+
+export const ownedRecordsSchema = z.array(ownedRecordSchema);
+
+export const ownedPartySchema = z.object({
+  partyId: suiIdSchema,
+  capId: suiIdSchema,
+  name: z.string(),
+  kind: z.enum(["individual", "group"]),
+});
+
+export const ownedPartiesSchema = z.array(ownedPartySchema);
+
+export const workKindSchema = z.enum(["composition", "recording", "release"]);
+
+export const ownedWorkSchema = z.object({
+  /** The ADMIN CAP object id — the catalog's routing key. */
+  capId: suiIdSchema,
+  kind: workKindSchema,
+  workId: suiIdSchema,
+  title: z.string(),
+  state: z.string(),
+});
+
+export const ownedWorksSchema = z.array(ownedWorkSchema);
+
+export const workDetailSchema = ownedWorkSchema.extend({
+  subtitle: z.string().optional(),
+  royaltyRateBps: z.number().int().min(0).max(10_000).optional(),
+  shareType: z.string().optional(),
+  discCount: z.number().int().min(0).optional(),
+  trackCount: z.number().int().min(0).optional(),
+});
+
+export const balanceSchema = z.object({
+  address: suiIdSchema,
+  coinType: z.string(),
+  /** Base units. Totals coin objects AND the address balance. */
+  balance: u64Schema,
+  decimals: z.number().int().min(0).max(18),
+});
+
+export const ownershipSchema = z.object({
+  address: suiIdSchema,
+  objectId: suiIdSchema,
+  isOwner: z.boolean(),
+  /** Party checks only — the derived PartyAdminCap id owner-gated writes need. */
+  capId: suiIdSchema.optional(),
+});
+
+// ── Receipts ─────────────────────────────────────────────────────────────────
+
+export const recordSaleSchema = z.object({
+  dropId: z.string(),
+  releaseId: z.string(),
+  edition: z.number().int().min(0),
+  recordId: suiIdSchema,
+  number: u64Schema,
+  paid: u64Schema,
+  buyer: z.string(),
+});
+
+export const trackRoyaltySchema = z.object({
+  no: z.string(),
+  title: z.string(),
+  recordingId: suiIdSchema,
+  splitBps: z.number().int().min(0).max(10_000),
+  amount: u64Schema,
+  /** Both null when the composition's royalty rate could not be resolved. */
+  composition: u64Schema.nullable(),
+  recording: u64Schema.nullable(),
+});
+
+export const purchaseReceiptSchema = z.object({
+  sale: recordSaleSchema,
+  detail: pressingDetailSchema,
+  /** The drop's list price — differs from `sale.paid` on a floor-price overpay. */
+  price: u64Schema,
+  tracks: z.array(trackRoyaltySchema),
+});
+
+// ── Errors ───────────────────────────────────────────────────────────────────
+
+/** The envelope every non-2xx carries, matching miso-api's `apiError`. */
+export const apiErrorSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+  }),
+});

package/src/types.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Types inferred from ./schemas.ts. Nothing is hand-written here on purpose — a
+// type and its validator that can disagree will eventually disagree.
+
+import type { z } from "zod";
+import type * as s from "./schemas.ts";
+
+export type WorkState = z.infer<typeof s.workStateSchema>;
+export type CoverImage = z.infer<typeof s.coverImageSchema>;
+export type Cover = z.infer<typeof s.coverSchema>;
+export type Credit = z.infer<typeof s.creditSchema>;
+export type TrackView = z.infer<typeof s.trackViewSchema>;
+
+export type ReleaseDetail = z.infer<typeof s.releaseDetailSchema>;
+export type TrackCredits = z.infer<typeof s.trackCreditsSchema>;
+export type ReleaseTrackCredits = z.infer<typeof s.releaseTrackCreditsSchema>;
+export type Price = z.infer<typeof s.priceSchema>;
+export type Currency = z.infer<typeof s.currencySchema>;
+export type PressingView = z.infer<typeof s.pressingViewSchema>;
+export type PressingDetail = z.infer<typeof s.pressingDetailSchema>;
+export type DiscoverItem = z.infer<typeof s.discoverItemSchema>;
+export type DiscoverShelf = z.infer<typeof s.discoverShelfSchema>;
+export type RecordAlbum = z.infer<typeof s.recordAlbumSchema>;
+export type DropPreview = z.infer<typeof s.dropPreviewSchema>;
+
+export type PartyMember = z.infer<typeof s.partyMemberSchema>;
+export type PlatformKey = z.infer<typeof s.platformKeySchema>;
+export type PartyLink = z.infer<typeof s.partyLinkSchema>;
+export type PartyCta = z.infer<typeof s.partyCtaSchema>;
+export type ArtistProfile = z.infer<typeof s.artistProfileSchema>;
+export type FeaturedRelease = z.infer<typeof s.featuredReleaseSchema>;
+export type PartySummary = z.infer<typeof s.partySummarySchema>;
+
+export type OwnedRecord = z.infer<typeof s.ownedRecordSchema>;
+export type OwnedParty = z.infer<typeof s.ownedPartySchema>;
+export type WorkKind = z.infer<typeof s.workKindSchema>;
+export type OwnedWork = z.infer<typeof s.ownedWorkSchema>;
+export type WorkDetail = z.infer<typeof s.workDetailSchema>;
+export type Balance = z.infer<typeof s.balanceSchema>;
+export type Ownership = z.infer<typeof s.ownershipSchema>;
+
+export type RecordSale = z.infer<typeof s.recordSaleSchema>;
+export type TrackRoyalty = z.infer<typeof s.trackRoyaltySchema>;
+export type PurchaseReceipt = z.infer<typeof s.purchaseReceiptSchema>;
+
+export type ApiErrorBody = z.infer<typeof s.apiErrorSchema>;