# @usealbatross/sdk

Official SDK for [Albatross](https://albatrossprotocol.com), the privacy protocol on Solana.

Move SOL privately with the bridge, or send SOL to anyone with a single unlinkable
Ghost Link. No wallet connection, no signup, noncustodial.

```bash
npm install @usealbatross/sdk
```

## Quick start

```ts
import { Albatross } from '@usealbatross/sdk'

const albatross = new Albatross()

// 1. Create a private bridge
const bridge = await albatross.createBridge({
  amount: 1,                 // SOL the recipient receives (0.1, 0.5, 1 or 5)
  destination: 'YourCleanWallet…',
})

console.log(`Send ${bridge.depositSol} SOL to ${bridge.depositAddress}`)

// 2. Wait until the payout lands
const result = await albatross.waitForBridge(bridge.id, {
  onUpdate: (s) => console.log(s.status),
})

console.log('Done:', result.payoutSignature)
```

Even shorter, with the one shot helper:

```ts
const { bridge, wait } = await albatross.bridge({ amount: 1, destination })
console.log(`Send ${bridge.depositSol} SOL to ${bridge.depositAddress}`)
const done = await wait()
```

## Ghost Links

Send SOL to anyone with just a link. No address, no wallet connect, no onchain trail
between sender and receiver. The claim secret lives only in the URL fragment and is
never sent to or stored by the server.

```ts
import { Albatross } from '@usealbatross/sdk'

const albatross = new Albatross()

// 1. Create a Ghost Link (secret + claim URL are generated locally)
const { link, claimUrl } = await albatross.createGhostLink({
  amount: 0.5,                     // SOL the receiver claims (0.1, 0.5, 1 or 5)
  refundAddress: 'YourWallet…',    // where funds return if never claimed
  note: 'gm 👻',                    // optional, shown to the receiver
})

console.log(`Fund it: send ${link.depositSol} SOL to ${link.depositAddress}`)
console.log(`Then share: ${claimUrl}`)   // keep this safe — it can never be recovered

// 2. The receiver claims to any wallet
await albatross.claimFromUrl(claimUrl, 'ReceiverWallet…')
```

⚠️ The `secret` and `claimUrl` are never stored server side and cannot be recovered.
Persist or share them the moment you create the link.

## How the bridge works

You send SOL to the fresh `depositAddress`. Albatross detects it and pays the same
amount to your `destination` from an unrelated wallet. The two transfers are never
linked onchain. The fee is 0.5%, added on top of the amount. Ghost Links work the
same way, but the payout goes to whoever claims the link.

## API

### `new Albatross(options?)`

| Option | Type | Default |
|---|---|---|
| `baseUrl` | `string` | `https://backend.albatrossprotocol.com/api` |
| `appUrl` | `string` | `https://albatrossprotocol.com` |
| `fetch` | `typeof fetch` | global `fetch` |

### Bridge methods

- `createBridge({ amount, destination })` → `Bridge` — create a bridge, returns the deposit address.
- `getBridge(id)` → `BridgeState` — fetch current status.
- `waitForBridge(id, opts?)` → `BridgeState` — poll until terminal (`completed`, `refunded`, `failed`, `expired`).
- `bridge({ amount, destination })` → `{ bridge, wait() }` — create and get a ready `wait()` helper.
- `getAmounts()` → `{ amounts, feeBps }` — selectable amounts and fee.
- `getStats()` → `{ bridges, volumeSol, fundingWallets, feeBps }` — network stats.

### Ghost Link methods

- `createGhostLink({ amount, refundAddress, note? })` → `{ link, secret, claimUrl }` — create a link locally hashing the secret.
- `getGhostLink(id)` → `GhostLinkState` — fetch current status.
- `claimGhostLink({ id, secret, destination })` → claim to a wallet.
- `claimFromUrl(claimUrl, destination)` → parse a claim URL and claim it.
- `waitForGhostLink(id, opts?)` → poll until terminal (`claimed`, `refunded`, `failed`, `expired`).
- `getGhostAmounts()` → `{ amounts, feeBps, claimExpiryDays }`.
- `buildClaimUrl(id, secret)` → build a shareable claim URL.
- `generateClaimSecret()` (named export) → `{ secret, secretHash }` low level helper.

### Statuses

Bridge: `awaiting_deposit` → `paying_out` → `completed`, or `refunded` / `failed` / `expired`.

Ghost Link: `awaiting_deposit` → `funded` → `claiming` → `claimed`, or `refunded` / `failed` / `expired`.

## License

MIT