@medialane/sdk 0.3.2 → 0.4.1

package/README.md

@@ -181,7 +181,14 @@ const history = await client.api.getTokenHistory(contract, tokenId);
 ### Query Collections
 
 ```typescript
+// All collections — newest first by default
 const collections = await client.api.getCollections();
+
+// With sort and pagination
+const byVolume = await client.api.getCollections(1, 20, undefined, "volume");
+const verified = await client.api.getCollections(1, 18, true, "recent");
+
+// Sort options: "recent" | "supply" | "floor" | "volume" | "name"
 const collection = await client.api.getCollection(contract);
 const tokens = await client.api.getCollectionTokens(contract);
 ```
@@ -406,6 +413,10 @@ Built with:
 
 ## Changelog
 
+### v0.3.3
+- `getCollections(page?, limit?, isKnown?, sort?)` — added `sort` parameter: `"recent"` (default) | `"supply"` | `"floor"` | `"volume"` | `"name"`
+- Default sort changed from `totalSupply DESC` to `createdAt DESC` (newest first) — matches backend default
+
 ### v0.3.1
 - `ApiCollection.collectionId: string | null` — on-chain registry numeric ID (decimal string). Required for `createMintIntent`. Populated for collections indexed after 2026-03-09.
 

package/dist/index.cjs

@@ -8,6 +8,8 @@ var starknet = require('starknet');
 // src/constants.ts
 var MARKETPLACE_CONTRACT_MAINNET = "0x04299b51289aa700de4ce19cc77bcea8430bfd1aef04193efab09d60a3a7ee0f";
 var COLLECTION_CONTRACT_MAINNET = "0x05e73b7be06d82beeb390a0e0d655f2c9e7cf519658e04f05d9c690ccc41da03";
+var MARKETPLACE_CONTRACT_SEPOLIA = "";
+var COLLECTION_CONTRACT_SEPOLIA = "";
 var SUPPORTED_TOKENS = [
   {
     // Circle-native USDC on Starknet (canonical — preferred)
@@ -44,122 +46,6 @@ var DEFAULT_RPC_URLS = {
   sepolia: "https://rpc.starknet-sepolia.lava.build"
 };
 
-// src/config.ts
-var MedialaneConfigSchema = zod.z.object({
-  network: zod.z.enum(SUPPORTED_NETWORKS).default("mainnet"),
-  rpcUrl: zod.z.string().url().optional(),
-  backendUrl: zod.z.string().url().optional(),
-  /** API key for authenticated /v1/* backend endpoints */
-  apiKey: zod.z.string().optional(),
-  marketplaceContract: zod.z.string().optional(),
-  collectionContract: zod.z.string().optional()
-});
-function resolveConfig(raw) {
-  const parsed = MedialaneConfigSchema.parse(raw);
-  return {
-    network: parsed.network,
-    rpcUrl: parsed.rpcUrl ?? DEFAULT_RPC_URLS[parsed.network],
-    backendUrl: parsed.backendUrl,
-    apiKey: parsed.apiKey,
-    marketplaceContract: parsed.marketplaceContract ?? MARKETPLACE_CONTRACT_MAINNET,
-    collectionContract: parsed.collectionContract ?? COLLECTION_CONTRACT_MAINNET
-  };
-}
-function buildOrderTypedData(message, chainId) {
-  return {
-    domain: {
-      name: "Medialane",
-      version: "1",
-      chainId,
-      revision: starknet.TypedDataRevision.ACTIVE
-    },
-    primaryType: "OrderParameters",
-    types: {
-      StarknetDomain: [
-        { name: "name", type: "shortstring" },
-        { name: "version", type: "shortstring" },
-        { name: "chainId", type: "shortstring" },
-        { name: "revision", type: "shortstring" }
-      ],
-      OrderParameters: [
-        { name: "offerer", type: "ContractAddress" },
-        { name: "offer", type: "OfferItem" },
-        { name: "consideration", type: "ConsiderationItem" },
-        { name: "start_time", type: "felt" },
-        { name: "end_time", type: "felt" },
-        { name: "salt", type: "felt" },
-        { name: "nonce", type: "felt" }
-      ],
-      OfferItem: [
-        { name: "item_type", type: "shortstring" },
-        { name: "token", type: "ContractAddress" },
-        { name: "identifier_or_criteria", type: "felt" },
-        { name: "start_amount", type: "felt" },
-        { name: "end_amount", type: "felt" }
-      ],
-      ConsiderationItem: [
-        { name: "item_type", type: "shortstring" },
-        { name: "token", type: "ContractAddress" },
-        { name: "identifier_or_criteria", type: "felt" },
-        { name: "start_amount", type: "felt" },
-        { name: "end_amount", type: "felt" },
-        { name: "recipient", type: "ContractAddress" }
-      ]
-    },
-    message
-  };
-}
-function buildFulfillmentTypedData(message, chainId) {
-  return {
-    domain: {
-      name: "Medialane",
-      version: "1",
-      chainId,
-      revision: starknet.TypedDataRevision.ACTIVE
-    },
-    primaryType: "OrderFulfillment",
-    types: {
-      StarknetDomain: [
-        { name: "name", type: "shortstring" },
-        { name: "version", type: "shortstring" },
-        { name: "chainId", type: "shortstring" },
-        { name: "revision", type: "shortstring" }
-      ],
-      OrderFulfillment: [
-        { name: "order_hash", type: "felt" },
-        { name: "fulfiller", type: "ContractAddress" },
-        { name: "nonce", type: "felt" }
-      ]
-    },
-    message
-  };
-}
-function buildCancellationTypedData(message, chainId) {
-  return {
-    domain: {
-      name: "Medialane",
-      version: "1",
-      chainId,
-      revision: starknet.TypedDataRevision.ACTIVE
-    },
-    primaryType: "OrderCancellation",
-    types: {
-      StarknetDomain: [
-        { name: "name", type: "shortstring" },
-        { name: "version", type: "shortstring" },
-        { name: "chainId", type: "shortstring" },
-        { name: "revision", type: "shortstring" }
-      ],
-      OrderCancellation: [
-        { name: "order_hash", type: "felt" },
-        { name: "offerer", type: "ContractAddress" },
-        { name: "nonce", type: "felt" }
-      ]
-    },
-    message
-  };
-}
-
 // src/abis.ts
 var IPMarketplaceABI = [
   {
@@ -512,11 +398,106 @@ function getTokenBySymbol(symbol) {
   const upper = symbol.toUpperCase();
   return SUPPORTED_TOKENS.find((t) => t.symbol === upper);
 }
+function buildOrderTypedData(message, chainId) {
+  return {
+    domain: {
+      name: "Medialane",
+      version: "1",
+      chainId,
+      revision: starknet.TypedDataRevision.ACTIVE
+    },
+    primaryType: "OrderParameters",
+    types: {
+      StarknetDomain: [
+        { name: "name", type: "shortstring" },
+        { name: "version", type: "shortstring" },
+        { name: "chainId", type: "shortstring" },
+        { name: "revision", type: "shortstring" }
+      ],
+      OrderParameters: [
+        { name: "offerer", type: "ContractAddress" },
+        { name: "offer", type: "OfferItem" },
+        { name: "consideration", type: "ConsiderationItem" },
+        { name: "start_time", type: "felt" },
+        { name: "end_time", type: "felt" },
+        { name: "salt", type: "felt" },
+        { name: "nonce", type: "felt" }
+      ],
+      OfferItem: [
+        { name: "item_type", type: "shortstring" },
+        { name: "token", type: "ContractAddress" },
+        { name: "identifier_or_criteria", type: "felt" },
+        { name: "start_amount", type: "felt" },
+        { name: "end_amount", type: "felt" }
+      ],
+      ConsiderationItem: [
+        { name: "item_type", type: "shortstring" },
+        { name: "token", type: "ContractAddress" },
+        { name: "identifier_or_criteria", type: "felt" },
+        { name: "start_amount", type: "felt" },
+        { name: "end_amount", type: "felt" },
+        { name: "recipient", type: "ContractAddress" }
+      ]
+    },
+    message
+  };
+}
+function buildFulfillmentTypedData(message, chainId) {
+  return {
+    domain: {
+      name: "Medialane",
+      version: "1",
+      chainId,
+      revision: starknet.TypedDataRevision.ACTIVE
+    },
+    primaryType: "OrderFulfillment",
+    types: {
+      StarknetDomain: [
+        { name: "name", type: "shortstring" },
+        { name: "version", type: "shortstring" },
+        { name: "chainId", type: "shortstring" },
+        { name: "revision", type: "shortstring" }
+      ],
+      OrderFulfillment: [
+        { name: "order_hash", type: "felt" },
+        { name: "fulfiller", type: "ContractAddress" },
+        { name: "nonce", type: "felt" }
+      ]
+    },
+    message
+  };
+}
+function buildCancellationTypedData(message, chainId) {
+  return {
+    domain: {
+      name: "Medialane",
+      version: "1",
+      chainId,
+      revision: starknet.TypedDataRevision.ACTIVE
+    },
+    primaryType: "OrderCancellation",
+    types: {
+      StarknetDomain: [
+        { name: "name", type: "shortstring" },
+        { name: "version", type: "shortstring" },
+        { name: "chainId", type: "shortstring" },
+        { name: "revision", type: "shortstring" }
+      ],
+      OrderCancellation: [
+        { name: "order_hash", type: "felt" },
+        { name: "offerer", type: "ContractAddress" },
+        { name: "nonce", type: "felt" }
+      ]
+    },
+    message
+  };
+}
 
 // src/marketplace/orders.ts
 var MedialaneError = class extends Error {
-  constructor(message, cause) {
+  constructor(message, code = "UNKNOWN", cause) {
     super(message);
+    this.code = code;
     this.cause = cause;
     this.name = "MedialaneError";
   }
@@ -556,7 +537,7 @@ function resolveToken(currency) {
   const token = SUPPORTED_TOKENS.find(
     (t) => t.symbol === currency.toUpperCase() || t.address.toLowerCase() === currency.toLowerCase()
   );
-  if (!token) throw new MedialaneError(`Unsupported currency: ${currency}`);
+  if (!token) throw new MedialaneError(`Unsupported currency: ${currency}`, "INVALID_PARAMS");
   return token;
 }
 async function createListing(account, params, config) {
@@ -640,7 +621,7 @@ async function createListing(account, params, config) {
     await provider.waitForTransaction(tx.transaction_hash);
     return { txHash: tx.transaction_hash };
   } catch (err) {
-    throw new MedialaneError("Failed to create listing", err);
+    throw new MedialaneError("Failed to create listing", "TRANSACTION_FAILED", err);
   }
 }
 async function makeOffer(account, params, config) {
@@ -711,7 +692,7 @@ async function makeOffer(account, params, config) {
     await provider.waitForTransaction(tx.transaction_hash);
     return { txHash: tx.transaction_hash };
   } catch (err) {
-    throw new MedialaneError("Failed to make offer", err);
+    throw new MedialaneError("Failed to make offer", "TRANSACTION_FAILED", err);
   }
 }
 async function fulfillOrder(account, params, config) {
@@ -739,7 +720,7 @@ async function fulfillOrder(account, params, config) {
     await provider.waitForTransaction(tx.transaction_hash);
     return { txHash: tx.transaction_hash };
   } catch (err) {
-    throw new MedialaneError("Failed to fulfill order", err);
+    throw new MedialaneError("Failed to fulfill order", "TRANSACTION_FAILED", err);
   }
 }
 async function cancelOrder(account, params, config) {
@@ -767,7 +748,7 @@ async function cancelOrder(account, params, config) {
     await provider.waitForTransaction(tx.transaction_hash);
     return { txHash: tx.transaction_hash };
   } catch (err) {
-    throw new MedialaneError("Failed to cancel order", err);
+    throw new MedialaneError("Failed to cancel order", "TRANSACTION_FAILED", err);
   }
 }
 function encodeByteArray(str) {
@@ -790,7 +771,7 @@ async function mint(account, params, config) {
     await provider.waitForTransaction(tx.transaction_hash);
     return { txHash: tx.transaction_hash };
   } catch (err) {
-    throw new MedialaneError("Failed to mint NFT", err);
+    throw new MedialaneError("Failed to mint NFT", "TRANSACTION_FAILED", err);
   }
 }
 async function createCollection(account, params, config) {
@@ -807,11 +788,11 @@ async function createCollection(account, params, config) {
     await provider.waitForTransaction(tx.transaction_hash);
     return { txHash: tx.transaction_hash };
   } catch (err) {
-    throw new MedialaneError("Failed to create collection", err);
+    throw new MedialaneError("Failed to create collection", "TRANSACTION_FAILED", err);
   }
 }
 async function checkoutCart(account, items, config) {
-  if (items.length === 0) throw new MedialaneError("Cart is empty");
+  if (items.length === 0) throw new MedialaneError("Cart is empty", "INVALID_PARAMS");
   const { contract, provider } = makeContract(config);
   const tokenTotals = /* @__PURE__ */ new Map();
   for (const item of items) {
@@ -858,10 +839,49 @@ async function checkoutCart(account, items, config) {
     await provider.waitForTransaction(tx.transaction_hash);
     return { txHash: tx.transaction_hash };
   } catch (err) {
-    throw new MedialaneError("Cart checkout failed", err);
+    throw new MedialaneError("Cart checkout failed", "TRANSACTION_FAILED", err);
   }
 }
 
+// src/config.ts
+var MedialaneConfigSchema = zod.z.object({
+  network: zod.z.enum(SUPPORTED_NETWORKS).default("mainnet"),
+  rpcUrl: zod.z.string().url().optional(),
+  backendUrl: zod.z.string().url().optional(),
+  /** API key for authenticated /v1/* backend endpoints */
+  apiKey: zod.z.string().optional(),
+  marketplaceContract: zod.z.string().optional(),
+  collectionContract: zod.z.string().optional(),
+  retryOptions: zod.z.object({
+    maxAttempts: zod.z.number().int().min(1).max(10).optional(),
+    baseDelayMs: zod.z.number().int().min(0).optional(),
+    maxDelayMs: zod.z.number().int().min(0).optional()
+  }).optional()
+});
+function resolveConfig(raw) {
+  const parsed = MedialaneConfigSchema.parse(raw);
+  const isMainnet = parsed.network === "mainnet";
+  const defaultMarketplace = isMainnet ? MARKETPLACE_CONTRACT_MAINNET : MARKETPLACE_CONTRACT_SEPOLIA;
+  const defaultCollection = isMainnet ? COLLECTION_CONTRACT_MAINNET : COLLECTION_CONTRACT_SEPOLIA;
+  const marketplaceContract = parsed.marketplaceContract ?? defaultMarketplace;
+  const collectionContract = parsed.collectionContract ?? defaultCollection;
+  if (!marketplaceContract || !collectionContract) {
+    throw new MedialaneError(
+      `Sepolia network is not yet supported: marketplace and collection contract addresses are not configured. Pass 'marketplaceContract' and 'collectionContract' explicitly in your MedialaneClient config.`,
+      "NETWORK_NOT_SUPPORTED"
+    );
+  }
+  return {
+    network: parsed.network,
+    rpcUrl: parsed.rpcUrl ?? DEFAULT_RPC_URLS[parsed.network],
+    backendUrl: parsed.backendUrl,
+    apiKey: parsed.apiKey,
+    marketplaceContract,
+    collectionContract,
+    retryOptions: parsed.retryOptions
+  };
+}
+
 // src/marketplace/index.ts
 var MarketplaceModule = class {
   constructor(config) {
@@ -911,18 +931,60 @@ function shortenAddress(address, chars = 4) {
   return `${norm.slice(0, chars + 2)}...${norm.slice(-chars)}`;
 }
 
+// src/utils/retry.ts
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 300;
+var DEFAULT_MAX_DELAY_MS = 5e3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, opts) {
+  const maxAttempts = opts?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const baseDelayMs = opts?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  const maxDelayMs = opts?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  let lastError;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (err instanceof MedialaneApiError && err.status < 500) {
+        throw err;
+      }
+      const isRetryable = err instanceof MedialaneApiError && err.status >= 500 || err instanceof TypeError;
+      if (!isRetryable || attempt === maxAttempts - 1) {
+        throw err;
+      }
+      const jitter = Math.random() * baseDelayMs;
+      const delay = Math.min(baseDelayMs * Math.pow(2, attempt) + jitter, maxDelayMs);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+
 // src/api/client.ts
+function deriveErrorCode(status) {
+  if (status === 404) return "TOKEN_NOT_FOUND";
+  if (status === 429) return "RATE_LIMITED";
+  if (status === 410) return "INTENT_EXPIRED";
+  if (status === 401 || status === 403) return "UNAUTHORIZED";
+  if (status === 400) return "INVALID_PARAMS";
+  return "UNKNOWN";
+}
 var MedialaneApiError = class extends Error {
   constructor(status, message) {
     super(message);
     this.status = status;
     this.name = "MedialaneApiError";
+    this.code = deriveErrorCode(status);
   }
 };
 var ApiClient = class {
-  constructor(baseUrl, apiKey) {
+  constructor(baseUrl, apiKey, retryOptions) {
     this.baseUrl = baseUrl;
     this.baseHeaders = apiKey ? { "x-api-key": apiKey } : {};
+    this.retryOptions = retryOptions;
   }
   async request(path, init) {
     const url = `${this.baseUrl.replace(/\/$/, "")}${path}`;
@@ -930,19 +992,23 @@ var ApiClient = class {
     if (!(init?.body instanceof FormData)) {
       headers["Content-Type"] = "application/json";
     }
-    const res = await fetch(url, {
-      ...init,
-      headers: { ...headers, ...init?.headers }
-    });
-    if (!res.ok) {
-      let message = res.statusText;
-      try {
-        const body = await res.json();
-        if (body.error) message = body.error;
-      } catch {
+    const res = await withRetry(async () => {
+      const response = await fetch(url, {
+        ...init,
+        headers: { ...headers, ...init?.headers }
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => response.statusText);
+        let message = text;
+        try {
+          const body = JSON.parse(text);
+          if (body.error) message = body.error;
+        } catch {
+        }
+        throw new MedialaneApiError(response.status, message);
       }
-      throw new MedialaneApiError(res.status, message);
-    }
+      return response;
+    }, this.retryOptions);
     return res.json();
   }
   get(path) {
@@ -1000,9 +1066,10 @@ var ApiClient = class {
     );
   }
   // ─── Collections ───────────────────────────────────────────────────────────
-  getCollections(page = 1, limit = 20, isKnown) {
+  getCollections(page = 1, limit = 20, isKnown, sort) {
     const params = new URLSearchParams({ page: String(page), limit: String(limit) });
     if (isKnown !== void 0) params.set("isKnown", String(isKnown));
+    if (sort) params.set("sort", sort);
     return this.get(`/v1/collections?${params}`);
   }
   getCollectionsByOwner(owner, page = 1, limit = 50) {
@@ -1109,6 +1176,79 @@ var ApiClient = class {
       `/v1/portal/webhooks/${id}`
     );
   }
+  // ─── Collection Claims ──────────────────────────────────────────────────────
+  /**
+   * Path 1: On-chain auto claim. Sends both x-api-key (tenant auth) and
+   * Authorization: Bearer (Clerk JWT) simultaneously.
+   */
+  async claimCollection(contractAddress, walletAddress, clerkToken) {
+    const url = `${this.baseUrl.replace(/\/$/, "")}/v1/collections/claim`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "x-api-key": this.baseHeaders["x-api-key"] ?? "",
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${clerkToken}`
+      },
+      body: JSON.stringify({ contractAddress, walletAddress })
+    });
+    return res.json();
+  }
+  /**
+   * Path 3: Manual off-chain claim request (email-based).
+   */
+  requestCollectionClaim(params) {
+    return this.request("/v1/collections/claim/request", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  // ─── Collection Profiles ────────────────────────────────────────────────────
+  async getCollectionProfile(contractAddress) {
+    const url = `${this.baseUrl.replace(/\/$/, "")}/v1/collections/${normalizeAddress(contractAddress)}/profile`;
+    const res = await fetch(url, { headers: this.baseHeaders });
+    if (res.status === 404) return null;
+    return res.json();
+  }
+  /**
+   * Update collection profile. Requires Clerk JWT for ownership check.
+   */
+  async updateCollectionProfile(contractAddress, data, clerkToken) {
+    const url = `${this.baseUrl.replace(/\/$/, "")}/v1/collections/${normalizeAddress(contractAddress)}/profile`;
+    const res = await fetch(url, {
+      method: "PATCH",
+      headers: {
+        "x-api-key": this.baseHeaders["x-api-key"] ?? "",
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${clerkToken}`
+      },
+      body: JSON.stringify(data)
+    });
+    return res.json();
+  }
+  // ─── Creator Profiles ───────────────────────────────────────────────────────
+  async getCreatorProfile(walletAddress) {
+    const url = `${this.baseUrl.replace(/\/$/, "")}/v1/creators/${normalizeAddress(walletAddress)}/profile`;
+    const res = await fetch(url, { headers: this.baseHeaders });
+    if (res.status === 404) return null;
+    return res.json();
+  }
+  /**
+   * Update creator profile. Requires Clerk JWT; wallet must match authenticated user.
+   */
+  async updateCreatorProfile(walletAddress, data, clerkToken) {
+    const url = `${this.baseUrl.replace(/\/$/, "")}/v1/creators/${normalizeAddress(walletAddress)}/profile`;
+    const res = await fetch(url, {
+      method: "PATCH",
+      headers: {
+        "x-api-key": this.baseHeaders["x-api-key"] ?? "",
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${clerkToken}`
+      },
+      body: JSON.stringify(data)
+    });
+    return res.json();
+  }
 };
 
 // src/client.ts
@@ -1127,7 +1267,7 @@ var MedialaneClient = class {
         }
       });
     } else {
-      this.api = new ApiClient(this.config.backendUrl, this.config.apiKey);
+      this.api = new ApiClient(this.config.backendUrl, this.config.apiKey, this.config.retryOptions);
     }
   }
   get network() {