@hasna/connectors 0.7.2 → 0.8.0

package/connectors/connect-accurai/src/utils/settings.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir, ensureConfigDir } from './config';
+
+// ============================================
+// Settings Storage Utility
+// ============================================
+
+/**
+ * TODO: Define your connector-specific settings
+ * Add fields for user preferences, defaults, etc.
+ */
+export interface Settings {
+  // Display settings
+  defaultFormat: 'json' | 'table' | 'pretty';
+
+  // Behavior settings
+  confirmDestructive: boolean;  // Require confirmation for destructive operations
+  verboseOutput: boolean;       // Enable verbose output by default
+
+  // API settings
+  defaultMaxResults: number;    // Default page size for list operations
+  requestTimeout: number;       // Request timeout in ms
+
+  // Add more settings as needed for your connector
+}
+
+const DEFAULT_SETTINGS: Settings = {
+  defaultFormat: 'pretty',
+  confirmDestructive: true,
+  verboseOutput: false,
+  defaultMaxResults: 20,
+  requestTimeout: 30000,
+};
+
+function getSettingsPath(): string {
+  return join(getConfigDir(), 'settings.json');
+}
+
+/**
+ * Load settings from disk, merging with defaults
+ */
+export function loadSettings(): Settings {
+  ensureConfigDir();
+  const filepath = getSettingsPath();
+
+  if (!existsSync(filepath)) {
+    // Create default settings file
+    saveSettings(DEFAULT_SETTINGS);
+    return DEFAULT_SETTINGS;
+  }
+
+  try {
+    const content = readFileSync(filepath, 'utf-8');
+    const loaded = JSON.parse(content);
+    // Merge with defaults to ensure all fields exist
+    return { ...DEFAULT_SETTINGS, ...loaded };
+  } catch {
+    return DEFAULT_SETTINGS;
+  }
+}
+
+/**
+ * Save settings to disk
+ */
+export function saveSettings(settings: Settings): void {
+  ensureConfigDir();
+  const filepath = getSettingsPath();
+  writeFileSync(filepath, JSON.stringify(settings, null, 2));
+}
+
+/**
+ * Get a specific setting value
+ */
+export function getSetting<K extends keyof Settings>(key: K): Settings[K] {
+  return loadSettings()[key];
+}
+
+/**
+ * Set a specific setting value
+ */
+export function setSetting<K extends keyof Settings>(key: K, value: Settings[K]): void {
+  const settings = loadSettings();
+  settings[key] = value;
+  saveSettings(settings);
+}
+
+/**
+ * Reset settings to defaults
+ */
+export function resetSettings(): void {
+  saveSettings(DEFAULT_SETTINGS);
+}
+
+/**
+ * Get default settings (useful for CLI help text)
+ */
+export function getDefaultSettings(): Settings {
+  return { ...DEFAULT_SETTINGS };
+}
+
+/**
+ * Check if verbose output is enabled
+ */
+export function isVerbose(): boolean {
+  return loadSettings().verboseOutput;
+}
+
+/**
+ * Check if destructive operations need confirmation
+ */
+export function needsConfirmation(): boolean {
+  return loadSettings().confirmDestructive;
+}

package/connectors/connect-accurai/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-accurai/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-accuranker/.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-accuranker/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+AccuRanker connector - a TypeScript CLI and library for interacting with the AccuRanker SEO rank tracking API. Provides keyword rank tracking, domain management, and SERP monitoring.
+
+## 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
+```
+
+## API Details
+
+- **Base URL**: `https://app.accuranker.com/api/v4/`
+- **Auth**: Token-based (`Authorization: Token <api-token>`)
+- **Rate Limits**: 100 requests/minute (read), 500 burst (write)
+
+### Read API (GET endpoints - trailing slashes)
+
+- `GET /accounts/` - List accounts
+- `GET /accounts/{id}/` - Get account
+- `GET /domains/` - List domains
+- `GET /domains/{id}/` - Get domain
+- `GET /domains/{id}/keywords/` - List keywords
+- `GET /domains/{id}/keywords/{kid}/` - Get keyword
+- `GET /domains/{id}/landing_pages/` - List landing pages
+- `GET /domains/{id}/landing_pages/{pid}/` - Get landing page
+- `GET /domains/{id}/tags/` - List tags
+
+### Write API (POST/PUT/DELETE - no trailing slashes)
+
+- `POST /domain/` - Create domain
+- `PUT /domain/{id}` - Update domain
+- `DELETE /domain/{id}` - Delete domain
+- `POST /keyword/` - Create keywords (async, returns 202)
+- `PUT /keyword/` - Update keywords
+- `DELETE /keyword/` - Delete keywords (body: keyword_ids)
+- `POST /group/` - Create group
+- `PUT /group/{id}` - Update group
+- `DELETE /group/{id}` - Delete group
+- `GET /overview/group_domains` - List groups with domains
+
+### Async Operations
+
+Keyword creation returns HTTP 202 with a `Location` header pointing to a job status endpoint:
+- `GET /status/keyword_job/{id}` - Check job status
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ACCURANKER_API_KEY` | API token (overrides profile config) |
+| `ACCURANKER_TOKEN` | Alias for API token |
+
+## CLI Commands
+
+```bash
+connect-accuranker accounts list
+connect-accuranker accounts get <id>
+connect-accuranker domains list [--fields <fields>]
+connect-accuranker domains get <id> [--fields <fields>]
+connect-accuranker domains create --domain <domain> --group-id <id>
+connect-accuranker domains delete <id>
+connect-accuranker keywords list --domain-id <id> [--fields] [--limit] [--offset]
+connect-accuranker keywords get <kid> --domain-id <id>
+connect-accuranker keywords create --domain-id <id> --keywords <k1,k2>
+connect-accuranker keywords delete --keyword-ids <id1,id2>
+connect-accuranker keywords job-status <jobId>
+connect-accuranker landing-pages list --domain-id <id>
+connect-accuranker landing-pages get <pageId> --domain-id <id>
+connect-accuranker tags list --domain-id <id>
+connect-accuranker groups list [--include-subaccounts]
+connect-accuranker groups create --account-id <id> --name <name>
+connect-accuranker groups update <id> --name <name>
+connect-accuranker groups delete <id>
+connect-accuranker config set-key <token>
+connect-accuranker config show
+connect-accuranker profile list|use|create|delete|show
+```

package/connectors/connect-accuranker/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-accuranker/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hasna/connect-accuranker",
+  "version": "0.0.1",
+  "description": "AccuRanker connector - SEO rank tracking and keyword monitoring",
+  "type": "module",
+  "bin": {
+    "connect-accuranker": "./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": [
+    "api",
+    "connector",
+    "accuranker",
+    "seo",
+    "rank-tracking",
+    "keywords",
+    "serp",
+    "cli",
+    "typescript",
+    "bun"
+  ],
+  "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-accuranker.git"
+  }
+}