@naculus/connect-appkit-core 0.7.0 → 0.8.0

package/README.md

@@ -0,0 +1,13 @@
+# `@naculus/connect-appkit-core`
+
+## Authorization and settlement views
+
+`describeAuthorization` builds network-free consent text from a connect-core
+`Authorization` or `ListedAuthorization`. Pass asset metadata explicitly to
+show symbols and decimal amounts; without it, the view deliberately shows the
+asset address and base units. `explainSpend` turns every evaluator refusal into
+UI text without changing the authorization decision.
+
+`describePayment` marks every server-reported settlement as `unverified`.
+`applySettlementVerification` is the only helper that changes that state, and
+the settlement label becomes verified only for a `verified` result.

package/dist/index.cjs

@@ -21,10 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   DEFAULT_NOTIFICATION_SETTINGS: () => DEFAULT_NOTIFICATION_SETTINGS,
+  DEFAULT_VERIFY_RETRY: () => DEFAULT_VERIFY_RETRY,
   InvalidUserOperationReceiptError: () => InvalidUserOperationReceiptError,
   NOTIFICATION_SETTINGS_KEY: () => NOTIFICATION_SETTINGS_KEY,
   __resetResolverForTests: () => __resetResolverForTests,
   addInAppNotification: () => addInAppNotification,
+  applySettlementVerification: () => applySettlementVerification,
   assertHexSignature: () => assertHexSignature,
   atomicSupportFor: () => atomicSupportFor,
   bareEvmAddress: () => bareEvmAddress,
@@ -45,13 +47,16 @@ __export(src_exports, {
   decodeRevertReason: () => decodeRevertReason,
   defaultSiwxDomain: () => defaultSiwxDomain,
   defaultSiwxUri: () => defaultSiwxUri,
+  describeAuthorization: () => describeAuthorization,
   describeChain: () => describeChain,
   describePayment: () => describePayment,
   eip155ChainIdToNumber: () => eip155ChainIdToNumber,
   encodeErc20Approve: () => encodeErc20Approve,
   encodeErc20Transfer: () => encodeErc20Transfer,
   encodeErc20TransferFrom: () => encodeErc20TransferFrom,
+  explainSpend: () => explainSpend,
   fetchUserOperationReceipt: () => fetchUserOperationReceipt,
+  formatAuthorizationAmount: () => formatAuthorizationAmount,
   getResolver: () => getResolver,
   getSharedSessionKeyManager: () => getSharedSessionKeyManager,
   initialWeb3State: () => initialWeb3State,
@@ -1374,7 +1379,125 @@ function createDelegationPolicyFlow(deps) {
   };
 }
 
+// src/authorization.ts
+var import_connect_core17 = require("@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 = (0, import_connect_core17.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;
 }
@@ -1404,7 +1527,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);
@@ -1418,7 +1542,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 {
@@ -1428,7 +1553,8 @@ function describePayment(input, result) {
     asset: null,
     payTo: null,
     amount: null,
-    reference: null
+    reference: null,
+    verification: { status: "unverified" }
   };
 }
 
@@ -1463,11 +1589,11 @@ function readMppRecoveryChannelId(error) {
 }
 
 // src/solana-session-key.ts
-var import_connect_core17 = require("@naculus/connect-core");
+var import_connect_core18 = require("@naculus/connect-core");
 function send(rpc) {
   const sendTransaction = rpc.sendTransaction;
   if (!sendTransaction) {
-    throw new import_connect_core17.WalletError(
+    throw new import_connect_core18.WalletError(
       "invalid_input",
       "The Solana RPC must implement sendTransaction to approve or revoke."
     );
@@ -1505,7 +1631,7 @@ function createSolanaSessionKeyFlow(deps) {
       } catch (cause) {
         await manager.revoke(draft.id).catch(() => {
         });
-        throw new import_connect_core17.WalletError(
+        throw new import_connect_core18.WalletError(
           "rpc_error",
           `The approval could not be confirmed as sent (${cause instanceof Error ? cause.message : String(cause)}); the key is revoked here. Call revoke("${draft.id}") to send the on-chain Revoke in case it landed.`
         );
@@ -1516,7 +1642,7 @@ function createSolanaSessionKeyFlow(deps) {
     async revoke(id) {
       const key = (await list()).find((k) => k.id === id);
       if (!key) {
-        throw new import_connect_core17.WalletError(
+        throw new import_connect_core18.WalletError(
           "invalid_input",
           `No Solana session key ${id} for this owner.`
         );
@@ -1528,7 +1654,7 @@ function createSolanaSessionKeyFlow(deps) {
         rpc
       );
       const signed = await owner.signTransaction(transaction);
-      const revocation = (0, import_connect_core17.verifySignedOwnerTransaction)(signed, {
+      const revocation = (0, import_connect_core18.verifySignedOwnerTransaction)(signed, {
         kind: "revoke",
         revocation: {
           owner: key.owner,
@@ -1543,7 +1669,7 @@ function createSolanaSessionKeyFlow(deps) {
 }
 
 // src/web3-store.ts
-var import_connect_core18 = require("@naculus/connect-core");
+var import_connect_core19 = require("@naculus/connect-core");
 function withTimeout(promise, ms, label = "Operation") {
   let timeoutId;
   const timeout = new Promise((_, reject) => {
@@ -1565,7 +1691,7 @@ async function withRetry(fn, options) {
       lastError = error;
       if (attempt < options.maxRetries) {
         const delay = options.baseDelay * 2 ** attempt;
-        import_connect_core18.logger.warn(
+        import_connect_core19.logger.warn(
           "appkit/core",
           `Retry attempt ${attempt + 1}/${options.maxRetries} after ${delay}ms`
         );
@@ -1680,10 +1806,12 @@ function siwxResultToSession(result, now = /* @__PURE__ */ new Date()) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_NOTIFICATION_SETTINGS,
+  DEFAULT_VERIFY_RETRY,
   InvalidUserOperationReceiptError,
   NOTIFICATION_SETTINGS_KEY,
   __resetResolverForTests,
   addInAppNotification,
+  applySettlementVerification,
   assertHexSignature,
   atomicSupportFor,
   bareEvmAddress,
@@ -1704,13 +1832,16 @@ function siwxResultToSession(result, now = /* @__PURE__ */ new Date()) {
   decodeRevertReason,
   defaultSiwxDomain,
   defaultSiwxUri,
+  describeAuthorization,
   describeChain,
   describePayment,
   eip155ChainIdToNumber,
   encodeErc20Approve,
   encodeErc20Transfer,
   encodeErc20TransferFrom,
+  explainSpend,
   fetchUserOperationReceipt,
+  formatAuthorizationAmount,
   getResolver,
   getSharedSessionKeyManager,
   initialWeb3State,