@beeperbot/sdk 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,317 @@
+# @beeper/sdk
+
+TypeScript SDK for [beep.works](https://beep.works) — the attention layer on Base.
+
+Send paid messages (beeps) to Farcaster users. Look up users, check prices, run targeted campaigns.
+
+## Install
+
+```bash
+npm install @beeper/sdk
+```
+
+## Quick Start — AI Agent
+
+The `AgentClient` is the simplest way to integrate beeps into your AI agent or bot.
+
+```typescript
+import { AgentClient } from '@beeper/sdk';
+
+const agent = new AgentClient({
+  apiKey: process.env.BEEPER_API_KEY!, // bpk_live_...
+});
+
+// Look up a user
+const user = await agent.lookup('dwr.eth');
+console.log(`@${user.username} — min beep price: $${user.attentionPriceUsd}`);
+
+// Create a payment intent
+const intent = await agent.createIntent({
+  to: 'dwr.eth',
+  amount: '$5',
+  message: 'Love your work on Farcaster!',
+});
+console.log(intent.instruction);
+// → "Send 5.50 USDC to 0x1a2b... on Base ($5.00 to @dwr + $0.50 platform fee)"
+```
+
+## API Reference — AgentClient
+
+### `new AgentClient(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | *required* | API key (`bpk_live_...` or `bpk_test_...`) |
+| `environment` | `'production' \| 'staging'` | `'production'` | API environment |
+| `baseUrl` | `string` | auto | Custom API base URL |
+| `timeoutMs` | `number` | `30000` | Request timeout |
+| `debug` | `boolean` | `false` | Enable debug logging |
+
+---
+
+### `agent.lookup(identifier)`
+
+Look up a user by username, FID, or wallet address.
+
+```typescript
+const user = await agent.lookup('dwr.eth');     // by username
+const user = await agent.lookup(3);             // by FID
+const user = await agent.lookup('0x1a2b...');   // by wallet
+```
+
+**Returns:** `User`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Internal user ID |
+| `fid` | `number?` | Farcaster ID |
+| `username` | `string` | Username |
+| `displayName` | `string?` | Display name |
+| `pfpUrl` | `string?` | Profile picture URL |
+| `platform` | `string` | Platform (farcaster, twitter) |
+| `walletAddress` | `string?` | Verified wallet address |
+| `attentionPriceUsd` | `string` | Minimum beep price in USD |
+| `followerCount` | `number?` | Follower count |
+
+---
+
+### `agent.getPrice(identifier)`
+
+Get the attention price for a user.
+
+```typescript
+const price = await agent.getPrice('dwr.eth');
+console.log(`$${price.priceUsd} USD`);
+```
+
+---
+
+### `agent.createIntent(input)`
+
+Create a payment intent. Returns instructions for the user to execute the payment.
+
+```typescript
+const intent = await agent.createIntent({
+  to: 'dwr.eth',       // recipient
+  amount: '$5',         // amount in USD
+  message: 'Hello!',   // required message
+  chainId: 8453,        // Base (default)
+});
+```
+
+**Returns:** `PaymentIntent` with `intentId`, `recipient`, `amount`, `instruction`, fee breakdown, etc.
+
+> **Note:** A 10% platform fee is added on top. `$5` beep → user pays `$5.50` USDC total.
+
+---
+
+### `agent.estimate(input)`
+
+Estimate how many recipients you can reach within a budget.
+
+```typescript
+const estimate = await agent.estimate({
+  filters: {
+    platform: 'farcaster',
+    neynarScoreMin: 0.5,
+    minFollowers: 1000,
+    countries: ['US'],
+  },
+  budget: '$100',
+});
+
+console.log(`Can reach ${estimate.recipientCount} people`);
+console.log(`Total cost: $${estimate.totalCostUsd}`);
+console.log(`Budget sufficient: ${estimate.budgetSufficient}`);
+```
+
+---
+
+### `agent.preview(input)`
+
+Preview sample users matching your filters.
+
+```typescript
+const preview = await agent.preview({
+  filters: { neynarScoreMin: 0.7, hasBaseWallet: true },
+  limit: 5,
+});
+
+preview.users.forEach(u => {
+  console.log(`@${u.username} — $${u.priceUsd} — ${u.followerCount} followers`);
+});
+console.log(`Total matching: ${preview.totalCount}`);
+```
+
+---
+
+### `agent.createBulkIntent(input)`
+
+Create payment intents for multiple recipients matching filters.
+
+```typescript
+const bulk = await agent.createBulkIntent({
+  filters: { signalTokens: ['0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed'] },
+  budget: '$50',
+  message: 'GM DEGEN community! 🎩',
+});
+
+console.log(bulk.summary);
+// → "Send to 120 recipients for total 42.50 USDC on Base"
+```
+
+---
+
+### `agent.describeFilters()`
+
+Get structured filter documentation for LLM system prompts.
+
+```typescript
+const schema = agent.describeFilters();
+// Use in your LLM's system prompt for filter-aware conversations
+```
+
+### `agent.getFilterDocumentation()`
+
+Get markdown-formatted filter docs.
+
+```typescript
+const docs = agent.getFilterDocumentation();
+// Include in system prompt: `Available filters:\n${docs}`
+```
+
+---
+
+## Filters Reference
+
+Use filters with `estimate`, `preview`, and `createBulkIntent`.
+
+### Platform & Activity
+| Filter | Type | Description |
+|--------|------|-------------|
+| `platform` | `'all' \| 'farcaster' \| 'twitter'` | Target platform |
+| `activeInLastDays` | `number` | Users active within N days |
+
+### Reputation & Quality
+| Filter | Type | Description |
+|--------|------|-------------|
+| `neynarScoreMin` | `number (0-1)` | Min Neynar reputation. 0.5+ = quality, 0.8+ = top tier |
+| `neynarScoreMax` | `number (0-1)` | Max Neynar reputation |
+| `quotientScoreMin` | `number (0-1)` | Min Quotient engagement score |
+| `quotientScoreMax` | `number (0-1)` | Max Quotient score |
+| `spamLabel` | `'not_spam_only' \| 'spam_only' \| 'all'` | Spam classification |
+| `verifiedOnly` | `boolean` | Only wallet-verified users |
+
+### Social Graph
+| Filter | Type | Description |
+|--------|------|-------------|
+| `minFollowers` | `number` | Minimum follower count |
+| `maxFollowers` | `number` | Maximum follower count |
+
+### Token Filters
+| Filter | Type | Description |
+|--------|------|-------------|
+| `signalTokens` | `string[]` | Token addresses users set as interests (community affinity) |
+| `tokenHolders` | `Array<{tokenAddress, chainId, minBalance?}>` | Actual onchain token holders |
+| `hasBaseWallet` | `boolean` | Has a Base chain wallet |
+| `hasVerifiedWallet` | `boolean` | Has a verified wallet |
+
+### Economics
+| Filter | Type | Description |
+|--------|------|-------------|
+| `maxAttentionPriceUsd` | `number` | Max beep price cap |
+| `minBatteryPercentage` | `number (0-100)` | Min battery (engagement metric) |
+| `hasRechargedInLastDays` | `number` | Checked in within N days |
+| `excludePingedToday` | `boolean` | Skip users already beeped today |
+
+### Geography
+| Filter | Type | Description |
+|--------|------|-------------|
+| `countries` | `string[]` | ISO 3166-1 alpha-2 codes (`['US', 'KR']`) |
+
+### Sorting
+| Value | Description |
+|-------|-------------|
+| `attention_price_asc` | Cheapest first (maximize reach) |
+| `attention_price_desc` | Most expensive first |
+| `neynar_score_desc` | Highest reputation first |
+| `followers_desc` | Most followers first |
+| `recent_activity` | Most recently active |
+| `battery_desc` | Highest engagement first |
+| `random` | Random order |
+
+---
+
+## Advanced — BeeperClient
+
+For the full deposit → execute → receipt flow:
+
+```typescript
+import { BeeperClient } from '@beeper/sdk';
+
+const client = new BeeperClient({
+  apiKey: process.env.BEEPER_API_KEY!,
+});
+
+// 1. Create a draft (local, no API call)
+const draft = client.createDraft({
+  filter: { and: [
+    { field: 'neynarScore', op: 'gte', value: 0.5 },
+    { field: 'hasBaseWallet', op: 'eq', value: true },
+  ]},
+  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
+  chainId: 8453, // Base
+  amountPerRecipient: '1000000', // 1 USDC (6 decimals)
+  budgetCap: '100000000', // 100 USDC max
+});
+
+// 2. Get a quote
+const quote = await client.createQuote(draft);
+
+// 3. Deposit tokens to quote.depositAddress
+// 4. Confirm deposit
+await client.confirmDeposit(quote.id, { txHash: '0x...' });
+
+// 5. Execute
+await client.executeSend(quote.id);
+
+// 6. Poll for completion
+const receipt = await client.pollUntilCompleteByQuoteId(quote.id);
+```
+
+## Error Handling
+
+```typescript
+import { BeeperError, ErrorCodes } from '@beeper/sdk';
+
+try {
+  await agent.lookup('nonexistent');
+} catch (err) {
+  if (err instanceof BeeperError) {
+    console.log(err.code);    // 'NOT_FOUND'
+    console.log(err.message); // Human-readable message
+    console.log(err.status);  // HTTP status code
+  }
+}
+```
+
+Retryable errors: `RATE_LIMITED`, `SERVER_ERROR`, `TIMEOUT`. Use exponential backoff.
+
+## API Keys
+
+Get your API key at [beep.works/sdk](https://beep.works/sdk).
+
+- `bpk_live_...` — Production
+- `bpk_test_...` — Sandbox (no real transactions)
+
+**Never expose API keys in frontend code.** Use server-side only.
+
+## Links
+
+- [beep.works](https://beep.works) — Main app
+- [API Docs](https://docs.beep.works) — Full API reference
+- [Discord](https://discord.gg/beepworks) — Community & support
+
+## License
+
+MIT