@hasna/connectors 0.9.3 → 1.0.1

package/connectors/connect-gong/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-gong/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-googleads/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+connect-googleads is a TypeScript connector for the Google Ads API. It provides a CLI and library API for managing Google Ads campaigns, ad groups, ads, and reporting.
+
+## 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
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Use async/await for all async operations
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # HTTP client with OAuth auth
+│   └── index.ts      # Main GoogleAds 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
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_ADS_DEVELOPER_TOKEN` | Google Ads developer token |
+| `GOOGLE_ADS_CLIENT_ID` | OAuth client ID |
+| `GOOGLE_ADS_CLIENT_SECRET` | OAuth client secret |
+| `GOOGLE_ADS_REFRESH_TOKEN` | OAuth refresh token |
+| `GOOGLE_ADS_CUSTOMER_ID` | Customer/account ID |
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-googleads/README.md

@@ -0,0 +1,39 @@
+# connect-googleads
+
+Google Ads API connector CLI - Campaigns, ad groups, ads, keywords, and reporting
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-googleads
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+connect-googleads config set-key YOUR_API_KEY
+
+# Or use environment variable
+export GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_API_KEY
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+Apache-2.0

package/connectors/connect-googleads/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/connect-googleads",
+  "version": "0.1.0",
+  "description": "Google Ads API connector CLI - Campaigns, ad groups, ads, keywords, and reporting",
+  "type": "module",
+  "bin": {
+    "connect-googleads": "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"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "google-ads",
+    "adwords",
+    "advertising",
+    "ppc",
+    "cli",
+    "api",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  }
+}

package/connectors/connect-googleads/src/api/adGroups.ts

@@ -0,0 +1,170 @@
+import { GoogleAdsClient } from './client';
+import type { SearchResponse, MutateResponse, AdGroupStatus } from '../types';
+
+export class AdGroupsApi {
+  constructor(private client: GoogleAdsClient) {}
+
+  /**
+   * List ad groups
+   */
+  async list(options?: { campaignId?: string; status?: AdGroupStatus; limit?: number }): Promise<SearchResponse> {
+    let query = `
+      SELECT
+        ad_group.id,
+        ad_group.name,
+        ad_group.status,
+        ad_group.type,
+        ad_group.campaign,
+        ad_group.cpc_bid_micros,
+        ad_group.target_cpa_micros,
+        campaign.name,
+        metrics.impressions,
+        metrics.clicks,
+        metrics.cost_micros,
+        metrics.conversions,
+        metrics.ctr,
+        metrics.average_cpc
+      FROM ad_group
+    `;
+
+    const conditions: string[] = [];
+
+    if (options?.campaignId) {
+      conditions.push(`campaign.id = ${options.campaignId}`);
+    }
+
+    if (options?.status) {
+      conditions.push(`ad_group.status = '${options.status}'`);
+    }
+
+    if (conditions.length > 0) {
+      query += ` WHERE ${conditions.join(' AND ')}`;
+    }
+
+    query += ` ORDER BY ad_group.name`;
+
+    if (options?.limit) {
+      query += ` LIMIT ${options.limit}`;
+    }
+
+    return this.client.search(query);
+  }
+
+  /**
+   * Get a specific ad group
+   */
+  async get(adGroupId: string): Promise<SearchResponse> {
+    return this.client.search(`
+      SELECT
+        ad_group.id,
+        ad_group.name,
+        ad_group.status,
+        ad_group.type,
+        ad_group.campaign,
+        ad_group.cpc_bid_micros,
+        ad_group.cpm_bid_micros,
+        ad_group.target_cpa_micros,
+        ad_group.target_roas,
+        campaign.name,
+        campaign.id,
+        metrics.impressions,
+        metrics.clicks,
+        metrics.cost_micros,
+        metrics.conversions,
+        metrics.conversions_value
+      FROM ad_group
+      WHERE ad_group.id = ${adGroupId}
+    `);
+  }
+
+  /**
+   * Create an ad group
+   */
+  async create(
+    campaignId: string,
+    name: string,
+    options?: {
+      status?: AdGroupStatus;
+      type?: string;
+      cpcBidMicros?: string;
+    }
+  ): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+
+    const adGroup: Record<string, unknown> = {
+      name,
+      campaign: `customers/${customerId}/campaigns/${campaignId}`,
+      status: options?.status || 'PAUSED',
+      type: options?.type || 'SEARCH_STANDARD',
+    };
+
+    if (options?.cpcBidMicros) {
+      adGroup.cpcBidMicros = options.cpcBidMicros;
+    }
+
+    return this.client.mutate('adGroups', [{ create: adGroup }]);
+  }
+
+  /**
+   * Update an ad group
+   */
+  async update(
+    adGroupId: string,
+    updates: {
+      name?: string;
+      status?: AdGroupStatus;
+      cpcBidMicros?: string;
+      targetCpaMicros?: string;
+    }
+  ): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+    const resourceName = `customers/${customerId}/adGroups/${adGroupId}`;
+
+    const adGroup: Record<string, unknown> = {
+      resourceName,
+      ...updates,
+    };
+
+    const updateMask = Object.keys(updates).map(k =>
+      k.replace(/([A-Z])/g, '_$1').toLowerCase()
+    ).join(',');
+
+    return this.client.mutate('adGroups', [{
+      update: adGroup,
+      updateMask,
+    }]);
+  }
+
+  /**
+   * Pause an ad group
+   */
+  async pause(adGroupId: string): Promise<MutateResponse> {
+    return this.update(adGroupId, { status: 'PAUSED' });
+  }
+
+  /**
+   * Enable an ad group
+   */
+  async enable(adGroupId: string): Promise<MutateResponse> {
+    return this.update(adGroupId, { status: 'ENABLED' });
+  }
+
+  /**
+   * Remove an ad group
+   */
+  async remove(adGroupId: string): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+    const resourceName = `customers/${customerId}/adGroups/${adGroupId}`;
+
+    return this.client.mutate('adGroups', [{
+      remove: resourceName,
+    }]);
+  }
+
+  /**
+   * Set ad group bid
+   */
+  async setBid(adGroupId: string, cpcBidMicros: string): Promise<MutateResponse> {
+    return this.update(adGroupId, { cpcBidMicros });
+  }
+}

package/connectors/connect-googleads/src/api/ads.ts

@@ -0,0 +1,171 @@
+import { GoogleAdsClient } from './client';
+import type { SearchResponse, MutateResponse, AdStatus } from '../types';
+
+export class AdsApi {
+  constructor(private client: GoogleAdsClient) {}
+
+  /**
+   * List ads
+   */
+  async list(options?: { adGroupId?: string; campaignId?: string; status?: AdStatus; limit?: number }): Promise<SearchResponse> {
+    let query = `
+      SELECT
+        ad_group_ad.ad.id,
+        ad_group_ad.ad.name,
+        ad_group_ad.ad.type,
+        ad_group_ad.ad.final_urls,
+        ad_group_ad.status,
+        ad_group_ad.ad_group,
+        ad_group_ad.policy_summary.approval_status,
+        ad_group_ad.policy_summary.review_status,
+        ad_group_ad.ad.responsive_search_ad.headlines,
+        ad_group_ad.ad.responsive_search_ad.descriptions,
+        ad_group.name,
+        campaign.name,
+        metrics.impressions,
+        metrics.clicks,
+        metrics.cost_micros,
+        metrics.conversions,
+        metrics.ctr
+      FROM ad_group_ad
+    `;
+
+    const conditions: string[] = [];
+
+    if (options?.adGroupId) {
+      conditions.push(`ad_group.id = ${options.adGroupId}`);
+    }
+
+    if (options?.campaignId) {
+      conditions.push(`campaign.id = ${options.campaignId}`);
+    }
+
+    if (options?.status) {
+      conditions.push(`ad_group_ad.status = '${options.status}'`);
+    }
+
+    if (conditions.length > 0) {
+      query += ` WHERE ${conditions.join(' AND ')}`;
+    }
+
+    query += ` ORDER BY ad_group_ad.ad.id`;
+
+    if (options?.limit) {
+      query += ` LIMIT ${options.limit}`;
+    }
+
+    return this.client.search(query);
+  }
+
+  /**
+   * Get a specific ad
+   */
+  async get(adGroupId: string, adId: string): Promise<SearchResponse> {
+    return this.client.search(`
+      SELECT
+        ad_group_ad.ad.id,
+        ad_group_ad.ad.name,
+        ad_group_ad.ad.type,
+        ad_group_ad.ad.final_urls,
+        ad_group_ad.ad.final_mobile_urls,
+        ad_group_ad.ad.tracking_url_template,
+        ad_group_ad.ad.display_url,
+        ad_group_ad.status,
+        ad_group_ad.ad_group,
+        ad_group_ad.policy_summary.approval_status,
+        ad_group_ad.policy_summary.review_status,
+        ad_group_ad.policy_summary.policy_topic_entries,
+        ad_group_ad.ad.responsive_search_ad.headlines,
+        ad_group_ad.ad.responsive_search_ad.descriptions,
+        ad_group_ad.ad.responsive_search_ad.path1,
+        ad_group_ad.ad.responsive_search_ad.path2,
+        metrics.impressions,
+        metrics.clicks,
+        metrics.cost_micros,
+        metrics.conversions
+      FROM ad_group_ad
+      WHERE ad_group.id = ${adGroupId}
+        AND ad_group_ad.ad.id = ${adId}
+    `);
+  }
+
+  /**
+   * Create a responsive search ad
+   */
+  async createResponsiveSearchAd(
+    adGroupId: string,
+    headlines: string[],
+    descriptions: string[],
+    finalUrls: string[],
+    options?: {
+      path1?: string;
+      path2?: string;
+      status?: AdStatus;
+    }
+  ): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+
+    const ad: Record<string, unknown> = {
+      adGroup: `customers/${customerId}/adGroups/${adGroupId}`,
+      status: options?.status || 'PAUSED',
+      ad: {
+        finalUrls,
+        responsiveSearchAd: {
+          headlines: headlines.map(text => ({ text })),
+          descriptions: descriptions.map(text => ({ text })),
+        },
+      },
+    };
+
+    if (options?.path1) {
+      (ad.ad as any).responsiveSearchAd.path1 = options.path1;
+    }
+    if (options?.path2) {
+      (ad.ad as any).responsiveSearchAd.path2 = options.path2;
+    }
+
+    return this.client.mutate('adGroupAds', [{ create: ad }]);
+  }
+
+  /**
+   * Update ad status
+   */
+  async updateStatus(adGroupId: string, adId: string, status: AdStatus): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+    const resourceName = `customers/${customerId}/adGroupAds/${adGroupId}~${adId}`;
+
+    return this.client.mutate('adGroupAds', [{
+      update: {
+        resourceName,
+        status,
+      },
+      updateMask: 'status',
+    }]);
+  }
+
+  /**
+   * Pause an ad
+   */
+  async pause(adGroupId: string, adId: string): Promise<MutateResponse> {
+    return this.updateStatus(adGroupId, adId, 'PAUSED');
+  }
+
+  /**
+   * Enable an ad
+   */
+  async enable(adGroupId: string, adId: string): Promise<MutateResponse> {
+    return this.updateStatus(adGroupId, adId, 'ENABLED');
+  }
+
+  /**
+   * Remove an ad
+   */
+  async remove(adGroupId: string, adId: string): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+    const resourceName = `customers/${customerId}/adGroupAds/${adGroupId}~${adId}`;
+
+    return this.client.mutate('adGroupAds', [{
+      remove: resourceName,
+    }]);
+  }
+}