@misofm/api-client 0.5.0 → 0.5.2

package/dist/client.d.ts

@@ -0,0 +1,150 @@
+import type { z } from "zod";
+import { queryPolicy } from "./cache.js";
+import type { ArtistProfile, Balance, ListingView, OwnedParty, PendingMembership, OwnedRecord, OwnedWork, Ownership, PartySummary, PressingView, PurchaseReceipt, RecordAlbum, ReleaseDetail, WorkDetail } from "./types.js";
+export interface MisoRequestOptions {
+    /** Cancels this request without affecting other calls made by the client. */
+    signal?: AbortSignal;
+    /** Additional request headers. `Accept: application/json` is supplied by default. */
+    headers?: HeadersInit;
+}
+export interface MisoApiErrorOptions {
+    requestId?: string;
+    retryAfter?: number;
+}
+export declare class MisoApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Correlation id supplied by the API, when available. */
+    readonly requestId?: string;
+    /** Delay requested by `Retry-After`, normalized to seconds. */
+    readonly retryAfter?: number;
+    constructor(status: number, code: string, message: string, metadata?: MisoApiErrorOptions);
+}
+/**
+ * The server said something this client cannot describe. Distinct from
+ * `MisoApiError`: this indicates API/client version skew rather than an
+ * expected API outcome.
+ */
+export declare class MisoApiContractError extends Error {
+    readonly issues: z.core.$ZodIssue[];
+    /** Correlation id supplied by the API, when available. */
+    readonly requestId?: string;
+    constructor(path: string, issues: z.core.$ZodIssue[], metadata?: MisoApiErrorOptions);
+}
+export interface MisoApiClientOptions {
+    /** Public API origin, e.g. `https://api.testnet.miso.fm`. */
+    baseUrl: string;
+    /**
+     * Cache buster appended as `?v=` to mutable public reads only. A surface that
+     * has just written something and must see its own change supplies a fresh
+     * value here (see {@link cacheBuster}). Returning `undefined` sends no `v`.
+     *
+     * Private wallet reads and immutable receipts/base record-album reads ignore
+     * this value: they are either not shared-cached or can never become fresher.
+     */
+    version?: () => string | undefined;
+    /** Injectable for tests, Workers, and anything with its own fetch. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Path the read endpoints are mounted under on `baseUrl`. The gateway routes
+     * `/read/*` to the read service, whose own routes are rooted at `/v1`.
+     */
+    prefix?: string;
+}
+export type WalletOwnershipTarget = {
+    partyId: string;
+    recordId?: never;
+} | {
+    partyId?: never;
+    recordId: string;
+};
+export declare function createMisoApiClient(options: MisoApiClientOptions): {
+    getPressing: (pressingId: string, opts?: MisoRequestOptions) => Promise<PressingView | null>;
+    getPressingListing: (pressingId: string, currencyType: string, opts?: MisoRequestOptions) => Promise<ListingView | null>;
+    getRelease: (releaseId: string, opts?: MisoRequestOptions & {
+        include?: readonly "trackCredits"[];
+    }) => Promise<ReleaseDetail | null>;
+    getRecordAlbum: (recordId: string, opts?: MisoRequestOptions & {
+        include?: readonly ("release" | "trackCredits")[];
+    }) => Promise<RecordAlbum | null>;
+    getArtist: (partyId: string, opts?: MisoRequestOptions & {
+        include?: readonly ("roles" | "tags")[];
+    }) => Promise<ArtistProfile | null>;
+    listArtists: (ids: readonly string[], opts?: MisoRequestOptions) => Promise<PartySummary[]>;
+    listWalletRecords: (address: string, opts?: MisoRequestOptions) => Promise<OwnedRecord[]>;
+    listWalletParties: (address: string, opts?: MisoRequestOptions) => Promise<OwnedParty[]>;
+    listWalletPendingMemberships: (address: string, opts?: MisoRequestOptions) => Promise<PendingMembership[]>;
+    listWalletWorks: (address: string, opts?: MisoRequestOptions) => Promise<OwnedWork[]>;
+    getWork: (capId: string, opts?: MisoRequestOptions) => Promise<WorkDetail | null>;
+    getWalletBalance: (address: string, coinType?: string, opts?: MisoRequestOptions) => Promise<Balance>;
+    getWalletOwnership: (address: string, target: WalletOwnershipTarget, opts?: MisoRequestOptions) => Promise<Ownership>;
+    getWalletPartyOwnership: (address: string, partyId: string, opts?: MisoRequestOptions) => Promise<Ownership>;
+    getWalletRecordOwnership: (address: string, recordId: string, opts?: MisoRequestOptions) => Promise<Ownership>;
+    getPurchaseReceipt: (pressingId: string, txDigest: string, opts?: MisoRequestOptions) => Promise<PurchaseReceipt | null>;
+    /** @deprecated Use {@link getPressingListing}. */
+    getListing: (pressingId: string, currencyType: string, opts?: MisoRequestOptions) => Promise<ListingView | null>;
+    /** @deprecated Use {@link listArtists}. */
+    getArtists: (ids: readonly string[], opts?: MisoRequestOptions) => Promise<PartySummary[]>;
+    /** @deprecated Use {@link listWalletRecords}. */
+    getWalletRecords: (address: string, opts?: MisoRequestOptions) => Promise<OwnedRecord[]>;
+    /** @deprecated Use {@link listWalletParties}. */
+    getWalletParties: (address: string, opts?: MisoRequestOptions) => Promise<OwnedParty[]>;
+    /** @deprecated Use {@link listWalletPendingMemberships}. */
+    getPendingMemberships: (address: string, opts?: MisoRequestOptions) => Promise<PendingMembership[]>;
+    /** @deprecated Use {@link listWalletWorks}. */
+    getWalletWorks: (address: string, opts?: MisoRequestOptions) => Promise<OwnedWork[]>;
+    /** @deprecated Use {@link getWalletBalance}. */
+    getBalance: (address: string, coinType?: string, opts?: MisoRequestOptions) => Promise<Balance>;
+    /** @deprecated Use {@link getWalletPartyOwnership}. */
+    ownsParty: (address: string, partyId: string, opts?: MisoRequestOptions) => Promise<Ownership>;
+    /** @deprecated Use {@link getWalletRecordOwnership}. */
+    ownsRecord: (address: string, recordId: string, opts?: MisoRequestOptions) => Promise<Ownership>;
+    /** @deprecated Use {@link getPurchaseReceipt}. */
+    getReceipt: (pressingId: string, txDigest: string, opts?: MisoRequestOptions) => Promise<PurchaseReceipt | null>;
+};
+export type MisoApiClient = ReturnType<typeof createMisoApiClient>;
+/**
+ * A cache-buster value for {@link MisoApiClientOptions.version}.
+ *
+ * Call this once after a write lands on-chain, retain the returned value, and
+ * use it for the writer's subsequent mutable public reads. The timestamp keeps
+ * the bypass bounded; the random nonce prevents an attacker from pre-filling
+ * the exact URL before the writer reaches it.
+ */
+export declare function cacheBuster(nowMs?: number, nonce?: string): string;
+/**
+ * Static cache classes for callers aligning their query options with the edge.
+ * `getRelease` is response-dependent and therefore absent. `getRecordAlbum`
+ * describes only the unexpanded base response; use `recordAlbumQueryPolicy`
+ * when requesting relationship expansions.
+ *
+ * Legacy keys remain for source compatibility with existing applications.
+ */
+export declare const READ_CACHE_CLASS: {
+    readonly getPressing: "sale";
+    readonly getPressingListing: "sale";
+    readonly getListing: "sale";
+    readonly getRecordAlbum: "immutable";
+    readonly getPurchaseReceipt: "immutable";
+    readonly getReceipt: "immutable";
+    readonly getArtist: "artist";
+    readonly listArtists: "artist";
+    readonly getArtists: "artist";
+    readonly listWalletRecords: "private";
+    readonly getWalletRecords: "private";
+    readonly listWalletParties: "private";
+    readonly getWalletParties: "private";
+    readonly listWalletPendingMemberships: "private";
+    readonly getPendingMemberships: "private";
+    readonly listWalletWorks: "private";
+    readonly getWalletWorks: "private";
+    readonly getWork: "private";
+    readonly getWalletBalance: "private";
+    readonly getBalance: "private";
+    readonly getWalletOwnership: "private";
+    readonly getWalletPartyOwnership: "private";
+    readonly ownsParty: "private";
+    readonly getWalletRecordOwnership: "private";
+    readonly ownsRecord: "private";
+};
+export { queryPolicy };

package/dist/client.js

@@ -0,0 +1,265 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The typed client for the Miso read API. Every response is parsed at the
+// boundary so API/client version skew fails loudly and locally.
+import * as s from "./schemas.js";
+import { queryPolicy } from "./cache.js";
+export class MisoApiError extends Error {
+    status;
+    code;
+    /** Correlation id supplied by the API, when available. */
+    requestId;
+    /** Delay requested by `Retry-After`, normalized to seconds. */
+    retryAfter;
+    constructor(status, code, message, metadata = {}) {
+        super(message);
+        this.name = "MisoApiError";
+        this.status = status;
+        this.code = code;
+        this.requestId = metadata.requestId;
+        this.retryAfter = metadata.retryAfter;
+    }
+}
+function errorMetadata(headers) {
+    const requestId = headers.get("X-Request-Id")?.trim() || undefined;
+    const rawRetryAfter = headers.get("Retry-After")?.trim();
+    if (!rawRetryAfter)
+        return { requestId };
+    const seconds = Number(rawRetryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return { requestId, retryAfter: seconds };
+    const timestamp = Date.parse(rawRetryAfter);
+    return Number.isFinite(timestamp)
+        ? {
+            requestId,
+            retryAfter: Math.max(0, Math.ceil((timestamp - Date.now()) / 1000)),
+        }
+        : { requestId };
+}
+/**
+ * The server said something this client cannot describe. Distinct from
+ * `MisoApiError`: this indicates API/client version skew rather than an
+ * expected API outcome.
+ */
+export class MisoApiContractError extends Error {
+    issues;
+    /** Correlation id supplied by the API, when available. */
+    requestId;
+    constructor(path, issues, metadata = {}) {
+        const first = issues[0];
+        super(`Response from ${path} did not match the expected contract` +
+            (first ? `: ${first.path.join(".")} — ${first.message}` : "") +
+            ". The API and @misofm/api-client are likely different versions.");
+        this.name = "MisoApiContractError";
+        this.issues = issues;
+        this.requestId = metadata.requestId;
+    }
+}
+/** Encode exactly one dynamic route segment, including `/`, `%`, `?`, and `#`. */
+function segment(value) {
+    const encoded = encodeURIComponent(value);
+    // WHATWG URL parsing treats literal and percent-encoded `.` / `..` as path
+    // navigation. Double-encoding dot-only inputs keeps even hostile values in
+    // the one dynamic segment where the caller supplied them.
+    return encoded === "."
+        ? "%252E"
+        : encoded === ".."
+            ? "%252E%252E"
+            : encoded;
+}
+/** Add the default Accept header without requiring a global Headers constructor. */
+function requestHeaders(input) {
+    if (!input)
+        return { Accept: "application/json" };
+    const entries = [];
+    if (Array.isArray(input)) {
+        for (const [name, value] of input)
+            entries.push([name, value]);
+    }
+    else if (typeof input.forEach === "function") {
+        input.forEach((value, name) => entries.push([name, value]));
+    }
+    else if (typeof input[Symbol.iterator] === "function") {
+        for (const [name, value] of input) {
+            entries.push([name, value]);
+        }
+    }
+    else {
+        entries.push(...Object.entries(input));
+    }
+    if (!entries.some(([name]) => name.toLowerCase() === "accept")) {
+        entries.unshift(["Accept", "application/json"]);
+    }
+    return entries;
+}
+export function createMisoApiClient(options) {
+    const base = options.baseUrl.replace(/\/$/, "");
+    const prefix = options.prefix ?? "/read/v1";
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    function url(path, query = {}, mutable = false) {
+        const u = new URL(`${base}${prefix}${path}`);
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null && value !== "")
+                u.searchParams.set(key, String(value));
+        }
+        const version = mutable ? options.version?.() : undefined;
+        if (version)
+            u.searchParams.set("v", version);
+        return u.toString();
+    }
+    async function request(schema, path, query = {}, opts = {}) {
+        const target = url(path, query, opts.mutable);
+        const response = await doFetch(target, {
+            headers: requestHeaders(opts.headers),
+            signal: opts.signal,
+        });
+        if (response.status === 404 && opts.nullOn404)
+            return null;
+        if (!response.ok) {
+            const body = await response.json().catch(() => null);
+            const parsed = s.apiErrorSchema.safeParse(body);
+            const metadata = errorMetadata(response.headers);
+            throw parsed.success
+                ? new MisoApiError(response.status, parsed.data.error.code, parsed.data.error.message, metadata)
+                : new MisoApiError(response.status, "unknown", `Request to ${path} failed (${response.status})`, metadata);
+        }
+        const json = await response.json().catch(() => {
+            throw new MisoApiError(response.status, "bad_response", `Response from ${path} was not JSON`, errorMetadata(response.headers));
+        });
+        const parsed = schema.safeParse(json);
+        if (!parsed.success)
+            throw new MisoApiContractError(path, parsed.error.issues, errorMetadata(response.headers));
+        return parsed.data;
+    }
+    async function required(schema, path, query, opts) {
+        return (await request(schema, path, query, opts));
+    }
+    // Each implementation is defined once so compatibility aliases cannot drift.
+    const getPressing = (pressingId, opts = {}) => request(s.pressingViewSchema, `/pressings/${segment(pressingId)}`, {}, {
+        ...opts,
+        nullOn404: true,
+        mutable: true,
+    });
+    const getPressingListing = (pressingId, currencyType, opts = {}) => request(s.listingViewSchema, `/pressings/${segment(pressingId)}/listing`, { currencyType }, { ...opts, nullOn404: true, mutable: true });
+    const getRelease = (releaseId, opts = {}) => request(s.releaseDetailSchema, `/releases/${segment(releaseId)}`, { include: opts.include?.join(",") }, { ...opts, nullOn404: true, mutable: true });
+    const getRecordAlbum = (recordId, opts = {}) => request(s.recordAlbumSchema, `/records/${segment(recordId)}/album`, { include: opts.include?.join(",") }, {
+        ...opts,
+        nullOn404: true,
+        // The relation is immutable; expanded release metadata can change.
+        mutable: (opts.include?.length ?? 0) > 0,
+    });
+    const getArtist = (partyId, opts = {}) => request(s.artistProfileSchema, `/artists/${segment(partyId)}`, { include: opts.include?.join(",") }, { ...opts, nullOn404: true, mutable: true });
+    const listArtists = (ids, opts = {}) => ids.length === 0
+        ? Promise.resolve([])
+        : required(s.partySummariesSchema, "/artists", { ids: ids.join(",") }, {
+            ...opts,
+            mutable: true,
+        });
+    const listWalletRecords = (address, opts = {}) => required(s.ownedRecordsSchema, `/wallets/${segment(address)}/records`, {}, opts);
+    const listWalletParties = (address, opts = {}) => required(s.ownedPartiesSchema, `/wallets/${segment(address)}/parties`, {}, opts);
+    const listWalletPendingMemberships = (address, opts = {}) => required(s.pendingMembershipsSchema, `/wallets/${segment(address)}/pending-memberships`, {}, opts);
+    const listWalletWorks = (address, opts = {}) => required(s.ownedWorksSchema, `/wallets/${segment(address)}/works`, {}, opts);
+    const getWork = (capId, opts = {}) => request(s.workDetailSchema, `/works/${segment(capId)}`, {}, {
+        ...opts,
+        nullOn404: true,
+    });
+    const getWalletBalance = (address, coinType, opts = {}) => required(s.balanceSchema, `/wallets/${segment(address)}/balance`, { coinType }, opts);
+    const getWalletPartyOwnership = (address, partyId, opts = {}) => required(s.ownershipSchema, `/wallets/${segment(address)}/owns`, { party: partyId }, opts);
+    const getWalletOwnership = (address, target, opts = {}) => required(s.ownershipSchema, `/wallets/${segment(address)}/owns`, {
+        party: target.partyId,
+        record: target.recordId,
+    }, opts);
+    const getWalletRecordOwnership = (address, recordId, opts = {}) => required(s.ownershipSchema, `/wallets/${segment(address)}/owns`, { record: recordId }, opts);
+    const getPurchaseReceipt = (pressingId, txDigest, opts = {}) => request(s.purchaseReceiptSchema, `/receipts/${segment(pressingId)}/${segment(txDigest)}`, {}, { ...opts, nullOn404: true });
+    return {
+        getPressing,
+        getPressingListing,
+        getRelease,
+        getRecordAlbum,
+        getArtist,
+        listArtists,
+        listWalletRecords,
+        listWalletParties,
+        listWalletPendingMemberships,
+        listWalletWorks,
+        getWork,
+        getWalletBalance,
+        getWalletOwnership,
+        getWalletPartyOwnership,
+        getWalletRecordOwnership,
+        getPurchaseReceipt,
+        /** @deprecated Use {@link getPressingListing}. */
+        getListing: getPressingListing,
+        /** @deprecated Use {@link listArtists}. */
+        getArtists: listArtists,
+        /** @deprecated Use {@link listWalletRecords}. */
+        getWalletRecords: listWalletRecords,
+        /** @deprecated Use {@link listWalletParties}. */
+        getWalletParties: listWalletParties,
+        /** @deprecated Use {@link listWalletPendingMemberships}. */
+        getPendingMemberships: listWalletPendingMemberships,
+        /** @deprecated Use {@link listWalletWorks}. */
+        getWalletWorks: listWalletWorks,
+        /** @deprecated Use {@link getWalletBalance}. */
+        getBalance: getWalletBalance,
+        /** @deprecated Use {@link getWalletPartyOwnership}. */
+        ownsParty: getWalletPartyOwnership,
+        /** @deprecated Use {@link getWalletRecordOwnership}. */
+        ownsRecord: getWalletRecordOwnership,
+        /** @deprecated Use {@link getPurchaseReceipt}. */
+        getReceipt: getPurchaseReceipt,
+    };
+}
+/**
+ * A cache-buster value for {@link MisoApiClientOptions.version}.
+ *
+ * Call this once after a write lands on-chain, retain the returned value, and
+ * use it for the writer's subsequent mutable public reads. The timestamp keeps
+ * the bypass bounded; the random nonce prevents an attacker from pre-filling
+ * the exact URL before the writer reaches it.
+ */
+export function cacheBuster(nowMs = Date.now(), nonce = crypto.getRandomValues(new Uint32Array(1))[0]
+    .toString(16)
+    .padStart(8, "0")) {
+    if (!/^[0-9a-fA-F]{8}$/.test(nonce)) {
+        throw new RangeError("cacheBuster nonce must be exactly 8 hexadecimal characters.");
+    }
+    return `${Math.floor(nowMs / 1000)}-${nonce.toLowerCase()}`;
+}
+/**
+ * Static cache classes for callers aligning their query options with the edge.
+ * `getRelease` is response-dependent and therefore absent. `getRecordAlbum`
+ * describes only the unexpanded base response; use `recordAlbumQueryPolicy`
+ * when requesting relationship expansions.
+ *
+ * Legacy keys remain for source compatibility with existing applications.
+ */
+export const READ_CACHE_CLASS = {
+    getPressing: "sale",
+    getPressingListing: "sale",
+    getListing: "sale",
+    getRecordAlbum: "immutable",
+    getPurchaseReceipt: "immutable",
+    getReceipt: "immutable",
+    getArtist: "artist",
+    listArtists: "artist",
+    getArtists: "artist",
+    listWalletRecords: "private",
+    getWalletRecords: "private",
+    listWalletParties: "private",
+    getWalletParties: "private",
+    listWalletPendingMemberships: "private",
+    getPendingMemberships: "private",
+    listWalletWorks: "private",
+    getWalletWorks: "private",
+    getWork: "private",
+    getWalletBalance: "private",
+    getBalance: "private",
+    getWalletOwnership: "private",
+    getWalletPartyOwnership: "private",
+    ownsParty: "private",
+    getWalletRecordOwnership: "private",
+    ownsRecord: "private",
+};
+export { queryPolicy };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createMisoApiClient, cacheBuster, MisoApiError, MisoApiContractError, READ_CACHE_CLASS, queryPolicy } from "./client.js";
+export type { MisoApiClient, MisoApiClientOptions, MisoApiErrorOptions, MisoRequestOptions, WalletOwnershipTarget } from "./client.js";
+export { CACHE_POLICIES, browserCacheControl, cacheControl, cdnCacheControl, workCacheClass, recordAlbumCacheClass, recordAlbumQueryPolicy } from "./cache.js";
+export type { CacheClass, CachePolicy, RecordAlbumCacheOptions, RecordAlbumCacheValue } from "./cache.js";
+export * as schemas from "./schemas.js";
+export type * from "./types.js";

package/{src/index.ts → dist/index.js}

@@ -10,12 +10,6 @@
 //
 //   import { createMisoApiClient } from "@misofm/api-client";
 //   const api = createMisoApiClient({ baseUrl: "https://api.testnet.miso.fm" });
-
-export { createMisoApiClient, cacheBuster, MisoApiError, MisoApiContractError, READ_CACHE_CLASS, queryPolicy } from "./client.ts";
-export type { MisoApiClient, MisoApiClientOptions } from "./client.ts";
-
-export { CACHE_POLICIES, cacheControl, workCacheClass } from "./cache.ts";
-export type { CacheClass, CachePolicy } from "./cache.ts";
-
-export * as schemas from "./schemas.ts";
-export type * from "./types.ts";
+export { createMisoApiClient, cacheBuster, MisoApiError, MisoApiContractError, READ_CACHE_CLASS, queryPolicy } from "./client.js";
+export { CACHE_POLICIES, browserCacheControl, cacheControl, cdnCacheControl, workCacheClass, recordAlbumCacheClass, recordAlbumQueryPolicy } from "./cache.js";
+export * as schemas from "./schemas.js";