@openpromo/google-ads

Type-safe TypeScript SDK for the Google Ads API v23 — generated from protobuf, with a typed GAQL query builder.

Powering openpromo.app — the AI-native social media workspace.

What

A fetch-based, runtime-agnostic Google Ads v23 client generated from the official protos. 184 resource types, 111 services, 543 enums, 235 metric fields, 132 segment fields — all typed. Plus a customer-bound factory for campaign lifecycle flows and a typed GAQL query builder with field-literal autocomplete and row-level narrowing.

Install

bun add @openpromo/google-ads
# or
npm install @openpromo/google-ads

Use

import { Google } from "@openpromo/google-ads";

const client = Google.createClient({
  getAccessToken: async () => db.getGoogleToken(userId),
  developerToken: process.env.GOOGLE_ADS_DEV_TOKEN!,
  loginCustomerId: "1234567890",
});
const customer = Google.Ads.customer(client, "9999999999");

// Campaign lifecycle — rich refs chain automatically
const budget = await customer.campaignBudgets.create({
  name: "Q1",
  amountMicros: "5000000",
});

const campaign = await customer.campaigns.create({
  name: "Search Q1",
  status: "PAUSED",
  advertisingChannelType: "SEARCH",
  campaignBudget: budget,               // rich ref, auto-resolved
});

const adGroup = await customer.adGroups.create({
  name: "Shoes",
  status: "ENABLED",
  type: "SEARCH_STANDARD",
  campaign,                              // same pattern
});

// Typed GAQL — full autocomplete, narrowed row shape
const { rows } = await customer.gaql
  .from("campaign")
  .select("campaign.id", "campaign.name", "metrics.clicks")
  .where("campaign.status = 'ENABLED'")
  .limit(100)
  .execute();

// rows: Array<{ campaign: { id: string; name: string }; metrics: { clicks: string } }>

Features

• 184 resource types, 111 services — generated from pinned v23 protos
• Typed GAQL builder — .from().select(...).where().limit().execute() with deep row narrowing
• Customer-bound factory — customer.campaigns.create(...), customer.adGroups.create(...), rich refs
• Proper error surface — GoogleAdsError parses nested GoogleAdsFailure details + request ID
• Runtime agnostic — native fetch, pluggable OAuth via getAccessToken callback
• Pagination — async iterables via customer.gaql.from(...).stream() and raw Google.Ads.paginate()

Umbrella package

For a single install covering Meta + TikTok + Google Ads, use @openpromo/ad-platforms.

License

MIT © OpenPromo