uvd-x402-sdk 2.51.0 → 2.52.1

package/dist/backend/index.d.mts

@@ -1658,6 +1658,33 @@ interface IdentityByOwnerResponse {
 /**
  * Response from GET /identity/{network}/{agent_id}/metadata/{key}
  */
+/**
+ * Lifecycle of an async registration. `mint_confirmed` and `done` carry an
+ * `agentId`; `failed` carries an `error`.
+ */
+type RegisterJobStatus = 'pending' | 'mint_confirmed' | 'done' | 'failed';
+/**
+ * Status of an asynchronous registration.
+ *
+ * Returned by `POST /register` with `Prefer: respond-async` (HTTP 202) and by
+ * `GET /register/status/{jobId}`.
+ *
+ * Terminal jobs are retained for one hour and then age out, after which the
+ * status endpoint 404s. Read the agent id before then, or it is only
+ * recoverable from the chain.
+ */
+interface RegisterJobResponse {
+    jobId: string;
+    status: RegisterJobStatus;
+    network?: string;
+    agentId?: AgentId;
+    transaction?: string;
+    transferTransaction?: string;
+    owner?: string;
+    error?: string;
+}
+/** Whether polling can stop: the job either finished or failed. */
+declare function isRegisterJobTerminal(job: RegisterJobResponse): boolean;
 interface IdentityMetadataResponse {
     /** Agent ID (EVM: number, Solana: string) */
     agentId: AgentId;
@@ -1918,6 +1945,39 @@ declare class Erc8004Client {
      * ```
      */
     registerAgent(request: RegisterAgentRequest): Promise<RegisterAgentResponse>;
+    /**
+     * Start a registration without waiting for the chain to confirm it.
+     *
+     * Registration waits on a mint receipt, which on a congested chain outlives
+     * client and proxy timeouts. A timed-out synchronous call is genuinely
+     * ambiguous — the mint may well have landed — and retrying it is how five
+     * duplicate agents once got minted. This returns immediately with a job id
+     * instead; poll {@link getRegisterStatus} or use {@link waitForRegistration}.
+     *
+     * On Solana, `recipient` is a base58 address: the facilitator mints,
+     * initializes the ATOM stats and transfers, paying every fee.
+     */
+    registerAgentAsync(request: RegisterAgentRequest): Promise<RegisterJobResponse>;
+    /**
+     * Read the current state of an asynchronous registration.
+     *
+     * Throws {@link Erc8004LookupError} with `notFound` when the job is unknown or
+     * has aged out — terminal jobs are kept for one hour.
+     */
+    getRegisterStatus(jobId: string): Promise<RegisterJobResponse>;
+    /**
+     * Poll an asynchronous registration until it finishes.
+     *
+     * Rejects on timeout rather than resolving with the last non-terminal status,
+     * so "still pending" is never mistaken for "did not happen": the mint may
+     * still land afterwards, and treating a timeout as failure is what leads to
+     * registering the same agent twice. Keep the job id and poll again rather
+     * than re-registering.
+     */
+    waitForRegistration(jobId: string, options?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<RegisterJobResponse>;
     /**
      * Get registration endpoint metadata
      *
@@ -2411,4 +2471,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, 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 };
+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 RegisterJobResponse, type RegisterJobStatus, 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, isRegisterJobTerminal, parsePaymentHeader };

package/dist/backend/index.d.ts

@@ -1658,6 +1658,33 @@ interface IdentityByOwnerResponse {
 /**
  * Response from GET /identity/{network}/{agent_id}/metadata/{key}
  */
+/**
+ * Lifecycle of an async registration. `mint_confirmed` and `done` carry an
+ * `agentId`; `failed` carries an `error`.
+ */
+type RegisterJobStatus = 'pending' | 'mint_confirmed' | 'done' | 'failed';
+/**
+ * Status of an asynchronous registration.
+ *
+ * Returned by `POST /register` with `Prefer: respond-async` (HTTP 202) and by
+ * `GET /register/status/{jobId}`.
+ *
+ * Terminal jobs are retained for one hour and then age out, after which the
+ * status endpoint 404s. Read the agent id before then, or it is only
+ * recoverable from the chain.
+ */
+interface RegisterJobResponse {
+    jobId: string;
+    status: RegisterJobStatus;
+    network?: string;
+    agentId?: AgentId;
+    transaction?: string;
+    transferTransaction?: string;
+    owner?: string;
+    error?: string;
+}
+/** Whether polling can stop: the job either finished or failed. */
+declare function isRegisterJobTerminal(job: RegisterJobResponse): boolean;
 interface IdentityMetadataResponse {
     /** Agent ID (EVM: number, Solana: string) */
     agentId: AgentId;
@@ -1918,6 +1945,39 @@ declare class Erc8004Client {
      * ```
      */
     registerAgent(request: RegisterAgentRequest): Promise<RegisterAgentResponse>;
+    /**
+     * Start a registration without waiting for the chain to confirm it.
+     *
+     * Registration waits on a mint receipt, which on a congested chain outlives
+     * client and proxy timeouts. A timed-out synchronous call is genuinely
+     * ambiguous — the mint may well have landed — and retrying it is how five
+     * duplicate agents once got minted. This returns immediately with a job id
+     * instead; poll {@link getRegisterStatus} or use {@link waitForRegistration}.
+     *
+     * On Solana, `recipient` is a base58 address: the facilitator mints,
+     * initializes the ATOM stats and transfers, paying every fee.
+     */
+    registerAgentAsync(request: RegisterAgentRequest): Promise<RegisterJobResponse>;
+    /**
+     * Read the current state of an asynchronous registration.
+     *
+     * Throws {@link Erc8004LookupError} with `notFound` when the job is unknown or
+     * has aged out — terminal jobs are kept for one hour.
+     */
+    getRegisterStatus(jobId: string): Promise<RegisterJobResponse>;
+    /**
+     * Poll an asynchronous registration until it finishes.
+     *
+     * Rejects on timeout rather than resolving with the last non-terminal status,
+     * so "still pending" is never mistaken for "did not happen": the mint may
+     * still land afterwards, and treating a timeout as failure is what leads to
+     * registering the same agent twice. Keep the job id and poll again rather
+     * than re-registering.
+     */
+    waitForRegistration(jobId: string, options?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<RegisterJobResponse>;
     /**
      * Get registration endpoint metadata
      *
@@ -2411,4 +2471,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, 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 };
+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 RegisterJobResponse, type RegisterJobStatus, 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, isRegisterJobTerminal, parsePaymentHeader };

package/dist/backend/index.js

@@ -2573,6 +2573,9 @@ var Erc8004LookupError = class extends Error {
     return this.status === 503;
   }
 };
+function isRegisterJobTerminal(job) {
+  return job.status === "done" || job.status === "failed";
+}
 var Erc8004Client = class {
   baseUrl;
   timeout;
@@ -2992,6 +2995,19 @@ var Erc8004Client = class {
       clearTimeout(timeoutId);
       if (!response.ok) {
         const errorText = await response.text();
+        try {
+          const parsed = JSON.parse(errorText);
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return {
+              ...parsed,
+              // Never let a 4xx body claim success, whatever it says.
+              success: false,
+              error: parsed.error ?? `Facilitator error: ${response.status}`,
+              network: parsed.network ?? request.network
+            };
+          }
+        } catch {
+        }
         return {
           success: false,
           error: `Facilitator error: ${response.status} - ${errorText}`,
@@ -3008,6 +3024,107 @@ var Erc8004Client = class {
       };
     }
   }
+  /**
+   * Start a registration without waiting for the chain to confirm it.
+   *
+   * Registration waits on a mint receipt, which on a congested chain outlives
+   * client and proxy timeouts. A timed-out synchronous call is genuinely
+   * ambiguous — the mint may well have landed — and retrying it is how five
+   * duplicate agents once got minted. This returns immediately with a job id
+   * instead; poll {@link getRegisterStatus} or use {@link waitForRegistration}.
+   *
+   * On Solana, `recipient` is a base58 address: the facilitator mints,
+   * initializes the ATOM stats and transfers, paying every fee.
+   */
+  async registerAgentAsync(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",
+          "Prefer": "respond-async"
+        },
+        body: JSON.stringify(request),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Erc8004LookupError(
+          `ERC-8004 API error: ${response.status} - ${errorText}`,
+          response.status,
+          errorText
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+  /**
+   * Read the current state of an asynchronous registration.
+   *
+   * Throws {@link Erc8004LookupError} with `notFound` when the job is unknown or
+   * has aged out — terminal jobs are kept for one hour.
+   */
+  async getRegisterStatus(jobId) {
+    const url = `${this.baseUrl}/register/status/${encodeURIComponent(jobId)}`;
+    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 Erc8004LookupError(
+          `ERC-8004 API error: ${response.status} - ${errorText}`,
+          response.status,
+          errorText
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+  /**
+   * Poll an asynchronous registration until it finishes.
+   *
+   * Rejects on timeout rather than resolving with the last non-terminal status,
+   * so "still pending" is never mistaken for "did not happen": the mint may
+   * still land afterwards, and treating a timeout as failure is what leads to
+   * registering the same agent twice. Keep the job id and poll again rather
+   * than re-registering.
+   */
+  async waitForRegistration(jobId, options) {
+    const pollIntervalMs = options?.pollIntervalMs ?? 2e3;
+    const timeoutMs = options?.timeoutMs ?? 3e5;
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const job = await this.getRegisterStatus(jobId);
+      if (isRegisterJobTerminal(job)) {
+        return job;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Registration job ${jobId} still '${job.status}' after ${Math.round(
+            timeoutMs / 1e3
+          )}s. It may still complete: poll getRegisterStatus('${jobId}') rather than registering again.`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  }
   /**
    * Get registration endpoint metadata
    *
@@ -4065,6 +4182,7 @@ exports.getEscrowSupportedChainIds = getEscrowSupportedChainIds;
 exports.isAlive = isAlive;
 exports.isEscrowExpired = isEscrowExpired;
 exports.isEscrowSupportedOnChain = isEscrowSupportedOnChain;
+exports.isRegisterJobTerminal = isRegisterJobTerminal;
 exports.parsePaymentHeader = parsePaymentHeader;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map