@hasna/connectors 0.9.0 → 0.9.2

package/connectors/connect-confluent/src/utils/storage.ts

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir } from './config';
+
+// ============================================
+// Generic Data Storage Utility
+// ============================================
+
+/**
+ * Base interface for storable entities
+ * All stored entities should have an id field
+ */
+export interface Storable {
+  id: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * Get the storage directory for an entity type
+ */
+function getStorageDir(entityType: string): string {
+  const dir = join(getConfigDir(), 'data', entityType);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Convert an ID to a safe filename
+ */
+function idToFilename(id: string): string {
+  return id.toLowerCase().replace(/[^a-z0-9]/g, '_') + '.json';
+}
+
+/**
+ * Get the file path for an entity
+ */
+function getEntityPath(entityType: string, id: string): string {
+  return join(getStorageDir(entityType), idToFilename(id));
+}
+
+/**
+ * Save an entity to storage
+ */
+export function saveEntity<T extends Storable>(entityType: string, entity: T): void {
+  const filepath = getEntityPath(entityType, entity.id);
+  const now = new Date().toISOString();
+
+  const existing = getEntity<T>(entityType, entity.id);
+
+  const data: T = {
+    ...entity,
+    createdAt: existing?.createdAt || now,
+    updatedAt: now,
+  };
+
+  writeFileSync(filepath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Get an entity by ID
+ */
+export function getEntity<T extends Storable>(entityType: string, id: string): T | null {
+  const filepath = getEntityPath(entityType, id);
+
+  if (!existsSync(filepath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filepath, 'utf-8');
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if an entity exists
+ */
+export function entityExists(entityType: string, id: string): boolean {
+  return existsSync(getEntityPath(entityType, id));
+}
+
+/**
+ * Get all entities of a type
+ */
+export function getAllEntities<T extends Storable>(entityType: string): T[] {
+  const storageDir = getStorageDir(entityType);
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+
+  const entities: T[] = [];
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(storageDir, file), 'utf-8');
+      entities.push(JSON.parse(content) as T);
+    } catch {
+      // Skip invalid files
+    }
+  }
+
+  return entities.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Delete an entity
+ */
+export function deleteEntity(entityType: string, id: string): boolean {
+  const filepath = getEntityPath(entityType, id);
+
+  if (existsSync(filepath)) {
+    unlinkSync(filepath);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Search entities by a predicate function
+ */
+export function searchEntities<T extends Storable>(
+  entityType: string,
+  predicate: (entity: T) => boolean
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  return all.filter(predicate);
+}
+
+/**
+ * Search entities by text match across all string fields
+ */
+export function searchEntitiesByText<T extends Storable>(
+  entityType: string,
+  query: string,
+  fields?: (keyof T)[]
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  const q = query.toLowerCase();
+
+  return all.filter(entity => {
+    const searchFields = fields || (Object.keys(entity) as (keyof T)[]);
+    return searchFields.some(field => {
+      const value = entity[field];
+      if (typeof value === 'string') {
+        return value.toLowerCase().includes(q);
+      }
+      return false;
+    });
+  });
+}
+
+/**
+ * Count entities of a type
+ */
+export function countEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+  return readdirSync(storageDir).filter(f => f.endsWith('.json')).length;
+}
+
+/**
+ * Clear all entities of a type
+ */
+export function clearEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    unlinkSync(join(storageDir, file));
+  }
+
+  return files.length;
+}
+
+/**
+ * Create a typed storage helper for a specific entity type
+ * This provides a cleaner API for working with a single entity type
+ */
+export function createStorage<T extends Storable>(entityType: string) {
+  return {
+    save: (entity: T) => saveEntity<T>(entityType, entity),
+    get: (id: string) => getEntity<T>(entityType, id),
+    exists: (id: string) => entityExists(entityType, id),
+    getAll: () => getAllEntities<T>(entityType),
+    delete: (id: string) => deleteEntity(entityType, id),
+    search: (predicate: (entity: T) => boolean) => searchEntities<T>(entityType, predicate),
+    searchByText: (query: string, fields?: (keyof T)[]) => searchEntitiesByText<T>(entityType, query, fields),
+    count: () => countEntities(entityType),
+    clear: () => clearEntities(entityType),
+  };
+}

package/connectors/connect-confluent/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}

package/connectors/connect-contactout/.env.example

@@ -0,0 +1,7 @@
+# ContactOut API Credentials
+# Get your API key from https://contactout.com/
+
+CONTACTOUT_API_KEY=your-api-key-here
+
+# Optional: Custom base URL (if needed)
+# CONTACTOUT_BASE_URL=https://api.contactout.com

package/connectors/connect-contactout/CLAUDE.md

@@ -0,0 +1,182 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## CRITICAL SECURITY RULES
+
+**NEVER expose API keys, tokens, or secrets:**
+- NEVER include API keys in emails, messages, or any external communication
+- NEVER log API keys to console or files
+- NEVER commit API keys to git (use .secrets/ or environment variables)
+- NEVER share API keys with anyone via any medium
+- If an API key is accidentally exposed, immediately request rotation
+
+## Project Overview
+
+connect-contactout is a TypeScript connector for the ContactOut API. It provides CLI and programmatic access to:
+- LinkedIn profile enrichment and contact info retrieval
+- People search and enrichment
+- Company search and domain enrichment
+- Email verification and reverse lookup
+- API usage statistics
+
+## Installation
+
+**IMPORTANT: Always install via bun, not npm.**
+
+```bash
+# Install globally (from this directory)
+bun link
+
+# This registers the CLI at ~/.bun/bin/connect-contactout
+# Make sure ~/.bun/bin is in your PATH
+
+# Verify installation
+connect-contactout --version
+```
+
+For development without global install:
+```bash
+bun run dev <command>
+```
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+
+# Run specific commands
+bun run dev profile list
+bun run dev config show
+bun run dev linkedin enrich <url>
+bun run dev company domain <domain>
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Use async/await for all async operations
+- Minimal dependencies: commander, chalk only
+- Type annotations required everywhere
+- Use interfaces for all API types
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # HTTP client with token auth
+│   ├── linkedin.ts   # LinkedIn profile/contact APIs
+│   ├── people.ts     # People search/enrich APIs
+│   ├── company.ts    # Company search/domain APIs
+│   ├── email.ts      # Email verify/enrich APIs
+│   ├── stats.ts      # Usage statistics API
+│   └── index.ts      # Main ContactOut class
+├── cli/
+│   └── index.ts      # CLI commands
+├── types/
+│   └── index.ts      # Type definitions
+├── utils/
+│   ├── config.ts     # Multi-profile configuration
+│   └── output.ts     # CLI output formatting
+└── index.ts          # Library exports
+```
+
+## API Endpoints
+
+### LinkedIn API
+- `linkedin enrich <url>` - Get full profile with contact info
+- `linkedin contact <url>` - Get emails/phones only
+- `linkedin batch <urls...>` - Batch contact info (max 30)
+- `linkedin check-email <url>` - Check email availability (free)
+- `linkedin check-phone <url>` - Check phone availability (free)
+
+### People API
+- `people search` - Search with filters (title, company, location, etc.)
+- `people count` - Count matching profiles (free)
+- `people enrich` - Enrich from multiple identifiers
+- `people decision-makers` - Get company decision makers
+
+### Company API
+- `company search` - Search by name, domain, size, industry
+- `company domain <domains...>` - Get company info from domains (free)
+
+### Email API
+- `email enrich <email>` - Get profile from email
+- `email verify <email>` - Verify email validity
+- `email to-linkedin <email>` - Find LinkedIn from email
+
+### Stats API
+- `stats show` - Show usage statistics
+- `stats current` - Show current month usage
+
+## Authentication
+
+ContactOut uses token header authentication:
+```
+token: <YOUR_API_TOKEN>
+```
+
+**Note:** Trial/demo API keys return sample data with a message to contact sales for full access. If you see responses like "This is a sample response", the API key needs to be upgraded for production use.
+
+## Multi-Profile Configuration
+
+Profiles stored in `~/.connect/connect-contactout/profiles/`:
+- Each profile is a separate JSON file
+- `current_profile` file tracks active profile
+- `--profile` flag overrides for single command
+- `CONTACTOUT_API_KEY` env var overrides profile config
+
+### Profile Commands
+```bash
+connect-contactout profile list
+connect-contactout profile create <name> --api-key <key>
+connect-contactout profile use <name>
+connect-contactout profile show [name]
+connect-contactout profile delete <name>
+```
+
+## Secrets
+
+API key stored in `.secrets/api-key.json` (gitignored):
+```json
+{
+  "apiKey": "your-key-here"
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CONTACTOUT_API_KEY` | API key (overrides profile) |
+| `CONTACTOUT_BASE_URL` | Override base URL (default: https://api.contactout.com) |
+
+## Rate Limits
+
+- People Search: 60 requests/minute
+- Contact Checker: 150 requests/minute
+- Other endpoints: 1000 requests/minute
+
+## Credit Costs
+
+- Search credit: Finding profiles
+- Email credit: Getting email addresses
+- Phone credit: Getting phone numbers
+- Verifier credit: Email verification
+
+Free endpoints (no credits):
+- `company domain` - Domain enrichment
+- `people count` - Profile counting
+- `linkedin check-email/phone` - Availability checks

package/connectors/connect-contactout/README.md

@@ -0,0 +1,186 @@
+# connect-contactout
+
+ContactOut API connector - Find emails, phone numbers, and enrich LinkedIn profiles.
+
+## Installation
+
+```bash
+# Install globally
+bun install -g @hasna/connect-contactout
+
+# Or run locally
+bun install
+bun run dev
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+connect-contactout config set-key <your-api-key>
+
+# Enrich a LinkedIn profile
+connect-contactout linkedin enrich "https://www.linkedin.com/in/username"
+
+# Get company info from domain (free, no credits)
+connect-contactout company domain google.com
+
+# Search for people
+connect-contactout people search --company "Google" --title "Engineer" --location "San Francisco"
+
+# Verify an email
+connect-contactout email verify test@example.com
+
+# Check API usage
+connect-contactout stats show
+```
+
+## Multi-Profile Support
+
+```bash
+# Create a profile
+connect-contactout profile create work --api-key <key> --use
+
+# Switch profiles
+connect-contactout profile use personal
+
+# List profiles
+connect-contactout profile list
+
+# Use a profile for single command
+connect-contactout -p work linkedin enrich <url>
+```
+
+## Commands
+
+### LinkedIn
+
+```bash
+# Enrich profile with contact info
+connect-contactout linkedin enrich <url>
+connect-contactout linkedin enrich <url> --profile-only  # Without contact info
+
+# Get contact info only
+connect-contactout linkedin contact <url> --phone --email-type personal
+
+# Batch requests
+connect-contactout linkedin batch <url1> <url2> <url3>
+connect-contactout linkedin batch-async <urls...> --phone --callback <webhook-url>
+connect-contactout linkedin job <job-id>
+
+# Check availability (free)
+connect-contactout linkedin check-email <url>
+connect-contactout linkedin check-phone <url>
+```
+
+### People
+
+```bash
+# Search
+connect-contactout people search --name "John" --company "Google" --title "Engineer"
+connect-contactout people search --location "NYC" --industry "Technology" --reveal
+
+# Count (free)
+connect-contactout people count --company "Google" --title "Engineer"
+
+# Enrich
+connect-contactout people enrich --email test@google.com --name "John Doe"
+connect-contactout people enrich --linkedin <url> --include work_email phone
+
+# Decision makers
+connect-contactout people decision-makers --domain google.com
+connect-contactout people decision-makers --name "Google" --reveal
+```
+
+### Company
+
+```bash
+# Search
+connect-contactout company search --name "Google" --industry "Technology"
+connect-contactout company search --size "1000+" --location "California"
+
+# Domain enrichment (free)
+connect-contactout company domain google.com microsoft.com apple.com
+```
+
+### Email
+
+```bash
+# Enrich from email
+connect-contactout email enrich test@example.com
+
+# Verify
+connect-contactout email verify test@example.com
+connect-contactout email verify-batch email1@test.com email2@test.com
+connect-contactout email verify-job <job-id>
+
+# Find LinkedIn from email
+connect-contactout email to-linkedin test@example.com
+```
+
+### Stats
+
+```bash
+connect-contactout stats show
+connect-contactout stats show --period 2024-01
+connect-contactout stats current
+```
+
+## Output Formats
+
+```bash
+# Pretty print (default)
+connect-contactout linkedin enrich <url>
+
+# JSON output
+connect-contactout -f json linkedin enrich <url>
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CONTACTOUT_API_KEY` | API key (overrides profile config) |
+| `CONTACTOUT_BASE_URL` | Override base URL |
+
+## Programmatic Usage
+
+```typescript
+import { ContactOut } from '@hasna/connect-contactout';
+
+const client = new ContactOut({ apiKey: 'your-key' });
+
+// Or from environment
+const client = ContactOut.fromEnv();
+
+// LinkedIn enrichment
+const profile = await client.linkedin.enrich({
+  profile: 'https://linkedin.com/in/username',
+});
+
+// Company domain (free)
+const companies = await client.company.enrichFromDomains({
+  domains: ['google.com', 'microsoft.com'],
+});
+
+// People search
+const results = await client.people.search({
+  company: ['Google'],
+  job_title: ['Engineer'],
+  location: ['San Francisco'],
+  reveal_info: true,
+});
+
+// Email verification
+const status = await client.email.verify('test@example.com');
+```
+
+## Rate Limits
+
+- People Search: 60 requests/minute
+- Contact Checker: 150 requests/minute
+- Other endpoints: 1000 requests/minute
+
+## License
+
+Apache-2.0

package/connectors/connect-contactout/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hasna/connect-contactout",
+  "version": "0.0.1",
+  "description": "ContactOut API connector - Find emails, phone numbers, and enrich LinkedIn profiles",
+  "type": "module",
+  "bin": {
+    "connect-contactout": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --emitDeclarationOnly --outDir ./dist && 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",
+    "release": "bun run ./scripts/publish.ts",
+    "release:patch": "bun run ./scripts/publish.ts patch",
+    "release:minor": "bun run ./scripts/publish.ts minor",
+    "release:dry": "bun run ./scripts/publish.ts --dry-run"
+  },
+  "keywords": [
+    "contactout",
+    "linkedin",
+    "email",
+    "enrichment",
+    "api",
+    "connector",
+    "cli"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  }
+}