@misonetwork/sdk 0.7.0 → 0.9.0

package/src/party/extensions/profile.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The `party_profile` extension: an editable identity card attached to a Party.
+// The builders hide the Option/vector plumbing and construct the validated
+// `CountryCode` / `LanguageCode` values from raw ISO codes.
+
+import * as profileMod from "../../contracts/party_profile/party_profile.ts";
+import type { TxThunk } from "../transactions.ts";
+
+const OPTION_NONE = "0x1::option::none";
+const OPTION_SOME = "0x1::option::some";
+
+export interface SetProfileParams {
+  partyId: string;
+  capId: 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", "ja"]. */
+  languages?: string[];
+  partyProfilePackageId: string;
+  countryCodePackageId: string;
+  languageCodePackageId: string;
+}
+
+/** Sets (creates or replaces) a party's whole profile. */
+export function setProfile(params: SetProfileParams): TxThunk {
+  return (tx) => {
+    const ccType = `${params.countryCodePackageId}::country_code::CountryCode`;
+    const country = params.country
+      ? tx.moveCall({
+          target: OPTION_SOME,
+          typeArguments: [ccType],
+          arguments: [
+            tx.moveCall({
+              target: `${params.countryCodePackageId}::country_code::new`,
+              arguments: [tx.pure.string(params.country)],
+            }),
+          ],
+        })
+      : tx.moveCall({ target: OPTION_NONE, typeArguments: [ccType], arguments: [] });
+
+    const lcType = `${params.languageCodePackageId}::language_code::LanguageCode`;
+    const languages = tx.makeMoveVec({
+      type: lcType,
+      elements: (params.languages ?? []).map((code) =>
+        tx.moveCall({
+          target: `${params.languageCodePackageId}::language_code::new`,
+          arguments: [tx.pure.string(code)],
+        }),
+      ),
+    });
+
+    tx.add(
+      profileMod.setProfile({
+        package: params.partyProfilePackageId,
+        arguments: [params.partyId, params.capId, params.bioShort, params.bioLong ?? null, country, languages],
+      }),
+    );
+  };
+}
+
+export interface ClearProfileParams {
+  partyId: string;
+  capId: string;
+  partyProfilePackageId: string;
+}
+
+/** Removes a party's profile. No-op on-chain if none is set. */
+export function clearProfile(params: ClearProfileParams): TxThunk {
+  return (tx) => {
+    tx.add(
+      profileMod.clearProfile({
+        package: params.partyProfilePackageId,
+        arguments: [params.partyId, params.capId],
+      }),
+    );
+  };
+}

package/src/party/extensions/roles.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The `party_roles` extension: the artist-type roles a party holds (artist,
+// producer, DJ, …), a `VecSet<ArtistRole>` on the party. Roles are a closed enum
+// with a `Custom(String)` escape hatch; the builders construct the right
+// `ArtistRole` value via its constructor move-call, then add/remove it.
+
+import * as rolesMod from "../../contracts/party_roles/party_roles.ts";
+import type { TxThunk } from "../transactions.ts";
+
+/** The canonical role variants (a fixed, typo-free set the frontend can render). */
+export type CanonicalRole =
+  | "artist"
+  | "producer"
+  | "dj"
+  | "composer"
+  | "songwriter"
+  | "band"
+  | "label"
+  | "collective";
+
+/**
+ * A role to add/remove: a canonical variant, or a user-defined `custom` name.
+ * Prefer a canonical variant when one fits.
+ */
+export type Role = { kind: CanonicalRole } | { kind: "custom"; name: string };
+
+// Canonical `kind` → the generated constructor function name (all take no args).
+const CANONICAL_CTORS = {
+  artist: rolesMod.artist,
+  producer: rolesMod.producer,
+  dj: rolesMod.dj,
+  composer: rolesMod.composer,
+  songwriter: rolesMod.songwriter,
+  band: rolesMod.band,
+  label: rolesMod.label,
+  collective: rolesMod.collective,
+} as const;
+
+/** Builds the `ArtistRole` value for a role via its constructor move-call. */
+function buildRole(tx: Parameters<TxThunk>[0], role: Role, pkg: string) {
+  if (role.kind === "custom") {
+    return tx.add(rolesMod.custom({ package: pkg, arguments: [role.name] }));
+  }
+  return tx.add(CANONICAL_CTORS[role.kind]({ package: pkg }));
+}
+
+export interface AddRoleParams {
+  partyId: string;
+  capId: string;
+  role: Role;
+  partyRolesPackageId: string;
+}
+
+/** Adds a role to the party. Aborts on-chain if already held or the max is reached. */
+export function addRole(params: AddRoleParams): TxThunk {
+  return (tx) => {
+    const role = buildRole(tx, params.role, params.partyRolesPackageId);
+    tx.add(
+      rolesMod.addRole({ package: params.partyRolesPackageId, arguments: [params.partyId, params.capId, role] }),
+    );
+  };
+}
+
+export interface RemoveRoleParams {
+  partyId: string;
+  capId: string;
+  role: Role;
+  partyRolesPackageId: string;
+}
+
+/** Removes a role from the party. Aborts on-chain if not held. */
+export function removeRole(params: RemoveRoleParams): TxThunk {
+  return (tx) => {
+    const role = buildRole(tx, params.role, params.partyRolesPackageId);
+    tx.add(
+      rolesMod.removeRole({ package: params.partyRolesPackageId, arguments: [params.partyId, params.capId, role] }),
+    );
+  };
+}
+
+export interface ClearRolesParams {
+  partyId: string;
+  capId: string;
+  partyRolesPackageId: string;
+}
+
+/** Removes the party's entire role set. No-op on-chain if none is set. */
+export function clearRoles(params: ClearRolesParams): TxThunk {
+  return (tx) => {
+    tx.add(rolesMod.clearRoles({ package: params.partyRolesPackageId, arguments: [params.partyId, params.capId] }));
+  };
+}

package/src/party/extensions/tags.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The `party_tags` extension: free-form descriptor tags on a party, a
+// `VecSet<String>`. Tags are stored exactly as given; normalization is a client
+// concern.
+
+import * as tagsMod from "../../contracts/party_tags/party_tags.ts";
+import type { TxThunk } from "../transactions.ts";
+
+export interface AddTagParams {
+  partyId: string;
+  capId: string;
+  tag: string;
+  partyTagsPackageId: string;
+}
+
+/** Adds a tag to the party. Aborts on-chain if empty, too long, duplicate, or the max is reached. */
+export function addTag(params: AddTagParams): TxThunk {
+  return (tx) => {
+    tx.add(
+      tagsMod.addTag({ package: params.partyTagsPackageId, arguments: [params.partyId, params.capId, params.tag] }),
+    );
+  };
+}
+
+export interface RemoveTagParams {
+  partyId: string;
+  capId: string;
+  tag: string;
+  partyTagsPackageId: string;
+}
+
+/** Removes a tag from the party. Aborts on-chain if not present. */
+export function removeTag(params: RemoveTagParams): TxThunk {
+  return (tx) => {
+    tx.add(
+      tagsMod.removeTag({ package: params.partyTagsPackageId, arguments: [params.partyId, params.capId, params.tag] }),
+    );
+  };
+}
+
+export interface ClearTagsParams {
+  partyId: string;
+  capId: string;
+  partyTagsPackageId: string;
+}
+
+/** Removes the party's entire tag set. No-op on-chain if none is set. */
+export function clearTags(params: ClearTagsParams): TxThunk {
+  return (tx) => {
+    tx.add(tagsMod.clearTags({ package: params.partyTagsPackageId, arguments: [params.partyId, params.capId] }));
+  };
+}

package/src/party/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./types.ts";
+export * from "./transactions.ts";
+export * from "./queries.ts";
+export * from "./client.ts";
+export * from "./extensions/profile.ts";
+export * from "./extensions/media.ts";
+export * from "./extensions/roles.ts";
+export * from "./extensions/tags.ts";
+export * from "./extensions/genres.ts";
+export * from "./extensions/ctas.ts";
+export * from "./extensions/links.ts";

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