@misofm/platform 0.24.0 → 0.25.0

package/src/party/client.ts

@@ -0,0 +1,268 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Party EXTENSIONS bound to one `PartyExtensionsDeployment`, wrapping a
+// `PartyosClient` for the Party core. Consumers reach this through
+// `client.miso.party`.
+
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import type { Party, PartyosClient } from "@misofm/partyos";
+import type { PartyExtensionsDeployment } from "../deployments.ts";
+import * as queries from "./queries.ts";
+import * as profileExt from "./extensions/profile.ts";
+import * as mediaExt from "./extensions/media.ts";
+import * as rolesExt from "./extensions/roles.ts";
+import * as tagsExt from "./extensions/tags.ts";
+import * as genresExt from "./extensions/genres.ts";
+import * as ctasExt from "./extensions/ctas.ts";
+import * as linksExt from "./extensions/links.ts";
+import type { Cta, Media, PlatformKey, PlatformLink, Profile } from "./types.ts";
+import * as profileMod from "../contracts/party_profile/party_profile.ts";
+import * as mediaMod from "../contracts/party_media/party_media.ts";
+import * as rolesMod from "../contracts/party_roles/party_roles.ts";
+import * as tagsMod from "../contracts/party_tags/party_tags.ts";
+import * as ctaMod from "../contracts/party_cta/party_cta.ts";
+import * as genreMod from "../contracts/party_genre/party_genre.ts";
+import * as platformLinkMod from "../contracts/party_platform_link/party_platform_link.ts";
+import * as socialMod from "../contracts/party_social/party_social.ts";
+import * as musicMod from "../contracts/party_music/party_music.ts";
+import * as proLinkMod from "../contracts/party_pro_link/party_pro_link.ts";
+
+type BoundMoveFunction<F> = F extends (options: infer Options) => infer Result
+  ? Options extends { package?: unknown }
+    ? (options: Omit<Options, "package">) => Result
+    : F
+  : F;
+type BoundModule<M extends object, Removed extends PropertyKey> = {
+  [Key in Exclude<keyof M, Removed>]: BoundMoveFunction<M[Key]>;
+};
+
+/** Defaults generated calls to one package and removes reference-returning calls. */
+function bindModulePackage<M extends object, K extends readonly (keyof M)[]>(
+  mod: M,
+  pkg: string,
+  unavailable: K = [] as unknown as K,
+): BoundModule<M, K[number]> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries({ ...mod })) {
+    if ((unavailable as readonly string[]).includes(key)) continue;
+    out[key] =
+      typeof value === "function"
+        ? (options: { package?: string }) => (value as (o: unknown) => unknown)({ package: pkg, ...options })
+        : value;
+  }
+  return out as BoundModule<M, K[number]>;
+}
+
+/**
+ * Package-bound Party client exposed at `client.miso.party`. Wraps a
+ * `PartyosClient` for the Party core (identity, admin caps, group membership)
+ * and adds the first-party extensions (profile, media, roles, tags, genres,
+ * CTAs, platform links) this package owns.
+ */
+export class PartyPlatformClient {
+  #client: ClientWithCoreApi;
+  #core: PartyosClient;
+  #profilePkg: string;
+  #countryCodePkg: string;
+  #languageCodePkg: string;
+  #mediaPkg: string;
+  #rolesPkg: string;
+  #tagsPkg: string;
+  #partyGenrePkg: string;
+  #ctaPkg: string;
+  #platformLinkPkg: string;
+  #socialPkg: string;
+  #musicPkg: string;
+  #proLinkPkg: string;
+
+  constructor(client: ClientWithCoreApi, core: PartyosClient, extensions: PartyExtensionsDeployment) {
+    this.#client = client;
+    this.#core = core;
+    this.#profilePkg = extensions.partyProfile;
+    this.#countryCodePkg = extensions.countryCode;
+    this.#languageCodePkg = extensions.languageCode;
+    this.#mediaPkg = extensions.partyMedia;
+    this.#rolesPkg = extensions.partyRoles;
+    this.#tagsPkg = extensions.partyTags;
+    this.#partyGenrePkg = extensions.partyGenre;
+    this.#ctaPkg = extensions.partyCta;
+    this.#platformLinkPkg = extensions.partyPlatformLink;
+    this.#socialPkg = extensions.partySocial;
+    this.#musicPkg = extensions.partyMusic;
+    this.#proLinkPkg = extensions.partyProLink;
+  }
+
+  /** The wrapped Party-core client (identity, admin caps, group membership). */
+  get core(): PartyosClient {
+    return this.#core;
+  }
+
+  // === Core (delegated to `PartyosClient`) ===
+
+  async getPartyById(partyId: string): Promise<Party> {
+    return this.#core.getPartyById(partyId);
+  }
+  async getPartiesByIds(partyIds: readonly string[]): Promise<Partial<Record<string, Party>>> {
+    return this.#core.getPartiesByIds(partyIds);
+  }
+  derivePartyAdminCapId(partyId: string): string {
+    return this.#core.derivePartyAdminCapId(partyId);
+  }
+  /** Group ids a party belongs to (member-side membership records). */
+  async getMemberships(partyId: string): Promise<string[]> {
+    return this.#core.getMemberships(partyId);
+  }
+  /** Member ids invited to a group but not yet accepted. */
+  async getPendingInvites(groupId: string): Promise<string[]> {
+    return this.#core.getPendingInvites(groupId);
+  }
+  /** Group ids that have invited this party but are awaiting its response. */
+  async getPendingMemberships(partyId: string): Promise<string[]> {
+    return this.#core.getPendingMemberships(partyId);
+  }
+  /** Whether a party is a member of a group. */
+  async isMember(memberId: string, groupId: string): Promise<boolean> {
+    return this.#core.isMember(memberId, groupId);
+  }
+
+  // === Extension queries ===
+
+  async getProfile(partyId: string): Promise<Profile | null> {
+    return queries.getProfile(this.#client, partyId, this.#profilePkg);
+  }
+  async getMedia(partyId: string): Promise<Media | null> {
+    return queries.getMedia(this.#client, partyId, this.#mediaPkg);
+  }
+  /** The party's artist-type roles (display names). */
+  async getRoles(partyId: string): Promise<string[]> {
+    return queries.getRoles(this.#client, partyId, this.#rolesPkg);
+  }
+  /** The party's free-form tags. */
+  async getTags(partyId: string): Promise<string[]> {
+    return queries.getTags(this.#client, partyId, this.#tagsPkg);
+  }
+  /** The party's genre object ids. */
+  async getGenres(partyId: string): Promise<string[]> {
+    return queries.getGenres(this.#client, partyId, this.#partyGenrePkg);
+  }
+  /** The party's ordered CTA list (position is priority). */
+  async getCtas(partyId: string): Promise<Cta[]> {
+    return queries.getCtas(this.#client, partyId, this.#ctaPkg);
+  }
+  /** All external-platform links attached to the party (social, music, professional). */
+  async getLinks(partyId: string): Promise<PlatformLink[]> {
+    return queries.getLinks(this.#client, partyId);
+  }
+
+  // === Transaction builders (thunks; package ids bound from the client) ===
+
+  get tx() {
+    const profilePkg = this.#profilePkg;
+    const cc = this.#countryCodePkg;
+    const lc = this.#languageCodePkg;
+    const mediaPkg = this.#mediaPkg;
+    const rolesPkg = this.#rolesPkg;
+    const tagsPkg = this.#tagsPkg;
+    const ctaPkg = this.#ctaPkg;
+    const partyGenrePkg = this.#partyGenrePkg;
+    const linkIds: linksExt.LinkPackageIds = {
+      partyPlatformLinkPackageId: this.#platformLinkPkg,
+      partySocialPackageId: this.#socialPkg,
+      partyMusicPackageId: this.#musicPkg,
+      partyProLinkPackageId: this.#proLinkPkg,
+    };
+    return {
+      // Party core builders — delegated straight from `PartyosClient`.
+      ...this.#core.tx,
+      setProfile: (
+        p: Omit<profileExt.SetProfileParams, "partyProfilePackageId" | "countryCodePackageId" | "languageCodePackageId">,
+      ) =>
+        profileExt.setProfile({
+          ...p,
+          partyProfilePackageId: profilePkg,
+          countryCodePackageId: cc,
+          languageCodePackageId: lc,
+        }),
+      clearProfile: (p: Omit<profileExt.ClearProfileParams, "partyProfilePackageId">) =>
+        profileExt.clearProfile({ ...p, partyProfilePackageId: profilePkg }),
+      setMedia: (p: Omit<mediaExt.SetMediaParams, "partyMediaPackageId">) =>
+        mediaExt.setMedia({ ...p, partyMediaPackageId: mediaPkg }),
+      clearMedia: (p: Omit<mediaExt.ClearMediaParams, "partyMediaPackageId">) =>
+        mediaExt.clearMedia({ ...p, partyMediaPackageId: mediaPkg }),
+      // Roles
+      addRole: (p: Omit<rolesExt.AddRoleParams, "partyRolesPackageId">) =>
+        rolesExt.addRole({ ...p, partyRolesPackageId: rolesPkg }),
+      removeRole: (p: Omit<rolesExt.RemoveRoleParams, "partyRolesPackageId">) =>
+        rolesExt.removeRole({ ...p, partyRolesPackageId: rolesPkg }),
+      clearRoles: (p: Omit<rolesExt.ClearRolesParams, "partyRolesPackageId">) =>
+        rolesExt.clearRoles({ ...p, partyRolesPackageId: rolesPkg }),
+      // Tags
+      addTag: (p: Omit<tagsExt.AddTagParams, "partyTagsPackageId">) =>
+        tagsExt.addTag({ ...p, partyTagsPackageId: tagsPkg }),
+      removeTag: (p: Omit<tagsExt.RemoveTagParams, "partyTagsPackageId">) =>
+        tagsExt.removeTag({ ...p, partyTagsPackageId: tagsPkg }),
+      clearTags: (p: Omit<tagsExt.ClearTagsParams, "partyTagsPackageId">) =>
+        tagsExt.clearTags({ ...p, partyTagsPackageId: tagsPkg }),
+      // Genres
+      addGenre: (p: Omit<genresExt.AddGenreParams, "partyGenrePackageId">) =>
+        genresExt.addGenre({ ...p, partyGenrePackageId: partyGenrePkg }),
+      removeGenre: (p: Omit<genresExt.RemoveGenreParams, "partyGenrePackageId">) =>
+        genresExt.removeGenre({ ...p, partyGenrePackageId: partyGenrePkg }),
+      clearGenres: (p: Omit<genresExt.ClearGenresParams, "partyGenrePackageId">) =>
+        genresExt.clearGenres({ ...p, partyGenrePackageId: partyGenrePkg }),
+      // CTAs
+      setCtas: (p: Omit<ctasExt.SetCtasParams, "partyCtaPackageId">) =>
+        ctasExt.setCtas({ ...p, partyCtaPackageId: ctaPkg }),
+      clearCtas: (p: Omit<ctasExt.ClearCtasParams, "partyCtaPackageId">) =>
+        ctasExt.clearCtas({ ...p, partyCtaPackageId: ctaPkg }),
+      // Platform links — generic (any platform) plus per-platform `set…`/`clear…`.
+      setLink: (platform: PlatformKey, p: linksExt.BoundSetLinkParams) =>
+        linksExt.setLink(platform, { ...p, ...linkIds }),
+      clearLink: (platform: PlatformKey, p: linksExt.BoundClearLinkParams) =>
+        linksExt.clearLink(platform, { ...p, ...linkIds }),
+      ...linksExt.linkTxBuilders(linkIds),
+    };
+  }
+
+  // === Generated type-safe Move calls (for tx.add) ===
+
+  get call() {
+    return {
+      party: this.#core.call.party,
+      profile: bindModulePackage(profileMod, this.#profilePkg, ["profile"] as const),
+      media: bindModulePackage(mediaMod, this.#mediaPkg),
+      roles: bindModulePackage(rolesMod, this.#rolesPkg),
+      tags: bindModulePackage(tagsMod, this.#tagsPkg),
+      cta: bindModulePackage(ctaMod, this.#ctaPkg),
+      genre: bindModulePackage(genreMod, this.#partyGenrePkg),
+      platformLink: bindModulePackage(platformLinkMod, this.#platformLinkPkg),
+      social: bindModulePackage(socialMod, this.#socialPkg),
+      music: bindModulePackage(musicMod, this.#musicPkg),
+      proLink: bindModulePackage(proLinkMod, this.#proLinkPkg),
+    };
+  }
+
+  // === Generated BCS structs (for parsing object/event content) ===
+
+  get bcs() {
+    return {
+      ...this.#core.bcs,
+      Profile: profileMod.Profile,
+      ProfileSetEvent: profileMod.ProfileSetEvent,
+      Media: mediaMod.Media,
+      MediaSetEvent: mediaMod.MediaSetEvent,
+      ArtistRole: rolesMod.ArtistRole,
+      RoleAddedEvent: rolesMod.RoleAddedEvent,
+      TagAddedEvent: tagsMod.TagAddedEvent,
+      Cta: ctaMod.Cta,
+      CtasSetEvent: ctaMod.CtasSetEvent,
+      GenreAddedEvent: genreMod.GenreAddedEvent,
+      LinkSetEvent: platformLinkMod.LinkSetEvent,
+      LinkClearedEvent: platformLinkMod.LinkClearedEvent,
+    };
+  }
+}
+
+/** @deprecated Use `PartyPlatformClient`. Retained for callers migrating from the pre-split class. */
+export { PartyPlatformClient as PartyProtocolClient };

package/src/party/extensions/ctas.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The `party_cta` extension: a party's ordered call-to-action list (Tickets,
+// Merch, Newsletter, …). Each CTA is a `{ label, url }`; the whole list is written
+// at once (position is priority). The builder constructs each `Cta` via `new_cta`
+// and passes the vector to `set_ctas`.
+
+import * as ctaMod from "../../contracts/party_cta/party_cta.ts";
+import type { TxThunk } from "@misofm/partyos";
+import type { Cta } from "../types.ts";
+
+export interface SetCtasParams {
+  partyId: string;
+  capId: string;
+  /** The ordered CTA list — position is priority. */
+  ctas: Cta[];
+  partyCtaPackageId: string;
+}
+
+/** Sets (or replaces) the party's ordered CTA list. */
+export function setCtas(params: SetCtasParams): TxThunk {
+  return (tx) => {
+    const ctaType = `${params.partyCtaPackageId}::party_cta::Cta`;
+    const ctas = tx.makeMoveVec({
+      type: ctaType,
+      elements: params.ctas.map((c) =>
+        tx.add(ctaMod.newCta({ package: params.partyCtaPackageId, arguments: [c.label, c.url] })),
+      ),
+    });
+    tx.add(ctaMod.setCtas({ package: params.partyCtaPackageId, arguments: [params.partyId, params.capId, ctas] }));
+  };
+}
+
+export interface ClearCtasParams {
+  partyId: string;
+  capId: string;
+  partyCtaPackageId: string;
+}
+
+/** Removes the party's CTA list. No-op on-chain if none is set. */
+export function clearCtas(params: ClearCtasParams): TxThunk {
+  return (tx) => {
+    tx.add(ctaMod.clearCtas({ package: params.partyCtaPackageId, arguments: [params.partyId, params.capId] }));
+  };
+}

package/src/party/extensions/genres.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The `party_genre` extension: a set of `genre::Genre` object ids tagged on a
+// party. `add_genre` takes a `&Genre` vocabulary object (proving the id is a real
+// entry), so the builder passes `tx.object(genreId)`; removal is by id.
+
+import * as genreMod from "../../contracts/party_genre/party_genre.ts";
+import type { TxThunk } from "@misofm/partyos";
+
+export interface AddGenreParams {
+  partyId: string;
+  capId: string;
+  /** The `genre::Genre` vocabulary object id to tag. */
+  genreId: string;
+  partyGenrePackageId: string;
+}
+
+/** Tags a genre on the party. Aborts on-chain if already present or the max is reached. */
+export function addGenre(params: AddGenreParams): TxThunk {
+  return (tx) => {
+    tx.add(
+      genreMod.addGenre({
+        package: params.partyGenrePackageId,
+        arguments: [params.partyId, params.capId, tx.object(params.genreId)],
+      }),
+    );
+  };
+}
+
+export interface RemoveGenreParams {
+  partyId: string;
+  capId: string;
+  /** The genre id to untag. */
+  genreId: string;
+  partyGenrePackageId: string;
+}
+
+/** Untags a genre from the party. Aborts on-chain if not present. */
+export function removeGenre(params: RemoveGenreParams): TxThunk {
+  return (tx) => {
+    tx.add(
+      genreMod.removeGenre({
+        package: params.partyGenrePackageId,
+        arguments: [params.partyId, params.capId, params.genreId],
+      }),
+    );
+  };
+}
+
+export interface ClearGenresParams {
+  partyId: string;
+  capId: string;
+  partyGenrePackageId: string;
+}
+
+/** Removes the party's entire genre set. No-op on-chain if none is set. */
+export function clearGenres(params: ClearGenresParams): TxThunk {
+  return (tx) => {
+    tx.add(genreMod.clearGenres({ package: params.partyGenrePackageId, arguments: [params.partyId, params.capId] }));
+  };
+}

package/src/party/extensions/links.ts

@@ -0,0 +1,185 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The platform-link facade: attaches one independent `PlatformLink<Data>` per
+// platform to a party via `party_platform_link`. The payload `Data` types live in
+// their own packages (`party_social`, `party_music`, `party_pro_link`); this file
+// drives all ~27 platforms from a single table (`PLATFORMS`) rather than 27×
+// copy-paste. Each setter builds the link via the platform's constructor move-call
+// (returning a `PlatformLink<…Data>`), then calls `set_link` with the matching
+// `Data` type argument; clearers call `clear_link` with the same type argument.
+// Only the native identifier is stored on-chain; the public URL is rebuilt from it.
+
+import * as platformLinkMod from "../../contracts/party_platform_link/party_platform_link.ts";
+import type { TxThunk } from "@misofm/partyos";
+import type { PlatformKey, PlatformLink } from "../types.ts";
+
+/** Which payload package a platform's `Data` type + constructor live in. */
+type PayloadPkgKind = "social" | "music" | "pro";
+
+/** Everything needed to build, store, and rebuild one platform's link. */
+export interface PlatformSpec {
+  key: PlatformKey;
+  /** Payload package the `Data` type + constructor live in. */
+  pkgKind: PayloadPkgKind;
+  /** Move module holding the constructor + `Data` type. */
+  module: "party_social" | "party_music" | "party_pro_link";
+  /** Constructor function (snake_case) — takes a single `String`, returns `PlatformLink<Data>`. */
+  ctor: string;
+  /** The `Data` type name (e.g. `InstagramData`). */
+  dataType: string;
+  /** Rebuilds the public URL from the stored native identifier. */
+  url: (value: string) => string;
+}
+
+/**
+ * Every platform this SDK can link, keyed by `PlatformKey`. The single source of
+ * truth: setters, clearers, and the read-side URL/type mapping all derive from it.
+ */
+export const PLATFORMS: Record<PlatformKey, PlatformSpec> = {
+  // === Social (party_social) ===
+  x: { key: "x", pkgKind: "social", module: "party_social", ctor: "x", dataType: "XData", url: (v) => `https://x.com/${v}` },
+  instagram: { key: "instagram", pkgKind: "social", module: "party_social", ctor: "instagram", dataType: "InstagramData", url: (v) => `https://instagram.com/${v}` },
+  threads: { key: "threads", pkgKind: "social", module: "party_social", ctor: "threads", dataType: "ThreadsData", url: (v) => `https://www.threads.net/@${v}` },
+  tiktok: { key: "tiktok", pkgKind: "social", module: "party_social", ctor: "tiktok", dataType: "TikTokData", url: (v) => `https://www.tiktok.com/@${v}` },
+  youtube: { key: "youtube", pkgKind: "social", module: "party_social", ctor: "youtube", dataType: "YouTubeData", url: (v) => `https://youtube.com/@${v}` },
+  discord: { key: "discord", pkgKind: "social", module: "party_social", ctor: "discord", dataType: "DiscordData", url: (v) => `https://discord.gg/${v}` },
+  telegram: { key: "telegram", pkgKind: "social", module: "party_social", ctor: "telegram", dataType: "TelegramData", url: (v) => `https://t.me/${v}` },
+  reddit: { key: "reddit", pkgKind: "social", module: "party_social", ctor: "reddit", dataType: "RedditData", url: (v) => `https://reddit.com/user/${v}` },
+  twitch: { key: "twitch", pkgKind: "social", module: "party_social", ctor: "twitch", dataType: "TwitchData", url: (v) => `https://twitch.tv/${v}` },
+  facebook: { key: "facebook", pkgKind: "social", module: "party_social", ctor: "facebook", dataType: "FacebookData", url: (v) => `https://facebook.com/${v}` },
+  // === Music (party_music) ===
+  spotify: { key: "spotify", pkgKind: "music", module: "party_music", ctor: "spotify", dataType: "SpotifyData", url: (v) => `https://open.spotify.com/artist/${v}` },
+  bandcamp: { key: "bandcamp", pkgKind: "music", module: "party_music", ctor: "bandcamp", dataType: "BandcampData", url: (v) => `https://${v}.bandcamp.com` },
+  soundcloud: { key: "soundcloud", pkgKind: "music", module: "party_music", ctor: "soundcloud", dataType: "SoundCloudData", url: (v) => `https://soundcloud.com/${v}` },
+  appleMusic: { key: "appleMusic", pkgKind: "music", module: "party_music", ctor: "apple_music", dataType: "AppleMusicData", url: (v) => `https://music.apple.com/artist/${v}` },
+  deezer: { key: "deezer", pkgKind: "music", module: "party_music", ctor: "deezer", dataType: "DeezerData", url: (v) => `https://www.deezer.com/artist/${v}` },
+  tidal: { key: "tidal", pkgKind: "music", module: "party_music", ctor: "tidal", dataType: "TidalData", url: (v) => `https://tidal.com/artist/${v}` },
+  amazonMusic: { key: "amazonMusic", pkgKind: "music", module: "party_music", ctor: "amazon_music", dataType: "AmazonMusicData", url: (v) => `https://music.amazon.com/artists/${v}` },
+  audiomack: { key: "audiomack", pkgKind: "music", module: "party_music", ctor: "audiomack", dataType: "AudiomackData", url: (v) => `https://audiomack.com/${v}` },
+  // === Professional / industry (party_pro_link). URL-based payloads store a full URL. ===
+  website: { key: "website", pkgKind: "pro", module: "party_pro_link", ctor: "website", dataType: "WebsiteData", url: (v) => v },
+  bookingPage: { key: "bookingPage", pkgKind: "pro", module: "party_pro_link", ctor: "booking_page", dataType: "BookingPageData", url: (v) => v },
+  managementPage: { key: "managementPage", pkgKind: "pro", module: "party_pro_link", ctor: "management_page", dataType: "ManagementPageData", url: (v) => v },
+  publisherPage: { key: "publisherPage", pkgKind: "pro", module: "party_pro_link", ctor: "publisher_page", dataType: "PublisherPageData", url: (v) => v },
+  labelPage: { key: "labelPage", pkgKind: "pro", module: "party_pro_link", ctor: "label_page", dataType: "LabelPageData", url: (v) => v },
+  epk: { key: "epk", pkgKind: "pro", module: "party_pro_link", ctor: "epk", dataType: "EpkData", url: (v) => v },
+  patreon: { key: "patreon", pkgKind: "pro", module: "party_pro_link", ctor: "patreon", dataType: "PatreonData", url: (v) => `https://patreon.com/${v}` },
+  substack: { key: "substack", pkgKind: "pro", module: "party_pro_link", ctor: "substack", dataType: "SubstackData", url: (v) => `https://${v}.substack.com` },
+  kofi: { key: "kofi", pkgKind: "pro", module: "party_pro_link", ctor: "kofi", dataType: "KofiData", url: (v) => `https://ko-fi.com/${v}` },
+};
+
+/** All platform keys, in table order. */
+export const PLATFORM_KEYS = Object.keys(PLATFORMS) as PlatformKey[];
+
+/** The package ids the platform-link facade binds (the facade + the three payload packages). */
+export interface LinkPackageIds {
+  partyPlatformLinkPackageId: string;
+  partySocialPackageId: string;
+  partyMusicPackageId: string;
+  partyProLinkPackageId: string;
+}
+
+function payloadPackageId(spec: PlatformSpec, ids: LinkPackageIds): string {
+  switch (spec.pkgKind) {
+    case "social":
+      return ids.partySocialPackageId;
+    case "music":
+      return ids.partyMusicPackageId;
+    case "pro":
+      return ids.partyProLinkPackageId;
+  }
+}
+
+/** The fully-qualified Move `Data` type for a platform (e.g. `0x…::party_social::InstagramData`). */
+function dataTypeArg(spec: PlatformSpec, ids: LinkPackageIds): string {
+  return `${payloadPackageId(spec, ids)}::${spec.module}::${spec.dataType}`;
+}
+
+export interface SetLinkParams extends LinkPackageIds {
+  partyId: string;
+  capId: string;
+  /** The platform-native identifier to store (handle / id / subdomain / full URL). */
+  value: string;
+}
+
+/** Sets (or replaces) a platform's link on the party. */
+export function setLink(platform: PlatformKey, params: SetLinkParams): TxThunk {
+  return (tx) => {
+    const spec = PLATFORMS[platform];
+    const pkg = payloadPackageId(spec, params);
+    const link = tx.moveCall({
+      target: `${pkg}::${spec.module}::${spec.ctor}`,
+      arguments: [tx.pure.string(params.value)],
+    });
+    tx.add(
+      platformLinkMod.setLink({
+        package: params.partyPlatformLinkPackageId,
+        typeArguments: [dataTypeArg(spec, params)],
+        arguments: [params.partyId, params.capId, link],
+      }),
+    );
+  };
+}
+
+export interface ClearLinkParams extends LinkPackageIds {
+  partyId: string;
+  capId: string;
+}
+
+/** Clears a platform's link from the party. No-op on-chain if unset. */
+export function clearLink(platform: PlatformKey, params: ClearLinkParams): TxThunk {
+  return (tx) => {
+    const spec = PLATFORMS[platform];
+    tx.add(
+      platformLinkMod.clearLink({
+        package: params.partyPlatformLinkPackageId,
+        typeArguments: [dataTypeArg(spec, params)],
+        arguments: [params.partyId, params.capId],
+      }),
+    );
+  };
+}
+
+// === Read helpers ===
+
+// The Move `Data` type suffix (`<module>::<dataType>`) → platform key. The package
+// id prefix varies, so match on the last two `::` segments (unique across the table).
+const BY_MOVE_TYPE: Record<string, PlatformKey> = Object.fromEntries(
+  PLATFORM_KEYS.map((k) => [`${PLATFORMS[k].module}::${PLATFORMS[k].dataType}`, k]),
+) as Record<string, PlatformKey>;
+
+/**
+ * The platform for a fully-qualified `Data` type argument, or null if unknown.
+ * @param dataType e.g. `0x…::party_social::InstagramData`.
+ */
+export function platformForDataType(dataType: string): PlatformKey | null {
+  const suffix = dataType.split("::").slice(-2).join("::");
+  return BY_MOVE_TYPE[suffix] ?? null;
+}
+
+/** Builds a public `PlatformLink` from a platform key and its stored native identifier. */
+export function buildLink(platform: PlatformKey, value: string): PlatformLink {
+  return { platform, value, url: PLATFORMS[platform].url(value) };
+}
+
+// === Bound builders (the client binds package ids, then exposes per-platform methods) ===
+
+export type BoundSetLinkParams = Omit<SetLinkParams, keyof LinkPackageIds>;
+export type BoundClearLinkParams = Omit<ClearLinkParams, keyof LinkPackageIds>;
+
+/** Per-platform `setX` / `clearX` builders, keyed off the table so all ~27 are covered. */
+export type LinkTxBuilders =
+  & { [K in PlatformKey as `set${Capitalize<K>}`]: (p: BoundSetLinkParams) => TxThunk }
+  & { [K in PlatformKey as `clear${Capitalize<K>}`]: (p: BoundClearLinkParams) => TxThunk };
+
+/** Builds the per-platform link tx builders with `ids` pre-bound. */
+export function linkTxBuilders(ids: LinkPackageIds): LinkTxBuilders {
+  const out: Record<string, unknown> = {};
+  for (const key of PLATFORM_KEYS) {
+    const cap = key.charAt(0).toUpperCase() + key.slice(1);
+    out[`set${cap}`] = (p: BoundSetLinkParams): TxThunk => setLink(key, { ...p, ...ids });
+    out[`clear${cap}`] = (p: BoundClearLinkParams): TxThunk => clearLink(key, { ...p, ...ids });
+  }
+  return out as LinkTxBuilders;
+}

package/src/party/extensions/media.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// The `party_media` extension: a party's imagery, stored on-chain as a single
+// Walrus *quilt* id. Individual images are quilt patches addressed by identifier
+// ("avatar", "header", …) — those roles are a client convention, derived here
+// off-chain, never stored on-chain. The write builder takes the quilt's base64url
+// blob id (what `walrus store-quilt` prints) and converts it to the on-chain
+// u256; the read helpers build aggregator URLs per identifier.
+
+import { b64UrlToU256 } from "../internal.ts";
+import * as mediaMod from "../../contracts/party_media/party_media.ts";
+import type { TxThunk } from "@misofm/partyos";
+import type { Media } from "../types.ts";
+
+/**
+ * Quilt patch identifiers party media uses, in role order. Uploaders store images
+ * under these identifiers; readers fetch by them. This is the whole "meaning" the
+ * chain defers to the client.
+ */
+export const MEDIA_IDENTIFIERS = { avatar: "avatar", header: "header" } as const;
+export type MediaIdentifier = (typeof MEDIA_IDENTIFIERS)[keyof typeof MEDIA_IDENTIFIERS];
+
+export interface SetMediaParams {
+  partyId: string;
+  capId: string;
+  /** Walrus quilt blob id (base64url), e.g. from `walrus store-quilt`. */
+  quiltId: string;
+  partyMediaPackageId: string;
+}
+
+/** Sets (or replaces) the party's media quilt. */
+export function setMedia(params: SetMediaParams): TxThunk {
+  return (tx) => {
+    tx.add(
+      mediaMod.setMedia({
+        package: params.partyMediaPackageId,
+        arguments: [params.partyId, params.capId, BigInt(b64UrlToU256(params.quiltId))],
+      }),
+    );
+  };
+}
+
+export interface ClearMediaParams {
+  partyId: string;
+  capId: string;
+  partyMediaPackageId: string;
+}
+
+/** Removes the party's media entirely. No-op on-chain if none is set. */
+export function clearMedia(params: ClearMediaParams): TxThunk {
+  return (tx) => {
+    tx.add(mediaMod.clearMedia({ package: params.partyMediaPackageId, arguments: [params.partyId, params.capId] }));
+  };
+}
+
+/** Aggregator URL for one image in a party's quilt, addressed by identifier. */
+export function mediaImageUrl(aggregatorUrl: string, quiltId: string, identifier: string): string {
+  return `${aggregatorUrl.replace(/\/$/, "")}/v1/blobs/by-quilt-id/${quiltId}/${identifier}`;
+}
+
+/** The avatar + header image URLs for a party's media, or null if unset. */
+export function mediaUrls(
+  aggregatorUrl: string,
+  media: Media | null,
+): { avatar: string; header: string } | null {
+  if (!media) return null;
+  return {
+    avatar: mediaImageUrl(aggregatorUrl, media.quiltId, MEDIA_IDENTIFIERS.avatar),
+    header: mediaImageUrl(aggregatorUrl, media.quiltId, MEDIA_IDENTIFIERS.header),
+  };
+}