npm package: @graph8/sdk
Description: graph8 SDK - CRM, enrichment, sequences, campaigns, and tracking for B2B
Author: graph8
Latest version: 0.2.1

# graph8

The most comprehensive GTM SDK. One `npm install`. Every graph8 capability.

## Install

```bash
npm install @graph8/sdk
```

## Quick Start

### Client-side (write key)

```typescript
import { g8 } from '@graph8/sdk';

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/sdk';

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/sdk/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