@hasna/connectors 1.3.45 → 1.3.46

package/connectors/zoominfo/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+Guidance for AI agents working on this connector.
+
+## Scope
+
+This package implements `@hasna/connect-zoominfo`, a real ZoomInfo B2B sales intelligence REST API connector. Keep it on documented ZoomInfo HTTP endpoints and do not add browser automation dependencies.
+
+## API Model
+
+- Default base URL: `https://api.zoominfo.com`
+- Authentication: `POST /authenticate` with username/password returns a JWT, or use a preconfigured JWT via `ZOOMINFO_JWT`
+- Subsequent requests use `Authorization: Bearer <jwt>`
+- Raw requests must use relative paths without `..` traversal
+- Keep `.env.example` values as placeholders only
+
+## Checks
+
+Before finishing changes:
+
+```bash
+bun run typecheck
+bun run build
+```
+
+Also scan for committed secrets, internal references, and browser automation dependencies.

package/connectors/zoominfo/CLAUDE.md

@@ -0,0 +1,20 @@
+# CLAUDE.md
+
+See `AGENTS.md` for connector-specific instructions.
+
+## Authentication
+
+ZoomInfo uses username/password authentication via `POST /authenticate` to obtain a Bearer JWT token. Preconfigured JWT tokens are also supported via `ZOOMINFO_JWT` or `connect-zoominfo config set-jwt`.
+
+Subsequent API calls use `Authorization: Bearer <jwt>`.
+
+Environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `ZOOMINFO_USERNAME` | ZoomInfo API username |
+| `ZOOMINFO_PASSWORD` | ZoomInfo API password |
+| `ZOOMINFO_JWT` | Preconfigured Bearer JWT (skips /authenticate) |
+| `ZOOMINFO_BASE_URL` | Override API base URL |
+
+JWT tokens expire after approximately 60 minutes. Long-running processes should re-authenticate or refresh the configured JWT.

package/connectors/zoominfo/README.md

@@ -0,0 +1,69 @@
+# @hasna/connect-zoominfo
+
+TypeScript and CLI connector for the ZoomInfo B2B sales intelligence API.
+
+## Install
+
+```bash
+bun add @hasna/connect-zoominfo
+```
+
+## Configure
+
+```bash
+export ZOOMINFO_USERNAME=your_zoominfo_username
+export ZOOMINFO_PASSWORD=your_zoominfo_password
+export ZOOMINFO_JWT=your_zoominfo_jwt
+export ZOOMINFO_BASE_URL=https://api.zoominfo.com
+```
+
+The CLI can also store local configuration:
+
+```bash
+connect-zoominfo config set-username your_zoominfo_username
+connect-zoominfo config set-password your_zoominfo_password
+connect-zoominfo config set-jwt your_zoominfo_jwt
+connect-zoominfo config show
+```
+
+## CLI Examples
+
+```bash
+connect-zoominfo authenticate
+connect-zoominfo search-contacts --body '{"jobTitle":["VP of Sales"],"rpp":25,"page":1}'
+connect-zoominfo search-companies --body '{"companyName":"Example Corp"}'
+connect-zoominfo enrich-contact --body '{"matchPersonInput":[{"emailAddress":"person@example.com"}],"outputFields":["email","jobTitle"]}'
+connect-zoominfo enrich-company --body '{"matchCompanyInput":[{"companyName":"Example Corp"}]}'
+connect-zoominfo lookup-contact 123456789
+connect-zoominfo contact-search-output-fields
+connect-zoominfo raw-request POST /search/contact --body '{"jobTitle":["CTO"]}'
+```
+
+## TypeScript
+
+```ts
+import { ZoomInfo } from "@hasna/connect-zoominfo";
+
+const zoominfo = new ZoomInfo({
+  username: process.env.ZOOMINFO_USERNAME,
+  password: process.env.ZOOMINFO_PASSWORD,
+});
+
+await zoominfo.authenticate();
+const contacts = await zoominfo.searchContacts({ jobTitle: ["VP of Sales"], rpp: 25, page: 1 });
+const enriched = await zoominfo.enrichContact({
+  matchPersonInput: [{ emailAddress: "person@example.com" }],
+  outputFields: ["email", "jobTitle"],
+});
+```
+
+## API Coverage
+
+- Username/password authentication (`POST /authenticate`) with JWT caching per client instance
+- Contact and company search
+- Contact and company enrichment
+- Contact lookup by ID
+- Search output field discovery
+- Relative raw requests
+
+JWT tokens are valid for approximately 60 minutes. Long-running processes may need to re-authenticate or provide a fresh `ZOOMINFO_JWT`.

package/connectors/zoominfo/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/connect-zoominfo",
+  "version": "0.0.1",
+  "description": "ZoomInfo B2B sales intelligence API connector for contact and company search, enrichment, and lookup",
+  "type": "module",
+  "bin": {
+    "connect-zoominfo": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "zoominfo",
+    "sales-intelligence",
+    "enrichment",
+    "contacts",
+    "companies",
+    "b2b",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connect-zoominfo.git"
+  }
+}

package/connectors/zoominfo/src/api/client.test.ts

@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { ZoomInfo, ZoomInfoApiError } from "../index";
+
+const originalFetch = globalThis.fetch;
+let fetchMock: ReturnType<typeof mock>;
+
+function mockJsonResponse(body: unknown, init: ResponseInit = {}) {
+  return new Response(JSON.stringify(body), {
+    status: init.status ?? 200,
+    headers: { "content-type": "application/json", ...init.headers },
+  });
+}
+
+function clientWithCredentials() {
+  return new ZoomInfo({
+    username: "api-user",
+    password: "api-pass",
+    baseUrl: "https://api.zoominfo.com",
+  });
+}
+
+function clientWithJwt() {
+  return new ZoomInfo({
+    jwt: "configured-jwt-token",
+    baseUrl: "https://custom.zoominfo.test",
+  });
+}
+
+beforeEach(() => {
+  fetchMock = mock(async () => mockJsonResponse({ success: true }));
+  globalThis.fetch = fetchMock as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("ZoomInfoClient", () => {
+  test("authenticates with username/password and caches JWT for subsequent calls", async () => {
+    fetchMock = mock(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith("/authenticate")) {
+        return mockJsonResponse({ jwt: "fresh-jwt-token" });
+      }
+      if (url.endsWith("/search/contact")) {
+        const headers = init?.headers as Record<string, string>;
+        expect(headers.Authorization).toBe("Bearer fresh-jwt-token");
+        return mockJsonResponse({ data: [{ id: "1" }] });
+      }
+      return mockJsonResponse({});
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const api = clientWithCredentials();
+    const auth = await api.authenticate();
+    expect(auth.jwt).toBe("fresh-jwt-token");
+
+    await api.searchContacts({ jobTitle: ["VP of Sales"] });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const [authUrl, authInit] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(authUrl).toBe("https://api.zoominfo.com/authenticate");
+    expect(authInit.method).toBe("POST");
+    expect(JSON.parse(String(authInit.body))).toEqual({ username: "api-user", password: "api-pass" });
+  });
+
+  test("configured JWT skips /authenticate on API calls", async () => {
+    const api = clientWithJwt();
+
+    await api.searchCompanies({ companyName: "Example Corp" });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://custom.zoominfo.test/search/company");
+    expect(init.method).toBe("POST");
+    expect((init.headers as Record<string, string>).Authorization).toBe("Bearer configured-jwt-token");
+  });
+
+  test("lookupContact uses bearer auth and encodes contact id", async () => {
+    const api = clientWithJwt();
+
+    await api.lookupContact("contact/id");
+
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://custom.zoominfo.test/lookup/contact/contact%2Fid");
+    expect(init.method).toBe("GET");
+    expect((init.headers as Record<string, string>).Authorization).toBe("Bearer configured-jwt-token");
+  });
+
+  test("enrichContact requires matchPersonInput", async () => {
+    const api = clientWithJwt();
+
+    await expect(api.enrichContact({ outputFields: ["email"] })).rejects.toThrow("matchPersonInput");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("enrichContact sends matchPersonInput payload", async () => {
+    const api = clientWithJwt();
+    const body = {
+      matchPersonInput: [{ emailAddress: "person@example.com" }],
+      outputFields: ["email", "jobTitle"],
+    };
+
+    await api.enrichContact(body);
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(String(init.body))).toEqual(body);
+  });
+
+  test("lists contact and company search output fields", async () => {
+    const api = clientWithJwt();
+
+    await api.listContactSearchOutputFields();
+    await api.listCompanySearchOutputFields();
+
+    const urls = (fetchMock.mock.calls as [string, RequestInit][]).map(([url]) => url);
+    expect(urls).toEqual([
+      "https://custom.zoominfo.test/lookup/outputfields/contact/search",
+      "https://custom.zoominfo.test/lookup/outputfields/company/search",
+    ]);
+  });
+
+  test("rawRequest rejects absolute URLs and path traversal", async () => {
+    const api = clientWithJwt();
+
+    await expect(api.rawRequest("GET", "https://evil.example/search/contact")).rejects.toThrow("absolute URLs");
+    await expect(api.rawRequest("GET", "/search/../admin")).rejects.toThrow("path traversal");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("throws ZoomInfoApiError on HTTP failures", async () => {
+    fetchMock = mock(async () => mockJsonResponse({ message: "Unauthorized" }, { status: 401 }));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const api = clientWithJwt();
+
+    await expect(api.searchContacts()).rejects.toBeInstanceOf(ZoomInfoApiError);
+  });
+});

package/connectors/zoominfo/src/api/client.ts

@@ -0,0 +1,228 @@
+import type { HttpMethod, JsonObject, JsonValue, QueryValue, RequestOptions, ZoomInfoConfig } from "../types";
+import { ZoomInfoApiError } from "../types";
+
+const DEFAULT_BASE_URL = "https://api.zoominfo.com";
+
+export class ZoomInfoClient {
+  private readonly username?: string;
+  private readonly password?: string;
+  private readonly configuredJwt?: string;
+  private readonly baseUrl: string;
+  private cachedJwt?: string;
+
+  constructor(config: ZoomInfoConfig = {}) {
+    this.username = config.username;
+    this.password = config.password;
+    this.configuredJwt = config.jwt;
+    this.baseUrl = this.cleanBaseUrl(config.baseUrl || DEFAULT_BASE_URL);
+  }
+
+  async authenticate(): Promise<{ jwt: string }> {
+    const username = this.requireString(this.username, "username");
+    const password = this.requireString(this.password, "password");
+
+    const response = await fetch(`${this.baseUrl}/authenticate`, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ username, password }),
+    });
+
+    const text = await response.text();
+    const data = this.parseResponseBody(text, response.headers.get("content-type"));
+
+    if (!response.ok) {
+      throw new ZoomInfoApiError(this.errorMessage(data, response.statusText), response.status, data);
+    }
+
+    const jwt = this.extractJwt(data);
+    this.cachedJwt = jwt;
+    return { jwt };
+  }
+
+  async searchContacts(body: JsonValue = {}, params: Record<string, QueryValue> = {}) {
+    return this.request("/search/contact", { method: "POST", params, body });
+  }
+
+  async searchCompanies(body: JsonValue = {}, params: Record<string, QueryValue> = {}) {
+    return this.request("/search/company", { method: "POST", params, body });
+  }
+
+  async enrichContact(body: JsonValue) {
+    this.requireMatchPersonInput(body);
+    return this.request("/enrich/contact", { method: "POST", body });
+  }
+
+  async enrichCompany(body: JsonValue = {}) {
+    return this.request("/enrich/company", { method: "POST", body });
+  }
+
+  async lookupContact(contactId: string) {
+    return this.request(`/lookup/contact/${this.segment(contactId)}`);
+  }
+
+  async listContactSearchOutputFields() {
+    return this.request("/lookup/outputfields/contact/search");
+  }
+
+  async listCompanySearchOutputFields() {
+    return this.request("/lookup/outputfields/company/search");
+  }
+
+  rawRequest<T = unknown>(method: HttpMethod, path: string, options: Omit<RequestOptions, "method"> = {}) {
+    return this.request<T>(path, { ...options, method });
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  async request<T = unknown>(path: string, options: RequestOptions = {}): Promise<T> {
+    const method = options.method || "GET";
+    const url = this.buildUrl(path, options.params);
+    const headers = await this.prepareHeaders(options);
+    const body = this.prepareBody(method, options.body, headers);
+
+    const response = await fetch(url.toString(), {
+      method,
+      headers,
+      body,
+    });
+    const text = await response.text();
+    const data = options.responseType === "text" ? text : this.parseResponseBody(text, response.headers.get("content-type"));
+
+    if (!response.ok) {
+      throw new ZoomInfoApiError(this.errorMessage(data, response.statusText), response.status, data);
+    }
+
+    return data as T;
+  }
+
+  private async prepareHeaders(options: RequestOptions): Promise<Record<string, string>> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      ...options.headers,
+    };
+
+    if (options.auth !== false) {
+      const jwt = await this.resolveJwt();
+      headers.Authorization = `Bearer ${jwt}`;
+    }
+
+    return headers;
+  }
+
+  private async resolveJwt(): Promise<string> {
+    if (this.configuredJwt) {
+      return this.configuredJwt;
+    }
+    if (this.cachedJwt) {
+      return this.cachedJwt;
+    }
+    const result = await this.authenticate();
+    return result.jwt;
+  }
+
+  private extractJwt(data: unknown): string {
+    if (typeof data === "object" && data !== null) {
+      const record = data as Record<string, unknown>;
+      for (const key of ["jwt", "access_token", "token"]) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim()) {
+          return value.trim();
+        }
+      }
+    }
+    throw new ZoomInfoApiError("ZoomInfo authenticate response did not include a JWT");
+  }
+
+  private requireMatchPersonInput(body: JsonValue): void {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+      throw new Error("ZoomInfo enrichContact body must be a JSON object with matchPersonInput");
+    }
+    const matchPersonInput = (body as JsonObject).matchPersonInput;
+    if (!Array.isArray(matchPersonInput) || matchPersonInput.length === 0) {
+      throw new Error("ZoomInfo enrichContact requires matchPersonInput");
+    }
+  }
+
+  private prepareBody(method: HttpMethod, body: JsonValue | string | undefined, headers: Record<string, string>): string | undefined {
+    if (body === undefined || body === null || method === "GET") return undefined;
+    headers["Content-Type"] = headers["Content-Type"] || "application/json";
+    return typeof body === "string" ? body : JSON.stringify(this.cleanObject(body));
+  }
+
+  private buildUrl(path: string, params?: Record<string, QueryValue>): URL {
+    const trimmedPath = path.trim();
+    if (!trimmedPath) throw new Error("ZoomInfo API path is required");
+    if (/^https?:\/\//i.test(trimmedPath)) throw new Error("ZoomInfo raw paths must be relative, not absolute URLs");
+    if (trimmedPath.includes("..")) throw new Error("ZoomInfo raw paths must not contain path traversal");
+
+    const normalizedPath = trimmedPath.startsWith("/") ? trimmedPath : `/${trimmedPath}`;
+    const url = new URL(`${this.baseUrl}${normalizedPath}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) this.appendQueryValue(url, key, value);
+    }
+    return url;
+  }
+
+  private appendQueryValue(url: URL, key: string, value: QueryValue): void {
+    if (value === undefined || value === null || value === "") return;
+    if (Array.isArray(value)) {
+      for (const item of value) url.searchParams.append(key, String(item));
+      return;
+    }
+    url.searchParams.append(key, String(value));
+  }
+
+  private parseResponseBody(text: string, contentType: string | null): unknown {
+    if (!text) return {};
+    if (contentType?.includes("json") || text.startsWith("{") || text.startsWith("[")) {
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+    return text;
+  }
+
+  private errorMessage(data: unknown, statusText: string): string {
+    if (typeof data === "object" && data !== null) {
+      const record = data as Record<string, unknown>;
+      if (typeof record.error_message === "string") return record.error_message;
+      if (typeof record.error === "string") return record.error;
+      if (typeof record.message === "string") return record.message;
+    }
+    if (typeof data === "string" && data.trim()) return data.slice(0, 500);
+    return statusText || "ZoomInfo API request failed";
+  }
+
+  private cleanBaseUrl(baseUrl: string): string {
+    const trimmed = baseUrl.trim();
+    const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    return withProtocol.replace(/\/+$/, "");
+  }
+
+  private segment(value: string): string {
+    return encodeURIComponent(this.requireString(value, "path segment"));
+  }
+
+  private requireString(value: string | undefined, label: string): string {
+    const trimmed = value?.trim();
+    if (!trimmed) throw new Error(`ZoomInfo ${label} is required`);
+    return trimmed;
+  }
+
+  private cleanObject(value: JsonValue): JsonValue {
+    if (Array.isArray(value)) return value.map((item) => this.cleanObject(item));
+    if (typeof value !== "object" || value === null) return value;
+    const cleaned: Record<string, JsonValue> = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (child !== undefined) cleaned[key] = this.cleanObject(child);
+    }
+    return cleaned;
+  }
+}

package/connectors/zoominfo/src/api/index.ts

@@ -0,0 +1 @@
+export { ZoomInfoClient, ZoomInfoClient as ZoomInfo } from "./client";