@misofm/platform 0.0.0 → 0.18.0

package/src/read/client.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The one client every read in this SDK goes through.
+//
+// Two transports, because Sui splits the job:
+//   core (gRPC)  the data plane — objects by id, objects by owner, balances,
+//                transactions. Everything cheap and current.
+//   graphql      the two questions gRPC cannot answer: "which object has type X"
+//                (share type → work id, for the studio catalog and the receipt's
+//                royalty hop) and "what did this pruned transaction do".
+//
+// It also carries the resolved `MisoConfig`, so a read function takes ONE argument
+// and never has a package id threaded through its signature.
+//
+// Party now shares the same network SDK registration and deployment as protocol
+// core, so every read hangs off one `sui.miso` namespace.
+
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { SuiGraphQLClient } from "@mysten/sui/graphql";
+import { miso, type MisoProtocolClient } from "@misofm/protocol/client";
+import { misoConfig, networkFrom, type MisoConfig, type MisoConfigOverrides, type Network } from "./config.ts";
+
+function definedOverrides<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined)) as Partial<T>;
+}
+
+/**
+ * The structural slice of a Sui client the protocol SDK's read helpers want. They
+ * declare `ClientWithCoreApi` against their own @mysten/sui; this alias names the
+ * same shape from our side so the one cast in `createMisoClient` is explicit
+ * rather than an `any` smeared across the codebase.
+ */
+export type ProtocolClient = Parameters<typeof import("@misofm/protocol").getReleaseById>[0];
+
+/** A GraphQL client in the shape the protocol SDK's type-discovery queries want. */
+export type ProtocolGraphQLClient = SuiGraphQLClient;
+
+export interface MisoClient {
+  config: MisoConfig;
+  /** gRPC data plane, including Party at `sui.miso.party`. */
+  sui: SuiGrpcClient & { miso: MisoProtocolClient };
+  /** The same client, typed for the protocol SDK's read helpers. */
+  protocol: ProtocolClient;
+  /** GraphQL RPC, typed for the protocol SDK's type-discovery queries. */
+  graphql: ProtocolGraphQLClient;
+  /** The raw GraphQL client, for this SDK's own queries (the pruned-transaction read). */
+  graphqlRaw: SuiGraphQLClient;
+}
+
+export interface CreateMisoClientOptions extends MisoConfigOverrides {
+  /** "testnet" | "mainnet". A bare string (e.g. a Worker's `NETWORK` var) is accepted. */
+  network?: Network | string;
+  /** Complete verified configuration for a custom or unbundled deployment. */
+  config?: MisoConfig;
+}
+
+/**
+ * Build the client from a bundled network or a complete verified custom config.
+ */
+export function createMisoClient(options: CreateMisoClientOptions = {}): MisoClient {
+  const { network, config: providedConfig, ...overrides } = options;
+  const requestedNetwork = networkFrom(network);
+  // A caller-supplied verified deployment may still override transport URLs or
+  // the discover shelf; undefined fields never erase verified config values.
+  const config = providedConfig
+    ? { ...providedConfig, ...definedOverrides(overrides) }
+    : misoConfig(requestedNetwork, overrides);
+  if (network !== undefined && config.network !== requestedNetwork) {
+    throw new Error(
+      `@misofm/platform/read: provided config is for ${config.network}, not ${requestedNetwork}.`,
+    );
+  }
+
+  const grpc = new SuiGrpcClient({ baseUrl: config.grpcUrl, network: config.network });
+  const graphqlRaw = new SuiGraphQLClient({ url: config.graphqlUrl, network: config.network });
+
+  const sui = grpc.$extend(miso({ deployment: config.deployment }));
+
+  return {
+    config,
+    sui,
+    protocol: sui as unknown as ProtocolClient,
+    graphql: graphqlRaw as unknown as ProtocolGraphQLClient,
+    graphqlRaw,
+  };
+}

package/src/read/config.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Per-network on-chain identity: which packages the reads address, which objects
+// they read, and which endpoints they read through. Every id that used to be a
+// hard-coded constant inside miso-app (`lib/party.ts`, `lib/release.ts`,
+// `lib/money.ts`, `lib/pressing.ts`) lives here instead, so a redeploy is a change
+// in ONE file that every surface picks up.
+//
+// Testnet values are derived from the same verified deployment record exported
+// by the platform SDK. Mainnet remains deliberately unavailable until a complete
+// deployment is bundled for it.
+
+import type { MisoDeployment } from "@misofm/protocol/deployments";
+import { getMisoPlatformDeployment, type RecordSalesDeployment } from "../deployments.ts";
+
+export type Network = "testnet" | "mainnet";
+
+/** Missing defaults to Testnet for local development; invalid values fail closed. */
+export function networkFrom(value: string | undefined): Network {
+  if (value === undefined || value === "testnet") return "testnet";
+  if (value === "mainnet") return "mainnet";
+  throw new Error(`@misofm/platform/read: unsupported network "${value}".`);
+}
+
+/** Package ids for the miso protocol core and the extensions the read layer touches. */
+export interface ProtocolIds {
+  /** `vault` — shared custody for protocol admin capabilities. */
+  vault: string;
+  /** `release_cover_art` — the release cover extension. */
+  releaseCoverArt: string;
+  /** `release_kind` — the Release's optional self-declared kind. */
+  releaseKind: string;
+  /** `recording_master_reference` — optional Walrus master pointers. */
+  recordingMasterReference: string;
+  /** `release_mix_reference` — optional per-track delivery descriptor pointers. */
+  releaseMixReference?: string;
+  /** `composition_credits` / `recording_credits` / `release_credits` extensions. */
+  compositionCredits: string;
+  recordingCredits: string;
+  releaseCredits: string;
+  /** `miso_credit` — the shared `Credit<Role>` value type credits are built from. */
+  credit: string;
+}
+
+/** The currency the app prices records in, and where test dollars come from. */
+export interface MoneyIds {
+  /** Coin type balances, listings, and purchases are denominated in. */
+  usdCoinType: string;
+  usdDecimals: number;
+}
+
+export interface MisoConfig {
+  network: Network;
+  /** Complete package set used by the integrated `client.miso` SDK. */
+  deployment: MisoDeployment;
+  protocol: ProtocolIds;
+  /** Final Record/Record Shop deployment, or an explicit unavailable legacy state. */
+  recordSales: RecordSalesDeployment;
+  money: MoneyIds;
+  /** Sui gRPC-web endpoint the data plane reads through. */
+  grpcUrl: string;
+  /**
+   * Sui GraphQL RPC endpoint. Needed for the two things gRPC cannot answer:
+   * "which object has type X" (share type → work id) and reading a transaction
+   * the fullnode has already pruned.
+   */
+  graphqlUrl: string;
+  /** Walrus aggregator serving cover art and party media for this network. */
+  walrusAggregatorUrl: string;
+  /**
+   * Public origin of the Miso API, used to build avatar URLs (`/media/avatar/…`).
+   * Avatars are an R2-backed API lane, not on-chain data, so the SDK needs the
+   * public host to hand back a URL a browser can actually fetch.
+   */
+  apiBaseUrl: string;
+  /** Explicit currency offers on the Discover shelf, in display order. */
+  discoverSales: readonly DiscoverSale[];
+}
+
+/** One release/currency pair to resolve by Pressing and Listing derived address. */
+export interface DiscoverSale {
+  releaseId: string;
+  edition: number;
+  currencyType: string;
+}
+
+/** Fields a deployment may override without forking the whole config (endpoints, shelf). */
+export type MisoConfigOverrides = Partial<
+  Pick<MisoConfig, "grpcUrl" | "graphqlUrl" | "walrusAggregatorUrl" | "apiBaseUrl" | "discoverSales">
+>;
+
+/** The config for `network`, derived from this SDK's verified deployment map. */
+export function misoConfig(network: Network, overrides: MisoConfigOverrides = {}): MisoConfig {
+  const platform = getMisoPlatformDeployment(network);
+  const vaultPackageId =
+    platform.operations.status === "available"
+      ? platform.operations.vault.packageId
+      : platform.operations.legacy?.vaultPackageId;
+  if (!vaultPackageId) {
+    throw new Error(
+      `@misofm/platform/read: no current or legacy Vault type metadata for "${network}".`,
+    );
+  }
+  const config: MisoConfig = {
+    network,
+    deployment: platform.protocol,
+    recordSales: platform.recordSales,
+    protocol: {
+      // Read-only legacy type discovery does not make this package an
+      // executable operations ABI; client call surfaces remain fail closed.
+      vault: vaultPackageId,
+      releaseCoverArt: platform.packages.releaseCoverArt,
+      releaseKind: platform.packages.releaseKind,
+      recordingMasterReference: platform.packages.recordingMasterReference,
+      compositionCredits: platform.packages.compositionCredits,
+      recordingCredits: platform.packages.recordingCredits,
+      releaseCredits: platform.packages.releaseCredits,
+      credit: platform.packages.credit,
+    },
+    money: {
+      usdCoinType:
+        "0x77774cb7b8cb5622b4ef2658101bf5f1e965418297fe874b683df8f760b6e749::fakeusd::FakeUsd",
+      usdDecimals: 6,
+    },
+    grpcUrl: "https://fullnode.testnet.sui.io",
+    graphqlUrl: "https://graphql.testnet.sui.io/graphql",
+    walrusAggregatorUrl: "https://aggregator.walrus-testnet.walrus.space",
+    apiBaseUrl: "https://api.testnet.miso.fm",
+    discoverSales: [],
+  };
+  return { ...config, ...stripUndefined(overrides) };
+}
+
+/** `{ a: undefined }` must not clobber a real default when spread. */
+function stripUndefined<T extends object>(o: T): Partial<T> {
+  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>;
+}

package/src/read/genres.ts

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

package/src/read/index.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// @misofm/platform/read — Miso's high-level platform read surface.
+//
+// One place that knows how to turn Sui objects into the things Miso talks about:
+// a pressing, a release, an artist, a library, a receipt. It composes
+// @misofm/protocol, owns the per-network id manifest, and returns view types that
+// survive JSON.
+//
+// Browser- and server-compatible. The HTTP API is a thin cached transport over
+// this same surface; direct clients can use it without going through the API.
+//
+//   const miso = createMisoClient({ network: "testnet" })
+//   const pressing = await getPressingDetail(miso, pressingId)
+
+export { createMisoClient } from "./client.ts";
+export type { MisoClient, CreateMisoClientOptions } from "./client.ts";
+
+export { misoConfig, networkFrom } from "./config.ts";
+export type {
+  MisoConfig,
+  MisoConfigOverrides,
+  DiscoverSale,
+  MoneyIds,
+  Network,
+  ProtocolIds,
+} from "./config.ts";
+
+export {
+  currencyInfo,
+  getDiscoverShelf,
+  getListingView,
+  getPressingDetail,
+  getPressingView,
+  getPressingSaleDetail,
+  getPressingPreview,
+  getRecordAlbum,
+  getReleaseDetail,
+  getReleaseResources,
+  getTrackCredits,
+  getSaleDetail,
+  primaryArtistNames,
+  readReleaseCover,
+} from "./catalog.ts";
+export type {
+  GetRecordAlbumOptions,
+  GetReleaseOptions,
+  RecordAlbumInclude,
+  ReleaseInclude,
+  ReleaseResourceInclude,
+} from "./catalog.ts";
+export type { ReleaseResources } from "./catalog.ts";
+
+export {
+  getArtistProfile,
+  getPartySummaries,
+  partyAvatarUrl,
+} from "./artist.ts";
+export type { ArtistInclude, GetArtistOptions } from "./artist.ts";
+
+export { resolveGenreNames } from "./genres.ts";
+
+export {
+  getBalance,
+  getOwnedParties,
+  getPendingMemberships,
+  getOwnedRecords,
+  getOwnedWorks,
+  getWorkByCap,
+  ownsParty,
+  ownsRecord,
+} from "./wallet.ts";
+
+export {
+  breakdown,
+  findRecordSale,
+  findRecordSales,
+  getPurchaseReceipt,
+  getPurchaseReceipts,
+  isRecordSoldEventType,
+  recordSoldCurrencyType,
+} from "./receipts.ts";
+
+export type * from "./types.ts";

package/src/read/internal/scalars.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The bigint→JSON boundary. Every u64/u128 the protocol SDKs hand back arrives as
+// a `bigint`, which `JSON.stringify` throws on; these convert once, here, so no
+// view type can carry one out of the SDK (see the header of ../types.ts).
+
+/** A u64/u128 as it may arrive off the wire, in BCS, or from a JSON projection. */
+export type NumericLike = bigint | number | string | null | undefined;
+
+/**
+ * Base-unit scalar → decimal string. Returns `"0"` for anything unreadable, which
+ * is the honest projection of "the chain gave us no number" for quantities and
+ * amounts. Use {@link u64OrNull} where absent must stay distinguishable from zero.
+ */
+export function u64(v: NumericLike): string {
+  return u64OrNull(v) ?? "0";
+}
+
+/** Base-unit scalar → decimal string, or `null` when absent/unparseable. */
+export function u64OrNull(v: NumericLike): string | null {
+  if (v == null) return null;
+  if (typeof v === "bigint") return v >= 0n ? v.toString() : null;
+  if (typeof v === "number") {
+    return Number.isSafeInteger(v) && v >= 0 ? BigInt(v).toString() : null;
+  }
+  const s = v.trim();
+  return /^\d+$/.test(s) ? BigInt(s).toString() : null;
+}
+
+/**
+ * A millisecond timestamp → `number`. Milliseconds stay numbers (they are far
+ * inside Number.MAX_SAFE_INTEGER and `new Date()` wants one), unlike token
+ * amounts which must not lose precision.
+ */
+export function msOrNull(v: NumericLike): number | null {
+  const s = u64OrNull(v);
+  if (s === null) return null;
+  const n = Number(s);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+/** As {@link msOrNull}, defaulting to `0` (the epoch) when absent. */
+export function ms(v: NumericLike): number {
+  return msOrNull(v) ?? 0;
+}
+
+/** A plain integer field (bps, edition, counts) → `number`, defaulting to `0`. */
+export function int(v: NumericLike): number {
+  if (typeof v === "number" && Number.isFinite(v)) return Math.trunc(v);
+  if (typeof v === "bigint") return Number(v);
+  if (typeof v === "string" && /^-?\d+$/.test(v.trim())) return Number(v.trim());
+  return 0;
+}
+
+/** Integer comparison over two decimal strings — `a >= b` without going through Number. */
+export function gte(a: string, b: string): boolean {
+  return BigInt(a) >= BigInt(b);
+}

package/src/read/internal/walrus.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from "@mysten/sui/bcs";
+import { toBase64 } from "@mysten/sui/utils";
+import { walrusBlobIdFromU256 } from "../../mix.ts";
+
+const u256 = bcs.u256();
+
+function toBase64Url(bytes: Uint8Array): string {
+  return toBase64(bytes).replace(/=*$/, "").replaceAll("+", "-").replaceAll("/", "_");
+}
+
+export function u256ToB64Url(value: bigint | string): string {
+  return walrusBlobIdFromU256(value);
+}
+
+/** Build a blob URL with Walrus's non-strict default made explicit. */
+export function walrusBlobReadUrl(
+  aggregator: string,
+  blobId: bigint | string,
+): string {
+  const base = aggregator.replace(/\/$/, "");
+  return `${base}/v1/blobs/${u256ToB64Url(blobId)}?strict_consistency_check=false`;
+}
+
+/** Build Walrus's 37-byte quilt-patch id. All fields use BCS little-endian. */
+export function quiltPatchId(
+  quiltId: bigint | string,
+  version: number,
+  startIndex: number,
+  endIndex: number,
+): string {
+  const bytes = new Uint8Array(37);
+  bytes.set(u256.serialize(BigInt(quiltId)).toBytes(), 0);
+  bytes[32] = version;
+  bytes[33] = startIndex & 0xff;
+  bytes[34] = (startIndex >> 8) & 0xff;
+  bytes[35] = endIndex & 0xff;
+  bytes[36] = (endIndex >> 8) & 0xff;
+  return toBase64Url(bytes);
+}