@misofm/sdk 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misofm/sdk",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Typed query helpers and transaction builders for the Miso platform layer on Sui \u2014 pressings, listings, records, and opinionated work publishing.",
   "license": "Apache-2.0",
   "repository": {
@@ -64,6 +64,18 @@
       "types": "./dist/catalog.d.ts",
       "default": "./dist/catalog.js"
     },
+    "./credits": {
+      "types": "./dist/credits.d.ts",
+      "default": "./dist/credits.js"
+    },
+    "./cover": {
+      "types": "./dist/cover.d.ts",
+      "default": "./dist/cover.js"
+    },
+    "./extensions/royalty-pool": {
+      "types": "./dist/extensions/royalty-pool.d.ts",
+      "default": "./dist/extensions/royalty-pool.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -93,7 +105,7 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@misonetwork/sdk": "^0.2.2"
+    "@misonetwork/sdk": "^0.3.1"
   },
   "main": "./dist/index.js"
 }

package/src/catalog.ts

@@ -14,10 +14,128 @@
 import type { ClientWithCoreApi } from "@mysten/sui/client";
 import type { SuiGraphQLClient } from "@mysten/sui/graphql";
 import {
+  getCompositionAddressByShareType,
   getOwnedRecordingAdminCaps,
   getRecordingByShareType,
+  getRecordingShareTypes,
+  getReleaseById,
   type Recording,
 } from "@misonetwork/sdk";
+import {
+  getCompositionCredits,
+  getRecordingCredits,
+  type CreditView,
+  type RecordingCreditsView,
+} from "./credits.ts";
+
+export interface GetReleaseTrackCreditsOptions {
+  /** Core Miso package that defines Composition and Recording. */
+  misoPackageId: string;
+  /** Package that defines the composition_credits extension key. */
+  compositionCreditsPackageId: string;
+  /** Package that defines the recording_credits extension key. */
+  recordingCreditsPackageId: string;
+}
+
+export interface ReleaseTrackCredits {
+  compositionCredits: CreditView[];
+  recordingCredits: RecordingCreditsView;
+}
+
+const EMPTY_RECORDING_CREDITS: RecordingCreditsView = {
+  credits: [],
+  primaryArtistIds: [],
+  featuredArtistIds: [],
+};
+
+/**
+ * Composition and recording credits for every track on a release, keyed by
+ * recording id.
+ *
+ * The read follows the chain's actual object graph instead of release credits:
+ * Release -> Recording -> Composition. Recording credit fields and recording
+ * type parameters are fetched together for every track. Composition addresses
+ * are then resolved concurrently, deduplicated, and all composition credit
+ * fields are fetched concurrently as well.
+ */
+export async function getReleaseTrackCredits(
+  client: ClientWithCoreApi,
+  graphqlClient: SuiGraphQLClient,
+  releaseId: string,
+  options: GetReleaseTrackCreditsOptions,
+): Promise<Record<string, ReleaseTrackCredits>> {
+  const release = await getReleaseById(client, releaseId);
+  return getTrackCreditsByRecordingIds(
+    client,
+    graphqlClient,
+    release.tracks.map((track) => track.recordingId),
+    options,
+  );
+}
+
+/**
+ * Composition and recording credits for the supplied recordings, keyed by
+ * recording id. This form is intended for consumers that already loaded a
+ * release and do not need to fetch it again.
+ */
+export async function getTrackCreditsByRecordingIds(
+  client: ClientWithCoreApi,
+  graphqlClient: SuiGraphQLClient,
+  recordingIdsInput: readonly string[],
+  options: GetReleaseTrackCreditsOptions,
+): Promise<Record<string, ReleaseTrackCredits>> {
+  const recordingIds = [...new Set(recordingIdsInput)];
+
+  const recordingReads = await Promise.all(
+    recordingIds.map(async (recordingId) => {
+      const [recordingCredits, [, compositionShareType]] = await Promise.all([
+        getRecordingCredits(client, recordingId, options.recordingCreditsPackageId),
+        getRecordingShareTypes(client, recordingId),
+      ]);
+      return { recordingId, recordingCredits, compositionShareType };
+    }),
+  );
+
+  const compositionShareTypes = [...new Set(recordingReads.map((read) => read.compositionShareType))];
+  const compositionAddressEntries = await Promise.all(
+    compositionShareTypes.map(async (shareType) => {
+      const compositionId = await getCompositionAddressByShareType(
+        graphqlClient,
+        shareType,
+        options.misoPackageId,
+      );
+      if (!compositionId) throw new Error(`Composition not found for share type: ${shareType}`);
+      return [shareType, compositionId] as const;
+    }),
+  );
+  const compositionAddressByShareType = new Map(compositionAddressEntries);
+
+  const compositionIds = [...new Set(compositionAddressEntries.map(([, compositionId]) => compositionId))];
+  const compositionCreditEntries = await Promise.all(
+    compositionIds.map(async (compositionId) => {
+      const credits = await getCompositionCredits(
+        client,
+        compositionId,
+        options.compositionCreditsPackageId,
+      );
+      return [compositionId, credits ?? []] as const;
+    }),
+  );
+  const compositionCreditsById = new Map(compositionCreditEntries);
+
+  return Object.fromEntries(
+    recordingReads.map((read) => {
+      const compositionId = compositionAddressByShareType.get(read.compositionShareType)!;
+      return [
+        read.recordingId,
+        {
+          compositionCredits: compositionCreditsById.get(compositionId) ?? [],
+          recordingCredits: read.recordingCredits ?? EMPTY_RECORDING_CREDITS,
+        },
+      ];
+    }),
+  );
+}
 
 export interface GetAdministeredRecordingsOptions {
   /**

package/src/contracts/composition_credits/composition_credits.ts

@@ -0,0 +1,169 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+
+
+/**
+ * First-party credits extension for compositions.
+ * 
+ * Attribution (writing credits) is display-oriented and varies across platforms,
+ * so it lives here as a dynamic field on the composition rather than in immutable
+ * core. The data is attached under `ExtensionKey()` via the composition's
+ * cap-gated `uid_mut`, so every mutation is authorized by the composition's admin
+ * and credits survive into any lifecycle state (they may be attached before or
+ * after the composition is published).
+ * 
+ * This is Miso's canonical credits standard; because it is an extension, other
+ * parties may publish their own composition-credits standard against the same
+ * `Composition`. Credits are NOT read by the economics — they are attribution.
+ */
+
+import { MoveTuple, MoveStruct, normalizeMoveArguments, type RawTransactionArgument } from '../utils/index.js';
+import { bcs } from '@mysten/sui/bcs';
+import { type Transaction, type TransactionArgument } from '@mysten/sui/transactions';
+import * as vec_map from './deps/sui/vec_map.js';
+import * as credit from './deps/miso_credit/credit.js';
+import * as composition_party_role from './composition_party_role.js';
+const $moduleName = '@local-pkg/composition_credits::composition_credits';
+export const ExtensionKey = new MoveTuple({ name: `${$moduleName}::ExtensionKey`, fields: [bcs.bool()] });
+export const CompositionCredits = new MoveStruct({ name: `${$moduleName}::CompositionCredits`, fields: {
+        /** Map of party IDs to their credit (display name + roles). */
+        credits: vec_map.VecMap(bcs.Address, credit.Credit(composition_party_role.CompositionPartyRole))
+    } });
+export const CreditAddedEvent = new MoveStruct({ name: `${$moduleName}::CreditAddedEvent`, fields: {
+        composition_id: bcs.Address,
+        party_id: bcs.Address,
+        credit: credit.Credit(composition_party_role.CompositionPartyRole)
+    } });
+export const CreditRemovedEvent = new MoveStruct({ name: `${$moduleName}::CreditRemovedEvent`, fields: {
+        composition_id: bcs.Address,
+        party_id: bcs.Address,
+        credit: credit.Credit(composition_party_role.CompositionPartyRole)
+    } });
+export interface AddCreditArguments {
+    self: RawTransactionArgument<string>;
+    cap: RawTransactionArgument<string>;
+    party: RawTransactionArgument<string>;
+    credit: TransactionArgument;
+}
+export interface AddCreditOptions {
+    package?: string;
+    arguments: AddCreditArguments | [
+        self: RawTransactionArgument<string>,
+        cap: RawTransactionArgument<string>,
+        party: RawTransactionArgument<string>,
+        credit: TransactionArgument
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/**
+ * Adds a credit for a party on the composition, lazily creating the credits record
+ * on first use. Each credit must have 1-5 roles, and a party may hold at most one
+ * credit. Requires the composition's admin capability.
+ */
+export function addCredit(options: AddCreditOptions) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null,
+        null,
+        null,
+        null
+    ] satisfies (string | null)[];
+    const parameterNames = ["self", "cap", "party", "credit"];
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'add_credit',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}
+export interface RemoveCreditArguments {
+    self: RawTransactionArgument<string>;
+    cap: RawTransactionArgument<string>;
+    partyId: RawTransactionArgument<string>;
+}
+export interface RemoveCreditOptions {
+    package?: string;
+    arguments: RemoveCreditArguments | [
+        self: RawTransactionArgument<string>,
+        cap: RawTransactionArgument<string>,
+        partyId: RawTransactionArgument<string>
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/** Removes a party's credit. Requires the composition's admin capability. */
+export function removeCredit(options: RemoveCreditOptions) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null,
+        null,
+        '0x2::object::ID'
+    ] satisfies (string | null)[];
+    const parameterNames = ["self", "cap", "partyId"];
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'remove_credit',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}
+export interface HasCreditsArguments {
+    self: RawTransactionArgument<string>;
+}
+export interface HasCreditsOptions {
+    package?: string;
+    arguments: HasCreditsArguments | [
+        self: RawTransactionArgument<string>
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/** Returns whether a credits record has been attached to this composition yet. */
+export function hasCredits(options: HasCreditsOptions) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null
+    ] satisfies (string | null)[];
+    const parameterNames = ["self"];
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'has_credits',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}
+export interface CreditsArguments {
+    self: RawTransactionArgument<string>;
+}
+export interface CreditsOptions {
+    package?: string;
+    arguments: CreditsArguments | [
+        self: RawTransactionArgument<string>
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/** Returns the party-to-credit map. Aborts if no credits are attached. */
+export function credits(options: CreditsOptions) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null
+    ] satisfies (string | null)[];
+    const parameterNames = ["self"];
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'credits',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}

package/src/contracts/composition_credits/composition_party_role.ts

@@ -0,0 +1,189 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+
+
+/**
+ * Defines the roles that parties can hold on a composition. Compositions are the
+ * underlying musical works (melody + lyrics), and these roles represent the
+ * writing and adaptation contributions to them.
+ * 
+ * ### Design
+ * 
+ * `CompositionPartyRole` is a closed enum: variants can only be constructed and
+ * matched inside this module, so the `new_*_role` constructors are the external
+ * write-API and `name()` is the external read-API.
+ * 
+ * - **No seniority axis.** Unlike recording roles, composition roles carry no
+ *   level — a writer either contributed in a given capacity or did not.
+ * - **`Custom` is the escape hatch.** The canonical variants cover the common
+ *   writing vocabulary; anything outside it is a `Custom(name)` whose name is
+ *   validated. Prefer a canonical variant when one fits.
+ * - **`name()` is the canonical identifier**, returned as a stable PascalCase
+ *   token (e.g. `"Songwriter"`). For `Custom`, `name()` returns the user-supplied
+ *   string.
+ * 
+ * These identifiers are Miso's own canonical vocabulary; any overlap with an
+ * external standard (e.g. DDEX) is coincidental, not a reproduction of it.
+ */
+
+import { MoveEnum, normalizeMoveArguments, type RawTransactionArgument } from '../utils/index.js';
+import { bcs } from '@mysten/sui/bcs';
+import { type Transaction, type TransactionArgument } from '@mysten/sui/transactions';
+const $moduleName = '@local-pkg/composition_credits::composition_party_role';
+/** Represents a party's role on a composition. */
+export const CompositionPartyRole = new MoveEnum({ name: `${$moduleName}::CompositionPartyRole`, fields: {
+        /** Adapted an existing work into this composition. */
+        Adapter: null,
+        /** Arranged the musical parts of the composition. */
+        Arranger: null,
+        /** Composed the music of the composition. */
+        Composer: null,
+        /** Wrote the lyrics of the composition. */
+        Lyricist: null,
+        /** Wrote both music and lyrics of the composition. */
+        Songwriter: null,
+        /** Translated the lyrics of the composition. */
+        Translator: null,
+        /**
+         * A user-defined role not covered by a canonical variant. Carries the role name
+         * (validated). An escape hatch — prefer a canonical variant when one fits.
+         */
+        Custom: bcs.string()
+    } });
+export interface NewAdapterRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Adapter role. */
+export function newAdapterRole(options: NewAdapterRoleOptions = {}) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'new_adapter_role',
+    });
+}
+export interface NewArrangerRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Arranger role. */
+export function newArrangerRole(options: NewArrangerRoleOptions = {}) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'new_arranger_role',
+    });
+}
+export interface NewComposerRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Composer role. */
+export function newComposerRole(options: NewComposerRoleOptions = {}) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'new_composer_role',
+    });
+}
+export interface NewLyricistRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Lyricist role. */
+export function newLyricistRole(options: NewLyricistRoleOptions = {}) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'new_lyricist_role',
+    });
+}
+export interface NewSongwriterRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Songwriter role. */
+export function newSongwriterRole(options: NewSongwriterRoleOptions = {}) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'new_songwriter_role',
+    });
+}
+export interface NewTranslatorRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Translator role. */
+export function newTranslatorRole(options: NewTranslatorRoleOptions = {}) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'new_translator_role',
+    });
+}
+export interface NewCustomRoleArguments {
+    roleName: RawTransactionArgument<string>;
+}
+export interface NewCustomRoleOptions {
+    package?: string;
+    arguments: NewCustomRoleArguments | [
+        roleName: RawTransactionArgument<string>
+    ];
+}
+/**
+ * Creates a new Custom role with a user-defined name. The name freezes into
+ * credits, so it is validated here. Prefer a canonical variant when one fits.
+ */
+export function newCustomRole(options: NewCustomRoleOptions) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        '0x1::string::String'
+    ] satisfies (string | null)[];
+    const parameterNames = ["roleName"];
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'new_custom_role',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+    });
+}
+export interface NameArguments {
+    self: TransactionArgument;
+}
+export interface NameOptions {
+    package?: string;
+    arguments: NameArguments | [
+        self: TransactionArgument
+    ];
+}
+/**
+ * Returns the canonical identifier of the role as a stable PascalCase token. For
+ * `Custom`, returns the user-supplied name.
+ */
+export function name(options: NameOptions) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null
+    ] satisfies (string | null)[];
+    const parameterNames = ["self"];
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_party_role',
+        function: 'name',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+    });
+}

package/src/contracts/composition_credits/deps/miso_credit/credit.ts

@@ -0,0 +1,27 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+
+
+/**
+ * Represents a party's credit on a work or activity. A credit pairs a display name
+ * with one or more roles, identifying how a party contributed to the work.
+ */
+
+import { type BcsType, bcs } from '@mysten/sui/bcs';
+import { MoveStruct } from '../../../utils/index.js';
+const $moduleName = 'miso_credit::credit';
+/**
+ * A credit attributing roles to a party on a work. Generic over the role type to
+ * support domain-specific roles.
+ */
+export function Credit<Role extends BcsType<any>>(...typeParameters: [
+    Role
+]) {
+    return new MoveStruct({ name: `${$moduleName}::Credit<${typeParameters[0].name as Role['name']}>`, fields: {
+            /** Human-readable name to display for this credit. */
+            display_name: bcs.string(),
+            /** Roles assigned to the credited party. */
+            roles: bcs.vector(typeParameters[0])
+        } });
+}

package/src/contracts/composition_credits/deps/sui/vec_map.ts

@@ -0,0 +1,33 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+import { type BcsType, bcs } from '@mysten/sui/bcs';
+import { MoveStruct } from '../../../utils/index.js';
+const $moduleName = '0x2::vec_map';
+/** An entry in the map */
+export function Entry<K extends BcsType<any>, V extends BcsType<any>>(...typeParameters: [
+    K,
+    V
+]) {
+    return new MoveStruct({ name: `${$moduleName}::Entry<${typeParameters[0].name as K['name']}, ${typeParameters[1].name as V['name']}>`, fields: {
+            key: typeParameters[0],
+            value: typeParameters[1]
+        } });
+}
+/**
+ * A map data structure backed by a vector. The map is guaranteed not to contain
+ * duplicate keys, but entries are _not_ sorted by key--entries are included in
+ * insertion order. All operations are O(N) in the size of the map--the intention
+ * of this data structure is only to provide the convenience of programming against
+ * a map API. Large maps should use handwritten parent/child relationships instead.
+ * Maps that need sorted iteration rather than insertion order iteration should
+ * also be handwritten.
+ */
+export function VecMap<K extends BcsType<any>, V extends BcsType<any>>(...typeParameters: [
+    K,
+    V
+]) {
+    return new MoveStruct({ name: `${$moduleName}::VecMap<${typeParameters[0].name as K['name']}, ${typeParameters[1].name as V['name']}>`, fields: {
+            contents: bcs.vector(Entry(typeParameters[0], typeParameters[1]))
+        } });
+}