feat: add opensea health diagnostic command (DIS-144) (#35)

* feat: add opensea health diagnostic command (DIS-144)

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

* fix: address code review feedback on health command (DIS-144)

- Fix misleading success message: says 'Connectivity is working' instead
  of claiming API key validation (endpoint returns 200 for any key)
- Extract shared checkHealth() into src/health.ts to DRY up duplicated
  logic between CLI command and SDK HealthAPI
- Change 'type HealthResult' to 'interface HealthResult' for consistency
  with other types in src/types/
- Add getApiKeyPrefix to MockClient type instead of using Record cast
- Fix SDK test: use vi.importActual for OpenSeaAPIError so instanceof
  works correctly, enabling auth/API error branch coverage
- Add SDK tests for auth error (401) and API error (500) branches

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

* fix: validate API key authentication in health check

The health check now performs two steps:
1. Connectivity check via /api/v2/collections (public endpoint)
2. Auth validation via /api/v2/listings (requires valid API key)

Previously the health check only hit a public endpoint that returned
200 regardless of API key validity, giving false "ok" results for
invalid keys.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: biome formatting and stale comment in health check

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

* fix: guard short API keys, add 429 rate-limit handling with exit code 3

- getApiKeyPrefix() returns '***' for keys shorter than 8 chars
- checkHealth() detects 429 responses and sets rate_limited flag
- CLI exits with code 3 on rate limiting (vs 1 for other errors)
- HealthResult interface gains rate_limited boolean field
- Added tests for 429 handling in both CLI and SDK

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

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

src/cli.ts

@@ -4,6 +4,7 @@ import {
   accountsCommand,
   collectionsCommand,
   eventsCommand,
+  healthCommand,
   listingsCommand,
   nftsCommand,
   offersCommand,
@@ -109,6 +110,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

@@ -109,6 +109,11 @@ export class OpenSeaClient {
   getDefaultChain(): string {
     return this.defaultChain
   }
+
+  getApiKeyPrefix(): string {
+    if (this.apiKey.length < 8) return "***"
+    return `${this.apiKey.slice(0, 4)}...`
+  }
 }
 
 export class OpenSeaAPIError extends Error {

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/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

@@ -14,3 +14,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/client.test.ts

@@ -218,6 +218,17 @@ describe("OpenSeaClient", () => {
       expect(client.getDefaultChain()).toBe("ethereum")
     })
   })
+
+  describe("getApiKeyPrefix", () => {
+    it("returns first 4 characters followed by ellipsis", () => {
+      expect(client.getApiKeyPrefix()).toBe("test...")
+    })
+
+    it("masks short API keys", () => {
+      const shortKeyClient = new OpenSeaClient({ apiKey: "ab" })
+      expect(shortKeyClient.getApiKeyPrefix()).toBe("***")
+    })
+  })
 })
 
 describe("OpenSeaAPIError", () => {

test/commands/health.test.ts

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { OpenSeaAPIError } from "../../src/client.js"
+import { healthCommand } from "../../src/commands/health.js"
+import { type CommandTestContext, createCommandTestContext } from "../mocks.js"
+
+describe("healthCommand", () => {
+  let ctx: CommandTestContext
+
+  beforeEach(() => {
+    ctx = createCommandTestContext()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it("creates command with correct name", () => {
+    const cmd = healthCommand(ctx.getClient, ctx.getFormat)
+    expect(cmd.name()).toBe("health")
+  })
+
+  it("outputs ok status when both connectivity and auth succeed", async () => {
+    ctx.mockClient.get.mockResolvedValue({})
+
+    const cmd = healthCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync([], { from: "user" })
+
+    expect(ctx.mockClient.get).toHaveBeenCalledWith("/api/v2/collections", {
+      limit: 1,
+    })
+    expect(ctx.mockClient.get).toHaveBeenCalledWith(
+      "/api/v2/listings/collection/boredapeyachtclub/all",
+      {
+        limit: 1,
+      },
+    )
+    const output = JSON.parse(ctx.consoleSpy.mock.calls[0][0] as string)
+    expect(output.status).toBe("ok")
+    expect(output.key_prefix).toBe("test...")
+    expect(output.authenticated).toBe(true)
+    expect(output.message).toBe("Connectivity and authentication are working")
+  })
+
+  it("outputs error status when connectivity fails", async () => {
+    ctx.mockClient.get.mockRejectedValue(
+      new OpenSeaAPIError(500, "Internal Server Error", "/api/v2/collections"),
+    )
+
+    const mockExit = vi
+      .spyOn(process, "exit")
+      .mockImplementation(() => undefined as never)
+
+    const cmd = healthCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync([], { from: "user" })
+
+    const output = JSON.parse(ctx.consoleSpy.mock.calls[0][0] as string)
+    expect(output.status).toBe("error")
+    expect(output.authenticated).toBe(false)
+    expect(output.message).toContain("API error (500)")
+    expect(mockExit).toHaveBeenCalledWith(1)
+  })
+
+  it("outputs error status when auth fails (401)", async () => {
+    ctx.mockClient.get
+      .mockResolvedValueOnce({}) // connectivity ok
+      .mockRejectedValueOnce(
+        new OpenSeaAPIError(
+          401,
+          "Unauthorized",
+          "/api/v2/listings/collection/boredapeyachtclub/all",
+        ),
+      )
+
+    const mockExit = vi
+      .spyOn(process, "exit")
+      .mockImplementation(() => undefined as never)
+
+    const cmd = healthCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync([], { from: "user" })
+
+    const output = JSON.parse(ctx.consoleSpy.mock.calls[0][0] as string)
+    expect(output.status).toBe("error")
+    expect(output.authenticated).toBe(false)
+    expect(output.message).toContain("Authentication failed (401)")
+    expect(mockExit).toHaveBeenCalledWith(1)
+  })
+
+  it("outputs error status on network errors", async () => {
+    ctx.mockClient.get.mockRejectedValue(new TypeError("fetch failed"))
+
+    const mockExit = vi
+      .spyOn(process, "exit")
+      .mockImplementation(() => undefined as never)
+
+    const cmd = healthCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync([], { from: "user" })
+
+    const output = JSON.parse(ctx.consoleSpy.mock.calls[0][0] as string)
+    expect(output.status).toBe("error")
+    expect(output.message).toContain("Network error: fetch failed")
+    expect(mockExit).toHaveBeenCalledWith(1)
+  })
+
+  it("reports ok with unverified auth when listings endpoint has non-auth error", async () => {
+    ctx.mockClient.get
+      .mockResolvedValueOnce({}) // connectivity ok
+      .mockRejectedValueOnce(
+        new OpenSeaAPIError(
+          500,
+          "Server Error",
+          "/api/v2/listings/collection/boredapeyachtclub/all",
+        ),
+      )
+
+    const cmd = healthCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync([], { from: "user" })
+
+    const output = JSON.parse(ctx.consoleSpy.mock.calls[0][0] as string)
+    expect(output.status).toBe("ok")
+    expect(output.authenticated).toBe(false)
+    expect(output.message).toContain("could not be verified")
+  })
+
+  it("exits with code 3 on rate limit (429)", async () => {
+    ctx.mockClient.get.mockRejectedValue(
+      new OpenSeaAPIError(429, "Too Many Requests", "/api/v2/collections"),
+    )
+
+    const mockExit = vi
+      .spyOn(process, "exit")
+      .mockImplementation(() => undefined as never)
+
+    const cmd = healthCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync([], { from: "user" })
+
+    const output = JSON.parse(ctx.consoleSpy.mock.calls[0][0] as string)
+    expect(output.status).toBe("error")
+    expect(output.rate_limited).toBe(true)
+    expect(output.message).toContain("Rate limited")
+    expect(mockExit).toHaveBeenCalledWith(3)
+  })
+})