uvd-x402-sdk 2.48.0 → 2.51.0

package/dist/backend/index.d.mts

@@ -1490,6 +1490,16 @@ interface FeedbackParams {
     feedbackUri?: string;
     /** Keccak256 hash of feedback content (for integrity) */
     feedbackHash?: string;
+    /**
+     * Quality score 0-100.
+     *
+     * Solana only, and effectively required there: the ATOM Engine ignores an
+     * unscored feedback. It is written to the agent but contributes nothing to
+     * reputation, and the program reports `had_impact=false`. This is not
+     * retroactive — reputation stays at zero however much unscored feedback
+     * accumulates.
+     */
+    score?: number;
     /** Proof of payment (required for authorized feedback) */
     proof?: ProofOfPayment;
 }
@@ -1522,10 +1532,69 @@ interface FeedbackResponse {
 /**
  * Reputation query response
  */
+/**
+ * Error from an ERC-8004 lookup, carrying the HTTP status as a field.
+ *
+ * `notFound` and `retryable` are mutually exclusive and must stay that way in
+ * calling code: the facilitator answers 404 for "this address owns no agent"
+ * and 503 for "I could not find out", usually an RPC failure behind it.
+ * Treating a 503 as absence is how a transient failure becomes a permanent
+ * wrong answer — on a registration path it mints a second agent for an owner
+ * who already has one, burning gas and leaving an orphan.
+ */
+declare class Erc8004LookupError extends Error {
+    /** HTTP status returned by the facilitator */
+    readonly status: number;
+    /** Raw response body, for debugging */
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+    /** The address genuinely owns no agent on this network. */
+    get notFound(): boolean;
+    /** The lookup reached no verdict. Retry; never read as "owns nothing". */
+    get retryable(): boolean;
+}
+/**
+ * ATOM Engine reputation analytics (Solana only).
+ *
+ * Present only when the agent's `atom_stats` account has been initialized. The
+ * facilitator does that during `registerAgent`; agents registered elsewhere may
+ * never have it, in which case their feedback is never scored.
+ *
+ * The engine measures quality through EMA scores, so there are no
+ * positive/negative tallies.
+ */
+interface AtomStats {
+    /** Trust tier 0-4 */
+    trustTier: number;
+    /** Human-readable trust tier */
+    trustTierName: string;
+    /** Cached quality score */
+    qualityScore: number;
+    /** Cached loyalty score */
+    loyaltyScore: number;
+    /** Statistical confidence */
+    confidence: number;
+    /** Risk assessment (lower is better) */
+    riskScore: number;
+    /** Client diversity from HyperLogLog */
+    diversityRatio: number;
+    /** Lowest score ever recorded */
+    minScore: number;
+    /** Highest score ever recorded */
+    maxScore: number;
+    /** Most recent score recorded */
+    lastScore: number;
+    /** Total feedback counted by the engine */
+    feedbackCount: number;
+    /** Slot of the most recent feedback */
+    lastFeedbackSlot: number;
+}
 interface ReputationResponse {
     agentId: AgentId;
     summary: ReputationSummary;
     feedback?: FeedbackEntry[];
+    /** ATOM Engine analytics; absent when the agent has no initialized stats */
+    atomStats?: AtomStats | null;
     network: Erc8004Network;
 }
 /**
@@ -1594,19 +1663,32 @@ interface IdentityMetadataResponse {
     agentId: AgentId;
     /** Metadata key */
     key: string;
-    /** Raw hex-encoded value */
-    valueHex: string;
+    /**
+     * Raw hex-encoded value. The facilitator sends this as `value`; this field
+     * used to be declared as `valueHex`, which no response ever carried, so it
+     * was always undefined at runtime.
+     */
+    value: string;
     /** UTF-8 decoded value (if decodable) */
     valueUtf8?: string;
+    /** Whether the entry can still be changed */
+    immutable?: boolean;
     /** Network */
     network: string;
 }
 /**
  * Response from GET /identity/{network}/total-supply
+ *
+ * On Solana the counts come from the Metaplex Core collection, not the registry,
+ * which keeps no counter of its own.
  */
 interface IdentityTotalSupplyResponse {
-    /** Total number of registered agents */
+    /** Registered agents, net of burns */
     totalSupply: number;
+    /** All-time mint count (Solana) */
+    numMinted?: number;
+    /** Metaplex Core collection backing the count (Solana) */
+    collection?: string;
     /** Network */
     network: string;
 }
@@ -1751,6 +1833,7 @@ declare class Erc8004Client {
      */
     revokeFeedback(network: Erc8004Network, agentId: AgentId, feedbackIndex: number, options?: {
         sealHash?: string;
+        originalFeedback?: Omit<FeedbackParams, 'agentId' | 'proof'>;
     }): Promise<FeedbackResponse>;
     /**
      * Get ERC-8004 contract addresses for a network
@@ -2328,4 +2411,4 @@ declare class AdvancedEscrowClient {
     private sendViaAdapter;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };

package/dist/backend/index.d.ts

@@ -1490,6 +1490,16 @@ interface FeedbackParams {
     feedbackUri?: string;
     /** Keccak256 hash of feedback content (for integrity) */
     feedbackHash?: string;
+    /**
+     * Quality score 0-100.
+     *
+     * Solana only, and effectively required there: the ATOM Engine ignores an
+     * unscored feedback. It is written to the agent but contributes nothing to
+     * reputation, and the program reports `had_impact=false`. This is not
+     * retroactive — reputation stays at zero however much unscored feedback
+     * accumulates.
+     */
+    score?: number;
     /** Proof of payment (required for authorized feedback) */
     proof?: ProofOfPayment;
 }
@@ -1522,10 +1532,69 @@ interface FeedbackResponse {
 /**
  * Reputation query response
  */
+/**
+ * Error from an ERC-8004 lookup, carrying the HTTP status as a field.
+ *
+ * `notFound` and `retryable` are mutually exclusive and must stay that way in
+ * calling code: the facilitator answers 404 for "this address owns no agent"
+ * and 503 for "I could not find out", usually an RPC failure behind it.
+ * Treating a 503 as absence is how a transient failure becomes a permanent
+ * wrong answer — on a registration path it mints a second agent for an owner
+ * who already has one, burning gas and leaving an orphan.
+ */
+declare class Erc8004LookupError extends Error {
+    /** HTTP status returned by the facilitator */
+    readonly status: number;
+    /** Raw response body, for debugging */
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+    /** The address genuinely owns no agent on this network. */
+    get notFound(): boolean;
+    /** The lookup reached no verdict. Retry; never read as "owns nothing". */
+    get retryable(): boolean;
+}
+/**
+ * ATOM Engine reputation analytics (Solana only).
+ *
+ * Present only when the agent's `atom_stats` account has been initialized. The
+ * facilitator does that during `registerAgent`; agents registered elsewhere may
+ * never have it, in which case their feedback is never scored.
+ *
+ * The engine measures quality through EMA scores, so there are no
+ * positive/negative tallies.
+ */
+interface AtomStats {
+    /** Trust tier 0-4 */
+    trustTier: number;
+    /** Human-readable trust tier */
+    trustTierName: string;
+    /** Cached quality score */
+    qualityScore: number;
+    /** Cached loyalty score */
+    loyaltyScore: number;
+    /** Statistical confidence */
+    confidence: number;
+    /** Risk assessment (lower is better) */
+    riskScore: number;
+    /** Client diversity from HyperLogLog */
+    diversityRatio: number;
+    /** Lowest score ever recorded */
+    minScore: number;
+    /** Highest score ever recorded */
+    maxScore: number;
+    /** Most recent score recorded */
+    lastScore: number;
+    /** Total feedback counted by the engine */
+    feedbackCount: number;
+    /** Slot of the most recent feedback */
+    lastFeedbackSlot: number;
+}
 interface ReputationResponse {
     agentId: AgentId;
     summary: ReputationSummary;
     feedback?: FeedbackEntry[];
+    /** ATOM Engine analytics; absent when the agent has no initialized stats */
+    atomStats?: AtomStats | null;
     network: Erc8004Network;
 }
 /**
@@ -1594,19 +1663,32 @@ interface IdentityMetadataResponse {
     agentId: AgentId;
     /** Metadata key */
     key: string;
-    /** Raw hex-encoded value */
-    valueHex: string;
+    /**
+     * Raw hex-encoded value. The facilitator sends this as `value`; this field
+     * used to be declared as `valueHex`, which no response ever carried, so it
+     * was always undefined at runtime.
+     */
+    value: string;
     /** UTF-8 decoded value (if decodable) */
     valueUtf8?: string;
+    /** Whether the entry can still be changed */
+    immutable?: boolean;
     /** Network */
     network: string;
 }
 /**
  * Response from GET /identity/{network}/total-supply
+ *
+ * On Solana the counts come from the Metaplex Core collection, not the registry,
+ * which keeps no counter of its own.
  */
 interface IdentityTotalSupplyResponse {
-    /** Total number of registered agents */
+    /** Registered agents, net of burns */
     totalSupply: number;
+    /** All-time mint count (Solana) */
+    numMinted?: number;
+    /** Metaplex Core collection backing the count (Solana) */
+    collection?: string;
     /** Network */
     network: string;
 }
@@ -1751,6 +1833,7 @@ declare class Erc8004Client {
      */
     revokeFeedback(network: Erc8004Network, agentId: AgentId, feedbackIndex: number, options?: {
         sealHash?: string;
+        originalFeedback?: Omit<FeedbackParams, 'agentId' | 'proof'>;
     }): Promise<FeedbackResponse>;
     /**
      * Get ERC-8004 contract addresses for a network
@@ -2328,4 +2411,4 @@ declare class AdvancedEscrowClient {
     private sendViaAdapter;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };

package/dist/backend/index.js

@@ -2553,6 +2553,26 @@ var ERC8004_CONTRACTS = {
     atomEngineProgram: SOLANA_ATOM_ENGINE
   }
 };
+var Erc8004LookupError = class extends Error {
+  /** HTTP status returned by the facilitator */
+  status;
+  /** Raw response body, for debugging */
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "Erc8004LookupError";
+    this.status = status;
+    this.body = body;
+  }
+  /** The address genuinely owns no agent on this network. */
+  get notFound() {
+    return this.status === 404;
+  }
+  /** The lookup reached no verdict. Retry; never read as "owns nothing". */
+  get retryable() {
+    return this.status === 503;
+  }
+};
 var Erc8004Client = class {
   baseUrl;
   timeout;
@@ -2616,7 +2636,11 @@ var Erc8004Client = class {
       clearTimeout(timeoutId);
       if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`ERC-8004 API error: ${response.status} - ${errorText}`);
+        throw new Erc8004LookupError(
+          `ERC-8004 API error: ${response.status} - ${errorText}`,
+          response.status,
+          errorText
+        );
       }
       return await response.json();
     } catch (error) {
@@ -2776,6 +2800,8 @@ var Erc8004Client = class {
     };
     if (options?.sealHash) {
       payload.sealHash = options.sealHash;
+    } else if (options?.originalFeedback) {
+      payload.originalFeedback = options.originalFeedback;
     }
     try {
       const response = await fetch(url, {
@@ -4005,6 +4031,7 @@ exports.ERC8004_EXTENSION_ID = ERC8004_EXTENSION_ID;
 exports.ESCROW_CONTRACTS = ESCROW_CONTRACTS;
 exports.ESCROW_TIMEOUT_MS = ESCROW_TIMEOUT_MS;
 exports.Erc8004Client = Erc8004Client;
+exports.Erc8004LookupError = Erc8004LookupError;
 exports.EscrowClient = EscrowClient;
 exports.FacilitatorClient = FacilitatorClient;
 exports.HEALTH_FILTERS = HEALTH_FILTERS;