@nexus-cross/pop 1.4.0-beta.6 → 2.4.0-beta.2

package/AGENTS.md

@@ -25,12 +25,19 @@ link's `#fragment` — the backend never sees it, so backend + link are each ins
 | Import | Contents | Requires |
 |---|---|---|
 | `@nexus-cross/pop` | domain types, use cases, pure utils, `createSafeDrop` | nothing |
-| `@nexus-cross/pop/adapters` | `createSafeDropClient`, viem/HTTP adapters, X OAuth, cross-auth | `viem`, `fetch` |
+| `@nexus-cross/pop/api` | HTTP clients only — `HttpSafeDropApiAdapter`, `CrossAuthClient`, X OAuth PKCE, base-URL helpers | `fetch` |
+| `@nexus-cross/pop/adapters` | everything in `/api` **plus** viem chain/signing adapters and `createSafeDropClient` | `viem`, `fetch` |
 | `@nexus-cross/pop/react` | `SafeDropProvider`, `useSafeDrop` | `react` |
 
 Default for an app: `createSafeDropClient` (adapters) + `SafeDropProvider` (react).
 `viem` and `react` are **optional peers** — install only what the chosen entry point needs.
 
+**Read-only consumer? Use `/api`, not `/adapters`.** The `/adapters` barrel
+statically imports the viem chain/signing adapters, so importing it just to call
+`/drops` or `/histories` drags `viem` into your bundle. `/api` is the fetch-only
+slice and needs no viem. Reach for `/adapters` when you actually sign or send
+transactions (deposit / withdraw / refund).
+
 ```sh
 pnpm add @nexus-cross/pop viem        # + react if using ./react
 ```

package/README.md

@@ -17,11 +17,19 @@ npm i @nexus-cross/pop viem   # react는 선택
 | import | 내용 | 의존 |
 |---|---|---|
 | `@nexus-cross/pop` | 도메인 타입, usecase, 순수 유틸, `createSafeDrop` facade | 없음 |
-| `@nexus-cross/pop/adapters` | viem/HTTP 어댑터, `createSafeDropClient`, X OAuth, cross-auth | viem, fetch |
+| `@nexus-cross/pop/api` | HTTP 클라이언트만 — `HttpSafeDropApiAdapter`, `CrossAuthClient`, X OAuth PKCE, base URL 헬퍼 | fetch |
+| `@nexus-cross/pop/adapters` | 위 전부 + viem 체인/서명 어댑터, `createSafeDropClient` | viem, fetch |
 | `@nexus-cross/pop/react` | `SafeDropProvider`, `useSafeDrop` | react |
 
 대부분의 앱은 **`createSafeDropClient`(adapters) + `SafeDropProvider`(react)** 만 쓰면 된다.
 
+**조회만 하는 소비자는 `/api` 를 쓴다.** `/adapters` 배럴은 viem 체인/서명
+어댑터를 static import 하므로, `/drops`·`/histories` 같은 읽기 전용 호출만
+필요한데 그 배럴을 쓰면 viem 이 딸려온다. `/api` 는 fetch 만 쓰는 부분을 떼어낸
+진입점이라 **viem 무의존**이다 (`@nexus-cross/connect-kit-react` 가 ONEpop
+summary 를 조회할 때 쓰는 경로 — 그 패키지는 의존성 정책상 viem 을 직접 쓸 수
+없다). deposit/withdraw/refund 처럼 서명·체인 호출이 필요하면 `/adapters`.
+
 ## 개념
 
 - **claimAddress** — 드롭당 임시 지갑 주소. `activeDropOf`로 현재 drop key를 찾는 데 사용.

package/dist/{createSafeDrop-DtWLupoE.d.ts → SafeDropApiPort-BLewfSaK.d.ts}

@@ -261,27 +261,6 @@ interface RecipientChangeSignature extends RecipientSignature {
     readonly newRecipient: Address;
 }
 
-/**
- * 순수 계산이 아니라 외부 구현(해시 라이브러리/CSPRNG)이 필요한 암호 연산.
- * core는 keccak/난수 구현을 갖지 않으므로 Port로 분리한다.
- * 어댑터가 viem `keccak256`/`crypto.getRandomValues` 등으로 구현.
- */
-interface CryptoPort {
-    /** utf8(secret) → keccak256 → 0x-prefixed hex. 컨트랙트 secretHash와 일치해야 함. */
-    keccak256(input: Secret): SecretHash;
-    /** CSPRNG 기반 고엔트로피 secret 문구 생성. */
-    randomSecret(): Secret;
-    /**
-     * digest + 서명 → 서명자 주소. 백엔드 validator 서명을 **가스 쓰기 전에** 검증하는
-     * 용도(최종 관문은 여전히 컨트랙트다). optional — 미구현 어댑터에서는 사전 검증만
-     * 생략되고 플로우는 그대로 동작한다.
-     */
-    recoverAddress?(params: {
-        digest: Hex;
-        signature: Hex;
-    }): Promise<Address>;
-}
-
 /**
  * off-chain 백엔드(one-pop-api) 계약. 임시 claim 키 보관/전달, X 연결, 조회
  * 엔드포인트, validator 서명을 담당한다. 이 포트만으로는 자금을 옮길 수 없다
@@ -401,292 +380,4 @@ interface SafeDropApiPort {
     }): Promise<BatchClaimSignature>;
 }
 
-/** Current ONEpop drop record, keyed by bytes32 rather than claim wallet. */
-interface OnePopDrop {
-    dropKey: Hex;
-    sponsor: Address;
-    amount: bigint;
-    claimAddress: Address;
-    recipient: Address;
-    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 반환.
- * withdraw는 임시 지갑이 직접 전송(가스 대납) — claimKey 필요.
- * ABI: src/infrastructure/safedrop_abi.json.
- */
-interface SafeDropChainPort {
-    getDropByKey(dropKey: Hex): Promise<OnePopDrop | null>;
-    getDropKeyByClaimAddress(claimAddress: Address, sponsor: Address): Promise<Hex | null>;
-    getClaimedRecipient(params: {
-        id: Id;
-    }): Promise<Address>;
-    getPendingDropsById(params: {
-        id: Id;
-    }): Promise<readonly OnePopDrop[]>;
-    getPendingDropsByRecipient(params: {
-        recipient: Address;
-    }): Promise<readonly OnePopDrop[]>;
-    getPendingDropsBySponsor(params: {
-        sponsor: Address;
-    }): Promise<readonly OnePopDrop[]>;
-    /** activeDropOf(claimAddr) → drops(dropKey). 없으면 null. */
-    getDrop(claimAddress: Address, sponsor: Address): Promise<DropState | null>;
-    /** claimDigest(recipient, id, dropKey) — 서명 대상 bytes32. */
-    getClaimDigest(params: {
-        recipient: Address;
-        id: Id;
-        dropKey: Hex;
-    }): Promise<Hex>;
-    /**
-     * EIP-2612 permit 예치 — 현재 ONEpop deposit의 유일한 형태다.
-     * 서명(typed data)·deadline·v/r/s는 전부 어댑터 내부 관심사다.
-     */
-    depositWithPermit(params: {
-        claimAddress: Address;
-        token: Address;
-        amount: bigint;
-        id: Id;
-        secretHash: SecretHash;
-        onSubmitted?: (txHash: Hex) => void | Promise<void>;
-    }): Promise<{
-        txHash: Hex;
-        dropKey: Hex;
-    }>;
-    depositMapped(params: {
-        token: Address;
-        amount: bigint;
-        id: Id;
-        onSubmitted?: (txHash: Hex) => void | Promise<void>;
-    }): Promise<{
-        txHash: Hex;
-        dropKey: 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: {
-        dropKey: Hex;
-        onSubmitted?: (txHash: Hex) => void | Promise<void>;
-    }): Promise<Hex>;
-    batchWithdrawMapped(params: {
-        count: number;
-    }): Promise<Hex>;
-    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;
-    }): Promise<Hex>;
-    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;
-        deadline: bigint;
-        signature: Hex;
-    }): Promise<Hex>;
-    /** validatorNonceById(keccak256(utf8(id))). id 해싱은 어댑터 책임. */
-    getValidatorNonce?(params: {
-        id: Id;
-    }): Promise<bigint>;
-    /**
-     * validatorClaimDigest(recipient, id, nonce, deadline) — 온체인 EIP-712 다이제스트.
-     * 로컬 재조립 대신 이 값을 읽어 백엔드 서명을 검증한다.
-     */
-    getValidatorClaimDigest?(params: {
-        recipient: Address;
-        id: Id;
-        nonce: bigint;
-        deadline: bigint;
-    }): Promise<Hex>;
-    /** validator() — 서명자여야 하는 주소. 백엔드 서명 검증의 기준값. */
-    getValidator?(): Promise<Address>;
-}
-
-/**
- * 임시 claim 키로 claimDigest(온체인에서 읽은 bytes32)에 raw ECDSA 서명을 만든다.
- * 컨트랙트가 claimDigest를 계산해주므로 로컬 EIP-712 typed data 구성은 불필요 —
- * digest를 그대로 서명한다. 서명은 브라우저 로컬, 백엔드 미관여.
- */
-interface ClaimSignerPort {
-    signDigest(params: {
-        claimKey: Hex;
-        digest: Hex;
-    }): Promise<Hex>;
-}
-
-/**
- * 프레임워크 무관 진입점. 포트 구현(어댑터)을 주입하면 usecase를 조립해 반환한다.
- *
- *   const safeDrop = createSafeDrop(
- *     { claimBaseUrl },
- *     { api, chain, signer, crypto },
- *   );
- *   const result = await safeDrop.deposit({ ... });
- *   if (!result.isMapped) sendLink(result.withdrawLink);
- *
- * viem/HTTP 어댑터를 자동 조립하려면 `@nexus-cross/pop/adapters`의
- * createSafeDropClient를 사용한다. (도메인/컨트랙트 주소는 chain 어댑터가 안다.)
- */
-
-interface SafeDropConfig {
-    /** 수령 링크 base URL. 예: https://one-pop.example/claim */
-    claimBaseUrl: string;
-}
-interface SafeDropDeps {
-    api: SafeDropApiPort;
-    chain: SafeDropChainPort;
-    signer: ClaimSignerPort;
-    crypto: CryptoPort;
-}
-interface SafeDrop {
-    readonly config: SafeDropConfig;
-    deposit(params: DepositParams): Promise<DepositResult>;
-    /** X OAuth 검증 후 (sender_address + 토큰 소유자)로 임시 claim 키/주소를 받는다 (point of return). */
-    retrieveClaimKey(params: {
-        claimAddress: Address;
-        senderAddress: Address;
-        oauth: OAuthProof;
-    }): Promise<{
-        isMapped: true;
-    } | {
-        isMapped: false;
-        claimKey: Hex;
-        claimAddress: Address;
-    }>;
-    withdraw(params: WithdrawParams): Promise<WithdrawResult>;
-    refund(params: RefundParams): Promise<RefundResult>;
-    /** activeDropOf(claimAddr)로 조회한 현재 온체인 드롭. */
-    getDrop(claimAddress: Address, sponsor: Address): Promise<DropState | null>;
-    getDropByKey(dropKey: Hex): Promise<OnePopDrop | 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[]>;
-    getPendingDropsBySponsor(sponsor: Address): Promise<readonly OnePopDrop[]>;
-    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: {
-        token: Address;
-        dropKey?: Hex;
-    }): Promise<DropInbox>;
-    /** 선택한 pending 드롭을 인박스에서 숨긴다. */
-    rejectDrops(dropIds: readonly number[]): Promise<number>;
-    /** 카드 디자인 목록 (공개). deposit의 `envelopeId`에 쓴다. */
-    listEnvelopes(params?: {
-        locale?: string;
-    }): Promise<readonly Envelope[]>;
-    /** 토큰별 pending 잔액 상위 (공개). */
-    getLeaderboard(params: {
-        token: Address;
-        page?: number;
-        pageSize?: number;
-        identifier?: string;
-    }): Promise<LeaderboardPage>;
-    getMyLeaderboardEntry(params: {
-        token: Address;
-    }): Promise<MyLeaderboardEntry>;
-    /** sent/received 드롭 히스토리. Bearer JWT 필요. */
-    listHistories(params: {
-        type: HistoryType;
-        token?: Address;
-        status?: HistoryStatus;
-        rejected?: boolean;
-        page?: number;
-        pageSize?: number;
-    }): Promise<HistoryPage>;
-    /** 활성 X 연결. 없으면 null. */
-    getXConnection(): Promise<XConnection | null>;
-    /** X 계정을 SIWE 지갑에 연결. `listDrops`의 선행 조건. */
-    connectX(params: {
-        oauth: OAuthProof;
-    }): 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>;
-    /**
-     * anchor drop의 secret/claim key와 validator 서명을 함께 사용해 현재 pending key를
-     * 한 번에 수령한다.
-     */
-    batchClaim(params: BatchClaimParams): Promise<BatchClaimResult>;
-    /**
-     * 서명만 따로 받는 저수준 경로(직접 컨트랙트를 호출할 때). 대부분은 `batchClaim`을 쓴다.
-     * nonce는 `validatorNonceById(keccak256(utf8(id)))`에서 읽은 값이어야 한다.
-     */
-    requestBatchClaimSignature(params: {
-        id: Id;
-        oauth: OAuthProof;
-        nonce: bigint;
-        deadline: bigint;
-    }): Promise<BatchClaimSignature>;
-}
-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 SafeDropErrorCode as F, type SecretHash as G, type Hex as H, type Id as I, type SocialIdentifier as J, type SocialProvider as K, type LeaderboardEntry as L, type MappedDepositResult as M, createSafeDrop as N, 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 HistoryReceiverParty as o, type HistoryStatus as p, type HistoryType as q, type LeaderboardPage as r, type MyLeaderboardEntry as s, type OnePopDrop as t, type RecipientChangeSignature as u, type RecipientSignature as v, type SafeDrop as w, type SafeDropConfig as x, type SafeDropDeps as y, SafeDropError as z };
+export { type Address as A, type BatchClaimParams as B, type DepositParams as D, type Envelope as E, type Hex as H, type Id as I, type LeaderboardPage as L, type MyLeaderboardEntry as M, type OAuthProof as O, type PendingDrop as P, type RefundParams as R, type Secret as S, type UnmappedDepositResult as U, type WithdrawParams as W, type XConnection as X, type SecretHash as a, type DepositResult as b, type WithdrawResult as c, type RefundResult as d, type DropInbox as e, type HistoryType as f, type HistoryStatus as g, type HistoryPage as h, type RecipientChangeSignature as i, type RecipientSignature as j, type BatchClaimResult as k, type BatchClaimSignature as l, type SafeDropApiPort as m, type DropSender as n, type HistoryEntry as o, type HistoryParty as p, type HistoryReceiverParty as q, type LeaderboardEntry as r, type MappedDepositResult as s, SafeDropError as t, type SafeDropErrorCode as u, type SocialIdentifier as v, type SocialProvider as w };