How htdangkhoa/google-ads works
Project Type and Purpose
• This is a Node.js client library for the Google Ads API. It wraps the gRPC definitions (generated via ts-proto), exposes a friendly TypeScript/JavaScript API (classes like GoogleAds, Customer, QueryBuilder), and manages authentication, request building, logging, and streaming/mutation calls.
File Structure Analysis
• Top-level directories:
• src/ – core TS code: ServiceProvider, Service, LoggingInterceptor, QueryBuilder, constants, utils, and entry point index.ts
• scripts/build/ – build scripts producing CJS, ESM, and type declarations
• example/ – sample usage scripts (ad-group, campaign, search, etc.)
• tests/ – unit tests for each module
• .github/workflows/ – CI pipelines (build, test, publish)
• Config: multiple tsconfig.json for base/CJS/ESM/types, vitest.config.ts for testing.
• package.json orchestrates dependencies (grpc-js, google-auth-library, ts-proto) and build/test scripts.
README Insights
• Describes instantiation of auth clients (UserRefreshClient, JWT)
• Shows core abstractions: Customer service, GoogleAds service, search/searchStream, mutate
• Explains logging and interceptor configuration
• Notes build steps: generate protos, compile TS, run tests
Main Components
a. Library API Layer (TypeScript classes)
• ServiceProvider → dynamic loader of generated gRPC service clients
• Service (base class) → common request wrapper, error handling
• GoogleAds / Customer classes → specific API entry points
• QueryBuilder → DSL for building GAQL queries
• LoggingInterceptor → logs summary/detail of each RPC
b. Generated gRPC Layer
• ts-proto–generated stubs (imported under src via codegen)
• grpc-js Client channels
c. Authentication Layer
• google-auth-library clients (UserRefreshClient, JWT)
d. Google Ads API Backend (external gRPC service at ads.googleapis.com)
e. Build & CI Pipeline
• scripts/build → cjs, esm, types outputs in dist/
• .github/workflows → test, publish, version bump
Interactions and Data Flows
• The user’s Node.js app imports @htdangkhoa/google-ads → instantiates a Service (Customer or GoogleAds)
• ServiceProvider uses auth credentials to create a grpc-js channel to the Google Ads API endpoint
• On each API call (search, mutate):
• QueryBuilder (if used) builds GAQL string
• Service invokes the corresponding gRPC method on the generated client
• LoggingInterceptor intercepts request/response for logging
• grpc-js transmits over TLS to Google Ads backend and returns results
• Build pipeline compiles TS → JS (CJS/ESM) + .d.ts and publishes to npm
Architectural Patterns & Principles
• Wrapper + Facade pattern: ServiceProvider hides low-level gRPC details
• Interceptor pattern: LoggingInterceptor conforms to grpc-js interceptor API
• DSL for queries: QueryBuilder enforces type-safe GAQL composition
• Separation of concerns: Auth, transport, logging, request building, and service definitions are modular