@dmgt/google-ad-manager-api/README.md

Typed Google Ad Manager API

# @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

```typescript
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:

```typescript
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:

```javascript
/**
 * @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.

```typescript
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)
}
```