@opensea/cli 0.4.0 → 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,26 +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_GRAPHQL_URL = "https://gql.opensea.io/graphql";
 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;
-  graphqlUrl;
   defaultChain;
   timeoutMs;
   verbose;
+  maxRetries;
+  retryBaseDelay;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
-    this.graphqlUrl = config.graphqlUrl ?? DEFAULT_GRAPHQL_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}`);
@@ -34,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) {
@@ -60,68 +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);
-    }
-    return response.json();
-  }
-  async graphql(query, variables) {
-    if (this.verbose) {
-      console.error(`[verbose] POST ${this.graphqlUrl}`);
-    }
-    const response = await fetch(this.graphqlUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
-        "x-api-key": this.apiKey
+    const response = await this.fetchWithRetry(
+      url.toString(),
+      {
+        method: "POST",
+        headers,
+        body: body ? JSON.stringify(body) : void 0
       },
-      body: JSON.stringify({ query, variables }),
-      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, "graphql");
-    }
-    const json = await response.json();
-    if (json.errors?.length) {
-      throw new OpenSeaAPIError(
-        400,
-        json.errors.map((e) => e.message).join("; "),
-        "graphql"
-      );
-    }
-    if (!json.data) {
-      throw new OpenSeaAPIError(500, "GraphQL response missing data", "graphql");
-    }
-    return json.data;
+      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) {
@@ -407,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)) {
@@ -450,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) {
@@ -586,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();
@@ -621,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(
@@ -691,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();
@@ -737,155 +868,38 @@ function offersCommand(getClient2, getFormat2) {
 }
 
 // src/commands/search.ts
-import { Command as Command7 } from "commander";
-
-// src/queries.ts
-var SEARCH_COLLECTIONS_QUERY = `
-query SearchCollections($query: String!, $limit: Int, $chains: [ChainIdentifier!]) {
-  collectionsByQuery(query: $query, limit: $limit, chains: $chains) {
-    slug
-    name
-    description
-    imageUrl
-    chain {
-      identifier
-      name
-    }
-    stats {
-      totalSupply
-      ownerCount
-      volume {
-        usd
-      }
-      sales
-    }
-    floorPrice {
-      pricePerItem {
-        usd
-        native {
-          unit
-          symbol
-        }
-      }
-    }
-  }
-}`;
-var SEARCH_NFTS_QUERY = `
-query SearchItems($query: String!, $collectionSlug: String, $limit: Int, $chains: [ChainIdentifier!]) {
-  itemsByQuery(query: $query, collectionSlug: $collectionSlug, limit: $limit, chains: $chains) {
-    tokenId
-    name
-    description
-    imageUrl
-    contractAddress
-    collection {
-      slug
-      name
-    }
-    chain {
-      identifier
-      name
-    }
-    bestListing {
-      pricePerItem {
-        usd
-        native {
-          unit
-          symbol
-        }
-      }
-    }
-    owner {
-      address
-      displayName
-    }
-  }
-}`;
-var SEARCH_TOKENS_QUERY = `
-query SearchCurrencies($query: String!, $limit: Int, $chain: ChainIdentifier) {
-  currenciesByQuery(query: $query, limit: $limit, chain: $chain, allowlistOnly: false) {
-    name
-    symbol
-    imageUrl
-    usdPrice
-    contractAddress
-    chain {
-      identifier
-      name
-    }
-    stats {
-      marketCapUsd
-      oneDay {
-        priceChange
-        volume
-      }
-    }
-  }
-}`;
-var SEARCH_ACCOUNTS_QUERY = `
-query SearchAccounts($query: String!, $limit: Int) {
-  accountsByQuery(query: $query, limit: $limit) {
-    address
-    username
-    imageUrl
-    isVerified
-  }
-}`;
-
-// src/commands/search.ts
+import { Command as Command8 } from "commander";
 function searchCommand(getClient2, getFormat2) {
-  const cmd = new Command7("search").description(
-    "Search for collections, NFTs, tokens, and accounts"
-  );
-  cmd.command("collections").description("Search collections by name or slug").argument("<query>", "Search query").option("--chains <chains>", "Filter by chains (comma-separated)").option("--limit <limit>", "Number of results", "10").action(
-    async (query, options) => {
-      const client = getClient2();
-      const result = await client.graphql(SEARCH_COLLECTIONS_QUERY, {
-        query,
-        limit: parseIntOption(options.limit, "--limit"),
-        chains: options.chains?.split(",")
-      });
-      console.log(formatOutput(result.collectionsByQuery, getFormat2()));
-    }
-  );
-  cmd.command("nfts").description("Search NFTs by name").argument("<query>", "Search query").option("--collection <slug>", "Filter by collection slug").option("--chains <chains>", "Filter by chains (comma-separated)").option("--limit <limit>", "Number of results", "10").action(
-    async (query, options) => {
-      const client = getClient2();
-      const result = await client.graphql(SEARCH_NFTS_QUERY, {
-        query,
-        collectionSlug: options.collection,
-        limit: parseIntOption(options.limit, "--limit"),
-        chains: options.chains?.split(",")
-      });
-      console.log(formatOutput(result.itemsByQuery, getFormat2()));
-    }
-  );
-  cmd.command("tokens").description("Search tokens/currencies by name or symbol").argument("<query>", "Search query").option("--chain <chain>", "Filter by chain").option("--limit <limit>", "Number of results", "10").action(
+  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(
     async (query, options) => {
       const client = getClient2();
-      const result = await client.graphql(SEARCH_TOKENS_QUERY, {
+      const params = {
         query,
-        limit: parseIntOption(options.limit, "--limit"),
-        chain: options.chain
-      });
-      console.log(formatOutput(result.currenciesByQuery, getFormat2()));
+        limit: parseIntOption(options.limit, "--limit")
+      };
+      if (options.types) {
+        params.asset_types = options.types;
+      }
+      if (options.chains) {
+        params.chains = options.chains;
+      }
+      const result = await client.get(
+        "/api/v2/search",
+        params
+      );
+      console.log(formatOutput(result, getFormat2()));
     }
   );
-  cmd.command("accounts").description("Search accounts by username or address").argument("<query>", "Search query").option("--limit <limit>", "Number of results", "10").action(async (query, options) => {
-    const client = getClient2();
-    const result = await client.graphql(SEARCH_ACCOUNTS_QUERY, {
-      query,
-      limit: parseIntOption(options.limit, "--limit")
-    });
-    console.log(formatOutput(result.accountsByQuery, getFormat2()));
-  });
   return cmd;
 }
 
 // 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(
@@ -925,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(
@@ -971,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 = `
    ____                   _____
   / __ \\                 / ____|
@@ -981,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;
@@ -990,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() {
@@ -1006,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));
@@ -1015,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
@@ -1032,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(
@@ -1045,7 +1084,7 @@ async function main() {
         2
       )
     );
-    process.exit(1);
+    process.exit(EXIT_API_ERROR);
   }
 }
 main();