@misofm/sdk 0.2.0 → 0.3.0

package/src/read/wallet.ts

@@ -0,0 +1,360 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Address-scoped reads: what a wallet owns, administers, and can spend.
+//
+// None of this is cacheable at a shared edge — every answer is different per
+// address — but it belongs here anyway, because the VALUE of a single read layer
+// is the response shape, not just the cache. The studio catalog's three-transport
+// dance (owned caps over gRPC → share types over GraphQL → work contents over
+// gRPC) is exactly the sort of thing that should exist once in the SDK rather
+// than be reimplemented by every browser, Worker, server, or native client.
+
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+import { contracts as partyContracts } from "@misonetwork/miso-party";
+import {
+  getCompositionByShareType,
+  getOwnedReleaseAdminCaps,
+  getRecordingByShareType,
+  getReleaseById,
+  isNotFound,
+} from "@misonetwork/sdk";
+import type { MisoClient } from "./client.ts";
+import { int, u64 } from "./internal/scalars.ts";
+import type { Balance, OwnedParty, OwnedRecord, OwnedWork, Ownership, WorkDetail } from "./types.ts";
+import { getRecordingTitles, getWorkAddressesByShareTypes, getWorksByIds } from "./works.ts";
+
+/** The on-chain type suffix every record object shares, across both live packages. */
+export const RECORD_TYPE_SUFFIX = "::record::Record";
+
+/**
+ * Page cap on the owned-objects scan, so a wallet holding a huge unrelated object
+ * set can't spin forever. 50/page × 20 = 1000 objects — far beyond any realistic
+ * library.
+ */
+const MAX_PAGES = 20;
+
+// ── Records ──────────────────────────────────────────────────────────────────
+
+function coerceNumber(v: unknown): number | null {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "bigint") return Number(v);
+  if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v))) return Number(v);
+  return null;
+}
+
+/**
+ * This copy's number in its run, across both record struct layouts: card
+ * checkout's `{ release_id, number }` and the SDK view's
+ * `{ release_id, edition, variant: { Prototype|Production: { number } } }`.
+ * The gRPC JSON enum shape varies by transport, so this probes defensively.
+ *
+ * Precedence is MOST SPECIFIC FIRST — a top-level `number`, then the variant's
+ * `number`, and only then `edition`. miso-app's original
+ * (`lib/records.ts:readRecordNumber`) checked `edition` before descending into
+ * the variant, so an SDK-view record reported which EDITION it came from (2)
+ * where the field means which COPY it is (12). `edition` survives as the last
+ * resort for a layout that carries nothing better.
+ */
+function readRecordNumber(json: Record<string, unknown>): number | null {
+  const direct = coerceNumber(json.number);
+  if (direct != null) return direct;
+
+  const variant = json.variant;
+  if (variant && typeof variant === "object") {
+    const v = variant as Record<string, unknown>;
+    const top = coerceNumber(v.number);
+    if (top != null) return top;
+    for (const inner of Object.values(v)) {
+      if (inner && typeof inner === "object") {
+        const n = coerceNumber((inner as Record<string, unknown>).number);
+        if (n != null) return n;
+      }
+    }
+  }
+  return coerceNumber(json.edition);
+}
+
+function readReleaseId(json: Record<string, unknown>): string | null {
+  const r = json.release_id ?? json.releaseId;
+  return typeof r === "string" && r ? r : null;
+}
+
+/**
+ * The records `owner` holds. Ownership is DIRECT — a record is an address-owned
+ * `<pkg>::record::Record` with no pressing/license/receipt intermediary.
+ *
+ * There is deliberately no `type` filter on the listing: two record packages are
+ * live, so we match the `::record::Record` SUFFIX client-side and catch both with
+ * no package-id config. Objects that fail to parse are skipped, never thrown.
+ */
+export async function getOwnedRecords(client: MisoClient, owner: string): Promise<OwnedRecord[]> {
+  const out: OwnedRecord[] = [];
+  let cursor: string | null = null;
+
+  for (let page = 0; page < MAX_PAGES; page++) {
+    // Annotated: `cursor` is both an input and assigned from the result, which
+    // TypeScript reads as a circular initializer without an explicit type.
+    const res: Awaited<ReturnType<typeof client.protocol.core.listOwnedObjects>> =
+      await client.protocol.core.listOwnedObjects({
+        owner,
+        cursor,
+        limit: 50,
+        include: { json: true },
+      });
+    for (const obj of res.objects) {
+      if (!obj.type || !obj.type.endsWith(RECORD_TYPE_SUFFIX)) continue;
+      const json = (obj.json ?? {}) as Record<string, unknown>;
+      out.push({
+        id: obj.objectId,
+        type: obj.type,
+        releaseId: readReleaseId(json),
+        number: readRecordNumber(json),
+      });
+    }
+    if (!res.hasNextPage) break;
+    cursor = res.cursor;
+    if (!cursor) break;
+  }
+  return out;
+}
+
+// ── Parties ──────────────────────────────────────────────────────────────────
+
+/**
+ * The parties `owner` administers. A wallet "owns" a party iff it holds the
+ * party's `PartyAdminCap`, so this is one owned-objects listing filtered to the
+ * cap type plus a name resolve. Caps are transferable, which is why this is
+ * authoritative in a way that remembering created parties client-side is not.
+ */
+export async function getOwnedParties(client: MisoClient, owner: string): Promise<OwnedParty[]> {
+  const capType = `${client.config.party.partyPackageId}::party::PartyAdminCap`;
+
+  // One page of 50 caps is plenty for launch-scale artists; paginate if labels
+  // ever start hitting the cap.
+  const { objects } = await client.protocol.core.listOwnedObjects({
+    owner,
+    type: capType,
+    limit: 50,
+    include: { content: true },
+  });
+
+  const caps = objects.flatMap((obj) => {
+    try {
+      const cap = partyContracts.party.PartyAdminCap.parse(obj.content);
+      return [{ capId: obj.objectId, partyId: cap.party_id }];
+    } catch {
+      return [];
+    }
+  });
+  if (caps.length === 0) return [];
+
+  const parties = await client.sui.party.getPartiesByIds(caps.map((c) => c.partyId));
+  return caps.flatMap(({ capId, partyId }) => {
+    const p = parties[partyId];
+    return p ? [{ partyId, capId, name: p.name, kind: p.kind }] : [];
+  });
+}
+
+// ── Works (studio catalog) ───────────────────────────────────────────────────
+
+/**
+ * Owned generic admin caps over gRPC. The bare type filter matches every
+ * instantiation of `CompositionAdminCap<T>` / `RecordingAdminCap<T>`; the share
+ * type `T` is parsed back out of each instance's type tag, because the cap does
+ * not store the work's id — only its share type.
+ */
+async function ownedGenericCaps(client: MisoClient, owner: string, capType: string) {
+  const { objects } = await client.protocol.core.listOwnedObjects({ owner, type: capType, limit: 50 });
+  const caps: { id: string; shareType: string }[] = [];
+  for (const obj of objects) {
+    const match = /<(.+)>$/.exec(obj.type);
+    if (match?.[1]) caps.push({ id: obj.objectId, shareType: match[1] });
+  }
+  return caps;
+}
+
+/**
+ * Every work the wallet administers, keyed by its ADMIN CAP id (the studio
+ * catalog's routing unit — caps are what control means here).
+ *
+ * Three transports, one answer: cap discovery is gRPC; one aliased GraphQL
+ * request maps every share type to its work address (gRPC cannot ask "which
+ * object has type X"); one gRPC batch loads all the work contents. Releases skip
+ * the GraphQL hop entirely — `ReleaseAdminCap` is not generic and carries
+ * `release_id` directly.
+ */
+export async function getOwnedWorks(client: MisoClient, owner: string): Promise<OwnedWork[]> {
+  const miso = client.config.protocol.miso;
+
+  const [compCaps, recCaps, relCaps] = await Promise.all([
+    ownedGenericCaps(client, owner, `${miso}::composition::CompositionAdminCap`),
+    ownedGenericCaps(client, owner, `${miso}::recording::RecordingAdminCap`),
+    getOwnedReleaseAdminCaps(client.protocol, owner, miso),
+  ]);
+
+  const addresses = await getWorkAddressesByShareTypes(
+    client.graphql,
+    { compositions: compCaps.map((c) => c.shareType), recordings: recCaps.map((c) => c.shareType) },
+    miso,
+  );
+  const works = await getWorksByIds(client.protocol, {
+    compositions: Object.values(addresses.compositions).filter((id): id is string => id !== undefined),
+    recordings: Object.values(addresses.recordings).filter((id): id is string => id !== undefined),
+    releases: relCaps.map((c) => c.releaseId),
+  });
+  const recordingTitles = await getRecordingTitles(
+    client.protocol,
+    client.graphql,
+    Object.values(addresses.recordings).filter((id): id is string => id !== undefined),
+    miso,
+  );
+
+  const comps = compCaps.flatMap((cap): OwnedWork[] => {
+    const workId = addresses.compositions[cap.shareType];
+    const composition = workId ? works.compositions[workId] : undefined;
+    if (!workId || !composition) return [];
+    return [{ capId: cap.id, kind: "composition", workId, title: composition.title, state: composition.state.type }];
+  });
+  const recs = recCaps.flatMap((cap): OwnedWork[] => {
+    const workId = addresses.recordings[cap.shareType];
+    const recording = workId ? works.recordings[workId] : undefined;
+    if (!workId || !recording) return [];
+    return [{
+      capId: cap.id,
+      kind: "recording",
+      workId,
+      title: recordingTitles[workId] ?? "Untitled",
+      state: recording.state.type,
+    }];
+  });
+  const rels = relCaps.flatMap((cap): OwnedWork[] => {
+    const release = works.releases[cap.releaseId];
+    if (!release) return [];
+    return [{ capId: cap.id, kind: "release", workId: release.id, title: release.title, state: release.state.type }];
+  });
+
+  return [...comps, ...recs, ...rels];
+}
+
+/** Classify a cap by its on-chain type, then resolve the work behind it. */
+export async function getWorkByCap(client: MisoClient, capId: string): Promise<WorkDetail | null> {
+  const miso = client.config.protocol.miso;
+
+  let type: string;
+  let json: Record<string, unknown> | null;
+  try {
+    const { object } = await client.protocol.core.getObject({ objectId: capId, include: { json: true } });
+    type = object.type;
+    json = (object.json ?? null) as Record<string, unknown> | null;
+  } catch (e) {
+    if (isNotFound(e)) return null;
+    throw e;
+  }
+
+  if (type.startsWith(`${miso}::composition::CompositionAdminCap<`)) {
+    const shareType = type.slice(type.indexOf("<") + 1, -1);
+    const c = await getCompositionByShareType(client.protocol, client.graphql, shareType, miso);
+    return {
+      capId,
+      kind: "composition",
+      workId: c.id,
+      title: c.title,
+      state: c.state.type,
+      royaltyRateBps: int(c.royaltyRate.value),
+      shareType,
+    };
+  }
+
+  if (type.startsWith(`${miso}::recording::RecordingAdminCap<`)) {
+    const shareType = type.slice(type.indexOf("<") + 1, -1);
+    const r = await getRecordingByShareType(client.protocol, client.graphql, shareType, miso);
+    const titles = await getRecordingTitles(client.protocol, client.graphql, [r.id], miso);
+    return {
+      capId,
+      kind: "recording",
+      workId: r.id,
+      title: titles[r.id] ?? "Untitled",
+      state: r.state.type,
+      shareType,
+    };
+  }
+
+  if (type.startsWith(`${miso}::release::ReleaseAdminCap`)) {
+    const releaseId = typeof json?.release_id === "string" ? json.release_id : null;
+    if (!releaseId) throw new Error(`Release cap ${capId} carries no release id`);
+    const r = await getReleaseById(client.protocol, releaseId);
+    return {
+      capId,
+      kind: "release",
+      workId: r.id,
+      title: r.title,
+      state: r.state.type,
+      discCount: r.tracks.length > 0 ? 1 : 0,
+      trackCount: r.tracks.length,
+    };
+  }
+
+  // A real object, but not a work admin cap — "no such work", not an error.
+  return null;
+}
+
+// ── Balance ──────────────────────────────────────────────────────────────────
+
+/**
+ * A wallet's spendable balance in one currency. `core.getBalance` totals coin
+ * OBJECTS and the address balance, so funds that arrived either way are counted —
+ * which matters because `balance::send_funds` (how the app transfers dollars)
+ * credits the address balance, not a coin.
+ */
+export async function getBalance(client: MisoClient, address: string, coinType?: string): Promise<Balance> {
+  const type = coinType ?? client.config.money.usdCoinType;
+  const res = await client.protocol.core.getBalance({ owner: address, coinType: type });
+  return {
+    address: normalizeSuiAddress(address),
+    coinType: type,
+    balance: u64(res.balance.balance),
+    decimals: type === client.config.money.usdCoinType ? client.config.money.usdDecimals : 9,
+  };
+}
+
+// ── Ownership ────────────────────────────────────────────────────────────────
+
+function isAddressOwner(owner: unknown, address: string): boolean {
+  const o = owner as { $kind?: string; AddressOwner?: string } | undefined;
+  return (
+    o?.$kind === "AddressOwner" && !!o.AddressOwner && normalizeSuiAddress(o.AddressOwner) === normalizeSuiAddress(address)
+  );
+}
+
+/**
+ * Whether `address` controls a party — i.e. holds its `PartyAdminCap`. The cap is
+ * a DERIVED object of the party, so this is one `getObject` on a computed id, no
+ * search. The chain enforces writes regardless; this drives the UI and hands back
+ * the cap id that owner-gated writes need.
+ *
+ * A failed read means "can't confirm", which resolves to `false` — the editor
+ * stays hidden rather than being offered and then rejected on submit.
+ */
+export async function ownsParty(client: MisoClient, address: string, partyId: string): Promise<Ownership> {
+  const capId = client.sui.party.derivePartyAdminCapId(partyId);
+  const isOwner = await client.protocol.core
+    .getObject({ objectId: capId })
+    .then(({ object }) => isAddressOwner(object?.owner, address))
+    .catch(() => false);
+  return { address: normalizeSuiAddress(address), objectId: partyId, isOwner, capId };
+}
+
+/**
+ * Whether `address` owns a record. Records are address-owned objects, so this is
+ * one `getObject` and an owner compare. Presentation gating only — it decides
+ * whether the Snapshots tab appears, and a non-owner has no snapshot content to
+ * fetch regardless.
+ */
+export async function ownsRecord(client: MisoClient, address: string, recordId: string): Promise<Ownership> {
+  const isOwner = await client.protocol.core
+    .getObject({ objectId: recordId })
+    .then(({ object }) => isAddressOwner(object?.owner, address))
+    .catch(() => false);
+  return { address: normalizeSuiAddress(address), objectId: recordId, isOwner };
+}

package/src/read/works.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import type { SuiGraphQLClient } from "@mysten/sui/graphql";
+import {
+  extractTypeParams2,
+  getCompositionsByIds,
+  getRecordingsByIds,
+  getReleasesByIds,
+  type Composition,
+  type Recording,
+  type Release,
+} from "@misonetwork/sdk";
+
+export interface WorkShareTypes {
+  compositions: readonly string[];
+  recordings: readonly string[];
+}
+
+export interface WorkAddressesByShareType {
+  compositions: Partial<Record<string, string>>;
+  recordings: Partial<Record<string, string>>;
+}
+
+interface ObjectsByTypeResult {
+  objects: {
+    nodes: Array<{
+      address: string;
+      asMoveObject: { contents: { type: { repr: string } } | null } | null;
+    }>;
+  } | null;
+}
+
+/** Resolve work share types without relying on unpublished protocol helpers. */
+export async function getWorkAddressesByShareTypes(
+  client: SuiGraphQLClient,
+  shareTypes: WorkShareTypes,
+  misoPackageId: string,
+): Promise<WorkAddressesByShareType> {
+  const compositions = [...new Set(shareTypes.compositions)];
+  const recordingSet = new Set(shareTypes.recordings);
+  const out: WorkAddressesByShareType = { compositions: {}, recordings: {} };
+
+  const compositionEntries = await Promise.all(
+    compositions.map(async (shareType) => {
+      const type = `${misoPackageId}::composition::Composition<${shareType}>`;
+      const result = await client.query<ObjectsByTypeResult, { type: string }>({
+        query: `query WorkByType($type: String!) {
+          objects(filter: { type: $type }) {
+            nodes { address asMoveObject { contents { type { repr } } } }
+          }
+        }`,
+        variables: { type },
+      });
+      if (result.errors?.length) throw new Error(result.errors[0]!.message);
+      return [shareType, result.data?.objects?.nodes[0]?.address] as const;
+    }),
+  );
+  for (const [shareType, address] of compositionEntries) {
+    if (address) out.compositions[shareType] = address;
+  }
+
+  if (recordingSet.size > 0) {
+    const type = `${misoPackageId}::recording::Recording`;
+    const result = await client.query<ObjectsByTypeResult, { type: string }>({
+      query: `query RecordingsByType($type: String!) {
+        objects(filter: { type: $type }) {
+          nodes { address asMoveObject { contents { type { repr } } } }
+        }
+      }`,
+      variables: { type },
+    });
+    if (result.errors?.length) throw new Error(result.errors[0]!.message);
+    for (const node of result.data?.objects?.nodes ?? []) {
+      const repr = node.asMoveObject?.contents?.type.repr;
+      if (!repr) continue;
+      let recordingShareType: string | undefined;
+      try {
+        [recordingShareType] = extractTypeParams2(repr);
+      } catch {
+        recordingShareType = /<(.+)>$/.exec(repr)?.[1]?.trim();
+      }
+      if (recordingShareType && recordingSet.has(recordingShareType)) {
+        out.recordings[recordingShareType] = node.address;
+      }
+    }
+  }
+
+  return out;
+}
+
+export interface WorkIds {
+  compositions: readonly string[];
+  recordings: readonly string[];
+  releases: readonly string[];
+}
+
+export interface WorksById {
+  compositions: Partial<Record<string, Composition>>;
+  recordings: Partial<Record<string, Recording>>;
+  releases: Partial<Record<string, Release>>;
+}
+
+/** Fetch each work kind through the authoritative protocol SDK. */
+export async function getWorksByIds(client: ClientWithCoreApi, ids: WorkIds): Promise<WorksById> {
+  const [compositions, recordings, releases] = await Promise.all([
+    getCompositionsByIds(client, [...ids.compositions]),
+    getRecordingsByIds(client, [...ids.recordings]),
+    getReleasesByIds(client, [...ids.releases]),
+  ]);
+  return { compositions, recordings, releases };
+}
+
+/**
+ * Resolve display titles for both deployed recording layouts. Older recordings
+ * carry `title` in JSON; current recordings inherit it from their composition.
+ */
+export async function getRecordingTitles(
+  client: ClientWithCoreApi,
+  graphql: SuiGraphQLClient,
+  recordingIds: readonly string[],
+  misoPackageId: string,
+): Promise<Record<string, string>> {
+  const ids = [...new Set(recordingIds)];
+  if (ids.length === 0) return {};
+
+  const { objects } = await client.core.getObjects({ objectIds: ids, include: { json: true } });
+  const titles: Record<string, string> = {};
+  const compositionShareByRecording: Record<string, string> = {};
+
+  for (const object of objects) {
+    if (object instanceof Error) continue;
+    const json = object.json as { title?: unknown } | null;
+    if (typeof json?.title === "string" && json.title) {
+      titles[object.objectId] = json.title;
+      continue;
+    }
+    try {
+      const [, compositionShareType] = extractTypeParams2(object.type);
+      compositionShareByRecording[object.objectId] = compositionShareType;
+    } catch {
+      // A deployed layout with no composition type and no JSON title remains Untitled.
+    }
+  }
+
+  const compositionShareTypes = Object.values(compositionShareByRecording);
+  if (compositionShareTypes.length === 0) return titles;
+  const addresses = await getWorkAddressesByShareTypes(
+    graphql,
+    { compositions: compositionShareTypes, recordings: [] },
+    misoPackageId,
+  );
+  const compositions = await getCompositionsByIds(
+    client,
+    Object.values(addresses.compositions).filter((id): id is string => !!id),
+  );
+  for (const [recordingId, shareType] of Object.entries(compositionShareByRecording)) {
+    const compositionId = addresses.compositions[shareType];
+    const title = compositionId ? compositions[compositionId]?.title : undefined;
+    if (title) titles[recordingId] = title;
+  }
+  return titles;
+}