uvd-x402-sdk 2.19.0 → 2.20.0

package/dist/backend/index.d.mts

@@ -1226,6 +1226,73 @@ interface ReputationResponse {
     feedback?: FeedbackEntry[];
     network: Erc8004Network;
 }
+/**
+ * Key-value metadata entry for agent registration
+ */
+interface MetadataEntryParam {
+    /** Metadata key */
+    key: string;
+    /** Metadata value (hex-encoded bytes or UTF-8 string) */
+    value: string;
+}
+/**
+ * Request body for POST /register
+ */
+interface RegisterAgentRequest {
+    /** x402 protocol version */
+    x402Version: 1 | 2;
+    /** Network where agent will be registered */
+    network: Erc8004Network;
+    /** URI pointing to agent registration file (IPFS, HTTPS) */
+    agentUri: string;
+    /** Optional metadata key-value pairs */
+    metadata?: MetadataEntryParam[];
+    /** Optional recipient address - NFT is transferred to this address after minting */
+    recipient?: string;
+}
+/**
+ * Response from POST /register
+ */
+interface RegisterAgentResponse {
+    /** Whether registration succeeded */
+    success: boolean;
+    /** The newly assigned agent ID (ERC-721 tokenId) */
+    agentId?: number;
+    /** Registration transaction hash */
+    transaction?: string;
+    /** Transfer transaction hash (if recipient was specified) */
+    transferTransaction?: string;
+    /** Owner address of the agent NFT */
+    owner?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Network where agent was registered */
+    network: string;
+}
+/**
+ * Response from GET /identity/{network}/{agent_id}/metadata/{key}
+ */
+interface IdentityMetadataResponse {
+    /** Agent ID */
+    agentId: number;
+    /** Metadata key */
+    key: string;
+    /** Raw hex-encoded value */
+    valueHex: string;
+    /** UTF-8 decoded value (if decodable) */
+    valueUtf8?: string;
+    /** Network */
+    network: string;
+}
+/**
+ * Response from GET /identity/{network}/total-supply
+ */
+interface IdentityTotalSupplyResponse {
+    /** Total number of registered agents */
+    totalSupply: number;
+    /** Network */
+    network: string;
+}
 /**
  * Options for the ERC8004Client
  */
@@ -1239,7 +1306,9 @@ interface Erc8004ClientOptions {
  * Client for ERC-8004 Trustless Agents API
  *
  * Provides methods for:
- * - Querying agent identity
+ * - Registering new agents (gasless, facilitator pays gas)
+ * - Registering agents on behalf of users (gasless delegation)
+ * - Querying agent identity, metadata, and total supply
  * - Querying agent reputation
  * - Submitting reputation feedback
  * - Revoking feedback
@@ -1394,6 +1463,58 @@ declare class Erc8004Client {
      * ```
      */
     appendResponse(network: Erc8004Network, agentId: number, feedbackIndex: number, response: string, responseUri?: string): Promise<FeedbackResponse>;
+    /**
+     * Register a new agent on the Identity Registry
+     *
+     * The facilitator pays gas fees. Optionally transfer the NFT to a
+     * recipient address (gasless delegation).
+     *
+     * @param request - Registration request
+     * @returns Registration response with agent ID and transaction hash
+     *
+     * @example
+     * ```ts
+     * // Register agent owned by facilitator
+     * const result = await client.registerAgent({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   agentUri: 'ipfs://QmYourAgentFile',
+     * });
+     * console.log(`Agent #${result.agentId} registered`);
+     *
+     * // Register agent and transfer to user
+     * const result = await client.registerAgent({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   agentUri: 'ipfs://QmYourAgentFile',
+     *   recipient: '0xUserAddress...',
+     * });
+     * console.log(`Agent #${result.agentId} transferred to user`);
+     * ```
+     */
+    registerAgent(request: RegisterAgentRequest): Promise<RegisterAgentResponse>;
+    /**
+     * Get registration endpoint metadata
+     *
+     * @returns Endpoint information for POST /register
+     */
+    getRegisterInfo(): Promise<Record<string, unknown>>;
+    /**
+     * Get a specific metadata entry for an agent
+     *
+     * @param network - Network where agent is registered
+     * @param agentId - Agent's tokenId
+     * @param key - Metadata key to retrieve
+     * @returns Metadata value (hex-encoded and UTF-8 decoded if possible)
+     */
+    getIdentityMetadata(network: Erc8004Network, agentId: number, key: string): Promise<IdentityMetadataResponse>;
+    /**
+     * Get total number of registered agents on a network
+     *
+     * @param network - Network to query
+     * @returns Total supply count
+     */
+    getIdentityTotalSupply(network: Erc8004Network): Promise<IdentityTotalSupplyResponse>;
 }
 /**
  * Build payment requirements with ERC-8004 extension
@@ -1639,4 +1760,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, isEscrowExpired, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, isEscrowExpired, parsePaymentHeader };

package/dist/backend/index.d.ts

@@ -1226,6 +1226,73 @@ interface ReputationResponse {
     feedback?: FeedbackEntry[];
     network: Erc8004Network;
 }
+/**
+ * Key-value metadata entry for agent registration
+ */
+interface MetadataEntryParam {
+    /** Metadata key */
+    key: string;
+    /** Metadata value (hex-encoded bytes or UTF-8 string) */
+    value: string;
+}
+/**
+ * Request body for POST /register
+ */
+interface RegisterAgentRequest {
+    /** x402 protocol version */
+    x402Version: 1 | 2;
+    /** Network where agent will be registered */
+    network: Erc8004Network;
+    /** URI pointing to agent registration file (IPFS, HTTPS) */
+    agentUri: string;
+    /** Optional metadata key-value pairs */
+    metadata?: MetadataEntryParam[];
+    /** Optional recipient address - NFT is transferred to this address after minting */
+    recipient?: string;
+}
+/**
+ * Response from POST /register
+ */
+interface RegisterAgentResponse {
+    /** Whether registration succeeded */
+    success: boolean;
+    /** The newly assigned agent ID (ERC-721 tokenId) */
+    agentId?: number;
+    /** Registration transaction hash */
+    transaction?: string;
+    /** Transfer transaction hash (if recipient was specified) */
+    transferTransaction?: string;
+    /** Owner address of the agent NFT */
+    owner?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Network where agent was registered */
+    network: string;
+}
+/**
+ * Response from GET /identity/{network}/{agent_id}/metadata/{key}
+ */
+interface IdentityMetadataResponse {
+    /** Agent ID */
+    agentId: number;
+    /** Metadata key */
+    key: string;
+    /** Raw hex-encoded value */
+    valueHex: string;
+    /** UTF-8 decoded value (if decodable) */
+    valueUtf8?: string;
+    /** Network */
+    network: string;
+}
+/**
+ * Response from GET /identity/{network}/total-supply
+ */
+interface IdentityTotalSupplyResponse {
+    /** Total number of registered agents */
+    totalSupply: number;
+    /** Network */
+    network: string;
+}
 /**
  * Options for the ERC8004Client
  */
@@ -1239,7 +1306,9 @@ interface Erc8004ClientOptions {
  * Client for ERC-8004 Trustless Agents API
  *
  * Provides methods for:
- * - Querying agent identity
+ * - Registering new agents (gasless, facilitator pays gas)
+ * - Registering agents on behalf of users (gasless delegation)
+ * - Querying agent identity, metadata, and total supply
  * - Querying agent reputation
  * - Submitting reputation feedback
  * - Revoking feedback
@@ -1394,6 +1463,58 @@ declare class Erc8004Client {
      * ```
      */
     appendResponse(network: Erc8004Network, agentId: number, feedbackIndex: number, response: string, responseUri?: string): Promise<FeedbackResponse>;
+    /**
+     * Register a new agent on the Identity Registry
+     *
+     * The facilitator pays gas fees. Optionally transfer the NFT to a
+     * recipient address (gasless delegation).
+     *
+     * @param request - Registration request
+     * @returns Registration response with agent ID and transaction hash
+     *
+     * @example
+     * ```ts
+     * // Register agent owned by facilitator
+     * const result = await client.registerAgent({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   agentUri: 'ipfs://QmYourAgentFile',
+     * });
+     * console.log(`Agent #${result.agentId} registered`);
+     *
+     * // Register agent and transfer to user
+     * const result = await client.registerAgent({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   agentUri: 'ipfs://QmYourAgentFile',
+     *   recipient: '0xUserAddress...',
+     * });
+     * console.log(`Agent #${result.agentId} transferred to user`);
+     * ```
+     */
+    registerAgent(request: RegisterAgentRequest): Promise<RegisterAgentResponse>;
+    /**
+     * Get registration endpoint metadata
+     *
+     * @returns Endpoint information for POST /register
+     */
+    getRegisterInfo(): Promise<Record<string, unknown>>;
+    /**
+     * Get a specific metadata entry for an agent
+     *
+     * @param network - Network where agent is registered
+     * @param agentId - Agent's tokenId
+     * @param key - Metadata key to retrieve
+     * @returns Metadata value (hex-encoded and UTF-8 decoded if possible)
+     */
+    getIdentityMetadata(network: Erc8004Network, agentId: number, key: string): Promise<IdentityMetadataResponse>;
+    /**
+     * Get total number of registered agents on a network
+     *
+     * @param network - Network to query
+     * @returns Total supply count
+     */
+    getIdentityTotalSupply(network: Erc8004Network): Promise<IdentityTotalSupplyResponse>;
 }
 /**
  * Build payment requirements with ERC-8004 extension
@@ -1639,4 +1760,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, isEscrowExpired, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, isEscrowExpired, parsePaymentHeader };

package/dist/backend/index.js

@@ -2287,6 +2287,150 @@ var Erc8004Client = class {
       };
     }
   }
+  /**
+   * Register a new agent on the Identity Registry
+   *
+   * The facilitator pays gas fees. Optionally transfer the NFT to a
+   * recipient address (gasless delegation).
+   *
+   * @param request - Registration request
+   * @returns Registration response with agent ID and transaction hash
+   *
+   * @example
+   * ```ts
+   * // Register agent owned by facilitator
+   * const result = await client.registerAgent({
+   *   x402Version: 1,
+   *   network: 'ethereum',
+   *   agentUri: 'ipfs://QmYourAgentFile',
+   * });
+   * console.log(`Agent #${result.agentId} registered`);
+   *
+   * // Register agent and transfer to user
+   * const result = await client.registerAgent({
+   *   x402Version: 1,
+   *   network: 'ethereum',
+   *   agentUri: 'ipfs://QmYourAgentFile',
+   *   recipient: '0xUserAddress...',
+   * });
+   * console.log(`Agent #${result.agentId} transferred to user`);
+   * ```
+   */
+  async registerAgent(request) {
+    const url = `${this.baseUrl}/register`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Accept": "application/json"
+        },
+        body: JSON.stringify(request),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        return {
+          success: false,
+          error: `Facilitator error: ${response.status} - ${errorText}`,
+          network: request.network
+        };
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+        network: request.network
+      };
+    }
+  }
+  /**
+   * Get registration endpoint metadata
+   *
+   * @returns Endpoint information for POST /register
+   */
+  async getRegisterInfo() {
+    const url = `${this.baseUrl}/register`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { "Accept": "application/json" },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`ERC-8004 API error: ${response.status} - ${errorText}`);
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+  /**
+   * Get a specific metadata entry for an agent
+   *
+   * @param network - Network where agent is registered
+   * @param agentId - Agent's tokenId
+   * @param key - Metadata key to retrieve
+   * @returns Metadata value (hex-encoded and UTF-8 decoded if possible)
+   */
+  async getIdentityMetadata(network, agentId, key) {
+    const url = `${this.baseUrl}/identity/${network}/${agentId}/metadata/${encodeURIComponent(key)}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { "Accept": "application/json" },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`ERC-8004 API error: ${response.status} - ${errorText}`);
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+  /**
+   * Get total number of registered agents on a network
+   *
+   * @param network - Network to query
+   * @returns Total supply count
+   */
+  async getIdentityTotalSupply(network) {
+    const url = `${this.baseUrl}/identity/${network}/total-supply`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { "Accept": "application/json" },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`ERC-8004 API error: ${response.status} - ${errorText}`);
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
 };
 function buildErc8004PaymentRequirements(options) {
   const base = buildPaymentRequirements(options);