@nexus-cross/connect-kit-core 1.3.4 → 1.3.5-beta.2

package/dist/index.d.ts

@@ -302,6 +302,65 @@ interface NetworkConfig {
     blockExplorerUrl?: string;
     testnet?: boolean;
 }
+/**
+ * The user-flow lifecycle events the kit EMITS. connect-kit is an SDK: it
+ * never stores, batches, or ships telemetry — it only surfaces these
+ * events through {@link AnalyticsPort} (react: `useConnectKitAnalytics`),
+ * and the DApp is the collection owner.
+ *
+ * See `docs/connect-kit/09-analytics-events.md`.
+ */
+type ConnectKitEventName = 'connect_modal_opened' | 'connect_modal_closed' | 'wallet_selected' | 'connect_started' | 'connect_succeeded' | 'connect_failed' | 'connect_cancelled' | 'wallet_switched' | 'disconnected';
+/** Why a connect attempt terminally failed. */
+type ConnectFailReason = 'connector_error' | 'connector_not_found' | 'fallback_failed' | 'unknown';
+/** Where in the flow the user abandoned a connect attempt. */
+type ConnectCancelStage = 'modal' | 'popup' | 'stalled';
+/**
+ * A single user-flow event. Discriminated on {@link ConnectKitEventName}.
+ *
+ * PRIVACY: payloads carry only categorical/structural values — walletId,
+ * walletType, chainId, reason, stage. Never an address, PIN, token, email,
+ * balance, or signature. `timestamp` (ms epoch) is stamped by the react
+ * adapter, not core (core has no clock).
+ */
+interface ConnectKitEventBase {
+    name: ConnectKitEventName;
+    /** ms epoch, stamped by the react adapter (core has no side effects). */
+    timestamp: number;
+}
+type ConnectKitEvent = (ConnectKitEventBase & {
+    name: 'connect_modal_opened';
+}) | (ConnectKitEventBase & {
+    name: 'connect_modal_closed';
+    completed: boolean;
+}) | (ConnectKitEventBase & {
+    name: 'wallet_selected';
+    walletId: WalletId;
+    walletType: ConnectorType;
+}) | (ConnectKitEventBase & {
+    name: 'connect_started';
+    walletId: WalletId;
+    walletType: ConnectorType;
+}) | (ConnectKitEventBase & {
+    name: 'connect_succeeded';
+    walletId: WalletId;
+    walletType: ConnectorType;
+    chainId: number;
+}) | (ConnectKitEventBase & {
+    name: 'connect_failed';
+    walletId: WalletId;
+    reason: ConnectFailReason;
+}) | (ConnectKitEventBase & {
+    name: 'connect_cancelled';
+    walletId: WalletId;
+    stage: ConnectCancelStage;
+}) | (ConnectKitEventBase & {
+    name: 'wallet_switched';
+    index: number;
+}) | (ConnectKitEventBase & {
+    name: 'disconnected';
+    walletId: WalletId | null;
+});
 type Unsubscribe = () => void;
 
 /**
@@ -391,6 +450,22 @@ interface OAuthPort {
     signIn(provider: OAuthProvider): Promise<void>;
 }
 
+/**
+ * Outbound analytics sink. The kit EMITS user-flow events; it never
+ * stores, batches, or ships them. The DApp implements this port (in the
+ * react layer, via the `useConnectKitAnalytics` hook) to route events into
+ * its own analytics (GA, Amplitude, backend, …).
+ *
+ * Sync + fire-and-forget (like {@link ModalControlPort}): a slow or
+ * throwing handler must never block or break the connect flow — the react
+ * adapter swallows handler errors.
+ *
+ * See `docs/connect-kit/09-analytics-events.md`.
+ */
+interface AnalyticsPort {
+    track(event: ConnectKitEvent): void;
+}
+
 /**
  * Theme-mode resolution.
  *
@@ -442,4 +517,4 @@ declare function formatBalance(value: bigint, decimals: number, displayDecimals?
  */
 declare function formatWei(wei: bigint, displayDecimals?: number): string;
 
-export { type Account, type AppMetadata, type BalancePort, type ChainBalance, type ColorOverrides, ConnectionStatus, type ConnectorPort, type ConnectorResult, type ConnectorType, type CrossConnectKitConfig, type LegalLinks, type ModalControlPort, type ModalView, type NetworkConfig, type OAuthPort, type OAuthProvider, type PinKeyboardMode, type PinKeyboardOption, type StoragePort, type Theme, type ThemeMode, type ThemePort, type ThemeTokens, type Unsubscribe, type WalletDescriptor, type WalletDetectionPort, type WalletId, type WalletState, formatBalance, formatWei, resolveThemeMode };
+export { type Account, type AnalyticsPort, type AppMetadata, type BalancePort, type ChainBalance, type ColorOverrides, type ConnectCancelStage, type ConnectFailReason, type ConnectKitEvent, type ConnectKitEventName, ConnectionStatus, type ConnectorPort, type ConnectorResult, type ConnectorType, type CrossConnectKitConfig, type LegalLinks, type ModalControlPort, type ModalView, type NetworkConfig, type OAuthPort, type OAuthProvider, type PinKeyboardMode, type PinKeyboardOption, type StoragePort, type Theme, type ThemeMode, type ThemePort, type ThemeTokens, type Unsubscribe, type WalletDescriptor, type WalletDetectionPort, type WalletId, type WalletState, formatBalance, formatWei, resolveThemeMode };

package/dist/index.js

@@ -1 +1 @@
-var f={CONNECTED:"connected",DISCONNECTED:"disconnected",CONNECTING:"connecting",RECONNECTING:"reconnecting"};function u(e,t){if(t&&typeof window<"u"&&window.matchMedia)try{return window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}catch{}return typeof e=="string"?e:e&&typeof e=="object"&&"mode"in e?e.mode??"dark":"dark"}function m(e,t,r=4){if(t<0||!Number.isInteger(t))throw new RangeError(`formatBalance: decimals must be a non-negative integer, got ${t}`);if(r<0||!Number.isInteger(r))throw new RangeError(`formatBalance: displayDecimals must be a non-negative integer, got ${r}`);let n=e<0n,i=n?-e:e;if(t===0){let o=i.toString();return n?`-${o}`:o}let l=10n**BigInt(t),s=i/l,g=i%l;if(r===0){let o=s.toString();return n?`-${o}`:o}let c=g.toString().padStart(t,"0").slice(0,r),a=c.length;for(;a>0&&c.charCodeAt(a-1)===48;)a--;let d=c.slice(0,a),p=d?`${s}.${d}`:s.toString();return n?`-${p}`:p}function y(e,t=4){return m(e,18,t)}import{OnRampError as M,normalizeDisallowReason as S}from"@nexus-cross/onramp";export{f as ConnectionStatus,M as OnRampError,m as formatBalance,y as formatWei,S as normalizeDisallowReason,u as resolveThemeMode};
+var f={CONNECTED:"connected",DISCONNECTED:"disconnected",CONNECTING:"connecting",RECONNECTING:"reconnecting"};function u(e,t){if(t&&typeof window<"u"&&window.matchMedia)try{return window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}catch{}return typeof e=="string"?e:e&&typeof e=="object"&&"mode"in e?e.mode??"dark":"dark"}function m(e,t,n=4){if(t<0||!Number.isInteger(t))throw new RangeError(`formatBalance: decimals must be a non-negative integer, got ${t}`);if(n<0||!Number.isInteger(n))throw new RangeError(`formatBalance: displayDecimals must be a non-negative integer, got ${n}`);let r=e<0n,c=r?-e:e;if(t===0){let o=c.toString();return r?`-${o}`:o}let s=10n**BigInt(t),i=c/s,g=c%s;if(n===0){let o=i.toString();return r?`-${o}`:o}let l=g.toString().padStart(t,"0").slice(0,n),a=l.length;for(;a>0&&l.charCodeAt(a-1)===48;)a--;let d=l.slice(0,a),p=d?`${i}.${d}`:i.toString();return r?`-${p}`:p}function C(e,t=4){return m(e,18,t)}import{OnRampError as E,normalizeDisallowReason as O}from"@nexus-cross/onramp";export{f as ConnectionStatus,E as OnRampError,m as formatBalance,C as formatWei,O as normalizeDisallowReason,u as resolveThemeMode};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-cross/connect-kit-core",
-  "version": "1.3.4",
+  "version": "1.3.5-beta.2",
   "description": "Core domain logic for @nexus-cross/connect-kit — types, ports, utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nexus-cross/onramp": "1.3.4"
+    "@nexus-cross/onramp": "1.3.5-beta.2"
   },
   "devDependencies": {
     "tsup": "^8.4.0",