@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
  • Create Simple Engagement Display Campaign

Prerequisites

Ensure that you have the following versions installed.

• Node: v18.12.1 and above
• Pnpm: v8.15.1 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/[e-mail]",
  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,
});

Create Simple Engagement Display Campaign

Getting Started

1. Advertiser

A new advertiser will be created if a name string is passed in. An existing advertiser will be used if an advertiser id is passed.

2. Campaign Group

A new campaign group will be created each time a new campaign is created. Both the campaign group and campaign will share the same flight data based on flightStartTime, flightEndTime, flightLifetimeBudget, bidAmount. The campaign group will be created based on campaignGroupName (optional) if passed in, else it will have a default name.

3. Campaign Ads

Follow Create Creatives using URLs, Create Creatives using Local Files to upload the creative and obtain if using Display Image Ads instead of JS Tags. This is optional depending on if the creative is already uploaded.

4. Campaign Geo

This is an optional input, see more details in the StackAdapt Campaign Geo Targeting guide. The geo targeting must be of the custom type SdkCampaignGeo.

5. Defaults Values

• Bid Type = CPM
• Pace evenly = true
• campaign goal type = Engagement
• campaign group budget type = cost
• campaign group revenue type = CPM

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

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

// optional depending if creative ID already exist or if using JS tag creatives
const creative = await createCreativeByURL({
  resourceType: ResourceType.Image,
  url: IMAGE_PNG_300x600_URL,
});

const geo = {
  type: "location", // available types: geoRadius, politicalDistricts, location, zipTargeting, zipTargetingAndLocation
  payload: { locationIds: ["1242619", "1242881"] }, // this will change based on type
};

try {
  /* returns a campaign GQL fragment containing trivial campaign data: 
      campaign {
        id
        name
        ads {
          ...
        }
        advertiser {
          id
          name
        }
        campaignGroup {
          id
          name
        }
        campaignStatus {
          state
          status
        }
        createdAt
        updatedAt
        flights {
          ...
        }
        geo {
          ...
        }
        isArchived
        isDraft
      }
  */
  const campaignResult = await createSimpleEngagementDisplayCampaign({
    ads: [
      {
        name: "SDK Test Ad",
        brandname: "SDK Test",
        clickUrl: "https://www.stackadapt.com",
        creative: { creativeId: creative.id },
      },
    ],
    advertiser: { name: "Test Advertiser" },
    flightStartTime: "2025-01-02T05:00:00",
    flightEndTime: "2026-01-02T05:00:00",
    flightLifetimeBudget: 50000.5,
    bidAmount: 3,
    name: "Test Simple Engagement Display Campaign",
    isDraft: true,
    geo,
  });
} catch (e) {
  throw new Error(`Error creating campaign: ${e}`);
}