@naculus/connect-appkit-core 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
+import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SpendRefusal, Authorization, ListedAuthorization, SpendRequest, SettlementVerification, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
 
 /**
  * The types the framework-neutral half of appkit is built on.
@@ -43,7 +43,7 @@ interface Web3State {
 }
 
 /**
- * EIP-5792 capability answers, normalised once.
+ * EIP-5792 capability answers, normalized once.
  *
  * Deciding how to execute before sending is the whole point of
  * `wallet_getCapabilities`, and the reasoning that turns a raw answer into
@@ -82,7 +82,7 @@ declare function normalizeCapabilities(raw: Record<string, unknown> | null | und
 /**
  * Find the entry for a chain, by CAIP-2 or by the hex form.
  *
- * Connectors normalise keys to CAIP-2, but a wallet answering in raw hex
+ * Connectors normalize keys to CAIP-2, but a wallet answering in raw hex
  * through a custom connector should still be found rather than reported as
  * "unknown" next to an entry that is sitting right there.
  */
@@ -618,7 +618,7 @@ type ExecuteRoute = (quote: ExecutableQuote, recipient: string, options?: Execut
  * a valid non-EVM address on a guess.
  */
 declare function validateRouteRecipient(quote: ExecutableQuote | null | undefined, recipient: string): ExecuteRouteError | null;
-/** Normalise whatever an executor threw into the hook's error shape. */
+/** Normalize whatever an executor threw into the hook's error shape. */
 declare function toExecuteRouteError(cause: unknown): ExecuteRouteError;
 
 /** The subset of the config that changes what a key may spend or how it is sealed. */
@@ -854,6 +854,62 @@ interface DelegationFrameworkAdapterOptions {
 }
 declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAdapterOptions): PolicyExecutionAdapter;
 
+type AssetId = string;
+interface AuthorizationAssetMetadata {
+    symbol: string;
+    decimals: number;
+}
+interface DescribeAuthorizationOptions {
+    assets?: Record<AssetId, AuthorizationAssetMetadata>;
+    locale?: string;
+    /** Unix timestamp in seconds. */
+    now?: number;
+}
+interface AuthorizationRecipientView {
+    shortened: string;
+    full: string;
+}
+interface AuthorizationAmountView {
+    formatted: string;
+}
+interface AuthorizationGrantView {
+    asset: AssetId;
+    assetLabel: string;
+    recipients: AuthorizationRecipientView[];
+    perPayment: AuthorizationAmountView;
+    total: AuthorizationAmountView;
+    count: number | null;
+    rails: string[];
+}
+interface AuthorizationExpiryView {
+    timestamp: number;
+    absolute: string;
+    relative: string;
+}
+interface AuthorizationDescription {
+    label: string | null;
+    principal: string | null;
+    grants: AuthorizationGrantView[];
+    expiry: AuthorizationExpiryView;
+    warnings: string[];
+}
+declare function formatAuthorizationAmount(amount: bigint, metadata: AuthorizationAssetMetadata | undefined): AuthorizationAmountView;
+/** Build a network-free consent/listing view of an authorization. */
+declare function describeAuthorization(input: Authorization | ListedAuthorization, options?: DescribeAuthorizationOptions): AuthorizationDescription;
+type SpendExplanation = {
+    allowed: true;
+    grant: number;
+    remainingTotal: bigint;
+    remainingTotalFormatted: AuthorizationAmountView;
+    sentence: string;
+} | {
+    allowed: false;
+    reason: SpendRefusal;
+    sentence: string;
+};
+/** Explain the shared evaluator's exact allow/refuse result for a UI. */
+declare function explainSpend(authorization: Authorization, request: SpendRequest, options?: DescribeAuthorizationOptions): SpendExplanation;
+
 /**
  * Agentic payments (x402 / MPP) for the appkit shells.
  *
@@ -861,7 +917,7 @@ declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAd
  * `@naculus/payments-x402` or `createMppFetch` from `@naculus/payments-mpp`,
  * with the session key and limits it chooses — and the hooks only track its
  * state. So appkit takes no dependency on either package: their results are
- * read here by shape, and a shape this does not recognise is reported as
+ * read here by shape, and a shape this does not recognize is reported as
  * `protocol: "unknown"` rather than guessed at.
  */
 /** What `createX402Fetch` and `createMppFetch` return, structurally. */
@@ -875,6 +931,11 @@ interface PaymentFetchResult {
     receipt?: unknown;
 }
 type PaymentFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<PaymentFetchResult>;
+type PaymentVerificationStatus = "unverified" | "pending" | "verified" | "mismatch" | "failed" | "unavailable";
+interface PaymentVerification {
+    status: PaymentVerificationStatus;
+    reason?: string;
+}
 /** One payment, in the terms a UI shows. Amounts are token base units. */
 interface PaymentRecord {
     protocol: "x402" | "mpp" | "unknown";
@@ -891,7 +952,19 @@ interface PaymentRecord {
      * other fields are what the client signed.
      */
     reference: string | null;
+    /** A server-reported reference remains unverified until this is verified. */
+    verification: PaymentVerification;
+}
+declare const DEFAULT_VERIFY_RETRY: {
+    readonly attempts: 5;
+    readonly delayMs: 4000;
+};
+interface VerifyRetryOptions {
+    attempts: number;
+    delayMs: number;
 }
+/** Apply a verifier result without mutating the payment record. */
+declare function applySettlementVerification(payment: PaymentRecord, result: SettlementVerification): PaymentRecord;
 /**
  * The payment a paying fetch made, or null when it paid nothing. Reads the
  * x402 requirement / settlement (EVM or Solana) or the MPP `evm` / `solana`
@@ -1079,4 +1152,4 @@ declare function siwxResultToSession<M extends SiwxMessageLike>(result: SiwxResu
     refreshedAt: null;
 };
 
-export { type AddressValidationLevel, type AtomicSupport, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, type MppSessionChannel, type MppSessionFetch, type MppSessionFetchResult, type MppSessionForceCloseResult, type MppSessionMeter, type MppSessionReceipt, type MppSessionRequest, type MppSessionRequestInit, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type NotificationSettingsUpdate, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type TransactionSimulationContext, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, fetchUserOperationReceipt, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readCurrentMppSessionChannel, readDecimals, readMppRecoveryChannelId, readMppSessionChannel, readMppSessionReceipt, readSolanaRoles, replayNotificationSettings, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };
+export { type AddressValidationLevel, type AssetId, type AtomicSupport, type AuthorizationAmountView, type AuthorizationAssetMetadata, type AuthorizationDescription, type AuthorizationExpiryView, type AuthorizationGrantView, type AuthorizationRecipientView, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, DEFAULT_VERIFY_RETRY, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DescribeAuthorizationOptions, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, type MppSessionChannel, type MppSessionFetch, type MppSessionFetchResult, type MppSessionForceCloseResult, type MppSessionMeter, type MppSessionReceipt, type MppSessionRequest, type MppSessionRequestInit, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type NotificationSettingsUpdate, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PaymentVerification, type PaymentVerificationStatus, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type SpendExplanation, type TokenIdentity, type TransactionSimulationContext, type VerifyRetryOptions, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, applySettlementVerification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeAuthorization, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, explainSpend, fetchUserOperationReceipt, formatAuthorizationAmount, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readCurrentMppSessionChannel, readDecimals, readMppRecoveryChannelId, readMppSessionChannel, readMppSessionReceipt, readSolanaRoles, replayNotificationSettings, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
+import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SpendRefusal, Authorization, ListedAuthorization, SpendRequest, SettlementVerification, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
 
 /**
  * The types the framework-neutral half of appkit is built on.
@@ -43,7 +43,7 @@ interface Web3State {
 }
 
 /**
- * EIP-5792 capability answers, normalised once.
+ * EIP-5792 capability answers, normalized once.
  *
  * Deciding how to execute before sending is the whole point of
  * `wallet_getCapabilities`, and the reasoning that turns a raw answer into
@@ -82,7 +82,7 @@ declare function normalizeCapabilities(raw: Record<string, unknown> | null | und
 /**
  * Find the entry for a chain, by CAIP-2 or by the hex form.
  *
- * Connectors normalise keys to CAIP-2, but a wallet answering in raw hex
+ * Connectors normalize keys to CAIP-2, but a wallet answering in raw hex
  * through a custom connector should still be found rather than reported as
  * "unknown" next to an entry that is sitting right there.
  */
@@ -618,7 +618,7 @@ type ExecuteRoute = (quote: ExecutableQuote, recipient: string, options?: Execut
  * a valid non-EVM address on a guess.
  */
 declare function validateRouteRecipient(quote: ExecutableQuote | null | undefined, recipient: string): ExecuteRouteError | null;
-/** Normalise whatever an executor threw into the hook's error shape. */
+/** Normalize whatever an executor threw into the hook's error shape. */
 declare function toExecuteRouteError(cause: unknown): ExecuteRouteError;
 
 /** The subset of the config that changes what a key may spend or how it is sealed. */
@@ -854,6 +854,62 @@ interface DelegationFrameworkAdapterOptions {
 }
 declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAdapterOptions): PolicyExecutionAdapter;
 
+type AssetId = string;
+interface AuthorizationAssetMetadata {
+    symbol: string;
+    decimals: number;
+}
+interface DescribeAuthorizationOptions {
+    assets?: Record<AssetId, AuthorizationAssetMetadata>;
+    locale?: string;
+    /** Unix timestamp in seconds. */
+    now?: number;
+}
+interface AuthorizationRecipientView {
+    shortened: string;
+    full: string;
+}
+interface AuthorizationAmountView {
+    formatted: string;
+}
+interface AuthorizationGrantView {
+    asset: AssetId;
+    assetLabel: string;
+    recipients: AuthorizationRecipientView[];
+    perPayment: AuthorizationAmountView;
+    total: AuthorizationAmountView;
+    count: number | null;
+    rails: string[];
+}
+interface AuthorizationExpiryView {
+    timestamp: number;
+    absolute: string;
+    relative: string;
+}
+interface AuthorizationDescription {
+    label: string | null;
+    principal: string | null;
+    grants: AuthorizationGrantView[];
+    expiry: AuthorizationExpiryView;
+    warnings: string[];
+}
+declare function formatAuthorizationAmount(amount: bigint, metadata: AuthorizationAssetMetadata | undefined): AuthorizationAmountView;
+/** Build a network-free consent/listing view of an authorization. */
+declare function describeAuthorization(input: Authorization | ListedAuthorization, options?: DescribeAuthorizationOptions): AuthorizationDescription;
+type SpendExplanation = {
+    allowed: true;
+    grant: number;
+    remainingTotal: bigint;
+    remainingTotalFormatted: AuthorizationAmountView;
+    sentence: string;
+} | {
+    allowed: false;
+    reason: SpendRefusal;
+    sentence: string;
+};
+/** Explain the shared evaluator's exact allow/refuse result for a UI. */
+declare function explainSpend(authorization: Authorization, request: SpendRequest, options?: DescribeAuthorizationOptions): SpendExplanation;
+
 /**
  * Agentic payments (x402 / MPP) for the appkit shells.
  *
@@ -861,7 +917,7 @@ declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAd
  * `@naculus/payments-x402` or `createMppFetch` from `@naculus/payments-mpp`,
  * with the session key and limits it chooses — and the hooks only track its
  * state. So appkit takes no dependency on either package: their results are
- * read here by shape, and a shape this does not recognise is reported as
+ * read here by shape, and a shape this does not recognize is reported as
  * `protocol: "unknown"` rather than guessed at.
  */
 /** What `createX402Fetch` and `createMppFetch` return, structurally. */
@@ -875,6 +931,11 @@ interface PaymentFetchResult {
     receipt?: unknown;
 }
 type PaymentFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<PaymentFetchResult>;
+type PaymentVerificationStatus = "unverified" | "pending" | "verified" | "mismatch" | "failed" | "unavailable";
+interface PaymentVerification {
+    status: PaymentVerificationStatus;
+    reason?: string;
+}
 /** One payment, in the terms a UI shows. Amounts are token base units. */
 interface PaymentRecord {
     protocol: "x402" | "mpp" | "unknown";
@@ -891,7 +952,19 @@ interface PaymentRecord {
      * other fields are what the client signed.
      */
     reference: string | null;
+    /** A server-reported reference remains unverified until this is verified. */
+    verification: PaymentVerification;
+}
+declare const DEFAULT_VERIFY_RETRY: {
+    readonly attempts: 5;
+    readonly delayMs: 4000;
+};
+interface VerifyRetryOptions {
+    attempts: number;
+    delayMs: number;
 }
+/** Apply a verifier result without mutating the payment record. */
+declare function applySettlementVerification(payment: PaymentRecord, result: SettlementVerification): PaymentRecord;
 /**
  * The payment a paying fetch made, or null when it paid nothing. Reads the
  * x402 requirement / settlement (EVM or Solana) or the MPP `evm` / `solana`
@@ -1079,4 +1152,4 @@ declare function siwxResultToSession<M extends SiwxMessageLike>(result: SiwxResu
     refreshedAt: null;
 };
 
-export { type AddressValidationLevel, type AtomicSupport, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, type MppSessionChannel, type MppSessionFetch, type MppSessionFetchResult, type MppSessionForceCloseResult, type MppSessionMeter, type MppSessionReceipt, type MppSessionRequest, type MppSessionRequestInit, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type NotificationSettingsUpdate, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type TransactionSimulationContext, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, fetchUserOperationReceipt, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readCurrentMppSessionChannel, readDecimals, readMppRecoveryChannelId, readMppSessionChannel, readMppSessionReceipt, readSolanaRoles, replayNotificationSettings, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };
+export { type AddressValidationLevel, type AssetId, type AtomicSupport, type AuthorizationAmountView, type AuthorizationAssetMetadata, type AuthorizationDescription, type AuthorizationExpiryView, type AuthorizationGrantView, type AuthorizationRecipientView, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, DEFAULT_VERIFY_RETRY, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DescribeAuthorizationOptions, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, type MppSessionChannel, type MppSessionFetch, type MppSessionFetchResult, type MppSessionForceCloseResult, type MppSessionMeter, type MppSessionReceipt, type MppSessionRequest, type MppSessionRequestInit, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type NotificationSettingsUpdate, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PaymentVerification, type PaymentVerificationStatus, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type SpendExplanation, type TokenIdentity, type TransactionSimulationContext, type VerifyRetryOptions, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, applySettlementVerification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeAuthorization, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, explainSpend, fetchUserOperationReceipt, formatAuthorizationAmount, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readCurrentMppSessionChannel, readDecimals, readMppRecoveryChannelId, readMppSessionChannel, readMppSessionReceipt, readSolanaRoles, replayNotificationSettings, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };

package/dist/index.js

@@ -1296,7 +1296,127 @@ function createDelegationPolicyFlow(deps) {
   };
 }
 
+// src/authorization.ts
+import {
+  evaluateSpend
+} from "@naculus/connect-core";
+function assetAddress(asset) {
+  return asset.split(/[:/]/).at(-1);
+}
+function groupDigits(value) {
+  return value.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function formatAuthorizationAmount(amount, metadata) {
+  const baseUnits = amount.toString();
+  if (!metadata || !metadata.symbol || !Number.isSafeInteger(metadata.decimals) || metadata.decimals < 0) {
+    return {
+      formatted: `${groupDigits(baseUnits)} base units`
+    };
+  }
+  const decimals = metadata.decimals;
+  const padded = baseUnits.padStart(decimals + 1, "0");
+  const integer = decimals === 0 ? padded : padded.slice(0, -decimals);
+  const fraction = decimals === 0 ? "" : padded.slice(-decimals).replace(/0+$/, "");
+  const value = `${groupDigits(integer)}${fraction ? `.${fraction}` : ""}`;
+  return { formatted: `${value} ${metadata.symbol}` };
+}
+function relativeExpiry(expiresAt, now, locale) {
+  const seconds = expiresAt - now;
+  const absolute = Math.abs(seconds);
+  const divisor = absolute >= 31536e3 ? 31536e3 : absolute >= 2592e3 ? 2592e3 : absolute >= 86400 ? 86400 : absolute >= 3600 ? 3600 : absolute >= 60 ? 60 : 1;
+  const unit = divisor === 31536e3 ? "year" : divisor === 2592e3 ? "month" : divisor === 86400 ? "day" : divisor === 3600 ? "hour" : divisor === 60 ? "minute" : "second";
+  return new Intl.RelativeTimeFormat(locale).format(
+    Math.round(seconds / divisor),
+    unit
+  );
+}
+function describeAuthorization(input, options = {}) {
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  const locale = options.locale ?? "en";
+  const flags = "flags" in input ? input.flags : [];
+  const label = "label" in input ? input.label ?? null : null;
+  return {
+    label,
+    principal: input.principal ?? null,
+    grants: input.grants.map((grant) => {
+      const metadata = options.assets?.[grant.asset];
+      return {
+        asset: grant.asset,
+        assetLabel: metadata?.symbol || assetAddress(grant.asset),
+        recipients: grant.recipients.map((full) => ({
+          shortened: full.length <= 14 ? full : `${full.slice(0, 6)}\u2026${full.slice(-6)}`,
+          full
+        })),
+        perPayment: formatAuthorizationAmount(grant.maxPerPayment, metadata),
+        total: formatAuthorizationAmount(grant.maxTotal, metadata),
+        count: grant.maxCount ?? null,
+        rails: grant.rails.map((r) => r.replace("-", " "))
+      };
+    }),
+    expiry: {
+      timestamp: input.expiresAt,
+      absolute: new Intl.DateTimeFormat(locale, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+        timeZone: "UTC",
+        timeZoneName: "short"
+      }).format(input.expiresAt * 1e3),
+      relative: relativeExpiry(input.expiresAt, now, locale)
+    },
+    warnings: flags.map(
+      (flag) => flag === "unrestricted-recipient-legacy" ? "This key can pay any recipient." : "This key can do more than shown here."
+    )
+  };
+}
+var REFUSAL_SENTENCES = {
+  expired: "This authorization has expired.",
+  "not-yet-valid": "This authorization is not valid yet.",
+  "no-matching-grant": "No grant covers this asset.",
+  "recipient-not-allowed": "This recipient is not allowed.",
+  "over-per-payment": "This amount exceeds the per-payment limit.",
+  "over-total": "This amount exceeds the remaining total limit.",
+  "over-count": "This authorization has reached its payment count limit.",
+  "rail-not-allowed": "This payment rail is not allowed.",
+  "invalid-authorization": "The authorization or spend request is invalid."
+};
+function explainSpend(authorization, request, options = {}) {
+  const verdict = evaluateSpend(authorization, request);
+  if (!verdict.allow) {
+    return {
+      allowed: false,
+      reason: verdict.reason,
+      sentence: REFUSAL_SENTENCES[verdict.reason]
+    };
+  }
+  const remainingTotal = authorization.grants[verdict.grant].maxTotal - request.spentSoFar - request.amount;
+  const remainingTotalFormatted = formatAuthorizationAmount(
+    remainingTotal,
+    options.assets?.[authorization.grants[verdict.grant].asset]
+  );
+  return {
+    allowed: true,
+    grant: verdict.grant,
+    remainingTotal,
+    remainingTotalFormatted,
+    sentence: `Allowed by grant ${verdict.grant + 1}; ${remainingTotalFormatted.formatted} remain.`
+  };
+}
+
 // src/payment-fetch.ts
+var DEFAULT_VERIFY_RETRY = { attempts: 5, delayMs: 4e3 };
+function applySettlementVerification(payment, result) {
+  return {
+    ...payment,
+    verification: {
+      status: result.status,
+      ..."reason" in result && result.reason !== void 0 ? { reason: result.reason } : {}
+    }
+  };
+}
 function record(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 }
@@ -1326,7 +1446,8 @@ function describePayment(input, result) {
       payTo: text(paid.payTo),
       amount: text(paid.amount),
       // A hash reported for another chain is not this payment's.
-      reference: settlement?.success === true && settlement.network === paid.network ? text(settlement.transaction) : null
+      reference: settlement?.success === true && settlement.network === paid.network ? text(settlement.transaction) : null,
+      verification: { status: "unverified" }
     };
   }
   const challenge = record(record(paid.challenge)?.params);
@@ -1340,7 +1461,8 @@ function describePayment(input, result) {
       asset: text(request.currency),
       payTo: text(request.recipient),
       amount: text(request.amount),
-      reference: text(record(result.receipt)?.reference)
+      reference: text(record(result.receipt)?.reference),
+      verification: { status: "unverified" }
     };
   }
   return {
@@ -1350,7 +1472,8 @@ function describePayment(input, result) {
     asset: null,
     payTo: null,
     amount: null,
-    reference: null
+    reference: null,
+    verification: { status: "unverified" }
   };
 }
 
@@ -1604,10 +1727,12 @@ function siwxResultToSession(result, now = /* @__PURE__ */ new Date()) {
 }
 export {
   DEFAULT_NOTIFICATION_SETTINGS,
+  DEFAULT_VERIFY_RETRY,
   InvalidUserOperationReceiptError,
   NOTIFICATION_SETTINGS_KEY,
   __resetResolverForTests,
   addInAppNotification,
+  applySettlementVerification,
   assertHexSignature,
   atomicSupportFor,
   bareEvmAddress,
@@ -1628,13 +1753,16 @@ export {
   decodeRevertReason,
   defaultSiwxDomain,
   defaultSiwxUri,
+  describeAuthorization,
   describeChain,
   describePayment,
   eip155ChainIdToNumber,
   encodeErc20Approve,
   encodeErc20Transfer,
   encodeErc20TransferFrom,
+  explainSpend,
   fetchUserOperationReceipt,
+  formatAuthorizationAmount,
   getResolver,
   getSharedSessionKeyManager,
   initialWeb3State,