@graph8/sdk 0.2.0

package/README.md

@@ -0,0 +1,281 @@
+# graph8
+
+The most comprehensive GTM SDK. One `npm install`. Every graph8 capability.
+
+## Install
+
+```bash
+npm install graph8
+```
+
+## Quick Start
+
+### Client-side (write key)
+
+```typescript
+import { g8 } from 'graph8';
+
+g8.init({ writeKey: 'YOUR_WRITE_KEY' });
+
+// Track events
+g8.track('signup', { plan: 'pro' });
+
+// Identify users
+g8.identify('user@acme.com', { name: 'John', company: 'Acme' });
+
+// Identify visitor's company from IP
+const visitor = await g8.visitors.identify();
+// { company_name: 'Acme Corp', industry: 'SaaS', employee_count: '200-500' }
+
+// Listen for high-intent visitors
+g8.visitors.onIntent('high', (visitor) => {
+  showCTABanner(`${visitor.company_name} is checking us out!`);
+});
+
+// Open AI copilot
+g8.copilot.open({ greeting: 'How can I help?' });
+
+// Open webchat
+g8.chat.open();
+
+// Show booking widget
+g8.calendar.show({ username: 'thomas', eventType: 'demo-30min' });
+
+// Progressive form enrichment
+const known = await g8.forms.lookup('user@acme.com');
+// { found: true, known_fields: { name: 'John' }, missing_fields: ['phone'] }
+```
+
+### Server-side (API key)
+
+```typescript
+import { g8 } from 'graph8';
+
+g8.init({ apiKey: 'YOUR_API_KEY' });
+
+// Contacts CRUD
+const { data: contacts } = await g8.contacts.list({ company_name: 'Acme', limit: 10 });
+const contact = await g8.contacts.create({ work_email: 'jane@acme.com', first_name: 'Jane' });
+await g8.contacts.update(contact.id, { job_title: 'VP Sales' });
+
+// Companies
+const { data: companies } = await g8.companies.list({ industry: 'SaaS' });
+const { data: teamContacts } = await g8.companies.contacts(companies[0].id);
+
+// Lists
+const list = await g8.lists.create('Q2 Outbound', 'contacts');
+await g8.lists.addContacts(list.id, [contact.id]);
+const { data: listContacts } = await g8.lists.contacts(list.id);
+
+// Enrich a person
+const person = await g8.enrich.person({ email: 'jane@acme.com' });
+
+// Search 300M+ contacts
+const leads = await g8.enrich.search([
+  { field: 'seniority_level', operator: 'any_of', value: ['VP', 'Director'] },
+  { field: 'company_industry', operator: 'contains', value: ['SaaS'] },
+]);
+
+// List sequences and add contacts
+const sequences = await g8.sequences.list();
+await g8.sequences.add({ sequenceId: sequences[0].id, contactIds: [123], listId: 637 });
+
+// Campaign management
+const campaign = await g8.campaigns.create({ name: 'Q2 Push', category: 'Outbound' });
+await g8.campaigns.launch(campaign.id);
+
+// Intent signals
+const signals = await g8.signals.company('acme.com');
+// { score: 87, intent: 'high', signals: ['pricing_page_3x', 'case_study'] }
+
+// Voice AI
+const call = await g8.voice.start({ agent: 'sales-discovery', contactId: 123 });
+const analysis = await g8.voice.analysis(call.id);
+
+// Landing pages
+const page = await g8.pages.clone('https://competitor.com/pricing');
+const { url } = await g8.pages.publish(page.id);
+
+// Webhook events
+g8.webhooks.on('reply_received', (event) => {
+  slack.send(`${event.contact} replied!`);
+});
+```
+
+### React / Next.js
+
+```tsx
+import { G8Provider, useG8 } from 'graph8/react';
+
+// Layout
+<G8Provider writeKey="YOUR_WRITE_KEY"><App /></G8Provider>
+
+// Any component
+const { track, identify, visitors, copilot, calendar } = useG8();
+```
+
+## Full API Reference
+
+### Core (write key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.init(config)` | Initialize SDK |
+| `g8.track(event, props?)` | Track event |
+| `g8.identify(userId, props?)` | Identify user |
+| `g8.page(props?)` | Track page view |
+| `g8.reset()` | Clear identity |
+
+### Contacts (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.contacts.list(params?)` | List contacts with filters |
+| `g8.contacts.get(id)` | Get contact by ID |
+| `g8.contacts.create(contact)` | Create a contact |
+| `g8.contacts.update(id, fields)` | Update contact (partial) |
+| `g8.contacts.delete(id)` | Delete contact |
+
+### Companies (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.companies.list(params?)` | List companies with filters |
+| `g8.companies.get(id)` | Get company by ID |
+| `g8.companies.contacts(id)` | Get company's contacts |
+| `g8.companies.update(id, fields)` | Update company (partial) |
+| `g8.companies.delete(id)` | Delete company |
+
+### Lists (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.lists.list(page?, limit?)` | List all lists |
+| `g8.lists.create(title, type?)` | Create a list |
+| `g8.lists.delete(id)` | Delete a list |
+| `g8.lists.contacts(id, page?, limit?)` | Get contacts in list |
+| `g8.lists.addContacts(id, contactIds)` | Add contacts to list |
+| `g8.lists.removeContacts(id, contactIds)` | Remove contacts from list |
+
+### Visitor Intelligence (write key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.visitors.identify()` | IP to company resolution |
+| `g8.visitors.score()` | Engagement score |
+| `g8.visitors.onIntent(level, cb)` | Real-time intent listener |
+
+### Forms (write key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.forms.lookup(email)` | Progressive form enrichment |
+
+### Copilot (write key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.copilot.open(config?)` | Open AI assistant widget |
+| `g8.copilot.ask(message)` | Send message programmatically |
+| `g8.copilot.registerAction(name, fn)` | Register custom action |
+| `g8.copilot.close()` | Close widget |
+
+### Webchat (write key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.chat.open(config?)` | Open chat widget |
+| `g8.chat.send(message)` | Send message |
+| `g8.chat.on(event, cb)` | Listen for events |
+| `g8.chat.close()` | Close widget |
+
+### Calendar (write key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.calendar.show(config)` | Show booking modal |
+| `g8.calendar.embed(selector, config)` | Inline embed |
+| `g8.calendar.slots(user, slug, range)` | Get available slots |
+| `g8.calendar.book(request)` | Book programmatically |
+
+### Enrichment (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.enrich.person(params)` | Look up a person (1 credit) |
+| `g8.enrich.company(params)` | Look up a company (1 credit) |
+| `g8.enrich.verifyEmail(email)` | Verify email (1 credit) |
+| `g8.enrich.search(filters)` | Search 300M+ contacts |
+
+### Sequences (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.sequences.list()` | List sequences |
+| `g8.sequences.add(config)` | Add contacts to sequence |
+
+### Campaigns (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.campaigns.list()` | List campaigns |
+| `g8.campaigns.create(config)` | Create campaign |
+| `g8.campaigns.launch(id)` | Launch campaign |
+| `g8.campaigns.stats(id)` | Get campaign stats |
+
+### Signals (write key or API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.signals.company(domain)` | Get intent signals |
+| `g8.signals.stream(domains, cb)` | Stream signals (polls 30s) |
+
+### Analytics (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.analytics.overview(config?)` | Dashboard metrics |
+
+### Integrations (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.integrations.list()` | List connected CRMs |
+| `g8.integrations.connect(provider)` | Connect CRM |
+| `g8.integrations.sync(provider)` | Trigger sync |
+
+### Voice AI (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.voice.start(config)` | Start AI voice call |
+| `g8.voice.analysis(sessionId)` | Get call analysis |
+
+### Landing Pages (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.pages.clone(url)` | Clone from URL |
+| `g8.pages.create(config)` | Create from template |
+| `g8.pages.publish(id)` | Publish to CDN |
+
+### Webhooks (API key)
+
+| Method | Description |
+|--------|-------------|
+| `g8.webhooks.on(event, cb)` | Listen for events |
+| `g8.webhooks.stop()` | Stop all listeners |
+
+## Auth Modes
+
+| Mode | Key | Use case |
+|------|-----|----------|
+| **Client-side** | `writeKey` | Browser apps - tracking, visitor ID, widgets |
+| **Server-side** | `apiKey` | Node.js - enrichment, sequences, campaigns, CRM |
+| **Both** | `writeKey` + `apiKey` | Full access |
+
+Get your API key at [app.graph8.com/settings](https://app.graph8.com/settings) under MCP & API > API.
+
+## License
+
+MIT