zigap-utils 3.1.0-preview.1 → 3.1.0-preview.4

package/dist/utils/deeplinkTransport.d.ts

@@ -0,0 +1,68 @@
+/**
+ * deeplinkTransport — type-무관 store-and-forward transport (서버 StoreForwardStore 의 클라이언트 짝).
+ *
+ * 딥링크로 dapp 탭이 꺼졌다 살아나도 연결을 끝까지 잇기 위한 모듈.
+ * envelope({roomId,type,payload,nonce,ttl})를 해석하지 않고 그대로 실어 보낸다 —
+ * type-무관 transport, login 외 type 은 envelope.type 만 바꿔 재사용(보고서 §7.1).
+ * login 은 첫 consumer 일 뿐, sendTransaction/payment 도 같은 모듈을 공유한다.
+ *
+ * 저장소 백엔드(LOCKED 가드): 스냅샷은 원시 localStorage 직접 호출(setItem/getItem/removeItem)만 쓴다 —
+ * 기존 zigap-utils 패턴(useZigap.ts 의 LOGIN_RES_KEY)과 동일.
+ * - ❌ ZIGAP.Store(zigap.io 전용; app=secureStorage 분기)를 끌어오지 않는다 — dapp 은 항상 browser 컨텍스트.
+ * - ❌ sessionStorage 도 쓰지 않는다 — 탭 discard 시 소멸해 unload 2겹 보존이 무력화된다.
+ *
+ * localStorage 경계(LOCKED 가드): 스냅샷은 dapp 자기 상태(roomId/nonce/pending) 보존 전용이다.
+ * 앱→dapp 결과 전달(cross-process)에는 절대 쓰지 않는다 — 결과는 서버 보관/소켓(resumeRoom)으로만(보고서 §3).
+ */
+export type DeeplinkEnvelopeType = 'login' | 'signMessage' | 'sendTransaction' | 'payment';
+export interface DeeplinkEnvelope {
+    roomId: string;
+    type: DeeplinkEnvelopeType | string;
+    payload: any;
+    nonce: string;
+    ttl?: number;
+}
+export type SnapshotStatus = 'pending' | 'done';
+export interface DeeplinkSnapshot {
+    roomId: string;
+    type: DeeplinkEnvelopeType | string;
+    status: SnapshotStatus;
+    nonce: string;
+    startedAt: number;
+}
+export type ResumeAction = 'resume' | 'noop' | 'timeout';
+/**
+ * 복귀했을 때 무엇을 할지 결정하는 순수 함수 (DOM·소켓에 의존 안 해 단위 검증 가능).
+ * type 비의존 — 어떤 type 의 스냅샷이든 동일하게 동작한다(type-무관).
+ *
+ * 스냅샷 없음 / 이미 완료('done')      → noop (할 일 없음; null→noop 로 데스크톱 격리 DeepLink-01)
+ * 화면이 아직 안 보임(백그라운드)        → noop (보일 때까지 대기)
+ * 시작 후 timeoutMs 초과               → timeout (시간 초과 안내)
+ * 그 외(진행중 + 화면 보임 + 시간 내)   → resume (이어서 진행)
+ */
+export declare const computeResumeAction: (snapshot: DeeplinkSnapshot | null | undefined, visibilityState: string, now?: number, timeoutMs?: number) => ResumeAction;
+/** 진행중('pending') 상태의 스냅샷 객체를 만든다 (순수). type='login'/'signMessage' 동일 구조(type-무관). */
+export declare const makeSnapshot: (roomId: string, nonce: string, type: DeeplinkEnvelopeType | string) => DeeplinkSnapshot;
+/**
+ * envelope 를 해석하지 않고 그대로 서버에 실어 보내는 type-무관 transport 클래스.
+ * register/resume 는 socketService emit, snapshot* 은 원시 localStorage I/O 뿐이다.
+ */
+declare class DeeplinkTransportService {
+    /** 딥링크로 넘어가기 직전, 서명할 메시지(envelope)를 서버에 미리 맡겨둔다 (선등록 DeepLink-02). */
+    register(roomId: string, envelope: DeeplinkEnvelope): void;
+    /** 돌아왔을 때 방에 다시 들어가 서버 보관분을 받아온다 (resumeRoom pull). */
+    resume(roomId: string): void;
+    /** 스냅샷을 원시 localStorage 에 저장한다 (dapp 자기 상태 보존 전용 — 결과 전달엔 절대 미사용). */
+    snapshotSave(snapshot: DeeplinkSnapshot): void;
+    snapshotLoad(roomId: string): DeeplinkSnapshot | null;
+    snapshotClear(roomId: string): void;
+    snapshotClearAll(): void;
+    /**
+     * 보관된 pending 스냅샷 중 미만료 최신 1건을 반환한다 (풀 리로드 복귀 시 원래 방 복구용).
+     * 스냅샷엔 ttl 필드가 없어 기본 timeout 창(DEFAULT_TIMEOUT_MS)을 만료 기준으로 쓴다.
+     * 만료 항목은 순회하며 removeItem 으로 정리한다. done/파싱불가/없음 → null.
+     */
+    snapshotLoadAnyPending(now?: number, timeoutMs?: number): DeeplinkSnapshot | null;
+}
+export declare const deeplinkTransport: DeeplinkTransportService;
+export default deeplinkTransport;

package/dist/utils/device.d.ts

@@ -0,0 +1,14 @@
+/**
+ * UA·포인터 입력만으로 모바일 여부를 판별하는 순수 함수.
+ * DOM 없이 단위 검증 가능하도록 분리한다 (device.test.mjs 가 동일 로직을 어서션).
+ */
+export declare const detectIsMobileFromInputs: (userAgent: string, isCoarsePointer: boolean) => boolean;
+declare class DeviceService {
+    /**
+     * 표준 웹 API(navigator.userAgent + matchMedia('(pointer: coarse)'))만으로 모바일을 판별한다.
+     * SSR(window/navigator 부재)에서는 절대 throw 하지 않고 false 를 반환한다.
+     */
+    isMobile(): boolean;
+}
+export declare const device: DeviceService;
+export {};

package/dist/utils/handshake.d.ts

@@ -0,0 +1,6 @@
+export declare function receiveRequest(roomId: string): Promise<{
+    roomId: string;
+    isSuccess: boolean;
+}>;
+export declare function sendMessage(roomId: string, message: string): Promise<void>;
+export declare function checkVerified(roomId: string, verified: boolean): Promise<string>;

package/dist/utils/resumeLoginResult.d.ts

@@ -0,0 +1,25 @@
+/** 모바일 resume(서버 보관분) 결과에 공통으로 비어 오는 인증 필드 — Login/Sig 가 같은 모양을 쓴다. */
+interface ResumeLoginFields {
+    token?: string;
+    signature?: string;
+    issuedDateTime?: string;
+    expire?: {
+        type: 'NONE';
+    } | {
+        type: 'FIX' | 'EXTEND';
+        seconds: number;
+    };
+}
+type ExpireOption = {
+    type: 'NONE' | 'FIX' | 'EXTEND';
+    seconds?: number;
+} | undefined;
+/**
+ * resume 결과는 token/issuedDateTime/expire 가 비어 온다(signature·address 등은 옴).
+ * LoginQR/SignatureQR 은 EVM 네트워크 전용이라 token payload 에 publicKey 가 없다 —
+ * signature(resume 보유) + message 만으로 라이브와 동일한 token 을 조립한다.
+ * token 이 라이브와 바이트 단위로 같아야 하므로 message 는 sigMessage·nonce 로 여기서 만든다.
+ * result 를 제자리에서 보강한다.
+ */
+export declare const completeResumeLoginResult: (result: ResumeLoginFields, sigMessage: string, nonce: string, expire: ExpireOption) => void;
+export default completeResumeLoginResult;

package/dist/utils/socketService.d.ts

@@ -12,6 +12,11 @@ declare class SocketService {
     onAirdropResult(callback: (message: any) => void): void;
     offAirdropResult(): void;
     confirmSendTransaction(roomId: string, message: string): Socket;
+    registerMessage(roomId: string, envelope: unknown): Socket;
+    resumeRoom(roomId: string): Socket;
+    isConnected(): boolean;
+    onceConnect(callback: () => void): void;
+    offConnect(callback: () => void): void;
     onMessageReceived(type: string, callback: (message: any) => void): void;
     offMessageReceived(type: string): void;
 }

package/dist/zigap/qr.d.ts

@@ -6,7 +6,6 @@ declare class QrService {
     generatePaymentQrCode(dapp: string, network: string, address: string, amount: string, description: string | undefined, info: string | undefined, qrDomain?: string): QrType;
     generateAirdropQrCode(dapp: string, network: string[], icon: string | undefined, qrDomain?: string): QrType;
     generateSendTransactionQrCode(dapp: string, networks: 'binance' | 'ethereum' | 'v2xphere' | 'v3xphere', url: string, icon: string | undefined, qrDomain?: string): QrType;
-    private getQrDomain;
 }
 export declare const Qr: QrService;
 export {};

package/dist/zigap/scanUrl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 공용 scan-URL 빌더 — qr.ts 의 5개 generator 가 반복하던 URL 인코딩 패턴
+ * (URLSearchParams → 퍼센트 인코딩 → 도메인 결합)을 한 곳에 모은다.
+ *
+ * import 가 전혀 없는 순수 모듈이어야 한다. tests/qrScanUrl.test.mjs 가
+ * 이 파일을 relative 경로로 의존성 없이 import 해 바이트 동일성을 검증한다.
+ */
+export type ScanType = 'login' | 'provide' | 'payment' | 'airdrop' | 'sendTransaction';
+export declare function buildScanUrl(type: ScanType, params: Record<string, string>, qrDomain?: string): string;

package/package.json

@@ -1,70 +1,65 @@
 {
-    "name": "zigap-utils",
-    "version": "3.1.0-preview.1",
-    "description": "",
-    "main": "dist/index.es.js",
-    "types": "dist/index.d.ts",
-    "author": "Seoullabs",
-    "license": "ISC",
-    "homepage": "https://seoul-labs.gitbook.io/zigap-utils",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/Seoullabs-official/zigap-utils"
-    },
-    "files": [
-        "dist"
-    ],
-    "pnpm": {
-        "onlyBuiltDependencies": [
-            "esbuild"
-        ]
-    },
-    "scripts": {
-        "preinstall": "npx only-allow pnpm",
-        "dev": "vite",
-        "build": "rm -rf dist && tsx ./src/preprocessEnv.ts && vite build",
-        "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
-        "preview": "vite preview"
-    },
-    "dependencies": {
-        "@rollup/plugin-terser": "^0.4.4",
-        "dayjs": "^1.11.11",
-        "dotenv": "^16.4.5",
-        "react": "^18.2.0 || ^19.0.0",
-        "react-dom": "^18.2.0 || ^19.0.0",
-        "styled-components": "^6.1.11",
-        "tsx": "^4.16.2",
-        "tweetnacl": "^1.0.3",
-        "vite-plugin-commonjs": "^0.10.1",
-        "web3": "^4.16.0"
-    },
-    "devDependencies": {
-        "@types/crypto-js": "^4.2.2",
-        "@types/elliptic": "^6.4.18",
-        "@types/node": "^20.12.12",
-        "@types/react": "^19.0.0",
-        "@types/react-dom": "^19.0.0",
-        "@types/styled-components": "^5.1.34",
-        "@typescript-eslint/eslint-plugin": "^7.2.0",
-        "@typescript-eslint/parser": "^7.2.0",
-        "@vitejs/plugin-react": "^4.2.1",
-        "crypto-js": "^4.2.0",
-        "elliptic": "^6.5.5",
-        "eslint": "^8.57.0",
-        "eslint-config-prettier": "^9.1.0",
-        "eslint-plugin-import": "^2.29.1",
-        "eslint-plugin-jsx-a11y": "^6.8.0",
-        "eslint-plugin-react": "^7.34.1",
-        "eslint-plugin-react-hooks": "^4.6.2",
-        "eslint-plugin-react-refresh": "^0.4.6",
-        "path": "^0.12.7",
-        "prettier": "^3.2.5",
-        "qrcode.react": "^4.2.0",
-        "socket.io-client": "^4.7.5",
-        "typescript": "^5.2.2",
-        "vite": "^5.2.0",
-        "vite-plugin-css-injected-by-js": "^3.5.1",
-        "vite-plugin-dts": "^3.9.1",
-        "vite-tsconfig-paths": "^4.3.2"
-    }
-}
+  "name": "zigap-utils",
+  "version": "3.1.0-preview.4",
+  "description": "",
+  "main": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "author": "Seoullabs",
+  "license": "ISC",
+  "homepage": "https://seoul-labs.gitbook.io/zigap-utils",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Seoullabs-official/zigap-utils"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "dayjs": "^1.11.11",
+    "dotenv": "^16.4.5",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "styled-components": "^6.1.11",
+    "tsx": "^4.16.2",
+    "tweetnacl": "^1.0.3",
+    "vite-plugin-commonjs": "^0.10.1",
+    "web3": "^4.16.0"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.2",
+    "@types/elliptic": "^6.4.18",
+    "@types/node": "^20.12.12",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/styled-components": "^5.1.34",
+    "@typescript-eslint/eslint-plugin": "^7.2.0",
+    "@typescript-eslint/parser": "^7.2.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "crypto-js": "^4.2.0",
+    "elliptic": "^6.5.5",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsx-a11y": "^6.8.0",
+    "eslint-plugin-react": "^7.34.1",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "eslint-plugin-react-refresh": "^0.4.6",
+    "path": "^0.12.7",
+    "prettier": "^3.2.5",
+    "qrcode.react": "^4.2.0",
+    "socket.io-client": "^4.7.5",
+    "typescript": "^5.2.2",
+    "vite": "^5.2.0",
+    "vite-plugin-css-injected-by-js": "^3.5.1",
+    "vite-plugin-dts": "^3.9.1",
+    "vite-tsconfig-paths": "^4.3.2"
+  },
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "dev": "vite",
+    "build": "rm -rf dist && tsx ./src/preprocessEnv.ts && vite build",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview"
+  }
+}

package/dist/utils/session.d.ts

@@ -1 +0,0 @@
-export declare const clearSession: () => void;