@stackadapt/pa-typescript-sdk

StackAdapt's new Public API SDK allows you to use all of the functionality of the existing GQL Public API with built-in workflows, types and general endpoints that provide you similar flexibility. Additionally, all of StackAdapt's GQL types and Schema are also available to be exported in this SDK, giving you access to all the data you need to build powerful integrations.

Table of Contents

• Prerequisites
• Installation
• GQL API Documentation
• Example Usage
  • Initializing
  • General Endpoint
  • Create Creatives using URLs
  • Create Creatives using Local Files
  • Use The Latest Schema
  • Insights Reporting

Prerequisites

Ensure that you have the following versions installed.

• Node: v18.12.1 and above
• Npm: v8.19.2 and above
• Nvm: v0.38.0 and above

Installation

You can install @stackadapt/pa-typescript-sdk using npm.

npm install @stackadapt/pa-typescript-sdk

GQL API Documentation

This SDK is built on top of StackAdapt's GQL Public API. We are continuously working on adding more documentation for the SDK to provide users with a better understanding of its usage. In the meantime, for more information, please refer to the following GQL documentations:

• GQL API Docs
• GQL Reference
• GQL Public Schema

Example Usage

Initializing

// Importing library
import { initStackAdaptSDK } from "@stackadapt/pa-typescript-sdk";

// Can use 'SANDBOX' or 'PRODUCTION'
// You only need to initialize it once in your codebase
initStackAdaptSDK({
  token: MY_TOKEN,
  env: "SANDBOX",
});

General Endpoint

import {
  initStackAdaptSDK,
  generalEndpoint,
  UserError, // Part of StackAdapt's GQL types
} from "@stackadapt/pa-typescript-sdk";

initStackAdaptSDK({
  token: MY_TOKEN,
  env: "SANDBOX",
});

const getAdvertisers = async (first: number) => {
  type Result = { advertisers: { nodes: { id: number }[] } };
  const result = await generalEndpoint<Result>({
    query:
      "query Advertisers($firsts: Int!){ advertisers(first: $firsts) { nodes {id } } }",
    variables: { firsts: first },
  });
  return result;
};

const createAdvertiser = async (name: string) => {
  type Result = {
    createAdvertiser: {
      advertiser: { id: string; name: string };
      userErrors: UserError[];
    };
  };
  const results = await generalEndpoint<Result>({
    query:
      "mutation createNewAdvertiser($input: AdvertiserInput!){ createAdvertiser(input: $input){ advertiser { id name } userErrors { message path }  } }",
    variables: { input: { name: name } },
  });
  return results;
};

Create Creatives using URLs

import {
  initStackAdaptSDK,
  createCreativeByURL,
  ResourceType,
} from "@stackadapt/pa-typescript-sdk";

initStackAdaptSDK({
  token: MY_TOKEN,
  env: "SANDBOX",
});

const result = await createCreativeByURL({
  resourceType: ResourceType.Image,
  url: "https://dxt983tp420wz.cloudfront.net/images/other/careers_engineering_jack_yiu@2x-3e20599c3982ae946ba4037f72874416.jpg",
  fragment: "{ id ...on ImageCreative{ s3Url } }", // GQL fragment of UploadedCreative type, defaults to { id }. More information on what fields are available https://docs.stackadapt.com/graphql/reference#definition-UploadedCreative
});

Create Creatives using Local Files

The localPath parameter should support both absolute and relative paths, assuming the asset exists at the specified path.

import {
  initStackAdaptSDK,
  createCreativeByLocalFile,
  ResourceType,
} from "@stackadapt/pa-typescript-sdk";

initStackAdaptSDK({
  token: MY_TOKEN,
  env: "SANDBOX",
});

const result = await createCreativeByLocalFile({
  resourceType: ResourceType.Image,
  localPath: "./resources/assets/IMAGE_JPEG_300x300.jpeg",
  fragment: "{ id ...on ImageCreative{ s3Url } }", // GQL fragment of UploadedCreative type, defaults to { id }. More information on what fields are available https://docs.stackadapt.com/graphql/reference#definition-UploadedCreative
});

Use The Latest Schema

This SDK uses the latest StackAdapt Public API Schema which is updated weekly.

import {
  StackadaptSchema // Exports as GraphQLSchema type
} from "@stackadapt/pa-typescript-sdk";

Insights Reporting

import {
  initStackAdaptSDK,
  // Current Exposed Insights Reporting
  getDomainsReport,
  getGeographicReport,
  DateRangeInput,
  InsightReportingFilters,
  Pagination
} from "@stackadapt/pa-typescript-sdk";

initStackAdaptSDK({
  token: MY_TOKEN,
  env: "SANDBOX",
});

const filters: InsightReportingFilters = { advertiserIds: [1] };

const pagination: Pagination = {
  first: 1,
};

const date: DateRangeInput = {
  from: "2021-01-01",
  to: "2024-12-31",
};

// Domain Insight Reporting
const domainReportResult = await getDomainReport({
  filters: filters,
  pagination: pagination,
  date: date
});

// Geographical Insight Reporting
const geoReportResult = await getGeographicReport({
  filters: filters,
  pagination: pagination,
  date: date
});