geodedo 0.1.0

package/README.md

@@ -0,0 +1,414 @@
+# GeoDedo TypeScript SDK
+
+Official TypeScript/JavaScript SDK for the [GeoDedo API](https://geodedo-api.vercel.app) — a white-label GTM outreach platform covering contact search, email/LinkedIn/Instagram/SMS messaging, AI chat, and more.
+
+## Installation
+
+```bash
+npm install geodedo
+```
+
+> Requires Node.js 18+ (uses the built-in `fetch` API).
+
+## Quick Start
+
+```ts
+import { GeoDedo } from 'geodedo';
+
+const client = new GeoDedo({ apiKey: 'gd_live_xxx' });
+
+const contacts = await client.contacts.search({ titles: ['CEO'], locations: ['San Francisco'] });
+console.log(contacts.data);
+```
+
+## Authentication
+
+Get your API key at [geodedo-api.vercel.app](https://geodedo-api.vercel.app) — sign up, go to Dashboard, and copy your key.
+
+Pass the key directly:
+
+```ts
+const client = new GeoDedo({ apiKey: 'gd_live_xxx' });
+```
+
+Or set the `GEODEDO_API_KEY` environment variable and omit the option:
+
+```ts
+const client = new GeoDedo();
+```
+
+## Multi-User Support
+
+If you are building a platform on top of GeoDedo and need to scope API calls to individual end-users, pass a `userId`:
+
+```ts
+const client = new GeoDedo({
+  apiKey: 'gd_live_xxx',
+  userId: 'user_abc123',
+});
+```
+
+The `userId` is sent as an `X-User-Id` header on every request. You can also override it per-request:
+
+```ts
+const contacts = await client.contacts.list(undefined, { userId: 'user_other' });
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | `process.env.GEODEDO_API_KEY` | API key for authentication |
+| `userId` | `string` | — | Default user ID for user-scoped operations |
+| `baseURL` | `string` | `https://geodedo-api.vercel.app` | API base URL |
+| `maxRetries` | `number` | `2` | Max retries on 429/5xx and network errors |
+| `timeout` | `number` | `60000` | Request timeout in milliseconds |
+| `dangerouslyAllowBrowser` | `boolean` | `false` | Allow usage in browser environments |
+
+## Resources
+
+### Contacts
+
+Search, enrich, import, and list contacts.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `search` | `search(params: ContactSearchParams): Promise<Page<Contact>>` | 10 | Search contacts by ICP criteria |
+| `enrich` | `enrich(params: ContactEnrichParams): Promise<Contact>` | 25 | Enrich a single contact |
+| `importCsv` | `importCsv(params: ContactImportParams): Promise<ImportResult>` | 1 | Import a batch of contacts |
+| `list` | `list(params?): Promise<Page<StoredContact>>` | 1 | List stored contacts (paginated) |
+| `csvLists` | `csvLists(): Promise<CsvList[]>` | 1 | List all CSV import lists |
+
+```ts
+// Search for VP-level contacts in tech
+const page = await client.contacts.search({
+  titles: ['VP Engineering', 'VP Product'],
+  locations: ['New York'],
+  employeeRanges: ['51-200'],
+  perPage: 10,
+});
+
+// Enrich a contact by email
+const contact = await client.contacts.enrich({ email: 'jane@example.com' });
+```
+
+### Sequences
+
+Create and manage automated outreach sequences.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `create` | `create(params: SequenceCreateParams): Promise<Sequence>` | 5 | Create a new sequence |
+| `list` | `list(params?): Promise<Page<SequenceWithStats>>` | 1 | List all sequences (paginated) |
+| `get` | `get(sequenceId: string): Promise<SequenceWithStats>` | 1 | Get a sequence by ID |
+| `pause` | `pause(sequenceId: string): Promise<Sequence>` | 1 | Pause a running sequence |
+| `resume` | `resume(sequenceId: string): Promise<Sequence>` | 1 | Resume a paused sequence |
+| `stop` | `stop(sequenceId: string): Promise<Sequence>` | 1 | Stop (terminate) a sequence |
+| `status` | `status(sequenceId: string): Promise<SequenceWithStats>` | 1 | Get sequence status with stats |
+
+```ts
+const seq = await client.sequences.create({
+  name: 'Q2 Outreach',
+  icp: 'SaaS founders, Series A, US-based',
+  channelType: 'email',
+  contactsPerDay: 50,
+  startHour: 9,
+  endHour: 17,
+  activeDays: ['mon', 'tue', 'wed', 'thu', 'fri'],
+  timezone: 'America/New_York',
+});
+
+const status = await client.sequences.status(seq.id);
+console.log(status.stats); // { sent: 12, replied: 3 }
+```
+
+### Drafts
+
+Generate AI-written outreach drafts, review, approve, and send them.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `generate` | `generate(params: DraftGenerateParams): Promise<DraftBatchResult>` | 20 | Generate drafts for contacts |
+| `list` | `list(params?): Promise<Page<Draft>>` | 1 | List drafts (paginated, filterable) |
+| `update` | `update(draftId: string, params: DraftUpdateParams): Promise<Draft>` | 1 | Edit a draft's subject/body |
+| `approve` | `approve(params: DraftApproveParams): Promise<DraftApproveResult>` | 1 | Approve drafts by ID |
+| `send` | `send(params: DraftSendParams): Promise<DraftSendResult>` | 2 | Send approved drafts |
+
+```ts
+const batch = await client.drafts.generate({
+  contacts: [
+    { fullName: 'Jane Smith', title: 'CTO', company: 'Acme', email: 'jane@acme.com' },
+  ],
+  channel: 'email',
+  context: 'Introducing our developer tools platform',
+});
+
+// Review and send
+await client.drafts.approve({ draftIds: batch.drafts.map(d => d.id) });
+const result = await client.drafts.send({ draftIds: batch.drafts.map(d => d.id) });
+console.log(`Sent: ${result.sent}, Failed: ${result.failed}`);
+```
+
+### Messages
+
+Send messages directly across channels.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `sendEmail` | `sendEmail(params: EmailSendParams): Promise<EmailResult>` | 2 | Send an email |
+| `sendLinkedIn` | `sendLinkedIn(params: LinkedInSendParams): Promise<LinkedInResult>` | 10 | Send a LinkedIn message |
+| `sendInstagram` | `sendInstagram(params: InstagramSendParams): Promise<InstagramResult>` | 10 | Send an Instagram DM |
+| `sendSms` | `sendSms(params: SmsSendParams): Promise<SmsResult>` | 5 | Send an SMS |
+| `inbox` | `inbox(channel: InboxChannel): Promise<Record<string, unknown>>` | 2 | Get unified inbox for a channel |
+
+```ts
+const result = await client.messages.sendEmail({
+  to: 'lead@example.com',
+  subject: 'Quick question',
+  body: 'Hi, I wanted to reach out about...',
+  provider: 'gmail',
+});
+console.log(result.sent); // true
+```
+
+### Chat
+
+Interact with the GeoDedo AI assistant. Conversations persist across messages.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `create` | `create(params: ChatCreateParams): Promise<ChatResponse>` | 5 | Send a message to the AI |
+| `conversations.list` | `conversations.list(): Promise<Conversation[]>` | 1 | List all conversations |
+| `conversations.get` | `conversations.get(id: string): Promise<ConversationMessage[]>` | 1 | Get messages in a conversation |
+| `conversations.delete` | `conversations.delete(id: string): Promise<void>` | 0 | Delete a conversation |
+
+```ts
+// Start a conversation
+const chat = await client.chat.create({ message: 'Find me SaaS CTOs in NYC' });
+console.log(chat.response);
+
+// Continue the conversation
+const followUp = await client.chat.create({
+  message: 'Now create an email sequence for them',
+  conversationId: chat.conversationId,
+});
+```
+
+### Channels
+
+Connect and manage outreach channels (Gmail, LinkedIn, Instagram, AgentMail, SMS).
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `status` | `status(): Promise<ChannelStatus>` | 0 | Get status of all channels |
+| `disconnect` | `disconnect(channel: ChannelName): Promise<void>` | 0 | Disconnect a channel |
+| `gmail.connect` | `gmail.connect(): Promise<GmailConnectResult>` | 0 | Start Gmail OAuth flow |
+| `linkedin.connect` | `linkedin.connect(params): Promise<ConnectionResult>` | 0 | Connect LinkedIn |
+| `linkedin.checkpoint` | `linkedin.checkpoint(params): Promise<ConnectionResult>` | 0 | Resolve LinkedIn 2FA |
+| `instagram.connect` | `instagram.connect(params): Promise<ConnectionResult>` | 0 | Connect Instagram |
+| `instagram.checkpoint` | `instagram.checkpoint(params): Promise<ConnectionResult>` | 0 | Resolve Instagram 2FA |
+| `agentmail.create` | `agentmail.create(params): Promise<AgentMailCreateResult>` | 0 | Create an AgentMail address |
+| `sms.verify` | `sms.verify(params): Promise<SmsVerifyResult>` | 0 | Start SMS verification |
+| `sms.confirm` | `sms.confirm(params): Promise<SmsVerifyResult>` | 0 | Confirm SMS with code |
+
+```ts
+// Check which channels are connected
+const status = await client.channels.status();
+console.log(status.gmail.connected); // true
+
+// Connect Gmail (returns an OAuth URL)
+const gmail = await client.channels.gmail.connect();
+console.log(gmail.authUrl); // User visits this URL
+
+// Create an AgentMail address
+const mail = await client.channels.agentmail.create({ username: 'outreach' });
+console.log(mail.email); // outreach@agentmail.geodedo.com
+```
+
+### Documents
+
+Upload and manage documents for AI context.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `upload` | `upload(params: DocumentUploadParams): Promise<Document>` | 1 | Upload a document |
+| `list` | `list(params?): Promise<Page<Document>>` | 1 | List documents (paginated) |
+| `delete` | `delete(documentId: string): Promise<void>` | 0 | Delete a document |
+
+```ts
+const doc = await client.documents.upload({
+  filename: 'product-overview.txt',
+  content: 'Our platform helps sales teams...',
+});
+```
+
+### Recommendations
+
+Get AI-powered recommendations for your outreach strategy.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `icpAnalysis` | `icpAnalysis(): Promise<ICPAnalysis>` | 5 | Analyze ideal customer profile |
+| `channel` | `channel(): Promise<ChannelRecommendation>` | 5 | Get channel recommendation |
+| `sequenceStrategy` | `sequenceStrategy(): Promise<SequenceStrategy>` | 5 | Get sequence strategy advice |
+
+```ts
+const icp = await client.recommendations.icpAnalysis();
+console.log(icp.recommendation);
+```
+
+### Billing
+
+Check credit balance and track usage.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `balance` | `balance(): Promise<CreditBalance>` | 0 | Get current credit balance |
+| `usage` | `usage(params?: UsageListParams): Promise<Page<UsageEntry>>` | 0 | List usage entries (paginated) |
+| `usageSummary` | `usageSummary(): Promise<UsageSummary>` | 0 | Get aggregated usage summary |
+
+```ts
+const balance = await client.billing.balance();
+console.log(`${balance.credits_remaining} credits remaining`);
+
+const summary = await client.billing.usageSummary();
+for (const entry of summary.summary) {
+  console.log(`${entry.operation}: ${entry.total_calls} calls, ${entry.total_credits} credits`);
+}
+```
+
+### Users
+
+Register and manage user profiles.
+
+| Method | Signature | Credits | Description |
+|--------|-----------|---------|-------------|
+| `register` | `register(params: UserRegisterParams): Promise<User>` | 0 | Register a new user |
+| `me` | `me(): Promise<User>` | 0 | Get current user profile |
+| `update` | `update(params: UserUpdateParams): Promise<User>` | 0 | Update user profile |
+
+```ts
+const user = await client.users.register({
+  externalUserId: 'usr_12345',
+  aboutMe: 'Sales leader at Acme Corp',
+  icp: 'SaaS CTOs at Series A startups',
+  cta: 'Book a 15-min demo call',
+});
+```
+
+## Pagination
+
+List endpoints return a `Page<T>` object that supports async iteration:
+
+### Async Iteration (recommended)
+
+Automatically fetches all pages:
+
+```ts
+for await (const contact of await client.contacts.search({ titles: ['CEO'] })) {
+  console.log(contact.fullName);
+}
+```
+
+### Manual Page Access
+
+```ts
+const page = await client.contacts.list({ page: 1, perPage: 25 });
+console.log(page.data);   // items on this page
+console.log(page.total);  // total items across all pages
+console.log(page.page);   // current page number (1-indexed)
+
+if (page.hasNextPage()) {
+  const next = await page.getNextPage();
+  console.log(next.data);
+}
+```
+
+## Error Handling
+
+All errors extend `GeoDedoError`. API errors include the HTTP status code and response body:
+
+```ts
+import {
+  GeoDedo,
+  APIError,
+  AuthenticationError,
+  InsufficientCreditsError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+} from 'geodedo';
+
+try {
+  await client.contacts.search({ titles: ['CEO'] });
+} catch (err) {
+  if (err instanceof InsufficientCreditsError) {
+    console.log(`Need ${err.creditsRequired} credits, have ${err.creditsRemaining}`);
+  } else if (err instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (err instanceof RateLimitError) {
+    console.log(`Rate limited — retry after ${err.retryAfter}s`);
+  } else if (err instanceof ValidationError) {
+    console.log('Invalid request:', err.message);
+  } else if (err instanceof NotFoundError) {
+    console.log('Resource not found');
+  } else if (err instanceof APIError) {
+    console.log(`API error ${err.status}: ${err.message}`);
+  }
+}
+```
+
+### Error Classes
+
+| Class | Status | Description |
+|-------|--------|-------------|
+| `GeoDedoError` | — | Base class for all SDK errors |
+| `APIError` | any | Generic API error with status/body |
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `InsufficientCreditsError` | 402 | Not enough credits |
+| `PermissionDeniedError` | 403 | Not authorized for this operation |
+| `NotFoundError` | 404 | Resource not found |
+| `ValidationError` | 422 | Invalid request parameters |
+| `RateLimitError` | 429 | Rate limit exceeded (has `retryAfter`) |
+| `InternalServerError` | 5xx | Server error |
+| `APIConnectionError` | — | Network-level failure |
+| `APITimeoutError` | — | Request timed out |
+
+## Per-Request Options
+
+Every method accepts an optional `RequestOptions` object as the last argument:
+
+```ts
+await client.contacts.search(
+  { titles: ['CEO'] },
+  {
+    apiKey: 'gd_live_override',   // Override API key
+    userId: 'user_override',      // Override user ID
+    timeout: 30000,               // Override timeout (ms)
+    headers: { 'X-Custom': '1' }, // Additional headers
+    signal: AbortSignal.timeout(5000), // Cancel with AbortSignal
+  },
+);
+```
+
+## Retries
+
+The SDK automatically retries on:
+- HTTP 429 (rate limit), 409, 500, 502, 503, 504
+- Network connection errors
+- Request timeouts
+
+Retries use exponential backoff with jitter (500ms base, 5s max). Configure with `maxRetries` (default: 2).
+
+## Examples
+
+See the [`examples/`](./examples) directory for complete working scripts:
+
+- [`search-contacts.ts`](./examples/search-contacts.ts) — Search and enrich contacts
+- [`create-sequence.ts`](./examples/create-sequence.ts) — Create and monitor a sequence
+- [`send-email.ts`](./examples/send-email.ts) — Send an email and check balance
+- [`ai-chat.ts`](./examples/ai-chat.ts) — Chat with the AI assistant
+
+## License
+
+MIT