@nexus-cross/pop 1.4.0-beta.1 → 1.4.0-beta.2

package/dist/{createSafeDrop-BSO9RQBD.d.ts → createSafeDrop-CayUX4w_.d.ts}

@@ -1,6 +1,6 @@
 /** 0x-prefixed 주소. viem Address에 의존하지 않는 도메인 표현. */
 type Address = string;
-/** 0x-prefixed hex 문자열 (서명/salt/digest/해시 등). */
+/** 0x-prefixed hex 문자열 (서명/digest/drop key/해시 등). */
 type Hex = string;
 /** 소셜 식별자 string (컨트랙트 `id`). 예: 'theo_13303'. */
 type Id = string;
@@ -28,7 +28,7 @@ interface DepositParams {
     token: Address;
     /** raw 토큰 수량 (wei-scale). BigInt 유지. */
     amount: bigint;
-    /** 비밀 문구. 미지정 시 CryptoPort.randomSecret()로 생성. (expiry는 계약이 결정.) */
+    /** 비밀 문구. 미지정 시 CryptoPort.randomSecret()로 생성. */
     secret?: Secret;
     /**
      * 수령인에게 보여줄 메시지 (최대 140 runes). 컨트랙트에는 필드가 없고
@@ -38,7 +38,8 @@ interface DepositParams {
     /** 카드 디자인 id. 목록은 `listEnvelopes()` (GET /envelopes). */
     envelopeId?: string;
 }
-interface DepositResult {
+interface UnmappedDepositResult {
+    readonly isMapped: false;
     /** 컨트랙트에 커밋된 임시 claim 지갑 주소 = 이 드롭의 키. */
     readonly claimAddress: Address;
     readonly secretHash: SecretHash;
@@ -46,7 +47,14 @@ interface DepositResult {
     readonly withdrawLink: string;
     readonly depositTxHash: Hex;
 }
+interface MappedDepositResult {
+    readonly isMapped: true;
+    readonly depositTxHash: Hex;
+}
+type DepositResult = UnmappedDepositResult | MappedDepositResult;
 interface WithdrawParams {
+    /** 링크의 sender query 값 = 온체인 sponsor. */
+    sponsor: Address;
     /** 수령 주소 — 수령인 본인이 지정. 서명에 바인딩된다. */
     recipient: Address;
     /** X OAuth 검증 후 백엔드에서 받은 임시 claim 지갑 주소. drops() 조회 키. */
@@ -60,7 +68,9 @@ interface WithdrawResult {
     readonly txHash: Hex;
 }
 interface RefundParams {
-    /** 환불할 드롭의 claimAddr. 만료 후 sponsor(msg.sender)만 호출 가능. */
+    /** 드롭 sponsor. */
+    sponsor: Address;
+    /** 환불할 드롭의 claimAddr. sponsor(msg.sender)만 호출 가능. */
     claimAddress: Address;
 }
 interface RefundResult {
@@ -71,6 +81,14 @@ interface BatchClaimParams {
     id: Id;
     /** 핸들 소유 증명용 X OAuth 토큰. 서명 발급의 전제. */
     oauth: OAuthProof;
+    /** anchor drop의 sponsor(링크 sender). */
+    sponsor: Address;
+    /** 첫 unmapped 드롭의 임시 claim 지갑 주소. */
+    claimAddress: Address;
+    /** 첫 드롭 링크 fragment의 secret. */
+    secret: Secret;
+    /** 첫 드롭의 임시 claim 개인키. */
+    claimKey: Hex;
     /**
      * 기대하는 수령 주소. 서명은 **SIWE 인증 주소**에 바인딩되므로, 다르면
      * `SIGN_FAILED`로 끊는다(다른 주소로 받으려면 그 주소로 SIWE 로그인).
@@ -81,11 +99,11 @@ interface BatchClaimParams {
     deadline?: bigint;
     /** deadline 자동 계산용 TTL(초). 기본 1800. */
     deadlineTtlSeconds?: bigint;
-    /** tx 1건이 처리할 드롭 수(서명 대상 아님 — 페이지 크기). 기본 30. */
+    /** tx 한 건에 포함할 drop key 수. 기본 30. 호출마다 새 validator 서명을 받는다. */
     maxCount?: number;
 }
 interface BatchClaimResult {
-    /** 페이지별 tx hash. 드롭이 maxCount 이하면 1건. */
+    /** 현재 batch 호출의 tx hash(호환을 위해 배열 유지). */
     readonly txHashes: readonly Hex[];
     /** 실제로 서명에 바인딩된 수령 주소. */
     readonly recipient: Address;
@@ -93,7 +111,7 @@ interface BatchClaimResult {
     readonly nonce: bigint;
     readonly deadline: bigint;
 }
-type SafeDropErrorCode = 'MISSING_SENDER' | 'MISSING_RECIPIENT' | 'MISSING_SECRET' | 'MISSING_CLAIM_KEY' | 'MISSING_CLAIM_ADDRESS' | 'INVALID_AMOUNT' | 'INVALID_TOKEN' | 'DROP_NOT_FOUND' | 'SECRET_MISMATCH' | 'SIGN_FAILED' | 'CHAIN_ERROR' | 'API_ERROR' | 'INVALID_PARAM' | 'RATE_LIMITED' | 'INVALID_OAUTH_TOKEN' | 'UNAUTHORIZED' | 'WALLET_NOT_FOUND' | 'SEND_BLOCKED' | 'ENVELOPE_NOT_FOUND' | 'PENDING_LIMIT_EXCEEDED' | 'X_CONNECTION_NOT_FOUND';
+type SafeDropErrorCode = 'MISSING_SENDER' | 'MISSING_RECIPIENT' | 'MISSING_SECRET' | 'MISSING_CLAIM_KEY' | 'MISSING_CLAIM_ADDRESS' | 'INVALID_AMOUNT' | 'INVALID_TOKEN' | 'DROP_NOT_FOUND' | 'SECRET_MISMATCH' | 'SIGN_FAILED' | 'CHAIN_ERROR' | 'API_ERROR' | 'INVALID_PARAM' | 'RATE_LIMITED' | 'INVALID_OAUTH_TOKEN' | 'UNAUTHORIZED' | 'WALLET_NOT_FOUND' | 'SEND_BLOCKED' | 'ENVELOPE_NOT_FOUND' | 'PENDING_LIMIT_EXCEEDED' | 'IDENTIFIER_NOT_MAPPED' | 'X_CONNECTION_NOT_FOUND';
 declare class SafeDropError extends Error {
     readonly code: SafeDropErrorCode;
     readonly details?: Record<string, unknown>;
@@ -108,6 +126,9 @@ interface XConnection {
     readonly profileImageUrl: string;
     /** SIWE 인증 주소. 본문으로 고를 수 없다. */
     readonly walletAddress: Address;
+    readonly revealYou: boolean;
+    readonly onchainMapped: boolean;
+    readonly mappedRecipient: Address | null;
 }
 /** 드롭을 보낸 sponsor. X 연결이 없으면 handle/displayName/profileImageUrl은 빈 문자열. */
 interface DropSender {
@@ -118,6 +139,10 @@ interface DropSender {
 }
 /** GET /drops의 개별 항목. claimAddress로 개별 수령(withdraw)을 진행한다. */
 interface PendingDrop {
+    /** 백엔드 drop id. feedback 등록에 사용한다. */
+    readonly id: number;
+    /** 현재 컨트랙트의 bytes32 drop key. */
+    readonly dropKey: Hex;
     readonly claimAddress: Address;
     readonly token: Address;
     /** raw 토큰 수량 (wei-scale). */
@@ -138,6 +163,8 @@ interface DropInbox {
     readonly totalAmount: bigint;
     /** 첫 수령은 개별 claim만 허용 — 일괄 수령 CTA 게이트. */
     readonly hasClaimedBefore: boolean;
+    readonly mappedRecipient: Address | null;
+    readonly pendingChangeTo: Address | null;
 }
 /** GET /envelopes — 카드 디자인. 공개 엔드포인트. */
 interface Envelope {
@@ -147,30 +174,50 @@ interface Envelope {
     readonly badge: string;
     readonly sortOrder: number;
 }
-/** GET /leaderboards — identifier별 pending 잔액 상위(최대 10). 공개 엔드포인트. */
+/** GET /leaderboards — identifier별 pending 잔액. */
 interface LeaderboardEntry {
     readonly identifier: string;
     /** 수령 가능(pending) 합계 (wei-scale). */
     readonly balance: bigint;
     /** 최근 Deposited 금액 (wei-scale). */
     readonly lastDepositAmount: bigint;
+    readonly rank: number;
+    readonly previousRank: number | null;
+    readonly profileImageUrl: string;
+}
+interface LeaderboardPage {
+    readonly items: readonly LeaderboardEntry[];
+    readonly page: number;
+    readonly pageSize: number;
+    readonly total: number;
+}
+interface MyLeaderboardEntry extends Omit<LeaderboardEntry, 'rank'> {
+    readonly rank: number | null;
+}
+type HistoryType = 'sent' | 'received';
+interface HistoryParty {
+    readonly address: Address;
+    readonly handle: string;
+    readonly displayName: string;
+    readonly profileImageUrl: string;
 }
-type PopEventName = 'Deposited' | 'Withdrawn' | 'Refunded' | 'BatchWithdrawn';
-/** GET /histories 항목. 이벤트가 담지 않는 주소는 null. */
+/** GET /histories의 drop 중심 항목. */
 interface HistoryEntry {
-    readonly eventName: PopEventName | (string & {});
-    readonly txHash: Hex;
-    readonly blockNumber: number;
-    readonly logIndex: number;
-    readonly contractAddress: Address;
-    readonly fromAddress: Address | null;
-    readonly toAddress: Address | null;
-    readonly tempTo: Address | null;
-    readonly identifier: string;
-    /** wei-scale. */
+    readonly id: number;
+    readonly type: HistoryType;
+    readonly status: string;
+    readonly token: Address;
     readonly amount: bigint;
-    readonly createdAt: string;
-    readonly payload?: Record<string, unknown>;
+    readonly claimAddress: Address;
+    readonly depositTxHash: Hex;
+    readonly depositedAt: string;
+    readonly resolvedTxHash: Hex | null;
+    readonly resolvedAt: string | null;
+    readonly message: string;
+    readonly feedback: string | null;
+    readonly envelopeId: string;
+    readonly sender: HistoryParty;
+    readonly receiver: HistoryParty;
 }
 interface HistoryPage {
     readonly items: readonly HistoryEntry[];
@@ -182,8 +229,7 @@ interface HistoryPage {
 /**
  * POST /batch-claim-signature 결과 — EIP-712 ValidatorClaim 서명.
  * recipient는 항상 Bearer 토큰의 SIWE 주소다(본문으로 못 고른다).
- * 같은 id의 live 드롭이 모두 빠질 때까지 페이지네이션된 온체인 호출에
- * **재사용**한다 — 페이지마다 다시 발급받지 않는다.
+ * 서명은 성공한 온체인 호출 1건마다 nonce와 함께 소비된다.
  */
 interface BatchClaimSignature {
     readonly id: Id;
@@ -192,6 +238,15 @@ interface BatchClaimSignature {
     readonly deadline: bigint;
     readonly signature: Hex;
 }
+interface RecipientSignature {
+    readonly id: Id;
+    readonly nonce: bigint;
+    readonly deadline: bigint;
+    readonly signature: Hex;
+}
+interface RecipientChangeSignature extends RecipientSignature {
+    readonly newRecipient: Address;
+}
 
 /**
  * 순수 계산이 아니라 외부 구현(해시 라이브러리/CSPRNG)이 필요한 암호 연산.
@@ -229,10 +284,6 @@ interface SafeDropApiPort {
     createClaimWallet(params: {
         sender: Address;
         recipient: SocialIdentifier;
-        /** 수령인에게 보여줄 메시지 (≤140 runes, 백엔드 저장 전용). */
-        message?: string;
-        /** 카드 디자인 id (GET /envelopes). */
-        envelopeId?: string;
     }): Promise<{
         claimAddress: Address;
         id: Id;
@@ -246,13 +297,8 @@ interface SafeDropApiPort {
     }): Promise<void>;
     /**
      * Withdraw: X OAuth 검증 후 복호화된 임시 claim 개인키 반환 (point of return).
-     * dropId가 아니라 (sender_address + OAuth 토큰 소유자의 identifier) 조합으로
-     * 해당하는 최신 pending 지갑 키를 찾는다 — one-pop-api /wallets/private-key.
-     *
-     * ⚠️ 한 (sender, identifier)에 pending 드롭이 여러 개 있을 수 있다(백엔드가
-     * 중복 제한을 풀었다). 이 엔드포인트는 그중 **최신 1건**만 돌려주고 특정
-     * claimAddress를 고르는 파라미터가 없다 — 같은 sender가 보낸 여러 드롭은
-     * 링크마다 순차로 수령해야 한다. 전체 목록은 `listDrops()`로 본다.
+     * claimAddress로 특정 pending 지갑을 선택하고 OAuth 토큰으로 handle 소유권을
+     * 증명한다 — one-pop-api /wallets/private-key.
      */
     retrieveClaimKey(params: {
         claimAddress: Address;
@@ -273,13 +319,20 @@ interface SafeDropApiPort {
     listEnvelopes?(params?: {
         locale?: string;
     }): Promise<readonly Envelope[]>;
-    /** GET /leaderboards — 토큰별 pending 잔액 상위. 공개(인증 불필요). */
+    /** GET /leaderboards — 토큰별 pending 잔액. 공개(인증 불필요). */
     getLeaderboard?(params: {
         token: Address;
-    }): Promise<readonly LeaderboardEntry[]>;
+        page?: number;
+        pageSize?: number;
+        identifier?: string;
+    }): Promise<LeaderboardPage>;
+    getMyLeaderboardEntry?(params: {
+        token: Address;
+    }): Promise<MyLeaderboardEntry>;
     /** GET /histories — 내가 sender이거나 최종 수령인인 온체인 이벤트. Bearer JWT. */
-    listHistories?(params?: {
-        event?: PopEventName;
+    listHistories?(params: {
+        type: HistoryType;
+        token?: Address;
         /** 1-based (기본 1). */
         page?: number;
         /** 기본 20, 최대 100. */
@@ -293,6 +346,25 @@ interface SafeDropApiPort {
     }): Promise<XConnection>;
     /** DELETE /x-connections — 연결 해제. 이미 없으면 조용히 성공(idempotent). */
     disconnectX?(): Promise<void>;
+    submitFeedback?(params: {
+        dropId: number;
+        message: string;
+    }): Promise<string>;
+    setRevealYou?(params: {
+        revealYou: boolean;
+    }): Promise<boolean>;
+    requestRecipientChangeSignature?(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientChangeSignature>;
+    requestRecipientResetSignature?(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientSignature>;
     /**
      * POST /batch-claim-signature — 일괄 수령용 EIP-712 ValidatorClaim 서명.
      * nonce/deadline은 호출자가 정한다. nonce는 컨트랙트
@@ -308,25 +380,6 @@ interface SafeDropApiPort {
     }): Promise<BatchClaimSignature>;
 }
 
-/**
- * drops(claimAddr) 결과 매핑.
- *
- * ⚠️ 배포본마다 `drops`의 반환 필드 수가 다르다(permit 배포본은 5개 —
- * sponsor/amount/secretHash/salt/id). 그래서 `token`·`expiry`는 **optional**이다:
- * - `token` — 5필드 배포본에서는 에스크로의 `token()`으로 채운다(단일 토큰 고정).
- * - `expiry` — 5필드 배포본은 노출하지 않는다 → `undefined`. 만료 판정에 쓰기 전에
- *   존재 여부를 확인해야 한다(없다고 만료가 아니라, 알 수 없다는 뜻).
- */
-interface DropState {
-    claimAddress: Address;
-    sponsor: Address;
-    token?: Address;
-    amount: bigint;
-    expiry?: number;
-    secretHash: SecretHash;
-    salt: Hex;
-    id: Id;
-}
 /** Current ONEpop drop record, keyed by bytes32 rather than claim wallet. */
 interface OnePopDrop {
     dropKey: Hex;
@@ -337,6 +390,10 @@ interface OnePopDrop {
     secretHash: SecretHash;
     id: Id;
 }
+interface DropState extends OnePopDrop {
+    /** ONEpop escrow is single-token; token() is contract-wide. */
+    token: Address;
+}
 /**
  * SafeDrop 컨트랙트 상호작용. 어댑터는 자신의 컨트랙트 주소를 알고 있으므로
  * approve의 spender 등은 받지 않는다. 쓰기는 receipt 확인 후 tx hash 반환.
@@ -345,7 +402,7 @@ interface OnePopDrop {
  */
 interface SafeDropChainPort {
     getDropByKey(dropKey: Hex): Promise<OnePopDrop | null>;
-    getDropKeyByClaimAddress(claimAddress: Address, sponsor?: Address): Promise<Hex | null>;
+    getDropKeyByClaimAddress(claimAddress: Address, sponsor: Address): Promise<Hex | null>;
     getClaimedRecipient(params: {
         id: Id;
     }): Promise<Address>;
@@ -358,36 +415,19 @@ interface SafeDropChainPort {
     getPendingDropsBySponsor(params: {
         sponsor: Address;
     }): Promise<readonly OnePopDrop[]>;
-    /** drops(claimAddr). 없으면 null. */
-    getDrop(claimAddress: Address): Promise<DropState | null>;
-    /** claimDigest(recipient, id, salt) — 서명 대상 bytes32. */
+    /** activeDropOf(claimAddr) → drops(dropKey). 없으면 null. */
+    getDrop(claimAddress: Address, sponsor: Address): Promise<DropState | null>;
+    /** claimDigest(recipient, id, dropKey) — 서명 대상 bytes32. */
     getClaimDigest(params: {
         recipient: Address;
         id: Id;
-        salt: Hex;
-    }): Promise<Hex>;
-    /** ERC20 approve (spender = SafeDrop 컨트랙트). 연결된 지갑이 서명. */
-    approve(params: {
-        token: Address;
-        amount: bigint;
+        dropKey: Hex;
     }): Promise<Hex>;
-    /** deposit(claimAddr, token, amount, id, secretHash). sponsor = msg.sender. */
-    deposit(params: {
-        claimAddress: Address;
-        token: Address;
-        amount: bigint;
-        id: Id;
-        secretHash: SecretHash;
-    }): Promise<{
-        txHash: Hex;
-    }>;
     /**
-     * EIP-2612 permit 예치 — approve tx 없이 서명 1회 + tx 1회로 끝낸다.
-     * permit 예치를 지원하는 배포본에서만 구현되는 optional 경로: 존재하면
-     * DepositUseCase가 approve+deposit 대신 이걸 쓴다.
+     * EIP-2612 permit 예치 — 현재 ONEpop deposit의 유일한 형태다.
      * 서명(typed data)·deadline·v/r/s는 전부 어댑터 내부 관심사다.
      */
-    depositWithPermit?(params: {
+    depositWithPermit(params: {
         claimAddress: Address;
         token: Address;
         amount: bigint;
@@ -405,25 +445,13 @@ interface SafeDropChainPort {
     }): Promise<{
         txHash: Hex;
     }>;
-    /**
-     * withdraw(recipient, id, salt, signature, secret). claimAddr는 서명 recover로
-     * 도출. tx는 claimKey 임시 지갑이 직접 전송 — estimateGas 없이 고정 gas +
-     * dynamic fee(type-2)로 보내 컨트랙트 gas-abstraction 대납을 받는다.
-     */
-    withdraw(params: {
-        claimKey: Hex;
-        recipient: Address;
-        id: Id;
-        salt: Hex;
-        signature: Hex;
-        secret: Secret;
-    }): Promise<Hex>;
     withdrawUnmapped(params: {
         claimKey: Hex;
         recipient: Address;
         id: Id;
         dropKey: Hex;
         secret: Secret;
+        signature?: Hex;
         onSubmitted?: (txHash: Hex) => void | Promise<void>;
     }): Promise<Hex>;
     withdrawMapped(params: {
@@ -433,9 +461,19 @@ interface SafeDropChainPort {
     batchWithdrawMapped(params: {
         count: number;
     }): Promise<Hex>;
-    /** refund(claimAddr). 만료 후 sponsor(msg.sender)만. */
-    refund(params: {
-        claimAddress: Address;
+    batchWithdrawMappedByKeys(params: {
+        dropKeys: readonly Hex[];
+    }): Promise<Hex>;
+    withdrawUnmappedBatchByKeys(params: {
+        claimKey: Hex;
+        recipient: Address;
+        id: Id;
+        anchorDropKey: Hex;
+        secret: Secret;
+        nonce: bigint;
+        deadline: bigint;
+        dropKeys: readonly Hex[];
+        validatorSignature: Hex;
     }): Promise<Hex>;
     refundByKey(params: {
         dropKey: Hex;
@@ -443,6 +481,22 @@ interface SafeDropChainPort {
     getChangeNonce(params: {
         id: Id;
     }): Promise<bigint>;
+    getPendingRecipientChange(params: {
+        id: Id;
+    }): Promise<Address>;
+    requestRecipientChange(params: {
+        id: Id;
+        newRecipient: Address;
+    }): Promise<Hex>;
+    completeRecipientChange(params: {
+        id: Id;
+        nonce: bigint;
+        deadline: bigint;
+        signature: Hex;
+    }): Promise<Hex>;
+    cancelRecipientChange(params: {
+        id: Id;
+    }): Promise<Hex>;
     resetRecipient(params: {
         id: Id;
         nonce: bigint;
@@ -465,23 +519,6 @@ interface SafeDropChainPort {
     }): Promise<Hex>;
     /** validator() — 서명자여야 하는 주소. 백엔드 서명 검증의 기준값. */
     getValidator?(): Promise<Address>;
-    /** liveDropCountById(id) — 남은 수령 대기 건수(페이지네이션 종료 조건). */
-    getLiveDropCount?(params: {
-        id: Id;
-    }): Promise<bigint>;
-    /**
-     * withdrawByValidator(recipient, id, nonce, deadline, maxCount, signature).
-     * tx는 **수령인 본인 지갑**이 보낸다(컨트랙트가 msg.sender와 서명의 recipient를
-     * 대조). `maxCount`는 서명 대상이 아니라 페이지 크기다 — 같은 서명을 재사용한다.
-     */
-    withdrawByValidator?(params: {
-        recipient: Address;
-        id: Id;
-        nonce: bigint;
-        deadline: bigint;
-        maxCount: number;
-        signature: Hex;
-    }): Promise<Hex>;
 }
 
 /**
@@ -503,7 +540,8 @@ interface ClaimSignerPort {
  *     { claimBaseUrl },
  *     { api, chain, signer, crypto },
  *   );
- *   const { withdrawLink, claimAddress } = await safeDrop.deposit({ ... });
+ *   const result = await safeDrop.deposit({ ... });
+ *   if (!result.isMapped) sendLink(result.withdrawLink);
  *
  * viem/HTTP 어댑터를 자동 조립하려면 `@nexus-cross/pop/adapters`의
  * createSafeDropClient를 사용한다. (도메인/컨트랙트 주소는 chain 어댑터가 안다.)
@@ -536,10 +574,10 @@ interface SafeDrop {
     }>;
     withdraw(params: WithdrawParams): Promise<WithdrawResult>;
     refund(params: RefundParams): Promise<RefundResult>;
-    /** 온체인 드롭 상태 (drops(claimAddr)). 없으면 null. */
-    getDrop(claimAddress: Address): Promise<DropState | null>;
+    /** activeDropOf(claimAddr)로 조회한 현재 온체인 드롭. */
+    getDrop(claimAddress: Address, sponsor: Address): Promise<DropState | null>;
     getDropByKey(dropKey: Hex): Promise<OnePopDrop | null>;
-    getDropKeyByClaimAddress(claimAddress: Address, sponsor?: Address): Promise<Hex | null>;
+    getDropKeyByClaimAddress(claimAddress: Address, sponsor: Address): Promise<Hex | null>;
     getClaimedRecipient(id: Id): Promise<Address>;
     getPendingDropsById(id: Id): Promise<readonly OnePopDrop[]>;
     getPendingDropsByRecipient(recipient: Address): Promise<readonly OnePopDrop[]>;
@@ -547,8 +585,13 @@ interface SafeDrop {
     withdrawUnmapped(params: Parameters<SafeDropChainPort['withdrawUnmapped']>[0]): Promise<Hex>;
     withdrawMapped(params: Parameters<SafeDropChainPort['withdrawMapped']>[0]): Promise<Hex>;
     batchWithdrawMapped(count: number): Promise<Hex>;
+    batchWithdrawMappedByKeys(dropKeys: readonly Hex[]): Promise<Hex>;
     refundByKey(dropKey: Hex): Promise<Hex>;
     getChangeNonce(id: Id): Promise<bigint>;
+    getPendingRecipientChange(id: Id): Promise<Address>;
+    requestRecipientChange(id: Id, newRecipient: Address): Promise<Hex>;
+    completeRecipientChange(params: Parameters<SafeDropChainPort['completeRecipientChange']>[0]): Promise<Hex>;
+    cancelRecipientChange(id: Id): Promise<Hex>;
     resetRecipient(params: Parameters<SafeDropChainPort['resetRecipient']>[0]): Promise<Hex>;
     /** 내게 온 수령 대기 목록. Bearer JWT + 활성 X 연결 필요. */
     listDrops(params?: {
@@ -561,10 +604,17 @@ interface SafeDrop {
     /** 토큰별 pending 잔액 상위 (공개). */
     getLeaderboard(params: {
         token: Address;
-    }): Promise<readonly LeaderboardEntry[]>;
-    /** 내 온체인 이벤트 히스토리. Bearer JWT 필요. */
-    listHistories(params?: {
-        event?: PopEventName;
+        page?: number;
+        pageSize?: number;
+        identifier?: string;
+    }): Promise<LeaderboardPage>;
+    getMyLeaderboardEntry(params: {
+        token: Address;
+    }): Promise<MyLeaderboardEntry>;
+    /** sent/received 드롭 히스토리. Bearer JWT 필요. */
+    listHistories(params: {
+        type: HistoryType;
+        token?: Address;
         page?: number;
         pageSize?: number;
     }): Promise<HistoryPage>;
@@ -576,9 +626,26 @@ interface SafeDrop {
     }): Promise<XConnection>;
     /** X 연결 해제 (idempotent). */
     disconnectX(): Promise<void>;
+    submitFeedback(params: {
+        dropId: number;
+        message: string;
+    }): Promise<string>;
+    setRevealYou(revealYou: boolean): Promise<boolean>;
+    requestRecipientChangeSignature(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientChangeSignature>;
+    requestRecipientResetSignature(params: {
+        id: Id;
+        oauth: OAuthProof;
+        nonce: bigint;
+        deadline: bigint;
+    }): Promise<RecipientSignature>;
     /**
-     * 일괄 수령 — nonce 조회 → 백엔드 서명 → **가스 전 서명 검증** → 전량 회수까지
-     * 한 번에. tx는 연결된 수령인 지갑이 보낸다(secret 불필요).
+     * anchor drop의 secret/claim key와 validator 서명을 함께 사용해 현재 pending key를
+     * 한 번에 수령한다.
      */
     batchClaim(params: BatchClaimParams): Promise<BatchClaimResult>;
     /**
@@ -594,4 +661,4 @@ interface SafeDrop {
 }
 declare function createSafeDrop(config: SafeDropConfig, deps: SafeDropDeps): SafeDrop;
 
-export { type Address as A, type BatchClaimParams as B, type CryptoPort as C, type DepositParams as D, type Envelope as E, type Hex as H, type Id as I, type LeaderboardEntry as L, type OAuthProof as O, type PendingDrop as P, type RefundParams as R, type SafeDropChainPort as S, type WithdrawParams as W, type XConnection as X, type SafeDropApiPort as a, type DepositResult as b, type BatchClaimResult as c, type ClaimSignerPort as d, type WithdrawResult as e, type RefundResult as f, type Secret as g, type BatchClaimSignature as h, type DropInbox as i, type DropSender as j, type DropState as k, type HistoryEntry as l, type HistoryPage as m, type OnePopDrop as n, type PopEventName as o, type SafeDrop as p, type SafeDropConfig as q, type SafeDropDeps as r, SafeDropError as s, type SafeDropErrorCode as t, type SecretHash as u, type SocialIdentifier as v, type SocialProvider as w, createSafeDrop as x };
+export { type Address as A, type BatchClaimParams as B, type CryptoPort as C, type DepositParams as D, type Envelope as E, type SocialIdentifier as F, type SocialProvider as G, type Hex as H, type Id as I, createSafeDrop as J, type LeaderboardEntry as L, type MappedDepositResult as M, type OAuthProof as O, type PendingDrop as P, type RefundParams as R, type SafeDropChainPort as S, type UnmappedDepositResult as U, type WithdrawParams as W, type XConnection as X, type SafeDropApiPort as a, type DepositResult as b, type BatchClaimResult as c, type ClaimSignerPort as d, type WithdrawResult as e, type RefundResult as f, type Secret as g, type BatchClaimSignature as h, type DropInbox as i, type DropSender as j, type DropState as k, type HistoryEntry as l, type HistoryPage as m, type HistoryParty as n, type HistoryType as o, type LeaderboardPage as p, type MyLeaderboardEntry as q, type OnePopDrop as r, type RecipientChangeSignature as s, type RecipientSignature as t, type SafeDrop as u, type SafeDropConfig as v, type SafeDropDeps as w, SafeDropError as x, type SafeDropErrorCode as y, type SecretHash as z };

package/dist/index.d.ts

@@ -1,12 +1,10 @@
-import { S as SafeDropChainPort, a as SafeDropApiPort, C as CryptoPort, D as DepositParams, b as DepositResult, B as BatchClaimParams, c as BatchClaimResult, d as ClaimSignerPort, W as WithdrawParams, e as WithdrawResult, R as RefundParams, f as RefundResult, A as Address, g as Secret } from './createSafeDrop-BSO9RQBD.js';
-export { h as BatchClaimSignature, i as DropInbox, j as DropSender, k as DropState, E as Envelope, H as Hex, l as HistoryEntry, m as HistoryPage, I as Id, L as LeaderboardEntry, O as OAuthProof, n as OnePopDrop, P as PendingDrop, o as PopEventName, p as SafeDrop, q as SafeDropConfig, r as SafeDropDeps, s as SafeDropError, t as SafeDropErrorCode, u as SecretHash, v as SocialIdentifier, w as SocialProvider, X as XConnection, x as createSafeDrop } from './createSafeDrop-BSO9RQBD.js';
+import { S as SafeDropChainPort, a as SafeDropApiPort, C as CryptoPort, D as DepositParams, b as DepositResult, B as BatchClaimParams, c as BatchClaimResult, d as ClaimSignerPort, W as WithdrawParams, e as WithdrawResult, R as RefundParams, f as RefundResult, A as Address, g as Secret } from './createSafeDrop-CayUX4w_.js';
+export { h as BatchClaimSignature, i as DropInbox, j as DropSender, k as DropState, E as Envelope, H as Hex, l as HistoryEntry, m as HistoryPage, n as HistoryParty, o as HistoryType, I as Id, L as LeaderboardEntry, p as LeaderboardPage, M as MappedDepositResult, q as MyLeaderboardEntry, O as OAuthProof, r as OnePopDrop, P as PendingDrop, s as RecipientChangeSignature, t as RecipientSignature, u as SafeDrop, v as SafeDropConfig, w as SafeDropDeps, x as SafeDropError, y as SafeDropErrorCode, z as SecretHash, F as SocialIdentifier, G as SocialProvider, U as UnmappedDepositResult, X as XConnection, J as createSafeDrop } from './createSafeDrop-CayUX4w_.js';
 export { X as XAuthPort, a as XTokenResult } from './XAuthPort-BNJePosj.js';
 
 /**
- * 예치: 임시 claim 지갑 생성 → secretHash 커밋 → (permit | approve) → deposit →
- * 수령 링크 생성. chain 어댑터가 depositWithPermit을 구현하면 approve tx를 생략한다.
+ * 예치: 임시 claim 지갑 생성 → secretHash 커밋 → permit deposit → 수령 링크 생성.
  * secret은 링크 fragment에만 담기고 어떤 포트로도 전송되지 않는다.
- * (expiry/salt는 컨트랙트가 결정.)
  */
 declare class DepositUseCase {
     private readonly chain;
@@ -18,55 +16,22 @@ declare class DepositUseCase {
     /** 수령 링크 base URL. */
     claimBaseUrl: string);
     execute(params: DepositParams): Promise<DepositResult>;
-    /** permit 미지원 배포본: ERC20 approve tx → deposit tx. */
-    private approveThenDeposit;
 }
 
-/**
- * 일괄 수령: 한 id에 쌓인 드롭 전부를 validator 서명 1건으로 회수한다.
- * 개별 수령과 달리 secret이 필요 없다 — 게이트는 validator 서명이다.
- *
- * 흐름 (온체인 계약이 정한 순서 그대로):
- *   1. nonce  = validatorNonceById(keccak256(utf8(id)))   ← id를 **해시**로 키잉
- *   2. 백엔드에 (id, nonce, deadline) + X 토큰으로 서명 요청
- *      → recipient는 **응답값**을 쓴다(SIWE 주소에 바인딩되어 서명됨)
- *   3. digest = validatorClaimDigest(recipient, id, nonce, deadline)  ← 온체인 값
- *      recover(digest, signature) == validator() 인지 **가스 전에** 검증
- *   4. liveDropCountById(id)이 0이 될 때까지 withdrawByValidator(..., maxCount, sig)
- *      반복. maxCount는 서명 대상이 아니라 페이지 크기 → **서명 재사용**.
- *
- * 3번이 이 usecase의 존재 이유다: 백엔드가 다른 domain/type/nonce/recipient로
- * 서명하면 온체인에서는 `ECDSAInvalidSignature`로만 드러나 원인을 못 찾는다.
- */
+/** Current ONEpop batch flow: one anchor claim proves the secret, validator authorizes one batch call. */
 declare class BatchClaimUseCase {
     private readonly chain;
     private readonly api;
     private readonly crypto;
-    /** 테스트 주입용 시계. 기본 Date.now(). */
     private readonly now;
-    constructor(chain: SafeDropChainPort, api: SafeDropApiPort, crypto: CryptoPort, 
-    /** 테스트 주입용 시계. 기본 Date.now(). */
-    now?: () => number);
+    constructor(chain: SafeDropChainPort, api: SafeDropApiPort, crypto: CryptoPort, now?: () => number);
     execute(params: BatchClaimParams): Promise<BatchClaimResult>;
-    /**
-     * 일괄 수령의 목적지가 **개별 수령으로 이미 확정된 주소**인지 온체인에서 확인한다.
-     * `claimedRecipientOf(id)`가 zero면 이 id는 아직 개별 수령을 하지 않은 상태 —
-     * API의 `has_claimed_before` 게이트와 같은 조건이다(첫 수령은 개별로).
-     * 어댑터가 이 read를 지원하지 않으면 검사를 생략한다(플로우는 유지).
-     */
-    private assertRecipientPinnedOnChain;
-    /**
-     * 사전 검증. `recoverAddress`가 없는 CryptoPort면 조용히 건너뛴다 — 최종 관문은
-     * 어차피 컨트랙트이고, 이 검사는 "가스 쓰기 전에 원인을 알려주는" 용도다.
-     */
     private assertSignedByValidator;
-    private liveCount;
 }
 
 /**
- * 수령: drops(claimAddr)에서 id·salt 조회 → claimDigest 읽기 → 임시 키로 digest
- * raw 서명 → withdraw tx(임시 지갑이 직접 전송, 가스 대납). id/salt는 온체인
- * 드롭 값을 그대로 써서 IdMismatch/SaltMismatch를 원천 차단한다.
+ * 수령: activeDropOf(claimAddr)로 dropKey를 찾고 온체인 id로 claimDigest를 서명한 뒤
+ * withdrawUnmapped를 호출한다.
  */
 declare class WithdrawUseCase {
     private readonly chain;
@@ -75,7 +40,7 @@ declare class WithdrawUseCase {
     execute(params: WithdrawParams): Promise<WithdrawResult>;
 }
 
-/** 환불: 만료 후 sponsor(msg.sender)만 호출 가능. 만료/권한 검증은 컨트랙트가 최종 강제. */
+/** claim address를 현재 drop key로 해석해 sponsor 환불을 실행한다. */
 declare class RefundUseCase {
     private readonly chain;
     constructor(chain: SafeDropChainPort);

package/dist/index.js

@@ -1 +1 @@
-import{a as r,b as e,c as o,d as t,e as p,f as a,g as s,h as i,i as f,j as m,k as n}from"./chunk-RS7SBR7A.js";export{i as BatchClaimUseCase,s as DepositUseCase,m as RefundUseCase,r as SafeDropError,f as WithdrawUseCase,a as buildComposeUrl,p as buildDmText,o as buildWithdrawLink,n as createSafeDrop,e as normalizeHandle,t as parseWithdrawLink};
+import{a as r,b as e,c as o,d as t,e as p,f as a,g as s,h as i,i as f,j as n,k as m}from"./chunk-SE2HF5WH.js";export{i as BatchClaimUseCase,s as DepositUseCase,n as RefundUseCase,r as SafeDropError,f as WithdrawUseCase,a as buildComposeUrl,p as buildDmText,o as buildWithdrawLink,m as createSafeDrop,e as normalizeHandle,t as parseWithdrawLink};

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { p as SafeDrop } from '../createSafeDrop-BSO9RQBD.js';
+import { u as SafeDrop } from '../createSafeDrop-CayUX4w_.js';
 
 interface SafeDropProviderProps {
     client: SafeDrop;