@bhooai/nexus-ads 2.0.17 → 2.0.19

package/README.md

@@ -1,14 +1,36 @@
 # @bhooai/nexus-ads
 
-Google Ads API client: OAuth2, campaigns, and a GAQL (Google Ads Query Language)
-reporting builder.
+Google AdSense module (publisher-side): AdSense Management API v2 client,
+reporting builder, and frontend display-snippet helpers.
 
 ## Exports
 
-- `createGoogleAds(config, opts)` → `GoogleAdsClient`.
-- **GaqlBuilder** — build reporting queries fluently.
-- `fetchTransport` — the authenticated transport helper.
-- Types for campaigns, reporting, and config.
+- `createAdSense(config, opts)` → `AdSenseClient`.
+- `AdSenseClient` — `listAccounts()`, `listAdClients()`, `listSites()`,
+  `listAdUnits()`, `generateReport()`, `earningsReport()`.
+- **ReportBuilder** — fluent reporting params + `earningsReportOptions()`,
+  `topPagesReportOptions()`.
+- `adsenseScript()`, `autoAdsScript()`, `adUnit()`, `normalizeAdClient()` —
+  framework-agnostic HTML strings (work with `nexus-future` `html`/`raw`).
+- `fetchTransport` — the default transport helper.
+- Types for config, accounts, ad clients, sites, ad units, reports.
 
-OAuth2 credentials are configured via `NEXUS_ADS_*` / `nexus.config.ts`. Tests mock
-the HTTP transport (no live Google Ads calls).
+OAuth2 credentials (`adsense.readonly` scope) are configured via
+`NEXUS_ADS_*` / `nexus.config.ts` (`ads: { enabled, publisherId, clientId,
+clientSecret, refreshToken, accountId? }`). Tests mock the HTTP transport
+(no live AdSense calls).
+
+### OAuth consent flow (obtain a refresh token)
+
+- `buildAuthorizeUrl({ clientId, redirectUri, state? })` — consent URL with
+  `access_type=offline` + `prompt=consent` so a refresh token is issued.
+  `redirectUri` must be registered on the Google Cloud OAuth web client.
+- `exchangeCode({ clientId, clientSecret, code, redirectUri })` — exchange the
+  returned `?code=...` for tokens; persist `refreshToken` as
+  `NEXUS_ADS_REFRESH_TOKEN` (gitignored `.env`, never in git).
+
+### Display snippet CSP
+
+Allow `script-src https://pagead2.googlesyndication.com` and
+`frame-src https://googleads.g.doubleclick.net`. For GDPR, gate the loader
+behind consent and consider `data-npa-on-unknown-consent`.

package/package.json

@@ -1,6 +1,7 @@
 {
     "name": "@bhooai/nexus-ads",
-    "version": "2.0.17",
+    "version": "2.0.19",
+    "description": "Google AdSense module: Management API v2 client, reporting builder, display snippets.",
     "publishConfig": {
         "access": "public"
     },

package/src/AdSenseClient.ts

@@ -0,0 +1,210 @@
+import type {
+  AdClient,
+  AdSenseAccount,
+  AdSenseConfig,
+  AdSenseSite,
+  AdUnit,
+  HttpTransport,
+  ReportOptions,
+  ReportResult,
+  ReportRow,
+} from './types.js';
+
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const ADSENSE_BASE = 'https://adsense.googleapis.com/v2';
+
+/**
+ * AdSense Management API v2 client (publisher-side, REST only, no native deps).
+ *
+ * OAuth2 access tokens are acquired via the refresh-token grant
+ * (`adsense.readonly` scope must be granted to the refresh token) and cached
+ * until near expiry. The HTTP transport is injectable so tests run without
+ * live credentials.
+ */
+export class AdSenseClient {
+  private readonly cfg: AdSenseConfig;
+  private readonly transport: HttpTransport;
+  private token: { value: string; expiresAt: number } | null = null;
+
+  constructor(cfg: AdSenseConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.clientId || !cfg.clientSecret || !cfg.refreshToken) {
+      throw new Error('[nexus-ads] clientId, clientSecret, refreshToken all required');
+    }
+    if (!cfg.publisherId && !cfg.accountId) {
+      throw new Error('[nexus-ads] publisherId (or accountId) is required');
+    }
+  }
+
+  /** 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 authHeaders(): Promise<Record<string, string>> {
+    return { authorization: `Bearer ${await this.accessToken()}` };
+  }
+
+  private async get<T>(path: string, query?: Record<string, string | undefined>): Promise<T> {
+    const headers = await this.authHeaders();
+    const qs = queryString(query);
+    const res = await this.transport({
+      method: 'GET',
+      url: `${ADSENSE_BASE}${path}${qs ? `?${qs}` : ''}`,
+      headers,
+    });
+    if (res.status !== 200) {
+      throw new Error(`[nexus-ads] GET ${path} failed: HTTP ${res.status} ${res.body}`);
+    }
+    return safeJson(res.body) as T;
+  }
+
+  private async listAll<T>(path: string, query?: Record<string, string | undefined>, pageSize = 50): Promise<T[]> {
+    const items: T[] = [];
+    let pageToken: string | undefined;
+    do {
+      const page = await this.get<{ [k: string]: unknown }>(path, {
+        ...query,
+        pageSize: String(pageSize),
+        ...(pageToken ? { pageToken } : {}),
+      });
+      const batch = extractList(page);
+      if (batch.length) items.push(...(batch as T[]));
+      pageToken = typeof page.nextPageToken === 'string' ? page.nextPageToken : undefined;
+    } while (pageToken);
+    return items;
+  }
+
+  /** Default account: `accountId` config or derived from `publisherId`. */
+  defaultAccount(): string {
+    const raw = this.cfg.accountId ?? this.cfg.publisherId;
+    return toAccountName(raw);
+  }
+
+  /** List AdSense accounts visible to the OAuth grant. */
+  async listAccounts(pageSize = 50): Promise<AdSenseAccount[]> {
+    return this.listAll<AdSenseAccount>('/accounts', undefined, pageSize);
+  }
+
+  /** List ad clients under an account. Defaults to the configured account. */
+  async listAdClients(account = this.defaultAccount(), pageSize = 50): Promise<AdClient[]> {
+    return this.listAll<AdClient>(`/${account}/adclients`, undefined, pageSize);
+  }
+
+  /** List verified sites under an account. */
+  async listSites(account = this.defaultAccount(), pageSize = 50): Promise<AdSenseSite[]> {
+    return this.listAll<AdSenseSite>(`/${account}/sites`, undefined, pageSize);
+  }
+
+  /** List ad units. `adClient` is `ca-pub-xxx` or the full resource name. */
+  async listAdUnits(account = this.defaultAccount(), adClient?: string, pageSize = 50): Promise<AdUnit[]> {
+    const query: Record<string, string | undefined> = {};
+    if (adClient) query.adClientName = toAdClientName(account, adClient);
+    return this.listAll<AdUnit>(`/${account}/adunits`, query, pageSize);
+  }
+
+  /** Generate an earnings/traffic report for a date range (YYYY-MM-DD). */
+  async generateReport(opts: ReportOptions, account = this.defaultAccount()): Promise<ReportResult> {
+    if (!opts.startDate || !opts.endDate) {
+      throw new Error('[nexus-ads] generateReport: startDate and endDate (YYYY-MM-DD) required');
+    }
+    const query: Record<string, string | undefined> = {
+      'dateRange.startDate.year': undefined,
+      ...(opts.dimensions?.length ? { dimensions: opts.dimensions.join(',') } : {}),
+      ...(opts.metrics?.length ? { metrics: opts.metrics.join(',') } : {}),
+      startDate: opts.startDate,
+      endDate: opts.endDate,
+      ...(opts.filters?.length ? { filters: opts.filters.join(',') } : {}),
+      ...(opts.orderBy?.length ? { orderBy: opts.orderBy.join(',') } : {}),
+      ...(opts.limit != null ? { limit: String(opts.limit) } : {}),
+    };
+    // Remove the placeholder key; keep query building explicit for readability.
+    delete query['dateRange.startDate.year'];
+    const raw = await this.get<Record<string, unknown>>(`/${account}/reports:generate`, query);
+    const rows = Array.isArray(raw.rows) ? (raw.rows as ReportRow[]) : [];
+    const totals = (raw.totals as ReportRow | undefined) ?? undefined;
+    const headers = Array.isArray(raw.headers)
+      ? (raw.headers as Array<{ name: string; type?: string }>)
+      : undefined;
+    return { rows, totals, headers };
+  }
+
+  /** Earnings report convenience (totals + daily rows when DATE dimension used). */
+  async earningsReport(fromDate: string, toDate: string, account = this.defaultAccount(), limit = 50): Promise<ReportResult> {
+    return this.generateReport(
+      {
+        dimensions: ['DATE'],
+        metrics: ['PAGE_VIEWS', 'AD_REQUESTS', 'CLICKS', 'ESTIMATED_EARNINGS'],
+        startDate: fromDate,
+        endDate: toDate,
+        orderBy: ['+DATE'],
+        limit,
+      },
+      account,
+    );
+  }
+}
+
+/** `pub-xxx` → `accounts/pub-xxx`; passes through full resource names. */
+export function toAccountName(raw: string): string {
+  const v = raw.trim();
+  if (v.startsWith('accounts/')) return v;
+  return `accounts/${v.replace(/^ca-/, '')}`;
+}
+
+/** `ca-pub-xxx` (or bare) → `accounts/pub-xxx/adclients/ca-pub-xxx`. */
+export function toAdClientName(account: string, adClient: string): string {
+  const c = adClient.trim();
+  if (c.includes('/adclients/')) return c;
+  const clientId = c.startsWith('ca-') ? c : `ca-${c.replace(/^pub-/, 'pub-')}`;
+  return `${account}/adclients/${clientId}`;
+}
+
+function queryString(query?: Record<string, string | undefined>): string {
+  if (!query) return '';
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v !== undefined && v !== '') params.append(k, v);
+  }
+  return params.toString();
+}
+
+/** AdSense list endpoints nest items under different keys; accept any array field. */
+function extractList(page: Record<string, unknown>): unknown[] {
+  for (const key of ['accounts', 'adClients', 'sites', 'adUnits']) {
+    const v = page[key];
+    if (Array.isArray(v)) return v;
+  }
+  // Fallback: first array-valued property.
+  for (const v of Object.values(page)) {
+    if (Array.isArray(v)) return v;
+  }
+  return [];
+}
+
+function safeJson(body: string): any {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+}

package/src/ReportBuilder.ts

@@ -0,0 +1,99 @@
+import type { ReportOptions } from './types.js';
+
+/**
+ * Fluent builder for AdSense `reports:generate` parameters.
+ *
+ * Produces e.g.:
+ *   dimensions=DATE,COUNTRY_NAME&metrics=PAGE_VIEWS,ESTIMATED_EARNINGS
+ *   &startDate=2026-01-01&endDate=2026-01-31&orderBy=%2BDATE&limit=50
+ */
+export class ReportBuilder {
+  private dimensions: string[] = [];
+  private metrics: string[] = [];
+  private filters: string[] = [];
+  private order: string[] = [];
+  private start?: string;
+  private end?: string;
+  private limitN?: number;
+
+  dimension(...dims: string[]): this {
+    this.dimensions.push(...dims);
+    return this;
+  }
+  metric(...metrics: string[]): this {
+    this.metrics.push(...metrics);
+    return this;
+  }
+  range(startDate: string, endDate: string): this {
+    this.start = startDate;
+    this.end = endDate;
+    return this;
+  }
+  /** Add a filter, e.g. `filter("COUNTRY_NAME==India")`. */
+  filter(condition: string): this {
+    this.filters.push(condition);
+    return this;
+  }
+  orderBy(...fields: string[]): this {
+    this.order.push(...fields);
+    return this;
+  }
+  limit(n: number): this {
+    this.limitN = n;
+    return this;
+  }
+
+  build(): ReportOptions {
+    if (!this.start || !this.end) {
+      throw new Error('[nexus-ads] ReportBuilder: date range required (call .range(from, to))');
+    }
+    if (this.metrics.length === 0) {
+      throw new Error('[nexus-ads] ReportBuilder: at least one metric required');
+    }
+    return {
+      ...(this.dimensions.length ? { dimensions: [...this.dimensions] } : {}),
+      metrics: [...this.metrics],
+      startDate: this.start,
+      endDate: this.end,
+      ...(this.filters.length ? { filters: [...this.filters] } : {}),
+      ...(this.order.length ? { orderBy: [...this.order] } : {}),
+      ...(this.limitN != null ? { limit: this.limitN } : {}),
+    };
+  }
+
+  /** Encode the built options as a URL query string (for logging/debugging). */
+  toQueryString(): string {
+    const opts = this.build();
+    const params = new URLSearchParams();
+    if (opts.dimensions?.length) params.append('dimensions', opts.dimensions.join(','));
+    params.append('metrics', opts.metrics!.join(','));
+    params.append('startDate', opts.startDate);
+    params.append('endDate', opts.endDate);
+    if (opts.filters?.length) params.append('filters', opts.filters.join(','));
+    if (opts.orderBy?.length) params.append('orderBy', opts.orderBy.join(','));
+    if (opts.limit != null) params.append('limit', String(opts.limit));
+    return params.toString();
+  }
+}
+
+/** Convenience: daily earnings report options for a date range (YYYY-MM-DD). */
+export function earningsReportOptions(fromDate: string, toDate: string, limit = 50): ReportOptions {
+  return new ReportBuilder()
+    .dimension('DATE')
+    .metric('PAGE_VIEWS', 'AD_REQUESTS', 'CLICKS', 'ESTIMATED_EARNINGS')
+    .range(fromDate, toDate)
+    .orderBy('+DATE')
+    .limit(limit)
+    .build();
+}
+
+/** Convenience: top-pages report options for a date range (YYYY-MM-DD). */
+export function topPagesReportOptions(fromDate: string, toDate: string, limit = 50): ReportOptions {
+  return new ReportBuilder()
+    .dimension('PAGE_URL')
+    .metric('PAGE_VIEWS', 'CLICKS', 'ESTIMATED_EARNINGS')
+    .range(fromDate, toDate)
+    .orderBy('-ESTIMATED_EARNINGS')
+    .limit(limit)
+    .build();
+}

package/src/adsenseHtml.ts

@@ -0,0 +1,75 @@
+/**
+ * Framework-agnostic AdSense display-snippet helpers.
+ *
+ * Returns plain HTML strings — safe to embed with `nexus-future` `html`/`raw`,
+ * any SSR pipeline, or `innerHTML`. All dynamic values are attribute-escaped.
+ */
+
+export interface AdSenseScriptOptions {
+  /** Defaults to true (`async` attribute). */
+  async?: boolean;
+  /** Defaults to `anonymous`. Pass `false` to omit. */
+  crossorigin?: string | false;
+}
+
+export interface AdUnitOptions {
+  /** Publisher client, `ca-pub-xxx` (or `pub-xxx`, normalized automatically). */
+  adClient: string;
+  /** Ad unit slot id from the AdSense dashboard. */
+  adSlot: string;
+  /** Defaults to `auto`. Use `fluid`, `rectangle`, etc. as needed. */
+  format?: string;
+  /** Defaults to true (`data-full-width-responsive="true"`). */
+  responsive?: boolean;
+  /** Extra CSS for the `<ins>` tag. Defaults to `display:block`. */
+  style?: string;
+  /** Layout for in-article / in-feed units (e.g. `in-article`). */
+  layout?: string;
+}
+
+/** `pub-xxx` → `ca-pub-xxx`; passes through values already prefixed. */
+export function normalizeAdClient(raw: string): string {
+  const v = raw.trim();
+  if (v.startsWith('ca-pub-')) return v;
+  if (v.startsWith('pub-')) return `ca-${v}`;
+  return `ca-pub-${v}`;
+}
+
+/** `<script>` loader for `pagead2.googlesyndication.com`. Include once per page. */
+export function adsenseScript(publisherId: string, opts: AdSenseScriptOptions = {}): string {
+  const client = normalizeAdClient(publisherId);
+  const asyncAttr = opts.async === false ? '' : ' async';
+  const crossorigin =
+    opts.crossorigin === false ? '' : ` crossorigin="${escapeAttr(opts.crossorigin ?? 'anonymous')}"`;
+  return `<script${asyncAttr} src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${escapeAttr(client)}"${crossorigin}></script>`;
+}
+
+/** Auto-ads variant (same loader; kept as a named helper for intent). */
+export function autoAdsScript(publisherId: string, opts: AdSenseScriptOptions = {}): string {
+  return adsenseScript(publisherId, opts);
+}
+
+/** Manual ad unit: `<ins class="adsbygoogle">` + push snippet. */
+export function adUnit(opts: AdUnitOptions): string {
+  if (!opts.adClient) throw new Error('[nexus-ads] adUnit: adClient is required');
+  if (!opts.adSlot) throw new Error('[nexus-ads] adUnit: adSlot is required');
+  const client = normalizeAdClient(opts.adClient);
+  const format = opts.format ?? 'auto';
+  const responsive = opts.responsive === false ? '' : ' data-full-width-responsive="true"';
+  const style = escapeAttr(opts.style ?? 'display:block');
+  const layout = opts.layout ? ` data-layout="${escapeAttr(opts.layout)}"` : '';
+  const ins =
+    `<ins class="adsbygoogle" style="${style}"` +
+    ` data-ad-client="${escapeAttr(client)}"` +
+    ` data-ad-slot="${escapeAttr(opts.adSlot)}"` +
+    ` data-ad-format="${escapeAttr(format)}"${layout}${responsive}></ins>`;
+  return `${ins}\n<script>(adsbygoogle = window.adsbygoogle || []).push({});</script>`;
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/src/index.ts

@@ -1,10 +1,12 @@
 export * from './types.js';
-export * from './GaqlBuilder.js';
-export * from './GoogleAdsClient.js';
+export * from './ReportBuilder.js';
+export * from './AdSenseClient.js';
+export * from './adsenseHtml.js';
+export * from './oauth.js';
 
-import { GoogleAdsClient } from './GoogleAdsClient.js';
+import { AdSenseClient } from './AdSenseClient.js';
 import { fetchTransport } from './fetchTransport.js';
-import type { GoogleAdsConfig, HttpTransport } from './types.js';
+import type { AdSenseConfig, HttpTransport } from './types.js';
 import { requireLicense } from '@bhooai/nexus-crypto';
 
 /** Default fetch-based transport (Node >= 18). */
@@ -12,12 +14,11 @@ 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 {
-  // Licensed feature: the Google Ads client needs a master key.
+/** Build an AdSense client. Throws at construction if required creds are missing. */
+export function createAdSense(config: AdSenseConfig, opts: CreateAdsOptions = {}): AdSenseClient {
+  // Licensed feature: the AdSense client needs a master key.
   requireLicense('nexus-ads');
-  return new GoogleAdsClient(config, opts.transport ?? fetchTransport, opts.apiVersion);
+  return new AdSenseClient(config, opts.transport ?? fetchTransport);
 }

package/src/oauth.ts

@@ -0,0 +1,96 @@
+import type { HttpTransport } from './types.js';
+import { fetchTransport } from './fetchTransport.js';
+
+export const AUTHORIZE_URL = 'https://accounts.google.com/o/oauth2/v2/auth';
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+
+/** OAuth2 scope for the AdSense Management API (read-only reporting). */
+export const ADSENSE_READONLY_SCOPE = 'https://www.googleapis.com/auth/adsense.readonly';
+
+export interface AuthorizeUrlInput {
+  /** OAuth2 web client ID (Google Cloud console → Credentials). */
+  clientId: string;
+  /** Must match a redirect URI registered on the OAuth client. */
+  redirectUri: string;
+  /** Extra scopes (adsense.readonly is always included). */
+  scopes?: string[];
+  /** Opaque CSRF state round-tripped through the consent redirect. */
+  state?: string;
+}
+
+/**
+ * Build the Google consent URL that issues an authorization code for the
+ * AdSense Management API. `access_type=offline` + `prompt=consent` ensure a
+ * long-lived refresh token is returned on exchange.
+ */
+export function buildAuthorizeUrl(input: AuthorizeUrlInput): string {
+  if (!input.clientId) throw new Error('[nexus-ads] buildAuthorizeUrl: clientId required');
+  if (!input.redirectUri) throw new Error('[nexus-ads] buildAuthorizeUrl: redirectUri required');
+  const params = new URLSearchParams({
+    client_id: input.clientId,
+    redirect_uri: input.redirectUri,
+    response_type: 'code',
+    access_type: 'offline',
+    prompt: 'consent',
+    scope: [ADSENSE_READONLY_SCOPE, ...(input.scopes ?? [])].join(' '),
+  });
+  if (input.state) params.set('state', input.state);
+  return `${AUTHORIZE_URL}?${params.toString()}`;
+}
+
+export interface ExchangeCodeInput {
+  clientId: string;
+  clientSecret: string;
+  /** Authorization code from the consent redirect (`?code=...`). */
+  code: string;
+  /** Must be the same redirect URI used in buildAuthorizeUrl. */
+  redirectUri: string;
+}
+
+export interface ExchangeCodeResult {
+  /** Long-lived credential — store in NEXUS_ADS_REFRESH_TOKEN (never in git). */
+  refreshToken: string;
+  accessToken: string;
+  expiresIn: number;
+}
+
+/**
+ * Exchange an authorization code for tokens (authorization_code grant).
+ * Returns the refresh token to persist server-side. Transport is injectable
+ * so tests run without live Google credentials.
+ */
+export async function exchangeCode(
+  input: ExchangeCodeInput,
+  transport: HttpTransport = fetchTransport,
+): Promise<ExchangeCodeResult> {
+  if (!input.clientId || !input.clientSecret || !input.code || !input.redirectUri) {
+    throw new Error('[nexus-ads] exchangeCode: clientId, clientSecret, code, redirectUri all required');
+  }
+  const body = new URLSearchParams({
+    client_id: input.clientId,
+    client_secret: input.clientSecret,
+    code: input.code,
+    grant_type: 'authorization_code',
+    redirect_uri: input.redirectUri,
+  }).toString();
+  const res = await transport({
+    method: 'POST',
+    url: TOKEN_URL,
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+  let parsed: any;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    parsed = undefined;
+  }
+  if (res.status !== 200 || !parsed?.access_token) {
+    throw new Error(`[nexus-ads] code exchange failed: HTTP ${res.status} ${res.body}`);
+  }
+  return {
+    refreshToken: parsed.refresh_token ?? '',
+    accessToken: parsed.access_token,
+    expiresIn: parsed.expires_in ?? 3600,
+  };
+}

package/src/types.ts

@@ -12,30 +12,65 @@ export interface HttpResponse {
 }
 export type HttpTransport = (req: HttpRequest) => Promise<HttpResponse>;
 
-/** Google Ads config as it appears in nexus.config.ts `ads`. */
-export interface GoogleAdsConfig {
+/** AdSense config as it appears in nexus.config.ts `ads`. */
+export interface AdSenseConfig {
   enabled: boolean;
-  /** Google Ads API developer token. */
-  developerToken: string;
-  /** OAuth2 client credentials. */
+  /** Publisher ID, `pub-xxx` or `ca-pub-xxx`. Used for display snippets. */
+  publisherId: string;
+  /** OAuth2 client credentials (AdSense Management API). */
   clientId: string;
   clientSecret: string;
-  /** OAuth2 refresh token (long-lived). */
+  /** OAuth2 refresh token (long-lived). Needs `adsense.readonly` scope. */
   refreshToken: string;
-  /** Login customer ID (MCC account, hyphenated or plain). Required for MCC. */
-  loginCustomerId?: string;
-  /** Default customer ID to query. */
-  customerId: string;
+  /** Default AdSense account, `pub-xxx` or `accounts/pub-xxx`. Falls back to publisherId. */
+  accountId?: string;
 }
 
-/** Minimal campaign shape from `campaign` resource. */
-export interface Campaign {
-  id: string;
+/** AdSense account resource (subset). */
+export interface AdSenseAccount {
   name: string;
-  status: string;
-  advertisingChannelType?: string;
-  budget?: { amountMicros?: string };
+  displayName?: string;
+  createTime?: string;
+  timeZone?: { id?: string };
 }
 
-/** A row from a GAQL search: a record mapping resource name → fields. */
-export type AdsRow = Record<string, unknown>;
+/** Ad client resource (subset). */
+export interface AdClient {
+  name: string;
+  reportingDimensionId?: string;
+}
+
+/** Verified site resource (subset). */
+export interface AdSenseSite {
+  name: string;
+  domain?: string;
+  state?: string;
+}
+
+/** Ad unit resource (subset). */
+export interface AdUnit {
+  name: string;
+  displayName?: string;
+  state?: string;
+}
+
+/** Options for `reports:generate`. Dates are `YYYY-MM-DD`. */
+export interface ReportOptions {
+  dimensions?: string[];
+  metrics?: string[];
+  startDate: string;
+  endDate: string;
+  filters?: string[];
+  orderBy?: string[];
+  limit?: number;
+}
+
+/** A single report row: dimension/metric code → value. */
+export type ReportRow = Record<string, string>;
+
+/** Parsed report response. */
+export interface ReportResult {
+  rows: ReportRow[];
+  totals?: ReportRow;
+  headers?: Array<{ name: string; type?: string }>;
+}

package/tests/adsense.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect } from 'vitest';
+import {
+  ReportBuilder,
+  AdSenseClient,
+  createAdSense,
+  earningsReportOptions,
+  topPagesReportOptions,
+  adsenseScript,
+  adUnit,
+  normalizeAdClient,
+  toAccountName,
+  type HttpTransport,
+  type HttpRequest,
+  type HttpResponse,
+} from '../src/index.js';
+
+describe('ReportBuilder', () => {
+  it('builds report options with dimensions/metrics/range/order/limit', () => {
+    const opts = new ReportBuilder()
+      .dimension('DATE')
+      .metric('PAGE_VIEWS', 'ESTIMATED_EARNINGS')
+      .range('2026-01-01', '2026-01-31')
+      .filter('COUNTRY_NAME==India')
+      .orderBy('+DATE')
+      .limit(10)
+      .build();
+    expect(opts).toEqual({
+      dimensions: ['DATE'],
+      metrics: ['PAGE_VIEWS', 'ESTIMATED_EARNINGS'],
+      startDate: '2026-01-01',
+      endDate: '2026-01-31',
+      filters: ['COUNTRY_NAME==India'],
+      orderBy: ['+DATE'],
+      limit: 10,
+    });
+  });
+  it('requires a date range and at least one metric', () => {
+    expect(() => new ReportBuilder().metric('PAGE_VIEWS').build()).toThrow(/range/);
+    expect(() => new ReportBuilder().range('2026-01-01', '2026-01-31').build()).toThrow(/metric/);
+  });
+  it('earningsReportOptions has daily earnings shape', () => {
+    const opts = earningsReportOptions('2026-01-01', '2026-01-31', 5);
+    expect(opts.dimensions).toEqual(['DATE']);
+    expect(opts.metrics).toContain('ESTIMATED_EARNINGS');
+    expect(opts.limit).toBe(5);
+  });
+  it('topPagesReportOptions orders by earnings desc', () => {
+    const opts = topPagesReportOptions('2026-01-01', '2026-01-31');
+    expect(opts.dimensions).toEqual(['PAGE_URL']);
+    expect(opts.orderBy).toEqual(['-ESTIMATED_EARNINGS']);
+  });
+});
+
+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,
+  publisherId: 'pub-123',
+  clientId: 'cid',
+  clientSecret: 'csec',
+  refreshToken: 'rtok',
+};
+
+describe('AdSenseClient', () => {
+  it('throws if required creds are missing', () => {
+    expect(() => new AdSenseClient({ ...cfg, clientId: '' } as any, mockTransport([]))).toThrow(/clientId/);
+    expect(() => new AdSenseClient({ ...cfg, publisherId: '', accountId: undefined } as any, mockTransport([]))).toThrow(
+      /publisherId/,
+    );
+  });
+
+  it('normalizes account names', () => {
+    expect(toAccountName('pub-123')).toBe('accounts/pub-123');
+    expect(toAccountName('ca-pub-123')).toBe('accounts/pub-123');
+    expect(toAccountName('accounts/pub-123')).toBe('accounts/pub-123');
+  });
+
+  it('acquires an OAuth2 token (cached) and lists accounts', async () => {
+    let tokenCalls = 0;
+    const t = mockTransport([
+      {
+        match: 'oauth2.googleapis.com/token',
+        respond: () => {
+          tokenCalls++;
+          return { status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) };
+        },
+      },
+      {
+        match: '/v2/accounts',
+        respond: (req) => {
+          expect(req.headers?.authorization).toBe('Bearer tok');
+          return { status: 200, body: JSON.stringify({ accounts: [{ name: 'accounts/pub-123' }] }) };
+        },
+      },
+    ]);
+    const client = new AdSenseClient(cfg as any, t);
+    const accounts = await client.listAccounts();
+    expect(accounts).toHaveLength(1);
+    expect(accounts[0]!.name).toBe('accounts/pub-123');
+    // second call reuses the cached token
+    await client.listAccounts();
+    expect(tokenCalls).toBe(1);
+  });
+
+  it('sends only Bearer auth (no developer-token) and paginates', async () => {
+    let calls = 0;
+    let sentHeaders: Record<string, string> = {};
+    const t = mockTransport([
+      {
+        match: 'oauth2.googleapis.com/token',
+        respond: () => ({ status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }),
+      },
+      {
+        match: '/adclients',
+        respond: (req) => {
+          calls++;
+          sentHeaders = req.headers ?? {};
+          if (calls === 1)
+            return { status: 200, body: JSON.stringify({ adClients: [{ name: 'a/1' }], nextPageToken: 'p2' }) };
+          return { status: 200, body: JSON.stringify({ adClients: [{ name: 'a/2' }] }) };
+        },
+      },
+    ]);
+    const client = new AdSenseClient(cfg as any, t);
+    const clients = await client.listAdClients();
+    expect(calls).toBe(2);
+    expect(clients).toHaveLength(2);
+    expect(sentHeaders.authorization).toBe('Bearer tok');
+    expect(sentHeaders['developer-token']).toBeUndefined();
+  });
+
+  it('generateReport passes dimensions/metrics/dates and parses rows', async () => {
+    let sentUrl = '';
+    const t = mockTransport([
+      {
+        match: 'oauth2.googleapis.com/token',
+        respond: () => ({ status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }),
+      },
+      {
+        match: 'reports:generate',
+        respond: (req) => {
+          sentUrl = req.url;
+          return {
+            status: 200,
+            body: JSON.stringify({ rows: [{ DATE: '2026-01-01', ESTIMATED_EARNINGS: '1.5' }], totals: { ESTIMATED_EARNINGS: '1.5' } }),
+          };
+        },
+      },
+    ]);
+    const client = new AdSenseClient(cfg as any, t);
+    const report = await client.generateReport({
+      dimensions: ['DATE'],
+      metrics: ['ESTIMATED_EARNINGS'],
+      startDate: '2026-01-01',
+      endDate: '2026-01-31',
+    });
+    expect(sentUrl).toContain('reports:generate');
+    expect(sentUrl).toContain('startDate=2026-01-01');
+    expect(report.rows).toHaveLength(1);
+    expect(report.totals?.ESTIMATED_EARNINGS).toBe('1.5');
+  });
+
+  it('propagates API errors', async () => {
+    const t = mockTransport([
+      {
+        match: 'oauth2.googleapis.com/token',
+        respond: () => ({ status: 200, body: JSON.stringify({ access_token: 'tok', expires_in: 3600 }) }),
+      },
+      { match: '/v2/', respond: () => ({ status: 403, body: JSON.stringify({ error: { message: 'denied' } }) }) },
+    ]);
+    const client = new AdSenseClient(cfg as any, t);
+    await expect(client.listSites()).rejects.toThrow(/failed/);
+  });
+});
+
+describe('createAdSense factory', () => {
+  it('builds a client with the default transport', () => {
+    const client = createAdSense(cfg as any);
+    expect(client).toBeInstanceOf(AdSenseClient);
+  });
+});
+
+describe('adsenseHtml', () => {
+  it('normalizes publisher ids to ca-pub-', () => {
+    expect(normalizeAdClient('pub-123')).toBe('ca-pub-123');
+    expect(normalizeAdClient('ca-pub-123')).toBe('ca-pub-123');
+  });
+  it('renders the loader script with the client id', () => {
+    const html = adsenseScript('pub-123');
+    expect(html).toContain('pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-123');
+    expect(html).toContain('async');
+  });
+  it('renders an ad unit with escaped attrs + push snippet', () => {
+    const html = adUnit({ adClient: 'pub-123', adSlot: '456', format: 'auto' });
+    expect(html).toContain('data-ad-client="ca-pub-123"');
+    expect(html).toContain('data-ad-slot="456"');
+    expect(html).toContain('(adsbygoogle = window.adsbygoogle || []).push({});');
+  });
+  it('escapes quotes in attrs', () => {
+    const html = adUnit({ adClient: 'pub-123', adSlot: '4" onload="x' });
+    expect(html).not.toContain('onload="x');
+    expect(html).toContain('&quot;');
+  });
+});

package/tests/oauth.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildAuthorizeUrl,
+  exchangeCode,
+  ADSENSE_READONLY_SCOPE,
+  type HttpTransport,
+} from '../src/index.js';
+
+describe('buildAuthorizeUrl', () => {
+  it('includes client, redirect, offline access and the adsense scope', () => {
+    const url = buildAuthorizeUrl({
+      clientId: 'cid.apps.googleusercontent.com',
+      redirectUri: 'https://nexus.bhooai.com',
+      state: 's1',
+    });
+    const parsed = new URL(url);
+    expect(parsed.origin + parsed.pathname).toBe('https://accounts.google.com/o/oauth2/v2/auth');
+    expect(parsed.searchParams.get('client_id')).toBe('cid.apps.googleusercontent.com');
+    expect(parsed.searchParams.get('redirect_uri')).toBe('https://nexus.bhooai.com');
+    expect(parsed.searchParams.get('response_type')).toBe('code');
+    expect(parsed.searchParams.get('access_type')).toBe('offline');
+    expect(parsed.searchParams.get('prompt')).toBe('consent');
+    expect(parsed.searchParams.get('scope')).toContain(ADSENSE_READONLY_SCOPE);
+    expect(parsed.searchParams.get('state')).toBe('s1');
+  });
+  it('requires clientId and redirectUri', () => {
+    expect(() => buildAuthorizeUrl({ clientId: '', redirectUri: 'https://x' })).toThrow(/clientId/);
+    expect(() => buildAuthorizeUrl({ clientId: 'c', redirectUri: '' })).toThrow(/redirectUri/);
+  });
+});
+
+describe('exchangeCode', () => {
+  const okTransport: HttpTransport = async (req) => {
+    expect(req.url).toContain('oauth2.googleapis.com/token');
+    const params = new URLSearchParams(req.body);
+    expect(params.get('grant_type')).toBe('authorization_code');
+    expect(params.get('code')).toBe('authcode123');
+    return {
+      status: 200,
+      body: JSON.stringify({ access_token: 'at', refresh_token: 'rt', expires_in: 3600 }),
+    };
+  };
+  it('returns the refresh token to persist', async () => {
+    const out = await exchangeCode(
+      { clientId: 'c', clientSecret: 's', code: 'authcode123', redirectUri: 'https://nexus.bhooai.com' },
+      okTransport,
+    );
+    expect(out).toEqual({ refreshToken: 'rt', accessToken: 'at', expiresIn: 3600 });
+  });
+  it('throws on non-200 without leaking transport internals', async () => {
+    const bad: HttpTransport = async () => ({ status: 400, body: JSON.stringify({ error: 'invalid_grant' }) });
+    await expect(
+      exchangeCode({ clientId: 'c', clientSecret: 's', code: 'bad', redirectUri: 'https://x' }, bad),
+    ).rejects.toThrow(/code exchange failed: HTTP 400/);
+  });
+});

package/vitest.config.ts

@@ -4,7 +4,7 @@ export default defineProject({
   test: {
     environment: 'node',
     include: ['tests/**/*.test.ts'],
-    env: { NEXUS_LICENSE_KEY: 'nxl_test_master_key_001' },
+    env: { NEXUS_LICENSE_KEY: 'nxl_test_master_key_001', NEXUS_LICENSE_ISSUER: '1' },
     globals: false,
     testTimeout: 15_000,
   },

package/src/GaqlBuilder.ts

@@ -1,72 +0,0 @@
-/**
- * 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

@@ -1,121 +0,0 @@
-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/tests/ads.test.ts

@@ -1,127 +0,0 @@
-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);
-  });
-});