@misonetwork/sdk 0.1.0

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@misonetwork/sdk",
+  "version": "0.1.0",
+  "description": "Typed query helpers and transaction builders for the Miso protocol core on Sui.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/misonetwork/sdk.git"
+  },
+  "homepage": "https://github.com/misonetwork/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/misonetwork/sdk/issues"
+  },
+  "keywords": [
+    "sui",
+    "move",
+    "miso",
+    "music",
+    "blockchain",
+    "sdk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "codegen": "sui-ts-codegen generate",
+    "docs": "typedoc",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
+    "prepare": "tsc -p tsconfig.build.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./queries": {
+      "types": "./dist/queries.d.ts",
+      "default": "./dist/queries.js"
+    },
+    "./cover": {
+      "types": "./dist/cover.d.ts",
+      "default": "./dist/cover.js"
+    },
+    "./credits": {
+      "types": "./dist/credits.d.ts",
+      "default": "./dist/credits.js"
+    },
+    "./transactions": {
+      "types": "./dist/transactions.d.ts",
+      "default": "./dist/transactions.js"
+    },
+    "./execute": {
+      "types": "./dist/execute.d.ts",
+      "default": "./dist/execute.js"
+    },
+    "./extensions/royalty-pool": {
+      "types": "./dist/extensions/royalty-pool.d.ts",
+      "default": "./dist/extensions/royalty-pool.js"
+    },
+    "./view": {
+      "types": "./dist/view.d.ts",
+      "default": "./dist/view.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas.d.ts",
+      "default": "./dist/schemas.js"
+    },
+    "./parsers": {
+      "types": "./dist/parsers.d.ts",
+      "default": "./dist/parsers.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "devDependencies": {
+    "@mysten/codegen": "^0.11.14",
+    "@mysten/sui": "^2.24.0",
+    "@types/bun": "^1.3.14",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0"
+  },
+  "peerDependencies": {
+    "@mysten/sui": "^2.4.0",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "main": "./dist/index.js"
+}

package/src/client.ts

@@ -0,0 +1,278 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ClientWithCoreApi, SuiClientRegistration } from "@mysten/sui/client";
+import type { SuiGraphQLClient } from "@mysten/sui/graphql";
+import type { TxThunk } from "./transactions.ts";
+import * as parsers from "./parsers.ts";
+import * as queries from "./queries.ts";
+import * as transactions from "./transactions.ts";
+import * as view from "./view.ts";
+import type { Composition, CompositionAdminCap, Deal, Recording, RecordingAdminCap, Release, ReleaseAdminCap } from "./types.ts";
+
+// Generated call modules (type-safe Move calls) and BCS structs.
+import * as composition from "./contracts/miso/composition.ts";
+import * as recording from "./contracts/miso/recording.ts";
+import * as release from "./contracts/miso/release.ts";
+import * as deal from "./contracts/miso/deal.ts";
+import * as track from "./contracts/miso/track.ts";
+
+export interface MisoOptions<Name extends string = "miso"> {
+  /** Name for the client extension. Defaults to "miso". */
+  name?: Name;
+  /** The Miso package ID. Required for type-based queries and derivation. */
+  misoPackageId: string;
+  /**
+   * The `ReleaseRegistry` object ID for this deployment.
+   *
+   * Created once in `release::init` and shared, so it is FIXED for the lifetime
+   * of a published package — deployment config, not runtime state. Supply it
+   * (alongside `misoPackageId`, from the same deployment manifest) and
+   * `getReleaseRegistry()` needs no network call at all. Omit it and the SDK
+   * falls back to a GraphQL scan, which is why this is worth configuring.
+   */
+  releaseRegistryId?: string;
+  /**
+   * Optional GraphQL client, required ONLY for the global type-discovery reads
+   * the Core API cannot express: `getCompositionByShareType`,
+   * `getRecordingByShareType`, and `getReleaseRegistry` when
+   * `releaseRegistryId` is not configured. Everything else — including every
+   * `getOwned*AdminCaps` — goes over the Core API.
+   */
+  graphqlClient?: SuiGraphQLClient;
+}
+
+/**
+ * Wraps a builder so the client's `misoPackageId` is injected, dropping it from
+ * the caller's params. Explicit call-sites (the free functions in
+ * `./transactions`) remain available for full control.
+ */
+function bindPackages<P extends { misoPackageId: string }>(
+  fn: (params: P) => TxThunk,
+  misoPackageId: string,
+): (params: Omit<P, "misoPackageId">) => TxThunk {
+  return (params) => fn({ misoPackageId, ...params } as unknown as P);
+}
+
+/** Defaults `options.package` to `pkg` for every call-function in a generated module. */
+function bindModulePackage<M extends object>(mod: M, pkg: string): M {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries({ ...mod })) {
+    out[key] =
+      typeof value === "function"
+        ? (options: { package?: string }) => (value as (o: unknown) => unknown)({ package: pkg, ...options })
+        : value;
+  }
+  return out as M;
+}
+
+/**
+ * Creates a Miso client extension for use with `$extend()`.
+ *
+ * @example
+ * ```ts
+ * const client = new SuiGrpcClient({ network: 'testnet' })
+ *   .$extend(miso({ misoPackageId: '0x...' }));
+ * const composition = await client.miso.getCompositionById('0x...');
+ * ```
+ */
+export function miso<const Name extends string = "miso">(
+  options: MisoOptions<Name>,
+): SuiClientRegistration<ClientWithCoreApi, Name, MisoClient> {
+  const name = (options.name ?? "miso") as Name;
+  return {
+    name,
+    register: (client) => new MisoClient(client, options),
+  };
+}
+
+export class MisoClient {
+  #client: ClientWithCoreApi;
+  #graphqlClient?: SuiGraphQLClient;
+  #misoPackageId: string;
+  #releaseRegistryId?: string;
+
+  constructor(client: ClientWithCoreApi, options: Omit<MisoOptions, "name">) {
+    this.#client = client;
+    this.#graphqlClient = options.graphqlClient;
+    this.#misoPackageId = options.misoPackageId;
+    this.#releaseRegistryId = options.releaseRegistryId;
+  }
+
+  // === Composition ===
+
+  async getCompositionById(compositionId: string): Promise<Composition> {
+    return queries.getCompositionById(this.#client, compositionId);
+  }
+  async getCompositionsByIds(ids: string[]): Promise<Record<string, Composition>> {
+    return queries.getCompositionsByIds(this.#client, ids);
+  }
+  async getCompositionShareType(compositionId: string): Promise<string> {
+    return queries.getCompositionShareType(this.#client, compositionId);
+  }
+  async getCompositionByShareType(shareType: string): Promise<Composition> {
+    return queries.getCompositionByShareType(this.#client, this.#requireGraphQL(), shareType, this.#misoPackageId);
+  }
+  async getCompositionAdminCapById(adminCapId: string): Promise<CompositionAdminCap> {
+    return queries.getCompositionAdminCapById(this.#client, adminCapId);
+  }
+  async getOwnedCompositionAdminCaps(owner: string): Promise<CompositionAdminCap[]> {
+    return queries.getOwnedCompositionAdminCaps(this.#client, owner, this.#misoPackageId);
+  }
+  deriveCompositionAdminCapId(compositionId: string): string {
+    return queries.deriveCompositionAdminCapId(compositionId, this.#misoPackageId);
+  }
+
+  // === Recording ===
+
+  async getRecordingById(recordingId: string): Promise<Recording> {
+    return queries.getRecordingById(this.#client, recordingId);
+  }
+  async getRecordingsByIds(ids: string[]): Promise<Record<string, Recording>> {
+    return queries.getRecordingsByIds(this.#client, ids);
+  }
+  async getRecordingShareType(recordingId: string): Promise<string> {
+    return queries.getRecordingShareType(this.#client, recordingId);
+  }
+  async getRecordingByShareType(shareType: string): Promise<Recording> {
+    return queries.getRecordingByShareType(this.#client, this.#requireGraphQL(), shareType, this.#misoPackageId);
+  }
+  async getRecordingAdminCapById(adminCapId: string): Promise<RecordingAdminCap> {
+    return queries.getRecordingAdminCapById(this.#client, adminCapId);
+  }
+  async getOwnedRecordingAdminCaps(owner: string): Promise<RecordingAdminCap[]> {
+    return queries.getOwnedRecordingAdminCaps(this.#client, owner, this.#misoPackageId);
+  }
+  deriveRecordingAdminCapId(recordingId: string): string {
+    return queries.deriveRecordingAdminCapId(recordingId, this.#misoPackageId);
+  }
+
+  // === Deal ===
+
+  async getDealById(dealId: string): Promise<Deal> {
+    return queries.getDealById(this.#client, dealId);
+  }
+
+  // === Release ===
+
+  async getReleaseById(releaseId: string): Promise<Release> {
+    return queries.getReleaseById(this.#client, releaseId);
+  }
+  async getReleasesByIds(ids: string[]): Promise<Record<string, Release>> {
+    return queries.getReleasesByIds(this.#client, ids);
+  }
+  async getReleaseAdminCapById(adminCapId: string): Promise<ReleaseAdminCap> {
+    return queries.getReleaseAdminCapById(this.#client, adminCapId);
+  }
+  deriveReleaseAdminCapId(releaseId: string): string {
+    return queries.deriveReleaseAdminCapId(releaseId, this.#misoPackageId);
+  }
+  async getOwnedReleaseAdminCaps(owner: string): Promise<ReleaseAdminCap[]> {
+    return queries.getOwnedReleaseAdminCaps(this.#client, owner, this.#misoPackageId);
+  }
+  /**
+   * The deployment's `ReleaseRegistry` object ID.
+   *
+   * Returns the configured `releaseRegistryId` with no network call. Only when
+   * it was not configured does this fall back to a GraphQL scan — a one-time
+   * bootstrap for a fresh deployment whose id you have not recorded yet. Prefer
+   * configuring it: the registry is created once in `release::init` and never
+   * changes, so scanning for it on every call is pure overhead.
+   */
+  async getReleaseRegistry(): Promise<string> {
+    if (this.#releaseRegistryId) return this.#releaseRegistryId;
+    return queries.getReleaseRegistry(this.#requireGraphQL(), this.#misoPackageId);
+  }
+
+  // === Share Currency ===
+
+  async getShareCurrencyType(shareCurrencyId: string): Promise<string> {
+    return queries.getShareCurrencyType(this.#client, shareCurrencyId);
+  }
+  /**
+   * The `TreasuryCap<shareType>` owned by `owner`. Takes the share TYPE — if you
+   * hold only the `Currency` object id, resolve it first with
+   * {@link getShareCurrencyType}.
+   */
+  async getShareCurrencyTreasuryCap(shareType: string, owner: string): Promise<string> {
+    return queries.getShareCurrencyTreasuryCap(this.#client, shareType, owner);
+  }
+
+  // === Transaction builders (thunks) ===
+
+  // Only the `(params) => TxThunk` builders bind here. The primitives that take
+  // a `Transaction` directly and return values (`createComposition`,
+  // `createRecording`, `createRelease`, `createDeal`) are free functions by
+  // design — they thread results into a caller-owned PTB, so there is nothing
+  // to bind. Import them from the package root and pass `misoPackageId`
+  // explicitly.
+  get tx() {
+    const miso = this.#misoPackageId;
+    return {
+      rejectDeal: bindPackages(transactions.rejectDeal, miso),
+    };
+  }
+
+  // === Simulate-based reads (view) ===
+
+  get view() {
+    const client = this.#client;
+    const misoPackageId = this.#misoPackageId;
+    return {
+      deriveReleaseId: (params: view.DeriveReleaseIdParams) => view.deriveReleaseId(client, misoPackageId, params),
+    };
+  }
+
+  // === Generated type-safe Move calls (for tx.add) ===
+
+  get call() {
+    const pkg = this.#misoPackageId;
+    return {
+      composition: bindModulePackage(composition, pkg),
+      recording: bindModulePackage(recording, pkg),
+      release: bindModulePackage(release, pkg),
+      deal: bindModulePackage(deal, pkg),
+      track: bindModulePackage(track, pkg),
+    };
+  }
+
+  // === Generated BCS structs (for parsing object/event content) ===
+
+  get bcs() {
+    return {
+      Composition: composition.Composition,
+      Recording: recording.Recording,
+      Release: release.Release,
+      Deal: deal.Deal,
+      Track: track.Track,
+      CompositionPublishedEvent: composition.CompositionPublishedEvent,
+      CompositionRoyaltySetEvent: composition.CompositionRoyaltySetEvent,
+      RecordingPublishedEvent: recording.RecordingPublishedEvent,
+      ReleasePublishedEvent: release.ReleasePublishedEvent,
+      DealCreatedEvent: deal.DealCreatedEvent,
+      DealAcceptedEvent: deal.DealAcceptedEvent,
+      DealRejectedEvent: deal.DealRejectedEvent,
+    };
+  }
+
+  // === Event parsers ===
+
+  get parse() {
+    return {
+      compositionPublishedEvent: parsers.parseCompositionPublishedEvent,
+      compositionRoyaltySetEvent: parsers.parseCompositionRoyaltySetEvent,
+      recordingPublishedEvent: parsers.parseRecordingPublishedEvent,
+      releasePublishedEvent: parsers.parseReleasePublishedEvent,
+      dealCreatedEvent: parsers.parseDealCreatedEvent,
+      dealAcceptedEvent: parsers.parseDealAcceptedEvent,
+      dealRejectedEvent: parsers.parseDealRejectedEvent,
+    };
+  }
+
+  #requireGraphQL(): SuiGraphQLClient {
+    if (!this.#graphqlClient) {
+      throw new Error("GraphQL client required. Pass graphqlClient to miso() options.");
+    }
+    return this.#graphqlClient;
+  }
+}

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