merge: resolve conflicts with main (health command, fields/max-lines, API key prefix)

Co-Authored-By: Chris K <ckorhonen@gmail.com>

Author: devin-ai-integration[bot]

src/cli.ts

@@ -4,14 +4,15 @@ import {
   accountsCommand,
   collectionsCommand,
   eventsCommand,
+  healthCommand,
   listingsCommand,
   nftsCommand,
   offersCommand,
   searchCommand,
   swapsCommand,
   tokensCommand,
 } from "./commands/index.js"
-import type { OutputFormat } from "./output.js"
+import { type OutputFormat, setOutputOptions } from "./output.js"
 import { parseIntOption } from "./parse.js"
 
 const EXIT_API_ERROR = 1
@@ -44,6 +45,11 @@ program
   .option("--verbose", "Log request and response info to stderr")
   .option("--max-retries <n>", "Max retries on 429/5xx (0 to disable)", "3")
   .option("--no-retry", "Disable request retries")
+  .option(
+    "--fields <fields>",
+    "Comma-separated list of fields to include in output",
+  )
+  .option("--max-lines <lines>", "Truncate output after N lines")
 
 function getClient(): OpenSeaClient {
   const opts = program.opts<{
@@ -85,6 +91,25 @@ function getFormat(): OutputFormat {
   return "json"
 }
 
+program.hook("preAction", () => {
+  const opts = program.opts<{
+    fields?: string
+    maxLines?: string
+  }>()
+  let maxLines: number | undefined
+  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))
@@ -94,6 +119,7 @@ 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 {

src/client.ts

@@ -122,6 +122,11 @@ export class OpenSeaClient {
     return this.defaultChain
   }
 
+  getApiKeyPrefix(): string {
+    if (this.apiKey.length < 8) return "***"
+    return `${this.apiKey.slice(0, 4)}...`
+  }
+
   private async fetchWithRetry(
     url: string,
     init: RequestInit,

src/commands/health.ts

@@ -0,0 +1,23 @@
+import { Command } from "commander"
+import type { OpenSeaClient } from "../client.js"
+import { checkHealth } from "../health.js"
+import type { OutputFormat } from "../output.js"
+import { formatOutput } from "../output.js"
+
+export function healthCommand(
+  getClient: () => OpenSeaClient,
+  getFormat: () => OutputFormat,
+): Command {
+  const cmd = new Command("health")
+    .description("Check API connectivity and authentication")
+    .action(async () => {
+      const client = getClient()
+      const result = await checkHealth(client)
+      console.log(formatOutput(result, getFormat()))
+      if (result.status === "error") {
+        process.exit(result.rate_limited ? 3 : 1)
+      }
+    })
+
+  return cmd
+}

src/commands/index.ts

@@ -1,6 +1,7 @@
 export { accountsCommand } from "./accounts.js"
 export { collectionsCommand } from "./collections.js"
 export { eventsCommand } from "./events.js"
+export { healthCommand } from "./health.js"
 export { listingsCommand } from "./listings.js"
 export { nftsCommand } from "./nfts.js"
 export { offersCommand } from "./offers.js"

src/health.ts

@@ -0,0 +1,75 @@
+import { OpenSeaAPIError, type OpenSeaClient } from "./client.js"
+import type { HealthResult } from "./types/index.js"
+
+export async function checkHealth(
+  client: OpenSeaClient,
+): Promise<HealthResult> {
+  const keyPrefix = client.getApiKeyPrefix()
+
+  // Step 1: Check basic connectivity with a public endpoint
+  try {
+    await client.get("/api/v2/collections", { limit: 1 })
+  } catch (error) {
+    let message: string
+    if (error instanceof OpenSeaAPIError) {
+      message =
+        error.statusCode === 429
+          ? "Rate limited: too many requests"
+          : `API error (${error.statusCode}): ${error.responseBody}`
+    } else {
+      message = `Network error: ${(error as Error).message}`
+    }
+    return {
+      status: "error",
+      key_prefix: keyPrefix,
+      authenticated: false,
+      rate_limited:
+        error instanceof OpenSeaAPIError && error.statusCode === 429,
+      message,
+    }
+  }
+
+  // Step 2: Validate authentication with an endpoint that requires a valid API key
+  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`,
+        }
+      }
+    }
+    // Non-auth error on listings endpoint — connectivity works but auth is unverified
+    return {
+      status: "ok",
+      key_prefix: keyPrefix,
+      authenticated: false,
+      rate_limited: false,
+      message:
+        "Connectivity is working but authentication could not be verified",
+    }
+  }
+}

src/index.ts

@@ -1,4 +1,5 @@
 export { OpenSeaAPIError, OpenSeaClient } from "./client.js"
+export { checkHealth } from "./health.js"
 export type { OutputFormat } from "./output.js"
 export { formatOutput } from "./output.js"
 export { OpenSeaCLI } from "./sdk.js"

src/output.ts

@@ -2,14 +2,36 @@ import { formatToon } from "./toon.js"
 
 export type OutputFormat = "json" | "table" | "toon"
 
+export interface OutputOptions {
+  fields?: string[]
+  maxLines?: number
+}
+
+let _outputOptions: OutputOptions = {}
+
+export function setOutputOptions(options: OutputOptions): void {
+  _outputOptions = options
+}
+
 export function formatOutput(data: unknown, format: OutputFormat): string {
+  const processed = _outputOptions.fields
+    ? filterFields(data, _outputOptions.fields)
+    : data
+
+  let result: string
   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: unknown): string {
@@ -57,3 +79,36 @@ function formatTable(data: unknown): string {
 
   return String(data)
 }
+
+function pickFields(
+  obj: Record<string, unknown>,
+  fields: string[],
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const field of fields) {
+    if (field in obj) {
+      result[field] = obj[field]
+    }
+  }
+  return result
+}
+
+function filterFields(data: unknown, fields: string[]): unknown {
+  if (Array.isArray(data)) {
+    return data.map(item => filterFields(item, fields))
+  }
+  if (data && typeof data === "object") {
+    return pickFields(data as Record<string, unknown>, fields)
+  }
+  return data
+}
+
+function truncateOutput(text: string, maxLines: number): string {
+  const lines = text.split("\n")
+  if (lines.length <= maxLines) return text
+  const omitted = lines.length - maxLines
+  return (
+    lines.slice(0, maxLines).join("\n") +
+    `\n... (${omitted} more line${omitted === 1 ? "" : "s"})`
+  )
+}

src/sdk.ts

@@ -1,4 +1,5 @@
 import { OpenSeaClient } from "./client.js"
+import { checkHealth } from "./health.js"
 import type {
   Account,
   AssetEvent,
@@ -9,6 +10,7 @@ import type {
   Contract,
   EventType,
   GetTraitsResponse,
+  HealthResult,
   Listing,
   NFT,
   Offer,
@@ -32,6 +34,7 @@ export class OpenSeaCLI {
   readonly tokens: TokensAPI
   readonly search: SearchAPI
   readonly swaps: SwapsAPI
+  readonly health: HealthAPI
 
   constructor(config: OpenSeaClientConfig) {
     this.client = new OpenSeaClient(config)
@@ -44,6 +47,7 @@ export class OpenSeaCLI {
     this.tokens = new TokensAPI(this.client)
     this.search = new SearchAPI(this.client)
     this.swaps = new SwapsAPI(this.client)
+    this.health = new HealthAPI(this.client)
   }
 }
 
@@ -384,3 +388,11 @@ class SwapsAPI {
     })
   }
 }
+
+class HealthAPI {
+  constructor(private client: OpenSeaClient) {}
+
+  async check(): Promise<HealthResult> {
+    return checkHealth(this.client)
+  }
+}

src/types/index.ts

@@ -16,3 +16,11 @@ export interface CommandOptions {
   format?: "json" | "table"
   raw?: boolean
 }
+
+export interface HealthResult {
+  status: "ok" | "error"
+  key_prefix: string
+  authenticated: boolean
+  rate_limited: boolean
+  message: string
+}

test/cli-api-error.test.ts

@@ -12,6 +12,7 @@ vi.mock("../src/commands/index.js", () => ({
   searchCommand: () => new Command("search"),
   swapsCommand: () => new Command("swaps"),
   tokensCommand: () => new Command("tokens"),
+  healthCommand: () => new Command("health"),
 }))
 
 const exitSpy = vi