API Reference
Complete reference for all @upspawn/ads exports — campaign builders, helpers, and types.
All public exports are available from @upspawn/ads. This page covers every exported function. For deeper coverage of specific areas, see:
Table of Contents
- Google Campaign Builders
- Meta Campaign Builders
- Ad Helpers
- Keyword Helpers
- Budget Helpers
- Targeting Helpers
- Extension Helpers
- Image Asset Helpers
- URL and Negatives
- Meta Helpers
- Account-Level Resources
- AI Module
- Assets
- Config
Google Campaign Builders
Import: import { google } from '@upspawn/ads'
google.search(name, config)
Creates a Google Search campaign with a chainable builder.
google.search(name: string, input: SearchCampaignInput): CampaignBuilder| Field | Type | Default |
|---|---|---|
budget | Budget | required |
bidding | BiddingInput | required |
targeting | Targeting | { rules: [] } |
negatives | Keyword[] | [] |
status | 'enabled' | 'paused' | 'enabled' |
startDate | string | — |
endDate | string | — |
trackingTemplate | string | — |
finalUrlSuffix | string | — |
customParameters | Record<string, string> | — |
networkSettings | NetworkSettings | — |
Returns a CampaignBuilder with methods: .group(), .locale(), .sitelinks(), .callouts(), .snippets(), .calls(), .prices(), .promotions(), .images().
import { google, daily, targeting, geo, languages, negatives } from '@upspawn/ads'
export default google.search('Search - Exact Match', {
budget: daily(20),
bidding: 'maximize-conversions',
targeting: targeting(geo('US', 'DE'), languages('en', 'de')),
negatives: negatives('free', 'open source'),
})google.display(name, config)
Creates a Google Display campaign.
google.display(name: string, input: DisplayCampaignInput): DisplayCampaignBuilderSame config fields as google.search() (minus customParameters). Returns a DisplayCampaignBuilder with .group().
import { google, daily, targeting, geo, languages } from '@upspawn/ads'
export default google.display('Display - Remarketing', {
budget: daily(5),
bidding: 'maximize-conversions',
targeting: targeting(geo('US'), languages('en')),
})
.group('remarketing', { ad: responsiveDisplay({ /* ... */ }) })google.performanceMax(name, config)
Creates a Google Performance Max campaign. PMax runs across all Google surfaces (Search, Display, YouTube, Gmail, Discover, Maps) using asset groups.
google.performanceMax(name: string, input: PMaxCampaignInput): PMaxCampaignBuilder| Field | Type | Default |
|---|---|---|
budget | Budget | required |
bidding | BiddingInput | required — only maximize-conversions or maximize-conversion-value |
targeting | Targeting | geo + language only |
urlExpansion | boolean | true |
status | 'enabled' | 'paused' | 'enabled' |
Returns a PMaxCampaignBuilder with .assetGroup().
import { google, daily, targeting, geo, languages } from '@upspawn/ads'
export default google.performanceMax('PMax - Core', {
budget: daily(15),
bidding: 'maximize-conversions',
targeting: targeting(geo('US', 'DE'), languages('en', 'de')),
})
.assetGroup('main', {
finalUrls: ['https://example.com'],
headlines: ['Rename Files Fast', 'AI File Renaming', 'Batch Rename Tool'],
longHeadlines: ['Rename All Your Files in Seconds with AI'],
descriptions: ['Try it free today.', 'No credit card required.'],
businessName: 'example.com',
})google.shopping(name, config)
Creates a Google Shopping campaign driven by a Merchant Center product feed.
google.shopping(name: string, input: ShoppingCampaignInput): ShoppingCampaignBuilder| Field | Type | Description |
|---|---|---|
budget | Budget | required |
bidding | BiddingInput | required |
merchantId | number | Merchant Center ID |
campaignPriority | 0 | 1 | 2 | 0 = low, 2 = high |
enableLocal | boolean | Enable local inventory ads |
feedLabel | string | Target a specific feed |
Returns a ShoppingCampaignBuilder with .group(). Shopping ad groups have no keywords or ads — only optional bids.
export default google.shopping('Shopping - All Products', {
budget: daily(10),
bidding: 'maximize-clicks',
targeting: targeting(geo('US')),
merchantId: 123456789,
})
.group('all-products', {})
.group('electronics', { bid: 0.75 })google.demandGen(name, config)
Creates a Demand Gen campaign serving across YouTube, Discover, Gmail, and Display with multi-asset and carousel ads.
google.demandGen(name: string, input: DemandGenCampaignInput): DemandGenCampaignBuilderReturns a DemandGenCampaignBuilder with .group(). Ad groups can contain DemandGenMultiAssetAd or DemandGenCarouselAd, plus optional channels controls.
google.smart(name, config)
Creates a Smart Campaign. Smart campaigns use keyword themes instead of keywords and run across Search, Display, and Maps. Returns a flat GoogleSmartCampaign (no .group() chaining).
google.smart(name: string, input: SmartCampaignInput): GoogleSmartCampaign| Field | Type | Description |
|---|---|---|
budget | Budget | required |
businessName | string | required |
finalUrl | string | required |
keywordThemes | string[] | required — theme strings |
ad | SmartCampaignAd | required — use smartAd() |
language | string | default 'en' |
google.app(name, config)
Creates an App Campaign for driving installs or in-app actions across Search, Display, YouTube, and Play Store.
google.app(name: string, input: AppCampaignInput): GoogleAppCampaign| Field | Type | Description |
|---|---|---|
budget | Budget | required |
bidding | BiddingInput | required |
appId | string | required |
appStore | 'google' | 'apple' | required |
ad | AppAdInfo | required — use appAd() |
goal | 'installs' | 'in-app-actions' | 'pre-registration' | default 'installs' |
Returns a flat GoogleAppCampaign (no chaining).
Builder Methods
These methods are available on the builders returned by google.search(), google.display(), etc.
.group(key, config) — Search, Display, Shopping, Demand Gen
Add an ad group. key is the stable identifier used for the resource path.
campaign.group('pdf-renaming', {
keywords: exact('rename pdf', 'pdf renamer'),
ad: rsa(headlines('...'), descriptions('...'), url('https://example.com')),
})For Display: ad accepts ResponsiveDisplayAd. For Shopping: accepts { bid?: number; status?: string }.
.locale(key, targeting, config) — Search only
Add an ad group with a targeting override (for multi-language or multi-region campaigns).
campaign.locale('en-us', targeting(geo('US'), languages('en')), {
keywords: exact('rename files'),
ad: rsa(/* ... */),
}).assetGroup(key, config) — Performance Max only
Add an asset group.
builder.assetGroup('main', {
finalUrls: ['https://example.com'],
headlines: ['Headline 1', 'Headline 2', 'Headline 3'],
longHeadlines: ['Long headline text'],
descriptions: ['Description 1', 'Description 2'],
businessName: 'My Business',
images: {
landscape: [landscape('./hero.png')],
square: [square('./hero-sq.png')],
},
audienceSignal: targeting(remarketing('123')),
}).sitelinks(), .callouts(), .snippets(), .calls(), .prices(), .promotions(), .images() — Search only
Attach extensions. See Extensions for full details.
Meta Campaign Builders
Import: import { meta } from '@upspawn/ads'
All Meta builders return a MetaCampaignBuilder<T> with a .adSet() method.
meta.traffic(name, config?)
meta.awareness(name, config?)
meta.engagement(name, config?)
meta.leads(name, config?)
meta.sales(name, config?)
meta.conversions(name, config?) — alias for meta.sales()
meta.appPromotion(name, config?)
meta.traffic(name: string, config?: MetaCampaignConfig): MetaCampaignBuilder<'traffic'>MetaCampaignConfig fields:
| Field | Type | Description |
|---|---|---|
budget | Budget | Campaign-level budget |
bidding | BidStrategy | Bidding strategy from lowestCost(), costCap(), etc. |
status | 'ACTIVE' | 'PAUSED' | Campaign status |
startTime | string | ISO 8601 start date |
endTime | string | ISO 8601 end date |
import { meta, daily, lowestCost } from '@upspawn/ads'
const campaign = meta.traffic('Traffic - US', {
budget: daily(15),
bidding: lowestCost(),
}).adSet(name, config, content)
Add an ad set. The optimization field is constrained by campaign objective type.
builder.adSet(
name: string,
config: AdSetConfig<T>,
content: AdSetContent,
): MetaCampaignBuilder<T>AdSetConfig fields:
| Field | Type | Description |
|---|---|---|
targeting | MetaTargeting | Required — from metaTargeting() |
optimization | objective-specific union | Type-safe optimization goal |
bidding | BidStrategy | Override campaign-level bidding |
budget | Budget | Override campaign-level budget |
placements | MetaPlacements | automatic() or manual() |
startTime | string | ISO 8601 |
endTime | string | ISO 8601 |
AdSetContent fields:
| Field | Type | Description |
|---|---|---|
ads | MetaCreative[] | Array of metaImage(), metaVideo(), carousel(), etc. |
url | string | Default destination URL |
cta | MetaCTA | Default call-to-action |
campaign.adSet(
'Website Visitors',
{
targeting: metaTargeting(geo('US'), age(25, 55)),
optimization: 'LINK_CLICKS',
},
{
url: 'https://example.com',
cta: 'SIGN_UP',
ads: [
metaImage('./assets/hero.png', {
headline: 'Try It Free',
primaryText: 'The fastest way to rename your files.',
}),
],
},
)Ad Helpers
headlines(...texts)
Create validated RSA headlines. Each must be 30 characters or fewer.
function headlines(...texts: string[]): Headline[]import { headlines } from '@upspawn/ads'
headlines('Rename Files Fast', 'AI File Renamer', 'Batch Rename Tool')descriptions(...texts)
Create validated RSA descriptions. Each must be 90 characters or fewer.
function descriptions(...texts: string[]): Description[]import { descriptions } from '@upspawn/ads'
descriptions(
'Rename thousands of files in seconds with AI-powered rules.',
'Try free. No credit card required.',
)rsa(headlines, descriptions, url, options?)
Build a Responsive Search Ad. Requires 3–15 headlines and 2–4 descriptions.
function rsa(
headlineList: Headline[],
descriptionList: Description[],
urlResult: { finalUrl: string; utm?: UTMParams },
options?: {
pinnedHeadlines?: PinnedHeadline[]
pinnedDescriptions?: PinnedDescription[]
path1?: string // max 15 chars
path2?: string // max 15 chars
mobileUrl?: string
trackingTemplate?: string
},
): RSAdimport { headlines, descriptions, rsa, url } from '@upspawn/ads'
rsa(
headlines('Rename Files Fast', 'AI File Renamer', 'Batch Rename Tool'),
descriptions('Rename thousands of files in seconds.', 'Try free today.'),
url('https://example.com'),
{
pinnedHeadlines: [{ text: 'Rename Files Fast', position: 1 }],
path1: 'rename',
path2: 'files',
},
)responsiveDisplay(config)
Build a Responsive Display Ad for Display campaigns.
function responsiveDisplay(config: {
headlines: string[] // 1–5 headlines, each max 30 chars
longHeadline: string // max 90 chars
descriptions: string[] // 1–5 descriptions
businessName: string
finalUrl: string
marketingImages: ImageRef[] // landscape 1.91:1 images
squareMarketingImages: ImageRef[]
logoImages?: ImageRef[]
squareLogoImages?: ImageRef[]
callToAction?: string
mainColor?: string
accentColor?: string
}): ResponsiveDisplayAdimport { responsiveDisplay, landscape, square } from '@upspawn/ads'
responsiveDisplay({
headlines: ['Rename Files Fast', 'AI Powered'],
longHeadline: 'Rename All Your Files in Seconds with AI',
descriptions: ['Try renamed.to free'],
businessName: 'example.com',
finalUrl: 'https://example.com',
marketingImages: [landscape('./hero.png')],
squareMarketingImages: [square('./hero-square.png')],
})demandGenMultiAsset(config)
Build a Demand Gen multi-asset ad. Google assembles headlines, descriptions, and images into the best combinations.
function demandGenMultiAsset(config: {
headlines: string[] // max 5, each max 40 chars
descriptions: string[] // max 5, each max 90 chars
businessName: string
finalUrl: string
marketingImages?: ImageRef[] // landscape 1.91:1
squareMarketingImages?: ImageRef[]
portraitMarketingImages?: ImageRef[]
logoImages?: ImageRef[]
callToAction?: string
}): DemandGenMultiAssetAddemandGenCarousel(config)
Build a Demand Gen carousel ad. Minimum 2, maximum 10 cards.
function demandGenCarousel(config: Omit<DemandGenCarouselAd, 'type'>): DemandGenCarouselAdcarouselCard(config)
Build a single card for a Demand Gen carousel.
function carouselCard(config: {
headline: string
finalUrl: string
marketingImage?: ImageRef
squareMarketingImage?: ImageRef
callToAction?: string
}): DemandGenCarouselCardsmartAd(config)
Build a Smart Campaign ad. Requires exactly 3 headlines and 2 descriptions.
function smartAd(config: {
headlines: [string, string, string] // exactly 3, max 30 chars each
descriptions: [string, string] // exactly 2, max 90 chars each
}): SmartCampaignAdappAd(config)
Build an App Campaign ad asset set.
function appAd(config: {
headlines: string[] // max 5, each max 30 chars
descriptions: string[] // max 5, each max 90 chars
images?: ImageRef[]
videos?: string[] // YouTube URLs
}): AppAdInfoKeyword Helpers
exact(...args), phrase(...args), broad(...args)
Create typed keywords with a specific match type.
function exact(...args: KeywordInput[]): ExactKeyword[]
function phrase(...args: KeywordInput[]): PhraseKeyword[]
function broad(...args: KeywordInput[]): BroadKeyword[]KeywordInput is string or { text: string; bid?: number; finalUrl?: string; status?: string }.
import { exact, phrase, broad } from '@upspawn/ads'
exact('rename files', 'batch rename')
phrase('file renaming tool', 'rename pdf')
broad('file organization', 'document management')
// With per-keyword bid:
exact({ text: 'rename files', bid: 1.50 })keywords(...texts)
Parse keywords from bracket notation. [text] = exact, "text" = phrase, bare text = broad.
function keywords(...texts: string[]): Keyword[]import { keywords } from '@upspawn/ads'
keywords('[rename files]', '"file renaming tool"', 'document management')
// Or as a template literal:
keywords(`
[rename files]
[batch rename]
"file renaming tool"
document management
`)Budget Helpers
daily(amount, currency?)
Daily budget. Default currency: 'EUR'.
function daily(amount: number, currency?: 'EUR' | 'USD'): DailyBudgetimport { daily } from '@upspawn/ads'
daily(20) // €20/day
daily(15, 'USD') // $15/daymonthly(amount, currency?)
Monthly budget. The engine converts to a daily amount.
function monthly(amount: number, currency?: 'EUR' | 'USD'): MonthlyBudgetlifetime(amount, endTime, currency?)
Lifetime budget with a fixed end date. Used for Meta campaigns with a defined flight.
function lifetime(amount: number, endTime: string, currency?: 'EUR' | 'USD'): LifetimeBudgetimport { lifetime } from '@upspawn/ads'
lifetime(500, '2026-04-01')
lifetime(1000, '2026-06-30T23:59:59Z', 'USD')eur(amount), usd(amount)
Branded currency shorthands for compile-time type checking.
function eur(amount: number): number & { __currency: 'EUR' }
function usd(amount: number): number & { __currency: 'USD' }Targeting Helpers
These are covered in detail at Targeting Helpers. Quick reference:
| Helper | Description |
|---|---|
targeting(...rules) | Compose rules into a Targeting object |
geo(...countries) | Country targeting |
regions(...names) | Region/state targeting |
cities(...names) | City targeting |
radius(lat, lng, km) | Radius targeting |
presence(mode) | Location presence mode |
languages(...langs) | Language targeting |
weekdays() | Mon–Fri schedule |
hours(start, end) | Hour range |
scheduleBid(day, start, end, adj) | Day/hour bid adjustment |
device(type, adj) | Device bid adjustment |
demographics(opts) | Age, gender, income, parental status |
audiences(...refs) | Audience observation mode |
audienceTargeting(...refs) | Audience targeting mode |
remarketing(id, opts?) | Remarketing list ref |
customAudience(id, opts?) | Custom audience ref |
inMarket(id, opts?) | In-market segment ref |
affinity(id, opts?) | Affinity segment ref |
customerMatch(id, opts?) | Customer match list ref |
placements(...urls) | Display placement targeting |
topics(...names) | Display topic targeting |
contentKeywords(...kws) | Display contextual targeting |
Extension Helpers
Covered in detail at Extensions. Quick reference:
| Helper | Description |
|---|---|
link(text, url, opts?) | Single sitelink — text ≤25, desc ≤35 chars |
sitelinks(...links) | Bundle multiple sitelinks |
callouts(...texts) | Callout strings — each ≤25 chars |
snippet(header, ...values) | Structured snippet — 3–10 values |
call(phone, country, callOnly?) | Call extension |
price(items, qualifier?) | Price extension — 3–8 items |
promotion(config) | Promotion extension |
image(url, altText?) | Image extension |
Image Asset Helpers
Used for Google Display, Performance Max, and Demand Gen campaigns.
landscape(path) — 1.91:1 aspect ratio
square(path) — 1:1 aspect ratio
portrait(path) — 4:5 aspect ratio
logo(path) — square logo, 1:1
logoLandscape(path) — landscape logo, 4:1
function landscape(path: string): ImageRef
function square(path: string): ImageRef
function portrait(path: string): ImageRef
function logo(path: string): ImageRef
function logoLandscape(path: string): ImageRefimport { landscape, square, portrait, logo, logoLandscape } from '@upspawn/ads'
landscape('./images/hero-landscape.png')
square('./images/hero-square.png')
portrait('./images/hero-portrait.png')
logo('./images/logo.png')
logoLandscape('./images/logo-wide.png')All return an ImageRef object: { type: 'image-ref', path, aspectRatio }.
URL and Negatives
url(finalUrl, utm?)
Create a URL with optional UTM tracking parameters. URL must start with http:// or https://.
function url(finalUrl: string, utm?: UTMParams): UrlResultimport { url } from '@upspawn/ads'
url('https://example.com')
url('https://example.com', {
source: 'google',
medium: 'cpc',
campaign: 'brand-search',
content: 'headline-a',
term: '{keyword}',
})negatives(...texts)
Create negative keywords (broad match). Deduplicates by lowercased text.
function negatives(...texts: string[]): Keyword[]import { negatives } from '@upspawn/ads'
negatives('free', 'open source', 'crack', 'download')
// [{ text: 'free', matchType: 'BROAD' }, ...]Meta Helpers
Creative helpers
| Export | Description |
|---|---|
metaImage(filePath, config?) | Image ad creative |
metaVideo(filePath, config?) | Video ad creative |
carousel(cards, config) | Carousel ad — 2–10 cards |
boostedPost(name?) | Boosted page post |
See the source in src/helpers/meta-creative.ts.
import { metaImage, metaVideo, carousel } from '@upspawn/ads'
metaImage('./hero.png', {
headline: 'Rename Files Instantly',
primaryText: 'Stop wasting hours organizing files manually.',
cta: 'SIGN_UP',
})
carousel(
[
{ image: './a.png', headline: 'Step 1', url: 'https://example.com/step-1' },
{ image: './b.png', headline: 'Step 2', url: 'https://example.com/step-2' },
],
{ primaryText: 'See how it works in 3 simple steps' },
)Targeting helpers
| Export | Description |
|---|---|
metaTargeting(...rules) | Compose Meta targeting |
age(min, max) | Age range 13–65 |
audience(nameOrId) | Custom audience by name or ID |
excludeAudience(nameOrId) | Exclude audience |
interests(...args) | Interest targeting |
lookalike(source, config) | Lookalike audience |
See Targeting Helpers — Meta Targeting for full details.
Bidding helpers
| Export | Description |
|---|---|
lowestCost() | No cap (default) |
costCap(amount) | Average cost per result cap |
bidCap(amount) | Max bid per auction |
minRoas(floor) | Minimum ROAS multiplier |
See Bidding Strategies — Meta for full details.
Placement helpers
| Export | Description |
|---|---|
automatic() | Advantage+ automatic placements (recommended) |
manual(platforms, positions?) | Manual platform/position selection |
import { automatic, manual } from '@upspawn/ads'
automatic()
manual(['facebook', 'instagram'], ['feed', 'story'])
manual(['facebook', 'instagram'], {
facebookPositions: ['feed', 'story'],
instagramPositions: ['stream', 'story', 'reels'],
})Account-Level Resources
These are exported as top-level campaign files (not inside campaigns/).
sharedNegatives(name, keywords)
Create a shared negative keyword list that can be linked to multiple campaigns. Google limits accounts to 20 shared lists, each with up to 5,000 keywords.
function sharedNegatives(name: string, keywords: Keyword[]): SharedNegativeListimport { sharedNegatives, negatives, exact } from '@upspawn/ads'
export default sharedNegatives('Brand Exclusions', [
...negatives('free', 'cheap', 'open source', 'crack'),
...exact('competitor brand'),
])conversionAction(name, config)
Define a conversion action for Google Ads.
function conversionAction(
name: string,
config: {
type: 'webpage' | 'ad-call' | 'click-to-call' | 'import'
category: 'purchase' | 'signup' | 'lead' | 'page-view' | 'download' | 'add-to-cart' | 'begin-checkout' | 'subscribe' | 'contact' | 'other'
counting: 'one-per-click' | 'many-per-click'
value?: { default?: number; currency?: string; useDynamic?: boolean }
attribution?: 'last-click' | 'data-driven'
lookbackDays?: number
primary?: boolean
},
): ConversionActionConfigimport { conversionAction } from '@upspawn/ads'
export default conversionAction('Website Signup', {
type: 'webpage',
category: 'signup',
counting: 'one-per-click',
value: { default: 10, currency: 'EUR' },
attribution: 'data-driven',
})sharedBudget(name, budget)
Create a shared budget that multiple campaigns can reference. Google distributes spend dynamically to higher-performing campaigns.
function sharedBudget(
name: string,
budget: { amount: number; currency: string; period: 'daily' },
): SharedBudgetConfigimport { sharedBudget, daily } from '@upspawn/ads'
export default sharedBudget('Search Campaigns Budget', daily(50))AI Module
The ai namespace provides markers for AI-generated content. Markers are inert tags — the actual LLM call happens during ads generate.
import { ai } from '@upspawn/ads'ai.rsa(prompt)
Replace an RSA with AI-generated headlines and descriptions.
ai.rsa('Write copy for a file renaming tool targeting freelance designers')
ai.rsa({ prompt: 'Write headlines', url: 'https://example.com', context: 'B2B SaaS' })ai.keywords(prompt)
Replace a keywords array with AI-generated keywords.
ai.keywords('Suggest keywords for PDF automation tools')ai.metaCopy(prompt)
Replace Meta ad copy fields with AI-generated content.
ai.metaCopy('Write a Meta ad for cloud storage targeting small business owners')
ai.metaCopy({ prompt: '...', objective: 'traffic', cta: 'SIGN_UP' })ai.interests(prompt)
Replace a Meta interests array with AI-suggested interests.
ai.interests('Suggest Meta interests for B2B SaaS productivity tool')See AI Generation for the full workflow.
Assets
asset(filePath, options?)
Create an asset marker for deferred resolution. Used when the same asset file needs to be shared across ad sets without re-uploading.
function asset(filePath: string, options?: AssetOptions): AssetMarkerConfig
defineConfig(config)
Identity function for ads.config.ts files. Provides type-checking and autocompletion.
function defineConfig(config: AdsConfig): AdsConfigimport { defineConfig } from '@upspawn/ads'
export default defineConfig({
google: {
customerId: 'YOUR_CUSTOMER_ID',
managerId: 'YOUR_MANAGER_ID',
},
meta: {
accountId: 'YOUR_ACCOUNT_ID',
pageId: 'YOUR_PAGE_ID',
},
})See Configuration Reference for all options.