Release v0.2.2

Author: ryanio

AGENTS.md

@@ -0,0 +1,47 @@
+# api-types — Agent Conventions
+
+Auto-generated TypeScript types from the OpenSea API v2 OpenAPI spec. Source of truth for API types across the devtools ecosystem.
+
+## Quick Reference
+
+```bash
+cd packages/api-types
+pnpm run update-spec   # Fetch latest OpenAPI spec from api.opensea.io
+pnpm run build         # Regenerate types from spec + bundle with tsup
+pnpm run lint          # Type-check with tsc --noEmit
+pnpm run test          # Run smoke tests with Vitest
+```
+
+## Architecture
+
+| File | Role |
+|------|------|
+| `opensea-api.json` | Local copy of the OpenAPI spec (fetched from `api.opensea.io/api/v2/openapi.json`) |
+| `scripts/update-spec.mjs` | Fetches the latest spec; falls back to existing local file on network errors |
+| `src/generated.ts` | Auto-generated types from `openapi-typescript` — do not edit manually |
+| `src/index.ts` | Named re-exports of commonly used schema types (collections, NFTs, orders, etc.) |
+| `test/smoke.test.ts` | Smoke test verifying the generated types compile and export correctly |
+
+## Review Checklist
+
+When reviewing changes to this package, verify:
+
+1. **Never hand-edit `src/generated.ts`**. It is produced by `openapi-typescript` from `opensea-api.json`. Changes are overwritten on the next build.
+
+2. **New types in `src/index.ts`**: When the spec adds new schemas, add named re-exports in `src/index.ts` grouped by domain (Collections, NFTs, Orders, etc.). Other packages import from `@opensea/api-types` — unnamed schemas are only accessible via `components["schemas"]["..."]`.
+
+3. **Downstream consumers**: The SDK (`@opensea/sdk`) and CLI (`@opensea/cli`) depend on this package. After updating the spec, rebuild api-types and verify downstream packages still compile:
+   ```bash
+   pnpm --filter @opensea/api-types run build
+   pnpm --filter sdk run check-types
+   pnpm --filter cli run build
+   ```
+
+4. **Chain enum sync**: The SDK's `Chain` enum has a compile-time assertion against `ChainIdentifier` from this package. If the spec adds a new chain, the SDK build will fail until `Chain` is updated.
+
+## Conventions
+
+- ESM-only (`"type": "module"`).
+- Dual CJS/ESM output via tsup (consumers can `import` or `require`).
+- The `update-spec` script is idempotent — safe to run anytime. It prints the path/schema counts on success.
+- Use `/sync-openapi` (monorepo slash command) for the full flow: fetch spec, regenerate, open a PR if changed.

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/api-types
 
+## 0.2.2
+
+### Patch Changes
+
+- 33bf144: Sync OpenAPI spec: add `traits` query param to three collection-scoped read endpoints (`GET /api/v2/collection/{slug}/nfts`, `GET /api/v2/listings/collection/{slug}/best`, `GET /api/v2/events/collection/{slug}`) — accepts a JSON-encoded array of `{traitType, value}` filters that are AND-combined server-side. Adds optional `status` field to `TokenBalanceResponse` (`OK` | `WARNING` | `SPAM` | `LOW_LIQUIDITY` | `LOW_VALUE`) surfaced when callers pass `disable_spam_filtering=true` on the account tokens endpoint, whose `limit` max also rises from 25 to 100. Non-breaking, additive.
+
 ## 0.2.1
 
 ### Patch Changes

biome.json

@@ -5,13 +5,13 @@
       "**/*.ts",
       "**/*.js",
       "**/*.json",
-      "!**/node_modules/**",
-      "!**/dist/**",
-      "!**/lib/**",
-      "!**/coverage/**",
-      "!**/.nyc_output/**",
-      "!packages/sdk/src/typechain/**",
-      "!**/typechain/**",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/lib",
+      "!**/coverage",
+      "!**/.nyc_output",
+      "!packages/sdk/src/typechain",
+      "!**/typechain",
       "!packages/api-types/src/generated.ts",
       "!**/pnpm-lock.yaml",
       "!**/package-lock.json"
@@ -41,9 +41,10 @@
         "noExplicitAny": "off"
       },
       "correctness": {
-        "noUnusedImports": "warn"
+        "noUnusedImports": "error"
       },
       "style": {
+        "noNonNullAssertion": "error",
         "noUnusedTemplateLiteral": "off"
       }
     }
@@ -53,8 +54,8 @@
       "includes": ["**/*.test.ts", "**/*.spec.ts", "**/test/**"],
       "linter": {
         "rules": {
-          "correctness": {
-            "noUnusedImports": "off"
+          "style": {
+            "noNonNullAssertion": "off"
           }
         }
       }

opensea-api.json

@@ -1967,7 +1967,7 @@
       "get": {
         "tags": ["Listing Endpoints"],
         "summary": "Get best listings by collection",
-        "description": "Get the best listings for a collection sorted by price ascending. Note: results are not deduplicated by token ID — if a token has multiple listings, each listing is returned individually. Filter client-side if you need unique tokens.",
+        "description": "Get the best listings for a collection sorted by price ascending. Optionally filter by item traits using the 'traits' query parameter with a JSON array of trait filters. Multiple traits are AND-combined (items must match all). Note: results are not deduplicated by token ID — if a token has multiple listings, each listing is returned individually. Filter client-side if you need unique tokens. Example: ?traits=[{\"traitType\":\"Background\",\"value\":\"Red\"}]",
         "operationId": "get_best_listings_collection",
         "parameters": [
           {
@@ -1988,6 +1988,21 @@
               "type": "boolean"
             }
           },
+          {
+            "name": "traits",
+            "in": "query",
+            "description": "JSON array of trait filters to narrow listings by item traits. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{\"traitType\":\"Background\",\"value\":\"Red\"}]",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "example": [
+              {
+                "traitType": "Background",
+                "value": "Red"
+              }
+            ]
+          },
           {
             "name": "limit",
             "in": "query",
@@ -2203,7 +2218,7 @@
       "get": {
         "tags": ["Analytics Endpoints"],
         "summary": "Get events (by collection)",
-        "description": "Get a list of events for a collection.",
+        "description": "Get a list of events for a collection. Optionally filter by traits to only return events for items matching the specified trait criteria.",
         "operationId": "list_events_by_collection",
         "parameters": [
           {
@@ -2257,6 +2272,21 @@
               }
             }
           },
+          {
+            "name": "traits",
+            "in": "query",
+            "description": "JSON array of trait filters. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{\"traitType\":\"Background\",\"value\":\"Red\"}]",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "example": [
+              {
+                "traitType": "Background",
+                "value": "Red"
+              }
+            ]
+          },
           {
             "name": "limit",
             "in": "query",
@@ -2997,7 +3027,7 @@
       "get": {
         "tags": ["NFT Endpoints"],
         "summary": "Get NFTs by collection",
-        "description": "Get all NFTs in a specific collection.",
+        "description": "Get NFTs in a specific collection. Optionally filter by traits using the 'traits' query parameter with a JSON array of trait filters. Multiple traits are AND-combined (items must match all specified traits). Example: ?traits=[{\"traitType\":\"Background\",\"value\":\"Red\"},{\"traitType\":\"Eyes\",\"value\":\"Blue\"}]",
         "operationId": "get_nfts_by_collection",
         "parameters": [
           {
@@ -3009,6 +3039,21 @@
               "type": "string"
             }
           },
+          {
+            "name": "traits",
+            "in": "query",
+            "description": "JSON array of trait filters. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{\"traitType\":\"Background\",\"value\":\"Red\"}]",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "example": [
+              {
+                "traitType": "Background",
+                "value": "Red"
+              }
+            ]
+          },
           {
             "name": "limit",
             "in": "query",
@@ -3606,7 +3651,7 @@
           {
             "name": "limit",
             "in": "query",
-            "description": "Number of results to return (default: 20, max: 25)",
+            "description": "Number of results to return (default: 20, max: 100)",
             "required": false,
             "schema": {
               "type": "integer",
@@ -3660,7 +3705,7 @@
           {
             "name": "disable_spam_filtering",
             "in": "query",
-            "description": "Disable spam token filtering (default: false)",
+            "description": "When true, disables OpenSea's heuristic spam filtering and returns tokens that would normally be hidden (low liquidity, dust, flagged-as-spam, etc.). Tokens flagged for trust & safety enforcement or as malicious are still filtered out regardless. Surfaced tokens carry a `status` field on the response indicating why they would have been filtered.",
             "required": false,
             "schema": {
               "type": "boolean",
@@ -7869,6 +7914,12 @@
           "opensea_url": {
             "type": "string",
             "description": "URL to the token page on OpenSea"
+          },
+          "status": {
+            "type": "string",
+            "default": "OK",
+            "description": "Token status relative to OpenSea's spam-classification rules. `OK` for tokens that pass all spam filters (the normal case); populated with a more specific value for tokens surfaced via `disable_spam_filtering=true` that would normally be hidden. Categories are intentionally broad and may evolve. Possible values, in decreasing severity: `WARNING` (flagged as risky/suspicious — caution advised), `SPAM` (flagged as spam), `LOW_LIQUIDITY` (insufficient pool liquidity), `LOW_VALUE` (dust holding < $0.01), `OK` (passes all filters).",
+            "enum": ["OK", "WARNING", "SPAM", "LOW_LIQUIDITY", "LOW_VALUE"]
           }
         },
         "required": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/api-types",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Auto-generated TypeScript types from the OpenSea API OpenAPI spec",
   "license": "MIT",
   "author": "OpenSea Developers",

src/generated.ts

@@ -543,7 +543,7 @@ export interface paths {
         };
         /**
          * Get best listings by collection
-         * @description Get the best listings for a collection sorted by price ascending. Note: results are not deduplicated by token ID — if a token has multiple listings, each listing is returned individually. Filter client-side if you need unique tokens.
+         * @description Get the best listings for a collection sorted by price ascending. Optionally filter by item traits using the 'traits' query parameter with a JSON array of trait filters. Multiple traits are AND-combined (items must match all). Note: results are not deduplicated by token ID — if a token has multiple listings, each listing is returned individually. Filter client-side if you need unique tokens. Example: ?traits=[{"traitType":"Background","value":"Red"}]
          */
         get: operations["get_best_listings_collection"];
         put?: never;
@@ -603,7 +603,7 @@ export interface paths {
         };
         /**
          * Get events (by collection)
-         * @description Get a list of events for a collection.
+         * @description Get a list of events for a collection. Optionally filter by traits to only return events for items matching the specified trait criteria.
          */
         get: operations["list_events_by_collection"];
         put?: never;
@@ -803,7 +803,7 @@ export interface paths {
         };
         /**
          * Get NFTs by collection
-         * @description Get all NFTs in a specific collection.
+         * @description Get NFTs in a specific collection. Optionally filter by traits using the 'traits' query parameter with a JSON array of trait filters. Multiple traits are AND-combined (items must match all specified traits). Example: ?traits=[{"traitType":"Background","value":"Red"},{"traitType":"Eyes","value":"Blue"}]
          */
         get: operations["get_nfts_by_collection"];
         put?: never;
@@ -2684,6 +2684,12 @@ export interface components {
             usd_value: string;
             /** @description URL to the token page on OpenSea */
             opensea_url: string;
+            /**
+             * @description Token status relative to OpenSea's spam-classification rules. `OK` for tokens that pass all spam filters (the normal case); populated with a more specific value for tokens surfaced via `disable_spam_filtering=true` that would normally be hidden. Categories are intentionally broad and may evolve. Possible values, in decreasing severity: `WARNING` (flagged as risky/suspicious — caution advised), `SPAM` (flagged as spam), `LOW_LIQUIDITY` (insufficient pool liquidity), `LOW_VALUE` (dust holding < $0.01), `OK` (passes all filters).
+             * @default OK
+             * @enum {string}
+             */
+            status: "OK" | "WARNING" | "SPAM" | "LOW_LIQUIDITY" | "LOW_VALUE";
         };
     };
     responses: {
@@ -3786,6 +3792,16 @@ export interface operations {
             query?: {
                 /** @description Whether to include private listings; defaults to false */
                 include_private_listings?: boolean;
+                /**
+                 * @description JSON array of trait filters to narrow listings by item traits. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{"traitType":"Background","value":"Red"}]
+                 * @example [
+                 *       {
+                 *         "traitType": "Background",
+                 *         "value": "Red"
+                 *       }
+                 *     ]
+                 */
+                traits?: string;
                 /**
                  * @description Number of items to return per page
                  * @example 20
@@ -3895,6 +3911,16 @@ export interface operations {
                 before?: number;
                 /** @description Filter by event types. To get order invalidation and revalidation events, please use the Stream API. The order status can also be checked on the Get Order endpoint. */
                 event_type?: ("sale" | "transfer" | "mint" | "listing" | "offer" | "trait_offer" | "collection_offer")[];
+                /**
+                 * @description JSON array of trait filters. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{"traitType":"Background","value":"Red"}]
+                 * @example [
+                 *       {
+                 *         "traitType": "Background",
+                 *         "value": "Red"
+                 *       }
+                 *     ]
+                 */
+                traits?: string;
                 /**
                  * @description Number of items to return per page
                  * @example 20
@@ -4284,6 +4310,16 @@ export interface operations {
     get_nfts_by_collection: {
         parameters: {
             query?: {
+                /**
+                 * @description JSON array of trait filters. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{"traitType":"Background","value":"Red"}]
+                 * @example [
+                 *       {
+                 *         "traitType": "Background",
+                 *         "value": "Red"
+                 *       }
+                 *     ]
+                 */
+                traits?: string;
                 /**
                  * @description Number of items to return per page
                  * @example 20
@@ -4636,7 +4672,7 @@ export interface operations {
         parameters: {
             query?: {
                 /**
-                 * @description Number of results to return (default: 20, max: 25)
+                 * @description Number of results to return (default: 20, max: 100)
                  * @example 20
                  */
                 limit?: number;
@@ -4656,7 +4692,7 @@ export interface operations {
                  */
                 sort_direction?: "asc" | "desc";
                 /**
-                 * @description Disable spam token filtering (default: false)
+                 * @description When true, disables OpenSea's heuristic spam filtering and returns tokens that would normally be hidden (low liquidity, dust, flagged-as-spam, etc.). Tokens flagged for trust & safety enforcement or as malicious are still filtered out regardless. Surfaced tokens carry a `status` field on the response indicating why they would have been filtered.
                  * @example false
                  */
                 disable_spam_filtering?: boolean;

test/smoke.test.ts

@@ -11,7 +11,6 @@ import type {
   ChainIdentifier,
   CollectionResponse,
   Contract,
-  components,
   Event,
   FulfillListingResponse,
   Listing,
@@ -23,7 +22,6 @@ import type {
   OperationRequestBody,
   OperationResponse,
   Order,
-  operations,
   paths,
   Schemas,
 } from "../src/index.js"