@nexus-cross/connect-kit-core 2.3.4-beta.1 → 2.4.0-beta.2

package/dist/index.d.ts

@@ -222,6 +222,25 @@ interface CrossConnectKitConfig {
      * `embeddedProjectId`(미설정 시 `crossProjectId` fallback)를 사용한다.
      */
     kycEnabled?: boolean;
+    /**
+     * ONEpop(소셜 핸들 드롭) 마스터 토글. default false.
+     *
+     * true이면 이 토글 **하나로** ONEpop이 특별한 추가 설정 없이 동작한다:
+     * - `ConnectButton`이 WalletInfo에 `showOnePop`을 켜서 액션 행 ONEpop
+     *   카드와 진입 화면을 노출한다 (prop으로 `showOnePop`을 명시하면 우선).
+     * - ONEpop 화면에 표시할 `onePopSummary`(수령 대기 수/합계, X 연결 여부,
+     *   최근 활동)를 `@nexus-cross/pop`으로 조회해 자동 주입한다(fallback).
+     *   one-pop-api `/drops`·`/histories`는 cross-auth SIWE JWT를 요구하므로
+     *   **사용자가 ONEpop 화면을 실제로 열 때** 서명을 한 번 요청하고, 발급된
+     *   토큰은 세션 동안 주소별로 재사용한다. DApp이 `onePopSummary`를 직접
+     *   주입하면 조회를 건너뛴다.
+     * - 화면의 액션(Send POP / Claim POPs / Activity / 배너)은 ONEpop 서비스
+     *   웹 딥링크가 기본 동작이고, `onOnePopSend` 등 콜백 주입 시 그것이
+     *   우선한다.
+     *
+     * false(기본)면 ONEpop 카드/화면이 렌더되지 않고 조회도 하지 않는다.
+     */
+    onePopEnabled?: boolean;
     /**
      * When `true`, the kit switches the wallet to {@link defaultNetwork}
      * exactly once right after a connection is established. External
@@ -242,6 +261,35 @@ interface CrossConnectKitConfig {
      * Requires `defaultNetwork` to be set. Default: `false`.
      */
     enforceDefaultNetworkOnConnect?: boolean;
+    /**
+     * When `true` (default), any wallet chain switch the kit performs *for
+     * an operation* is undone once that operation completes — the wallet is
+     * restored to the chain it was on before. This covers the bridge/swap
+     * flow (which switches to the source chain to submit the tx) and the
+     * Send screen (which switches to the token's chain to send).
+     *
+     * Rationale: the temporary switch is an implementation detail of the
+     * operation. Leaving the DApp's wallet stranded on, say, BSC after a
+     * BSC→CROSS bridge makes the rest of the app (and the developer's own
+     * flows) behave unexpectedly. app-launcher is a DApp-integration tool,
+     * so the friendly default is to hand the chain back.
+     *
+     * Semantics:
+     *   - Best-effort: restore is fire-and-forget. A rejected switch-back
+     *     (or an unconfigured chain) never turns a successful bridge/send
+     *     into a failure.
+     *   - Only after success. A failed/cancelled operation leaves the
+     *     wallet on the operation chain so the user can retry without an
+     *     extra switch round-trip.
+     *   - No-op when no switch happened (e.g. already on the target chain,
+     *     or the gasless permit bridge path that never switches).
+     *
+     * Unlike {@link enforceDefaultNetworkOnConnect} — which pins to a fixed
+     * canonical chain once at connect — this restores to whatever chain the
+     * user actually had before the operation. Set `false` to leave the
+     * wallet on the operation chain. Default: `true`.
+     */
+    restoreChainAfterSwitch?: boolean;
 }
 interface AppMetadata {
     name: string;
@@ -273,6 +321,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;
 
 /**
@@ -362,6 +469,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.
  *
@@ -413,4 +536,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 d=10n**BigInt(t),s=i/d,g=i%d;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 l=c.slice(0,a),p=l?`${s}.${l}`: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": "2.3.4-beta.1",
+  "version": "2.4.0-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": "2.3.4-beta.1"
+    "@nexus-cross/onramp": "2.4.0-beta.2"
   },
   "devDependencies": {
     "tsup": "^8.4.0",