@hasna/connectors 0.7.2 → 0.8.0

package/connectors/connect-acquire/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-acquire/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-actionnetwork/.env.example

@@ -0,0 +1,11 @@
+# API Credentials
+# TODO: Update variable names and instructions for your API
+# Example: PERPLEXITY_API_KEY, OPENAI_API_KEY, etc.
+
+CONNECTOR_API_KEY=your-api-key-here
+
+# Optional: API secret (if your API requires it)
+# CONNECTOR_API_SECRET=your-api-secret-here
+
+# Optional: Custom base URL (if needed)
+# CONNECTOR_BASE_URL=https://api.example.com

package/connectors/connect-actionnetwork/CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+connect-actionnetwork is a TypeScript connector for the Action Network API v2. Action Network is a progressive organizing platform for petitions, events, fundraising, advocacy campaigns, email messaging, and people management. It follows the OSDI (Open Supporter Data Interface) specification.
+
+## API Details
+
+- **Base URL**: `https://actionnetwork.org/api/v2`
+- **Auth**: Custom header `OSDI-API-Token: <api_key>`
+- **Format**: HAL+JSON (OSDI spec v1.1.1)
+- **Rate Limits**: 4 requests/second, messages limited to 1 POST/30 seconds
+
+## Build & Run Commands
+
+```bash
+bun install
+bun run dev                    # Run CLI in development
+bun run build                  # Build for distribution
+bun run typecheck              # Type check
+
+# Example commands
+bun run dev people list
+bun run dev petitions list --filter "modified_date gt '2024-01-01'"
+bun run dev events create --title "Town Hall" --start-date "2024-06-01T18:00:00Z"
+bun run dev tags create --name "Volunteer"
+bun run dev fundraising donations <pageId>
+```
+
+## API Modules
+
+| Module | Resource | Endpoints |
+|--------|----------|-----------|
+| `people` | People/Activists | list, get, signup, update |
+| `petitions` | Petitions | list, get, create, update, listSignatures, createSignature |
+| `events` | Events | list, get, create, update, listAttendances, createAttendance |
+| `forms` | Forms | list, get, create, update, listSubmissions, createSubmission |
+| `fundraising` | Fundraising Pages | list, get, create, update, listDonations, createDonation |
+| `tags` | Tags | list, get, create, listTaggings, createTagging, deleteTagging |
+| `messages` | Email Messages | list, get, create, update |
+| `advocacy` | Advocacy Campaigns | list, get, create, update, listOutreaches |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ACTION_NETWORK_API_KEY` | OSDI API token (overrides profile) |
+| `ACTION_NETWORK_TOKEN` | Token alias for API key |
+| `ACTION_NETWORK_API_SECRET` | API secret (optional) |
+
+## Key Patterns
+
+### HAL+JSON Response Format
+
+All list endpoints return HAL collections:
+```json
+{
+  "_links": { "self": { "href": "..." }, "next": { "href": "..." } },
+  "_embedded": { "osdi:people": [...] },
+  "total_pages": 5,
+  "per_page": 25,
+  "page": 1,
+  "total_records": 120
+}
+```
+
+### OData Filtering
+
+List endpoints support OData `$filter` for date-based queries:
+```
+filter=modified_date gt '2024-01-01'
+filter=created_date lt '2024-06-01'
+```
+
+### Person Signup (Upsert)
+
+POST to `/people` acts as upsert - creates new or updates existing based on email match.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `people list/get/signup/update` | Manage activists |
+| `petitions list/get/create/update/signatures/sign` | Petition campaigns |
+| `events list/get/create/update/attendances/attend` | Event management |
+| `forms list/get/create/update/submissions/submit` | Form management |
+| `fundraising list/get/create/update/donations/donate` | Fundraising |
+| `tags list/get/create/taggings/tag-person/untag` | Tag management |
+| `messages list/get/create/update` | Email messaging |
+| `advocacy list/get/create/update/outreaches` | Advocacy campaigns |
+| `profile list/use/create/delete/show` | Profile management |
+| `config set-key/show/clear` | Configuration |

package/connectors/connect-actionnetwork/README.md

@@ -0,0 +1,193 @@
+# scaffold-connector
+
+A TypeScript scaffold for building API connector CLIs with multi-profile support.
+
+## Features
+
+- Multi-profile configuration (switch between different API keys/accounts)
+- Bearer token authentication (easily customizable)
+- Clean CLI structure with Commander.js
+- Pretty and JSON output formats
+- TypeScript with strict mode
+
+## Quick Start
+
+### 1. Clone and Rename
+
+```bash
+# Clone for your connector
+git clone https://github.com/hasna/scaffold-connector.git connect-yourapi
+cd connect-yourapi
+
+# Update package.json name
+# Change "@hasna/scaffold-connector" to "@hasna/connect-yourapi"
+```
+
+### 2. Update Configuration
+
+Search for `TODO` comments throughout the codebase and update:
+
+- `src/cli/index.ts` - Update `CONNECTOR_NAME` and description
+- `src/utils/config.ts` - Update `CONNECTOR_NAME` and env var names
+- `src/api/client.ts` - Update `DEFAULT_BASE_URL` and authentication method
+- `src/api/index.ts` - Rename `Connector` class to your API name
+- `src/types/index.ts` - Add your API's type definitions
+- `package.json` - Update name, description, bin command
+- `.env.example` - Update environment variable names
+
+### 3. Install and Test
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI
+bun run dev
+
+# Or run specific commands
+bun run dev profile list
+bun run dev config show
+```
+
+## CLI Structure
+
+```bash
+connector [options] [command]
+
+Options:
+  -k, --api-key <key>      API key (overrides config)
+  -f, --format <format>    Output format (json, pretty)
+  -p, --profile <profile>  Use a specific profile
+
+Commands:
+  profile list             List all profiles
+  profile use <name>       Switch to a profile
+  profile create <name>    Create a new profile
+  profile delete <name>    Delete a profile
+  profile show [name]      Show profile configuration
+
+  config set-key <key>     Set API key for active profile
+  config show              Show current configuration
+  config clear             Clear configuration
+
+  example list             Example API command (replace)
+  example get <id>         Example API command (replace)
+  example create           Example API command (replace)
+```
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # HTTP client with authentication
+│   ├── example.ts    # Example API module (replace with your API)
+│   └── index.ts      # Main connector 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
+```
+
+## Multi-Profile Configuration
+
+Profiles are stored in `~/.connect/{connector-name}/profiles/`:
+
+```
+~/.connect/connector/
+├── current_profile   # Name of active profile
+└── profiles/
+    ├── default.json  # Default profile
+    ├── work.json     # Named profile
+    └── personal.json # Named profile
+```
+
+### Profile Commands
+
+```bash
+# Create profiles
+connector profile create work --api-key sk-xxx --use
+connector profile create personal --api-key sk-yyy
+
+# Switch profiles
+connector profile use work
+
+# Use profile for single command
+connector -p personal example list
+
+# List profiles
+connector profile list
+```
+
+## Customizing Authentication
+
+Edit `src/api/client.ts` to change authentication:
+
+```typescript
+// Bearer token (default)
+'Authorization': `Bearer ${this.apiKey}`,
+
+// API Key header
+'X-API-Key': this.apiKey,
+
+// Basic auth
+'Authorization': `Basic ${Buffer.from(`${this.apiKey}:${this.apiSecret}`).toString('base64')}`,
+```
+
+## Adding API Endpoints
+
+1. Create a new file in `src/api/` (e.g., `users.ts`)
+2. Export it from `src/api/index.ts`
+3. Add types in `src/types/index.ts`
+4. Add CLI commands in `src/cli/index.ts`
+
+Example API module:
+
+```typescript
+// src/api/users.ts
+import type { ConnectorClient } from './client';
+
+export class UsersApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(options?: { limit?: number }) {
+    return this.client.get('/users', { limit: options?.limit });
+  }
+
+  async get(id: string) {
+    return this.client.get(`/users/${id}`);
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CONNECTOR_API_KEY` | API key (overrides profile config) |
+| `CONNECTOR_API_SECRET` | API secret (optional) |
+| `CONNECTOR_BASE_URL` | Override base URL (optional) |
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+MIT

package/connectors/connect-actionnetwork/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hasna/connect-actionnetwork",
+  "version": "0.0.1",
+  "description": "Action Network API connector - progressive organizing platform (petitions, events, fundraising, advocacy, email)",
+  "type": "module",
+  "bin": {
+    "connect-actionnetwork": "./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",
+    "release": "bun run scripts/release.ts",
+    "release:dry": "bun run scripts/release.ts --dry-run"
+  },
+  "keywords": [
+    "action-network",
+    "actionnetwork",
+    "organizing",
+    "petitions",
+    "events",
+    "fundraising",
+    "advocacy",
+    "osdi",
+    "connector"
+  ],
+  "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/connect-actionnetwork.git"
+  }
+}