@bhooai/nexus-ads 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# @bhooai/nexus-ads
+
+Google Ads API client: OAuth2, campaigns, and a GAQL (Google Ads Query Language)
+reporting builder.
+
+## Exports
+
+- `createGoogleAds(config, opts)` → `GoogleAdsClient`.
+- **GaqlBuilder** — build reporting queries fluently.
+- `fetchTransport` — the authenticated transport helper.
+- Types for campaigns, reporting, and config.
+
+OAuth2 credentials are configured via `NEXUS_ADS_*` / `nexus.config.ts`. Tests mock
+the HTTP transport (no live Google Ads calls).

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@bhooai/nexus-ads",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/GaqlBuilder.ts

@@ -0,0 +1,72 @@
+/**
+ * GAQL (Google Ads Query Language) builder. Produces queries like:
+ *   SELECT campaign.id, campaign.name FROM campaign WHERE campaign.status = 'ENABLED' ORDER BY campaign.id LIMIT 50
+ */
+export class GaqlBuilder {
+  private fields: string[] = [];
+  private resource: string = '';
+  private conditions: string[] = [];
+  private order?: { field: string; dir: 'ASC' | 'DESC' };
+  private limitN?: number;
+
+  select(...fields: string[]): this {
+    this.fields.push(...fields);
+    return this;
+  }
+  from(resource: string): this {
+    this.resource = resource;
+    return this;
+  }
+  /** Add a condition, e.g. `where("campaign.status = 'ENABLED'")`. */
+  where(condition: string): this {
+    this.conditions.push(condition);
+    return this;
+  }
+  orderBy(field: string, dir: 'ASC' | 'DESC' = 'ASC'): this {
+    this.order = { field, dir };
+    return this;
+  }
+  limit(n: number): this {
+    this.limitN = n;
+    return this;
+  }
+
+  build(): string {
+    if (!this.resource) throw new Error('[nexus-ads] GaqlBuilder: FROM resource required');
+    if (this.fields.length === 0) throw new Error('[nexus-ads] GaqlBuilder: at least one field required');
+    let q = `SELECT ${this.fields.join(', ')} FROM ${this.resource}`;
+    if (this.conditions.length) q += ` WHERE ${this.conditions.join(' AND ')}`;
+    if (this.order) q += ` ORDER BY ${this.order.field} ${this.order.dir}`;
+    if (this.limitN != null) q += ` LIMIT ${this.limitN}`;
+    return q;
+  }
+}
+
+/** Convenience: standard campaign listing query. */
+export function campaignsQuery(limit = 50): string {
+  return new GaqlBuilder()
+    .select('campaign.id', 'campaign.name', 'campaign.status', 'campaign.advertising_channel_type')
+    .from('campaign')
+    .orderBy('campaign.id')
+    .limit(limit)
+    .build();
+}
+
+/** Convenience: campaign performance metrics for a date range (YYYY-MM-DD). */
+export function campaignMetricsQuery(fromDate: string, toDate: string, limit = 50): string {
+  return new GaqlBuilder()
+    .select(
+      'campaign.id',
+      'campaign.name',
+      'metrics.impressions',
+      'metrics.clicks',
+      'metrics.cost_micros',
+      'metrics.conversions',
+    )
+    .from('campaign')
+    .where(`segments.date >= '${fromDate}'`)
+    .where(`segments.date <= '${toDate}'`)
+    .orderBy('campaign.id')
+    .limit(limit)
+    .build();
+}

package/src/GoogleAdsClient.ts

@@ -0,0 +1,121 @@
+import type { GoogleAdsConfig, HttpTransport, AdsRow, Campaign } from './types.js';
+
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+
+/**
+ * Google Ads REST client (no grpc/native deps). Uses the Google Ads API REST
+ * endpoint `googleAds:search` with GAQL. OAuth2 access tokens are acquired via
+ * the refresh-token grant and cached until near expiry. The HTTP transport is
+ * injectable so tests run without live credentials.
+ */
+export class GoogleAdsClient {
+  private readonly cfg: GoogleAdsConfig;
+  private readonly transport: HttpTransport;
+  private readonly apiVersion: string;
+  private token: { value: string; expiresAt: number } | null = null;
+
+  constructor(cfg: GoogleAdsConfig, transport: HttpTransport, apiVersion = 'v17') {
+    this.cfg = cfg;
+    this.transport = transport;
+    this.apiVersion = apiVersion;
+    if (!cfg.developerToken || !cfg.clientId || !cfg.clientSecret || !cfg.refreshToken) {
+      throw new Error('[nexus-ads] developerToken, clientId, clientSecret, refreshToken all required');
+    }
+  }
+
+  private baseUrl(): string {
+    return `https://googleads.googleapis.com/${this.apiVersion}`;
+  }
+
+  /** OAuth2 refresh-token → access token, cached with a 60s safety margin. */
+  private async accessToken(): Promise<string> {
+    if (this.token && Date.now() < this.token.expiresAt - 60_000) return this.token.value;
+    const body = new URLSearchParams({
+      client_id: this.cfg.clientId,
+      client_secret: this.cfg.clientSecret,
+      refresh_token: this.cfg.refreshToken,
+      grant_type: 'refresh_token',
+    }).toString();
+    const res = await this.transport({
+      method: 'POST',
+      url: TOKEN_URL,
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+    });
+    const parsed = safeJson(res.body);
+    if (res.status !== 200 || !parsed?.access_token) {
+      throw new Error(`[nexus-ads] token refresh failed: HTTP ${res.status} ${res.body}`);
+    }
+    this.token = { value: parsed.access_token, expiresAt: Date.now() + (parsed.expires_in ?? 3600) * 1000 };
+    return this.token.value;
+  }
+
+  private async searchHeaders(): Promise<Record<string, string>> {
+    return {
+      authorization: `Bearer ${await this.accessToken()}`,
+      'developer-token': this.cfg.developerToken,
+      'content-type': 'application/json',
+      ...(this.cfg.loginCustomerId ? { 'login-customer-id': normalizeId(this.cfg.loginCustomerId) } : {}),
+    };
+  }
+
+  /** Run a GAQL query against a customer and return all rows (handles pagination). */
+  async search(customerId: string, query: string): Promise<AdsRow[]> {
+    const headers = await this.searchHeaders();
+    let pageToken: string | undefined;
+    const rows: AdsRow[] = [];
+    do {
+      const body = JSON.stringify({ query, ...(pageToken ? { pageToken } : {}) });
+      const res = await this.transport({
+        method: 'POST',
+        url: `${this.baseUrl()}/customers/${normalizeId(customerId)}/googleAds:search`,
+        headers,
+        body,
+      });
+      const parsed = safeJson(res.body);
+      if (res.status !== 200) {
+        throw new Error(`[nexus-ads] search failed: HTTP ${res.status} ${res.body}`);
+      }
+      if (Array.isArray(parsed?.results)) rows.push(...parsed.results);
+      pageToken = parsed?.nextPageToken;
+    } while (pageToken);
+    return rows;
+  }
+
+  /** List campaigns on the default customer. */
+  async listCampaigns(customerId = this.cfg.customerId, limit = 50): Promise<Campaign[]> {
+    const rows = await this.search(customerId, listCampaignsGaql(limit));
+    return rows.map(rowToCampaign);
+  }
+
+  /** Campaign metrics for a date range (YYYY-MM-DD). */
+  async campaignMetrics(fromDate: string, toDate: string, customerId = this.cfg.customerId, limit = 50): Promise<AdsRow[]> {
+    const rows = await this.search(customerId, metricsGaql(fromDate, toDate, limit));
+    return rows;
+  }
+}
+
+function listCampaignsGaql(limit: number): string {
+  return `SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type FROM campaign ORDER BY campaign.id LIMIT ${limit}`;
+}
+function metricsGaql(from: string, to: string, limit: number): string {
+  return `SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date >= '${from}' AND segments.date <= '${to}' ORDER BY campaign.id LIMIT ${limit}`;
+}
+
+function rowToCampaign(row: AdsRow): Campaign {
+  const c = (row.campaign ?? {}) as Record<string, unknown>;
+  return {
+    id: String(c.id ?? ''),
+    name: String(c.name ?? ''),
+    status: String(c.status ?? ''),
+    advertisingChannelType: c.advertisingChannelType != null ? String(c.advertisingChannelType) : undefined,
+  };
+}
+
+function normalizeId(id: string): string {
+  return id.replace(/-/g, '');
+}
+
+function safeJson(body: string): any {
+  try { return JSON.parse(body); } catch { return undefined; }
+}

package/src/fetchTransport.ts

@@ -0,0 +1,10 @@
+import type { HttpTransport, HttpRequest, HttpResponse } from './types.js';
+
+/** Default HTTP transport built on the global `fetch` (Node >= 18). */
+export const fetchTransport: HttpTransport = async (req: HttpRequest): Promise<HttpResponse> => {
+  const res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body });
+  const body = await res.text();
+  const headers: Record<string, string> = {};
+  res.headers.forEach((v, k) => { headers[k] = v; });
+  return { status: res.status, body, headers };
+};

package/src/index.ts

@@ -0,0 +1,20 @@
+export * from './types.js';
+export * from './GaqlBuilder.js';
+export * from './GoogleAdsClient.js';
+
+import { GoogleAdsClient } from './GoogleAdsClient.js';
+import { fetchTransport } from './fetchTransport.js';
+import type { GoogleAdsConfig, HttpTransport } from './types.js';
+
+/** Default fetch-based transport (Node >= 18). */
+export { fetchTransport };
+
+export interface CreateAdsOptions {
+  transport?: HttpTransport;
+  apiVersion?: string;
+}
+
+/** Build a Google Ads client. Throws at construction if required creds are missing. */
+export function createGoogleAds(config: GoogleAdsConfig, opts: CreateAdsOptions = {}): GoogleAdsClient {
+  return new GoogleAdsClient(config, opts.transport ?? fetchTransport, opts.apiVersion);
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+/** Injectable HTTP transport so the client is testable without live Google creds. */
+export interface HttpRequest {
+  method: 'GET' | 'POST';
+  url: string;
+  headers?: Record<string, string>;
+  body?: string;
+}
+export interface HttpResponse {
+  status: number;
+  body: string;
+  headers?: Record<string, string>;
+}
+export type HttpTransport = (req: HttpRequest) => Promise<HttpResponse>;
+
+/** Google Ads config as it appears in nexus.config.ts `ads`. */
+export interface GoogleAdsConfig {
+  enabled: boolean;
+  /** Google Ads API developer token. */
+  developerToken: string;
+  /** OAuth2 client credentials. */
+  clientId: string;
+  clientSecret: string;
+  /** OAuth2 refresh token (long-lived). */
+  refreshToken: string;
+  /** Login customer ID (MCC account, hyphenated or plain). Required for MCC. */
+  loginCustomerId?: string;
+  /** Default customer ID to query. */
+  customerId: string;
+}
+
+/** Minimal campaign shape from `campaign` resource. */
+export interface Campaign {
+  id: string;
+  name: string;
+  status: string;
+  advertisingChannelType?: string;
+  budget?: { amountMicros?: string };
+}
+
+/** A row from a GAQL search: a record mapping resource name → fields. */
+export type AdsRow = Record<string, unknown>;

package/tests/ads.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { GaqlBuilder, GoogleAdsClient, createGoogleAds, campaignsQuery, campaignMetricsQuery, type HttpTransport, type HttpRequest, type HttpResponse } from '../src/index.js';
+
+describe('GaqlBuilder', () => {
+  it('builds a SELECT/FROM/WHERE/ORDER/LIMIT query', () => {
+    const q = new GaqlBuilder().select('campaign.id', 'campaign.name').from('campaign').where("campaign.status = 'ENABLED'").orderBy('campaign.id', 'DESC').limit(10).build();
+    expect(q).toBe("SELECT campaign.id, campaign.name FROM campaign WHERE campaign.status = 'ENABLED' ORDER BY campaign.id DESC LIMIT 10");
+  });
+  it('joins multiple WHERE with AND', () => {
+    const q = new GaqlBuilder().select('campaign.id').from('campaign').where('a = 1').where('b = 2').build();
+    expect(q).toBe('SELECT campaign.id FROM campaign WHERE a = 1 AND b = 2');
+  });
+  it('requires FROM and at least one field', () => {
+    expect(() => new GaqlBuilder().select('x').build()).toThrow(/FROM/);
+    expect(() => new GaqlBuilder().from('campaign').build()).toThrow(/field/);
+  });
+  it('campaignsQuery convenience builds the standard query', () => {
+    expect(campaignsQuery(5)).toBe('SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type FROM campaign ORDER BY campaign.id ASC LIMIT 5');
+  });
+  it('campaignMetricsQuery includes date range + metrics', () => {
+    const q = campaignMetricsQuery('2024-01-01', '2024-01-31', 10);
+    expect(q).toContain("segments.date >= '2024-01-01'");
+    expect(q).toContain("segments.date <= '2024-01-31'");
+    expect(q).toContain('metrics.clicks');
+  });
+});
+
+function mockTransport(routes: { match: string; respond: (req: HttpRequest) => HttpResponse }[]): HttpTransport {
+  return async (req) => {
+    for (const r of routes) if (req.url.includes(r.match)) return r.respond(req);
+    return { status: 404, body: JSON.stringify({ error: `no mock for ${req.url}` }) };
+  };
+}
+
+const cfg = {
+  enabled: true,
+  developerToken: 'dev-token',
+  clientId: 'cid',
+  clientSecret: 'csec',
+  refreshToken: 'rtok',
+  customerId: '123-456-7890',
+};
+
+describe('GoogleAdsClient', () => {
+  it('throws if required creds are missing', () => {
+    expect(() => new GoogleAdsClient({ ...cfg, developerToken: '' } as any, mockTransport([]))).toThrow(/developerToken/);
+  });
+
+  it('acquires an OAuth2 token (cached) and calls googleAds:search', async () => {
+    let tokenCalls = 0;
+    const t = mockTransport([
+      { match: 'oauth2.googleapis.com/token', respond: (req) => { tokenCalls++; void req; return { status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }; } },
+      { match: 'googleAds:search', respond: (req) => ({ status: 200, body: JSON.stringify({ results: [{ campaign: { id: '1', name: 'Camp A', status: 'ENABLED', advertisingChannelType: 'SEARCH' } }] }) }) },
+    ]);
+    const client = new GoogleAdsClient(cfg as any, t);
+    const rows = await client.search('1234567890', 'SELECT campaign.id FROM campaign LIMIT 1');
+    expect(tokenCalls).toBe(1);
+    expect(rows).toHaveLength(1);
+    expect((rows[0]!.campaign as any).name).toBe('Camp A');
+    // second call reuses the cached token
+    await client.search('1234567890', 'SELECT campaign.id FROM campaign LIMIT 1');
+    expect(tokenCalls).toBe(1);
+  });
+
+  it('listCampaigns maps rows to Campaign objects', async () => {
+    const t = mockTransport([
+      { match: 'oauth2.googleapis.com/token', respond: () => ({ status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }) },
+      { match: 'googleAds:search', respond: (req) => {
+        const body = JSON.parse(req.body as string);
+        expect(body.query).toContain('FROM campaign');
+        return { status: 200, body: JSON.stringify({ results: [{ campaign: { id: '1', name: 'A', status: 'ENABLED' } }, { campaign: { id: '2', name: 'B', status: 'PAUSED' } }] }) };
+      } },
+    ]);
+    const client = new GoogleAdsClient(cfg as any, t);
+    const camps = await client.listCampaigns();
+    expect(camps).toHaveLength(2);
+    expect(camps[0]!.name).toBe('A');
+    expect(camps[1]!.id).toBe('2');
+  });
+
+  it('normalizes customer ids (strips hyphens) and sends developer-token header', async () => {
+    let sentHeaders: Record<string, string> = {};
+    let sentUrl = '';
+    const t = mockTransport([
+      { match: 'oauth2.googleapis.com/token', respond: () => ({ status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }) },
+      { match: 'googleAds:search', respond: (req) => { sentHeaders = req.headers ?? {}; sentUrl = req.url; return { status: 200, body: JSON.stringify({ results: [] }) }; } },
+    ]);
+    const client = new GoogleAdsClient({ ...cfg, loginCustomerId: '11-22-33' } as any, t);
+    await client.search('1-2-3', 'SELECT campaign.id FROM campaign');
+    expect(sentUrl).toContain('/customers/123/googleAds:search');
+    expect(sentHeaders['developer-token']).toBe('dev-token');
+    expect(sentHeaders['login-customer-id']).toBe('112233');
+    expect(sentHeaders.authorization).toBe('Bearer tok');
+  });
+
+  it('propagates search errors', async () => {
+    const t = mockTransport([
+      { match: 'oauth2.googleapis.com/token', respond: () => ({ status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }) },
+      { match: 'googleAds:search', respond: () => ({ status: 400, body: JSON.stringify({ error: { message: 'bad query' } }) }) },
+    ]);
+    const client = new GoogleAdsClient(cfg as any, t);
+    await expect(client.search('123', 'bad')).rejects.toThrow(/search failed/);
+  });
+
+  it('handles pagination via nextPageToken', async () => {
+    let call = 0;
+    const t = mockTransport([
+      { match: 'oauth2.googleapis.com/token', respond: () => ({ status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }) },
+      { match: 'googleAds:search', respond: () => {
+        call++;
+        if (call === 1) return { status: 200, body: JSON.stringify({ results: [{ campaign: { id: '1' } }], nextPageToken: 'tok2' }) };
+        return { status: 200, body: JSON.stringify({ results: [{ campaign: { id: '2' } }] }) };
+      } },
+    ]);
+    const client = new GoogleAdsClient(cfg as any, t);
+    const rows = await client.search('123', 'SELECT campaign.id FROM campaign');
+    expect(call).toBe(2);
+    expect(rows).toHaveLength(2);
+  });
+});
+
+describe('createGoogleAds factory', () => {
+  it('builds a client with the default transport', () => {
+    const client = createGoogleAds(cfg as any);
+    expect(client).toBeInstanceOf(GoogleAdsClient);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "references": [{ "path": "../nexus-core" }]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    globals: false,
+    testTimeout: 15_000,
+  },
+});