@hasna/contacts 0.2.7 → 0.2.8

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/mcp/index.js

@@ -1773,28 +1773,42 @@ 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") {
+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";
+  }
+}
+function getConnectorTokenPath(name, profile = "default") {
   const bases = [
-    join2(homedir(), ".connectors", "connect-gmail"),
-    join2(homedir(), ".connect", "connect-gmail")
+    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 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 {}
-    }
+  for (const p of bases) {
+    if (existsSync2(p))
+      return p;
   }
-  throw new Error("Gmail not authenticated. Run `connect-gmail auth login` first.");
+  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 +1870,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 +1888,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 +1904,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 +1915,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")),

package/package.json

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