@hasna/connectors 1.3.45 → 1.4.0

package/connectors/x/src/api/oauth.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import {
+  exchangeCodeForTokens,
+  refreshAccessToken,
+  revokeToken,
+  type OAuth2Config,
+} from './oauth';
+
+/**
+ * Regression tests for https://github.com/hasna/connectors/issues/1
+ *
+ * X rejects `Authorization: Basic <client_id:client_secret>` on
+ * POST /2/oauth2/token when the app is registered as a *public* client:
+ *   {"error":"unauthorized_client",
+ *    "error_description":"Missing valid authorization header"}
+ *
+ * The connector therefore must always authenticate the client with POST body
+ * parameters (`client_id`, plus `client_secret` when one is configured) and
+ * must never fall back to an Authorization header on the token/revoke
+ * endpoints.
+ */
+
+interface CapturedRequest {
+  url: string;
+  method?: string;
+  headers: Record<string, string>;
+  body: URLSearchParams;
+}
+
+const realFetch = globalThis.fetch;
+
+/**
+ * Normalise every shape `RequestInit.headers` can take (plain object, entry
+ * array, `Headers` instance) into a lower-cased record. Going through
+ * `new Headers(...)` matters: if the implementation ever switched to a
+ * `Headers` object, a naive `Object.entries()` would yield `[]` and the
+ * "no Authorization header" assertions below would pass vacuously.
+ */
+function normaliseHeaders(init?: RequestInit): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!init?.headers) return out;
+  new Headers(init.headers).forEach((value, key) => {
+    out[key.toLowerCase()] = value;
+  });
+  return out;
+}
+
+function captureTokenRequest(): { calls: CapturedRequest[] } {
+  const calls: CapturedRequest[] = [];
+
+  globalThis.fetch = (async (input: unknown, init?: RequestInit) => {
+    const headers = normaliseHeaders(init);
+
+    calls.push({
+      url: String(input),
+      method: init?.method,
+      headers,
+      body: new URLSearchParams(String(init?.body ?? '')),
+    });
+
+    return new Response(
+      JSON.stringify({
+        access_token: 'ACCESS_TOKEN',
+        refresh_token: 'NEW_REFRESH_TOKEN',
+        expires_in: 7200,
+        scope: 'tweet.read tweet.write offline.access',
+        token_type: 'bearer',
+      }),
+      { status: 200, headers: { 'Content-Type': 'application/json' } }
+    );
+  }) as typeof fetch;
+
+  return { calls };
+}
+
+const PUBLIC_CLIENT: OAuth2Config = {
+  clientId: 'PUBLIC_CLIENT_ID',
+  redirectUri: 'http://localhost:8888/callback',
+};
+
+const CONFIDENTIAL_CLIENT: OAuth2Config = {
+  clientId: 'CONFIDENTIAL_CLIENT_ID',
+  clientSecret: 'CONFIDENTIAL_CLIENT_SECRET',
+  redirectUri: 'http://localhost:8888/callback',
+};
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('OAuth 2.0 token requests - public client (issue #1)', () => {
+  test('exchangeCodeForTokens sends client_id in the body and no auth header', async () => {
+    const { calls } = captureTokenRequest();
+
+    const tokens = await exchangeCodeForTokens(
+      PUBLIC_CLIENT,
+      'AUTH_CODE',
+      'CODE_VERIFIER'
+    );
+
+    expect(calls).toHaveLength(1);
+    const req = calls[0]!;
+    expect(req.url).toBe('https://api.twitter.com/2/oauth2/token');
+    expect(req.method).toBe('POST');
+    expect(req.headers['authorization']).toBeUndefined();
+    expect(req.headers['content-type']).toBe(
+      'application/x-www-form-urlencoded'
+    );
+    expect(req.body.get('client_id')).toBe('PUBLIC_CLIENT_ID');
+    expect(req.body.get('client_secret')).toBeNull();
+    expect(req.body.get('grant_type')).toBe('authorization_code');
+    expect(req.body.get('code')).toBe('AUTH_CODE');
+    expect(req.body.get('code_verifier')).toBe('CODE_VERIFIER');
+    expect(req.body.get('redirect_uri')).toBe(
+      'http://localhost:8888/callback'
+    );
+
+    expect(tokens.accessToken).toBe('ACCESS_TOKEN');
+    expect(tokens.refreshToken).toBe('NEW_REFRESH_TOKEN');
+  });
+
+  test('refreshAccessToken sends client_id in the body and no auth header', async () => {
+    const { calls } = captureTokenRequest();
+
+    await refreshAccessToken(PUBLIC_CLIENT, 'OLD_REFRESH_TOKEN');
+
+    expect(calls).toHaveLength(1);
+    const req = calls[0]!;
+    expect(req.url).toBe('https://api.twitter.com/2/oauth2/token');
+    expect(req.headers['authorization']).toBeUndefined();
+    expect(req.body.get('grant_type')).toBe('refresh_token');
+    expect(req.body.get('refresh_token')).toBe('OLD_REFRESH_TOKEN');
+    expect(req.body.get('client_id')).toBe('PUBLIC_CLIENT_ID');
+    expect(req.body.get('client_secret')).toBeNull();
+  });
+
+  test('revokeToken sends client_id in the body and no auth header', async () => {
+    const { calls } = captureTokenRequest();
+
+    await revokeToken(PUBLIC_CLIENT, 'SOME_ACCESS_TOKEN', 'access_token');
+
+    expect(calls).toHaveLength(1);
+    const req = calls[0]!;
+    expect(req.url).toBe('https://api.twitter.com/2/oauth2/revoke');
+    expect(req.headers['authorization']).toBeUndefined();
+    expect(req.body.get('token')).toBe('SOME_ACCESS_TOKEN');
+    expect(req.body.get('token_type_hint')).toBe('access_token');
+    expect(req.body.get('client_id')).toBe('PUBLIC_CLIENT_ID');
+  });
+});
+
+describe('OAuth 2.0 token requests - configured client secret (issue #1)', () => {
+  // This is the exact trigger of issue #1: a client_secret is present in the
+  // connector config (env var or ~/.hasna/connectors/connect-x/credentials.json)
+  // while the X app itself is registered as a public client. Sending Basic auth
+  // in that situation is what produced "Missing valid authorization header".
+  test('never falls back to Basic auth when a client secret is configured', async () => {
+    const { calls } = captureTokenRequest();
+
+    await exchangeCodeForTokens(
+      CONFIDENTIAL_CLIENT,
+      'AUTH_CODE',
+      'CODE_VERIFIER'
+    );
+    await refreshAccessToken(CONFIDENTIAL_CLIENT, 'OLD_REFRESH_TOKEN');
+    await revokeToken(CONFIDENTIAL_CLIENT, 'SOME_ACCESS_TOKEN');
+
+    expect(calls).toHaveLength(3);
+    for (const req of calls) {
+      expect(req.headers['authorization']).toBeUndefined();
+      expect(req.body.get('client_id')).toBe('CONFIDENTIAL_CLIENT_ID');
+    }
+  });
+
+  test('still authenticates the client via client_secret_post', async () => {
+    const { calls } = captureTokenRequest();
+
+    await exchangeCodeForTokens(
+      CONFIDENTIAL_CLIENT,
+      'AUTH_CODE',
+      'CODE_VERIFIER'
+    );
+
+    expect(calls[0]!.body.get('client_secret')).toBe(
+      'CONFIDENTIAL_CLIENT_SECRET'
+    );
+  });
+});
+
+describe('OAuth 2.0 token requests - error surfacing', () => {
+  test('exchangeCodeForTokens surfaces the X error payload', async () => {
+    globalThis.fetch = (async () =>
+      new Response(
+        JSON.stringify({
+          error: 'unauthorized_client',
+          error_description: 'Missing valid authorization header',
+        }),
+        { status: 400 }
+      )) as typeof fetch;
+
+    await expect(
+      exchangeCodeForTokens(PUBLIC_CLIENT, 'AUTH_CODE', 'CODE_VERIFIER')
+    ).rejects.toThrow(/Token exchange failed:.*unauthorized_client/s);
+  });
+});

package/connectors/zoominfo/.env.example

@@ -0,0 +1,4 @@
+ZOOMINFO_USERNAME=your_zoominfo_username
+ZOOMINFO_PASSWORD=your_zoominfo_password
+ZOOMINFO_JWT=your_zoominfo_jwt
+ZOOMINFO_BASE_URL=https://api.zoominfo.com

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);
+  });
+});