@hasna/contacts 0.2.7 → 0.2.9

package/dist/index.d.ts

@@ -5,6 +5,12 @@ export { createTag, getTag, getTagByName, listTags, updateTag, deleteTag, addTag
 export { createRelationship, listRelationships, getRelationship, deleteRelationship, } from "./db/relationships.js";
 export { createGroup, getGroup, listGroups, updateGroup, deleteGroup, addContactToGroup, removeContactFromGroup, listContactsInGroup, listGroupsForContact, addCompanyToGroup, removeCompanyFromGroup, listCompaniesInGroup, listGroupsForCompany, } from "./db/groups.js";
 export { logActivity, listActivity, getActivity } from "./db/activity.js";
+export { runConnector, readConnectorTokens, getConnectorTokenPath, ConnectorNotInstalledError, ConnectorAuthError } from "./lib/connector.js";
+export type { ConnectorRunOptions } from "./lib/connector.js";
+export { extractContactsFromGmail, parseAddressHeader, domainToCompany, parseName } from "./lib/gmail-import.js";
+export type { GmailImportOptions, ExtractedContact } from "./lib/gmail-import.js";
+export { listGoogleContacts, searchGoogleContacts, pullGoogleContactsAsInputs, pushContactToGoogle, googlePersonToContactInput, contactToGoogleArgs, } from "./lib/google-contacts.js";
+export type { GooglePerson, GoogleContactsSyncOptions, GoogleContactsPushOptions, SyncResult } from "./lib/google-contacts.js";
 export type { EmailType, PhoneType, AddressType, SocialPlatform, RelationshipType, ContactSource, PreferredContactMethod, ContactStatus, Email, Phone, Address, SocialProfile, Tag, Contact, ContactWithDetails, Company, CompanyWithDetails, ContactRelationship, ActivityLog, Webhook, Group, CreateGroupInput, CreateEmailInput, CreatePhoneInput, CreateAddressInput, CreateSocialProfileInput, CreateTagInput, UpdateTagInput, CreateContactInput, UpdateContactInput, ContactListOptions, CreateCompanyInput, UpdateCompanyInput, CompanyListOptions, CreateRelationshipInput, CreateActivityInput, CreateWebhookInput, UpdateWebhookInput, DuplicateByEmail, DuplicateByName, ContactRow, CompanyRow, EmailRow, PhoneRow, AddressRow, SocialProfileRow, TagRow, RelationshipRow, ActivityRow, WebhookRow, } from "./types/index.js";
 export { ContactNotFoundError, CompanyNotFoundError, TagNotFoundError, DuplicateTagNameError, } from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAG9D,OAAO,EACL,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,aAAa,EACb,UAAU,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG1E,YAAY,EAEV,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,aAAa,EAEb,KAAK,EACL,KAAK,EACL,OAAO,EACP,aAAa,EAEb,GAAG,EACH,OAAO,EACP,kBAAkB,EAClB,OAAO,EACP,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,OAAO,EACP,KAAK,EACL,gBAAgB,EAEhB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EAEf,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,MAAM,EACN,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAG9D,OAAO,EACL,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,aAAa,EACb,UAAU,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC9I,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG9D,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACjH,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGlF,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAG/H,YAAY,EAEV,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,aAAa,EAEb,KAAK,EACL,KAAK,EACL,OAAO,EACP,aAAa,EAEb,GAAG,EACH,OAAO,EACP,kBAAkB,EAClB,OAAO,EACP,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,OAAO,EACP,KAAK,EACL,gBAAgB,EAEhB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EAEf,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,MAAM,EACN,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1312,6 +1312,354 @@ function listCompaniesInGroup(db, groupId) {
 function listGroupsForCompany(db, companyId) {
   return db.query(`SELECT g.* FROM groups g JOIN company_groups cog ON g.id = cog.group_id WHERE cog.company_id = ? ORDER BY g.name`).all(companyId);
 }
+// src/lib/connector.ts
+import { join as join2 } from "path";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { homedir } from "os";
+
+class ConnectorNotInstalledError extends Error {
+  connectorName;
+  constructor(connectorName) {
+    super(`connect-${connectorName} is not installed. ` + `Run: bun install -g @hasnaxyz/connect-${connectorName}`);
+    this.connectorName = connectorName;
+    this.name = "ConnectorNotInstalledError";
+  }
+}
+
+class ConnectorAuthError extends Error {
+  connectorName;
+  constructor(connectorName, detail) {
+    super(`connect-${connectorName} is not authenticated. ` + `Run: connect-${connectorName} auth login` + (detail ? ` (${detail})` : ""));
+    this.connectorName = connectorName;
+    this.name = "ConnectorAuthError";
+  }
+}
+async function runConnector(name, args, opts = {}) {
+  const binary = `connect-${name}`;
+  const profile = opts.profile ?? "default";
+  const fullArgs = [
+    "--format",
+    "json",
+    "--profile",
+    profile,
+    ...args
+  ];
+  let proc;
+  try {
+    proc = Bun.spawn([binary, ...fullArgs], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("not found") || msg.includes("ENOENT")) {
+      throw new ConnectorNotInstalledError(name);
+    }
+    throw err;
+  }
+  const timeoutMs = opts.timeout ?? 30000;
+  const timer = setTimeout(() => proc.kill(), timeoutMs);
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      proc.stdout ? new Response(proc.stdout).text() : Promise.resolve(""),
+      proc.stderr ? new Response(proc.stderr).text() : Promise.resolve(""),
+      proc.exited
+    ]);
+    if (exitCode !== 0) {
+      const errText = (stderr || stdout).trim();
+      const lower = errText.toLowerCase();
+      if (lower.includes("auth") || lower.includes("token") || lower.includes("401") || lower.includes("unauthorized") || lower.includes("not authenticated")) {
+        throw new ConnectorAuthError(name, errText.slice(0, 200));
+      }
+      throw new Error(`connect-${name} exited ${exitCode}: ${errText.slice(0, 400)}`);
+    }
+    const text = stdout.trim();
+    if (!text || text === "null")
+      return null;
+    return JSON.parse(text);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function getConnectorTokenPath(name, profile = "default") {
+  const bases = [
+    join2(homedir(), ".connectors", `connect-${name}`, "profiles", profile, "tokens.json"),
+    join2(homedir(), ".connect", `connect-${name}`, "profiles", profile, "tokens.json"),
+    join2(homedir(), ".connect", `connect-${name}`, "tokens.json")
+  ];
+  for (const p of bases) {
+    if (existsSync2(p))
+      return p;
+  }
+  return null;
+}
+function readConnectorTokens(name, profile = "default") {
+  const path = getConnectorTokenPath(name, profile);
+  if (!path)
+    throw new ConnectorAuthError(name);
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    throw new ConnectorAuthError(name, "tokens file unreadable");
+  }
+}
+// src/lib/gmail-import.ts
+function parseAddressHeader(header) {
+  const results = [];
+  const parts = header.split(/,(?![^<>]*>)(?![^"]*")/);
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed)
+      continue;
+    const angleMatch = trimmed.match(/^(.*?)\s*<([^>]+)>\s*$/);
+    if (angleMatch) {
+      const name = angleMatch[1].trim().replace(/^"|"$/g, "");
+      const email = angleMatch[2].trim().toLowerCase();
+      if (email.includes("@"))
+        results.push({ name, email });
+    } else if (trimmed.includes("@")) {
+      results.push({ name: "", email: trimmed.toLowerCase() });
+    }
+  }
+  return results;
+}
+function domainToCompany(email) {
+  const domain = email.split("@")[1];
+  if (!domain)
+    return null;
+  const genericDomains = new Set([
+    "gmail.com",
+    "googlemail.com",
+    "yahoo.com",
+    "yahoo.co.uk",
+    "hotmail.com",
+    "hotmail.co.uk",
+    "outlook.com",
+    "live.com",
+    "icloud.com",
+    "me.com",
+    "mac.com",
+    "protonmail.com",
+    "pm.me",
+    "fastmail.com",
+    "hey.com",
+    "aol.com",
+    "msn.com"
+  ]);
+  if (genericDomains.has(domain.toLowerCase()))
+    return null;
+  const parts = domain.split(".");
+  const name = parts.length > 2 ? parts[parts.length - 2] : parts[0];
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function parseName(displayName) {
+  const name = displayName.trim();
+  if (!name)
+    return {};
+  const parts = name.split(/\s+/);
+  if (parts.length === 1)
+    return { first_name: parts[0] };
+  const last = parts.pop();
+  return { first_name: parts.join(" "), last_name: last };
+}
+async function extractContactsFromGmail(opts) {
+  const maxMessages = Math.min(opts.max_messages ?? 200, 500);
+  const profile = opts.gmail_profile ?? "default";
+  let token;
+  try {
+    const tokens = readConnectorTokens("gmail", profile);
+    token = tokens["accessToken"];
+    if (!token)
+      throw new ConnectorAuthError("gmail", "accessToken missing");
+  } catch (err) {
+    if (err instanceof ConnectorAuthError)
+      throw err;
+    throw new ConnectorAuthError("gmail", String(err));
+  }
+  const listUrl = new URL("https://gmail.googleapis.com/gmail/v1/users/me/messages");
+  listUrl.searchParams.set("q", opts.query);
+  listUrl.searchParams.set("maxResults", String(maxMessages));
+  const listResp = await fetch(listUrl.toString(), {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  if (!listResp.ok) {
+    if (listResp.status === 401) {
+      throw new ConnectorAuthError("gmail", "token expired \u2014 run connect-gmail auth login");
+    }
+    throw new Error(`Gmail API error ${listResp.status}: ${await listResp.text()}`);
+  }
+  const listData = await listResp.json();
+  const messageRefs = listData.messages ?? [];
+  if (messageRefs.length === 0)
+    return [];
+  const seen = new Map;
+  const batchSize = 20;
+  for (let i = 0;i < messageRefs.length; i += batchSize) {
+    const batch = messageRefs.slice(i, i + batchSize);
+    const fetches = batch.map((ref) => {
+      const url = new URL(`https://gmail.googleapis.com/gmail/v1/users/me/messages/${ref.id}`);
+      url.searchParams.set("format", "metadata");
+      url.searchParams.append("metadataHeaders", "From");
+      url.searchParams.append("metadataHeaders", "To");
+      url.searchParams.append("metadataHeaders", "Cc");
+      return fetch(url.toString(), {
+        headers: { Authorization: `Bearer ${token}` }
+      }).then((r) => r.ok ? r.json() : null);
+    });
+    const results = await Promise.all(fetches);
+    for (const msg of results) {
+      if (!msg?.payload?.headers)
+        continue;
+      const getHeader = (name) => msg.payload.headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+      const addresses = [
+        ...parseAddressHeader(getHeader("From")),
+        ...parseAddressHeader(getHeader("To")),
+        ...parseAddressHeader(getHeader("Cc"))
+      ];
+      for (const { name, email } of addresses) {
+        if (seen.has(email))
+          continue;
+        const company_hint = domainToCompany(email);
+        const nameParts = parseName(name);
+        const contact_input = {
+          ...nameParts,
+          display_name: name || email.split("@")[0],
+          emails: [{ address: email, type: "work", is_primary: true }],
+          ...opts.tag_ids?.length ? { tag_ids: opts.tag_ids } : {},
+          source: "email"
+        };
+        seen.set(email, { email, name, company_hint, contact_input });
+      }
+    }
+  }
+  return Array.from(seen.values());
+}
+// src/lib/google-contacts.ts
+function googlePersonToContactInput(person) {
+  const name = person.names?.[0];
+  const primaryEmail = person.emailAddresses?.[0]?.value;
+  const nameParts = name?.givenName || name?.familyName ? { first_name: name.givenName, last_name: name.familyName } : primaryEmail ? parseName(name?.displayName ?? primaryEmail.split("@")[0] ?? "") : {};
+  const emails = (person.emailAddresses ?? []).filter((e) => e.value).map((e, i) => ({
+    address: e.value.toLowerCase(),
+    type: normalizeEmailType(e.type),
+    is_primary: i === 0
+  }));
+  const phones = (person.phoneNumbers ?? []).filter((p) => p.value).map((p, i) => ({
+    number: p.value,
+    type: normalizePhoneType(p.type),
+    is_primary: i === 0
+  }));
+  const org = person.organizations?.[0];
+  const website = person.urls?.[0]?.value;
+  const birthday = (() => {
+    const b = person.birthdays?.[0]?.date;
+    if (!b?.year || !b?.month || !b?.day)
+      return;
+    const mm = String(b.month).padStart(2, "0");
+    const dd = String(b.day).padStart(2, "0");
+    return `${b.year}-${mm}-${dd}`;
+  })();
+  const notes = person.biographies?.map((b) => b.value).filter(Boolean).join(`
+
+`) || undefined;
+  return {
+    ...nameParts,
+    display_name: name?.displayName ?? (nameParts.first_name ? `${nameParts.first_name} ${nameParts.last_name ?? ""}`.trim() : primaryEmail?.split("@")[0] ?? "Unknown"),
+    job_title: org?.title,
+    notes,
+    birthday,
+    website,
+    source: "import",
+    emails,
+    phones,
+    custom_fields: { google_resource_name: person.resourceName }
+  };
+}
+function normalizeEmailType(type) {
+  if (!type)
+    return "work";
+  const t = type.toLowerCase();
+  if (t === "work" || t === "home" || t === "personal")
+    return t === "home" ? "personal" : "work";
+  return "other";
+}
+function normalizePhoneType(type) {
+  if (!type)
+    return "mobile";
+  const t = type.toLowerCase();
+  if (t === "mobile" || t === "cell")
+    return "mobile";
+  if (t === "work")
+    return "work";
+  if (t === "home")
+    return "home";
+  if (t === "fax")
+    return "fax";
+  return "other";
+}
+function contactToGoogleArgs(contact) {
+  const args = [];
+  const displayName = contact.display_name;
+  if (displayName)
+    args.push("--name", displayName);
+  if (contact.first_name)
+    args.push("--given-name", contact.first_name);
+  if (contact.last_name)
+    args.push("--family-name", contact.last_name);
+  const primaryEmail = contact.emails.find((e) => e.is_primary) ?? contact.emails[0];
+  if (primaryEmail)
+    args.push("--email", primaryEmail.address);
+  const primaryPhone = contact.phones.find((p) => p.is_primary) ?? contact.phones[0];
+  if (primaryPhone)
+    args.push("--phone", primaryPhone.number);
+  if (contact.job_title)
+    args.push("--title", contact.job_title);
+  if (contact.company)
+    args.push("--company", contact.company.name);
+  if (contact.notes)
+    args.push("--notes", contact.notes);
+  if (contact.website)
+    args.push("--url", contact.website);
+  return args;
+}
+async function listGoogleContacts(opts = {}) {
+  const args = ["contacts", "list"];
+  if (opts.page_size)
+    args.push("--page-size", String(opts.page_size));
+  const raw = await runConnector("googlecontacts", args, opts);
+  return normalizeGoogleContactsResponse(raw);
+}
+async function searchGoogleContacts(query, opts = {}) {
+  const raw = await runConnector("googlecontacts", ["contacts", "search", query], opts);
+  return normalizeGoogleContactsResponse(raw);
+}
+function normalizeGoogleContactsResponse(raw) {
+  if (!raw)
+    return [];
+  if (Array.isArray(raw))
+    return raw;
+  const obj = raw;
+  if (Array.isArray(obj["connections"]))
+    return obj["connections"];
+  if (Array.isArray(obj["contacts"]))
+    return obj["contacts"];
+  return [];
+}
+async function pushContactToGoogle(contact, opts = {}) {
+  const googleResourceName = contact.custom_fields?.["google_resource_name"];
+  if (googleResourceName && opts.update_existing) {
+    const args2 = ["contacts", "update", googleResourceName, ...contactToGoogleArgs(contact)];
+    const result2 = await runConnector("googlecontacts", args2, opts);
+    return { resourceName: result2?.resourceName ?? googleResourceName, action: "updated" };
+  }
+  const args = ["contacts", "create", ...contactToGoogleArgs(contact)];
+  const result = await runConnector("googlecontacts", args, opts);
+  return { resourceName: result?.resourceName ?? "", action: "created" };
+}
+async function pullGoogleContactsAsInputs(opts = {}) {
+  const people = opts.query ? await searchGoogleContacts(opts.query, opts) : await listGoogleContacts(opts);
+  return people.filter((p) => p.emailAddresses?.some((e) => e.value)).map(googlePersonToContactInput);
+}
 export {
   updateTag,
   updateGroup,
@@ -1319,13 +1667,20 @@ export {
   updateCompany,
   unarchiveContact,
   unarchiveCompany,
+  searchGoogleContacts,
   searchContacts,
   searchCompanies,
+  runConnector,
   resetDatabase,
   removeTagFromContact,
   removeTagFromCompany,
   removeContactFromGroup,
   removeCompanyFromGroup,
+  readConnectorTokens,
+  pushContactToGoogle,
+  pullGoogleContactsAsInputs,
+  parseName,
+  parseAddressHeader,
   mergeContacts,
   logActivity,
   listTags,
@@ -1334,6 +1689,7 @@ export {
   listGroupsForContact,
   listGroupsForCompany,
   listGroups,
+  listGoogleContacts,
   listContactsInGroup,
   listContactsByTag,
   listContacts,
@@ -1341,6 +1697,7 @@ export {
   listCompaniesInGroup,
   listCompanies,
   listActivity,
+  googlePersonToContactInput,
   getTagByName,
   getTag,
   getRelationship,
@@ -1348,8 +1705,11 @@ export {
   getDatabase,
   getContactByEmail,
   getContact,
+  getConnectorTokenPath,
   getCompany,
   getActivity,
+  extractContactsFromGmail,
+  domainToCompany,
   deleteTag,
   deleteRelationship,
   deleteGroup,
@@ -1360,6 +1720,7 @@ export {
   createGroup,
   createContact,
   createCompany,
+  contactToGoogleArgs,
   autoLinkContactToCompany,
   archiveContact,
   archiveCompany,
@@ -1372,5 +1733,7 @@ export {
   TagNotFoundError,
   DuplicateTagNameError,
   ContactNotFoundError,
+  ConnectorNotInstalledError,
+  ConnectorAuthError,
   CompanyNotFoundError
 };

package/dist/lib/connector.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generic connector runner — the scalable foundation for all external service
+ * integrations. Any connector (Gmail, Google Contacts, HubSpot, Salesforce…)
+ * uses this same interface; only the `name` and `args` differ.
+ *
+ * Prerequisites: the target connector must be globally installed and authed:
+ *   bun install -g @hasnaxyz/connect-{name}
+ *   connect-{name} auth login
+ */
+export interface ConnectorRunOptions {
+    /** Connector profile to use (default: "default") */
+    profile?: string;
+    /** Timeout in ms (default: 30_000) */
+    timeout?: number;
+}
+export declare class ConnectorNotInstalledError extends Error {
+    readonly connectorName: string;
+    constructor(connectorName: string);
+}
+export declare class ConnectorAuthError extends Error {
+    readonly connectorName: string;
+    constructor(connectorName: string, detail?: string);
+}
+/**
+ * Execute any connector operation and return the parsed JSON output.
+ *
+ * Usage:
+ *   const messages = await runConnector("gmail", ["messages", "list", "-q", "from:acme.com"]);
+ *   const contacts = await runConnector("googlecontacts", ["contacts", "list"]);
+ */
+export declare function runConnector(name: string, args: string[], opts?: ConnectorRunOptions): Promise<unknown>;
+/**
+ * Returns the path to a connector's token file.
+ * Useful for implementations that need direct API access with refreshed tokens.
+ * Checks canonical path first, then legacy fallback.
+ */
+export declare function getConnectorTokenPath(name: string, profile?: string): string | null;
+/**
+ * Read and parse connector tokens from disk.
+ * Useful when a library needs a raw access token (e.g. for batched REST calls
+ * that would be too slow to do one-at-a-time through the CLI).
+ */
+export declare function readConnectorTokens(name: string, profile?: string): Record<string, unknown>;
+//# sourceMappingURL=connector.d.ts.map

package/dist/lib/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../src/lib/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,0BAA2B,SAAQ,KAAK;aACvB,aAAa,EAAE,MAAM;gBAArB,aAAa,EAAE,MAAM;CAOlD;AAED,qBAAa,kBAAmB,SAAQ,KAAK;aACf,aAAa,EAAE,MAAM;gBAArB,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAQnE;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAyDlB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAY,GAAG,MAAM,GAAG,IAAI,CAUtF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ9F"}

package/dist/lib/gmail-import.d.ts

@@ -1,10 +1,10 @@
 /**
- * Gmail contact import — fetches messages matching a query, extracts unique
- * senders/recipients, and returns them as CreateContactInput objects.
+ * Gmail contact import — fetches messages matching a query via the connect-gmail
+ * connector, extracts unique senders/recipients, and returns them as
+ * CreateContactInput objects ready to upsert into the local DB.
  *
- * Uses the Gmail REST API directly with tokens stored at
- * ~/.connectors/connect-gmail/profiles/default/tokens.json
- * (requires connect-gmail auth login to be completed first).
+ * Auth: connect-gmail auth login   (run once per profile)
+ * Install: bun install -g @hasnaxyz/connect-gmail
  */
 import type { CreateContactInput } from "../types/index.js";
 /**
@@ -15,6 +15,18 @@ export declare function parseAddressHeader(header: string): Array<{
     name: string;
     email: string;
 }>;
+/**
+ * Infer a company name from an email domain.
+ * Returns null for personal/generic domains (gmail, yahoo, hotmail, etc.).
+ */
+export declare function domainToCompany(email: string): string | null;
+/**
+ * Parse display name into first/last name.
+ */
+export declare function parseName(displayName: string): {
+    first_name?: string;
+    last_name?: string;
+};
 export interface GmailImportOptions {
     query: string;
     /** Max messages to scan (default 200, max 500) */
@@ -32,6 +44,7 @@ export interface ExtractedContact {
 }
 /**
  * Fetch messages matching `query` from Gmail and extract unique contacts.
+ * Uses connect-gmail's stored tokens for auth — no API keys needed in code.
  * Does NOT write to the database — returns prepared CreateContactInput objects.
  */
 export declare function extractContactsFromGmail(opts: GmailImportOptions): Promise<ExtractedContact[]>;

package/dist/lib/gmail-import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gmail-import.d.ts","sourceRoot":"","sources":["../../src/lib/gmail-import.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAoD5D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBzF;AAqCD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,kBAAkB,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoF7B"}
+{"version":3,"file":"gmail-import.d.ts","sourceRoot":"","sources":["../../src/lib/gmail-import.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAK5D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB5D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAO1F;AAID,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,kBAAkB,CAAC;CACnC;AAQD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAsF7B"}

package/dist/lib/google-contacts.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Google Contacts sync — bidirectional sync between local DB and Google Contacts
+ * via the connect-googlecontacts connector.
+ *
+ * Auth: connect-googlecontacts auth login   (run once per profile)
+ * Install: bun install -g @hasnaxyz/connect-googlecontacts
+ *
+ * Data format: Google People API
+ *   https://developers.google.com/people/api/rest/v1/people
+ */
+import type { ContactWithDetails, CreateContactInput } from "../types/index.js";
+import { ConnectorRunOptions } from "./connector.js";
+interface PeopleName {
+    displayName?: string;
+    givenName?: string;
+    familyName?: string;
+    middleName?: string;
+}
+interface PeopleEmail {
+    value?: string;
+    type?: string;
+    formattedType?: string;
+}
+interface PeoplePhone {
+    value?: string;
+    type?: string;
+    formattedType?: string;
+}
+interface PeopleOrg {
+    name?: string;
+    title?: string;
+    department?: string;
+}
+interface PeopleAddress {
+    streetAddress?: string;
+    city?: string;
+    region?: string;
+    postalCode?: string;
+    country?: string;
+    type?: string;
+}
+interface PeopleBio {
+    value?: string;
+}
+interface PeopleUrl {
+    value?: string;
+    type?: string;
+}
+export interface GooglePerson {
+    resourceName: string;
+    etag?: string;
+    names?: PeopleName[];
+    emailAddresses?: PeopleEmail[];
+    phoneNumbers?: PeoplePhone[];
+    organizations?: PeopleOrg[];
+    addresses?: PeopleAddress[];
+    biographies?: PeopleBio[];
+    urls?: PeopleUrl[];
+    birthdays?: Array<{
+        date?: {
+            year?: number;
+            month?: number;
+            day?: number;
+        };
+    }>;
+}
+export interface GoogleContactsSyncOptions extends ConnectorRunOptions {
+    /** Max contacts to pull per page (connector handles pagination automatically) */
+    page_size?: number;
+    /** Only import contacts matching this query */
+    query?: string;
+}
+export interface GoogleContactsPushOptions extends ConnectorRunOptions {
+    /** If true, update existing Google contact if resourceName is stored in custom_fields */
+    update_existing?: boolean;
+}
+export interface SyncResult {
+    imported: number;
+    updated: number;
+    skipped: number;
+    errors: string[];
+}
+/**
+ * Convert a Google People API person to a CreateContactInput.
+ */
+export declare function googlePersonToContactInput(person: GooglePerson): CreateContactInput;
+/**
+ * Convert a local ContactWithDetails to Google People API create/update args.
+ * Returns the CLI flags for `connect-googlecontacts contacts create`.
+ */
+export declare function contactToGoogleArgs(contact: ContactWithDetails): string[];
+/**
+ * List all contacts from Google Contacts.
+ */
+export declare function listGoogleContacts(opts?: GoogleContactsSyncOptions): Promise<GooglePerson[]>;
+/**
+ * Search contacts in Google Contacts.
+ */
+export declare function searchGoogleContacts(query: string, opts?: ConnectorRunOptions): Promise<GooglePerson[]>;
+/**
+ * Create a new contact in Google Contacts from a local contact.
+ * Returns the Google resource name (e.g. "people/c12345").
+ */
+export declare function pushContactToGoogle(contact: ContactWithDetails, opts?: GoogleContactsPushOptions): Promise<{
+    resourceName: string;
+    action: "created" | "updated";
+}>;
+/**
+ * Sync all Google Contacts into the local database.
+ * Caller is responsible for the actual upsert (pass a db upsert function).
+ * Returns structured CreateContactInput objects ready for upsert.
+ */
+export declare function pullGoogleContactsAsInputs(opts?: GoogleContactsSyncOptions): Promise<CreateContactInput[]>;
+export {};
+//# sourceMappingURL=google-contacts.d.ts.map

package/dist/lib/google-contacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-contacts.d.ts","sourceRoot":"","sources":["../../src/lib/google-contacts.ts"],"names":[],"mappings":"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"}

package/dist/lib/google-contacts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=google-contacts.test.d.ts.map

package/dist/lib/google-contacts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-contacts.test.d.ts","sourceRoot":"","sources":["../../src/lib/google-contacts.test.ts"],"names":[],"mappings":""}

package/dist/mcp/index.js

@@ -1773,28 +1773,99 @@ async function exportContacts(format, contacts) {
   }
 }
 
-// src/lib/gmail-import.ts
+// src/lib/connector.ts
+import { join as join2 } from "path";
 import { existsSync as existsSync2, readFileSync } from "fs";
 import { homedir } from "os";
-import { join as join2 } from "path";
-function loadGmailToken(profile = "default") {
-  const bases = [
-    join2(homedir(), ".connectors", "connect-gmail"),
-    join2(homedir(), ".connect", "connect-gmail")
+
+class ConnectorNotInstalledError extends Error {
+  connectorName;
+  constructor(connectorName) {
+    super(`connect-${connectorName} is not installed. ` + `Run: bun install -g @hasnaxyz/connect-${connectorName}`);
+    this.connectorName = connectorName;
+    this.name = "ConnectorNotInstalledError";
+  }
+}
+
+class ConnectorAuthError extends Error {
+  connectorName;
+  constructor(connectorName, detail) {
+    super(`connect-${connectorName} is not authenticated. ` + `Run: connect-${connectorName} auth login` + (detail ? ` (${detail})` : ""));
+    this.connectorName = connectorName;
+    this.name = "ConnectorAuthError";
+  }
+}
+async function runConnector(name, args, opts = {}) {
+  const binary = `connect-${name}`;
+  const profile = opts.profile ?? "default";
+  const fullArgs = [
+    "--format",
+    "json",
+    "--profile",
+    profile,
+    ...args
   ];
-  for (const base of bases) {
-    const tokenPath = join2(base, "profiles", profile, "tokens.json");
-    if (existsSync2(tokenPath)) {
-      try {
-        const raw = readFileSync(tokenPath, "utf-8");
-        const tokens = JSON.parse(raw);
-        if (tokens.accessToken)
-          return tokens.accessToken;
-      } catch {}
+  let proc;
+  try {
+    proc = Bun.spawn([binary, ...fullArgs], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("not found") || msg.includes("ENOENT")) {
+      throw new ConnectorNotInstalledError(name);
     }
+    throw err;
+  }
+  const timeoutMs = opts.timeout ?? 30000;
+  const timer = setTimeout(() => proc.kill(), timeoutMs);
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      proc.stdout ? new Response(proc.stdout).text() : Promise.resolve(""),
+      proc.stderr ? new Response(proc.stderr).text() : Promise.resolve(""),
+      proc.exited
+    ]);
+    if (exitCode !== 0) {
+      const errText = (stderr || stdout).trim();
+      const lower = errText.toLowerCase();
+      if (lower.includes("auth") || lower.includes("token") || lower.includes("401") || lower.includes("unauthorized") || lower.includes("not authenticated")) {
+        throw new ConnectorAuthError(name, errText.slice(0, 200));
+      }
+      throw new Error(`connect-${name} exited ${exitCode}: ${errText.slice(0, 400)}`);
+    }
+    const text = stdout.trim();
+    if (!text || text === "null")
+      return null;
+    return JSON.parse(text);
+  } finally {
+    clearTimeout(timer);
   }
-  throw new Error("Gmail not authenticated. Run `connect-gmail auth login` first.");
 }
+function getConnectorTokenPath(name, profile = "default") {
+  const bases = [
+    join2(homedir(), ".connectors", `connect-${name}`, "profiles", profile, "tokens.json"),
+    join2(homedir(), ".connect", `connect-${name}`, "profiles", profile, "tokens.json"),
+    join2(homedir(), ".connect", `connect-${name}`, "tokens.json")
+  ];
+  for (const p of bases) {
+    if (existsSync2(p))
+      return p;
+  }
+  return null;
+}
+function readConnectorTokens(name, profile = "default") {
+  const path = getConnectorTokenPath(name, profile);
+  if (!path)
+    throw new ConnectorAuthError(name);
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    throw new ConnectorAuthError(name, "tokens file unreadable");
+  }
+}
+
+// src/lib/gmail-import.ts
 function parseAddressHeader(header) {
   const results = [];
   const parts = header.split(/,(?![^<>]*>)(?![^"]*")/);
@@ -1856,7 +1927,17 @@ function parseName(displayName) {
 async function extractContactsFromGmail(opts) {
   const maxMessages = Math.min(opts.max_messages ?? 200, 500);
   const profile = opts.gmail_profile ?? "default";
-  const token = loadGmailToken(profile);
+  let token;
+  try {
+    const tokens = readConnectorTokens("gmail", profile);
+    token = tokens["accessToken"];
+    if (!token)
+      throw new ConnectorAuthError("gmail", "accessToken missing");
+  } catch (err) {
+    if (err instanceof ConnectorAuthError)
+      throw err;
+    throw new ConnectorAuthError("gmail", String(err));
+  }
   const listUrl = new URL("https://gmail.googleapis.com/gmail/v1/users/me/messages");
   listUrl.searchParams.set("q", opts.query);
   listUrl.searchParams.set("maxResults", String(maxMessages));
@@ -1864,17 +1945,15 @@ async function extractContactsFromGmail(opts) {
     headers: { Authorization: `Bearer ${token}` }
   });
   if (!listResp.ok) {
-    const body = await listResp.text();
     if (listResp.status === 401) {
-      throw new Error("Gmail token expired. Run `connect-gmail auth login` to re-authenticate.");
+      throw new ConnectorAuthError("gmail", "token expired \u2014 run connect-gmail auth login");
     }
-    throw new Error(`Gmail API error ${listResp.status}: ${body}`);
+    throw new Error(`Gmail API error ${listResp.status}: ${await listResp.text()}`);
   }
   const listData = await listResp.json();
   const messageRefs = listData.messages ?? [];
-  if (messageRefs.length === 0) {
+  if (messageRefs.length === 0)
     return [];
-  }
   const seen = new Map;
   const batchSize = 20;
   for (let i = 0;i < messageRefs.length; i += batchSize) {
@@ -1882,9 +1961,9 @@ async function extractContactsFromGmail(opts) {
     const fetches = batch.map((ref) => {
       const url = new URL(`https://gmail.googleapis.com/gmail/v1/users/me/messages/${ref.id}`);
       url.searchParams.set("format", "metadata");
-      url.searchParams.set("metadataHeaders", "From");
-      url.searchParams.set("metadataHeaders", "To");
-      url.searchParams.set("metadataHeaders", "Cc");
+      url.searchParams.append("metadataHeaders", "From");
+      url.searchParams.append("metadataHeaders", "To");
+      url.searchParams.append("metadataHeaders", "Cc");
       return fetch(url.toString(), {
         headers: { Authorization: `Bearer ${token}` }
       }).then((r) => r.ok ? r.json() : null);
@@ -1893,8 +1972,7 @@ async function extractContactsFromGmail(opts) {
     for (const msg of results) {
       if (!msg?.payload?.headers)
         continue;
-      const headers = msg.payload.headers;
-      const getHeader = (name) => headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+      const getHeader = (name) => msg.payload.headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
       const addresses = [
         ...parseAddressHeader(getHeader("From")),
         ...parseAddressHeader(getHeader("To")),
@@ -1919,6 +1997,133 @@ async function extractContactsFromGmail(opts) {
   return Array.from(seen.values());
 }
 
+// src/lib/google-contacts.ts
+function googlePersonToContactInput(person) {
+  const name = person.names?.[0];
+  const primaryEmail = person.emailAddresses?.[0]?.value;
+  const nameParts = name?.givenName || name?.familyName ? { first_name: name.givenName, last_name: name.familyName } : primaryEmail ? parseName(name?.displayName ?? primaryEmail.split("@")[0] ?? "") : {};
+  const emails = (person.emailAddresses ?? []).filter((e) => e.value).map((e, i) => ({
+    address: e.value.toLowerCase(),
+    type: normalizeEmailType(e.type),
+    is_primary: i === 0
+  }));
+  const phones = (person.phoneNumbers ?? []).filter((p) => p.value).map((p, i) => ({
+    number: p.value,
+    type: normalizePhoneType(p.type),
+    is_primary: i === 0
+  }));
+  const org = person.organizations?.[0];
+  const website = person.urls?.[0]?.value;
+  const birthday = (() => {
+    const b = person.birthdays?.[0]?.date;
+    if (!b?.year || !b?.month || !b?.day)
+      return;
+    const mm = String(b.month).padStart(2, "0");
+    const dd = String(b.day).padStart(2, "0");
+    return `${b.year}-${mm}-${dd}`;
+  })();
+  const notes = person.biographies?.map((b) => b.value).filter(Boolean).join(`
+
+`) || undefined;
+  return {
+    ...nameParts,
+    display_name: name?.displayName ?? (nameParts.first_name ? `${nameParts.first_name} ${nameParts.last_name ?? ""}`.trim() : primaryEmail?.split("@")[0] ?? "Unknown"),
+    job_title: org?.title,
+    notes,
+    birthday,
+    website,
+    source: "import",
+    emails,
+    phones,
+    custom_fields: { google_resource_name: person.resourceName }
+  };
+}
+function normalizeEmailType(type) {
+  if (!type)
+    return "work";
+  const t = type.toLowerCase();
+  if (t === "work" || t === "home" || t === "personal")
+    return t === "home" ? "personal" : "work";
+  return "other";
+}
+function normalizePhoneType(type) {
+  if (!type)
+    return "mobile";
+  const t = type.toLowerCase();
+  if (t === "mobile" || t === "cell")
+    return "mobile";
+  if (t === "work")
+    return "work";
+  if (t === "home")
+    return "home";
+  if (t === "fax")
+    return "fax";
+  return "other";
+}
+function contactToGoogleArgs(contact) {
+  const args = [];
+  const displayName = contact.display_name;
+  if (displayName)
+    args.push("--name", displayName);
+  if (contact.first_name)
+    args.push("--given-name", contact.first_name);
+  if (contact.last_name)
+    args.push("--family-name", contact.last_name);
+  const primaryEmail = contact.emails.find((e) => e.is_primary) ?? contact.emails[0];
+  if (primaryEmail)
+    args.push("--email", primaryEmail.address);
+  const primaryPhone = contact.phones.find((p) => p.is_primary) ?? contact.phones[0];
+  if (primaryPhone)
+    args.push("--phone", primaryPhone.number);
+  if (contact.job_title)
+    args.push("--title", contact.job_title);
+  if (contact.company)
+    args.push("--company", contact.company.name);
+  if (contact.notes)
+    args.push("--notes", contact.notes);
+  if (contact.website)
+    args.push("--url", contact.website);
+  return args;
+}
+async function listGoogleContacts(opts = {}) {
+  const args = ["contacts", "list"];
+  if (opts.page_size)
+    args.push("--page-size", String(opts.page_size));
+  const raw = await runConnector("googlecontacts", args, opts);
+  return normalizeGoogleContactsResponse(raw);
+}
+async function searchGoogleContacts(query, opts = {}) {
+  const raw = await runConnector("googlecontacts", ["contacts", "search", query], opts);
+  return normalizeGoogleContactsResponse(raw);
+}
+function normalizeGoogleContactsResponse(raw) {
+  if (!raw)
+    return [];
+  if (Array.isArray(raw))
+    return raw;
+  const obj = raw;
+  if (Array.isArray(obj["connections"]))
+    return obj["connections"];
+  if (Array.isArray(obj["contacts"]))
+    return obj["contacts"];
+  return [];
+}
+async function pushContactToGoogle(contact, opts = {}) {
+  const googleResourceName = contact.custom_fields?.["google_resource_name"];
+  if (googleResourceName && opts.update_existing) {
+    const args2 = ["contacts", "update", googleResourceName, ...contactToGoogleArgs(contact)];
+    const result2 = await runConnector("googlecontacts", args2, opts);
+    return { resourceName: result2?.resourceName ?? googleResourceName, action: "updated" };
+  }
+  const args = ["contacts", "create", ...contactToGoogleArgs(contact)];
+  const result = await runConnector("googlecontacts", args, opts);
+  return { resourceName: result?.resourceName ?? "", action: "created" };
+}
+async function pullGoogleContactsAsInputs(opts = {}) {
+  const people = opts.query ? await searchGoogleContacts(opts.query, opts) : await listGoogleContacts(opts);
+  return people.filter((p) => p.emailAddresses?.some((e) => e.value)).map(googlePersonToContactInput);
+}
+
 // src/mcp/index.ts
 var server = new Server({ name: "contacts", version: "0.1.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -2733,6 +2938,46 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         required: ["query"]
       }
+    },
+    {
+      name: "sync_from_google_contacts",
+      description: "Pull contacts from Google Contacts (People API) and upsert them into the local database. Skips contacts that already exist by email. Requires connect-googlecontacts auth login. Returns { imported, skipped, errors }.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Optional search query to filter which Google Contacts to import" },
+          page_size: { type: "number", description: "Contacts per page (default: connector default)" },
+          google_profile: { type: "string", description: "connect-googlecontacts profile (default: 'default')" },
+          tag_ids: { type: "array", items: { type: "string" }, description: "Tag IDs to apply to all imported contacts" },
+          project_id: { type: "string", description: "Project ID to assign to all imported contacts" },
+          dry_run: { type: "boolean", description: "Preview what would be imported without saving" }
+        }
+      }
+    },
+    {
+      name: "push_contact_to_google",
+      description: "Push a local contact to Google Contacts \u2014 creates a new Google contact (or updates if google_resource_name is stored in custom_fields). Requires connect-googlecontacts auth login.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          contact_id: { type: "string", description: "Local contact ID to push" },
+          google_profile: { type: "string", description: "connect-googlecontacts profile (default: 'default')" },
+          update_existing: { type: "boolean", description: "If true, update existing Google contact when google_resource_name is present in custom_fields" }
+        },
+        required: ["contact_id"]
+      }
+    },
+    {
+      name: "search_google_contacts",
+      description: "Search Google Contacts by name or email (read-only, does not import). Returns raw Google People API objects. Useful for lookup or preview before a push/sync.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          google_profile: { type: "string", description: "connect-googlecontacts profile (default: 'default')" }
+        },
+        required: ["query"]
+      }
     }
   ]
 }));
@@ -3363,14 +3608,79 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }]
         };
       }
+      case "sync_from_google_contacts": {
+        const db = getDatabase();
+        const googleProfile = a.google_profile;
+        const inputs = await pullGoogleContactsAsInputs({
+          query: a.query,
+          page_size: a.page_size,
+          profile: googleProfile ?? "default"
+        });
+        const enriched = inputs.map((inp) => ({
+          ...inp,
+          ...a.tag_ids ? { tag_ids: a.tag_ids } : {},
+          ...a.project_id ? { project_id: a.project_id } : {}
+        }));
+        if (a.dry_run) {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({ dry_run: true, would_import: enriched.length, contacts: enriched }, null, 2)
+            }]
+          };
+        }
+        let imported = 0;
+        let skipped = 0;
+        const syncErrors = [];
+        for (const input of enriched) {
+          const primaryEmail = input.emails?.[0]?.address;
+          if (!primaryEmail) {
+            skipped++;
+            continue;
+          }
+          try {
+            const existing = db.prepare(`SELECT contact_id FROM emails WHERE LOWER(address) = LOWER(?) AND contact_id IS NOT NULL LIMIT 1`).get(primaryEmail);
+            if (existing) {
+              skipped++;
+              continue;
+            }
+            createContact(input);
+            imported++;
+          } catch (err) {
+            syncErrors.push(`${primaryEmail}: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ imported, skipped, errors: syncErrors.length, error_details: syncErrors }, null, 2)
+          }]
+        };
+      }
+      case "push_contact_to_google": {
+        const contact = getContact(a.contact_id);
+        const result = await pushContactToGoogle(contact, {
+          profile: a.google_profile ?? "default",
+          update_existing: a.update_existing
+        });
+        return { content: [{ type: "text", text: JSON.stringify({ ...result, contact_id: contact.id }, null, 2) }] };
+      }
+      case "search_google_contacts": {
+        const people = await searchGoogleContacts(a.query, {
+          profile: a.google_profile ?? "default"
+        });
+        const mapped = people.map((p) => ({
+          google: p,
+          as_contact_input: googlePersonToContactInput(p)
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(mapped, null, 2) }] };
+      }
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
     }
   } catch (err) {
-    return {
-      content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
-      isError: true
-    };
+    const msg = err instanceof ConnectorNotInstalledError || err instanceof ConnectorAuthError ? err.message : `Error: ${err instanceof Error ? err.message : String(err)}`;
+    return { content: [{ type: "text", text: msg }], isError: true };
   }
 });
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/contacts",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Contact management for AI coding agents — CLI + MCP + Web",
   "type": "module",
   "main": "dist/index.js",