@misonetwork/sdk 0.8.0 → 0.9.0

package/src/party/internal.ts

@@ -0,0 +1,119 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The single boundary between generated BCS-parse output (snake_case, Move-shaped)
+// and the public camelCase types.
+
+import { bcs } from "@mysten/sui/bcs";
+import { fromBase64, toBase64 } from "@mysten/sui/utils";
+import type { Cta, Media, Party, Profile } from "./types.ts";
+
+const u256 = bcs.u256();
+
+function toBase64Url(bytes: Uint8Array): string {
+  return toBase64(bytes).replace(/=*$/, "").replaceAll("+", "-").replaceAll("/", "_");
+}
+
+function fromBase64Url(value: string): Uint8Array {
+  let base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+  while (base64.length % 4) base64 += "=";
+  return fromBase64(base64);
+}
+
+export function u256ToB64Url(value: bigint | string): string {
+  return toBase64Url(u256.serialize(BigInt(value)).toBytes());
+}
+
+export function b64UrlToU256(value: string): string {
+  return u256.parse(fromBase64Url(value)).toString();
+}
+
+/** `CountryCode` / `LanguageCode` are single-field tuple structs → parse to a 1-element array. */
+function unwrapCode(v: unknown): string | undefined {
+  if (v == null) return undefined;
+  return Array.isArray(v) ? (v[0] as string) : (v as string);
+}
+
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+export function mapProfile(partyId: string, d: any): Profile {
+  return {
+    partyId,
+    bioShort: d.bio_short,
+    bioLong: d.bio_long ?? undefined,
+    country: unwrapCode(d.country),
+    languages: Array.isArray(d.languages)
+      ? d.languages.map((l: unknown) => unwrapCode(l)).filter((c: unknown): c is string => Boolean(c))
+      : [],
+  };
+}
+
+// On-chain `Media` holds the quilt blob id as a u256 (decimal string from BCS);
+// expose it in Walrus's base64url form so callers can build aggregator URLs.
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+export function mapMedia(partyId: string, d: any): Media {
+  return { partyId, quiltId: u256ToB64Url(String(d.quilt)) };
+}
+
+// The display name of each canonical `ArtistRole` variant (matches Move's
+// `role_name` — note `Dj` → "DJ"). `Custom` carries its own string.
+const CANONICAL_ROLE_NAMES: Record<string, string> = {
+  Artist: "Artist",
+  Producer: "Producer",
+  Dj: "DJ",
+  Composer: "Composer",
+  Songwriter: "Songwriter",
+  Band: "Band",
+  Label: "Label",
+  Collective: "Collective",
+};
+
+/** One parsed `ArtistRole` enum value → its display name (`Custom` → its string). */
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+function roleName(r: any): string {
+  if (r?.$kind === "Custom") return String(r.Custom ?? r.value ?? "");
+  return CANONICAL_ROLE_NAMES[r?.$kind] ?? String(r?.$kind ?? "");
+}
+
+/** A party's `VecSet<ArtistRole>` → role display names. */
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+export function mapRoles(d: any): string[] {
+  const contents = Array.isArray(d) ? d : d?.contents ?? d?.roles?.contents ?? [];
+  return (Array.isArray(contents) ? contents : []).map(roleName);
+}
+
+/** A party's `VecSet<String>` tag set → tag strings. */
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+export function mapTags(d: any): string[] {
+  const contents = Array.isArray(d) ? d : d?.contents ?? d?.tags?.contents ?? [];
+  return (Array.isArray(contents) ? contents : []).map((t: unknown) => String(t));
+}
+
+/** A party's `VecSet<ID>` genre set → genre object id strings. */
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+export function mapGenres(d: any): string[] {
+  const contents = Array.isArray(d) ? d : d?.contents ?? d?.genres?.contents ?? [];
+  return (Array.isArray(contents) ? contents : []).map((g: unknown) => String(g));
+}
+
+/** A party's `vector<Cta>` → CTA entries, preserving order (position is priority). */
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+export function mapCtas(d: any): Cta[] {
+  return (Array.isArray(d) ? d : []).map((c: any) => ({ label: String(c.label), url: String(c.url) }));
+}
+
+// deno-lint-ignore no-explicit-any -- generated parse output is loosely typed
+export function mapParty(id: string, d: any): Party {
+  const kind = d.kind;
+  const createdAtMs = Number(d.created_at_ms);
+  // PartyKind is `Individual | Group(VecSet<ID>)`. The enum parses to
+  // `{ $kind, Individual? , Group? }`; Group's payload is a VecSet `{ contents }`.
+  const groupPayload = kind?.Group ?? (kind?.$kind === "Group" ? kind.value : undefined);
+  if (groupPayload !== undefined) {
+    const contents = groupPayload?.contents ?? groupPayload ?? [];
+    const members = (Array.isArray(contents) ? contents : []).map((m: unknown) =>
+      typeof m === "string" ? m : (m as { id?: string })?.id ?? String(m),
+    );
+    return { id, kind: "group", name: d.name, members, createdAtMs };
+  }
+  return { id, kind: "individual", name: d.name, createdAtMs };
+}

package/src/party/queries.ts

@@ -0,0 +1,303 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Typed reads: fetch an on-chain object (or dynamic field) via the Core API, BCS-parse
+// it through the generated struct, and map to the public camelCase types.
+
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import { deriveDynamicFieldID, deriveObjectID } from "@mysten/sui/utils";
+import { bcs } from "@mysten/sui/bcs";
+import { fromBase64 } from "@mysten/sui/utils";
+import {
+  MembershipKey as MembershipKeyBcs,
+  Party as PartyBcs,
+  PendingInviteKey as PendingInviteKeyBcs,
+  PendingMembershipKey as PendingMembershipKeyBcs,
+} from "../contracts/miso_party/party.ts";
+import { Profile as ProfileBcs, ProfileKey as ProfileKeyBcs } from "../contracts/party_profile/party_profile.ts";
+import { Media as MediaBcs, MediaKey as MediaKeyBcs } from "../contracts/party_media/party_media.ts";
+import { ArtistRole as ArtistRoleBcs, RolesKey as RolesKeyBcs } from "../contracts/party_roles/party_roles.ts";
+import { TagsKey as TagsKeyBcs } from "../contracts/party_tags/party_tags.ts";
+import { GenresKey as GenresKeyBcs } from "../contracts/party_genre/party_genre.ts";
+import { Cta as CtaBcs, CtasKey as CtasKeyBcs } from "../contracts/party_cta/party_cta.ts";
+import { mapCtas, mapGenres, mapMedia, mapParty, mapProfile, mapRoles, mapTags } from "./internal.ts";
+import { buildLink, platformForDataType } from "./extensions/links.ts";
+import type { Cta, Media, Party, PlatformLink, Profile } from "./types.ts";
+
+/** True for the Core API's "object does not exist" error (a missing dynamic field). */
+function isNotFound(e: unknown): boolean {
+  const msg = e instanceof Error ? e.message : String(e);
+  return /not\s*found|does not exist|no object/i.test(msg);
+}
+
+// A missing object (e.g. an unset profile/media dynamic field) surfaces as a
+// thrown "not found" from the Core API, not an empty result — treat it as null
+// so optional extensions read cleanly.
+async function getContent(client: ClientWithCoreApi, objectId: string): Promise<Uint8Array | null> {
+  try {
+    const { object } = await client.core.getObject({ objectId, include: { content: true } });
+    return object?.content ?? null;
+  } catch (e) {
+    if (isNotFound(e)) return null;
+    throw e;
+  }
+}
+
+/** Fetches and parses a shared `Party` object. */
+export async function getPartyById(client: ClientWithCoreApi, partyId: string): Promise<Party> {
+  const content = await getContent(client, partyId);
+  if (!content) throw new Error(`Party not found: ${partyId}`);
+  return mapParty(partyId, PartyBcs.parse(content));
+}
+
+/** Fetches and parses multiple shared `Party` objects in one Core request. */
+export async function getPartiesByIds(
+  client: ClientWithCoreApi,
+  partyIds: readonly string[],
+): Promise<Partial<Record<string, Party>>> {
+  if (partyIds.length === 0) return {};
+  const { objects } = await client.core.getObjects({
+    objectIds: [...new Set(partyIds)],
+    include: { content: true },
+  });
+  const parties: Partial<Record<string, Party>> = {};
+  for (const obj of objects) {
+    if (obj instanceof Error) continue;
+    parties[obj.objectId] = mapParty(obj.objectId, PartyBcs.parse(obj.content));
+  }
+  return parties;
+}
+
+/** Derives a party's `PartyAdminCap` id (it is a `derived_object` off the party UID). */
+export function derivePartyAdminCapId(partyId: string, partyPackageId: string): string {
+  return deriveObjectID(
+    partyId,
+    `${partyPackageId}::party::PartyAdminCapKey`,
+    bcs.Address.serialize(partyId).toBytes(),
+  );
+}
+
+// The profile is a dynamic field on the party UID under an empty `ProfileKey()`
+// (Move's implicit `dummy_field: bool` → one zero byte).
+const ProfileField = bcs.struct("Field", { id: bcs.Address, name: ProfileKeyBcs, value: ProfileBcs });
+const PROFILE_KEY_BYTES = ProfileKeyBcs.serialize([false]).toBytes();
+
+/** Fetches a party's profile, or null if none is set. */
+export async function getProfile(
+  client: ClientWithCoreApi,
+  partyId: string,
+  partyProfilePackageId: string,
+): Promise<Profile | null> {
+  const fieldId = deriveDynamicFieldID(
+    partyId,
+    `${partyProfilePackageId}::party_profile::ProfileKey`,
+    PROFILE_KEY_BYTES,
+  );
+  const content = await getContent(client, fieldId);
+  if (!content) return null;
+  return mapProfile(partyId, ProfileField.parse(content).value);
+}
+
+// Media is a dynamic field on the party UID under an empty `MediaKey()` (same
+// implicit `dummy_field: bool` → one zero byte as the profile key).
+const MediaField = bcs.struct("Field", { id: bcs.Address, name: MediaKeyBcs, value: MediaBcs });
+const MEDIA_KEY_BYTES = MediaKeyBcs.serialize([false]).toBytes();
+
+/** Fetches a party's media (avatar + header), or null if none is set. */
+export async function getMedia(
+  client: ClientWithCoreApi,
+  partyId: string,
+  partyMediaPackageId: string,
+): Promise<Media | null> {
+  const fieldId = deriveDynamicFieldID(
+    partyId,
+    `${partyMediaPackageId}::party_media::MediaKey`,
+    MEDIA_KEY_BYTES,
+  );
+  const content = await getContent(client, fieldId);
+  if (!content) return null;
+  return mapMedia(partyId, MediaField.parse(content).value);
+}
+
+// === Collection extension reads (roles / tags / genres / ctas) ===
+//
+// Each is a single dynamic field on the party UID under an empty positional key
+// (Move's implicit `dummy_field: bool` → one zero byte, same as the profile key).
+
+const ROLES_KEY_BYTES = RolesKeyBcs.serialize([false]).toBytes();
+const RolesField = bcs.struct("Field", { id: bcs.Address, name: RolesKeyBcs, value: bcs.vector(ArtistRoleBcs) });
+
+/** The party's artist-type roles (display names), or `[]` if none are set. */
+export async function getRoles(
+  client: ClientWithCoreApi,
+  partyId: string,
+  partyRolesPackageId: string,
+): Promise<string[]> {
+  const fieldId = deriveDynamicFieldID(partyId, `${partyRolesPackageId}::party_roles::RolesKey`, ROLES_KEY_BYTES);
+  const content = await getContent(client, fieldId);
+  if (!content) return [];
+  return mapRoles(RolesField.parse(content).value);
+}
+
+const TAGS_KEY_BYTES = TagsKeyBcs.serialize([false]).toBytes();
+const TagsField = bcs.struct("Field", { id: bcs.Address, name: TagsKeyBcs, value: bcs.vector(bcs.string()) });
+
+/** The party's free-form tags, or `[]` if none are set. */
+export async function getTags(
+  client: ClientWithCoreApi,
+  partyId: string,
+  partyTagsPackageId: string,
+): Promise<string[]> {
+  const fieldId = deriveDynamicFieldID(partyId, `${partyTagsPackageId}::party_tags::TagsKey`, TAGS_KEY_BYTES);
+  const content = await getContent(client, fieldId);
+  if (!content) return [];
+  return mapTags(TagsField.parse(content).value);
+}
+
+const GENRES_KEY_BYTES = GenresKeyBcs.serialize([false]).toBytes();
+const GenresField = bcs.struct("Field", { id: bcs.Address, name: GenresKeyBcs, value: bcs.vector(bcs.Address) });
+
+/** The party's genre object ids, or `[]` if none are set. */
+export async function getGenres(
+  client: ClientWithCoreApi,
+  partyId: string,
+  partyGenrePackageId: string,
+): Promise<string[]> {
+  const fieldId = deriveDynamicFieldID(partyId, `${partyGenrePackageId}::party_genre::GenresKey`, GENRES_KEY_BYTES);
+  const content = await getContent(client, fieldId);
+  if (!content) return [];
+  return mapGenres(GenresField.parse(content).value);
+}
+
+const CTAS_KEY_BYTES = CtasKeyBcs.serialize([false]).toBytes();
+// The CTA field's value is a bare `vector<Cta>` (not a wrapper struct).
+const CtasField = bcs.struct("Field", { id: bcs.Address, name: CtasKeyBcs, value: bcs.vector(CtaBcs) });
+
+/** The party's ordered CTA list (position is priority), or `[]` if none is set. */
+export async function getCtas(
+  client: ClientWithCoreApi,
+  partyId: string,
+  partyCtaPackageId: string,
+): Promise<Cta[]> {
+  const fieldId = deriveDynamicFieldID(partyId, `${partyCtaPackageId}::party_cta::CtasKey`, CTAS_KEY_BYTES);
+  const content = await getContent(client, fieldId);
+  if (!content) return [];
+  return mapCtas(CtasField.parse(content).value);
+}
+
+// === Platform-link reads ===
+//
+// Each platform is an independent `PlatformLink<Data>` dynamic field keyed by
+// `platform_link::PlatformLinkKey<Data>`. There is no single key to derive, so
+// enumerate the party's dynamic fields and pick out the platform-link ones,
+// identifying the platform from the `Data` type argument. Every payload `Data`
+// type is a single-`String` newtype, so `PlatformLink<Data>` serializes exactly
+// as one BCS string — parse the field value as such.
+const PlatformLinkField = bcs.struct("Field", { id: bcs.Address, name: bcs.bool(), value: bcs.string() });
+const PLATFORM_LINK_KEY_RE = /::platform_link::PlatformLinkKey<(.+)>$/;
+
+/** All external-platform links attached to a party (social, music, professional). */
+export async function getLinks(client: ClientWithCoreApi, partyId: string): Promise<PlatformLink[]> {
+  const links: PlatformLink[] = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = await client.core.listDynamicFields({ parentId: partyId, cursor: cursor ?? undefined });
+    for (const f of page.dynamicFields) {
+      if (typeof f.name?.type !== "string") continue;
+      const match = f.name.type.match(PLATFORM_LINK_KEY_RE);
+      const dataType = match?.[1];
+      if (!dataType) continue;
+      const platform = platformForDataType(dataType);
+      if (!platform) continue;
+      const content = await getContent(client, f.fieldId);
+      if (!content) continue;
+      links.push(buildLink(platform, PlatformLinkField.parse(content).value));
+    }
+    cursor = page.hasNextPage ? page.cursor : null;
+  } while (cursor);
+  return links;
+}
+
+// === Group membership reads ===
+
+/** Normalizes a dynamic-field key's BCS bytes (Uint8Array or base64 string). */
+function keyBytes(bcs: unknown): Uint8Array {
+  return typeof bcs === "string" ? fromBase64(bcs) : (bcs as Uint8Array);
+}
+
+/**
+ * The group ids a party currently belongs to, read from its `MembershipKey`
+ * dynamic fields (the member-side record). No indexer required.
+ */
+export async function getMemberships(client: ClientWithCoreApi, partyId: string): Promise<string[]> {
+  const groups: string[] = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = await client.core.listDynamicFields({ parentId: partyId, cursor: cursor ?? undefined });
+    for (const f of page.dynamicFields) {
+      if (typeof f.name?.type === "string" && f.name.type.endsWith("::party::MembershipKey") && f.name.bcs != null) {
+        const [groupId] = MembershipKeyBcs.parse(keyBytes(f.name.bcs));
+        groups.push(String(groupId));
+      }
+    }
+    cursor = page.hasNextPage ? page.cursor : null;
+  } while (cursor);
+  return groups;
+}
+
+/** The member ids invited to a group but not yet accepted (its `PendingInviteKey` fields). */
+export async function getPendingInvites(client: ClientWithCoreApi, groupId: string): Promise<string[]> {
+  const members: string[] = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = await client.core.listDynamicFields({ parentId: groupId, cursor: cursor ?? undefined });
+    for (const f of page.dynamicFields) {
+      if (typeof f.name?.type === "string" && f.name.type.endsWith("::party::PendingInviteKey") && f.name.bcs != null) {
+        const [memberId] = PendingInviteKeyBcs.parse(keyBytes(f.name.bcs));
+        members.push(String(memberId));
+      }
+    }
+    cursor = page.hasNextPage ? page.cursor : null;
+  } while (cursor);
+  return members;
+}
+
+/**
+ * The group ids that have invited a party but are still awaiting its response.
+ * This reads the member-side `PendingMembershipKey` inbox index, so it only
+ * enumerates the target party's dynamic fields.
+ */
+export async function getPendingMemberships(client: ClientWithCoreApi, partyId: string): Promise<string[]> {
+  const groups: string[] = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = await client.core.listDynamicFields({ parentId: partyId, cursor: cursor ?? undefined });
+    for (const f of page.dynamicFields) {
+      if (
+        typeof f.name?.type === "string" &&
+        f.name.type.endsWith("::party::PendingMembershipKey") &&
+        f.name.bcs != null
+      ) {
+        const [groupId] = PendingMembershipKeyBcs.parse(keyBytes(f.name.bcs));
+        groups.push(String(groupId));
+      }
+    }
+    cursor = page.hasNextPage ? page.cursor : null;
+  } while (cursor);
+  return groups;
+}
+
+/** Whether `memberId` currently holds a membership record for `groupId`. */
+export async function isMember(
+  client: ClientWithCoreApi,
+  memberId: string,
+  groupId: string,
+  partyPackageId: string,
+): Promise<boolean> {
+  const fieldId = deriveDynamicFieldID(
+    memberId,
+    `${partyPackageId}::party::MembershipKey`,
+    MembershipKeyBcs.serialize([groupId]).toBytes(),
+  );
+  return (await getContent(client, fieldId)) !== null;
+}

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;
+}