@graph8/sdk 0.245.0 → 0.260.0

package/README.md

@@ -2,6 +2,12 @@
 
 The most comprehensive GTM SDK. One `npm install`. Every graph8 capability.
 
+> **AI coding agents (Claude Code, Codex, Cursor):** read
+> [`docs/agents.md`](docs/agents.md) (`node_modules/@graph8/sdk/docs/agents.md`) first. It covers setup, the
+> two client layers, safety tiers, errors and tested recipes, and links a per-area reference for every
+> operation in [`docs/api/`](docs/api/README.md). It ships with the package, so it matches this version.
+> Run `npx @graph8/sdk init-agent` to point Claude Code, Codex and Cursor in your project at it automatically.
+
 ## Install
 
 ```bash
@@ -53,7 +59,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' });
@@ -133,8 +145,9 @@ export const CTA = () => {
 
 The clients above are the ergonomic layer — hand-written, opinionated, and only
 as complete as someone made them. `g8.api` is the complete one: it is
-**generated from the published OpenAPI contract**, so it covers **every one of
-the 587 Developer API operations**, including surfaces with no hand-written
+**generated from the published OpenAPI contract**, so it covers **every
+Developer API operation** (the count and a per-area reference are in
+[`docs/api/README.md`](docs/api/README.md)), including surfaces with no hand-written
 client (Appointments, Radar, App Objects, Ad Campaigns, Sandbox, Landing Pages,
 Agent, OpenSearch, ClickHouse and more).
 
@@ -225,9 +238,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 +311,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 |

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+var import_node_fs = __toESM(require("fs"));
+var import_node_path = __toESM(require("path"));
+
+// src/agentSetup.ts
+var ALL_TARGETS = ["claude", "codex", "cursor"];
+var MARKER_START = "<!-- graph8-sdk:start (managed by `npx @graph8/sdk init-agent`; edits inside are overwritten) -->";
+var MARKER_END = "<!-- graph8-sdk:end -->";
+function coreInstructions() {
+  return [
+    "This project uses the graph8 JavaScript SDK, `@graph8/sdk`.",
+    "",
+    "Before writing graph8 code, read `node_modules/@graph8/sdk/docs/agents.md`. It matches the installed version:",
+    "trust it over what you remember about graph8.",
+    "",
+    '- Server code: `import { g8 } from "@graph8/sdk"; g8.init({ apiKey: process.env.G8_API_KEY })`. Browser code: a',
+    "  write key (`g8.init({ writeKey })`), never an API key.",
+    "- Prefer a hand-written client when one exists (`g8.contacts`, `g8.deals`, `g8.sequences`, ...):",
+    "  `node_modules/@graph8/sdk/docs/sdk-clients.md`.",
+    "- Everything else is `g8.api.<namespace>.<member>(input)`, which covers every Developer API operation. Find it in",
+    "  `node_modules/@graph8/sdk/docs/api/README.md` (by area) or `docs/api/by-path.md` (by REST path). Exact types:",
+    "  `docs/api/<namespace>.d.ts`. `g8.api` returns the `{ data, ... }` envelope.",
+    "- Do not guess method names, fields or ids. If the docs do not list it, it does not exist: say so instead of",
+    "  inventing it. (`g8.contacts.search`, `g8.sequences.enroll` and an `@graph8/cli` npm package do not exist.)",
+    "- Ask the user before any `external` (sends messages), `billable` (spends credits) or `destructive` operation.",
+    "  The tier is in each reference entry and in `g8.api.operation(id).tier`.",
+    "- Errors are `G8Error`: log `err.detail`, not only `err.message`. The SDK already retries 429/5xx; do not add",
+    "  another retry loop."
+  ].join("\n");
+}
+function claudeSkill() {
+  return [
+    "---",
+    "name: graph8-sdk",
+    "description: Use when writing or changing code that uses the graph8 JavaScript SDK (@graph8/sdk, `g8.` calls):",
+    "  graph8 contacts, companies, lists, deals, sequences, campaigns, enrichment, inbox, webhooks or any graph8 API.",
+    "---",
+    "",
+    "# graph8 SDK",
+    "",
+    coreInstructions(),
+    "",
+    "_Generated by `npx @graph8/sdk init-agent`. Re-run it to update; edits here are overwritten._",
+    ""
+  ].join("\n");
+}
+function cursorRule() {
+  return [
+    "---",
+    "description: How to use the graph8 JavaScript SDK (@graph8/sdk) in this project",
+    "globs:",
+    "alwaysApply: false",
+    "---",
+    "",
+    coreInstructions(),
+    "",
+    "_Generated by `npx @graph8/sdk init-agent`. Re-run it to update; edits here are overwritten._",
+    ""
+  ].join("\n");
+}
+function agentsMdSection() {
+  return [MARKER_START, "## graph8 SDK", "", coreInstructions(), MARKER_END].join("\n");
+}
+function upsertAgentsMd(existing) {
+  const section = agentsMdSection();
+  if (existing === null || existing.trim() === "") return `${section}
+`;
+  const start = existing.indexOf("<!-- graph8-sdk:start");
+  const end = existing.indexOf(MARKER_END);
+  if (start !== -1 && end !== -1 && end > start) {
+    return existing.slice(0, start) + section + existing.slice(end + MARKER_END.length);
+  }
+  if (start !== -1 || end !== -1) {
+    throw new Error("AGENTS.md has an unmatched graph8-sdk marker; fix or remove it, then re-run.");
+  }
+  return `${existing.replace(/\s*$/, "")}
+
+${section}
+`;
+}
+function planAgentSetup(targets, read) {
+  const plans = [];
+  const add = (target, path2, next) => {
+    const current = read(path2);
+    plans.push({ target, path: path2, content: next, action: current === null ? "create" : current === next ? "unchanged" : "update" });
+  };
+  for (const target of targets) {
+    if (target === "claude") add(target, ".claude/skills/graph8-sdk/SKILL.md", claudeSkill());
+    else if (target === "codex") add(target, "AGENTS.md", upsertAgentsMd(read("AGENTS.md")));
+    else if (target === "cursor") add(target, ".cursor/rules/graph8-sdk.mdc", cursorRule());
+  }
+  return plans;
+}
+var INIT_AGENT_USAGE = `Usage: npx @graph8/sdk init-agent [--claude] [--codex] [--cursor] [--dry-run]
+
+Point the coding agents in this project at the @graph8/sdk agent guide.
+With no agent flag, sets up all three:
+  --claude   .claude/skills/graph8-sdk/SKILL.md   (Claude Code skill)
+  --codex    AGENTS.md, managed section            (Codex, Cursor, Copilot, ...)
+  --cursor   .cursor/rules/graph8-sdk.mdc         (Cursor rule)
+  --dry-run  print what would change, write nothing
+Re-running updates the files in place; your own AGENTS.md text is never touched.`;
+function parseInitAgentArgs(argv) {
+  const targets = [];
+  let dryRun = false;
+  for (const arg of argv) {
+    if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--claude" || arg === "--codex" || arg === "--cursor") targets.push(arg.slice(2));
+    else throw new Error(`unknown option ${arg}
+
+${INIT_AGENT_USAGE}`);
+  }
+  return { targets: targets.length ? [...new Set(targets)] : [...ALL_TARGETS], dryRun };
+}
+
+// src/cli.ts
+var USAGE = `Usage: npx @graph8/sdk <command>
+
+Commands:
+  init-agent   point Claude Code, Codex and Cursor in this project at the SDK's agent guide
+
+${INIT_AGENT_USAGE}`;
+function runCli(argv, io) {
+  const [command, ...rest] = argv;
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    io.out(USAGE);
+    return command ? 0 : 1;
+  }
+  if (command !== "init-agent") {
+    io.err(`unknown command ${command}
+
+${USAGE}`);
+    return 1;
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    io.out(INIT_AGENT_USAGE);
+    return 0;
+  }
+  let options;
+  try {
+    options = parseInitAgentArgs(rest);
+  } catch (e) {
+    io.err(e.message);
+    return 1;
+  }
+  const read = (rel) => {
+    const full = import_node_path.default.join(io.cwd, rel);
+    return import_node_fs.default.existsSync(full) ? import_node_fs.default.readFileSync(full, "utf8") : null;
+  };
+  let plans;
+  try {
+    plans = planAgentSetup(options.targets, read);
+  } catch (e) {
+    io.err(e.message);
+    return 1;
+  }
+  for (const plan of plans) {
+    if (!options.dryRun && plan.action !== "unchanged") {
+      const full = import_node_path.default.join(io.cwd, plan.path);
+      import_node_fs.default.mkdirSync(import_node_path.default.dirname(full), { recursive: true });
+      import_node_fs.default.writeFileSync(full, plan.content, "utf8");
+    }
+    io.out(`${options.dryRun ? "would " : ""}${plan.action === "unchanged" ? "keep" : plan.action} ${plan.path}  (${plan.target})`);
+  }
+  if (!options.dryRun) io.out("\nDone. The full guide is node_modules/@graph8/sdk/docs/agents.md.");
+  return 0;
+}
+var invokedDirectly = typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
+if (invokedDirectly) {
+  process.exitCode = runCli(process.argv.slice(2), {
+    cwd: process.cwd(),
+    out: (l) => process.stdout.write(`${l}
+`),
+    err: (l) => process.stderr.write(`${l}
+`)
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCli
+});