Amazon Ads API

https://github.com/whitebox-co/amazon-ads-api
Admin
A fully typed, auto-generated TypeScript library for the Amazon Ads API, simplifying integration...
Tokens:2,501
Snippets:16
Trust Score:5.8
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Installing Amazon Ads API SDK via npm

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This command installs the Amazon Ads API SDK from npm, making it available as a dependency in your project. It's the standard way to integrate the library for general use.

```Shell
npm install @whitebox-co/amazon-ads-api
```

--------------------------------

### Installing Amazon Ads API SDK for Development

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This command installs all necessary development dependencies for the Amazon Ads API SDK. It is used when setting up the project for local development or contributing to the library, assuming all prerequisites are already satisfied.

```Shell
npm install
```

--------------------------------

### Initializing Single Amazon Ads Attribution Client (TypeScript)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This snippet demonstrates how to initialize and use a single Amazon Ads Attribution Client. It shows how to optionally configure throttling and retry mechanisms, set global configuration, and then obtain a configured client instance using `amazonAdsApi.getConfiguredApi`. It also includes an example of making a GET call to the attribution API. This approach is recommended when only one client instance is needed.

```TypeScript
import amazonAdsApi, { AttributionClient, AmazonAdsApiConfiguration, setConfiguration } from '@whitebox-co/amazon-ads-api';

// The optional configuration
const configuration: AmazonAdsApiConfiguration = {
    throttling: {
        reservoir: 100,
        reservoirRefreshAmount: 100,
        reservoirRefreshInterval: 60 * 1000,
        maxConcurrent: 5,
        minTime: 333,
    },
	retries: {
		count: 3,    // defaults to 3
        refreshTime: 5000, // in ms. defaults to 5000
        maxWaitTime: 5000, // in ms. defaults to 5000
		retryCallback: (jobId: string) => { console.log(`Retrying job ${jobId}`); }  // optional
	},
    jobOptions: {
        expiration: 3600 * 1000,
    },
	envoyProxyRateLimitUrl: 'http://localhost:8080' // optional (see https://github.com/envoyproxy/ratelimit)
};

// set the configuration options (totally optional, defaults are set above)
setConfiguration(configuration);

/**
 * Init the amazon ads, attribution client, with client credentials and get back a fully
 * configured instance of the client with token caching built-in.
 *
 * Any subsequent call using the same credentials but a different client
 * will use cached credentials until they expire.
 */
const attributionClient = await amazonAdsApi.getConfiguredApi(AttributionClient, {
    clientId,
    clientSecret,
    profileId,
    refreshToken
});

/**
 * Example of a GET call to the attribution API.
 */
const response = await attributionClient.getAdvertisersByProfile({
    amazonAdvertisingAPIClientId: '',
    amazonAdvertisingAPIScope: ''
});
```

--------------------------------

### Initializing Redoc and Dynamic Navigation (JavaScript)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/docs/redoc.html

This JavaScript code initializes the Redoc documentation viewer with the first API schema and dynamically builds a navigation menu. It iterates through a 'schemas' array, creating list items for each API, attaching a click event listener to load the corresponding API documentation using Redoc.init().

```JavaScript
// initially render first API Redoc.init(schemas[0].url); function onClick() { var url = this.getAttribute('data-link'); Redoc.init(url); } // dynamically building navigation items var $list = document.getElementById('links_container'); schemas.forEach(function (api) { var $listitem = document.createElement('li'); $listitem.setAttribute('data-link', api.url); $listitem.innerText = api.name; $listitem.addEventListener('click', onClick); $list.appendChild($listitem); });
```

--------------------------------

### Building and Viewing API Documentation (Shell)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This snippet provides shell commands to build and view different types of documentation for the Amazon Ads API client. It shows how to generate Redoc, SwaggerUI, and TypeDoc documentation using `npm run` scripts, leveraging `http-server` to serve the generated docs, typically on port 8080.

```Shell
npm run docs # or `npm run docs:typedoc`
npm run docs:redoc
npm run docs:swaggerui
```

--------------------------------

### Initializing Swagger UI with First API Schema (JavaScript)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/docs/swagger.html

This JavaScript snippet initializes the Swagger UI component upon page load, displaying the first API schema from the global `schemas` array. It configures the UI to render within the `#swagger-ui` DOM element, utilizing standard Swagger UI presets for API documentation and standalone functionality.

```JavaScript
SwaggerUIBundle({ url: schemas[0].url, dom_id: '#swagger-ui', presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset] });
```

--------------------------------

### Initializing Multiple Amazon Ads Clients with Class (TypeScript)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This snippet illustrates a class-based approach for managing multiple Amazon Ads clients, which is beneficial when handling various client instances. It shows how to initialize the `AmazonAds` class with credentials and optional configuration once, then retrieve specific configured API clients (like `AttributionClient`) from this central instance. This method streamlines credential management across multiple client types.

```TypeScript
import { AmazonAds, AttributionClient } from '@whitebox-co/amazon-ads-api';

// The optional configuration
const configuration: AmazonAdsApiConfiguration = {
    throttling: {
        reservoir: 100,
        reservoirRefreshAmount: 100,
        reservoirRefreshInterval: 60 * 1000,
        maxConcurrent: 5,
        minTime: 333,
    },
	retries: {
		count: 3,    // defaults to 3
        refreshTime: 5000, // in ms. defaults to 5000
        maxWaitTime: 5000, // in ms. defaults to 5000
		retryCallback: (jobId: string) => { console.log(`Retrying job ${jobId}`); }  // optional
	},
    jobOptions: {
        expiration: 3600 * 1000,
    },
	envoyProxyRateLimitUrl: 'localhost:8080' // optional (see https://github.com/envoyproxy/ratelimit)
};

// The user provided api credentials
const apiCredentials: AmazonAdvertisingAPICredentials = {
    clientId,
    clientSecret,
    profileId,
    refreshToken
}

/**
 * Init a new instance of the AmazonAds class.
 *
 * This has the advantage of only having to pass in credentials once.
 */
const amazonAdsApi = new AmazonAds(apiCredentials, configuration);

/**
 *  Retrieves a fully authorized instance of the attribution client.
 */
const attributionClient = await amazonAdsApi.getConfiguredApi(AttributionClient);

/**
 * Example of a GET call to the attribution API.
 */
const response = await attributionClient.getAdvertisersByProfile({
    amazonAdvertisingAPIClientId: '',
    amazonAdvertisingAPIScope: ''
});
```

--------------------------------

### Downloading Amazon Ads API Schemas (Shell)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This command initiates the download of all available Amazon Ads API OpenAPI 3.0 schemas. It overwrites existing schemas in the `./docs/schemas` directory if updates are found, ensuring the local schemas are current for API generation.

```Shell
npm run download-schemas
```

--------------------------------

### Common Development Commands (Shell)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This snippet lists essential shell commands for developing the Amazon Ads API client library. It includes commands for building the project, running a development server with live reloading, executing ESLint for code linting, and running tests with specific options for filtering.

```Shell
npm run build       # build the project (output to ./lib)
npm run dev         # run ts-node-dev to watch and rebuild project while in development.
npm run lint        # runs eslint linter
npm test -- -i/-u -t "<DESCRIBE_OR_IT_NAME>" # Example: npm test -- -i -t "Attribution"
```

--------------------------------

### Generating All Amazon Ads APIs (Shell)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This comprehensive command performs all API generation steps in a single execution. It downloads schemas, generates models, generates clients, and generates tests, outputting all artifacts to their respective folders. This process is also automated daily via GitHub Actions.

```Shell
npm run generate-apis
```

--------------------------------

### Generating API Clients (Shell)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This command generates API clients based on the previously generated models. The resulting client files are created and placed in the `src/apis/clients` directory, enabling programmatic interaction with the Amazon Ads API endpoints.

```Shell
npm run generate-clients
```

--------------------------------

### Styling Basic Page Layout and Navigation Elements (CSS)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/docs/redoc.html

This CSS snippet defines basic styling for the page body, a fixed navigation bar, and list items within the navigation container. It sets margins, padding, background color, display properties, and cursor styles for navigation links.

```CSS
body { margin: 0; padding-top: 40px; } nav { position: fixed; top: 0; width: 100%; z-index: 100; } #links_container { margin: 0; padding: 0; background-color: #002654; } #links_container li { display: inline-block; padding: 10px; color: white; cursor: pointer; }
```

--------------------------------

### Styling Amazon Advertising API UI Layout

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/docs/swagger.html

This CSS snippet defines the foundational styling for the web page, ensuring a full-height layout and styling for the header, navigation, and content areas. It uses flexbox for layout and sets basic visual properties like colors and padding for elements such as html, body, header, #content, nav, #links_container, li, and #swagger-ui.

```CSS
html, body { margin: 0; padding: 0; height: 100%; } header { top: 0; width: 100%; z-index: 100; display: flex; align-items: center; padding: 10px; font-size: 18px; font-weight: bold; color: white; background: #002654; } #content { width: 100%; height: 100%; display: flex; } #content nav { border-right: 1px solid #002654; padding: 10px; min-width: 200px; } #content #links_container { margin: 0; padding: 0; } #content #links_container li { padding: 10px; color: #002654; cursor: pointer; } #content #swagger-ui { width: 100%; height: 100%; flex-grow: 1; overflow-y: scroll; }
```

--------------------------------

### Dynamically Populating API Navigation Links (JavaScript)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/docs/swagger.html

This JavaScript snippet dynamically generates navigation list items based on an array of API schemas. For each schema, it creates a list item, sets its `data-link` attribute to the schema's URL, displays the schema's name, and attaches the `onClick` event listener, finally appending it to the `#links_container`.

```JavaScript
var $list = document.getElementById('links_container'); schemas.forEach(function (api) { var $listitem = document.createElement('li'); $listitem.setAttribute('data-link', api.url); $listitem.innerText = api.name; $listitem.addEventListener('click', onClick); $list.appendChild($listitem); });
```

--------------------------------

### Generating API Models from Schemas (Shell)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/README.md

This command processes the previously downloaded OpenAPI schemas to generate corresponding API models. The generated models are created and stored in the `src/apis/models` directory, providing structured data representations essential for API interactions.

```Shell
npm run generate-models
```

--------------------------------

### Defining Click Handler for Swagger UI Navigation (JavaScript)

Source: https://github.com/whitebox-co/amazon-ads-api/blob/main/docs/swagger.html

This JavaScript function, `onClick`, serves as an event handler for navigation links. When invoked, it retrieves the `data-link` attribute from the clicked element, which contains the URL of an API schema, and then re-initializes the Swagger UI to display the content from that new URL.

```JavaScript
function onClick() { var url = this.getAttribute('data-link'); SwaggerUIBundle({ url, dom_id: '#swagger-ui', presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset] }); }
```
Tokens:
Raw