SDK API Reference / P13nStudioSDK
Class: P13nStudioSDK
Constructors
Constructor
new P13nStudioSDK(
context):P13nStudioSDK
Parameters
context
Returns
P13nStudioSDK
Methods
createCreativeAsset()
createCreativeAsset(
input):Promise<P13nCreativeAsset>
Create a creative asset from HTML, and optionally CSS.
Service content rejections are mapped to actionable INVALID_ARGUMENT errors. Other HTTP errors bubble unchanged; a create has no ID to name.
Parameters
input
P13nCreativeAssetCreate
The content to store; htmlValue must be non-empty
Returns
Promise<P13nCreativeAsset>
The new asset as stored, after the service has sanitized it
Throws
INVALID_ARGUMENT when the HTML is empty or only whitespace
createPersonalization()
createPersonalization(
campaignId,input):Promise<P13nPersonalizationWriteResult>
Wire a creative asset to a campaign's audience and content spot.
Every reference in the wiring is validated by the service, which checks the campaign, that the audience is one of its members, that the content spot and creative asset belong to the account, and that the audience and spot are not already wired. So this makes no pre-flight requests: it checks only that the IDs are shaped like IDs, then sends the create and translates whatever comes back into the command that fixes it.
Creating a personalization changes what a launched campaign would render, so the service marks such a campaign stale and leaves every other state alone. The campaign is therefore read back rather than assumed, the same way listPersonalizations reads it: it carries the status the caller reports, and the audience names the personalizations endpoint cannot sideload. One read serves both.
That read is best-effort. It happens after the record is stored, so failing it cannot undo the create and must not fail the call — it returns a null campaign, and the personalization keeps a null audienceName.
The create itself is one request: the content spot and its page come back resolved as a sideload on the 201.
Parameters
campaignId
string
Campaign ID
input
P13nPersonalizationCreate
The wiring to store; a null audienceId asks for the default personalization
Returns
Promise<P13nPersonalizationWriteResult>
The stored personalization — its opaque ID, its content spot and page resolved, its audience named where the campaign knows it — and the campaign as it stands after the create, or null when re-reading it failed
Throws
INVALID_ARGUMENT when an ID is not a number; NOT_FOUND when no campaign has that ID; INVALID_REQUEST when the service rejects a reference; ALREADY_EXISTS when the audience and spot are already wired
deletePersonalization()
deletePersonalization(
campaignId,personalization):Promise<P13nPersonalizationWriteResult>
Remove a personalization from a campaign.
Takes the record rather than its ID, because a delete is only ever reached by way of one: an opaque token says nothing about what it points at, so nothing can confirm a delete without having read the record first — see getPersonalization. Asking for it keeps that read to one, and lets the result carry the wiring back out, which is what a caller needs to put it back. There is no update route for a personalization, so this and createPersonalization are the only way to change one.
Deleting a personalization changes what a launched campaign would render, so the service marks such a campaign stale and leaves every other state alone. The campaign is therefore read back after the delete rather than assumed, exactly as on create — a campaign read before it cannot answer this, since its status predates the write. That read is best-effort: it happens once the record is gone, so failing it cannot undo the delete and must not fail the call.
Parameters
campaignId
string
Campaign ID
personalization
P13nPersonalization
The record to remove, as read from the campaign
Returns
Promise<P13nPersonalizationWriteResult>
The personalization as it was, and the campaign as it stands after the delete, or null when re-reading it failed
Throws
INVALID_ARGUMENT when the campaign ID is malformed; NOT_FOUND when the service no longer has the record
getCampaign()
getCampaign(
campaignId):Promise<P13nCampaignDetail>
Get one campaign on its own.
The cheap counterpart to getCampaignDetail, which additionally walks the personalizations collection and resolves the parent segment's name. Callers that only need to confirm a campaign exists — or to read its name — should use this.
Parameters
campaignId
string
Campaign ID
Returns
Promise<P13nCampaignDetail>
The campaign, with its sideloaded audience references
Throws
NOT_FOUND when no campaign has that ID — the same error the name path raises, so both read alike to a caller
getCampaignDetail()
getCampaignDetail(
campaignId,options?):Promise<P13nCampaignDetailResult>
Get a campaign, its personalizations, and its parent segment's name.
Personalizations are always fetched because the API publishes no count — walking the collection is the only way to report one. Without includePersonalizations that walk is capped at COUNT_ONLY_PAGE_LIMIT pages, so a campaign larger than the cap reports a floor rather than an exact count.
Audience names come from the campaign's own sideloaded audiences, since the personalizations endpoint cannot sideload them.
Parameters
campaignId
string
Campaign ID
options?
Whether to enumerate personalizations in full
Returns
Promise<P13nCampaignDetailResult>
The campaign, its personalizations, the resolved parent name, and the bound that cut the walk short, if one did
getCreativeAsset()
getCreativeAsset(
creativeAssetId):Promise<P13nCreativeAsset>
Get one creative asset.
Parameters
creativeAssetId
string
Creative asset ID
Returns
Promise<P13nCreativeAsset>
The creative asset, with the content the server stored
Throws
NOT_FOUND when no creative asset has that ID
getLaunchSummary()
getLaunchSummary(
campaignId):Promise<P13nLaunchSummary>
Describe a campaign for launch confirmation. Does not validate: the service owns launchability, and its refusal is what the user should see.
Parameters
campaignId
string
Campaign ID
Returns
Promise<P13nLaunchSummary>
The campaign, its counts, and its resolved parent segment name
Throws
NOT_FOUND when no campaign has that ID
getPersonalization()
getPersonalization(
campaignId,personalizationId):Promise<P13nPersonalization>
Read one of a campaign's personalizations.
Served from the campaign's listing rather than from the service's single-record route, because the listing is where a personalization is already whole: listPersonalizations sideloads the content spot and its page, and names the audience from the campaign it reads alongside.
The ID is an opaque token, so a miss is reported against the listing that produced it rather than guessed at.
Parameters
campaignId
string
Campaign ID
personalizationId
string
The personalization's opaque ID
Returns
Promise<P13nPersonalization>
The personalization, with its audience, content spot and page resolved as far as the campaign and the sideload allow
Throws
INVALID_ARGUMENT when either ID is malformed; NOT_FOUND when no campaign has that ID, or no personalization matches. A miss from a truncated listing reports how many were searched because the record may still exist beyond the part that was read.
launchCampaign()
launchCampaign(
campaignId):Promise<P13nCampaignDetail>
Launch a Personalization Studio campaign.
Parameters
campaignId
string
Campaign ID
Returns
Promise<P13nCampaignDetail>
The campaign as it stands after the launch, with a bumped version
Throws
NOT_FOUND, or INVALID_REQUEST carrying the service's own account of the refusal, CDP validation errors included
listCampaigns()
listCampaigns(
parentSegmentId):Promise<P13nCollection<P13nCampaign>>
Parameters
parentSegmentId
number
Parent segment to list within
Returns
Promise<P13nCollection<P13nCampaign>>
Every campaign on it, and whether a bound cut the walk short
listPersonalizations()
listPersonalizations(
campaignId):Promise<P13nPersonalizationListResult>
List every personalization on a campaign, with audience names resolved.
Deliberately not routed through getCampaignDetail: that also resolves the parent segment name against CDP and caps the walk for a count, neither of which this needs. The campaign is fetched all the same — audience names are not sideloadable on the personalizations endpoint — and returned rather than discarded, since the caller heads its listing with it.
Parameters
campaignId
string
Campaign ID
Returns
Promise<P13nPersonalizationListResult>
The personalizations, their campaign, and whether a bound cut the walk short
Throws
NOT_FOUND when no campaign has that ID
parseCampaignId()
parseCampaignId(
value):string
Validate a --campaign-id value. See parseNumericId.
The help text offers the name instead, since every command taking this flag accepts a campaign name in the same position.
Parameters
value
string
Raw flag value, as typed by the user
Returns
string
The campaign ID, trimmed
Throws
When the value is not a positive integer
parseCreativeAssetId()
parseCreativeAssetId(
value):string
Validate a creative asset ID. See parseNumericId.
Named by what it is rather than by a flag, because it arrives as a positional on creative-asset show and update.
Parameters
value
string
Raw argument value, as typed by the user
Returns
string
The creative asset ID, trimmed
Throws
When the value is not a positive integer
parseParentSegmentId()
parseParentSegmentId(
value):number
Validate a --parent-segment-id value and return it as a number.
The one ID this SDK carries as a number rather than a string, because it reaches the API as a query parameter — see parseNumericId for why the shape is checked at all.
Parameters
value
string
Raw flag value, as typed by the user
Returns
number
The parent segment ID
Throws
When the value is not a positive integer
resolveAndGetCampaign()
resolveAndGetCampaign(
target,parentSegment?):Promise<P13nCampaignDetail>
Resolve a campaign argument — a name or an ID — and fetch the campaign.
The counterpart to resolveCampaign for callers that need to know the campaign exists rather than merely name it: resolveCampaign takes a numeric argument on trust, and this fetch is what turns that trust into a check. tdx use p13n_campaign pins the returned ID and echoes the name.
Parameters
target
string
Campaign name or ID, as printed by tdx ps p13n list
parentSegment?
number | (() => Promise<number | undefined>)
Parent segment to search a name within. A thunk is invoked only on the name path, so resolving an ID costs no lookup.
Returns
Promise<P13nCampaignDetail>
The campaign — id is canonical, whatever target was
Throws
When a name is given without a parent segment, or when no campaign matches
resolveCampaign()
resolveCampaign(
target,parentSegment?):Promise<string>
Resolve a campaign argument — a name or an ID — to a campaign ID.
Campaign IDs are numeric, so a numeric argument is taken as an ID and used as-is; anything else is a name. Names are unique only within a parent segment, so resolving one requires parentSegmentId — when it is missing the caller is told to pass an ID instead.
Parameters
target
string
Campaign name or ID, as printed by tdx ps p13n list
parentSegment?
number | (() => Promise<number | undefined>)
Parent segment to search a name within. A thunk is invoked only on the name path, so resolving an ID costs no lookup.
Returns
Promise<string>
The campaign ID
Throws
When a name is given without a parent segment, when no campaign matches, or when more than one does
resolveParentSegment()
resolveParentSegment(
explicitId?,name?):Promise<number|undefined>
Resolve the parent segment to operate on, from whichever of an ID or a name the caller has.
Order: an explicit ID (validated, no lookup) → a name → undefined. Both are optional because a command may have neither; deciding what to do about that is the caller's business, not this method's.
Parameters
explicitId?
string
Raw --parent-segment-id value, if the user gave one
name?
string
Parent segment name, from a positional argument, --parent-segment, or tdx use parent_segment
Returns
Promise<number | undefined>
The parent segment ID, or undefined when neither was supplied
Throws
When explicitId is present but not numeric, or when name matches no parent segment
unlaunchCampaign()
unlaunchCampaign(
campaignId):Promise<P13nCampaignDetail>
Unlaunch a Personalization Studio campaign, leaving it paused.
Parameters
campaignId
string
Campaign ID
Returns
Promise<P13nCampaignDetail>
The campaign as it stands after the unlaunch
Throws
NOT_FOUND, or INVALID_REQUEST carrying the refusal
updateCreativeAsset()
updateCreativeAsset(
creativeAssetId,input):Promise<P13nCreativeAsset>
Replace a creative asset's HTML and/or CSS.
Parameters
creativeAssetId
string
Creative asset ID
input
P13nCreativeAssetUpdate
The content to write; at least one field must be set
Returns
Promise<P13nCreativeAsset>
The asset as stored, after the service has sanitized it
Throws
INVALID_ARGUMENT when the input sets nothing, or when the service rejects the content; NOT_FOUND when no asset has that ID