google-ads-cli-core 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './invoke.js';
+export * from './oauth.js';
+export * from './profile.js';

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export * from './invoke.js';
+export * from './oauth.js';
+export * from './profile.js';

package/dist/src/invoke.d.ts

@@ -0,0 +1,24 @@
+export interface OperationDescriptor {
+    operationId: string;
+    httpMethod: string;
+    path: string;
+}
+export interface BuildGoogleAdsRequestOptions {
+    operation: OperationDescriptor;
+    accessToken: string;
+    developerToken: string;
+    loginCustomerId?: string;
+    linkedCustomerId?: string;
+    pathParams?: Record<string, string>;
+    payload?: unknown;
+}
+export interface BuiltGoogleAdsRequest {
+    operationId: string;
+    url: string;
+    init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    };
+}
+export declare function buildGoogleAdsRequest(options: BuildGoogleAdsRequestOptions): BuiltGoogleAdsRequest;

package/dist/src/invoke.js

@@ -0,0 +1,38 @@
+const GOOGLE_ADS_API_BASE_URL = 'https://googleads.googleapis.com';
+const PATH_PARAM_PATTERN = /\{[+]?([^}]+)\}/g;
+function interpolatePath(path, pathParams) {
+    return path.replace(PATH_PARAM_PATTERN, (_match, key) => {
+        const value = pathParams[key];
+        if (!value) {
+            throw new Error(`Missing required path param: ${key}`);
+        }
+        return encodeURIComponent(value);
+    });
+}
+export function buildGoogleAdsRequest(options) {
+    const headers = {
+        Authorization: `Bearer ${options.accessToken}`,
+        'developer-token': options.developerToken
+    };
+    if (options.loginCustomerId) {
+        headers['login-customer-id'] = options.loginCustomerId;
+    }
+    if (options.linkedCustomerId) {
+        headers['linked-customer-id'] = options.linkedCustomerId;
+    }
+    const resolvedPath = interpolatePath(options.operation.path, options.pathParams ?? {});
+    if (options.payload !== undefined) {
+        headers['content-type'] = 'application/json';
+    }
+    return {
+        operationId: options.operation.operationId,
+        url: `${GOOGLE_ADS_API_BASE_URL}/${resolvedPath}`,
+        init: {
+            method: options.operation.httpMethod,
+            headers,
+            ...(options.payload !== undefined
+                ? { body: JSON.stringify(options.payload) }
+                : {})
+        }
+    };
+}

package/dist/src/oauth.d.ts

@@ -0,0 +1,27 @@
+export interface GoogleOAuthTokenResponse {
+    access_token: string;
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+    token_type: string;
+}
+export interface GoogleAuthUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    state?: string;
+}
+export interface ExchangeAuthCodeOptions {
+    clientId: string;
+    clientSecret: string;
+    authCode: string;
+    redirectUri: string;
+}
+export interface RefreshAccessTokenOptions {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}
+export type OAuthFetch = typeof fetch;
+export declare function buildGoogleAdsAuthUrl(options: GoogleAuthUrlOptions): string;
+export declare function exchangeAuthCode(options: ExchangeAuthCodeOptions, fetchImpl?: OAuthFetch): Promise<GoogleOAuthTokenResponse>;
+export declare function refreshGoogleAdsAccessToken(options: RefreshAccessTokenOptions, fetchImpl?: OAuthFetch): Promise<GoogleOAuthTokenResponse>;

package/dist/src/oauth.js

@@ -0,0 +1,57 @@
+const GOOGLE_OAUTH_AUTHORIZE_URL = 'https://accounts.google.com/o/oauth2/v2/auth';
+const GOOGLE_OAUTH_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const GOOGLE_ADS_SCOPE = 'https://www.googleapis.com/auth/adwords';
+function buildTokenRequest(body) {
+    return {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/x-www-form-urlencoded'
+        },
+        body: body.toString()
+    };
+}
+async function parseTokenResponse(response) {
+    const json = (await response.json());
+    if (!response.ok || !json.access_token) {
+        throw new Error(json.error_description ?? json.error ?? `OAuth request failed: ${response.status}`);
+    }
+    return {
+        access_token: json.access_token,
+        expires_in: json.expires_in ?? 0,
+        refresh_token: json.refresh_token,
+        scope: json.scope ?? GOOGLE_ADS_SCOPE,
+        token_type: json.token_type ?? 'Bearer'
+    };
+}
+export function buildGoogleAdsAuthUrl(options) {
+    const url = new URL(GOOGLE_OAUTH_AUTHORIZE_URL);
+    url.searchParams.set('client_id', options.clientId);
+    url.searchParams.set('redirect_uri', options.redirectUri);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('scope', GOOGLE_ADS_SCOPE);
+    url.searchParams.set('access_type', 'offline');
+    url.searchParams.set('prompt', 'consent');
+    if (options.state) {
+        url.searchParams.set('state', options.state);
+    }
+    return url.toString();
+}
+export async function exchangeAuthCode(options, fetchImpl = fetch) {
+    const body = new URLSearchParams({
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+        code: options.authCode,
+        grant_type: 'authorization_code',
+        redirect_uri: options.redirectUri
+    });
+    return parseTokenResponse(await fetchImpl(GOOGLE_OAUTH_TOKEN_URL, buildTokenRequest(body)));
+}
+export async function refreshGoogleAdsAccessToken(options, fetchImpl = fetch) {
+    const body = new URLSearchParams({
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+        refresh_token: options.refreshToken,
+        grant_type: 'refresh_token'
+    });
+    return parseTokenResponse(await fetchImpl(GOOGLE_OAUTH_TOKEN_URL, buildTokenRequest(body)));
+}

package/dist/src/profile.d.ts

@@ -0,0 +1,18 @@
+export interface GoogleAdsProfile {
+    api_version: string;
+    developer_token: string;
+    client_id: string;
+    client_secret: string;
+    refresh_token?: string;
+    default_customer_id?: string;
+    login_customer_id?: string;
+    linked_customer_id?: string;
+}
+export interface GoogleAdsConfig {
+    profiles: Record<string, GoogleAdsProfile>;
+}
+export declare function getDefaultGoogleAdsConfigPath(): string;
+export declare function loadGoogleAdsConfig(configPath?: string): Promise<GoogleAdsConfig>;
+export declare function saveGoogleAdsConfig(configPath: string, config: GoogleAdsConfig): Promise<void>;
+export declare function upsertGoogleAdsProfile(configPath: string, profileName: string, profile: GoogleAdsProfile): Promise<GoogleAdsConfig>;
+export declare function getGoogleAdsProfile(configPath: string, profileName: string): Promise<GoogleAdsProfile>;

package/dist/src/profile.js

@@ -0,0 +1,45 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { parse, stringify } from 'yaml';
+export function getDefaultGoogleAdsConfigPath() {
+    return join(homedir(), '.config', 'gads', 'config.yaml');
+}
+export async function loadGoogleAdsConfig(configPath = getDefaultGoogleAdsConfigPath()) {
+    try {
+        const file = await readFile(configPath, 'utf8');
+        const parsed = parse(file);
+        return {
+            profiles: parsed?.profiles ?? {}
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { profiles: {} };
+        }
+        throw error;
+    }
+}
+export async function saveGoogleAdsConfig(configPath, config) {
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, stringify(config), 'utf8');
+}
+export async function upsertGoogleAdsProfile(configPath, profileName, profile) {
+    const config = await loadGoogleAdsConfig(configPath);
+    const nextConfig = {
+        profiles: {
+            ...config.profiles,
+            [profileName]: profile
+        }
+    };
+    await saveGoogleAdsConfig(configPath, nextConfig);
+    return nextConfig;
+}
+export async function getGoogleAdsProfile(configPath, profileName) {
+    const config = await loadGoogleAdsConfig(configPath);
+    const profile = config.profiles[profileName];
+    if (!profile) {
+        throw new Error(`Unknown profile: ${profileName}`);
+    }
+    return profile;
+}

package/dist/test/invoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/invoke.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { buildGoogleAdsRequest } from '../src/invoke.js';
+describe('buildGoogleAdsRequest', () => {
+    it('interpolates path params and required Google Ads headers', () => {
+        const request = buildGoogleAdsRequest({
+            accessToken: 'token-123',
+            developerToken: 'dev-456',
+            linkedCustomerId: '9998887776',
+            loginCustomerId: '1234567890',
+            operation: {
+                httpMethod: 'POST',
+                operationId: 'customers.campaigns.mutate',
+                path: 'v22/customers/{+customerId}/campaigns:mutate'
+            },
+            pathParams: {
+                customerId: '5554443333'
+            },
+            payload: {
+                mutateOperations: []
+            }
+        });
+        expect(request).toEqual({
+            init: {
+                body: JSON.stringify({
+                    mutateOperations: []
+                }),
+                headers: {
+                    Authorization: 'Bearer token-123',
+                    'content-type': 'application/json',
+                    'developer-token': 'dev-456',
+                    'linked-customer-id': '9998887776',
+                    'login-customer-id': '1234567890'
+                },
+                method: 'POST'
+            },
+            operationId: 'customers.campaigns.mutate',
+            url: 'https://googleads.googleapis.com/v22/customers/5554443333/campaigns:mutate'
+        });
+    });
+});

package/dist/test/oauth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/oauth.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { buildGoogleAdsAuthUrl, exchangeAuthCode, refreshGoogleAdsAccessToken } from '../src/oauth.js';
+describe('buildGoogleAdsAuthUrl', () => {
+    it('creates an installed-app OAuth URL for the adwords scope', () => {
+        const authUrl = buildGoogleAdsAuthUrl({
+            clientId: 'client-id',
+            redirectUri: 'http://127.0.0.1:8085/callback',
+            state: 'state-123'
+        });
+        expect(authUrl).toContain('https://accounts.google.com/o/oauth2/v2/auth');
+        expect(authUrl).toContain('client_id=client-id');
+        expect(authUrl).toContain('scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords');
+        expect(authUrl).toContain('access_type=offline');
+        expect(authUrl).toContain('prompt=consent');
+        expect(authUrl).toContain('state=state-123');
+    });
+});
+describe('oauth token exchanges', () => {
+    it('exchanges an auth code for tokens', async () => {
+        const result = await exchangeAuthCode({
+            authCode: 'code-123',
+            clientId: 'client-id',
+            clientSecret: 'client-secret',
+            redirectUri: 'http://127.0.0.1:8085/callback'
+        }, async (url, init) => {
+            expect(url).toBe('https://oauth2.googleapis.com/token');
+            expect(init?.method).toBe('POST');
+            expect(String(init?.body)).toContain('grant_type=authorization_code');
+            return new Response(JSON.stringify({
+                access_token: 'access-123',
+                expires_in: 3600,
+                refresh_token: 'refresh-456',
+                scope: 'https://www.googleapis.com/auth/adwords',
+                token_type: 'Bearer'
+            }), { status: 200 });
+        });
+        expect(result.refresh_token).toBe('refresh-456');
+        expect(result.access_token).toBe('access-123');
+    });
+    it('refreshes an access token from a refresh token', async () => {
+        const result = await refreshGoogleAdsAccessToken({
+            clientId: 'client-id',
+            clientSecret: 'client-secret',
+            refreshToken: 'refresh-456'
+        }, async (_url, init) => {
+            expect(String(init?.body)).toContain('grant_type=refresh_token');
+            expect(String(init?.body)).toContain('refresh_token=refresh-456');
+            return new Response(JSON.stringify({
+                access_token: 'access-789',
+                expires_in: 3600,
+                scope: 'https://www.googleapis.com/auth/adwords',
+                token_type: 'Bearer'
+            }), { status: 200 });
+        });
+        expect(result.access_token).toBe('access-789');
+    });
+});

package/dist/test/profile.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/profile.test.js

@@ -0,0 +1,72 @@
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { loadGoogleAdsConfig, saveGoogleAdsConfig, upsertGoogleAdsProfile } from '../src/profile.js';
+describe('google ads profile config', () => {
+    it('saves and loads yaml config files', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'gads-profile-'));
+        const configPath = join(dir, 'config.yaml');
+        await saveGoogleAdsConfig(configPath, {
+            profiles: {
+                default: {
+                    api_version: 'v22',
+                    client_id: 'client-id',
+                    client_secret: 'client-secret',
+                    developer_token: 'developer-token',
+                    refresh_token: 'refresh-token'
+                }
+            }
+        });
+        expect(await loadGoogleAdsConfig(configPath)).toEqual({
+            profiles: {
+                default: {
+                    api_version: 'v22',
+                    client_id: 'client-id',
+                    client_secret: 'client-secret',
+                    developer_token: 'developer-token',
+                    refresh_token: 'refresh-token'
+                }
+            }
+        });
+        expect(await readFile(configPath, 'utf8')).toContain('developer_token');
+    });
+    it('upserts a named profile without dropping other profiles', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'gads-profile-'));
+        const configPath = join(dir, 'config.yaml');
+        await saveGoogleAdsConfig(configPath, {
+            profiles: {
+                keep: {
+                    api_version: 'v22',
+                    client_id: 'keep-client',
+                    client_secret: 'keep-secret',
+                    developer_token: 'keep-dev'
+                }
+            }
+        });
+        await upsertGoogleAdsProfile(configPath, 'default', {
+            api_version: 'v22',
+            client_id: 'client-id',
+            client_secret: 'client-secret',
+            developer_token: 'developer-token',
+            refresh_token: 'refresh-token'
+        });
+        expect(await loadGoogleAdsConfig(configPath)).toEqual({
+            profiles: {
+                keep: {
+                    api_version: 'v22',
+                    client_id: 'keep-client',
+                    client_secret: 'keep-secret',
+                    developer_token: 'keep-dev'
+                },
+                default: {
+                    api_version: 'v22',
+                    client_id: 'client-id',
+                    client_secret: 'client-secret',
+                    developer_token: 'developer-token',
+                    refresh_token: 'refresh-token'
+                }
+            }
+        });
+    });
+});

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "google-ads-cli-core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "dependencies": {
+    "yaml": "^2.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}