npm package: @newblet/sign-sdk
Description: Newblet popup SDK for web dApps.
Latest version: 0.1.14

# @newblet/sign-sdk

Newblet popup SDK for web dApps.

- **Connect**: obtain the user’s wallet address with explicit approval.
- **Sign**: review → PIN → broadcast, then get the **`txHash`**.  
  Both popups auto‑close after completion.

---

## Install
```bash
npm i @newblet/sign-sdk
# or: pnpm add @newblet/sign-sdk / yarn add @newblet/sign-sdk
```

## Quick start (Connect → Sign)
```ts
import { openNewbletConnectPopup, openNewbletSignPopup } from '@newblet/sign-sdk';

// 1) Ask the wallet to share the user's address
const { address } = await openNewbletConnectPopup({
  walletUrl: 'https://newblet.com', // opens `${walletUrl}/connect`
  state: `demo-${Date.now()}`,
});

// 2) Build your tx
const tx = {
  chain_id: 56,
  to: '0xB0B84e71A6b171c6F315823eec8c911499AB8D06',
  value: '1000000000000000000', // 1 BNB (wei)
  // data?: '0x...'  // optional for contract calls
};

// 3) Review, sign, submit
const { txHash } = await openNewbletSignPopup(tx as any, {
  walletUrl: 'https://newblet.com', // opens `${walletUrl}/sign`
  state: 'order#123',
});
console.log('tx sent:', txHash);
```
> **Call inside a user click handler** to avoid popup blockers.

---

## API

### `openNewbletConnectPopup(opts?) → Promise<{ address: string; state?: string }>`
Opens `/connect`. The wallet shows the requesting origin and asks approval to share the address. If the origin is trusted, it may respond silently (`silentIfTrusted`).

- `walletUrl?: string` (default `https://newblet.com`)
- `state?: string` (echoed)
- `timeoutMs?: number` (default `120_000`)
- `devAllowAnyOrigin?: boolean` — **dev only**
- `silentIfTrusted?: boolean` (default `true`)

**Returns**: `{ address, state? }`  
**Errors**: `TIMEOUT`, `USER_REJECTED`, `ENV_NOT_BROWSER`

---

### `openNewbletSignPopup(tx, opts?) → Promise<{ txHash: string; state?: string }>`
Opens `/sign`. The wallet renders a review, requests PIN, signs, and broadcasts.

`tx` can be **minimal** or **fully built**:

```ts
// Minimal — wallet completes the rest
{ chain_id:number; to:string; data?:string; value?:string }

// Fully built — you provide nonce/gas
{ chain_id:number; to:string; data?:string; value:string; nonce:number; gas_limit:number|string; gas_price:string; type?:0 }
```

Options: `walletUrl?`, `state?`, `timeoutMs?`, `devAllowAnyOrigin?`  
**Returns**: `{ txHash, state? }`  
**Errors**: `TIMEOUT`, `USER_REJECTED`, `MALFORMED_TX`, `SUBMIT_FAILED`, `ENV_NOT_BROWSER`

---

## Types
```ts
export type MinimalTx = {
  chain_id: number;
  to: string;
  data?: string;
  value?: string; // '0' | undefined allowed
};

export type BuiltTx = {
  chain_id: number;
  to: string;
  data?: string;
  value: string;
  nonce: number;
  gas_limit: number | string;
  gas_price: string;
  type?: 0;
};

export type OpenPopupOptions = {
  walletUrl?: string;     // default 'https://newblet.com'
  state?: string;
  timeoutMs?: number;     // default 120_000
  devAllowAnyOrigin?: boolean; // DEV ONLY
};

export type ConnectOptions = OpenPopupOptions & {
  silentIfTrusted?: boolean; // default true
};
```

---

## Notes

- Origin is checked by default (except when `devAllowAnyOrigin` is enabled for local dev). The wallet UI always shows the requesting origin.
- Connect returns **only the address**; signing requires the Sign popup.
- Always open popups from a user gesture.
- Adjust `timeoutMs` for slow environments.

---

## Examples
```ts
// Connect then send a minimal tx
const { address } = await openNewbletConnectPopup({ walletUrl: 'https://newblet.com' });
const tx = { chain_id: 56, to: '0x…', value: '1000000000000000000' };
const { txHash } = await openNewbletSignPopup(tx as any, { walletUrl: 'https://newblet.com' });

// Fully built
const built = {
  chain_id: 56, to: '0x…', value: '0', data: '0xabcdef…',
  nonce: 12, gas_limit: 120000, gas_price: '25000000000', type: 0,
};
const { txHash: h2 } = await openNewbletSignPopup(built, { walletUrl: 'https://newblet.com' });
```

---

## License
MIT