@hasna/connectors 1.3.45 → 1.3.46

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

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { ZoomInfo } from "../api";
+import type { HttpMethod, JsonObject, JsonValue, OutputFormat, QueryPrimitive, QueryValue } from "../types";
+import {
+  clearConfig,
+  getBaseUrl,
+  getJwt,
+  getPassword,
+  getUsername,
+  loadConfig,
+  setBaseUrl,
+  setJwt,
+  setPassword,
+  setUsername,
+} from "../utils/config";
+import { error, info, print, success } from "../utils/output";
+
+const CONNECTOR_NAME = "connect-zoominfo";
+const VERSION = "0.0.1";
+
+const program = new Command();
+
+program
+  .name(CONNECTOR_NAME)
+  .description("ZoomInfo B2B sales intelligence API CLI")
+  .version(VERSION)
+  .option("-f, --format <format>", "Output format (json, pretty)", "pretty")
+  .option("--username <username>", "ZoomInfo API username")
+  .option("--password <password>", "ZoomInfo API password")
+  .option("--jwt <jwt>", "Preconfigured ZoomInfo JWT (skips /authenticate)")
+  .option("--base-url <url>", "Override ZoomInfo API base URL");
+
+function getFormat(): OutputFormat {
+  return (program.opts().format || "pretty") as OutputFormat;
+}
+
+function getCliOptions(): Record<string, unknown> {
+  return program.opts() as Record<string, unknown>;
+}
+
+function client(): ZoomInfo {
+  const opts = getCliOptions();
+  return new ZoomInfo({
+    username: optionString(opts, "username") || getUsername(),
+    password: optionString(opts, "password") || getPassword(),
+    jwt: optionString(opts, "jwt") || getJwt(),
+    baseUrl: optionString(opts, "baseUrl") || getBaseUrl(),
+  });
+}
+
+function parseJsonValue(value: string | undefined, label: string, fallback: JsonValue | undefined): JsonValue | undefined {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value) as JsonValue;
+  } catch (err) {
+    throw new Error(`Invalid ${label}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function parseJsonObject(value: string | undefined, label: string, fallback: JsonObject = {}): JsonObject {
+  const parsed = parseJsonValue(value, label, fallback);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`${label} must be a JSON object`);
+  return parsed as JsonObject;
+}
+
+function toQueryValue(value: unknown, label: string): QueryValue {
+  if (value === undefined || value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item !== "string" && typeof item !== "number" && typeof item !== "boolean") {
+        throw new Error(`Invalid ${label}: arrays must contain strings, numbers, or booleans`);
+      }
+    }
+    return value as QueryPrimitive[];
+  }
+  throw new Error(`Invalid ${label}: expected string, number, boolean, array, null, or undefined`);
+}
+
+function parseParams(value: unknown): Record<string, QueryValue> {
+  const parsed = parseJsonObject(typeof value === "string" ? value : undefined, "params");
+  const params: Record<string, QueryValue> = {};
+  for (const [key, rawValue] of Object.entries(parsed)) params[key] = toQueryValue(rawValue, `params.${key}`);
+  return params;
+}
+
+function parseHeaders(value: unknown): Record<string, string> {
+  const parsed = parseJsonObject(typeof value === "string" ? value : undefined, "headers");
+  const headers: Record<string, string> = {};
+  for (const [key, rawValue] of Object.entries(parsed)) {
+    if (typeof rawValue !== "string") throw new Error(`headers.${key} must be a string`);
+    headers[key] = rawValue;
+  }
+  return headers;
+}
+
+function optionString(opts: Record<string, unknown>, key: string): string | undefined {
+  const value = opts[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function optionBody(opts: Record<string, unknown>, fallback: JsonValue = {}): JsonValue {
+  return parseJsonValue(optionString(opts, "body"), "body", fallback) ?? fallback;
+}
+
+async function run(action: () => Promise<unknown>): Promise<void> {
+  try {
+    print(await action(), getFormat());
+  } catch (err) {
+    error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+const configCmd = program.command("config").description("Manage CLI configuration");
+
+configCmd.command("set-username <username>").description("Store a ZoomInfo API username").action((username: string) => {
+  setUsername(username);
+  success("Username saved");
+});
+
+configCmd.command("set-password <password>").description("Store a ZoomInfo API password").action((password: string) => {
+  setPassword(password);
+  success("Password saved");
+});
+
+configCmd.command("set-jwt <jwt>").description("Store a preconfigured ZoomInfo JWT").action((jwt: string) => {
+  setJwt(jwt);
+  success("JWT saved");
+});
+
+configCmd.command("set-base-url <baseUrl>").description("Set a custom ZoomInfo API base URL").action((baseUrl: string) => {
+  setBaseUrl(baseUrl);
+  success(`Base URL set to ${baseUrl}`);
+});
+
+configCmd.command("show").description("Show current configuration").action(() => {
+  const api = client();
+  const config = loadConfig();
+  info(`Username: ${getUsername() ? "configured" : "not set"}`);
+  info(`Password: ${getPassword() ? "configured" : "not set"}`);
+  info(`JWT: ${getJwt() ? "configured" : "not set"}`);
+  info(`Base URL: ${api.getBaseUrl()}`);
+  if (Object.keys(config).length > 0) info("Stored config file is present");
+});
+
+configCmd.command("clear").description("Clear saved configuration").action(() => {
+  clearConfig();
+  success("Configuration cleared");
+});
+
+program.command("authenticate").description("Authenticate with username/password and obtain a JWT").action(() => run(() => client().authenticate()));
+program.command("search-contacts").description("Search ZoomInfo contacts").option("--body <json>", "JSON request body", "{}").option("--params <json>", "Query parameters as JSON object").action((opts: Record<string, unknown>) => run(() => client().searchContacts(optionBody(opts), parseParams(opts.params))));
+program.command("search-companies").description("Search ZoomInfo companies").option("--body <json>", "JSON request body", "{}").option("--params <json>", "Query parameters as JSON object").action((opts: Record<string, unknown>) => run(() => client().searchCompanies(optionBody(opts), parseParams(opts.params))));
+program.command("enrich-contact").description("Enrich contacts (requires matchPersonInput in body)").requiredOption("--body <json>", "JSON request body with matchPersonInput").action((opts: Record<string, unknown>) => run(() => client().enrichContact(optionBody(opts))));
+program.command("enrich-company").description("Enrich companies").option("--body <json>", "JSON request body", "{}").action((opts: Record<string, unknown>) => run(() => client().enrichCompany(optionBody(opts))));
+program.command("lookup-contact <contactId>").description("Look up a contact by ZoomInfo ID").action((contactId: string) => run(() => client().lookupContact(contactId)));
+program.command("contact-search-output-fields").description("List available contact search output fields").action(() => run(() => client().listContactSearchOutputFields()));
+program.command("company-search-output-fields").description("List available company search output fields").action(() => run(() => client().listCompanySearchOutputFields()));
+
+program
+  .command("raw-request <method> <path>")
+  .description("Send a raw relative ZoomInfo request")
+  .option("--params <json>", "Query parameters as JSON object")
+  .option("--body <json>", "JSON request body")
+  .option("--headers <json>", "Additional headers as JSON object")
+  .option("--no-auth", "Do not attach Bearer JWT")
+  .action((method: string, path: string, opts: Record<string, unknown>) =>
+    run(() =>
+      client().rawRequest(method.toUpperCase() as HttpMethod, path, {
+        params: parseParams(opts.params),
+        body: parseJsonValue(optionString(opts, "body"), "body", undefined),
+        headers: parseHeaders(opts.headers),
+        auth: opts.auth !== false,
+      }),
+    ),
+  );
+
+program.parse();

package/connectors/zoominfo/src/index.ts

@@ -0,0 +1,3 @@
+export { ZoomInfoClient, ZoomInfoClient as ZoomInfo } from "./api";
+export * from "./api";
+export * from "./types";

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

@@ -0,0 +1,39 @@
+export type OutputFormat = "json" | "pretty";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+
+export interface JsonObject {
+  [key: string]: JsonValue | undefined;
+}
+
+export type QueryPrimitive = string | number | boolean;
+export type QueryValue = QueryPrimitive | QueryPrimitive[] | null | undefined;
+
+export interface ZoomInfoConfig {
+  username?: string;
+  password?: string;
+  jwt?: string;
+  baseUrl?: string;
+}
+
+export interface RequestOptions {
+  method?: HttpMethod;
+  params?: Record<string, QueryValue>;
+  body?: JsonValue | string;
+  headers?: Record<string, string>;
+  responseType?: "json" | "text";
+  auth?: boolean;
+}
+
+export class ZoomInfoApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status?: number,
+    public readonly data?: unknown,
+  ) {
+    super(message);
+    this.name = "ZoomInfoApiError";
+  }
+}

package/connectors/zoominfo/src/utils/config.ts

@@ -0,0 +1,61 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+interface StoredConfig {
+  username?: string;
+  password?: string;
+  jwt?: string;
+  baseUrl?: string;
+}
+
+const CONFIG_PATH = join(homedir(), ".hasna", "connectors", "zoominfo", "config.json");
+
+export function loadConfig(): StoredConfig {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as StoredConfig;
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config: StoredConfig): void {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function clearConfig(): void {
+  rmSync(CONFIG_PATH, { force: true });
+}
+
+export function getUsername(): string | undefined {
+  return process.env.ZOOMINFO_USERNAME || loadConfig().username;
+}
+
+export function setUsername(username: string): void {
+  saveConfig({ ...loadConfig(), username });
+}
+
+export function getPassword(): string | undefined {
+  return process.env.ZOOMINFO_PASSWORD || loadConfig().password;
+}
+
+export function setPassword(password: string): void {
+  saveConfig({ ...loadConfig(), password });
+}
+
+export function getJwt(): string | undefined {
+  return process.env.ZOOMINFO_JWT || loadConfig().jwt;
+}
+
+export function setJwt(jwt: string): void {
+  saveConfig({ ...loadConfig(), jwt });
+}
+
+export function getBaseUrl(): string | undefined {
+  return process.env.ZOOMINFO_BASE_URL || loadConfig().baseUrl;
+}
+
+export function setBaseUrl(baseUrl: string): void {
+  saveConfig({ ...loadConfig(), baseUrl });
+}

package/connectors/zoominfo/src/utils/output.ts

@@ -0,0 +1,27 @@
+import type { OutputFormat } from "../types";
+
+export function print(value: unknown, format: OutputFormat = "pretty"): void {
+  if (format === "json") {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  if (typeof value === "string") {
+    console.log(value);
+    return;
+  }
+
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export function success(message: string): void {
+  console.log(message);
+}
+
+export function info(message: string): void {
+  console.log(message);
+}
+
+export function error(message: string): void {
+  console.error(message);
+}

package/connectors/zoominfo/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}

package/connectors/zotero/.env.example

@@ -0,0 +1,7 @@
+# Zotero API Configuration
+ZOTERO_API_KEY=your-zotero-api-key-here
+ZOTERO_LIBRARY_ID=your-user-or-group-library-id
+ZOTERO_LIBRARY_TYPE=users
+
+# Optional: Override the default API base URL
+# ZOTERO_BASE_URL=https://api.zotero.org

package/connectors/zotero/.npmrc.example

@@ -0,0 +1,2 @@
+@hasna:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}

package/connectors/zotero/AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS.md
+
+Guidance for AI agents working with connect-zotero.
+
+## Overview
+
+Zotero Web API v3 connector with API-key auth, multi-profile config, and CLI/library entry points.
+
+## Quick Commands
+
+```bash
+bun install
+bun run dev
+bun run build
+bun run typecheck
+bun test
+```
+
+## Key Features
+
+- Items: list, search, get, create, update, delete
+- Collections: list, get, create
+- Attachments: URL/file attachments and 3-step file upload
+- Raw request escape hatch for unlisted endpoints
+- Multi-profile config under `~/.hasna/connectors/connect-zotero/`
+
+## Environment
+
+| Variable | Description |
+|----------|-------------|
+| `ZOTERO_API_KEY` | API key |
+| `ZOTERO_LIBRARY_ID` | Library ID |
+| `ZOTERO_LIBRARY_TYPE` | `users` or `groups` |
+| `ZOTERO_BASE_URL` | Optional API base URL |
+
+## Security
+
+- Never commit real API keys
+- `.env.example` contains placeholders only
+- No browser-use or scraper dependencies

package/connectors/zotero/CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+connect-zotero is a TypeScript CLI and library for the Zotero Web API v3. It provides item, collection, and attachment management with multi-profile API key configuration.
+
+## Build & Run Commands
+
+```bash
+bun install           # Install dependencies
+bun run dev           # Run CLI in development
+bun run build         # Build for distribution
+bun run typecheck     # Type check
+bun test              # Run connector tests
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts       # HTTP client with Zotero-API-Key auth
+│   ├── items.ts        # Items CRUD and search
+│   ├── collections.ts  # Collections list/create
+│   ├── attachments.ts  # Attachment create and file upload
+│   └── index.ts        # Main Zotero class
+├── cli/
+│   └── index.ts        # CLI commands
+├── types/
+│   └── index.ts        # TypeScript types
+├── utils/
+│   ├── config.ts       # Multi-profile configuration
+│   └── output.ts       # CLI output formatting
+└── index.ts            # Library exports
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ZOTERO_API_KEY` | Zotero API key (Zotero-API-Key header) |
+| `ZOTERO_LIBRARY_ID` | User or group library ID |
+| `ZOTERO_LIBRARY_TYPE` | `users` (default) or `groups` |
+| `ZOTERO_BASE_URL` | Optional override (default https://api.zotero.org) |
+
+## Authentication
+
+Auth type: **apikey** (no OAuth). Config dir: `~/.hasna/connectors/connect-zotero/profiles/{name}/config.json`
+
+## API Notes
+
+- Base URL: https://api.zotero.org
+- Required headers: `Zotero-API-Key`, `Zotero-API-Version: 3`
+- Update/delete require `If-Unmodified-Since-Version` with the item version
+- File upload uses a 3-step protocol: auth POST → S3 POST → register POST
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/zotero/README.md

@@ -0,0 +1,91 @@
+# @hasna/connect-zotero
+
+Zotero Web API v3 connector with CLI and library support. Manage bibliography items, collections, and file attachments via the official Zotero REST API.
+
+## Installation
+
+```bash
+bun add @hasna/connect-zotero
+```
+
+For CLI usage:
+
+```bash
+bun install -g @hasna/connect-zotero
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export ZOTERO_API_KEY="your-api-key"
+export ZOTERO_LIBRARY_ID="your-library-id"
+export ZOTERO_LIBRARY_TYPE="users"   # or groups
+# export ZOTERO_BASE_URL="https://api.zotero.org"
+```
+
+### CLI Configuration
+
+```bash
+connect-zotero config set-api-key <key>
+connect-zotero config set-library-id <id>
+connect-zotero config set-library-type users
+connect-zotero config show
+```
+
+Configuration is stored in `~/.hasna/connectors/connect-zotero/`.
+
+## CLI Usage
+
+```bash
+# Test authentication
+connect-zotero test
+
+# List items
+connect-zotero items list
+connect-zotero items list --collection <key> --limit 25
+
+# Search items
+connect-zotero items search "machine learning"
+
+# Get, create, update, delete items
+connect-zotero items get <itemKey>
+connect-zotero items create --json ./item.json
+connect-zotero items update <itemKey> --json ./patch.json --version 12
+connect-zotero items delete <itemKey> --version 12
+
+# Collections
+connect-zotero collections list
+connect-zotero collections create --json ./collection.json
+
+# Attachments
+connect-zotero attachments create --json ./attachment.json
+connect-zotero attachments upload --file ./paper.pdf --parent <itemKey>
+
+# Raw API escape hatch
+connect-zotero raw /users/1234567/items -X GET
+```
+
+## Library Usage
+
+```typescript
+import { Zotero } from '@hasna/connect-zotero';
+
+const zotero = new Zotero({
+  apiKey: process.env.ZOTERO_API_KEY!,
+  libraryId: process.env.ZOTERO_LIBRARY_ID!,
+  libraryType: 'users',
+});
+
+const items = await zotero.items.list({ limit: 10 });
+const results = await zotero.items.search('neural networks');
+```
+
+## API Reference
+
+- [Zotero Web API v3](https://www.zotero.org/support/dev/web_api/v3/start)
+
+## License
+
+Apache-2.0

package/connectors/zotero/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hasna/connect-zotero",
+  "version": "0.0.1",
+  "description": "Zotero Web API v3 connector with CLI and library support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "connect-zotero": "bin/index.js"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "zotero",
+    "api",
+    "cli",
+    "connector",
+    "bibliography",
+    "citations"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "CLAUDE.md"
+  ]
+}