@misofm/platform 0.0.0 → 0.18.0

package/package.json

@@ -1,10 +1,150 @@
 {
   "name": "@misofm/platform",
-  "version": "0.0.0",
-  "description": "Placeholder reserving @misofm/platform. Not usable — see the real release.",
+  "version": "0.18.0",
+  "packageManager": "bun@1.4.0",
+  "description": "Complete client SDK for the Miso platform on Sui — high-level reads, pressings, listings, records, and work publishing.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/misofm/sdk.git" },
-  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/misofm/sdks.git"
+  },
+  "homepage": "https://github.com/misofm/sdks#readme",
+  "bugs": {
+    "url": "https://github.com/misofm/sdks/issues"
+  },
+  "keywords": [
+    "sui",
+    "move",
+    "miso",
+    "music",
+    "blockchain",
+    "sdk",
+    "pressing"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "type": "module",
-  "files": ["README.md"]
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./deployments": {
+      "types": "./dist/deployments.d.ts",
+      "default": "./dist/deployments.js"
+    },
+    "./pressing": {
+      "types": "./dist/pressing.d.ts",
+      "default": "./dist/pressing.js"
+    },
+    "./transactions": {
+      "types": "./dist/transactions.d.ts",
+      "default": "./dist/transactions.js"
+    },
+    "./execute": {
+      "types": "./dist/execute.d.ts",
+      "default": "./dist/execute.js"
+    },
+    "./share": {
+      "types": "./dist/share.d.ts",
+      "default": "./dist/share.js"
+    },
+    "./share-template": {
+      "types": "./dist/share-template.d.ts",
+      "default": "./dist/share-template.js"
+    },
+    "./release-graph": {
+      "types": "./dist/release-graph.d.ts",
+      "default": "./dist/release-graph.js"
+    },
+    "./publication": {
+      "types": "./dist/publication.d.ts",
+      "default": "./dist/publication.js"
+    },
+    "./catalog": {
+      "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"
+    },
+    "./release-extensions": {
+      "types": "./dist/release-extensions.d.ts",
+      "default": "./dist/release-extensions.js"
+    },
+    "./recording-extensions": {
+      "types": "./dist/recording-extensions.d.ts",
+      "default": "./dist/recording-extensions.js"
+    },
+    "./mix": {
+      "types": "./dist/mix.d.ts",
+      "default": "./dist/mix.js"
+    },
+    "./read": {
+      "types": "./dist/read/index.d.ts",
+      "default": "./dist/read/index.js"
+    },
+    "./read/types": {
+      "types": "./dist/read/types.d.ts",
+      "default": "./dist/read/types.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "default": "./dist/auth.js"
+    },
+    "./vault": {
+      "types": "./dist/vault.d.ts",
+      "default": "./dist/vault.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "codegen": "sui-ts-codegen generate && bun run codegen:format",
+    "codegen:format": "bun scripts/format-codegen.ts",
+    "codegen:check": "bun run codegen && git diff --exit-code -- src/contracts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepare": "rm -rf dist && tsc -p tsconfig.build.json --noCheck"
+  },
+  "dependencies": {
+    "@misofm/protocol": "0.12.0",
+    "@mysten/bcs": "^2.1.1"
+  },
+  "devDependencies": {
+    "@mysten/codegen": "^0.11.14",
+    "@mysten/move-bytecode-template": "^0.4.0",
+    "@mysten/seal": "1.4.6",
+    "@mysten/sui": "2.29.0",
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@mysten/move-bytecode-template": "^0.4.0",
+    "@mysten/seal": "1.4.6",
+    "@mysten/sui": "2.29.0",
+    "typescript": "^5.7 || ^6 || ^7"
+  },
+  "main": "./dist/index.js"
 }

package/src/auth.ts

@@ -0,0 +1,275 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isValidSuiAddress, normalizeSuiAddress } from "@mysten/sui/utils";
+
+export type AuthNetwork = "testnet" | "mainnet";
+
+export interface ApiAuthorizationFields {
+  method: string;
+  path: string;
+  address: string;
+  network: AuthNetwork;
+  issuedAt: string;
+}
+
+export interface AuthorizationChallenge extends ApiAuthorizationFields {
+  payload: string;
+  expiresAt: string;
+}
+
+export interface PersonalMessageSigner {
+  signPersonalMessage(message: Uint8Array): Promise<{ signature: string; bytes?: string }>;
+}
+
+export const AUTHORIZATION_MAX_AGE_MS = 5 * 60 * 1_000;
+export const AUTHORIZATION_FUTURE_SKEW_MS = 60 * 1_000;
+
+export const MISO_AUTH_HEADERS = {
+  address: "X-Sui-Address",
+  signature: "X-Sui-Signature",
+  issuedAt: "X-Sui-Issued-At",
+} as const;
+
+export type MisoAuthErrorCode =
+  | "invalid_target"
+  | "challenge_rejected"
+  | "invalid_challenge"
+  | "signing_failed";
+
+export class MisoAuthError extends Error {
+  readonly code: MisoAuthErrorCode;
+  readonly status?: number;
+
+  constructor(code: MisoAuthErrorCode, message: string, options: { status?: number; cause?: unknown } = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "MisoAuthError";
+    this.code = code;
+    this.status = options.status;
+  }
+}
+
+/** The byte-exact Sui personal message required for an authenticated API mutation. */
+export function buildApiAuthorizationPayload(fields: ApiAuthorizationFields): string {
+  return [
+    "miso.fm API authorization v1",
+    "",
+    `Method: ${fields.method.toUpperCase()}`,
+    `Path: ${fields.path}`,
+    `Address: ${fields.address}`,
+    `Network: ${fields.network}`,
+    `Issued At: ${fields.issuedAt}`,
+  ].join("\n");
+}
+
+export function isValidAuthorizationTarget(method: string, path: string): boolean {
+  return (
+    ["POST", "PUT", "PATCH", "DELETE"].includes(method.toUpperCase()) &&
+    path.startsWith("/platform/") &&
+    path.length <= 2_048 &&
+    !/[\r\n?#]/.test(path)
+  );
+}
+
+/** Accept only fresh timestamps in one canonical spelling. */
+export function parseFreshAuthorizationIssuedAt(input: unknown, nowMs: number = Date.now()): string | null {
+  if (typeof input !== "string") return null;
+  const issuedAtMs = Date.parse(input);
+  if (!Number.isFinite(issuedAtMs)) return null;
+  if (
+    issuedAtMs > nowMs + AUTHORIZATION_FUTURE_SKEW_MS ||
+    nowMs - issuedAtMs > AUTHORIZATION_MAX_AGE_MS
+  ) {
+    return null;
+  }
+  const canonical = new Date(issuedAtMs).toISOString();
+  return input === canonical ? canonical : null;
+}
+
+function target(method: string, path: string): { method: string; path: string } {
+  const normalized = { method: method.toUpperCase(), path };
+  if (!isValidAuthorizationTarget(normalized.method, normalized.path)) {
+    throw new MisoAuthError("invalid_target", "Authenticated requests require a mutation under /platform/.");
+  }
+  return normalized;
+}
+
+function parseChallenge(
+  input: unknown,
+  expected: { method: string; path: string; address: string; network?: AuthNetwork; nowMs?: number },
+): AuthorizationChallenge {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new MisoAuthError("invalid_challenge", "The API returned an invalid authorization challenge.");
+  }
+  const body = input as Partial<Record<keyof AuthorizationChallenge, unknown>>;
+  if (
+    typeof body.payload !== "string" ||
+    typeof body.method !== "string" ||
+    typeof body.path !== "string" ||
+    typeof body.address !== "string" ||
+    typeof body.network !== "string" ||
+    typeof body.issuedAt !== "string" ||
+    typeof body.expiresAt !== "string" ||
+    !isValidSuiAddress(body.address) ||
+    (body.network !== "testnet" && body.network !== "mainnet")
+  ) {
+    throw new MisoAuthError("invalid_challenge", "The API returned an invalid authorization challenge.");
+  }
+
+  const nowMs = expected.nowMs ?? Date.now();
+  const issuedAt = parseFreshAuthorizationIssuedAt(body.issuedAt, nowMs);
+  const expiresAtMs = Date.parse(body.expiresAt);
+  const canonicalAddress = normalizeSuiAddress(body.address);
+  const expectedAddress = normalizeSuiAddress(expected.address);
+  const challenge: AuthorizationChallenge = {
+    payload: body.payload,
+    method: body.method,
+    path: body.path,
+    address: canonicalAddress,
+    network: body.network,
+    issuedAt: body.issuedAt,
+    expiresAt: body.expiresAt,
+  };
+  const canonicalExpiresAt = Number.isFinite(expiresAtMs) ? new Date(expiresAtMs).toISOString() : "";
+
+  if (
+    !issuedAt ||
+    body.method !== expected.method ||
+    body.path !== expected.path ||
+    canonicalAddress !== expectedAddress ||
+    (expected.network !== undefined && body.network !== expected.network) ||
+    body.expiresAt !== canonicalExpiresAt ||
+    expiresAtMs <= nowMs ||
+    expiresAtMs > Date.parse(issuedAt) + AUTHORIZATION_MAX_AGE_MS ||
+    body.payload !== buildApiAuthorizationPayload(challenge)
+  ) {
+    throw new MisoAuthError("invalid_challenge", "The authorization challenge did not match this request.");
+  }
+  return challenge;
+}
+
+async function responseMessage(response: Response): Promise<string> {
+  const body = await response.clone().json().catch(() => null) as {
+    error?: { message?: unknown } | string;
+    message?: unknown;
+  } | null;
+  if (typeof body?.error === "object" && typeof body.error.message === "string") return body.error.message;
+  if (typeof body?.error === "string") return body.error;
+  if (typeof body?.message === "string") return body.message;
+  return `Authorization challenge failed (${response.status}).`;
+}
+
+export interface RequestAuthorizationChallengeOptions {
+  apiUrl: string | URL;
+  token: string;
+  address: string;
+  method: string;
+  path: string;
+  network?: AuthNetwork;
+  challengeUrl?: string | URL;
+  fetch?: typeof globalThis.fetch;
+  nowMs?: number;
+}
+
+/** Ask Miso to verify the Enoki account and issue the exact message to sign. */
+export async function requestAuthorizationChallenge(
+  options: RequestAuthorizationChallengeOptions,
+): Promise<AuthorizationChallenge> {
+  const expected = target(options.method, options.path);
+  if (!options.token || !isValidSuiAddress(options.address)) {
+    throw new MisoAuthError("challenge_rejected", "A valid Enoki token and Sui address are required.");
+  }
+  const apiUrl = new URL(options.apiUrl);
+  const challengeUrl = options.challengeUrl === undefined
+    ? new URL("/platform/auth/challenge", apiUrl.origin)
+    : new URL(options.challengeUrl, apiUrl);
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const response = await fetcher(challengeUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${options.token}`,
+      [MISO_AUTH_HEADERS.address]: normalizeSuiAddress(options.address),
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(expected),
+  });
+  if (!response.ok) {
+    throw new MisoAuthError("challenge_rejected", await responseMessage(response), { status: response.status });
+  }
+  const body = await response.json().catch(() => null);
+  return parseChallenge(body, {
+    ...expected,
+    address: options.address,
+    network: options.network,
+    nowMs: options.nowMs,
+  });
+}
+
+export interface CreateAuthorizationHeadersOptions extends RequestAuthorizationChallengeOptions {
+  signer: PersonalMessageSigner;
+}
+
+/** Verify the challenge locally, sign it as a Sui personal message, and produce API headers. */
+export async function createAuthorizationHeaders(
+  options: CreateAuthorizationHeadersOptions,
+): Promise<{ challenge: AuthorizationChallenge; headers: Headers }> {
+  const challenge = await requestAuthorizationChallenge(options);
+  let signature: string;
+  try {
+    const signed = await options.signer.signPersonalMessage(new TextEncoder().encode(challenge.payload));
+    signature = signed.signature;
+  } catch (cause) {
+    throw new MisoAuthError("signing_failed", "The authorization request was not signed.", { cause });
+  }
+  if (!signature) {
+    throw new MisoAuthError("signing_failed", "The signer returned an empty authorization signature.");
+  }
+  return {
+    challenge,
+    headers: new Headers({
+      Authorization: `Bearer ${options.token}`,
+      [MISO_AUTH_HEADERS.address]: challenge.address,
+      [MISO_AUTH_HEADERS.signature]: signature,
+      [MISO_AUTH_HEADERS.issuedAt]: challenge.issuedAt,
+    }),
+  };
+}
+
+export interface AuthenticatedFetchOptions extends RequestInit {
+  auth: {
+    token: string;
+    address: string;
+    signer: PersonalMessageSigner;
+    network?: AuthNetwork;
+  };
+  challengeUrl?: string | URL;
+  fetch?: typeof globalThis.fetch;
+}
+
+/** Perform a protected Miso API mutation with a fresh Enoki-verified Sui signature. */
+export async function authenticatedFetch(
+  input: string | URL,
+  options: AuthenticatedFetchOptions,
+): Promise<Response> {
+  const { auth, challengeUrl, fetch: fetchOption, ...init } = options;
+  const url = new URL(input);
+  const method = (init.method ?? "").toUpperCase();
+  if (url.search || url.hash) {
+    throw new MisoAuthError("invalid_target", "Authenticated request URLs cannot include a query or fragment.");
+  }
+  const fetcher = fetchOption ?? globalThis.fetch;
+  const authorization = await createAuthorizationHeaders({
+    apiUrl: url,
+    challengeUrl,
+    fetch: fetcher,
+    token: auth.token,
+    address: auth.address,
+    signer: auth.signer,
+    network: auth.network,
+    method,
+    path: url.pathname,
+  });
+  const headers = new Headers(init.headers);
+  authorization.headers.forEach((value, name) => headers.set(name, value));
+  return fetcher(url, { ...init, method, headers });
+}

package/src/catalog.ts

@@ -0,0 +1,189 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Composed catalog reads.
+//
+// `@misofm/protocol` exposes one-question reads: fetch an object by id, list the
+// caps an address owns, resolve a share type to its work. Stitching several of
+// those together to answer a PRODUCT question — "show me everything this artist
+// administers" — is orchestration, and it lives here for the same reason the
+// opinionated publish flows do: it picks a traversal strategy, decides how much
+// to fetch, and chooses a concurrency/rate-limit tradeoff. Those are platform
+// calls, not protocol facts.
+
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import type { SuiGraphQLClient } from "@mysten/sui/graphql";
+import {
+  extractTypeParams2,
+  getOwnedRecordingAdminCaps,
+  getRecordingsByIds,
+  getReleaseById,
+  type Recording,
+} from "@misofm/protocol";
+import { getWorkAddressesByShareTypes } from "./read/works.ts";
+import {
+  getCompositionCreditsByIds,
+  getRecordingCreditsByIds,
+  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)];
+  if (recordingIds.length === 0) return {};
+
+  const [recordingCreditsById, recordingObjects] = await Promise.all([
+    getRecordingCreditsByIds(
+      client,
+      recordingIds,
+      options.recordingCreditsPackageId,
+    ),
+    client.core.getObjects({ objectIds: recordingIds }),
+  ]);
+  const recordingReads = recordingObjects.objects.map((object, index) => {
+    const recordingId = recordingIds[index]!;
+    if (object instanceof Error) throw object;
+    const [, compositionShareType] = extractTypeParams2(object.type);
+    return {
+      recordingId,
+      recordingCredits: recordingCreditsById[recordingId] ?? null,
+      compositionShareType,
+    };
+  });
+
+  const compositionShareTypes = [
+    ...new Set(recordingReads.map((read) => read.compositionShareType)),
+  ];
+  const addresses = await getWorkAddressesByShareTypes(
+    graphqlClient,
+    { compositions: compositionShareTypes, recordings: [] },
+    options.misoPackageId,
+  );
+  for (const shareType of compositionShareTypes) {
+    if (!addresses.compositions[shareType]) {
+      throw new Error(`Composition not found for share type: ${shareType}`);
+    }
+  }
+  const compositionIds = [
+    ...new Set(
+      Object.values(addresses.compositions).filter(
+        (id): id is string => id !== undefined,
+      ),
+    ),
+  ];
+  const compositionCreditsById = await getCompositionCreditsByIds(
+    client,
+    compositionIds,
+    options.compositionCreditsPackageId,
+  );
+
+  return Object.fromEntries(
+    recordingReads.map((read) => {
+      const compositionId = addresses.compositions[read.compositionShareType]!;
+      return [
+        read.recordingId,
+        {
+          compositionCredits: compositionCreditsById[compositionId] ?? [],
+          recordingCredits: read.recordingCredits ?? EMPTY_RECORDING_CREDITS,
+        },
+      ];
+    }),
+  );
+}
+
+export interface GetAdministeredRecordingsOptions {
+  /**
+   * @deprecated Resolution is batched; this option is retained for source
+   * compatibility and no longer affects request concurrency.
+   */
+  concurrency?: number;
+}
+
+/**
+ * Every `Recording` administered by `owner`.
+ *
+ * Three bounded stages: list the owner's `RecordingAdminCap`s, resolve every
+ * share type in one aliased GraphQL query, then batch-fetch the recordings.
+ */
+export async function getAdministeredRecordings(
+  client: ClientWithCoreApi,
+  graphqlClient: SuiGraphQLClient,
+  owner: string,
+  misoPackageId: string,
+  options: GetAdministeredRecordingsOptions = {},
+): Promise<Recording[]> {
+  void options;
+  const caps = await getOwnedRecordingAdminCaps(client, owner, misoPackageId);
+  if (caps.length === 0) return [];
+  const addresses = await getWorkAddressesByShareTypes(
+    graphqlClient,
+    { compositions: [], recordings: caps.map((cap) => cap.shareType) },
+    misoPackageId,
+  );
+  const byId = await getRecordingsByIds(
+    client,
+    Object.values(addresses.recordings).filter(
+      (id): id is string => id !== undefined,
+    ),
+  );
+  return caps.flatMap((cap) => {
+    const id = addresses.recordings[cap.shareType];
+    const recording = id ? byId[id] : undefined;
+    return recording ? [recording] : [];
+  });
+}