@hasna/connectors 1.3.45 → 1.4.0

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";

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