npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@adginr/google-ads-rest

v0.4.0

Published

Typed Google Ads API client over REST (no gRPC, no developer token) plus ready-made agent tools.

Readme

@adginr/google-ads-rest

Typed Google Ads API client for Node.js over REST, plus ready-made tools for AI agents.

  • fetch and OAuth only: no gRPC, no protobuf runtime, no developer token.
  • Types for all of Google Ads API v26, generated from Google's REST discovery document.
  • One atomic mutate() for every resource type, GAQL search() with pagination, readable errors.
  • MutatePlan to publish a whole campaign in one atomic request, or as a background batch job.
  • 43 agent tools with zod schemas, usable from MCP, TanStack AI, the Vercel AI SDK or plain code.
npm install @adginr/google-ads-rest

Requires Node.js 22 or newer.

Credentials

You need an OAuth client and a refresh token with the https://www.googleapis.com/auth/adwords scope:

  1. In Google Cloud Console → Google Auth Platform → Clients, create a client of type Desktop app in a project with the Google Ads API enabled.
  2. Get a refresh token, for example with npx @adginr/google-ads-mcp auth client_secret.json, which runs the sign-in and writes everything to .env.

| Variable | Required | Meaning | | ------------------------------ | -------- | --------------------------------------------------------------- | | GOOGLE_ADS_CLIENT_ID | yes | OAuth client ID | | GOOGLE_ADS_CLIENT_SECRET | yes | OAuth client secret | | GOOGLE_ADS_REFRESH_TOKEN | yes | Refresh token of the Google user | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | no | Manager (MCC) account used to reach client accounts; dashes ok. |

Google retired developer tokens on 2026-09-09: API access now comes from the Cloud project that owns the OAuth client.

Client

import { GoogleAdsClient, resourceNames, type services } from '@adginr/google-ads-rest';

const ads = GoogleAdsClient.fromEnv(); // or new GoogleAdsClient({ clientId, clientSecret, refreshToken })

// GAQL, all pages up to maxRows (default 10 000). Rows are typed as services.GoogleAdsRow.
const rows = await ads.search(
  '1234567890',
  `SELECT campaign.id, campaign.name, metrics.cost_micros
	 FROM campaign WHERE segments.date DURING LAST_30_DAYS`
);
rows[0]?.campaign?.name;

// Atomic mutate across resource types (GoogleAdsService.Mutate). validateOnly makes it a dry run.
const operations: services.MutateOperation[] = [
  {
    campaignOperation: {
      update: { resourceName: resourceNames.campaign('1234567890', '987'), status: 'PAUSED' },
      updateMask: 'status'
    }
  }
];
await ads.mutate('1234567890', operations, { validateOnly: true });

await ads.listAccessibleCustomers(); // ['customers/1234567890', …]
await ads.generateKeywordIdeas('1234567890', { keywordSeed: { keywords: ['car lease'] } });
await ads.suggestGeoTargetConstants(['Mün'], { locale: 'de', countryCode: 'DE' });
await ads.searchFields("SELECT name, selectable WHERE name LIKE 'campaign.%'");

REST returns int64 values (IDs, metrics, *Micros) as strings and omits fields that hold their default value (0, false, ''). Money is in micros: divide by 1 000 000.

Publishing a whole campaign

MutatePlan sends related entities together. Entities refer to each other through temporary resource names (negative IDs) that Google resolves within the request, and the results come back under your own keys. The operation builders (searchCampaignOperation, adGroupOperation, keywordOperation, responsiveSearchAdOperation, negativeKeywordListOperation, …) start everything that can spend PAUSED.

import {
  MutatePlan,
  adGroupOperation,
  campaignBudgetOperation,
  campaignTargetingOperations,
  keywordOperation,
  searchCampaignOperation
} from '@adginr/google-ads-rest';

const plan = new MutatePlan('1234567890');
const budget = plan.tempResourceName('campaignBudgets');
plan.add(
  campaignBudgetOperation({
    resourceName: budget,
    name: 'Sofas budget',
    amountMicros: 50e6,
    explicitlyShared: false
  }),
  'budget'
);
const campaign = plan.tempResourceName('campaigns');
plan.add(
  searchCampaignOperation({
    resourceName: campaign,
    name: 'Sofas',
    budget,
    bidding: { strategy: 'MAXIMIZE_CLICKS' },
    containsEuPoliticalAdvertising: false
  }),
  'campaign'
);
for (const op of campaignTargetingOperations(campaign, {
  locationIds: [2784],
  languageIds: [1000]
}))
  plan.add(op);
const adGroup = plan.tempResourceName('adGroups');
plan.add(adGroupOperation({ resourceName: adGroup, campaign, name: 'Outdoor sofas' }), 'adGroup');
plan.add(
  keywordOperation({ adGroup, text: 'outdoor sofa', matchType: 'PHRASE' }),
  'kw:outdoor sofa'
);

await plan.publish(ads, { validateOnly: true }); // Google checks every operation, nothing changes
const { resourceNames } = await plan.publish(ads); // { budget: 'customers/…/campaignBudgets/…', … }

publish is atomic (all or nothing) and takes up to 10 000 operations. Larger plans go through a batch job: plan.publishInBackground(ads, { onProgress }) uploads in chunks, polls progress and returns the resource names plus per-operation failures. Batch jobs are not atomic and have no dry run, so dry-run smaller plans (for example one per campaign) first. To survive a restart, call plan.submitBatchJob(ads), store the job name and plan.keys, and later call waitForBatchJob and collectBatchJobResults.

Errors

Every failure is a GoogleAdsError. Its message leads with Google's specific error codes rather than the generic "invalid argument":

Google Ads API 400 INVALID_ARGUMENT: queryError.UNRECOGNIZED_FIELD: Unrecognized field in the query: 'campaign.nope'.

error.errors holds each entry (code, message, field, trigger), and error.requestId is the ID to quote to Google support.

Types

import type { common, resources, services } from '@adginr/google-ads-rest';

const keyword: common.KeywordInfo = { text: 'car lease', matchType: 'EXACT' };
type Status = NonNullable<resources.Campaign['status']>; // 'ENABLED' | 'PAUSED' | 'REMOVED' | …

Types are generated from the discovery document and erased at build time, so they cost nothing at runtime. GAQL_RESOURCES lists every resource that can follow FROM.

GAQL helpers

import { buildGaql, gaqlString, unsafeConditionReason } from '@adginr/google-ads-rest';

const query = buildGaql({
  fields: ['ad_group_criterion.keyword.text'],
  resource: 'ad_group_criterion',
  conditions: [`ad_group_criterion.keyword.text = ${gaqlString(userInput)}`], // escaped literal
  limit: 100
});

Never interpolate free text into GAQL without gaqlString. unsafeConditionReason rejects conditions that would rewrite the query (clause keywords, comments, ; outside quotes).

Agent tools

@adginr/google-ads-rest/tools exports adsTools: each tool has a name, a description written for the model, zod input and output schemas, annotations (readOnly, destructive, idempotent) and run(input, { ads }).

import { GoogleAdsClient } from '@adginr/google-ads-rest';
import { adsTools, readOnlyAdsTools } from '@adginr/google-ads-rest/tools';

const ads = GoogleAdsClient.fromEnv();
const tool = adsTools.find((t) => t.name === 'list_campaigns')!;
const result = await tool.run(tool.input.parse({ customerId: '123-456-7890' }), { ads });

With TanStack AI:

import { toolDefinition } from '@tanstack/ai';

const tools = adsTools.map((tool) =>
  toolDefinition({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.input,
    outputSchema: tool.output,
    needsApproval: !tool.annotations.readOnly // ask the user before any change
  }).server((input) => tool.run(input, { ads }))
);

With the Vercel AI SDK:

import { tool as aiTool } from 'ai';

const tools = Object.fromEntries(
  adsTools.map((t) => [
    t.name,
    aiTool({
      description: t.description,
      inputSchema: t.input,
      execute: (input) => t.run(input, { ads })
    })
  ])
);

Always parse input through tool.input before run: the schemas normalize what is safe to normalize (dashes in customer IDs, enum case, whitespace) and reject the rest with messages the model can act on.

The full tool list is in the MCP server README. Write your own with defineTool().

License

Apache-2.0. Not affiliated with Google.