# JavaScript Software Development Kit for Kevel Management APIs

Usable server-side as TypeScript or JavaScript!

- [Open Source on Github](https://github.com/adzerk/adzerk-management-sdk-js)
- [NPM Package](https://www.npmjs.com/package/@adzerk/management-sdk)

## Installation

Requires [Node.js v10](https://nodejs.org/en/about/releases/) or higher.

Shell

```shell
npm install --save @adzerk/management-sdk
```

or

Shell

```shell
yarn add @adzerk/management-sdk
```

## How It Works

Our Management SDK takes a data-driven approach to working with our API. This means that all of our operations are driven by OpenAPI documentation found at [https://github.com/adzerk/adzerk-api-specification](https://github.com/adzerk/adzerk-api-specification). This means that the SDK Client Factory takes a list of specifications during construction. There are several utility methods for building that specification list, the easiest of which is `buildFullSpecificationList`. You then pass that list to `fetchSpecifications` to load and parse the documents:

JavaScript

```javascript
let Adzerk = require("@adzerk/management-sdk");
let specificationList = Adzerk.buildFullSpecificationList();
let specifications = await Adzerk.fetchSpecifications(specificationList);
let client = await Adzerk.buildClient({ apiKey: "*****", specifications });
```

We also provide the ability to pin to a specific version of the OpenAPI documents as well. This allows a stable set of functionality but may prevent usage of the latest and greatest features. If you want to take advantage of this, you can use the `buildFullSpecificationList` helper method:

JavaScript

```javascript
let Adzerk = require("@adzerk/management-sdk");
let specificationList = Adzerk.buildFullSpecificationList({ version: "v1.0.1" });
let specifications = await Adzerk.fetchSpecifications(specificationList);
let client = await Adzerk.buildClient({ apiKey: "*****", specifications });
```

This will still download and parse the specifications at runtime. We also provide the ability to load the OpenAPI documents from disk. This will save some time and allow you pin to a specific revision (or allow you to patch them yourselves):

JavaScript

```javascript
let Adzerk = require("@adzerk/management-sdk");
let specificationList = Adzerk.buildFullSpecificationList({
  basePath: "../path/to/repo ",
});
let specifications = await Adzerk.fetchSpecifications(specificationList);
let client = await Adzerk.buildClient({ apiKey: "*****", specifications });
```

We also provide the ability to specify only the API objects you are interested in. By using this, you'll gain another performance boost as only a handful of documents will be parsed instead of the full set. This method also supports pinning to versions or loading from disk:

JavaScript

```javascript
let Adzerk = require("@adzerk/management-sdk");
let specificationList = Adzerk.buildPartialSpecificationList({
  version: "v1.0.1",
  objects: ["campaign", "flight", "ad"],
});
let specifications = await Adzerk.fetchSpecifications(specificationList);
let client = await Adzerk.buildClient({ apiKey: "*****", specifications });
```

## Acquiring API Credentials

Go to [API Keys page](https://app.adzerk.com/#!/api-keys/) to find active API keys.

## Object, Operation, Parameters Pattern

There is really only one method you will call on the SDK, and that is the `client.run` method. However, it takes at a minimum an object name (like `advertiser`) and a `camelCased` operation name (like `create`, `list`, or `listForCampaign`). Some operations also take a JavaScript object of parameters.

## Examples

The [Management API documentation](https://dev.kevel.com/reference/campaign-api-overview) has a complete set of code samples for each object and endpoint, but these examples give you a brief introduction to the SDK.

### Creating an Advertiser

JavaScript

```javascript
const Adzerk = require('@adzerk/management-sdk');
const apiKey = process.env.ADZERK_API_KEY;

async function createAdvertiser() {
  let specifications = await Adzerk.fetchSpecifications();
  let client = await Adzerk.buildClient({apiKey, specifications});

let advertiser = await client.run("advertiser", "create", {
    title: "Advertiser Name",
    isActive: true,
  });

console.log(advertiser);
}

createAdvertiser();
```

### List Flights in a Campaign

JavaScript

```javascript
const Adzerk = require('@adzerk/management-sdk');
const apiKey = process.env.ADZERK_API_KEY;

async function listFlightsForCampaign() {
  let specifications = await Adzerk.fetchSpecifications();
  let client = await Adzerk.buildClient({apiKey, specifications });

let flights = await client.run("flight", "listForCampaign", {campaignId: 123456});
  console.log(flights);

let names = flights.items.map(a => a.name)
  console.log(names);
}

listFlightsForCampaign();
```

### Instant Counts

JavaScript

```javascript
const Adzerk = require('@adzerk/management-sdk');
const apiKey = process.env.ADZERK_API_KEY;

async function getBulkCounts() {
  let specifications = await Adzerk.fetchSpecifications();
  let client = await Adzerk.buildClient({apiKey, specifications });

let counts = await client.run("realTimeReport", "bulk", {
    advertisers: [1234, 5678, 9012],
    campaigns: [8765, 4321, 9876],
  });

console.log(counts);
}

getBulkCounts();
```