@opensea/cli 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -269,93 +269,58 @@ interface SwapQuoteResponse {
     quote: SwapQuote;
     transactions: SwapTransaction[];
 }
-interface SearchCollectionResult {
-    slug: string;
-    name: string;
-    description: string;
-    imageUrl: string;
-    chain: {
-        identifier: string;
-        name: string;
-    };
-    stats: {
-        totalSupply: number;
-        ownerCount: number;
-        volume: {
-            usd: number;
-        };
-        sales: number;
-    } | null;
-    floorPrice: {
-        pricePerItem: {
-            usd: number;
-            native: {
-                unit: number;
-                symbol: string;
-            };
-        };
-    } | null;
-}
-interface SearchNFTResult {
-    tokenId: string;
+type SearchAssetType = "collection" | "nft" | "token" | "account";
+interface SearchResultCollection {
+    collection: string;
     name: string;
-    description: string;
-    imageUrl: string;
-    contractAddress: string;
-    collection: {
-        slug: string;
-        name: string;
-    };
-    chain: {
-        identifier: string;
-        name: string;
-    };
-    bestListing: {
-        pricePerItem: {
-            usd: number;
-            native: {
-                unit: number;
-                symbol: string;
-            };
-        };
-    } | null;
-    owner: {
-        address: string;
-        displayName: string;
-    } | null;
+    image_url: string | null;
+    is_disabled: boolean;
+    is_nsfw: boolean;
+    opensea_url: string;
 }
-interface SearchTokenResult {
+interface SearchResultToken {
+    address: string;
+    chain: string;
     name: string;
     symbol: string;
-    imageUrl: string;
-    usdPrice: string;
-    contractAddress: string;
-    chain: {
-        identifier: string;
-        name: string;
-    };
-    stats: {
-        marketCapUsd: number;
-        oneDay: {
-            priceChange: number;
-            volume: number;
-        };
-    } | null;
+    image_url: string | null;
+    usd_price: string;
+    decimals: number;
+    opensea_url: string;
+}
+interface SearchResultNFT {
+    identifier: string;
+    collection: string;
+    contract: string;
+    name: string | null;
+    image_url: string | null;
+    opensea_url: string;
 }
-interface SearchAccountResult {
+interface SearchResultAccount {
     address: string;
-    username: string;
-    imageUrl: string;
-    isVerified: boolean;
+    username: string | null;
+    profile_image_url: string | null;
+    opensea_url: string;
+}
+interface SearchResult {
+    type: SearchAssetType;
+    collection?: SearchResultCollection;
+    token?: SearchResultToken;
+    nft?: SearchResultNFT;
+    account?: SearchResultAccount;
+}
+interface SearchResponse {
+    results: SearchResult[];
 }
 
 interface OpenSeaClientConfig {
     apiKey: string;
     baseUrl?: string;
-    graphqlUrl?: string;
     chain?: string;
     timeout?: number;
     verbose?: boolean;
+    maxRetries?: number;
+    retryBaseDelay?: number;
 }
 interface CommandOptions {
     apiKey?: string;
@@ -363,19 +328,29 @@ interface CommandOptions {
     format?: "json" | "table";
     raw?: boolean;
 }
+interface HealthResult {
+    status: "ok" | "error";
+    key_prefix: string;
+    authenticated: boolean;
+    rate_limited: boolean;
+    message: string;
+}
 
 declare class OpenSeaClient {
     private apiKey;
     private baseUrl;
-    private graphqlUrl;
     private defaultChain;
     private timeoutMs;
     private verbose;
+    private maxRetries;
+    private retryBaseDelay;
     constructor(config: OpenSeaClientConfig);
+    private get defaultHeaders();
     get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
     post<T>(path: string, body?: Record<string, unknown>, params?: Record<string, unknown>): Promise<T>;
-    graphql<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
     getDefaultChain(): string;
+    getApiKeyPrefix(): string;
+    private fetchWithRetry;
 }
 declare class OpenSeaAPIError extends Error {
     statusCode: number;
@@ -384,6 +359,8 @@ declare class OpenSeaAPIError extends Error {
     constructor(statusCode: number, responseBody: string, path: string);
 }
 
+declare function checkHealth(client: OpenSeaClient): Promise<HealthResult>;
+
 type OutputFormat = "json" | "table" | "toon";
 declare function formatOutput(data: unknown, format: OutputFormat): string;
 
@@ -398,6 +375,7 @@ declare class OpenSeaCLI {
     readonly tokens: TokensAPI;
     readonly search: SearchAPI;
     readonly swaps: SwapsAPI;
+    readonly health: HealthAPI;
     constructor(config: OpenSeaClientConfig);
 }
 declare class CollectionsAPI {
@@ -564,22 +542,11 @@ declare class TokensAPI {
 declare class SearchAPI {
     private client;
     constructor(client: OpenSeaClient);
-    collections(query: string, options?: {
-        chains?: string[];
-        limit?: number;
-    }): Promise<SearchCollectionResult[]>;
-    nfts(query: string, options?: {
-        collection?: string;
+    query(query: string, options?: {
+        assetTypes?: SearchAssetType[];
         chains?: string[];
         limit?: number;
-    }): Promise<SearchNFTResult[]>;
-    tokens(query: string, options?: {
-        chain?: string;
-        limit?: number;
-    }): Promise<SearchTokenResult[]>;
-    accounts(query: string, options?: {
-        limit?: number;
-    }): Promise<SearchAccountResult[]>;
+    }): Promise<SearchResponse>;
 }
 declare class SwapsAPI {
     private client;
@@ -595,7 +562,12 @@ declare class SwapsAPI {
         recipient?: string;
     }): Promise<SwapQuoteResponse>;
 }
+declare class HealthAPI {
+    private client;
+    constructor(client: OpenSeaClient);
+    check(): Promise<HealthResult>;
+}
 
 declare function formatToon(data: unknown): string;
 
-export { type Account, type AssetEvent, type Chain, type Collection, type CollectionOrderBy, type CollectionStats, type CommandOptions, type Contract, type EventAsset, type EventPayment, type EventType, type Fee, type GetTraitsResponse, type Listing, type NFT, type Offer, OpenSeaAPIError, OpenSeaCLI, OpenSeaClient, type OpenSeaClientConfig, type Order, type OrderSide, type OutputFormat, type PaymentToken, type Price, type SafelistStatus, type SearchAccountResult, type SearchCollectionResult, type SearchNFTResult, type SearchTokenResult, type SwapQuote, type SwapQuoteResponse, type SwapTransaction, type Token, type TokenDetails, type TokenSocials, type TokenStats, type Trait, type TraitCategories, type TraitCounts, formatOutput, formatToon };
+export { type Account, type AssetEvent, type Chain, type Collection, type CollectionOrderBy, type CollectionStats, type CommandOptions, type Contract, type EventAsset, type EventPayment, type EventType, type Fee, type GetTraitsResponse, type HealthResult, type Listing, type NFT, type Offer, OpenSeaAPIError, OpenSeaCLI, OpenSeaClient, type OpenSeaClientConfig, type Order, type OrderSide, type OutputFormat, type PaymentToken, type Price, type SafelistStatus, type SearchAssetType, type SearchResponse, type SearchResult, type SearchResultAccount, type SearchResultCollection, type SearchResultNFT, type SearchResultToken, type SwapQuote, type SwapQuoteResponse, type SwapTransaction, type Token, type TokenDetails, type TokenSocials, type TokenStats, type Trait, type TraitCategories, type TraitCounts, checkHealth, formatOutput, formatToon };

package/dist/index.js

@@ -1,21 +1,47 @@
 // 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}`);
@@ -29,21 +55,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) {
@@ -55,68 +74,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) {
@@ -128,6 +146,68 @@ var OpenSeaAPIError = class extends Error {
   }
 };
 
+// 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/toon.ts
 var INDENT = "  ";
 var NUMERIC_RE = /^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i;
@@ -399,14 +479,21 @@ function formatToon(data) {
 }
 
 // src/output.ts
+var _outputOptions = {};
 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)) {
@@ -442,99 +529,31 @@ function formatTable(data) {
   }
   return String(data);
 }
-
-// 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
+function pickFields(obj, fields) {
+  const result = {};
+  for (const field of fields) {
+    if (field in obj) {
+      result[field] = obj[field];
     }
   }
-}`;
-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
-      }
-    }
+  return result;
+}
+function filterFields(data, fields) {
+  if (Array.isArray(data)) {
+    return data.map((item) => filterFields(item, fields));
   }
-}`;
-var SEARCH_ACCOUNTS_QUERY = `
-query SearchAccounts($query: String!, $limit: Int) {
-  accountsByQuery(query: $query, limit: $limit) {
-    address
-    username
-    imageUrl
-    isVerified
+  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/sdk.ts
 var OpenSeaCLI = class {
@@ -548,6 +567,7 @@ var OpenSeaCLI = class {
   tokens;
   search;
   swaps;
+  health;
   constructor(config) {
     this.client = new OpenSeaClient(config);
     this.collections = new CollectionsAPI(this.client);
@@ -559,6 +579,7 @@ var OpenSeaCLI = class {
     this.tokens = new TokensAPI(this.client);
     this.search = new SearchAPI(this.client);
     this.swaps = new SwapsAPI(this.client);
+    this.health = new HealthAPI(this.client);
   }
 };
 var CollectionsAPI = class {
@@ -750,37 +771,13 @@ var SearchAPI = class {
   constructor(client) {
     this.client = client;
   }
-  async collections(query, options) {
-    const result = await this.client.graphql(SEARCH_COLLECTIONS_QUERY, {
-      query,
-      limit: options?.limit,
-      chains: options?.chains
-    });
-    return result.collectionsByQuery;
-  }
-  async nfts(query, options) {
-    const result = await this.client.graphql(SEARCH_NFTS_QUERY, {
-      query,
-      collectionSlug: options?.collection,
-      limit: options?.limit,
-      chains: options?.chains
-    });
-    return result.itemsByQuery;
-  }
-  async tokens(query, options) {
-    const result = await this.client.graphql(SEARCH_TOKENS_QUERY, {
-      query,
-      limit: options?.limit,
-      chain: options?.chain
-    });
-    return result.currenciesByQuery;
-  }
-  async accounts(query, options) {
-    const result = await this.client.graphql(SEARCH_ACCOUNTS_QUERY, {
+  async query(query, options) {
+    return this.client.get("/api/v2/search", {
       query,
+      asset_types: options?.assetTypes?.join(","),
+      chains: options?.chains?.join(","),
       limit: options?.limit
     });
-    return result.accountsByQuery;
   }
 };
 var SwapsAPI = class {
@@ -800,10 +797,19 @@ var SwapsAPI = class {
     });
   }
 };
+var HealthAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async check() {
+    return checkHealth(this.client);
+  }
+};
 export {
   OpenSeaAPIError,
   OpenSeaCLI,
   OpenSeaClient,
+  checkHealth,
   formatOutput,
   formatToon
 };