@beeperbot/sdk 0.1.1 → 0.2.1

package/README.md

@@ -1,177 +1,316 @@
-# @beeperbot/sdk
+# @beeper/sdk
 
-TypeScript SDK for [beep.works](https://beep.works) — the attention tokenization platform on Farcaster.
+TypeScript SDK for [beep.works](https://beep.works) — the attention layer on Base.
 
-Send beeps (paid DMs) programmatically. Look up users, check prices, create payment intents, and run bulk campaigns.
+Send paid messages (beeps) to Farcaster users. Look up users, check prices, run targeted campaigns.
 
 ## Install
 
 ```bash
-npm install @beeperbot/sdk
+npm install @beeper/sdk
 ```
 
-## Quick Start
+## Quick Start — AI Agent
+
+The `AgentClient` is the simplest way to integrate beeps into your AI agent or bot.
 
 ```typescript
-import { AgentClient } from '@beeperbot/sdk';
+import { AgentClient } from '@beeper/sdk';
 
-const client = new AgentClient({
-  apiKey: 'bpk_live_...',
-  environment: 'production',
+const agent = new AgentClient({
+  apiKey: process.env.BEEPER_API_KEY!, // bpk_live_...
 });
 
 // Look up a user
-const user = await client.lookup('dwr');
-console.log(user); // { username, fid, attentionPriceUsd, ... }
-
-// Check attention price
-const price = await client.getPrice('dwr');
-console.log(price); // { priceUsd: "0.50", priceUsdc: "500000" }
-
-// Create a payment intent (single user)
-const intent = await client.createIntent({
-  to: 'dwr',
-  amountUsd: 1.0,
-  message: 'Hey, check this out!',
+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); // { intentId, recipient, amount, instruction, ... }
+console.log(intent.instruction);
+// → "Send 5.50 USDC to 0x1a2b... on Base ($5.00 to @dwr + $0.50 platform fee)"
 ```
 
-## Agent Client API
+## 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 |
 
-The `AgentClient` is designed for AI agents and simple integrations.
+---
 
-### `lookup(query)`
-Search for a user by username, FID, or wallet address.
+### `agent.lookup(identifier)`
+
+Look up a user by username, FID, or wallet address.
 
 ```typescript
-const user = await client.lookup('dwr');
-const user = await client.lookup('3'); // by FID
-const user = await client.lookup('0x1234...'); // by wallet
+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
 ```
 
-### `getPrice(username)`
+**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 client.getPrice('dwr');
-// { userId, username, priceUsd, priceUsdc }
+const price = await agent.getPrice('dwr.eth');
+console.log(`$${price.priceUsd} USD`);
 ```
 
-### `createIntent(input)`
-Create a single payment intent.
+---
+
+### `agent.createIntent(input)`
+
+Create a payment intent. Returns instructions for the user to execute the payment.
 
 ```typescript
-const intent = await client.createIntent({
-  to: 'dwr',           // username or FID
-  amountUsd: 1.0,      // amount in USD
-  message: 'Hello!',   // optional message
-  chainId: 8453,       // Base (default)
+const intent = await agent.createIntent({
+  to: 'dwr.eth',       // recipient
+  amount: '$5',         // amount in USD
+  message: 'Hello!',   // required message
+  chainId: 8453,        // Base (default)
 });
 ```
 
-### `estimate(input)`
-Estimate campaign costs before committing.
+**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 client.estimate({
-  filter: { minFollowers: 1000, platform: 'farcaster' },
-  budgetUsd: 100,
-  message: 'Check out our launch!',
+const estimate = await agent.estimate({
+  filters: {
+    platform: 'farcaster',
+    neynarScoreMin: 0.5,
+    minFollowers: 1000,
+    countries: ['US'],
+  },
+  budget: '$100',
 });
-// { estimatedRecipients, estimatedCostUsd, averagePriceUsd }
+
+console.log(`Can reach ${estimate.recipientCount} people`);
+console.log(`Total cost: $${estimate.totalCostUsd}`);
+console.log(`Budget sufficient: ${estimate.budgetSufficient}`);
 ```
 
-### `preview(input)`
-Preview who would receive a campaign.
+---
+
+### `agent.preview(input)`
+
+Preview sample users matching your filters.
 
 ```typescript
-const preview = await client.preview({
-  filter: { minFollowers: 1000 },
-  limit: 20,
+const preview = await agent.preview({
+  filters: { neynarScoreMin: 0.7, hasBaseWallet: true },
+  limit: 5,
 });
-// { users: [...], totalMatched }
+
+preview.users.forEach(u => {
+  console.log(`@${u.username} — $${u.priceUsd} — ${u.followerCount} followers`);
+});
+console.log(`Total matching: ${preview.totalCount}`);
 ```
 
-### `createBulkIntent(input)`
-Create a bulk campaign targeting multiple users.
+---
+
+### `agent.createBulkIntent(input)`
+
+Create payment intents for multiple recipients matching filters.
 
 ```typescript
-const bulk = await client.createBulkIntent({
-  filter: { platform: 'farcaster', minFollowers: 500 },
-  budgetUsd: 50,
-  message: 'GM from our SDK!',
+const bulk = await agent.createBulkIntent({
+  filters: { signalTokens: ['0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed'] },
+  budget: '$50',
+  message: 'GM DEGEN community! 🎩',
 });
-// { intentId, recipientCount, totalAmountUsd, ... }
-```
 
-## Advanced: BeeperClient
+console.log(bulk.summary);
+// → "Send to 120 recipients for total 42.50 USDC on Base"
+```
 
-For the full quote-based flow (create draft → get quote → deposit → execute → receipt):
+---
 
-```typescript
-import { BeeperClient } from '@beeperbot/sdk';
+### `agent.describeFilters()`
 
-const beeper = new BeeperClient({
-  apiKey: 'bpk_live_...',
-});
+Get structured filter documentation for LLM system prompts.
 
-// Full flow
-const draft = await beeper.createDraft({ ... });
-const quote = await beeper.getQuote(draft.id);
-const confirmed = await beeper.confirmDeposit(quote.id, { txHash: '0x...' });
-const result = await beeper.execute(quote.id);
-const receipt = await beeper.getReceipt(quote.id);
+```typescript
+const schema = agent.describeFilters();
+// Use in your LLM's system prompt for filter-aware conversations
 ```
 
-## Filter Builder
+### `agent.getFilterDocumentation()`
 
-Build complex recipient filters with a fluent API:
+Get markdown-formatted filter docs.
 
 ```typescript
-import { FilterBuilder } from '@beeperbot/sdk';
-
-const filter = FilterBuilder.and(
-  FilterBuilder.platform('farcaster'),
-  FilterBuilder.minFollowers(1000),
-  FilterBuilder.neynarScoreMin(0.8),
-  FilterBuilder.maxAttentionPrice(2.0),
-);
+const docs = agent.getFilterDocumentation();
+// Include in system prompt: `Available filters:\n${docs}`
 ```
 
-## Authentication
+---
+
+## 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);
 
-API keys use the format `bpk_live_*` (production) or `bpk_test_*` (testing).
+// 3. Deposit tokens to quote.depositAddress
+// 4. Confirm deposit
+await client.confirmDeposit(quote.id, { txHash: '0x...' });
 
-Get your API key from the [beep.works dashboard](https://beep.works/settings).
+// 5. Execute
+await client.executeSend(quote.id);
+
+// 6. Poll for completion
+const receipt = await client.pollUntilCompleteByQuoteId(quote.id);
+```
 
 ## Error Handling
 
 ```typescript
-import { BeeperError } from '@beeperbot/sdk';
+import { BeeperError, ErrorCodes } from '@beeper/sdk';
 
 try {
-  const user = await client.lookup('nonexistent');
+  await agent.lookup('nonexistent');
 } catch (err) {
   if (err instanceof BeeperError) {
     console.log(err.code);    // 'NOT_FOUND'
-    console.log(err.message); // 'User not found'
-    console.log(err.status);  // 404
+    console.log(err.message); // Human-readable message
+    console.log(err.status);  // HTTP status code
   }
 }
 ```
 
-## Configuration
+Retryable errors: `RATE_LIMITED`, `SERVER_ERROR`, `TIMEOUT`. Use exponential backoff.
 
-```typescript
-const client = new AgentClient({
-  apiKey: 'bpk_live_...',
-  environment: 'production',  // 'production' | 'staging' | 'development'
-  baseUrl: 'https://custom.api.url', // override base URL
-  timeout: 30000,             // request timeout (ms)
-  debug: false,               // enable debug logging
-});
-```
+## 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