@misonetwork/sdk 0.7.0 → 0.9.0

package/src/party/transactions.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Core PartyOS transaction builders. Every builder returns a thunk that *appends*
+// commands to a caller-owned Transaction, so flows compose. Package ids are taken
+// in params (the client binds them; see ./client.ts). Calls into the party package
+// go through the generated typed call fns (party.*).
+
+import type { Transaction } from "@mysten/sui/transactions";
+import * as party from "../contracts/miso_party/party.ts";
+
+export type TxThunk = (tx: Transaction) => void | Promise<void>;
+
+export interface CreatePartyParams {
+  /** Human-readable party name (not verified; app-layer verifies). */
+  name: string;
+  /** Address that receives the PartyAdminCap. */
+  recipient: string;
+  partyPackageId: string;
+}
+
+/** Creates an individual party, shares it, and transfers its admin cap to `recipient`. */
+export function createIndividualParty(params: CreatePartyParams): TxThunk {
+  return (tx) => {
+    const kind = tx.add(party.newIndividualKind({ package: params.partyPackageId }));
+    const res = tx.add(party._new({ package: params.partyPackageId, arguments: [kind, params.name] }));
+    tx.add(party.share({ package: params.partyPackageId, arguments: [res[0]!, res[1]!] }));
+    tx.transferObjects([res[1]!], params.recipient);
+  };
+}
+
+/** Creates a group party (empty member set), shares it, transfers its admin cap. */
+export function createGroupParty(params: CreatePartyParams): TxThunk {
+  return (tx) => {
+    const kind = tx.add(party.newGroupKind({ package: params.partyPackageId }));
+    const res = tx.add(party._new({ package: params.partyPackageId, arguments: [kind, params.name] }));
+    tx.add(party.share({ package: params.partyPackageId, arguments: [res[0]!, res[1]!] }));
+    tx.transferObjects([res[1]!], params.recipient);
+  };
+}
+
+// === Group membership: invite / accept / decline / revoke / leave / evict ===
+// Membership is consent-based: the group admin invites, the member accepts with
+// its OWN admin cap. `member`/`group`/`*Cap` params are all object ids.
+
+export interface InvitePartyParams {
+  groupId: string;
+  groupCapId: string;
+  /** The individual party (shared object id) to invite. */
+  memberId: string;
+  partyPackageId: string;
+}
+
+/** Invites an individual party to a group (gated by the group's admin cap). */
+export function inviteParty(params: InvitePartyParams): TxThunk {
+  return (tx) => {
+    tx.add(party.inviteParty({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.groupCapId],
+    }));
+  };
+}
+
+export interface AcceptInviteParams {
+  groupId: string;
+  memberId: string;
+  /** The member party's admin cap id (proves consent). */
+  memberCapId: string;
+  partyPackageId: string;
+}
+
+/** Accepts a pending invite, joining the member to the group (member's cap). */
+export function acceptInvite(params: AcceptInviteParams): TxThunk {
+  return (tx) => {
+    tx.add(party.acceptInvite({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.memberCapId],
+    }));
+  };
+}
+
+export interface DeclineInviteParams {
+  groupId: string;
+  /** The invited individual party (shared object id). */
+  memberId: string;
+  memberCapId: string;
+  partyPackageId: string;
+}
+
+/** Declines a pending invite (member's cap). */
+export function declineInvite(params: DeclineInviteParams): TxThunk {
+  return (tx) => {
+    tx.add(party.declineInvite({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.memberCapId],
+    }));
+  };
+}
+
+export interface RevokeInviteParams {
+  groupId: string;
+  /** The invited individual party (shared object id). */
+  memberId: string;
+  groupCapId: string;
+  partyPackageId: string;
+}
+
+/** Revokes a pending invite (group's admin cap). */
+export function revokeInvite(params: RevokeInviteParams): TxThunk {
+  return (tx) => {
+    tx.add(party.revokeInvite({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.groupCapId],
+    }));
+  };
+}
+
+export interface LeaveGroupParams {
+  groupId: string;
+  memberId: string;
+  memberCapId: string;
+  partyPackageId: string;
+}
+
+/** Leaves a group, authorized by the member's own admin cap. */
+export function leaveGroup(params: LeaveGroupParams): TxThunk {
+  return (tx) => {
+    tx.add(party.leave({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.memberCapId],
+    }));
+  };
+}
+
+export interface RemoveMemberParams {
+  groupId: string;
+  groupCapId: string;
+  memberId: string;
+  partyPackageId: string;
+}
+
+/** Evicts a member from a group (group's admin cap); scrubs the member's record too. */
+export function removeMember(params: RemoveMemberParams): TxThunk {
+  return (tx) => {
+    tx.add(party.removeMember({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.groupCapId, params.memberId],
+    }));
+  };
+}
+
+export interface SetNameParams {
+  partyId: string;
+  capId: string;
+  name: string;
+  partyPackageId: string;
+}
+
+/** Sets the party's human-readable name. */
+export function setName(params: SetNameParams): TxThunk {
+  return (tx) => {
+    tx.add(party.setName({
+      package: params.partyPackageId,
+      arguments: [params.partyId, params.capId, params.name],
+    }));
+  };
+}

package/src/party/types.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Public, camelCase result types. The mappers in ./internal.ts turn the generated
+// (snake_case, Move-shaped) parse output into these.
+
+export type PartyKind = "individual" | "group";
+
+export interface Party {
+  id: string;
+  kind: PartyKind;
+  /** Human-readable name (not verified). */
+  name: string;
+  /** Member party ids — present only when `kind === "group"`. */
+  members?: string[];
+  /** Unix ms when the party was created. */
+  createdAtMs: number;
+}
+
+export interface Profile {
+  partyId: string;
+  bioShort: string;
+  bioLong?: string;
+  /** ISO 3166-1 alpha-2 country code, e.g. "GB". */
+  country?: string;
+  /** ISO 639-1 language codes, e.g. ["en"]. */
+  languages: string[];
+}
+
+/**
+ * A party's imagery, stored on-chain as a single Walrus quilt. Individual images
+ * (avatar, header, …) are quilt patches addressed by identifier off-chain — see
+ * `mediaUrls` / `MEDIA_IDENTIFIERS` in `extensions/media`.
+ */
+export interface Media {
+  partyId: string;
+  /** Walrus quilt blob id (base64url) holding the party's images. */
+  quiltId: string;
+}
+
+/** A single call-to-action on a party: a labeled external link. Position is priority. */
+export interface Cta {
+  label: string;
+  url: string;
+}
+
+/**
+ * A platform this SDK knows how to build a link for. One key per external
+ * platform, spanning social (`x`, `instagram`, …), music (`spotify`, `bandcamp`,
+ * …), and professional/industry (`website`, `patreon`, …) payloads.
+ */
+export type PlatformKey =
+  // 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";
+
+/**
+ * One external-platform link attached to a party. Only the native identifier
+ * (`value` — a handle, artist id, subdomain, or full URL) is stored on-chain; the
+ * public `url` is rebuilt client-side from it.
+ */
+export interface PlatformLink {
+  platform: PlatformKey;
+  /** The platform-native identifier stored on-chain (handle / id / subdomain / URL). */
+  value: string;
+  /** The public profile URL, rebuilt from `value`. */
+  url: string;
+}

package/src/queries.ts

@@ -12,10 +12,8 @@
 //     they obtained from the chain, so a miss means a broken reference — an
 //     exceptional state, not a normal one.
 //   - Extension dynamic-field readers return `null` — extension data is optional
-//     by design, and "not attached" is a normal, expected state. Those readers
-//     live in `@misofm/sdk` now (`getCompositionCredits`, `getRecordingCredits`,
-//     `getReleaseCredits`, `getReleaseCover`) and re-import {@link isNotFound}
-//     from here to keep one not-found taxonomy across both packages.
+//     by design, and "not attached" is a normal, expected state. Use
+//     `getExtensionField` with the generated BCS codec for the extension.
 // All null-returning readers use {@link isNotFound} to distinguish a missing
 // object from a transport failure (which still throws).
 
@@ -26,7 +24,13 @@ import { deriveObjectID, normalizeSuiAddress } from "@mysten/sui/utils";
 
 import { Composition as CompositionBcs } from "./contracts/miso/composition.ts";
 import { Recording as RecordingBcs } from "./contracts/miso/recording.ts";
-import { Release as ReleaseBcs } from "./contracts/miso/release.ts";
+import {
+  Release as ReleaseBcs,
+  ReleaseRegistry as ReleaseRegistryBcs,
+} from "./contracts/miso/release.ts";
+import { RoyaltyPool as RoyaltyPoolBcs } from "./contracts/royalty_pool/pool.ts";
+import { Stake as RoyaltyStakeBcs } from "./contracts/royalty_pool/stake.ts";
+import { RoutedStake as RoutedStakeBcs } from "./contracts/routed_stake/routed_stake.ts";
 import {
   mapBps,
   mapComposition,
@@ -117,6 +121,35 @@ export function isNotFound(e: unknown): boolean {
 /** Key bytes for Move unit structs (single `0x00` for `dummy_field: bool = false`). */
 const UNIT_STRUCT_KEY_BYTES = new Uint8Array([0x00]);
 
+/** Any generated BCS codec with a `parse` method. */
+export interface BcsParser<T> {
+  parse(bytes: Uint8Array): T;
+}
+
+/** Exhaust every Core owned-object page; cap discovery must not truncate. */
+async function listAllOwnedObjects(
+  client: ClientWithCoreApi,
+  input: Record<string, unknown>,
+): Promise<Array<{ objectId: string; type?: string; json?: unknown }>> {
+  const objects: Array<{ objectId: string; type?: string; json?: unknown }> = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = await (client.core.listOwnedObjects as (args: unknown) => Promise<{
+      objects: Array<{ objectId: string; type?: string; json?: unknown }>;
+      pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };
+      hasNextPage?: boolean;
+      cursor?: string | null;
+    }>)(cursor ? { ...input, cursor } : input);
+    objects.push(...page.objects);
+    cursor = page.pageInfo?.hasNextPage
+      ? page.pageInfo.endCursor
+      : page.hasNextPage
+        ? page.cursor
+        : null;
+  } while (cursor);
+  return objects;
+}
+
 /** Fetches one object's BCS content bytes (or null if absent). */
 async function getContent(
   client: ClientWithCoreApi,
@@ -129,6 +162,168 @@ async function getContent(
   return object.content ?? null;
 }
 
+/**
+ * Fetch and parse an object through the transport-neutral Core API. Object
+ * content is BCS; never pass the full `objectBcs` envelope to a Move codec.
+ */
+export async function getObjectByBcs<T>(
+  client: ClientWithCoreApi,
+  objectId: string,
+  codec: BcsParser<T>,
+): Promise<T> {
+  const content = await getContent(client, objectId);
+  if (!content) throw new Error(`Object not found: ${objectId}`);
+  return codec.parse(content);
+}
+
+export interface ExtensionFieldParams<T> {
+  /** Freshly published package address for the extension. */
+  packageId: string;
+  /** Move module declaring the fieldless `ExtensionKey`. */
+  module: string;
+  /** Generated codec for the dynamic-field value. */
+  codec: BcsParser<T>;
+}
+
+/**
+ * Read an optional first-party extension field from a core object's UID. Every
+ * current extension uses a fieldless `ExtensionKey`, whose BCS is one false
+ * boolean byte. Absence returns `null`; transport errors still propagate.
+ */
+export async function getExtensionField<T>(
+  client: ClientWithCoreApi,
+  parentId: string,
+  params: ExtensionFieldParams<T>,
+): Promise<T | null> {
+  try {
+    const { dynamicField } = await client.core.getDynamicField({
+      parentId,
+      name: {
+        type: `${params.packageId}::${params.module}::ExtensionKey`,
+        bcs: UNIT_STRUCT_KEY_BYTES,
+      },
+    });
+    return params.codec.parse(dynamicField.value.bcs);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+}
+
+export interface ReleaseDspFieldParams<T> {
+  /** Freshly published `release_dsp_link` package address. */
+  packageId: string;
+  /** Numeric DSP discriminator (`DspLinkData::platform()`). */
+  platform: number;
+  /** Generated codec for `DspLinkData` or `PerTrack<Option<DspLinkData>>`. */
+  codec: BcsParser<T>;
+}
+
+async function getReleaseDspField<T>(
+  client: ClientWithCoreApi,
+  releaseId: string,
+  key: "ReleaseLinkKey" | "TrackLinksKey",
+  params: ReleaseDspFieldParams<T>,
+): Promise<T | null> {
+  if (!Number.isInteger(params.platform) || params.platform < 0 || params.platform > 255) {
+    throw new Error("DSP platform must be a u8 discriminator");
+  }
+  try {
+    const { dynamicField } = await client.core.getDynamicField({
+      parentId: releaseId,
+      name: {
+        type: `${params.packageId}::release_dsp_link::${key}`,
+        bcs: Uint8Array.of(params.platform),
+      },
+    });
+    return params.codec.parse(dynamicField.value.bcs);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+}
+
+/** Read a release-level DSP link stored under `ReleaseLinkKey(platform)`. */
+export function getReleaseDspLink<T>(
+  client: ClientWithCoreApi,
+  releaseId: string,
+  params: ReleaseDspFieldParams<T>,
+): Promise<T | null> {
+  return getReleaseDspField(client, releaseId, "ReleaseLinkKey", params);
+}
+
+/** Read the per-track DSP-link array stored under `TrackLinksKey(platform)`. */
+export function getTrackDspLinks<T>(
+  client: ClientWithCoreApi,
+  releaseId: string,
+  params: ReleaseDspFieldParams<T>,
+): Promise<T | null> {
+  return getReleaseDspField(client, releaseId, "TrackLinksKey", params);
+}
+
+// ============================================================================
+// Core registry and generic primitive reads
+// ============================================================================
+
+/** Parse the shared canonical core `miso::release::ReleaseRegistry` by ID. */
+export async function getReleaseRegistryById(
+  client: ClientWithCoreApi,
+  registryId: string,
+) {
+  return getObjectByBcs(client, registryId, ReleaseRegistryBcs);
+}
+
+/** Parse a royalty pool by object ID. Phantom type arguments do not affect BCS. */
+export async function getRoyaltyPoolById(
+  client: ClientWithCoreApi,
+  poolId: string,
+) {
+  return getObjectByBcs(client, poolId, RoyaltyPoolBcs);
+}
+
+/** Parse an owned `Stake<Share>` by object ID. */
+export async function getRoyaltyStakeById(
+  client: ClientWithCoreApi,
+  stakeId: string,
+) {
+  return getObjectByBcs(client, stakeId, RoyaltyStakeBcs);
+}
+
+/** Parse a shared routed stake by object ID. */
+export async function getRoutedStakeById(
+  client: ClientWithCoreApi,
+  routedStakeId: string,
+) {
+  return getObjectByBcs(client, routedStakeId, RoutedStakeBcs);
+}
+
+/** Deterministically derive the royalty-pool ID for a parent and type pair. */
+export function deriveRoyaltyPoolId(
+  parentId: string,
+  shareType: string,
+  currencyType: string,
+  royaltyPoolPackageId: string,
+): string {
+  return deriveObjectID(
+    parentId,
+    `${royaltyPoolPackageId}::pool::RoyaltyPoolKey<${shareType}, ${currencyType}>`,
+    UNIT_STRUCT_KEY_BYTES,
+  );
+}
+
+/** Deterministically derive the routed-stake ID for a parent and stake share. */
+export function deriveRoutedStakeId(
+  parentId: string,
+  stakeShareType: string,
+  routedStakePackageId: string,
+): string {
+  return deriveObjectID(
+    parentId,
+    `${routedStakePackageId}::routed_stake::RoutedStakeKey<${stakeShareType}>`,
+    UNIT_STRUCT_KEY_BYTES,
+  );
+}
+
 // ============================================================================
 // GraphQL discovery queries
 // ============================================================================
@@ -465,10 +660,7 @@ export async function getOwnedCompositionAdminCaps(
   misoPackageId: string,
 ): Promise<CompositionAdminCap[]> {
   const capType = `${misoPackageId}::composition::CompositionAdminCap`;
-  const { objects } = await client.core.listOwnedObjects({
-    owner,
-    type: capType,
-  });
+  const objects = await listAllOwnedObjects(client, { owner, type: capType });
   const caps: CompositionAdminCap[] = [];
   for (const obj of objects) {
     const match = obj.type?.match(/<(.+)>$/);
@@ -590,10 +782,7 @@ export async function getOwnedRecordingAdminCaps(
   misoPackageId: string,
 ): Promise<RecordingAdminCap[]> {
   const capType = `${misoPackageId}::recording::RecordingAdminCap`;
-  const { objects } = await client.core.listOwnedObjects({
-    owner,
-    type: capType,
-  });
+  const objects = await listAllOwnedObjects(client, { owner, type: capType });
   const caps: RecordingAdminCap[] = [];
   for (const obj of objects) {
     const match = obj.type?.match(/<(.+)>$/);
@@ -666,7 +855,7 @@ export async function getOwnedReleaseAdminCaps(
   misoPackageId: string,
 ): Promise<ReleaseAdminCap[]> {
   const capType = `${misoPackageId}::release::ReleaseAdminCap`;
-  const { objects } = await client.core.listOwnedObjects({
+  const objects = await listAllOwnedObjects(client, {
     owner,
     type: capType,
     include: { json: true },
@@ -724,7 +913,7 @@ export async function getShareCurrencyTreasuryCap(
   shareType: string,
   owner: string,
 ): Promise<string> {
-  const { objects } = await client.core.listOwnedObjects({
+  const objects = await listAllOwnedObjects(client, {
     owner,
     type: `0x2::coin::TreasuryCap<${shareType}>`,
   });
@@ -766,15 +955,28 @@ async function addressOfRecordingWithShareType(
   misoPackageId: string,
   shareType: string,
 ): Promise<string | null> {
-  const result = await client.query({
-    query: AddressesAndTypesByTypeQuery,
-    variables: { type: `${misoPackageId}::recording::Recording` },
-  });
-  for (const node of result.data?.objects?.nodes ?? []) {
-    const repr = node?.asMoveObject?.contents?.type?.repr;
-    if (!repr || !node.address) continue;
-    const [recordingShareType] = extractTypeParams2(repr);
-    if (recordingShareType === shareType) return node.address;
-  }
+  let cursor: string | null | undefined;
+  do {
+    const result = await client.query<
+      { objects?: WorkAddressConnection | null },
+      { type: string; cursor?: string | null }
+    >({
+      query: `query RecordingAddress($type: String!, $cursor: String) {
+        objects(first: 50, after: $cursor, filter: { type: $type }) {
+          pageInfo { hasNextPage endCursor }
+          nodes { address asMoveObject { contents { type { repr } } } }
+        }
+      }`,
+      variables: { type: `${misoPackageId}::recording::Recording`, cursor },
+    });
+    const page = result.data?.objects;
+    for (const node of page?.nodes ?? []) {
+      const repr = node?.asMoveObject?.contents?.type?.repr;
+      if (!repr || !node.address) continue;
+      const [recordingShareType] = extractTypeParams2(repr);
+      if (recordingShareType === shareType) return node.address;
+    }
+    cursor = page?.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;
+  } while (cursor);
   return null;
 }