Contacts (CRM)

npm install @gately/sdk

import { GatelyContacts } from '@gately/sdk'

const crm = new GatelyContacts({
  projectId: 'YOUR_PROJECT_ID',
  // apiUrl: 'https://api.usegately.com' // optional override
})

const { contacts, pagination } = await crm.list({
  page: 1,
  limit: 50,
  status: 'active',
  search: 'jane',
})

console.log(`${pagination.total} contacts found`)

const contact = await crm.get('con_abc123')
console.log(contact.email) // 'jane@example.com'

const contact = await crm.create({
  name: 'Jane Smith',
  email: 'jane@example.com',
  company: 'Acme Corp',
  status: 'active',
  tags: ['VIP', 'Newsletter'],
  custom_fields: { plan: 'pro', source: 'webinar' },
})

await crm.update('con_abc123', {
  status: 'inactive',
  notes: 'Churned after trial',
})

await crm.delete('con_abc123')

const result = await crm.bulkImport([
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob',   email: 'bob@example.com', company: 'Acme' },
])

console.log(`Imported: ${result.imported}, Skipped: ${result.skipped}`)

if (result.errors.length) {
  result.errors.forEach(e => console.warn(`Row ${e.row}: ${e.error}`))
}

const { lists, segments } = await crm.getContactLists('con_abc123')

const activity = await crm.getEmailActivity('con_abc123')

activity.forEach(event => {
  console.log(`${event.type} — ${event.occurred_at}`)
})

const fields = await crm.getCustomFields('con_abc123')
console.log(fields.plan) // 'pro'

await crm.updateCustomFields('con_abc123', {
  plan: 'enterprise',
  onboarded: true,
})

await crm.unsubscribeContact('con_abc123', {
  reason: 'Too many emails',
  source: 'user_request',
})

await crm.resubscribeContact('con_abc123')

const records = await crm.getUnsubscribes('con_abc123')

const tags = await crm.listTags()

const tag = await crm.createTag({ name: 'VIP', color: '#ff6600' })

await crm.updateTag('tag_abc', { color: '#0066ff' })

await crm.deleteTag('tag_abc')

await crm.addTagToContact('con_abc123', 'tag_abc')

await crm.removeTagFromContact('con_abc123', 'tag_abc')

const lists = await crm.listContactLists()

const list = await crm.getContactList('list_abc')

const list = await crm.createContactList({
  name: 'Newsletter Subscribers',
  description: 'Monthly newsletter opt-ins',
})

await crm.updateContactList('list_abc', { name: 'Weekly Newsletter' })

await crm.deleteContactList('list_abc')

const members = await crm.getListMembers('list_abc', { page: 1, limit: 100 })

await crm.addContactToList('list_abc', 'con_abc123')

await crm.removeContactFromList('list_abc', 'con_abc123')

const segments = await crm.listSegments()

const segment = await crm.getSegment('seg_abc')

const segment = await crm.createSegment({
  name: 'Pro Plan Users',
  rules: [
    { field: 'custom_fields.plan', operator: 'eq', value: 'pro' },
    { field: 'status',             operator: 'eq', value: 'active' },
  ],
})

await crm.updateSegment('seg_abc', {
  name: 'Enterprise Users',
  rules: [{ field: 'custom_fields.plan', operator: 'eq', value: 'enterprise' }],
})

await crm.deleteSegment('seg_abc')

import type {
  ContactsConfig,
  Contact,
  ContactStatus,
  CreateContactRequest,
  UpdateContactRequest,
  ContactListOptions,
  ContactsResult,
  ContactTag,
  ContactList,
  ContactListMember,
  ContactSegment,
  SegmentRule,
  BulkImportResult,
  EmailActivity,
  UnsubscribeRecord,
} from '@gately/sdk'

type ContactStatus = 'new' | 'active' | 'inactive' | 'archived'

interface Contact {
  id: string
  project_id: string
  name: string
  email: string
  phone?: string | null
  company?: string | null
  status: ContactStatus
  notes?: string | null
  custom_fields?: Record<string, any>
  unsubscribed?: boolean
  tags?: ContactTag[]
  last_contacted_at?: string | null
  created_at: string
  updated_at?: string
}

interface SegmentRule {
  field: string
  operator: 'eq' | 'neq' | 'contains' | 'not_contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' | 'empty'
  value?: string | number | boolean
}

import { GatelyContacts } from '@gately/sdk'

const crm = new GatelyContacts({ projectId: 'YOUR_PROJECT_ID' })

async function onboardUser(email: string, name: string, plan: string) {
  // 1. Create the contact
  const contact = await crm.create({
    name,
    email,
    status: 'active',
    custom_fields: { plan, onboarded_at: new Date().toISOString() },
  })

  // 2. Add to the right list
  const lists = await crm.listContactLists()
  const onboardingList = lists.find(l => l.name === 'Onboarding')
  if (onboardingList) {
    await crm.addContactToList(onboardingList.id, contact.id)
  }

  // 3. Tag as VIP if on pro plan
  if (plan === 'pro') {
    const tags = await crm.listTags()
    const vipTag = tags.find(t => t.name === 'VIP')
    if (vipTag) {
      await crm.addTagToContact(contact.id, vipTag.id)
    }
  }

  return contact
}