@beeperbot/sdk 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,178 @@
+# @beeperbot/sdk
+
+TypeScript SDK for [beep.works](https://beep.works) — the attention tokenization platform on Farcaster.
+
+Send beeps (paid DMs) programmatically. Look up users, check prices, create payment intents, and run bulk campaigns.
+
+## Install
+
+```bash
+npm install @beeperbot/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AgentClient } from '@beeperbot/sdk';
+
+const client = new AgentClient({
+  apiKey: 'bpk_live_...',
+  environment: 'production',
+});
+
+// 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!',
+});
+console.log(intent); // { intentId, recipient, amount, instruction, ... }
+```
+
+## Agent Client API
+
+The `AgentClient` is designed for AI agents and simple integrations.
+
+### `lookup(query)`
+Search for 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
+```
+
+### `getPrice(username)`
+Get the attention price for a user.
+
+```typescript
+const price = await client.getPrice('dwr');
+// { userId, username, priceUsd, priceUsdc }
+```
+
+### `createIntent(input)`
+Create a single payment intent.
+
+```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)
+});
+```
+
+### `estimate(input)`
+Estimate campaign costs before committing.
+
+```typescript
+const estimate = await client.estimate({
+  filter: { minFollowers: 1000, platform: 'farcaster' },
+  budgetUsd: 100,
+  message: 'Check out our launch!',
+});
+// { estimatedRecipients, estimatedCostUsd, averagePriceUsd }
+```
+
+### `preview(input)`
+Preview who would receive a campaign.
+
+```typescript
+const preview = await client.preview({
+  filter: { minFollowers: 1000 },
+  limit: 20,
+});
+// { users: [...], totalMatched }
+```
+
+### `createBulkIntent(input)`
+Create a bulk campaign targeting multiple users.
+
+```typescript
+const bulk = await client.createBulkIntent({
+  filter: { platform: 'farcaster', minFollowers: 500 },
+  budgetUsd: 50,
+  message: 'GM from our SDK!',
+});
+// { intentId, recipientCount, totalAmountUsd, ... }
+```
+
+## Advanced: BeeperClient
+
+For the full quote-based flow (create draft → get quote → deposit → execute → receipt):
+
+```typescript
+import { BeeperClient } from '@beeperbot/sdk';
+
+const beeper = new BeeperClient({
+  apiKey: 'bpk_live_...',
+});
+
+// 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);
+```
+
+## Filter Builder
+
+Build complex recipient filters with a fluent API:
+
+```typescript
+import { FilterBuilder } from '@beeperbot/sdk';
+
+const filter = FilterBuilder.and(
+  FilterBuilder.platform('farcaster'),
+  FilterBuilder.minFollowers(1000),
+  FilterBuilder.neynarScoreMin(0.8),
+  FilterBuilder.maxAttentionPrice(2.0),
+);
+```
+
+## Authentication
+
+API keys use the format `bpk_live_*` (production) or `bpk_test_*` (testing).
+
+Get your API key from the [beep.works dashboard](https://beep.works/settings).
+
+## Error Handling
+
+```typescript
+import { BeeperError } from '@beeperbot/sdk';
+
+try {
+  const user = await client.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
+  }
+}
+```
+
+## Configuration
+
+```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
+});
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeperbot/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript SDK for Beeper payment distribution",
   "type": "module",
   "main": "./dist/index.cjs",