@cascade-fyi/sati-sdk 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -4641,6 +4641,36 @@ function deserializeEncryptedPayload(bytes) {
 
 //#endregion
 //#region src/uploaders.ts
+const SATI_UPLOAD_URL = "https://sati.cascade.fyi/api/upload-metadata";
+/**
+* Create a hosted SATI metadata uploader.
+*
+* Uploads JSON to the SATI Identity Service which pins it to IPFS via Pinata.
+* No API keys needed - zero-config alternative to `createPinataUploader()`.
+*
+* @returns MetadataUploader that uploads via sati.cascade.fyi
+*
+* @example
+* ```typescript
+* const uploader = createSatiUploader();
+* const uri = await uploader.upload({ name: "MyAgent" });
+* // "ipfs://QmXyz..."
+* ```
+*/
+function createSatiUploader() {
+	return { async upload(data) {
+		const response = await fetch(SATI_UPLOAD_URL, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(data)
+		});
+		if (!response.ok) {
+			const text = await response.text();
+			throw new Error(`Metadata upload failed (${response.status}): ${text}`);
+		}
+		return (await response.json()).uri;
+	} };
+}
 /**
 * Create a Pinata IPFS uploader using the v3 Files API.
 *
@@ -4677,8 +4707,7 @@ function createPinataUploader(jwt) {
 			const verifyResponse = await fetch(`https://gateway.pinata.cloud/ipfs/${cid}`, { signal: AbortSignal.timeout(5e3) });
 			if (!verifyResponse.ok && verifyResponse.status !== 429) throw new Error(`Pinata returned CID ${cid} but content not accessible on gateway (HTTP ${verifyResponse.status})`);
 		} catch (verifyError) {
-			if (verifyError instanceof Error && !verifyError.message.includes("not accessible")) console.warn(`[SATI] Pinata gateway verification skipped for ${cid}: ${verifyError.message}`);
-			else throw verifyError;
+			if (verifyError instanceof Error && verifyError.message.includes("not accessible")) throw verifyError;
 		}
 		return `ipfs://${cid}`;
 	} };
@@ -4872,8 +4901,8 @@ function buildRegistrationFile(params) {
 * Fetch and parse a registration file from URI.
 *
 * - Returns null on network errors or invalid URIs
-* - Validates structure, logs warnings for non-conforming files
-* - Never throws
+* - Validates structure, returns raw data for non-conforming files
+* - Never throws, never logs to console
 */
 async function fetchRegistrationFile(uri) {
 	if (!uri) return null;
@@ -4883,19 +4912,12 @@ async function fetchRegistrationFile(uri) {
 	else if (!uri.startsWith("http://") && !uri.startsWith("https://")) return null;
 	try {
 		const response = await fetch(url);
-		if (!response.ok) {
-			console.warn(`[SATI] Failed to fetch metadata from ${url}: ${response.status}`);
-			return null;
-		}
+		if (!response.ok) return null;
 		const data = await response.json();
 		const result = RegistrationFileSchema.safeParse(data);
-		if (!result.success) {
-			console.warn(`[SATI] Registration file validation issues:`, result.error.issues);
-			return data;
-		}
+		if (!result.success) return data;
 		return result.data;
-	} catch (error) {
-		console.warn(`[SATI] Failed to fetch metadata from ${uri}:`, error);
+	} catch {
 		return null;
 	}
 }
@@ -4961,6 +4983,211 @@ function getSatiAgentIds(file) {
 	return file.registrations?.filter((r) => typeof r.agentRegistry === "string" && r.agentRegistry.startsWith(SATI_CHAIN_ID)).map((r) => String(r.agentId)) ?? [];
 }
 
+//#endregion
+//#region src/cache.ts
+var FeedbackCache = class {
+	cache = /* @__PURE__ */ new Map();
+	constructor(ttlMs = 3e4) {
+		this.ttlMs = ttlMs;
+	}
+	/** Get cached data or null if expired/missing. */
+	get(key) {
+		const entry = this.cache.get(key);
+		if (!entry || Date.now() > entry.expires) {
+			if (entry) this.cache.delete(key);
+			return null;
+		}
+		return entry.data;
+	}
+	/** Store data with TTL. */
+	set(key, data) {
+		this.cache.set(key, {
+			data,
+			expires: Date.now() + this.ttlMs
+		});
+	}
+	/** Invalidate a specific key, or all entries if no key given. */
+	invalidate(key) {
+		if (key) this.cache.delete(key);
+		else this.cache.clear();
+	}
+	/** Build a cache key from schema and optional agent mint. */
+	static cacheKey(sasSchema, agentMint) {
+		return `${sasSchema}:${agentMint ?? "*"}`;
+	}
+};
+
+//#endregion
+//#region src/agent-builder.ts
+var SatiAgentBuilder = class {
+	_params;
+	_identity;
+	_sati;
+	constructor(sati, name, description, image) {
+		this._sati = sati;
+		this._params = {
+			name,
+			description,
+			image,
+			endpoints: [],
+			active: true
+		};
+	}
+	/** Current registration file parameters. */
+	get params() {
+		return this._params;
+	}
+	/** On-chain identity (available after register/load). */
+	get identity() {
+		return this._identity;
+	}
+	/** Set a generic endpoint. */
+	setEndpoint(endpoint) {
+		if (!this._params.endpoints) this._params.endpoints = [];
+		this._params.endpoints = this._params.endpoints.filter((ep) => ep.name !== endpoint.name);
+		this._params.endpoints.push(endpoint);
+		return this;
+	}
+	/**
+	* Set MCP endpoint.
+	*
+	* Unlike agent0-sdk's `SatiAgent.setMCP()`, this does NOT auto-fetch capabilities.
+	* Pass tools/prompts/resources explicitly via the `meta` parameter.
+	*/
+	setMCP(url, version, meta) {
+		return this.setEndpoint({
+			name: "MCP",
+			endpoint: url,
+			...version && { version },
+			...meta?.tools?.length && { mcpTools: meta.tools },
+			...meta?.prompts?.length && { mcpPrompts: meta.prompts },
+			...meta?.resources?.length && { mcpResources: meta.resources }
+		});
+	}
+	/** Set A2A endpoint. */
+	setA2A(url, version, meta) {
+		return this.setEndpoint({
+			name: "A2A",
+			endpoint: url,
+			...version && { version },
+			...meta?.skills?.length && { a2aSkills: meta.skills }
+		});
+	}
+	/** Set wallet endpoint. */
+	setWallet(address$5) {
+		return this.setEndpoint({
+			name: "agentWallet",
+			endpoint: address$5
+		});
+	}
+	/** Remove an endpoint by name. */
+	removeEndpoint(name) {
+		if (this._params.endpoints) this._params.endpoints = this._params.endpoints.filter((ep) => ep.name !== name);
+		return this;
+	}
+	/** Set agent active status. */
+	setActive(active) {
+		this._params.active = active;
+		return this;
+	}
+	/** Set x402 payment support. */
+	setX402Support(x402) {
+		this._params.x402support = x402;
+		return this;
+	}
+	/** Set supported trust mechanisms. */
+	setSupportedTrust(trusts) {
+		this._params.supportedTrust = trusts;
+		return this;
+	}
+	/** Set external URL. */
+	setExternalUrl(url) {
+		this._params.externalUrl = url;
+		return this;
+	}
+	/** Update basic info. */
+	updateInfo(opts) {
+		if (opts.name !== void 0) this._params.name = opts.name;
+		if (opts.description !== void 0) this._params.description = opts.description;
+		if (opts.image !== void 0) this._params.image = opts.image;
+		return this;
+	}
+	/**
+	* Upload registration file and register agent on-chain.
+	*
+	* @returns Registration result with mint address, member number, and signature
+	*/
+	async register(opts) {
+		const uri = await this._sati.uploadRegistrationFile(this._params, opts.uploader);
+		return this._registerWithUri(uri, opts);
+	}
+	/**
+	* Register agent on-chain with a pre-existing URI.
+	*
+	* Use when you already have a hosted registration file.
+	*/
+	async registerWithUri(opts) {
+		return this._registerWithUri(opts.uri, opts);
+	}
+	/**
+	* Re-upload registration file and update the on-chain URI.
+	*
+	* Use after modifying the builder via fluent setters.
+	*/
+	async update(opts) {
+		if (!this._identity) throw new Error("Agent not registered on-chain. Call register() first.");
+		const uri = await this._sati.uploadRegistrationFile(this._params, opts.uploader);
+		return this._updateUri(uri, opts);
+	}
+	/**
+	* Update the on-chain URI to point to a new registration file.
+	*/
+	async updateUri(opts) {
+		if (!this._identity) throw new Error("Agent not registered on-chain. Call register() first.");
+		return this._updateUri(opts.uri, opts);
+	}
+	/**
+	* Load existing on-chain identity into this builder.
+	* Useful for wrapping an already-registered agent.
+	*/
+	setIdentity(identity) {
+		this._identity = identity;
+		return this;
+	}
+	async _registerWithUri(uri, opts) {
+		if (this._identity) throw new Error("Agent is already registered on-chain. Use update() instead.");
+		const result = await this._sati.registerAgent({
+			payer: opts.payer,
+			name: this._params.name,
+			uri,
+			nonTransferable: opts.nonTransferable,
+			owner: opts.owner
+		});
+		this._identity = {
+			mint: result.mint,
+			owner: opts.owner ?? opts.payer.address,
+			name: this._params.name,
+			uri,
+			memberNumber: result.memberNumber,
+			additionalMetadata: {},
+			nonTransferable: opts.nonTransferable ?? false
+		};
+		return result;
+	}
+	async _updateUri(uri, opts) {
+		const identity = this._identity;
+		if (!identity) throw new Error("Agent not registered on-chain. Call register() first.");
+		const result = await this._sati.updateAgentMetadata({
+			payer: opts.payer,
+			owner: opts.owner,
+			mint: identity.mint,
+			updates: { uri }
+		});
+		identity.uri = uri;
+		return { signature: result.signature };
+	}
+};
+
 //#endregion
 //#region src/client.ts
 /**
@@ -4987,6 +5214,11 @@ const WS_URLS = {
 	devnet: "wss://api.devnet.solana.com",
 	localnet: "ws://127.0.0.1:8900"
 };
+const PHOTON_URLS = {
+	mainnet: "https://sati.cascade.fyi/api/photon/mainnet",
+	devnet: "https://sati.cascade.fyi/api/photon/devnet",
+	localnet: "http://127.0.0.1:8899"
+};
 /**
 * Convert an Address to Base58EncodedBytes for RPC memcmp filters.
 */
@@ -5047,6 +5279,9 @@ var Sati = class {
 	rpcSubscriptions;
 	sendAndConfirm;
 	lightClient;
+	_deployedConfig;
+	_feedbackCache = new FeedbackCache();
+	_onWarning;
 	/** Network configuration */
 	network;
 	constructor(options) {
@@ -5059,7 +5294,9 @@ var Sati = class {
 			rpc: this.rpc,
 			rpcSubscriptions: this.rpcSubscriptions
 		});
-		this.lightClient = createSATILightClient(options.photonRpcUrl ?? rpcUrl);
+		this.lightClient = createSATILightClient(options.photonRpcUrl ?? PHOTON_URLS[options.network]);
+		this._deployedConfig = loadDeployedConfig(options.network);
+		this._onWarning = options.onWarning;
 	}
 	/** @internal */
 	getRpc() {
@@ -6179,6 +6416,432 @@ var Sati = class {
 		await this.sendAndConfirm(signedTx, { commitment: "confirmed" });
 		return signature;
 	}
+	/** Deployed SAS configuration for this network (null for localnet unless deployed). */
+	get deployedConfig() {
+		return this._deployedConfig;
+	}
+	/** FeedbackPublic schema address (CounterpartySigned mode). */
+	get feedbackPublicSchema() {
+		return this._deployedConfig?.schemas.feedbackPublic;
+	}
+	/** Feedback schema address (DualSignature mode). */
+	get feedbackSchema() {
+		return this._deployedConfig?.schemas.feedback;
+	}
+	/** Validation schema address. */
+	get validationSchema() {
+		return this._deployedConfig?.schemas.validation;
+	}
+	/** Address Lookup Table for transaction compression. */
+	get lookupTable() {
+		return this._deployedConfig?.lookupTable;
+	}
+	/**
+	* Give feedback to an agent (simplified).
+	*
+	* Uses FeedbackPublicV1 schema (CounterpartySigned mode).
+	* Automatically handles SIWS message construction and signing.
+	*
+	* @example
+	* ```typescript
+	* const result = await sati.giveFeedback({
+	*   payer: myKeypair,
+	*   agentMint: address("Agent..."),
+	*   score: 85,
+	*   tags: ["quality", "speed"],
+	*   message: "Great response time",
+	* });
+	* ```
+	*/
+	async giveFeedback(params) {
+		const schema = this._requireFeedbackPublicSchema();
+		const payer = params.payer;
+		if (params.score !== void 0 && (!Number.isFinite(params.score) || params.score < 0 || params.score > 100)) throw new Error(`Feedback score must be a finite number between 0 and 100, got: ${params.score}`);
+		const contentObj = {};
+		if (params.score !== void 0) contentObj.score = params.score;
+		if (params.tags?.length) contentObj.tags = params.tags;
+		if (params.endpoint) contentObj.endpoint = params.endpoint;
+		if (params.message) contentObj.m = params.message;
+		const content = Object.keys(contentObj).length > 0 ? new TextEncoder().encode(JSON.stringify(contentObj)) : new Uint8Array(0);
+		const contentType = content.length > 0 ? ContentType.JSON : ContentType.None;
+		const taskRef = params.taskRef ?? globalThis.crypto.getRandomValues(new Uint8Array(32));
+		const outcome = params.outcome ?? Outcome.Neutral;
+		const { messageBytes } = buildCounterpartyMessage({
+			schemaName: "FeedbackPublicV1",
+			data: serializeFeedback({
+				taskRef,
+				agentMint: params.agentMint,
+				counterparty: payer.address,
+				dataHash: zeroDataHash$1(),
+				outcome,
+				contentType,
+				content
+			})
+		});
+		const sig = await (0, __solana_kit.signBytes)(payer.keyPair.privateKey, messageBytes);
+		const result = await this.createFeedback({
+			payer,
+			sasSchema: schema,
+			taskRef,
+			agentMint: params.agentMint,
+			counterparty: payer.address,
+			dataHash: zeroDataHash$1(),
+			outcome,
+			contentType,
+			content,
+			agentSignature: {
+				pubkey: payer.address,
+				signature: new Uint8Array(sig)
+			},
+			counterpartyMessage: messageBytes,
+			lookupTableAddress: this._deployedConfig?.lookupTable
+		});
+		this._feedbackCache.invalidate();
+		return {
+			signature: result.signature,
+			attestationAddress: result.address
+		};
+	}
+	/**
+	* Prepare feedback for browser wallet signing.
+	*
+	* Returns SIWS message bytes that the counterparty must sign externally.
+	* Pass the result + signature to `submitPreparedFeedback()`.
+	*/
+	async prepareFeedback(params) {
+		const schema = this._requireFeedbackPublicSchema();
+		if (params.score !== void 0 && (!Number.isFinite(params.score) || params.score < 0 || params.score > 100)) throw new Error(`Feedback score must be a finite number between 0 and 100, got: ${params.score}`);
+		const contentObj = {};
+		if (params.score !== void 0) contentObj.score = params.score;
+		if (params.tags?.length) contentObj.tags = params.tags;
+		if (params.endpoint) contentObj.endpoint = params.endpoint;
+		if (params.message) contentObj.m = params.message;
+		const content = Object.keys(contentObj).length > 0 ? new TextEncoder().encode(JSON.stringify(contentObj)) : new Uint8Array(0);
+		const contentType = content.length > 0 ? ContentType.JSON : ContentType.None;
+		const taskRef = params.taskRef ?? globalThis.crypto.getRandomValues(new Uint8Array(32));
+		const outcome = params.outcome ?? Outcome.Neutral;
+		const { messageBytes } = buildCounterpartyMessage({
+			schemaName: "FeedbackPublicV1",
+			data: serializeFeedback({
+				taskRef,
+				agentMint: params.agentMint,
+				counterparty: params.counterparty,
+				dataHash: zeroDataHash$1(),
+				outcome,
+				contentType,
+				content
+			})
+		});
+		return {
+			messageBytes,
+			agentMint: params.agentMint,
+			counterparty: params.counterparty,
+			taskRef,
+			dataHash: zeroDataHash$1(),
+			outcome,
+			contentType,
+			content,
+			sasSchema: schema,
+			lookupTable: this._deployedConfig?.lookupTable,
+			meta: {
+				score: params.score,
+				tags: params.tags ? [...params.tags] : void 0,
+				message: params.message,
+				endpoint: params.endpoint
+			}
+		};
+	}
+	/**
+	* Submit prepared feedback with an externally-obtained wallet signature.
+	*
+	* The payer signs the transaction and pays gas. The counterparty's SIWS
+	* signature (from wallet) proves consent.
+	*/
+	async submitPreparedFeedback(params) {
+		const { payer, prepared, counterpartySignature } = params;
+		const result = await this.createFeedback({
+			payer,
+			sasSchema: prepared.sasSchema,
+			taskRef: prepared.taskRef,
+			agentMint: prepared.agentMint,
+			counterparty: prepared.counterparty,
+			dataHash: prepared.dataHash,
+			outcome: prepared.outcome,
+			contentType: prepared.contentType,
+			content: prepared.content,
+			agentSignature: {
+				pubkey: prepared.counterparty,
+				signature: new Uint8Array(counterpartySignature)
+			},
+			counterpartyMessage: prepared.messageBytes,
+			lookupTableAddress: prepared.lookupTable
+		});
+		this._feedbackCache.invalidate();
+		return {
+			signature: result.signature,
+			attestationAddress: result.address
+		};
+	}
+	/**
+	* Revoke (close) a feedback attestation by its compressed account address.
+	*
+	* The payer must be the counterparty who originally submitted the feedback.
+	* Closed attestations are permanently deleted.
+	*/
+	async revokeFeedback(params) {
+		const schema = this._deployedConfig?.schemas.feedbackPublic ?? this._deployedConfig?.schemas.feedback;
+		if (!schema) throw new Error(`No feedback schema deployed for network "${this.network}"`);
+		const result = await this.closeCompressedAttestation({
+			payer: params.payer,
+			counterparty: params.payer,
+			sasSchema: schema,
+			attestationAddress: params.attestationAddress,
+			lookupTableAddress: this._deployedConfig?.lookupTable
+		});
+		this._feedbackCache.invalidate();
+		return { signature: result.signature };
+	}
+	/**
+	* Search feedback attestations with client-side filtering.
+	*
+	* Note: `createdAt` timestamps are approximate - derived from Solana slot
+	* numbers using ~400ms/slot estimate.
+	*
+	* @example
+	* ```typescript
+	* const feedbacks = await sati.searchFeedback({
+	*   agentMint: address("Agent..."),
+	*   tags: ["quality"],
+	*   minScore: 70,
+	* });
+	* ```
+	*/
+	async searchFeedback(options) {
+		const schema = this._deployedConfig?.schemas.feedbackPublic ?? this._deployedConfig?.schemas.feedback;
+		if (!schema) throw new Error(`No feedback schema deployed for network "${this.network}"`);
+		const filter = { sasSchema: schema };
+		if (options?.agentMint) filter.agentMint = options.agentMint;
+		if (options?.counterparty) filter.counterparty = options.counterparty;
+		const cacheKey = FeedbackCache.cacheKey(schema, options?.agentMint);
+		const cached = this._feedbackCache.get(cacheKey);
+		const result = cached ?? await this.listFeedbacks(filter);
+		if (!cached) this._feedbackCache.set(cacheKey, result);
+		const currentSlot = await this.rpc.getSlot({ commitment: "confirmed" }).send();
+		const nowSec = Math.floor(Date.now() / 1e3);
+		const feedbacks = [];
+		for (const item of result.items) {
+			const rawContent = this._parseContentJson(item.data.content, item.data.contentType);
+			const score = rawContent?.score;
+			const tags = rawContent?.tags ?? [];
+			const message = rawContent?.m;
+			const endpoint = rawContent?.endpoint;
+			if (options?.tags?.length) {
+				if (!options.tags.every((t) => tags.includes(t))) continue;
+			}
+			if (options?.minScore !== void 0 && (score === void 0 || score < options.minScore)) continue;
+			if (options?.maxScore !== void 0 && (score === void 0 || score > options.maxScore)) continue;
+			const slotDiff = Number(BigInt(currentSlot) - item.raw.slotCreated);
+			const createdAt = nowSec - Math.floor(slotDiff * .4);
+			const [compressedAddress] = (0, __solana_kit.getAddressDecoder)().read(item.address, 0);
+			feedbacks.push({
+				compressedAddress,
+				agentMint: item.data.agentMint,
+				counterparty: item.data.counterparty,
+				outcome: item.data.outcome,
+				score,
+				tags,
+				message,
+				endpoint,
+				createdAt
+			});
+		}
+		if (options?.includeTxHash) {
+			const photon = this.getLightClient().getRpc();
+			await Promise.all(feedbacks.map(async (fb) => {
+				try {
+					fb.txSignature = (await photon.getCompressionSignaturesForAddress(fb.compressedAddress, { limit: 1 })).items[0]?.signature;
+				} catch (error) {
+					this._warn({
+						code: "SIGNATURE_LOOKUP_FAILED",
+						message: "Failed to fetch tx signature",
+						context: fb.compressedAddress,
+						cause: error
+					});
+				}
+			}));
+		}
+		return feedbacks;
+	}
+	/**
+	* Get reputation summary for an agent.
+	*
+	* Aggregates feedback scores, optionally filtered by tags.
+	*
+	* @example
+	* ```typescript
+	* const summary = await sati.getReputationSummary(address("Agent..."));
+	* console.log(`${summary.count} reviews, avg ${summary.averageScore}`);
+	* ```
+	*/
+	async getReputationSummary(agentMint, tags) {
+		const schema = this._deployedConfig?.schemas.feedbackPublic ?? this._deployedConfig?.schemas.feedback;
+		if (!schema) throw new Error(`No feedback schema deployed for network "${this.network}"`);
+		const cacheKey = FeedbackCache.cacheKey(schema, agentMint);
+		const cached = this._feedbackCache.get(cacheKey);
+		const result = cached ?? await this.listFeedbacks({
+			sasSchema: schema,
+			agentMint
+		});
+		if (!cached) this._feedbackCache.set(cacheKey, result);
+		if (result.items.length === 0) return {
+			count: 0,
+			averageScore: 0
+		};
+		let sum = 0;
+		let count = 0;
+		for (const item of result.items) {
+			const rawContent = this._parseContentJson(item.data.content, item.data.contentType);
+			const score = rawContent?.score;
+			const itemTags = rawContent?.tags ?? [];
+			if (tags?.length && !tags.every((t) => itemTags.includes(t))) continue;
+			if (score !== void 0) {
+				sum += score;
+				count++;
+			}
+		}
+		return {
+			count,
+			averageScore: count > 0 ? sum / count : 0
+		};
+	}
+	/**
+	* Search validation attestations for an agent.
+	*
+	* Note: `createdAt` timestamps are approximate.
+	*/
+	async searchValidations(agentMint) {
+		const validationSchema = this._deployedConfig?.schemas.validation;
+		if (!validationSchema) throw new Error(`No validation schema deployed for network "${this.network}"`);
+		const result = await this.listValidations({
+			sasSchema: validationSchema,
+			agentMint
+		});
+		const currentSlot = await this.rpc.getSlot({ commitment: "confirmed" }).send();
+		const nowSec = Math.floor(Date.now() / 1e3);
+		return result.items.map((item) => {
+			const slotDiff = Number(BigInt(currentSlot) - item.raw.slotCreated);
+			const createdAt = nowSec - Math.floor(slotDiff * .4);
+			const [compressedAddress] = (0, __solana_kit.getAddressDecoder)().read(item.address, 0);
+			return {
+				compressedAddress,
+				agentMint: item.data.agentMint,
+				counterparty: item.data.counterparty,
+				outcome: item.data.outcome,
+				createdAt
+			};
+		});
+	}
+	/**
+	* Search registered agents with filtering and optional feedback stats.
+	*
+	* @example
+	* ```typescript
+	* const agents = await sati.searchAgents({
+	*   endpointTypes: ["MCP"],
+	*   active: true,
+	*   includeFeedbackStats: true,
+	* });
+	* ```
+	*/
+	async searchAgents(options) {
+		const limit = options?.limit ?? 100;
+		const offset = options?.offset;
+		let agents;
+		if (options?.owner) agents = await this.listAgentsByOwner(options.owner);
+		else agents = await this.listAllAgents({
+			limit,
+			offset
+		});
+		if (options?.name) {
+			const lower = options.name.toLowerCase();
+			agents = agents.filter((a) => a.name.toLowerCase().includes(lower));
+		}
+		const regFiles = !!(options?.active !== void 0 || options?.endpointTypes?.length) || options?.includeFeedbackStats ? await Promise.all(agents.map(async (a) => {
+			try {
+				return await fetchRegistrationFile(a.uri);
+			} catch {
+				return null;
+			}
+		})) : agents.map(() => null);
+		const filtered = [];
+		for (let i = 0; i < agents.length; i++) {
+			const identity = agents[i];
+			const regFile = regFiles[i];
+			const endpoints = regFile?.endpoints ?? [];
+			if (options?.active !== void 0 && (regFile?.active ?? true) !== options.active) continue;
+			if (options?.endpointTypes?.length) {
+				if (!options.endpointTypes.every((type) => endpoints.some((e) => e.name.toUpperCase() === type.toUpperCase()))) continue;
+			}
+			filtered.push({
+				identity,
+				regFile
+			});
+		}
+		let statsMap = null;
+		if (options?.includeFeedbackStats && this._deployedConfig && filtered.length > 0) {
+			statsMap = /* @__PURE__ */ new Map();
+			await Promise.all(filtered.map(async ({ identity }) => {
+				try {
+					const summary = await this.getReputationSummary(identity.mint);
+					statsMap?.set(identity.mint, summary);
+				} catch (error) {
+					this._warn({
+						code: "RPC_ERROR",
+						message: "Failed to fetch feedback stats",
+						context: identity.mint,
+						cause: error
+					});
+				}
+			}));
+		}
+		return filtered.map(({ identity, regFile }) => ({
+			identity,
+			registrationFile: regFile,
+			...statsMap && { feedbackStats: statsMap.get(identity.mint) }
+		}));
+	}
+	/**
+	* Create a fluent builder for agent registration.
+	*
+	* @example
+	* ```typescript
+	* const builder = sati.createAgentBuilder("MyAgent", "AI assistant", "https://example.com/avatar.png");
+	* builder.setMCP("https://mcp.example.com").setActive(true);
+	* const result = await builder.register({ payer, uploader: createSatiUploader() });
+	* ```
+	*/
+	createAgentBuilder(name, description, image) {
+		return new SatiAgentBuilder(this, name, description, image);
+	}
+	/** Safely parse JSON content from an attestation. */
+	_parseContentJson(content, contentType) {
+		if (contentType !== ContentType.JSON || content.length === 0) return null;
+		try {
+			return JSON.parse(new TextDecoder().decode(content));
+		} catch {
+			return null;
+		}
+	}
+	/** Fire a non-fatal warning. */
+	_warn(warning) {
+		this._onWarning?.(warning);
+	}
+	/** Get the FeedbackPublic schema address or throw. */
+	_requireFeedbackPublicSchema() {
+		const schema = this._deployedConfig?.schemas.feedbackPublic;
+		if (!schema) throw new Error(`No FeedbackPublic schema deployed for network "${this.network}". Pass sasSchema explicitly via the low-level createFeedback() method.`);
+		return schema;
+	}
 };
 
 //#endregion
@@ -6363,6 +7026,7 @@ exports.DuplicateAttestationError = DuplicateAttestationError;
 exports.ED25519_PROGRAM_ADDRESS = ED25519_PROGRAM_ADDRESS;
 exports.ENCRYPTION_VERSION = ENCRYPTION_VERSION;
 exports.FEEDBACK_OFFSETS = FEEDBACK_OFFSETS;
+exports.FeedbackCache = FeedbackCache;
 exports.INITIALIZE_DISCRIMINATOR = INITIALIZE_DISCRIMINATOR;
 exports.LIGHT_ERROR_CODES = LIGHT_ERROR_CODES;
 exports.LINK_EVM_ADDRESS_DISCRIMINATOR = LINK_EVM_ADDRESS_DISCRIMINATOR;
@@ -6446,6 +7110,7 @@ exports.SCHEMA_SEED = SCHEMA_SEED;
 exports.SOLANA_CHAIN_REFS = SOLANA_CHAIN_REFS;
 exports.Sati = Sati;
 exports.SatiAccount = SatiAccount;
+exports.SatiAgentBuilder = SatiAgentBuilder;
 exports.SatiError = SatiError;
 exports.SatiInstruction = SatiInstruction;
 exports.SchemaNotFoundError = SchemaNotFoundError;
@@ -6480,6 +7145,7 @@ exports.createEd25519Instruction = createEd25519Instruction;
 exports.createJsonContent = createJsonContent;
 exports.createPinataUploader = createPinataUploader;
 exports.createSATILightClient = createSATILightClient;
+exports.createSatiUploader = createSatiUploader;
 exports.decodeAgentIndex = decodeAgentIndex;
 exports.decodeRegistryConfig = decodeRegistryConfig;
 exports.decodeSchemaConfig = decodeSchemaConfig;