README.md

@dmgt/google-ad-manager-api

A fully typed library to access Google's Ad Manager.

Installation

npm install google-auth-library @dmgt/google-ad-manager-api

Usage

Simple queries

import {
  GoogleAdManager,
  In,
  Not,
  Like,
  getByStatement,
} from '@dmgt/google-ad-manager-api'
import { JWT } from 'google-auth-lbrary'

const jwt = new JWT({
  key: 'MY_JWT_KEY',
  email: 'MY_JWT_EMAIL',
  scopes: ['https://www.googleapis.com/auth/dfp'],
})

const api = new GoogleAdManager({
  applicationName: 'MY_APPLICATION_NAME',
  networkCode: 123456789,
  authorize: () => jwt.authorize(),
})

const client = await api.createLineItemServiceClient()

const [response] = await getByStatement(client, 'lineItems', {
  limit: 10,
  where: {
    orderId: In(1, 2, 3),
    id: Not(11222),
    name: Like('foo %'),
    orderName: 'Foo',
  },
})

expect(response.rval?.results).toHaveLength(10)

The following will produce the same result albeit more verbose:

import {
  LineItemService,
  In,
  Not,
  Like,
  pql,
} from '@dmgt/google-ad-manager-api'

const [response] = await client.getLineItemsByStatementAsync({
  filterStatement: {
    query: pql<LineItemService.LineItems>({
      limit: 10,
      where: {
        orderId: In(1, 2, 3),
        id: Not(11222),
        name: Like('foo %'),
        orderName: 'Foo',
      },
    }),
  },
})

You can also type the pql function with JSDocs:

/**
 * @typedef {import('@dmgt/google-ad-manager-api').PQL<
 *   import('@dmgt/google-ad-manager-api').LineItemService.LineItems
 * >} LineItemsPQL
 */

const [response] = await client.getLineItemsByStatementAsync({
  filterStatement: {
    query: /** @type {LineItemsPQL} */ (pql)({
      limit: 10,
      where: {
        orderId: In(1, 2, 3),
        id: Not(11222),
        name: Like('foo %'),
        orderName: 'Foo',
      },
    }),
  },
})

Paginated queries

When quering large amounts of data, you'd generally want to use GAM's pagination feature. Use the iterate function to help iterate through all individual items in paginated queries.

import {
  GoogleAdManager,
  iterate,
  getByStatement,
} from '@dmgt/google-ad-manager-api'
import { JWT } from 'google-auth-lbrary'

const jwt = new JWT({
  key: 'MY_JWT_KEY',
  email: 'MY_JWT_EMAIL',
  scopes: ['https://www.googleapis.com/auth/dfp'],
})

const api = new GoogleAdManager({
  applicationName: 'MY_APPLICATION_NAME',
  networkCode: 123456789,
  authorize: () => jwt.authorize(),
})

const client = await api.createLineItemServiceClient()

for await (const result of iterate({
  executeQuery: (limit, offset) =>
    getByStatement(client, 'lineItems', {
      limit,
      offset,
    }),
})) {
  console.info(result)
}