google-ads-cli-spec 0.1.0

package/dist/src/catalog.d.ts

@@ -0,0 +1,12 @@
+import type { OperationBaseline } from './discovery.js';
+export interface DocsCatalogEntry {
+    path: string;
+    topic: string;
+    url: string;
+}
+export interface CoverageThreshold {
+    totalCount: number;
+    coveredCountRequired: number;
+}
+export declare function collectDocsCatalogEntries(html: string): DocsCatalogEntry[];
+export declare function computeCoverageThreshold(operations: OperationBaseline[]): CoverageThreshold;

package/dist/src/catalog.js

@@ -0,0 +1,19 @@
+const DOCS_BASE_URL = 'https://developers.google.com';
+const DOCS_PATH_PATTERN = /\/google-ads\/api\/docs\/[^"]+/g;
+export function collectDocsCatalogEntries(html) {
+    const paths = new Set(html.match(DOCS_PATH_PATTERN) ?? []);
+    return [...paths]
+        .sort((left, right) => left.localeCompare(right))
+        .map((path) => ({
+        path,
+        topic: path.split('/')[4] ?? 'unknown',
+        url: `${DOCS_BASE_URL}${path}`
+    }));
+}
+export function computeCoverageThreshold(operations) {
+    const totalCount = operations.length;
+    return {
+        totalCount,
+        coveredCountRequired: Math.ceil(totalCount * 0.9)
+    };
+}

package/dist/src/discovery.d.ts

@@ -0,0 +1,17 @@
+export interface DiscoveryMethod {
+    httpMethod?: string;
+    path?: string;
+}
+export interface DiscoveryResource {
+    methods?: Record<string, DiscoveryMethod>;
+    resources?: Record<string, DiscoveryResource>;
+}
+export interface DiscoveryDocument {
+    resources?: Record<string, DiscoveryResource>;
+}
+export interface OperationBaseline {
+    operationId: string;
+    httpMethod: string;
+    path: string;
+}
+export declare function collectOperationBaselines(discovery: DiscoveryDocument): OperationBaseline[];

package/dist/src/discovery.js

@@ -0,0 +1,19 @@
+function walkResources(segments, resource, output) {
+    for (const [methodName, method] of Object.entries(resource.methods ?? {})) {
+        output.push({
+            operationId: [...segments, methodName].join('.'),
+            httpMethod: method.httpMethod ?? 'GET',
+            path: method.path ?? ''
+        });
+    }
+    for (const [resourceName, childResource] of Object.entries(resource.resources ?? {})) {
+        walkResources([...segments, resourceName], childResource, output);
+    }
+}
+export function collectOperationBaselines(discovery) {
+    const output = [];
+    for (const [resourceName, resource] of Object.entries(discovery.resources ?? {})) {
+        walkResources([resourceName], resource, output);
+    }
+    return output.sort((left, right) => left.operationId.localeCompare(right.operationId));
+}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './discovery.js';
+export * from './catalog.js';
+export * from './sync.js';
+export * from './shortcuts.js';

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export * from './discovery.js';
+export * from './catalog.js';
+export * from './sync.js';
+export * from './shortcuts.js';

package/dist/src/shortcuts.d.ts

@@ -0,0 +1,9 @@
+import type { OperationBaseline } from './discovery.js';
+export interface ShortcutEntry {
+    operationId: string;
+    commandPath: string[];
+    pathParams: string[];
+    httpMethod: string;
+    path: string;
+}
+export declare function generateShortcutEntries(operations: OperationBaseline[]): ShortcutEntry[];

package/dist/src/shortcuts.js

@@ -0,0 +1,25 @@
+const PATH_PARAM_PATTERN = /\{[+]?([^}]+)\}/g;
+function extractPathParams(path) {
+    const params = new Set();
+    for (const match of path.matchAll(PATH_PARAM_PATTERN)) {
+        const paramName = match[1];
+        if (paramName) {
+            params.add(paramName);
+        }
+    }
+    return [...params];
+}
+function deriveCommandPath(operationId) {
+    return operationId.split('.').filter(Boolean);
+}
+export function generateShortcutEntries(operations) {
+    return [...operations]
+        .sort((left, right) => left.operationId.localeCompare(right.operationId))
+        .map((operation) => ({
+        commandPath: deriveCommandPath(operation.operationId),
+        httpMethod: operation.httpMethod,
+        operationId: operation.operationId,
+        path: operation.path,
+        pathParams: extractPathParams(operation.path)
+    }));
+}

package/dist/src/sync.d.ts

@@ -0,0 +1,13 @@
+import { type CoverageThreshold, type DocsCatalogEntry } from './catalog.js';
+import { type OperationBaseline } from './discovery.js';
+export interface SyncGoogleAdsCatalogOptions {
+    version: string;
+    fetchText?: (url: string) => Promise<string>;
+}
+export interface SyncedGoogleAdsCatalog {
+    version: string;
+    operations: OperationBaseline[];
+    docsEntries: DocsCatalogEntry[];
+    coverage: CoverageThreshold;
+}
+export declare function syncGoogleAdsCatalog(options: SyncGoogleAdsCatalogOptions): Promise<SyncedGoogleAdsCatalog>;

package/dist/src/sync.js

@@ -0,0 +1,26 @@
+import { collectDocsCatalogEntries, computeCoverageThreshold } from './catalog.js';
+import { collectOperationBaselines } from './discovery.js';
+const DISCOVERY_URL = 'https://googleads.googleapis.com/$discovery/rest?version=';
+const DOCS_START_URL = 'https://developers.google.com/google-ads/api/docs/start';
+async function fetchTextViaHttp(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status}`);
+    }
+    return response.text();
+}
+export async function syncGoogleAdsCatalog(options) {
+    const fetchText = options.fetchText ?? fetchTextViaHttp;
+    const [discoveryText, docsHtml] = await Promise.all([
+        fetchText(`${DISCOVERY_URL}${options.version}`),
+        fetchText(DOCS_START_URL)
+    ]);
+    const operations = collectOperationBaselines(JSON.parse(discoveryText));
+    const docsEntries = collectDocsCatalogEntries(docsHtml);
+    return {
+        version: options.version,
+        operations,
+        docsEntries,
+        coverage: computeCoverageThreshold(operations)
+    };
+}

package/dist/test/catalog.test.d.ts

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

package/dist/test/catalog.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { collectDocsCatalogEntries, computeCoverageThreshold } from '../src/catalog.js';
+describe('collectDocsCatalogEntries', () => {
+    it('extracts unique Google Ads docs urls and derives topics', () => {
+        const html = `
+      <a href="/google-ads/api/docs/campaigns/overview">Campaigns</a>
+      <a href="/google-ads/api/docs/campaigns/create-campaigns">Create</a>
+      <a href="/google-ads/api/docs/conversions/overview">Conversions</a>
+      <a href="/google-ads/api/docs/campaigns/overview">Campaigns</a>
+    `;
+        expect(collectDocsCatalogEntries(html)).toEqual([
+            {
+                path: '/google-ads/api/docs/campaigns/create-campaigns',
+                topic: 'campaigns',
+                url: 'https://developers.google.com/google-ads/api/docs/campaigns/create-campaigns'
+            },
+            {
+                path: '/google-ads/api/docs/campaigns/overview',
+                topic: 'campaigns',
+                url: 'https://developers.google.com/google-ads/api/docs/campaigns/overview'
+            },
+            {
+                path: '/google-ads/api/docs/conversions/overview',
+                topic: 'conversions',
+                url: 'https://developers.google.com/google-ads/api/docs/conversions/overview'
+            }
+        ]);
+    });
+});
+describe('computeCoverageThreshold', () => {
+    it('rounds up the required count for ninety percent coverage', () => {
+        expect(computeCoverageThreshold([
+            { operationId: 'a', httpMethod: 'GET', path: 'x' },
+            { operationId: 'b', httpMethod: 'GET', path: 'x' },
+            { operationId: 'c', httpMethod: 'GET', path: 'x' },
+            { operationId: 'd', httpMethod: 'GET', path: 'x' },
+            { operationId: 'e', httpMethod: 'GET', path: 'x' },
+            { operationId: 'f', httpMethod: 'GET', path: 'x' },
+            { operationId: 'g', httpMethod: 'GET', path: 'x' },
+            { operationId: 'h', httpMethod: 'GET', path: 'x' },
+            { operationId: 'i', httpMethod: 'GET', path: 'x' }
+        ])).toEqual({
+            coveredCountRequired: 9,
+            totalCount: 9
+        });
+    });
+});

package/dist/test/discovery.test.d.ts

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

package/dist/test/discovery.test.js

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { collectOperationBaselines } from '../src/discovery.js';
+describe('collectOperationBaselines', () => {
+    it('normalizes Google Ads discovery resources into operation ids', () => {
+        const discovery = {
+            resources: {
+                customers: {
+                    resources: {
+                        campaigns: {
+                            methods: {
+                                mutate: {
+                                    httpMethod: 'POST',
+                                    path: 'v22/customers/{+customerId}/campaigns:mutate'
+                                }
+                            }
+                        },
+                        googleAds: {
+                            methods: {
+                                search: {
+                                    httpMethod: 'POST',
+                                    path: 'v22/customers/{+customerId}/googleAds:search'
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        expect(collectOperationBaselines(discovery)).toEqual([
+            {
+                httpMethod: 'POST',
+                operationId: 'customers.campaigns.mutate',
+                path: 'v22/customers/{+customerId}/campaigns:mutate'
+            },
+            {
+                httpMethod: 'POST',
+                operationId: 'customers.googleAds.search',
+                path: 'v22/customers/{+customerId}/googleAds:search'
+            }
+        ]);
+    });
+});

package/dist/test/shortcuts.test.d.ts

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

package/dist/test/shortcuts.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { generateShortcutEntries } from '../src/shortcuts.js';
+describe('generateShortcutEntries', () => {
+    it('maps a customers mutate operation to a shortcut entry', () => {
+        expect(generateShortcutEntries([
+            {
+                httpMethod: 'POST',
+                operationId: 'customers.campaigns.mutate',
+                path: 'v22/customers/{+customerId}/campaigns:mutate'
+            }
+        ])).toEqual([
+            {
+                commandPath: ['customers', 'campaigns', 'mutate'],
+                httpMethod: 'POST',
+                operationId: 'customers.campaigns.mutate',
+                path: 'v22/customers/{+customerId}/campaigns:mutate',
+                pathParams: ['customerId']
+            }
+        ]);
+    });
+    it('keeps root level operations as a two segment command path', () => {
+        expect(generateShortcutEntries([
+            {
+                httpMethod: 'POST',
+                operationId: 'audienceInsights.listInsightsEligibleDates',
+                path: 'v22/audienceInsights:listInsightsEligibleDates'
+            }
+        ])).toEqual([
+            {
+                commandPath: ['audienceInsights', 'listInsightsEligibleDates'],
+                httpMethod: 'POST',
+                operationId: 'audienceInsights.listInsightsEligibleDates',
+                path: 'v22/audienceInsights:listInsightsEligibleDates',
+                pathParams: []
+            }
+        ]);
+    });
+    it('extracts resourceName path params for get operations', () => {
+        expect(generateShortcutEntries([
+            {
+                httpMethod: 'GET',
+                operationId: 'googleAdsFields.get',
+                path: 'v22/{+resourceName}'
+            }
+        ])).toEqual([
+            {
+                commandPath: ['googleAdsFields', 'get'],
+                httpMethod: 'GET',
+                operationId: 'googleAdsFields.get',
+                path: 'v22/{+resourceName}',
+                pathParams: ['resourceName']
+            }
+        ]);
+    });
+    it('retains googleAdsFields search command segments', () => {
+        expect(generateShortcutEntries([
+            {
+                httpMethod: 'POST',
+                operationId: 'googleAdsFields.search',
+                path: 'v22/googleAdsFields:search'
+            }
+        ])).toEqual([
+            {
+                commandPath: ['googleAdsFields', 'search'],
+                httpMethod: 'POST',
+                operationId: 'googleAdsFields.search',
+                path: 'v22/googleAdsFields:search',
+                pathParams: []
+            }
+        ]);
+    });
+});

package/dist/test/sync.test.d.ts

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

package/dist/test/sync.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { syncGoogleAdsCatalog } from '../src/sync.js';
+describe('syncGoogleAdsCatalog', () => {
+    it('collects operations, docs entries, and a ninety percent threshold', async () => {
+        const responses = new Map([
+            [
+                'https://googleads.googleapis.com/$discovery/rest?version=v22',
+                JSON.stringify({
+                    resources: {
+                        customers: {
+                            resources: {
+                                campaigns: {
+                                    methods: {
+                                        mutate: {
+                                            httpMethod: 'POST',
+                                            path: 'v22/customers/{+customerId}/campaigns:mutate'
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                })
+            ],
+            [
+                'https://developers.google.com/google-ads/api/docs/start',
+                `
+          <a href="/google-ads/api/docs/campaigns/overview">Campaigns</a>
+          <a href="/google-ads/api/docs/conversions/overview">Conversions</a>
+        `
+            ]
+        ]);
+        const result = await syncGoogleAdsCatalog({
+            fetchText: async (url) => {
+                const value = responses.get(url);
+                if (!value) {
+                    throw new Error(`Unexpected URL: ${url}`);
+                }
+                return value;
+            },
+            version: 'v22'
+        });
+        expect(result).toEqual({
+            coverage: {
+                coveredCountRequired: 1,
+                totalCount: 1
+            },
+            docsEntries: [
+                {
+                    path: '/google-ads/api/docs/campaigns/overview',
+                    topic: 'campaigns',
+                    url: 'https://developers.google.com/google-ads/api/docs/campaigns/overview'
+                },
+                {
+                    path: '/google-ads/api/docs/conversions/overview',
+                    topic: 'conversions',
+                    url: 'https://developers.google.com/google-ads/api/docs/conversions/overview'
+                }
+            ],
+            operations: [
+                {
+                    httpMethod: 'POST',
+                    operationId: 'customers.campaigns.mutate',
+                    path: 'v22/customers/{+customerId}/campaigns:mutate'
+                }
+            ],
+            version: 'v22'
+        });
+    });
+});

package/package.json

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