Release v0.4.0

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,25 @@
 # @opensea/tool-sdk
 
+## 0.4.0
+
+### Minor Changes
+
+- 5838915: DX improvements from canary builder feedback:
+
+  - `createWellKnownHandler` now accepts `ManifestDefinition` (with `EnvResolver` lambdas) and resolves internally on first request — eliminates the silent-failure footgun where lambda fields would serialize as `undefined`. Accepts an optional `env` parameter for non-Node runtimes (Cloudflare Workers, Bun).
+  - Well-known handler no longer 404s on pathname mismatch — relies on framework router. If you mounted `createWellKnownHandler` as a fall-through, scope it to the well-known path explicitly.
+  - `defineToolPaywall` recipient accepts `EnvResolver<Address>` so the payout address can be read from env vars at request time instead of module-load time
+  - `defineToolPaywall` returns `onSettle` callback for post-payment telemetry/logging
+  - Template `package.json` files inject the current SDK version at `init` time instead of pinning stale `^0.1.0`
+  - Vercel adapter uses `x-forwarded-proto` header (consistent with Express adapter)
+  - `describeToolAccess` helper reads a tool's predicate name and requirements from the registry; `decodeRequirement` decodes known kinds (ERC-721, ERC-1155, Subscription) into typed objects
+  - `onSettle` payer is now sourced from the facilitator's `/verify` response (reliable for pure-x402 tools) with fallback to `ctx.callerAddress`
+  - `registerTool` and `updateToolMetadata` validate URI length client-side before sending the transaction
+  - Templates include `EnvResolver` lambda examples in comments
+  - `init` command prints workspace warning for pnpm users
+
+- ba59886: Add `@opensea/tool-sdk/testing` subpath export with test utilities for tool builders: `createMockManifest`, `createMockToolContext`, `mockFetch`, and `createTestHandler`.
+
 ## 0.3.1
 
 ### Patch Changes

SKILLS.md

@@ -689,6 +689,35 @@ CompositePredicate.setComposition(toolId, Op.ALL, [
 ])
 ```
 
+### SDK Helpers for Reading Predicate Requirements
+
+Use `describeToolAccess` to read a tool's predicate name, requirements, and logic from the registry, and `decodeRequirement` to decode the raw `kind`/`data` into typed objects:
+
+```typescript
+import { describeToolAccess, decodeRequirement } from "@opensea/tool-sdk"
+
+const description = await describeToolAccess({ toolId: 1n })
+// { openAccess: false, predicateName: "ERC721OwnerPredicate", requirements: [...], logic: "OR" }
+
+for (const req of description.requirements) {
+  const decoded = decodeRequirement(req)
+  switch (decoded.type) {
+    case "erc721":
+      console.log(`Requires NFT from collection ${decoded.collection}`)
+      break
+    case "erc1155":
+      console.log(`Requires token #${decoded.tokenId} from ${decoded.collection}`)
+      break
+    case "subscription":
+      console.log(`Requires subscription (min tier ${decoded.minTier}) from ${decoded.collection}`)
+      break
+    case "unknown":
+      console.log(`Unknown requirement kind ${decoded.kind}`)
+      break
+  }
+}
+```
+
 ---
 
 ## 7. Wallet Setup

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "SDK and CLI for building ERC-XXXX compliant AI agent tools",
   "repository": {
@@ -18,6 +18,10 @@
     "./cloudflare": {
       "types": "./dist/adapters/cloudflare.d.ts",
       "default": "./dist/adapters/cloudflare.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
     }
   },
   "files": [