@cascade-fyi/sati-sdk 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-02-12
+
+### Added
+
+- `createSatiUploader()` - zero-config hosted metadata uploader via sati.cascade.fyi (no Pinata JWT needed)
+- Default Photon RPC proxy URLs (`sati.cascade.fyi/api/photon/{network}`) - SDK now works without a Helius API key for Light Protocol queries
+
+### Changed
+
+- Photon URL fallback changed from `rpcUrl` to hosted proxy - users only need `network` for a working setup
+- `createSatiUploader` exported from main entry alongside `createPinataUploader`
+
+## [0.5.0] - 2026-02-12
+
+### Added
+
+- `createPinataUploader(jwt)` and `MetadataUploader` interface exported from main entry - pluggable IPFS upload for agent registration
+- `uploadRegistrationFile(params, uploader)` convenience method on `Sati` class
+- Registration `Endpoint` type extended with optional fields: `mcpTools`, `mcpPrompts`, `mcpResources`, `a2aSkills`, `skills`, `domains`
+- Gateway verification after Pinata uploads - catches silent upload failures with 5s timeout (non-fatal for timeouts/rate limits)
+
+### Changed
+
+- **BREAKING**: Pinata uploader migrated from v1 (`pinJSONToIPFS`) to v3 Files API (`uploads.pinata.cloud/v3/files`) - returns CIDv1 (`bafkrei...`) instead of CIDv0 (`Qm...`). Both formats are valid IPFS URIs.
+- Compressed attestation queries now use server-side memcmp filtering via Photon RPC for `sasSchema` and `agentMint` (significant performance improvement for large datasets)
+- Client-side filtering retained for `counterparty` and `outcome` fields only
+
+### Dependencies
+
+- Requires `@cascade-fyi/compression-kit` >= 0.2.1 (memcmp filter support)
+
 ## [0.4.2] - 2026-02-10
 
 ### Fixed
@@ -85,6 +116,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Compressed attestation storage via Light Protocol
 - Basic querying via Photon RPC
 
+[0.6.0]: https://github.com/cascade-protocol/sati/compare/@cascade-fyi/sati-sdk@0.5.0...@cascade-fyi/sati-sdk@0.6.0
+[0.5.0]: https://github.com/cascade-protocol/sati/compare/@cascade-fyi/sati-sdk@0.4.2...@cascade-fyi/sati-sdk@0.5.0
 [0.4.2]: https://github.com/cascade-protocol/sati/compare/@cascade-fyi/sati-sdk@0.4.1...@cascade-fyi/sati-sdk@0.4.2
 [0.4.1]: https://github.com/cascade-protocol/sati/compare/@cascade-fyi/sati-sdk@0.4.0...@cascade-fyi/sati-sdk@0.4.1
 [0.4.0]: https://github.com/cascade-protocol/sati/compare/@cascade-fyi/sati-sdk@0.3.0...@cascade-fyi/sati-sdk@0.4.0

package/README.md

@@ -41,6 +41,7 @@ const result = await sati.registerAgent({
   payer,                          // KeyPairSigner (pays fees + becomes owner)
   name: "MyAgent",                // Max 32 chars
   uri: "ipfs://Qm...",            // Agent metadata JSON
+  owner: ownerAddress,            // Optional: mint NFT to a different address
   additionalMetadata: [           // Optional key-value pairs
     { key: "version", value: "1.0" },
   ],
@@ -51,6 +52,48 @@ console.log(result.mint);         // Agent's token address (identity)
 console.log(result.memberNumber); // Registry member number
 ```
 
+### IPFS Upload + Registration
+
+Upload a registration file to IPFS and register in one flow:
+
+```typescript
+import { createPinataUploader } from "@cascade-fyi/sati-sdk";
+
+const uploader = createPinataUploader(process.env.PINATA_JWT!);
+
+// Build + upload registration file, then register
+const uri = await sati.uploadRegistrationFile(
+  {
+    name: "MyAgent",
+    description: "AI assistant",
+    image: "https://example.com/avatar.png",
+    endpoints: [
+      { name: "MCP", endpoint: "https://myagent.com/mcp", version: "2025-06-18", mcpTools: ["search"] },
+      { name: "A2A", endpoint: "https://myagent.com/.well-known/agent.json", version: "0.3.0" },
+    ],
+    supportedTrust: ["reputation"],
+  },
+  uploader,
+);
+
+const result = await sati.registerAgent({ payer, name: "MyAgent", uri });
+```
+
+### Custom Storage Providers
+
+Implement the `MetadataUploader` interface for any storage backend:
+
+```typescript
+import type { MetadataUploader } from "@cascade-fyi/sati-sdk";
+
+const arweaveUploader: MetadataUploader = {
+  async upload(data: unknown): Promise<string> {
+    // Upload to Arweave and return ar:// URI
+    return `ar://${txId}`;
+  },
+};
+```
+
 ---
 
 ## Creating Attestations