soundlink 2.3.0 → 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/README.md +22 -1
- package/dist/cjs/index.cjs +95 -0
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +226 -10
- package/dist/esm/index.js +95 -0
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +2045 -449
- package/package.json +1 -1
package/dist/esm/index.d.ts
CHANGED
|
@@ -1,12 +1,7 @@
|
|
|
1
1
|
/** Stable snake_case error codes returned by the Soundlink Public API. */
|
|
2
|
-
type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | '
|
|
3
|
-
/**
|
|
4
|
-
|
|
5
|
-
*
|
|
6
|
-
* Includes OpenAPI values plus `inactive` (observed on wallet campaigns in
|
|
7
|
-
* production; may be aligned in a later OpenAPI revision).
|
|
8
|
-
*/
|
|
9
|
-
type CampaignStatus = 'creating' | 'active' | 'paused' | 'stopped' | 'completed' | 'failed' | 'ended' | 'inactive';
|
|
2
|
+
type PublicApiErrorCode = 'invalid_api_key' | 'invalid_token' | 'api_key_revoked' | 'api_key_expired' | 'access_denied' | 'insufficient_scope' | 'not_found' | 'not_in_listening_graph' | 'campaign_not_found' | 'invalid_query_parameter' | 'invalid_date_range' | 'page_size_exceeded' | 'invalid_request' | 'invalid_genre' | 'invalid_duration_or_budget' | 'invalid_daily_budget' | 'invalid_duration_days' | 'invalid_spotify_url' | 'invalid_tier_budget_allocation' | 'invalid_tier_status' | 'learning_edit_ack_required' | 'wallet_not_enabled' | 'premium_plan_required' | 'youtube_music_not_enabled' | 'attribution_not_enabled' | 'soundlink_plan_required' | 'custom_pixel_not_enabled' | 'meta_pixel_conflict' | 'insufficient_credit' | 'idempotency_key_conflict' | 'rate_limit_exceeded' | 'invalid_video_url' | 'video_import_limit_exceeded' | 'video_import_session_not_found' | 'internal_error';
|
|
3
|
+
/** Campaign lifecycle status returned by the Public API. */
|
|
4
|
+
type CampaignStatus = 'creating' | 'active' | 'inactive' | 'ended' | 'renewing' | 'restarting' | 'restart_failed' | 'renew_awaiting_charge' | 'renew_failed' | 'stopped';
|
|
10
5
|
/** Ad platform used by the campaign. */
|
|
11
6
|
type SocialPlatform = 'meta';
|
|
12
7
|
/**
|
|
@@ -116,15 +111,40 @@ interface CampaignSummary {
|
|
|
116
111
|
campaignDuration: number;
|
|
117
112
|
/** Resource generation — writable Public API methods require `3`. */
|
|
118
113
|
generation: CampaignGeneration;
|
|
114
|
+
/** Follow-attribution Spotify artist ID. `null` when unset. */
|
|
115
|
+
artistId: string | null;
|
|
116
|
+
/** Display name for `artistId`. `null` when unknown or unset. */
|
|
117
|
+
artistName: string | null;
|
|
118
|
+
/** Promoted Spotify track ID. `null` for playlist campaigns. */
|
|
119
|
+
trackId: string | null;
|
|
120
|
+
/** Promoted Spotify playlist ID. `null` for track campaigns. */
|
|
121
|
+
playlistId: string | null;
|
|
122
|
+
/** Promoted track title. `null` for playlist campaigns or when unknown. */
|
|
123
|
+
trackName: string | null;
|
|
124
|
+
/** Logged-in campaign insights URL. Not a public share link. */
|
|
125
|
+
campaignUrl: string;
|
|
119
126
|
/** ISO 8601 creation timestamp. */
|
|
120
127
|
createdAt: string;
|
|
121
128
|
/** ISO 8601 last update timestamp. */
|
|
122
129
|
updatedAt: string;
|
|
123
130
|
}
|
|
131
|
+
/** Meta ad set learning status on a campaign tier. */
|
|
132
|
+
type TierLearningStatus = 'LEARNING' | 'FAIL' | 'SUCCESS';
|
|
124
133
|
/** Full campaign detail from {@link CampaignsResource.get}. */
|
|
125
134
|
interface CampaignDetail extends CampaignSummary {
|
|
126
135
|
/** Growth strategy set at creation (e.g. `custom`, `maximum_growth`). */
|
|
127
136
|
strategyType?: StrategyType;
|
|
137
|
+
/**
|
|
138
|
+
* Whether this wallet campaign renews at the end of each cycle.
|
|
139
|
+
* `false` when auto-renew is off or the campaign has no stored value.
|
|
140
|
+
*/
|
|
141
|
+
autoRenew: boolean;
|
|
142
|
+
/**
|
|
143
|
+
* When the current wallet cycle ends and the campaign renews.
|
|
144
|
+
* `null` unless the campaign is wallet-funded, auto-renew is on,
|
|
145
|
+
* and a cycle end is stored.
|
|
146
|
+
*/
|
|
147
|
+
nextRenewalAt: string | null;
|
|
128
148
|
}
|
|
129
149
|
/** Paginated campaign list payload. */
|
|
130
150
|
interface CampaignListData {
|
|
@@ -162,6 +182,11 @@ interface CreateCampaignRequestBase {
|
|
|
162
182
|
};
|
|
163
183
|
/** Lineage only — does not copy settings from the source campaign. */
|
|
164
184
|
clonedFromCampaignId?: string;
|
|
185
|
+
/**
|
|
186
|
+
* When true, the wallet campaign renews at the end of each cycle if credit
|
|
187
|
+
* remains. When false or omitted, auto-renew stays off.
|
|
188
|
+
*/
|
|
189
|
+
autoRenew?: boolean;
|
|
165
190
|
}
|
|
166
191
|
interface DoItForMeCreativeDirection {
|
|
167
192
|
type: 'do_it_for_me';
|
|
@@ -199,6 +224,105 @@ type CreateCampaignRequest = CreateCampaignRequestBuiltIn | CreateCampaignReques
|
|
|
199
224
|
interface CampaignCreateData {
|
|
200
225
|
campaignId: string;
|
|
201
226
|
status: CampaignStatus;
|
|
227
|
+
/** Stored auto-renew flag for this wallet campaign. */
|
|
228
|
+
autoRenew: boolean;
|
|
229
|
+
}
|
|
230
|
+
interface UpdateCampaignAutoRenewRequest {
|
|
231
|
+
autoRenew: boolean;
|
|
232
|
+
}
|
|
233
|
+
interface CampaignAutoRenewData {
|
|
234
|
+
campaignId: string;
|
|
235
|
+
autoRenew: boolean;
|
|
236
|
+
}
|
|
237
|
+
/** Payload from `GET /v1/wallet`. */
|
|
238
|
+
interface WalletData {
|
|
239
|
+
balance: number;
|
|
240
|
+
available: number;
|
|
241
|
+
reserved: number;
|
|
242
|
+
currency: 'USD';
|
|
243
|
+
/** ISO 8601. `null` when the organization has no credits row. */
|
|
244
|
+
updatedAt: string | null;
|
|
245
|
+
}
|
|
246
|
+
/** One variant under a creative group (`GET .../metrics/creatives`). */
|
|
247
|
+
interface CreativeMetricsChild {
|
|
248
|
+
caption: string | null;
|
|
249
|
+
language: string | null;
|
|
250
|
+
spotify_track_id: string;
|
|
251
|
+
/** Audio cut start in ms. `null` when the cut is not a ready sound. */
|
|
252
|
+
timestamp_start_ms: number | null;
|
|
253
|
+
/** Audio cut end in ms. `null` when the cut is not a ready sound. */
|
|
254
|
+
timestamp_end_ms: number | null;
|
|
255
|
+
listeners: number | null;
|
|
256
|
+
followers: number | null;
|
|
257
|
+
link_clicks: number | null;
|
|
258
|
+
cpl: number | null;
|
|
259
|
+
cpf: number | null;
|
|
260
|
+
cpc_linkclick: number | null;
|
|
261
|
+
frequency: number | null;
|
|
262
|
+
}
|
|
263
|
+
/** Background-video group from `GET .../metrics/creatives`. */
|
|
264
|
+
interface CreativeMetricsGroup {
|
|
265
|
+
video_id: string;
|
|
266
|
+
caption: string | null;
|
|
267
|
+
listeners: number | null;
|
|
268
|
+
followers: number | null;
|
|
269
|
+
link_clicks: number | null;
|
|
270
|
+
cpl: number | null;
|
|
271
|
+
cpf: number | null;
|
|
272
|
+
cpc_linkclick: number | null;
|
|
273
|
+
frequency: number | null;
|
|
274
|
+
children: CreativeMetricsChild[];
|
|
275
|
+
}
|
|
276
|
+
interface CreativeMetrics {
|
|
277
|
+
creatives: CreativeMetricsGroup[];
|
|
278
|
+
}
|
|
279
|
+
/** One event from `GET /v1/campaigns/{campaignId}/activity`. */
|
|
280
|
+
interface CampaignActivityItem {
|
|
281
|
+
event_type: string;
|
|
282
|
+
/** ISO 8601 timestamp. */
|
|
283
|
+
timestamp: string;
|
|
284
|
+
summary: string;
|
|
285
|
+
}
|
|
286
|
+
/** Page from `campaigns.activity`. */
|
|
287
|
+
interface CampaignActivityData {
|
|
288
|
+
items: CampaignActivityItem[];
|
|
289
|
+
pagination: Pagination;
|
|
290
|
+
}
|
|
291
|
+
/** Query for {@link CampaignsResource.activity}. */
|
|
292
|
+
interface CampaignActivityParams {
|
|
293
|
+
/**
|
|
294
|
+
* Events at or after this moment. `YYYY-MM-DD` starts at 00:00:00Z.
|
|
295
|
+
* An ISO-8601 timestamp uses that instant. Omit for the full history.
|
|
296
|
+
*/
|
|
297
|
+
startDate?: string;
|
|
298
|
+
/** Page number (1-indexed). Default: `1`. */
|
|
299
|
+
page?: number;
|
|
300
|
+
/** Items per page. Default: `20`. Max: **100**. */
|
|
301
|
+
pageSize?: number;
|
|
302
|
+
}
|
|
303
|
+
/** One row from `GET .../metrics/creative-daily`. */
|
|
304
|
+
interface CreativeDailyRow {
|
|
305
|
+
/** UTC calendar date (`YYYY-MM-DD`). */
|
|
306
|
+
date: string;
|
|
307
|
+
meta_ad_creative_id: string;
|
|
308
|
+
/** Meta media spend. Fees are not included. */
|
|
309
|
+
spend_media: number;
|
|
310
|
+
impressions: number;
|
|
311
|
+
followers: number;
|
|
312
|
+
/** `spend_media / followers` for this row. `null` when followers is zero. */
|
|
313
|
+
cpf: number | null;
|
|
314
|
+
}
|
|
315
|
+
/** Page from `metrics.creativeDaily`. */
|
|
316
|
+
interface CreativeDailyData {
|
|
317
|
+
items: CreativeDailyRow[];
|
|
318
|
+
pagination: Pagination;
|
|
319
|
+
}
|
|
320
|
+
/** Query for {@link MetricsResource.creativeDaily}. */
|
|
321
|
+
interface CreativeDailyParams extends DateRangeParams {
|
|
322
|
+
/** Page number (1-indexed). Default: `1`. */
|
|
323
|
+
page?: number;
|
|
324
|
+
/** Rows per page. Default: `50`. Max: **500**. */
|
|
325
|
+
pageSize?: number;
|
|
202
326
|
}
|
|
203
327
|
/** Success payload from campaign stop. */
|
|
204
328
|
interface CampaignStopData {
|
|
@@ -233,6 +357,8 @@ interface CampaignTier {
|
|
|
233
357
|
tierName: string;
|
|
234
358
|
isEnabled: boolean;
|
|
235
359
|
allocationPercent: number;
|
|
360
|
+
/** Meta learning status for this tier. `null` when not yet reported. */
|
|
361
|
+
learningStatus: TierLearningStatus | null;
|
|
236
362
|
}
|
|
237
363
|
interface CampaignTiersData {
|
|
238
364
|
lastUpdate: string | null;
|
|
@@ -249,10 +375,21 @@ interface TierStatusUpdateItem {
|
|
|
249
375
|
}
|
|
250
376
|
interface UpdateCampaignTiersRequest {
|
|
251
377
|
items: TierStatusUpdateItem[];
|
|
378
|
+
/**
|
|
379
|
+
* Set to `true` to continue a tier edit while ad sets are still learning.
|
|
380
|
+
* Omit or `false` to leave the warning unacknowledged.
|
|
381
|
+
*/
|
|
382
|
+
acknowledgeLearningWarning?: boolean;
|
|
252
383
|
}
|
|
253
384
|
/** Campaign-level metric totals from {@link MetricsResource.overview}. */
|
|
254
385
|
interface MetricsOverview {
|
|
386
|
+
/** Attributed new listeners (CPL denominator). */
|
|
255
387
|
listeners: number;
|
|
388
|
+
/**
|
|
389
|
+
* Distinct new + returning listeners in the selected window.
|
|
390
|
+
* Denominator for {@link MetricsOverview.streams_per_listener}.
|
|
391
|
+
*/
|
|
392
|
+
total_listeners: number;
|
|
256
393
|
streams: number;
|
|
257
394
|
followers: number;
|
|
258
395
|
impressions: number | null;
|
|
@@ -269,9 +406,10 @@ interface MetricsOverview {
|
|
|
269
406
|
cpl: number;
|
|
270
407
|
/** Cost per follower. */
|
|
271
408
|
cpf: number;
|
|
409
|
+
/** Streams / `total_listeners`. Zero when `total_listeners` is 0. */
|
|
272
410
|
streams_per_listener: number;
|
|
273
411
|
}
|
|
274
|
-
/** One row of the `campaign_country_daily` v1.
|
|
412
|
+
/** One row of the `campaign_country_daily` v1.1 schema. */
|
|
275
413
|
interface BreakdownRow {
|
|
276
414
|
provider: 'soundlink';
|
|
277
415
|
account_id: string;
|
|
@@ -291,7 +429,13 @@ interface BreakdownRow {
|
|
|
291
429
|
ad_clicks: number | null;
|
|
292
430
|
link_clicks: number | null;
|
|
293
431
|
streams: number;
|
|
432
|
+
/** Attributed new listeners. */
|
|
294
433
|
listeners: number;
|
|
434
|
+
/** Alias of `listeners`. */
|
|
435
|
+
new_listeners: number;
|
|
436
|
+
returning_listeners: number;
|
|
437
|
+
/** `new_listeners` + `returning_listeners`. Do not sum across days. */
|
|
438
|
+
total_listeners: number;
|
|
295
439
|
followers: number;
|
|
296
440
|
streams_per_listener: number;
|
|
297
441
|
spend_media: number;
|
|
@@ -416,6 +560,15 @@ interface SoundlinkDetail extends SoundlinkSummary {
|
|
|
416
560
|
artistIdFollow: string | null;
|
|
417
561
|
metaPixelId: string | null;
|
|
418
562
|
tiktokPixelId: string | null;
|
|
563
|
+
/** Stored Apple Music URL, or `null` when unset. */
|
|
564
|
+
appleMusicUrl: string | null;
|
|
565
|
+
/** Stored YouTube Music URL, or `null` when unset. */
|
|
566
|
+
youtubeMusicUrl: string | null;
|
|
567
|
+
/**
|
|
568
|
+
* When `false`, the landing page skips Spotify login and only tracks the
|
|
569
|
+
* landing-page click.
|
|
570
|
+
*/
|
|
571
|
+
attributionEnabled: boolean;
|
|
419
572
|
}
|
|
420
573
|
/** Body for `POST /v1/soundlinks`. */
|
|
421
574
|
interface CreateSoundlinkRequest {
|
|
@@ -432,6 +585,21 @@ interface CreateSoundlinkRequest {
|
|
|
432
585
|
* Must be sent together with `metaPixelId`.
|
|
433
586
|
*/
|
|
434
587
|
metaConversionAccessToken?: string;
|
|
588
|
+
/**
|
|
589
|
+
* Optional HTTPS Apple Music song or playlist URL. The API checks URL shape
|
|
590
|
+
* only and stores an album share-sheet link (`?i=`) as the canonical song URL.
|
|
591
|
+
*/
|
|
592
|
+
appleMusicUrl?: string;
|
|
593
|
+
/**
|
|
594
|
+
* Optional HTTPS YouTube Music song or playlist URL. A missing video or
|
|
595
|
+
* playlist returns `400 invalid_request`.
|
|
596
|
+
*/
|
|
597
|
+
youtubeMusicUrl?: string;
|
|
598
|
+
/**
|
|
599
|
+
* When `false`, the landing page skips Spotify login and only tracks the
|
|
600
|
+
* landing-page click. Defaults to `true`. Cannot combine with `autoFollow: true`.
|
|
601
|
+
*/
|
|
602
|
+
attributionEnabled?: boolean;
|
|
435
603
|
}
|
|
436
604
|
/** Paginated soundlink list payload. */
|
|
437
605
|
interface SoundlinkListData {
|
|
@@ -598,6 +766,7 @@ declare class HttpClient {
|
|
|
598
766
|
get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
|
|
599
767
|
post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
600
768
|
patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
769
|
+
put<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
601
770
|
delete<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
602
771
|
getJsonl<T>({ path, query, accept, }: HttpJsonlOptions): Promise<ApiResponse<JsonlStream<T>>>;
|
|
603
772
|
private mutateJson;
|
|
@@ -657,6 +826,22 @@ declare class PingResource {
|
|
|
657
826
|
*/
|
|
658
827
|
ping(): Promise<ApiResponse<PingData>>;
|
|
659
828
|
}
|
|
829
|
+
/** Organization wallet (`GET /v1/wallet`). Requires `wallet:read`. */
|
|
830
|
+
declare class WalletResource {
|
|
831
|
+
private readonly http;
|
|
832
|
+
constructor(http: HttpClient);
|
|
833
|
+
/**
|
|
834
|
+
* Wallet snapshot for the organization on the API key.
|
|
835
|
+
*
|
|
836
|
+
* Maps to `GET /v1/wallet`. `available` is balance minus active reservations.
|
|
837
|
+
*
|
|
838
|
+
* @example
|
|
839
|
+
* ```ts
|
|
840
|
+
* const { data } = await soundlink.wallet.get();
|
|
841
|
+
* ```
|
|
842
|
+
*/
|
|
843
|
+
get(): Promise<ApiResponse<WalletData>>;
|
|
844
|
+
}
|
|
660
845
|
/** Strategy catalog (`GET /v1/strategies`). Requires `campaigns:read`. */
|
|
661
846
|
declare class StrategiesResource {
|
|
662
847
|
private readonly http;
|
|
@@ -720,6 +905,13 @@ declare class CampaignsResource {
|
|
|
720
905
|
* @param campaignId - Campaign identifier returned by {@link CampaignsResource.list}.
|
|
721
906
|
*/
|
|
722
907
|
get(campaignId: string): Promise<ApiResponse<CampaignDetail>>;
|
|
908
|
+
/**
|
|
909
|
+
* Page of creative adds, budget changes, and other campaign events.
|
|
910
|
+
*
|
|
911
|
+
* Maps to `GET /v1/campaigns/{campaignId}/activity`. Requires `campaigns:read`.
|
|
912
|
+
* Omit `startDate` for the full history. Max `pageSize` is **100**.
|
|
913
|
+
*/
|
|
914
|
+
activity(campaignId: string, params?: CampaignActivityParams): Promise<ApiResponse<CampaignActivityData>>;
|
|
723
915
|
/**
|
|
724
916
|
* Create a wallet-funded campaign.
|
|
725
917
|
*
|
|
@@ -761,6 +953,13 @@ declare class CampaignsResource {
|
|
|
761
953
|
* Requires `campaigns:write` and `Idempotency-Key`. Wallet only (`generation: 3`).
|
|
762
954
|
*/
|
|
763
955
|
decreaseBudget(campaignId: string, body: DecreaseCampaignBudgetRequest, options: IdempotencyOptions): Promise<ApiResponse<DecreaseCampaignBudgetData>>;
|
|
956
|
+
/**
|
|
957
|
+
* Set auto-renew for a wallet campaign.
|
|
958
|
+
*
|
|
959
|
+
* Maps to `PUT /v1/campaigns/{campaignId}/auto-renew`. Requires `campaigns:write`
|
|
960
|
+
* and `Idempotency-Key`. Wallet campaigns only (`generation: 3`).
|
|
961
|
+
*/
|
|
962
|
+
updateAutoRenew(campaignId: string, body: UpdateCampaignAutoRenewRequest, options: IdempotencyOptions): Promise<ApiResponse<CampaignAutoRenewData>>;
|
|
764
963
|
/**
|
|
765
964
|
* Async iterator over every campaign across all pages.
|
|
766
965
|
*
|
|
@@ -944,6 +1143,21 @@ declare class MetricsResource {
|
|
|
944
1143
|
* ```
|
|
945
1144
|
*/
|
|
946
1145
|
overview(campaignId: string, params?: DateRangeParams): Promise<ApiResponse<MetricsOverview>>;
|
|
1146
|
+
/**
|
|
1147
|
+
* Lifetime creative performance, grouped by background video.
|
|
1148
|
+
*
|
|
1149
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/creatives`.
|
|
1150
|
+
* Snapshot only — do not send a date range.
|
|
1151
|
+
*/
|
|
1152
|
+
creatives(campaignId: string): Promise<ApiResponse<CreativeMetrics>>;
|
|
1153
|
+
/**
|
|
1154
|
+
* One row per day and Meta ad creative.
|
|
1155
|
+
*
|
|
1156
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/creative-daily`.
|
|
1157
|
+
* Requires `metrics:read`. Omit both dates for every day that has rows.
|
|
1158
|
+
* Max `pageSize` is **500**.
|
|
1159
|
+
*/
|
|
1160
|
+
creativeDaily(campaignId: string, params?: CreativeDailyParams): Promise<ApiResponse<CreativeDailyData>>;
|
|
947
1161
|
}
|
|
948
1162
|
/**
|
|
949
1163
|
* Country-level daily metrics (`campaign_country_daily` schema).
|
|
@@ -1011,6 +1225,8 @@ declare class EngagementMetricsResource {
|
|
|
1011
1225
|
declare class Soundlink {
|
|
1012
1226
|
/** Verify connectivity and authentication. Maps to `GET /v1/ping`. */
|
|
1013
1227
|
readonly ping: PingResource['ping'];
|
|
1228
|
+
/** Organization wallet snapshot. Requires `wallet:read` scope. */
|
|
1229
|
+
readonly wallet: WalletResource;
|
|
1014
1230
|
/** Growth strategy catalog. Requires `campaigns:read` scope. */
|
|
1015
1231
|
readonly strategies: StrategiesResource;
|
|
1016
1232
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
@@ -1052,4 +1268,4 @@ declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
|
1052
1268
|
declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
|
|
1053
1269
|
declare const METRICS_MAX_PAGE_SIZE = 500;
|
|
1054
1270
|
|
|
1055
|
-
export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, type BudgetDecreaseMode, type BudgetIncreaseMode, type BuiltInStrategyType, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreateSoundlinkRequest, type CreativeDirection, type CustomTier, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type DecreaseCampaignBudgetData, type DecreaseCampaignBudgetRequest, type DoItForMeCreativeDirection, type EngagementContext, type EngagementExportParams, type EngagementRow, type ExportCollection, type ExportResource, type FullControlCreativeDirection, type Genre, HttpClient, type IdempotencyOptions, type IncreaseCampaignBudgetData, type IncreaseCampaignBudgetRequest, type JsonlStream, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type Pagination, type PingData, type PublicApiErrorCode, SOUNDLINKS_MAX_PAGE_SIZE, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkBreakdownListData, type SoundlinkBreakdownListParams, type SoundlinkBreakdownRow, type SoundlinkBreakdownSortBy, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkDetail, type SoundlinkEngagementListData, type SoundlinkEngagementListParams, type SoundlinkEngagementRow, type SoundlinkEngagementSortBy, type SoundlinkListData, type SoundlinkListParams, type SoundlinkMetricsOverview, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type SoundlinkSortBy, type SoundlinkStatus, type SoundlinkSummary, type SoundlinkTargetType, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignTiersRequest, getStreamRowCount, resolveClientOptions };
|
|
1271
|
+
export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, type BudgetDecreaseMode, type BudgetIncreaseMode, type BuiltInStrategyType, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignActivityData, type CampaignActivityItem, type CampaignActivityParams, type CampaignAutoRenewData, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreateSoundlinkRequest, type CreativeDailyData, type CreativeDailyParams, type CreativeDailyRow, type CreativeDirection, type CreativeMetrics, type CreativeMetricsChild, type CreativeMetricsGroup, type CustomTier, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type DecreaseCampaignBudgetData, type DecreaseCampaignBudgetRequest, type DoItForMeCreativeDirection, type EngagementContext, type EngagementExportParams, type EngagementRow, type ExportCollection, type ExportResource, type FullControlCreativeDirection, type Genre, HttpClient, type IdempotencyOptions, type IncreaseCampaignBudgetData, type IncreaseCampaignBudgetRequest, type JsonlStream, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type Pagination, type PingData, type PublicApiErrorCode, SOUNDLINKS_MAX_PAGE_SIZE, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkBreakdownListData, type SoundlinkBreakdownListParams, type SoundlinkBreakdownRow, type SoundlinkBreakdownSortBy, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkDetail, type SoundlinkEngagementListData, type SoundlinkEngagementListParams, type SoundlinkEngagementRow, type SoundlinkEngagementSortBy, type SoundlinkListData, type SoundlinkListParams, type SoundlinkMetricsOverview, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type SoundlinkSortBy, type SoundlinkStatus, type SoundlinkSummary, type SoundlinkTargetType, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierLearningStatus, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignAutoRenewRequest, type UpdateCampaignTiersRequest, type WalletData, getStreamRowCount, resolveClientOptions };
|
package/dist/esm/index.js
CHANGED
|
@@ -237,6 +237,21 @@ var HttpClient = class {
|
|
|
237
237
|
idempotencyKey
|
|
238
238
|
});
|
|
239
239
|
}
|
|
240
|
+
async put({
|
|
241
|
+
path,
|
|
242
|
+
body,
|
|
243
|
+
query,
|
|
244
|
+
headers,
|
|
245
|
+
idempotencyKey
|
|
246
|
+
}) {
|
|
247
|
+
return this.mutateJson("PUT", {
|
|
248
|
+
path,
|
|
249
|
+
body,
|
|
250
|
+
query,
|
|
251
|
+
headers,
|
|
252
|
+
idempotencyKey
|
|
253
|
+
});
|
|
254
|
+
}
|
|
240
255
|
async delete({
|
|
241
256
|
path,
|
|
242
257
|
body,
|
|
@@ -456,6 +471,25 @@ var PingResource = class {
|
|
|
456
471
|
return this.http.get({ path: "/ping" });
|
|
457
472
|
}
|
|
458
473
|
};
|
|
474
|
+
var WalletResource = class {
|
|
475
|
+
constructor(http) {
|
|
476
|
+
this.http = http;
|
|
477
|
+
}
|
|
478
|
+
http;
|
|
479
|
+
/**
|
|
480
|
+
* Wallet snapshot for the organization on the API key.
|
|
481
|
+
*
|
|
482
|
+
* Maps to `GET /v1/wallet`. `available` is balance minus active reservations.
|
|
483
|
+
*
|
|
484
|
+
* @example
|
|
485
|
+
* ```ts
|
|
486
|
+
* const { data } = await soundlink.wallet.get();
|
|
487
|
+
* ```
|
|
488
|
+
*/
|
|
489
|
+
get() {
|
|
490
|
+
return this.http.get({ path: "/wallet" });
|
|
491
|
+
}
|
|
492
|
+
};
|
|
459
493
|
var StrategiesResource = class {
|
|
460
494
|
constructor(http) {
|
|
461
495
|
this.http = http;
|
|
@@ -548,6 +582,22 @@ var CampaignsResource = class {
|
|
|
548
582
|
path: `/campaigns/${encodeURIComponent(campaignId)}`
|
|
549
583
|
});
|
|
550
584
|
}
|
|
585
|
+
/**
|
|
586
|
+
* Page of creative adds, budget changes, and other campaign events.
|
|
587
|
+
*
|
|
588
|
+
* Maps to `GET /v1/campaigns/{campaignId}/activity`. Requires `campaigns:read`.
|
|
589
|
+
* Omit `startDate` for the full history. Max `pageSize` is **100**.
|
|
590
|
+
*/
|
|
591
|
+
activity(campaignId, params = {}) {
|
|
592
|
+
return this.http.get({
|
|
593
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/activity`,
|
|
594
|
+
query: {
|
|
595
|
+
startDate: params.startDate,
|
|
596
|
+
page: params.page,
|
|
597
|
+
pageSize: params.pageSize
|
|
598
|
+
}
|
|
599
|
+
});
|
|
600
|
+
}
|
|
551
601
|
/**
|
|
552
602
|
* Create a wallet-funded campaign.
|
|
553
603
|
*
|
|
@@ -612,6 +662,19 @@ var CampaignsResource = class {
|
|
|
612
662
|
idempotencyKey: options.idempotencyKey
|
|
613
663
|
});
|
|
614
664
|
}
|
|
665
|
+
/**
|
|
666
|
+
* Set auto-renew for a wallet campaign.
|
|
667
|
+
*
|
|
668
|
+
* Maps to `PUT /v1/campaigns/{campaignId}/auto-renew`. Requires `campaigns:write`
|
|
669
|
+
* and `Idempotency-Key`. Wallet campaigns only (`generation: 3`).
|
|
670
|
+
*/
|
|
671
|
+
updateAutoRenew(campaignId, body, options) {
|
|
672
|
+
return this.http.put({
|
|
673
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/auto-renew`,
|
|
674
|
+
body,
|
|
675
|
+
idempotencyKey: options.idempotencyKey
|
|
676
|
+
});
|
|
677
|
+
}
|
|
615
678
|
/**
|
|
616
679
|
* Async iterator over every campaign across all pages.
|
|
617
680
|
*
|
|
@@ -867,6 +930,35 @@ var MetricsResource = class {
|
|
|
867
930
|
}
|
|
868
931
|
});
|
|
869
932
|
}
|
|
933
|
+
/**
|
|
934
|
+
* Lifetime creative performance, grouped by background video.
|
|
935
|
+
*
|
|
936
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/creatives`.
|
|
937
|
+
* Snapshot only — do not send a date range.
|
|
938
|
+
*/
|
|
939
|
+
creatives(campaignId) {
|
|
940
|
+
return this.http.get({
|
|
941
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/creatives`
|
|
942
|
+
});
|
|
943
|
+
}
|
|
944
|
+
/**
|
|
945
|
+
* One row per day and Meta ad creative.
|
|
946
|
+
*
|
|
947
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/creative-daily`.
|
|
948
|
+
* Requires `metrics:read`. Omit both dates for every day that has rows.
|
|
949
|
+
* Max `pageSize` is **500**.
|
|
950
|
+
*/
|
|
951
|
+
creativeDaily(campaignId, params = {}) {
|
|
952
|
+
return this.http.get({
|
|
953
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/creative-daily`,
|
|
954
|
+
query: {
|
|
955
|
+
startDate: params.startDate,
|
|
956
|
+
endDate: params.endDate,
|
|
957
|
+
page: params.page,
|
|
958
|
+
pageSize: params.pageSize
|
|
959
|
+
}
|
|
960
|
+
});
|
|
961
|
+
}
|
|
870
962
|
};
|
|
871
963
|
var BreakdownMetricsResource = class {
|
|
872
964
|
constructor(http) {
|
|
@@ -936,6 +1028,8 @@ var EngagementMetricsResource = class {
|
|
|
936
1028
|
var Soundlink = class {
|
|
937
1029
|
/** Verify connectivity and authentication. Maps to `GET /v1/ping`. */
|
|
938
1030
|
ping;
|
|
1031
|
+
/** Organization wallet snapshot. Requires `wallet:read` scope. */
|
|
1032
|
+
wallet;
|
|
939
1033
|
/** Growth strategy catalog. Requires `campaigns:read` scope. */
|
|
940
1034
|
strategies;
|
|
941
1035
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
@@ -953,6 +1047,7 @@ var Soundlink = class {
|
|
|
953
1047
|
const http = new HttpClient(options);
|
|
954
1048
|
const pingResource = new PingResource(http);
|
|
955
1049
|
this.ping = pingResource.ping.bind(pingResource);
|
|
1050
|
+
this.wallet = new WalletResource(http);
|
|
956
1051
|
this.strategies = new StrategiesResource(http);
|
|
957
1052
|
this.campaigns = new CampaignsResource(http);
|
|
958
1053
|
this.soundlinks = new SoundlinksResource(http);
|