Release v1.8.0

Origin-SHA: 36691654b9a5b5cbfe770b3d23c8fc9f05179a62

Author: ryanio

.agents/rules.md

@@ -49,7 +49,10 @@ CLI (src/cli.ts)              SDK (src/sdk.ts)
 | `src/sdk.ts` | High-level SDK with domain-specific API classes (`OpenSeaCLI`). |
 | `src/cli.ts` | CLI entrypoint. Configures Commander program and global options. |
 | `src/commands/*.ts` | One file per API domain. Each exports a factory function. |
-| `src/output.ts` | Output formatting (JSON or table). |
+| `src/output.ts` | Output formatting (JSON, table, or server-side TOON via `Accept: text/markdown`). |
+| `src/parse.ts` | Shared `--body <path>` JSON file reading utility. |
+| `src/health.ts` | Health-check logic used by the `health` command. |
+| `src/wallet/` | Wallet adapter re-exports from `@opensea/wallet-adapters` and chain ID resolution. |
 | `src/types/api.ts` | TypeScript interfaces matching OpenSea API v2 response shapes. |
 | `src/types/index.ts` | Re-exports API types plus internal config types. |
 
@@ -68,6 +71,7 @@ CI runs `pnpm check-api-paths` on every PR; it fails if `src/sdk.ts` or `src/com
 Each domain has both a CLI command file (`src/commands/<domain>.ts`) and an SDK class (`src/sdk.ts`):
 
 - **accounts** - Account profile lookup
+- **assets** - Asset movement transactions (transfers)
 - **auth** - API key request and management
 - **chains** - Chain information and supported networks
 - **collections** - Collection metadata, stats, traits
@@ -218,7 +222,14 @@ npm run test -- --coverage  # Run with coverage report
 | `test/client.test.ts` | `OpenSeaClient` (get, post, graphql, error handling) |
 | `test/output.test.ts` | `formatOutput` (JSON and table formatting) |
 | `test/sdk.test.ts` | All SDK API classes and their methods |
+| `test/sdk-swaps.test.ts` | SDK swap-specific tests |
 | `test/commands/*.test.ts` | Each CLI command module (option parsing, subcommand routing, output) |
+| `test/cli-api-error.test.ts` | CLI API error handling and exit codes |
+| `test/cli-network-error.test.ts` | CLI network error handling |
+| `test/cli-rate-limit.test.ts` | CLI rate-limit (HTTP 429) handling |
+| `test/parse.test.ts` | `--body` JSON file parsing utility |
+| `test/toon.test.ts` | Toon output formatter |
+| `test/resolve-quantity.test.ts` | Quantity resolution logic |
 | `test/integration.test.ts` | End-to-end SDK flows with mocked `fetch` |
 | `test/mocks.ts` | Shared mock factories (`createCommandTestContext`, `mockFetchResponse`, `mockFetchTextResponse`) |
 

CHANGELOG.md

@@ -1,5 +1,44 @@
 # @opensea/cli
 
+## 1.8.0
+
+### Minor Changes
+
+- 0bc1053: Source `EventAsset`, `AssetEvent`, `Token`, `TokenDetails`, `TokenStats`, and `TokenSocials` from `@opensea/api-types` instead of hand-rolling them.
+
+  ## What changed
+
+  - `EventAsset` is now an alias for the api-types `Nft` schema. It gains `display_image_url`, `display_animation_url`, `original_image_url`, `original_animation_url`, and `traits` fields, and relaxes `name`, `description`, `image_url`, and `metadata_url` from required to optional (matching the OpenAPI spec — these are still present in every live response we probed).
+  - `AssetEvent` is now `AssetEventsResponse["asset_events"][number]`, i.e. the `OrderEvent | SaleEvent | TransferEvent` union from the spec. Consumers can now narrow on `event_type` to access variant-specific fields (`seller`, `buyer`, `nft` on sales; `transfer_type`, `from_address`, `to_address` on transfers; `order_type`, `asset`, `maker`, `taker` on orders). The previous `[key: string]: unknown` index signature is gone; code that read arbitrary fields off an `AssetEvent` will need to narrow first or cast.
+  - `Token`, `TokenDetails`, `TokenStats`, `TokenSocials` are now aliases for `TokenResponse`, `TokenDetailedResponse`, `TokenStatsResponse`, `TokenSocialsResponse`. Field shapes are identical except `TokenDetails` gains an optional `status` field (`"OK" | "WARNING" | "SPAM" | "LOW_LIQUIDITY"`) that the live API has been returning.
+  - `ChainInfo` / `ChainListResponse` are now aliases for the api-types `ChainResponse` / `ChainListResponse`. Identical shape.
+  - `TokenBalance` / `TokenBalancePaginatedResponse` are now aliases for the api-types `TokenBalanceResponse` / `TokenBalancePaginatedResponse`. `TokenBalance` gains optional `status`, `base_token_liquidity_usd`, and `quote_token_liquidity_usd` fields that the live API returns.
+  - `SearchResultCollection` / `SearchResultToken` / `SearchResultNFT` / `SearchResultAccount` / `SearchResult` / `SearchResponse` are now aliases for api-types `CollectionSearchResponse` / `TokenSearchResponse` / `NftSearchResponse` / `AccountSearchResponse` / `SearchResultResponse` / `SearchResponse`. Field shapes match.
+  - `SwapQuote` / `SwapTransaction` / `SwapQuoteResponse` are now aliases for api-types `SwapQuoteDetails` / `SwapTransactionResponse` / `SwapQuoteResponse`. `SwapQuote` gains optional `price_impact`, `swap_provider`, and required `costs` / `route_errors` fields.
+
+  ## Migration
+
+  Most consumers won't need any changes — the same snake_case fields are still there. Code that did `event.someArbitraryField` will need to narrow on `event_type` first:
+
+  ```ts
+  // Before
+  const seller = event.seller as string;
+
+  // After
+  if (event.event_type === "sale") {
+    const seller = event.seller; // typed as string
+  }
+  ```
+
+- a10c5c0: Switch `--format toon` to server-side TOON encoding via `Accept: text/markdown` content negotiation. The client-side encoder (`src/toon.ts` and `formatToon`) is gone now that os2-core supports TOON encoding server-side. `--format toon` still works — it just triggers a `getAsMarkdown` call instead of running a 338-line encoder client-side.
+
+  **Note:** `formatToon` is no longer exported from `@opensea/cli`. The CLI doesn't depend on `@opensea/sdk` directly (responses pass through `outputGet`'s generic JSON formatter), so the SDK 11.0 shape changes don't affect CLI output.
+
+### Patch Changes
+
+- Updated dependencies [fb03c09]
+  - @opensea/api-types@0.4.2
+
 ## 1.7.0
 
 ### Minor Changes

README.md

@@ -154,16 +154,7 @@ tokens[3]{name,symbol,chain,market_cap,price_usd}:
 next: abc123
 ```
 
-TOON collapses uniform arrays of objects into CSV-like tables with a single header row, while nested objects use YAML-like indentation. The encoder follows the [TOON v3.0 spec](https://github.com/toon-format/spec/blob/main/SPEC.md) and is implemented without external dependencies.
-
-TOON is also available programmatically via the SDK:
-
-```typescript
-import { formatToon } from "@opensea/cli"
-
-const data = await client.tokens.trending({ limit: 5 })
-console.log(formatToon(data))
-```
+TOON collapses uniform arrays of objects into CSV-like tables with a single header row, while nested objects use YAML-like indentation. The encoding is performed server-side via the `Accept: text/markdown` header — no client-side encoder is needed.
 
 ## Exit Codes
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@opensea/api-types": "^0.4.0",
+    "@opensea/api-types": "^0.4.2",
     "@opensea/wallet-adapters": "^0.3.0",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

src/client.ts

@@ -80,6 +80,41 @@ export class OpenSeaClient {
     return response.json() as Promise<T>
   }
 
+  async getAsMarkdown(
+    path: string,
+    params?: Record<string, unknown>,
+  ): Promise<{ text: string; isMarkdown: boolean }> {
+    const url = new URL(`${this.baseUrl}${path}`)
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+          url.searchParams.set(key, String(value))
+        }
+      }
+    }
+
+    if (this.verbose) {
+      console.error(`[verbose] GET ${url.toString()} (Accept: text/markdown)`)
+    }
+
+    const response = await this.fetchWithRetry(
+      url.toString(),
+      {
+        method: "GET",
+        headers: { ...this.defaultHeaders, Accept: "text/markdown" },
+      },
+      path,
+    )
+
+    const contentType = response.headers.get("content-type") ?? ""
+    const text = await response.text()
+    return {
+      text,
+      isMarkdown: contentType.includes("text/markdown"),
+    }
+  }
+
   async post<T>(
     path: string,
     body?: Record<string, unknown>,

src/commands/accounts.ts

@@ -1,20 +1,9 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import type { OutputFormat } from "../output.js"
-import { formatOutput } from "../output.js"
+import { outputGet } from "../output.js"
 import { parseIntOption } from "../parse.js"
-import type {
-  Account,
-  AccountResolveResponse,
-  Listing,
-  NFT,
-  Offer,
-  PortfolioHistoryResponse,
-  PortfolioStatsResponse,
-  ProfileCollectionsResponse,
-  TokenBalancePaginatedResponse,
-  TokenBalanceSortBy,
-} from "../types/index.js"
+import type { TokenBalanceSortBy } from "../types/index.js"
 
 export function accountsCommand(
   getClient: () => OpenSeaClient,
@@ -28,8 +17,7 @@ export function accountsCommand(
     .argument("<address>", "Wallet address")
     .action(async (address: string) => {
       const client = getClient()
-      const result = await client.get<Account>(`/api/v2/accounts/${address}`)
-      console.log(formatOutput(result, getFormat()))
+      await outputGet(client, getFormat(), `/api/v2/accounts/${address}`)
     })
 
   cmd
@@ -58,7 +46,9 @@ export function accountsCommand(
         },
       ) => {
         const client = getClient()
-        const result = await client.get<TokenBalancePaginatedResponse>(
+        await outputGet(
+          client,
+          getFormat(),
           `/api/v2/account/${address}/tokens`,
           {
             chains: options.chains,
@@ -69,7 +59,6 @@ export function accountsCommand(
             disable_spam_filtering: options.spamFilter ? undefined : true,
           },
         )
-        console.log(formatOutput(result, getFormat()))
       },
     )
 
@@ -84,10 +73,11 @@ export function accountsCommand(
     )
     .action(async (identifier: string) => {
       const client = getClient()
-      const result = await client.get<AccountResolveResponse>(
+      await outputGet(
+        client,
+        getFormat(),
         `/api/v2/accounts/resolve/${identifier}`,
       )
-      console.log(formatOutput(result, getFormat()))
     })
 
   cmd
@@ -97,11 +87,12 @@ export function accountsCommand(
     .option("--timeframe <window>", "P&L window (HOUR, DAY, WEEK, MONTH)")
     .action(async (address: string, options: { timeframe?: string }) => {
       const client = getClient()
-      const result = await client.get<PortfolioStatsResponse>(
+      await outputGet(
+        client,
+        getFormat(),
         `/api/v2/account/${address}/portfolio`,
         { timeframe: options.timeframe },
       )
-      console.log(formatOutput(result, getFormat()))
     })
 
   cmd
@@ -111,11 +102,12 @@ export function accountsCommand(
     .option("--timeframe <window>", "History window (HOUR, DAY, WEEK, MONTH)")
     .action(async (address: string, options: { timeframe?: string }) => {
       const client = getClient()
-      const result = await client.get<PortfolioHistoryResponse>(
+      await outputGet(
+        client,
+        getFormat(),
         `/api/v2/account/${address}/portfolio/history`,
         { timeframe: options.timeframe },
       )
-      console.log(formatOutput(result, getFormat()))
     })
 
   cmd
@@ -144,7 +136,9 @@ export function accountsCommand(
         },
       ) => {
         const client = getClient()
-        const result = await client.get<{ offers: Offer[]; next?: string }>(
+        await outputGet(
+          client,
+          getFormat(),
           `/api/v2/account/${address}/offers`,
           {
             after: options.after,
@@ -155,7 +149,6 @@ export function accountsCommand(
             sort_direction: options.sortDirection,
           },
         )
-        console.log(formatOutput(result, getFormat()))
       },
     )
 
@@ -185,7 +178,9 @@ export function accountsCommand(
         },
       ) => {
         const client = getClient()
-        const result = await client.get<{ offers: Offer[]; next?: string }>(
+        await outputGet(
+          client,
+          getFormat(),
           `/api/v2/account/${address}/offers_received`,
           {
             after: options.after,
@@ -196,7 +191,6 @@ export function accountsCommand(
             sort_direction: options.sortDirection,
           },
         )
-        console.log(formatOutput(result, getFormat()))
       },
     )
 
@@ -226,18 +220,19 @@ export function accountsCommand(
         },
       ) => {
         const client = getClient()
-        const result = await client.get<{
-          listings: Listing[]
-          next?: string
-        }>(`/api/v2/account/${address}/listings`, {
-          after: options.after,
-          limit: parseIntOption(options.limit, "--limit"),
-          collection_slugs: options.collectionSlugs,
-          chains: options.chains,
-          sort_by: options.sortBy,
-          sort_direction: options.sortDirection,
-        })
-        console.log(formatOutput(result, getFormat()))
+        await outputGet(
+          client,
+          getFormat(),
+          `/api/v2/account/${address}/listings`,
+          {
+            after: options.after,
+            limit: parseIntOption(options.limit, "--limit"),
+            collection_slugs: options.collectionSlugs,
+            chains: options.chains,
+            sort_by: options.sortBy,
+            sort_direction: options.sortDirection,
+          },
+        )
       },
     )
 
@@ -262,7 +257,9 @@ export function accountsCommand(
         },
       ) => {
         const client = getClient()
-        const result = await client.get<{ nfts: NFT[]; next?: string }>(
+        await outputGet(
+          client,
+          getFormat(),
           `/api/v2/account/${address}/favorites`,
           {
             after: options.after,
@@ -272,7 +269,6 @@ export function accountsCommand(
             chains: options.chains,
           },
         )
-        console.log(formatOutput(result, getFormat()))
       },
     )
 
@@ -293,15 +289,16 @@ export function accountsCommand(
         },
       ) => {
         const client = getClient()
-        const result = await client.get<ProfileCollectionsResponse>(
+        await outputGet(
+          client,
+          getFormat(),
           `/api/v2/account/${address}/collections`,
           {
             after: options.after,
             limit: parseIntOption(options.limit, "--limit"),
             chains: options.chains,
           },
         )
-        console.log(formatOutput(result, getFormat()))
       },
     )
 

src/commands/chains.ts

@@ -1,8 +1,7 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import type { OutputFormat } from "../output.js"
-import { formatOutput } from "../output.js"
-import type { ChainListResponse } from "../types/index.js"
+import { outputGet } from "../output.js"
 
 export function chainsCommand(
   getClient: () => OpenSeaClient,
@@ -15,8 +14,7 @@ export function chainsCommand(
     .description("List all supported blockchains and their capabilities")
     .action(async () => {
       const client = getClient()
-      const result = await client.get<ChainListResponse>("/api/v2/chains")
-      console.log(formatOutput(result, getFormat()))
+      await outputGet(client, getFormat(), "/api/v2/chains")
     })
 
   return cmd