@graph8/sdk 0.245.0 → 0.251.0

package/README.md

@@ -53,7 +53,13 @@ import { g8 } from '@graph8/sdk';
 
 g8.init({ apiKey: 'YOUR_API_KEY' });
 
-// Contacts CRUD
+// Contacts: create-or-update in one idempotent call (matches work_email, then linkedin_url).
+// Use this when the contact may already exist; it is safe to retry.
+const { action } = await g8.contacts.upsert({ list_id: 42, work_email: 'jane@acme.com', first_name: 'Jane' });
+// action is "created" or "updated"
+
+// Contacts CRUD. create() is create-only: a duplicate throws a 409 G8Error
+// whose detail.hint / detail.upsert point back at upsert().
 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' });
@@ -225,9 +231,10 @@ Two things to know before reaching for it:
 
 | Method | Description |
 |--------|-------------|
+| `g8.contacts.upsert(contact)` | **Create or update** a contact (`PUT /contacts/assert`). Matches `work_email`, then `linkedin_url`; needs `list_id`. Idempotent, the recommended way to write a contact |
 | `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.create(contact)` | Create a contact. Create-only: a duplicate throws a 409 whose `detail.upsert` names `upsert()` |
 | `g8.contacts.update(id, fields)` | Update contact (partial) |
 | `g8.contacts.delete(id)` | Delete contact |
 
@@ -297,7 +304,7 @@ Two things to know before reaching for it:
 
 | Method | Description |
 |--------|-------------|
-| `g8.enrich.person(params)` | Look up a person (1 credit) |
+| `g8.enrich.person(params)` | Look up a person (1 credit). REST: `POST /enrichment/lookup/person` (`POST /enrichment/person` is an alias) |
 | `g8.enrich.company(params)` | Look up a company (1 credit) |
 | `g8.enrich.verifyEmail(email)` | Verify email (1 credit) |
 | `g8.enrich.search(filters)` | Search 700M+ contacts |