@opensea/cli 0.4.1 → 0.4.2

package/README.md

@@ -167,8 +167,9 @@ console.log(formatToon(data))
 ## Exit Codes
 
 - `0` - Success
-- `1` - API error
+- `1` - API error (non-429)
 - `2` - Authentication error
+- `3` - Rate limited (HTTP 429)
 
 ## Requirements
 

package/dist/cli.js

@@ -1,23 +1,52 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.opensea.io";
 var DEFAULT_TIMEOUT_MS = 3e4;
+var USER_AGENT = `opensea-cli/${"0.4.2"}`;
+var DEFAULT_MAX_RETRIES = 0;
+var DEFAULT_RETRY_BASE_DELAY_MS = 1e3;
+function isRetryableStatus(status, method) {
+  if (status === 429) return true;
+  return status >= 500 && method === "GET";
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (!Number.isNaN(seconds)) return seconds * 1e3;
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var OpenSeaClient = class {
   apiKey;
   baseUrl;
   defaultChain;
   timeoutMs;
   verbose;
+  maxRetries;
+  retryBaseDelay;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
     this.defaultChain = config.chain ?? "ethereum";
     this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS;
     this.verbose = config.verbose ?? false;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.retryBaseDelay = config.retryBaseDelay ?? DEFAULT_RETRY_BASE_DELAY_MS;
+  }
+  get defaultHeaders() {
+    return {
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+      "x-api-key": this.apiKey
+    };
   }
   async get(path, params) {
     const url = new URL(`${this.baseUrl}${path}`);
@@ -31,21 +60,14 @@ var OpenSeaClient = class {
     if (this.verbose) {
       console.error(`[verbose] GET ${url.toString()}`);
     }
-    const response = await fetch(url.toString(), {
-      method: "GET",
-      headers: {
-        Accept: "application/json",
-        "x-api-key": this.apiKey
+    const response = await this.fetchWithRetry(
+      url.toString(),
+      {
+        method: "GET",
+        headers: this.defaultHeaders
       },
-      signal: AbortSignal.timeout(this.timeoutMs)
-    });
-    if (this.verbose) {
-      console.error(`[verbose] ${response.status} ${response.statusText}`);
-    }
-    if (!response.ok) {
-      const body = await response.text();
-      throw new OpenSeaAPIError(response.status, body, path);
-    }
+      path
+    );
     return response.json();
   }
   async post(path, body, params) {
@@ -57,34 +79,67 @@ var OpenSeaClient = class {
         }
       }
     }
-    const headers = {
-      Accept: "application/json",
-      "x-api-key": this.apiKey
-    };
+    const headers = { ...this.defaultHeaders };
     if (body) {
       headers["Content-Type"] = "application/json";
     }
     if (this.verbose) {
       console.error(`[verbose] POST ${url.toString()}`);
     }
-    const response = await fetch(url.toString(), {
-      method: "POST",
-      headers,
-      body: body ? JSON.stringify(body) : void 0,
-      signal: AbortSignal.timeout(this.timeoutMs)
-    });
-    if (this.verbose) {
-      console.error(`[verbose] ${response.status} ${response.statusText}`);
-    }
-    if (!response.ok) {
-      const text = await response.text();
-      throw new OpenSeaAPIError(response.status, text, path);
-    }
+    const response = await this.fetchWithRetry(
+      url.toString(),
+      {
+        method: "POST",
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      },
+      path
+    );
     return response.json();
   }
   getDefaultChain() {
     return this.defaultChain;
   }
+  getApiKeyPrefix() {
+    if (this.apiKey.length < 8) return "***";
+    return `${this.apiKey.slice(0, 4)}...`;
+  }
+  async fetchWithRetry(url, init, path) {
+    for (let attempt = 0; ; attempt++) {
+      const response = await fetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      if (this.verbose) {
+        console.error(`[verbose] ${response.status} ${response.statusText}`);
+      }
+      if (response.ok) {
+        return response;
+      }
+      const method = init.method ?? "GET";
+      if (attempt < this.maxRetries && isRetryableStatus(response.status, method)) {
+        const retryAfterMs = parseRetryAfter(
+          response.headers.get("Retry-After")
+        );
+        const backoffMs = this.retryBaseDelay * 2 ** attempt;
+        const jitterMs = Math.random() * this.retryBaseDelay;
+        const delayMs = Math.max(retryAfterMs ?? 0, backoffMs) + jitterMs;
+        if (this.verbose) {
+          console.error(
+            `[verbose] Retry ${attempt + 1}/${this.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`
+          );
+        }
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+        await sleep(delayMs);
+        continue;
+      }
+      const text = await response.text();
+      throw new OpenSeaAPIError(response.status, text, path);
+    }
+  }
 };
 var OpenSeaAPIError = class extends Error {
   constructor(statusCode, responseBody, path) {
@@ -370,14 +425,24 @@ function formatToon(data) {
 }
 
 // src/output.ts
+var _outputOptions = {};
+function setOutputOptions(options) {
+  _outputOptions = options;
+}
 function formatOutput(data, format) {
+  const processed = _outputOptions.fields ? filterFields(data, _outputOptions.fields) : data;
+  let result;
   if (format === "table") {
-    return formatTable(data);
+    result = formatTable(processed);
+  } else if (format === "toon") {
+    result = formatToon(processed);
+  } else {
+    result = JSON.stringify(processed, null, 2);
   }
-  if (format === "toon") {
-    return formatToon(data);
+  if (_outputOptions.maxLines != null) {
+    result = truncateOutput(result, _outputOptions.maxLines);
   }
-  return JSON.stringify(data, null, 2);
+  return result;
 }
 function formatTable(data) {
   if (Array.isArray(data)) {
@@ -413,6 +478,31 @@ function formatTable(data) {
   }
   return String(data);
 }
+function pickFields(obj, fields) {
+  const result = {};
+  for (const field of fields) {
+    if (field in obj) {
+      result[field] = obj[field];
+    }
+  }
+  return result;
+}
+function filterFields(data, fields) {
+  if (Array.isArray(data)) {
+    return data.map((item) => filterFields(item, fields));
+  }
+  if (data && typeof data === "object") {
+    return pickFields(data, fields);
+  }
+  return data;
+}
+function truncateOutput(text, maxLines) {
+  const lines = text.split("\n");
+  if (lines.length <= maxLines) return text;
+  const omitted = lines.length - maxLines;
+  return lines.slice(0, maxLines).join("\n") + `
+... (${omitted} more line${omitted === 1 ? "" : "s"})`;
+}
 
 // src/commands/accounts.ts
 function accountsCommand(getClient2, getFormat2) {
@@ -549,10 +639,88 @@ function eventsCommand(getClient2, getFormat2) {
   return cmd;
 }
 
-// src/commands/listings.ts
+// src/commands/health.ts
 import { Command as Command4 } from "commander";
+
+// src/health.ts
+async function checkHealth(client) {
+  const keyPrefix = client.getApiKeyPrefix();
+  try {
+    await client.get("/api/v2/collections", { limit: 1 });
+  } catch (error) {
+    let message;
+    if (error instanceof OpenSeaAPIError) {
+      message = error.statusCode === 429 ? "Rate limited: too many requests" : `API error (${error.statusCode}): ${error.responseBody}`;
+    } else {
+      message = `Network error: ${error.message}`;
+    }
+    return {
+      status: "error",
+      key_prefix: keyPrefix,
+      authenticated: false,
+      rate_limited: error instanceof OpenSeaAPIError && error.statusCode === 429,
+      message
+    };
+  }
+  try {
+    await client.get("/api/v2/listings/collection/boredapeyachtclub/all", {
+      limit: 1
+    });
+    return {
+      status: "ok",
+      key_prefix: keyPrefix,
+      authenticated: true,
+      rate_limited: false,
+      message: "Connectivity and authentication are working"
+    };
+  } catch (error) {
+    if (error instanceof OpenSeaAPIError) {
+      if (error.statusCode === 429) {
+        return {
+          status: "error",
+          key_prefix: keyPrefix,
+          authenticated: false,
+          rate_limited: true,
+          message: "Rate limited: too many requests"
+        };
+      }
+      if (error.statusCode === 401 || error.statusCode === 403) {
+        return {
+          status: "error",
+          key_prefix: keyPrefix,
+          authenticated: false,
+          rate_limited: false,
+          message: `Authentication failed (${error.statusCode}): invalid API key`
+        };
+      }
+    }
+    return {
+      status: "ok",
+      key_prefix: keyPrefix,
+      authenticated: false,
+      rate_limited: false,
+      message: "Connectivity is working but authentication could not be verified"
+    };
+  }
+}
+
+// src/commands/health.ts
+function healthCommand(getClient2, getFormat2) {
+  const cmd = new Command4("health").description("Check API connectivity and authentication").action(async () => {
+    const client = getClient2();
+    const result = await checkHealth(client);
+    console.log(formatOutput(result, getFormat2()));
+    if (result.status === "error") {
+      process.exit(result.rate_limited ? 3 : 1);
+    }
+  });
+  return cmd;
+}
+
+// src/commands/listings.ts
+import { Command as Command5 } from "commander";
 function listingsCommand(getClient2, getFormat2) {
-  const cmd = new Command4("listings").description("Query NFT listings");
+  const cmd = new Command5("listings").description("Query NFT listings");
   cmd.command("all").description("Get all listings for a collection").argument("<collection>", "Collection slug").option("--limit <limit>", "Number of results", "20").option("--next <cursor>", "Pagination cursor").action(
     async (collection, options) => {
       const client = getClient2();
@@ -584,9 +752,9 @@ function listingsCommand(getClient2, getFormat2) {
 }
 
 // src/commands/nfts.ts
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 function nftsCommand(getClient2, getFormat2) {
-  const cmd = new Command5("nfts").description("Query NFTs");
+  const cmd = new Command6("nfts").description("Query NFTs");
   cmd.command("get").description("Get a single NFT").argument("<chain>", "Chain (e.g. ethereum, base)").argument("<contract>", "Contract address").argument("<token-id>", "Token ID").action(async (chain, contract, tokenId) => {
     const client = getClient2();
     const result = await client.get(
@@ -654,9 +822,9 @@ function nftsCommand(getClient2, getFormat2) {
 }
 
 // src/commands/offers.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 function offersCommand(getClient2, getFormat2) {
-  const cmd = new Command6("offers").description("Query NFT offers");
+  const cmd = new Command7("offers").description("Query NFT offers");
   cmd.command("all").description("Get all offers for a collection").argument("<collection>", "Collection slug").option("--limit <limit>", "Number of results", "20").option("--next <cursor>", "Pagination cursor").action(
     async (collection, options) => {
       const client = getClient2();
@@ -700,9 +868,9 @@ function offersCommand(getClient2, getFormat2) {
 }
 
 // src/commands/search.ts
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 function searchCommand(getClient2, getFormat2) {
-  const cmd = new Command7("search").description("Search across collections, tokens, NFTs, and accounts").argument("<query>", "Search query").option(
+  const cmd = new Command8("search").description("Search across collections, tokens, NFTs, and accounts").argument("<query>", "Search query").option(
     "--types <types>",
     "Filter by type (comma-separated: collection,nft,token,account)"
   ).option("--chains <chains>", "Filter by chains (comma-separated)").option("--limit <limit>", "Number of results", "20").action(
@@ -729,9 +897,9 @@ function searchCommand(getClient2, getFormat2) {
 }
 
 // src/commands/swaps.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 function swapsCommand(getClient2, getFormat2) {
-  const cmd = new Command8("swaps").description(
+  const cmd = new Command9("swaps").description(
     "Get swap quotes for token trading"
   );
   cmd.command("quote").description(
@@ -771,9 +939,9 @@ function swapsCommand(getClient2, getFormat2) {
 }
 
 // src/commands/tokens.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 function tokensCommand(getClient2, getFormat2) {
-  const cmd = new Command9("tokens").description(
+  const cmd = new Command10("tokens").description(
     "Query trending tokens, top tokens, and token details"
   );
   cmd.command("trending").description("Get trending tokens based on OpenSea's trending score").option("--chains <chains>", "Comma-separated list of chains to filter by").option("--limit <limit>", "Number of results (max 100)", "20").option("--next <cursor>", "Pagination cursor").action(
@@ -817,6 +985,9 @@ function tokensCommand(getClient2, getFormat2) {
 }
 
 // src/cli.ts
+var EXIT_API_ERROR = 1;
+var EXIT_AUTH_ERROR = 2;
+var EXIT_RATE_LIMITED = 3;
 var BANNER = `
    ____                   _____
   / __ \\                 / ____|
@@ -827,8 +998,11 @@ var BANNER = `
         | |
         |_|
 `;
-var program = new Command10();
-program.name("opensea").description("OpenSea CLI - Query the OpenSea API from the command line").version(process.env.npm_package_version ?? "0.0.0").addHelpText("before", BANNER).option("--api-key <key>", "OpenSea API key (or set OPENSEA_API_KEY env var)").option("--chain <chain>", "Default chain", "ethereum").option("--format <format>", "Output format (json, table, or toon)", "json").option("--base-url <url>", "API base URL").option("--timeout <ms>", "Request timeout in milliseconds", "30000").option("--verbose", "Log request and response info to stderr");
+var program = new Command11();
+program.name("opensea").description("OpenSea CLI - Query the OpenSea API from the command line").version(process.env.npm_package_version ?? "0.0.0").addHelpText("before", BANNER).option("--api-key <key>", "OpenSea API key (or set OPENSEA_API_KEY env var)").option("--chain <chain>", "Default chain", "ethereum").option("--format <format>", "Output format (json, table, or toon)", "json").option("--base-url <url>", "API base URL").option("--timeout <ms>", "Request timeout in milliseconds", "30000").option("--verbose", "Log request and response info to stderr").option(
+  "--fields <fields>",
+  "Comma-separated list of fields to include in output"
+).option("--max-lines <lines>", "Truncate output after N lines").option("--max-retries <n>", "Max retries on 429/5xx (0 to disable)", "3").option("--no-retry", "Disable request retries");
 function getClient() {
   const opts = program.opts();
   const apiKey = opts.apiKey ?? process.env.OPENSEA_API_KEY;
@@ -836,14 +1010,16 @@ function getClient() {
     console.error(
       "Error: API key required. Use --api-key or set OPENSEA_API_KEY environment variable."
     );
-    process.exit(2);
+    process.exit(EXIT_AUTH_ERROR);
   }
+  const maxRetries = opts.retry ? parseIntOption(opts.maxRetries, "--max-retries") : 0;
   return new OpenSeaClient({
     apiKey,
     chain: opts.chain,
     baseUrl: opts.baseUrl,
     timeout: parseIntOption(opts.timeout, "--timeout"),
-    verbose: opts.verbose
+    verbose: opts.verbose,
+    maxRetries
   });
 }
 function getFormat() {
@@ -852,6 +1028,21 @@ function getFormat() {
   if (opts.format === "toon") return "toon";
   return "json";
 }
+program.hook("preAction", () => {
+  const opts = program.opts();
+  let maxLines;
+  if (opts.maxLines) {
+    maxLines = parseIntOption(opts.maxLines, "--max-lines");
+    if (maxLines < 1) {
+      console.error("Error: --max-lines must be >= 1");
+      process.exit(2);
+    }
+  }
+  setOutputOptions({
+    fields: opts.fields?.split(",").map((f) => f.trim()),
+    maxLines
+  });
+});
 program.addCommand(collectionsCommand(getClient, getFormat));
 program.addCommand(nftsCommand(getClient, getFormat));
 program.addCommand(listingsCommand(getClient, getFormat));
@@ -861,15 +1052,17 @@ program.addCommand(accountsCommand(getClient, getFormat));
 program.addCommand(tokensCommand(getClient, getFormat));
 program.addCommand(searchCommand(getClient, getFormat));
 program.addCommand(swapsCommand(getClient, getFormat));
+program.addCommand(healthCommand(getClient, getFormat));
 async function main() {
   try {
     await program.parseAsync(process.argv);
   } catch (error) {
     if (error instanceof OpenSeaAPIError) {
+      const isRateLimited = error.statusCode === 429;
       console.error(
         JSON.stringify(
           {
-            error: "API Error",
+            error: isRateLimited ? "Rate Limited" : "API Error",
             status: error.statusCode,
             path: error.path,
             message: error.responseBody
@@ -878,7 +1071,7 @@ async function main() {
           2
         )
       );
-      process.exit(1);
+      process.exit(isRateLimited ? EXIT_RATE_LIMITED : EXIT_API_ERROR);
     }
     const label = error instanceof TypeError ? "Network Error" : error.name;
     console.error(
@@ -891,7 +1084,7 @@ async function main() {
         2
       )
     );
-    process.exit(1);
+    process.exit(EXIT_API_ERROR);
   }
 }
 main();