@misofm/api-client 0.5.1 → 0.5.2

package/src/client.test.ts

@@ -1,284 +0,0 @@
-// 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("joins catalog relationship expansions into one param", async () => {
-    const { fetch, calls } = stubFetch({ status: 404 });
-    const client = createMisoApiClient({ baseUrl: BASE, fetch });
-    await client.getRelease("0xl", { include: ["trackCredits"] });
-    await client.getRecordAlbum("0xr", {
-      include: ["release", "trackCredits"],
-    });
-    expect(calls[0]).toContain("include=trackCredits");
-    expect(calls[1]).toContain("include=release%2CtrackCredits");
-  });
-
-  test("passes the currency to the modular Listing route", async () => {
-    const { fetch, calls } = stubFetch({ status: 404 });
-    await createMisoApiClient({ baseUrl: BASE, fetch }).getListing(
-      "0xp",
-      "0x2::sui::SUI",
-    );
-    expect(calls[0]).toBe(
-      `${BASE}/read/v1/pressings/0xp/listing?currencyType=0x2%3A%3Asui%3A%3ASUI`,
-    );
-  });
-
-  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("an unknown 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.getPressing("0xp")).rejects.toThrow(MisoApiError);
-    try {
-      await api.getPressing("0xp");
-    } 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 }).getPressing("0xp");
-      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.getPressing).toBe("sale");
-    expect(READ_CACHE_CLASS.getListing).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

@@ -1,325 +0,0 @@
-// 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 pressing = await api.getPressing("0x…")
-//
-// 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,
-  ListingView,
-  OwnedParty,
-  PendingMembership,
-  OwnedRecord,
-  OwnedWork,
-  Ownership,
-  PartySummary,
-  PressingView,
-  PurchaseReceipt,
-  RecordAlbum,
-  ReleaseDetail,
-  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 ─────────────────────────────────────────────────────────────
-    /** One permanent pressing resource. */
-    getPressing: (pressingId: string): Promise<PressingView | null> =>
-      request(
-        s.pressingViewSchema,
-        `/pressings/${pressingId}`,
-        {},
-        { nullOn404: true },
-      ),
-
-    /** One currency-specific Listing derived from a permanent Pressing. */
-    getListing: (
-      pressingId: string,
-      currencyType: string,
-    ): Promise<ListingView | null> =>
-      request(
-        s.listingViewSchema,
-        `/pressings/${pressingId}/listing`,
-        { currencyType },
-        { nullOn404: true },
-      ),
-
-    /** A release with its cover, credits, and resolved tracklist. */
-    getRelease: (
-      releaseId: string,
-      opts: { include?: readonly "trackCredits"[] } = {},
-    ): Promise<ReleaseDetail | null> =>
-      request(
-        s.releaseDetailSchema,
-        `/releases/${releaseId}`,
-        { include: opts.include?.join(",") },
-        { nullOn404: true },
-      ),
-
-    /** A record's parent release. Immutable for the life of the record. */
-    getRecordAlbum: (
-      recordId: string,
-      opts: { include?: readonly ("release" | "trackCredits")[] } = {},
-    ): Promise<RecordAlbum | null> =>
-      request(
-        s.recordAlbumSchema,
-        `/records/${recordId}/album`,
-        { include: opts.include?.join(",") },
-        { nullOn404: true },
-      ),
-
-    // ── Artist ──────────────────────────────────────────────────────────────
-    /** An artist plus optional relationship expansions. */
-    getArtist: (
-      partyId: string,
-      opts: { include?: readonly ("roles" | "tags")[] } = {},
-    ): Promise<ArtistProfile | null> =>
-      request(
-        s.artistProfileSchema,
-        `/artists/${partyId}`,
-        { include: opts.include?.join(",") },
-        { nullOn404: true },
-      ),
-
-    /** 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`),
-
-    /** Group invitations awaiting acceptance by this wallet's controlled parties. */
-    getPendingMemberships: (address: string): Promise<PendingMembership[]> =>
-      required(s.pendingMembershipsSchema, `/wallets/${address}/pending-memberships`),
-
-    /** 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 = {
-  getPressing: "sale",
-  getListing: "sale",
-  getRecordAlbum: "immutable",
-  getReceipt: "immutable",
-  getArtist: "artist",
-  getArtists: "artist",
-  getWalletRecords: "private",
-  getWalletParties: "private",
-  getPendingMemberships: "private",
-  getWalletWorks: "private",
-  getWork: "private",
-  getBalance: "private",
-  ownsParty: "private",
-  ownsRecord: "private",
-} as const satisfies Record<string, CacheClass>;
-
-export { queryPolicy };