soundlink 2.9.0 → 2.11.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.
@@ -0,0 +1,877 @@
1
+ /** Stable snake_case error codes returned by the Soundlink Public API. */
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' | 'stream_value_not_enabled' | 'custom_pixel_not_enabled' | 'meta_pixel_conflict' | 'pixel_in_use' | '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';
5
+ /** Ad platform used by the campaign. */
6
+ type SocialPlatform = 'meta';
7
+ /**
8
+ * Campaign resource generation.
9
+ *
10
+ * - `1` — Stripe / one-time / subscription / legacy
11
+ * - `2` — managed
12
+ * - `3` — wallet (writable via Public API)
13
+ */
14
+ type CampaignGeneration = 1 | 2 | 3;
15
+ /**
16
+ * Engagement context for per-track metrics.
17
+ *
18
+ * - `catalog` — same-artist spillover and promoted track plays.
19
+ * - `playlist` — per-track performance inside a promoted playlist.
20
+ */
21
+ type EngagementContext = 'catalog' | 'playlist';
22
+ /** Allowed `sortBy` values for {@link CampaignListParams}. */
23
+ type CampaignSortBy = 'createdAt' | 'status';
24
+ /** Allowed `sortBy` values for {@link SoundlinkListParams}. */
25
+ type SoundlinkSortBy = 'createdAt';
26
+ /** Allowed `sortBy` values for breakdown list requests. */
27
+ type BreakdownSortBy = 'report_date' | 'spend_total';
28
+ /** Allowed `sortBy` values for soundlink breakdown list requests. */
29
+ type SoundlinkBreakdownSortBy = 'report_date' | 'country_code';
30
+ /** Allowed `sortBy` values for soundlink engagement list requests. */
31
+ type SoundlinkEngagementSortBy = 'report_date';
32
+ /** Sort direction for list endpoints. */
33
+ type SortOrder = 'asc' | 'desc';
34
+ /** Lifecycle status for a self-serve soundlink. */
35
+ type SoundlinkStatus = 'draft' | 'active' | 'archived';
36
+ /** Spotify resource type promoted by a soundlink. */
37
+ type SoundlinkTargetType = 'track' | 'album' | 'playlist';
38
+ /** Growth strategy for campaign create / catalog. */
39
+ type StrategyType = 'maximum_growth' | 'market_discovery' | 'revenue_maximization' | 'custom';
40
+ /** Non-custom strategies (platform default tiering; no `tierTargeting`). */
41
+ type BuiltInStrategyType = Exclude<StrategyType, 'custom'>;
42
+ /** Strictly validated genre list from the Public API. */
43
+ type Genre = 'Alternative/Indie' | 'Ambient/Sleep' | 'Chill/Background' | 'Classical' | 'Country' | 'Electronic/Dance' | 'Hip-Hop/R&B' | 'Latin/Reggaeton' | 'Pop' | 'Rock' | 'Christmas';
44
+ /** Budget increase mode for wallet campaigns. */
45
+ type BudgetIncreaseMode = 'current_cycle' | 'next_renewal' | 'current_and_renewals';
46
+ /** Budget decrease mode for wallet campaigns. */
47
+ type BudgetDecreaseMode = 'current_cycle' | 'current_and_renewals';
48
+ /** Options for write methods that require an `Idempotency-Key` header. */
49
+ interface IdempotencyOptions {
50
+ /** Client-generated key; reused retries must send the same body. */
51
+ idempotencyKey: string;
52
+ }
53
+ /** Server-generated request metadata. Include `requestId` when contacting Soundlink support. */
54
+ interface ApiMeta {
55
+ /** UUID for this API request. */
56
+ requestId: string;
57
+ }
58
+ /** API error returned in `{ data: null, error }` — never thrown by SDK methods. */
59
+ interface ApiError {
60
+ /** Stable error code from the Public API. */
61
+ code: PublicApiErrorCode;
62
+ /** Human-readable description. Do not parse programmatically. */
63
+ message: string;
64
+ /** HTTP status code. */
65
+ status: number;
66
+ /** Same as `meta.requestId` when present. */
67
+ requestId?: string;
68
+ /** Seconds to wait before retrying, from the `Retry-After` header on `429`. */
69
+ retryAfter?: number;
70
+ /**
71
+ * Error-code-specific context from the API (e.g. `available` / `required` on
72
+ * `insufficient_credit`). Absent when the API sends no `details`.
73
+ */
74
+ details?: Record<string, unknown> | null;
75
+ }
76
+ /**
77
+ * Standard SDK response shape for every Public API method.
78
+ *
79
+ * @typeParam T - Success payload type. `null` when `error` is set.
80
+ */
81
+ interface ApiResponse<T> {
82
+ /** Success payload, or `null` when the API returned an error. */
83
+ data: T | null;
84
+ /** API error details, or `null` on success. */
85
+ error: ApiError | null;
86
+ /** Request metadata (always present on successful envelope responses). */
87
+ meta?: ApiMeta;
88
+ }
89
+ /** Pagination metadata included in list responses. */
90
+ interface Pagination {
91
+ /** Current page (1-indexed). */
92
+ page: number;
93
+ /** Items per page. */
94
+ pageSize: number;
95
+ /** Total items across all pages. */
96
+ totalCount: number;
97
+ /** Total number of pages. */
98
+ totalPages: number;
99
+ }
100
+ /** Campaign summary returned by {@link CampaignsResource.list}. */
101
+ interface CampaignSummary {
102
+ campaignId: string;
103
+ organizationId: string;
104
+ status: CampaignStatus;
105
+ socialPlatform: SocialPlatform;
106
+ /** Daily budget in USD. */
107
+ dailyBudget: number;
108
+ /** Total budget in USD. */
109
+ totalBudget: number;
110
+ /** Campaign duration in days. */
111
+ campaignDuration: number;
112
+ /** Resource generation — writable Public API methods require `3`. */
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;
126
+ /** ISO 8601 creation timestamp. */
127
+ createdAt: string;
128
+ /** ISO 8601 last update timestamp. */
129
+ updatedAt: string;
130
+ }
131
+ /** Meta ad set learning status on a campaign tier. */
132
+ type TierLearningStatus = 'LEARNING' | 'FAIL' | 'SUCCESS';
133
+ /** Full campaign detail from {@link CampaignsResource.get}. */
134
+ interface CampaignDetail extends CampaignSummary {
135
+ /** Growth strategy set at creation (e.g. `custom`, `maximum_growth`). */
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;
148
+ }
149
+ /** Paginated campaign list payload. */
150
+ interface CampaignListData {
151
+ items: CampaignSummary[];
152
+ pagination: Pagination;
153
+ }
154
+ /** Successful `GET /v1/ping` payload. */
155
+ interface PingData {
156
+ status: 'ok';
157
+ }
158
+ /** One entry from `GET /v1/strategies`. */
159
+ interface StrategyCatalogItem {
160
+ strategyType: StrategyType;
161
+ /** When `false`, omit `tierTargeting` on create. */
162
+ tierTargetingAllowed: boolean;
163
+ }
164
+ /** Payload from `GET /v1/strategies`. */
165
+ interface StrategiesCatalogData {
166
+ strategies: StrategyCatalogItem[];
167
+ }
168
+ /** Shared fields for wallet campaign create. */
169
+ interface CreateCampaignRequestBase {
170
+ /** Spotify track or playlist URL. */
171
+ spotifyUrl: string;
172
+ /** USD per day (minimum 10). */
173
+ dailyBudget: number;
174
+ /** Duration in days: 7–30, or 60, or 90. */
175
+ durationDays: number;
176
+ genre: Genre;
177
+ /** Optional; server generates a default when omitted. */
178
+ campaignName?: string;
179
+ creativeDirection?: CreativeDirection;
180
+ trackOptions?: {
181
+ artistIdFollow?: string;
182
+ };
183
+ /** Lineage only — does not copy settings from the source campaign. */
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;
190
+ }
191
+ interface DoItForMeCreativeDirection {
192
+ type: 'do_it_for_me';
193
+ }
194
+ interface FullControlCreativeDirection {
195
+ type: 'full_control';
196
+ selectedCreatives: Array<{
197
+ videoId: string;
198
+ }>;
199
+ }
200
+ type CreativeDirection = DoItForMeCreativeDirection | FullControlCreativeDirection;
201
+ interface CustomTier {
202
+ name: string;
203
+ percentBudget: number;
204
+ countries?: string[];
205
+ language?: string;
206
+ }
207
+ interface TierTargeting {
208
+ customTierIds?: number[];
209
+ customTiers?: CustomTier[];
210
+ }
211
+ /** Create with a built-in strategy (no `tierTargeting`). */
212
+ interface CreateCampaignRequestBuiltIn extends CreateCampaignRequestBase {
213
+ strategyType: BuiltInStrategyType;
214
+ tierTargeting?: never;
215
+ }
216
+ /** Create with `custom` strategy (requires `tierTargeting`). */
217
+ interface CreateCampaignRequestCustom extends CreateCampaignRequestBase {
218
+ strategyType: 'custom';
219
+ tierTargeting: TierTargeting;
220
+ }
221
+ /** Body for `POST /v1/campaigns`. */
222
+ type CreateCampaignRequest = CreateCampaignRequestBuiltIn | CreateCampaignRequestCustom;
223
+ /** Success payload from campaign create. */
224
+ interface CampaignCreateData {
225
+ campaignId: string;
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
+ /** Ad platform for an organization pixel. Only `meta` is supported today. */
247
+ type PixelPlatform = 'meta';
248
+ /** Send-health status on an organization pixel. */
249
+ type PixelStatus = 'ok' | 'error';
250
+ /** One pixel from {@link PixelsResource.list} / {@link PixelsResource.update}. */
251
+ interface Pixel {
252
+ id: string;
253
+ platform: PixelPlatform;
254
+ /** App soundlink create picker only; create APIs never fall back to it. */
255
+ isDefault: boolean;
256
+ status: PixelStatus;
257
+ lastErrorCode: string | null;
258
+ /** ISO 8601 when an open send-error episode started, or `null`. */
259
+ errorSince: string | null;
260
+ }
261
+ /** Payload from `GET /v1/pixels`. */
262
+ interface PixelListData {
263
+ pixels: Pixel[];
264
+ }
265
+ /** Body for `PUT /v1/pixels/{pixelId}`. At least one of `accessToken` or `isDefault`. */
266
+ interface UpdatePixelRequest {
267
+ platform: PixelPlatform;
268
+ /** Conversions API access token. Stored and never returned. Required when creating. */
269
+ accessToken?: string;
270
+ /** Sets or clears the organization default for Meta. */
271
+ isDefault?: boolean;
272
+ }
273
+ /** Payload from `POST /v1/pixels/{pixelId}/test-events`. */
274
+ interface PixelTestEventData {
275
+ status: 'sent';
276
+ pixelId: string;
277
+ }
278
+ /** One variant under a creative group (`GET .../metrics/creatives`). */
279
+ interface CreativeMetricsChild {
280
+ caption: string | null;
281
+ language: string | null;
282
+ spotify_track_id: string;
283
+ /** Audio cut start in ms. `null` when the cut is not a ready sound. */
284
+ timestamp_start_ms: number | null;
285
+ /** Audio cut end in ms. `null` when the cut is not a ready sound. */
286
+ timestamp_end_ms: number | null;
287
+ listeners: number | null;
288
+ followers: number | null;
289
+ link_clicks: number | null;
290
+ cpl: number | null;
291
+ cpf: number | null;
292
+ cpc_linkclick: number | null;
293
+ frequency: number | null;
294
+ }
295
+ /** Background-video group from `GET .../metrics/creatives`. */
296
+ interface CreativeMetricsGroup {
297
+ video_id: string;
298
+ caption: string | null;
299
+ listeners: number | null;
300
+ followers: number | null;
301
+ link_clicks: number | null;
302
+ cpl: number | null;
303
+ cpf: number | null;
304
+ cpc_linkclick: number | null;
305
+ frequency: number | null;
306
+ children: CreativeMetricsChild[];
307
+ }
308
+ interface CreativeMetrics {
309
+ creatives: CreativeMetricsGroup[];
310
+ }
311
+ /** One event from `GET /v1/campaigns/{campaignId}/activity`. */
312
+ interface CampaignActivityItem {
313
+ event_type: string;
314
+ /** ISO 8601 timestamp. */
315
+ timestamp: string;
316
+ summary: string;
317
+ }
318
+ /** Page from `campaigns.activity`. */
319
+ interface CampaignActivityData {
320
+ items: CampaignActivityItem[];
321
+ pagination: Pagination;
322
+ }
323
+ /** Query for {@link CampaignsResource.activity}. */
324
+ interface CampaignActivityParams {
325
+ /**
326
+ * Events at or after this moment. `YYYY-MM-DD` starts at 00:00:00Z.
327
+ * An ISO-8601 timestamp uses that instant. Omit for the full history.
328
+ */
329
+ startDate?: string;
330
+ /** Page number (1-indexed). Default: `1`. */
331
+ page?: number;
332
+ /** Items per page. Default: `20`. Max: **100**. */
333
+ pageSize?: number;
334
+ }
335
+ /** One row from `GET .../metrics/creative-daily`. */
336
+ interface CreativeDailyRow {
337
+ /** UTC calendar date (`YYYY-MM-DD`). */
338
+ date: string;
339
+ meta_ad_creative_id: string;
340
+ /** Meta media spend. Fees are not included. */
341
+ spend_media: number;
342
+ impressions: number;
343
+ followers: number;
344
+ /** `spend_media / followers` for this row. `null` when followers is zero. */
345
+ cpf: number | null;
346
+ }
347
+ /** Page from `metrics.creativeDaily`. */
348
+ interface CreativeDailyData {
349
+ items: CreativeDailyRow[];
350
+ pagination: Pagination;
351
+ }
352
+ /** Query for {@link MetricsResource.creativeDaily}. */
353
+ interface CreativeDailyParams extends DateRangeParams {
354
+ /** Page number (1-indexed). Default: `1`. */
355
+ page?: number;
356
+ /** Rows per page. Default: `50`. Max: **500**. */
357
+ pageSize?: number;
358
+ }
359
+ /** Success payload from campaign stop. */
360
+ interface CampaignStopData {
361
+ campaignId: string;
362
+ status: CampaignStatus;
363
+ }
364
+ interface IncreaseCampaignBudgetRequest {
365
+ amount: number;
366
+ mode?: BudgetIncreaseMode;
367
+ targetDailyBudget?: number;
368
+ }
369
+ interface IncreaseCampaignBudgetData {
370
+ campaignId: string;
371
+ mode: BudgetIncreaseMode;
372
+ amount: number;
373
+ walletBalance: number;
374
+ walletNextCycleDailyBudget?: number | null;
375
+ }
376
+ interface DecreaseCampaignBudgetRequest {
377
+ targetDailyBudget: number;
378
+ mode?: BudgetDecreaseMode;
379
+ }
380
+ interface DecreaseCampaignBudgetData {
381
+ campaignId: string;
382
+ mode: BudgetDecreaseMode;
383
+ targetDailyBudget: number;
384
+ accepted: true;
385
+ walletNextCycleDailyBudget?: number | null;
386
+ }
387
+ interface CampaignTier {
388
+ tierId: number;
389
+ tierName: string;
390
+ isEnabled: boolean;
391
+ allocationPercent: number;
392
+ /** Meta learning status for this tier. `null` when not yet reported. */
393
+ learningStatus: TierLearningStatus | null;
394
+ }
395
+ interface CampaignTiersData {
396
+ lastUpdate: string | null;
397
+ tiers: CampaignTier[];
398
+ }
399
+ interface TierStatusUpdateItem {
400
+ /**
401
+ * Targeting tier id — same value as `tierId` returned by
402
+ * `campaigns.tiers.get` (`CampaignTier.tierId`).
403
+ */
404
+ targetingTierId: number;
405
+ isEnabled: boolean;
406
+ newAllocationPercent: number;
407
+ }
408
+ interface UpdateCampaignTiersRequest {
409
+ items: TierStatusUpdateItem[];
410
+ /**
411
+ * Set to `true` to continue a tier edit while ad sets are still learning.
412
+ * Omit or `false` to leave the warning unacknowledged.
413
+ */
414
+ acknowledgeLearningWarning?: boolean;
415
+ }
416
+ /** Campaign-level metric totals from {@link MetricsResource.overview}. */
417
+ interface MetricsOverview {
418
+ /** Attributed new listeners (CPL denominator). */
419
+ listeners: number;
420
+ /**
421
+ * Distinct new + returning listeners in the selected window.
422
+ * Denominator for {@link MetricsOverview.streams_per_listener}.
423
+ */
424
+ total_listeners: number;
425
+ streams: number;
426
+ followers: number;
427
+ impressions: number | null;
428
+ ad_clicks: number | null;
429
+ link_clicks: number | null;
430
+ /** Meta ad spend excluding Soundlink fees (USD). */
431
+ spend_media: number;
432
+ /** Total billed amount including fees (USD). */
433
+ spend_total: number;
434
+ /** Soundlink service fee (USD). */
435
+ fees: number;
436
+ currency: string;
437
+ /** Cost per listener. */
438
+ cpl: number;
439
+ /** Cost per follower. */
440
+ cpf: number;
441
+ /** Streams / `total_listeners`. Zero when `total_listeners` is 0. */
442
+ streams_per_listener: number;
443
+ }
444
+ /** One row of the `campaign_country_daily` v1.1 schema. */
445
+ interface BreakdownRow {
446
+ provider: 'soundlink';
447
+ account_id: string;
448
+ schema_version: string;
449
+ /** UTC calendar date (`YYYY-MM-DD`). */
450
+ report_date: string;
451
+ report_date_timezone: 'UTC';
452
+ exported_at: string;
453
+ campaign_id: string;
454
+ campaign_name: string;
455
+ campaign_target_type: 'track' | 'playlist' | null;
456
+ campaign_target_isrc: string | null;
457
+ campaign_target_spotify_track_id: string | null;
458
+ campaign_target_playlist_id: string | null;
459
+ country_code: string;
460
+ impressions: number | null;
461
+ ad_clicks: number | null;
462
+ link_clicks: number | null;
463
+ streams: number;
464
+ /** Attributed new listeners. */
465
+ listeners: number;
466
+ /** Alias of `listeners`. */
467
+ new_listeners: number;
468
+ returning_listeners: number;
469
+ /** `new_listeners` + `returning_listeners`. Do not sum across days. */
470
+ total_listeners: number;
471
+ followers: number;
472
+ streams_per_listener: number;
473
+ spend_media: number;
474
+ spend_total: number;
475
+ fees: number;
476
+ currency: string;
477
+ currency_account: string;
478
+ cpl: number;
479
+ cpf: number;
480
+ cpc_linkclick: number | null;
481
+ ctr_linkclick: number | null;
482
+ ctr_adclick: number | null;
483
+ cost_per_result: number;
484
+ result_type: 'lp_click' | 'stream' | 'follow' | null;
485
+ }
486
+ /** One row of the `campaign_engagement_daily` v1.0 schema. */
487
+ interface EngagementRow {
488
+ provider: 'soundlink';
489
+ account_id: string;
490
+ schema_version: string;
491
+ report_date: string;
492
+ report_date_timezone: 'UTC';
493
+ exported_at: string;
494
+ campaign_id: string;
495
+ campaign_name: string;
496
+ campaign_target_type: 'track' | 'playlist' | null;
497
+ campaign_target_isrc: string | null;
498
+ campaign_target_spotify_track_id: string | null;
499
+ campaign_target_playlist_id: string | null;
500
+ status: string;
501
+ engagement_context: EngagementContext;
502
+ country_code: string;
503
+ engaged_track_isrc: string | null;
504
+ engaged_spotify_track_id: string;
505
+ engaged_track_name: string;
506
+ playlist_position: number | null;
507
+ new_listeners: number;
508
+ returning_listeners: number;
509
+ listeners: number;
510
+ new_listener_streams: number;
511
+ returning_listener_streams: number;
512
+ streams: number;
513
+ spl: number;
514
+ }
515
+ /** Paginated breakdown list payload. */
516
+ interface BreakdownListData {
517
+ schemaVersion: string;
518
+ items: BreakdownRow[];
519
+ pagination: Pagination;
520
+ }
521
+ /** In-memory result from {@link ExportResource.collect}. */
522
+ interface ExportCollection<T> {
523
+ rows: T[];
524
+ /** Same as `rows.length`. */
525
+ rowCount: number;
526
+ }
527
+ /** Async iterable JSONL stream from export endpoints. May include `rowCount` from `X-Row-Count`. */
528
+ interface JsonlStream<T> extends AsyncIterable<T> {
529
+ /** Total rows when the API sent the `X-Row-Count` header. */
530
+ rowCount?: number;
531
+ }
532
+ /** Options for {@link Soundlink} and {@link HttpClient}. */
533
+ interface SoundlinkClientOptions {
534
+ /** Soundlink API key (`sk_<prefix>_<secret>`). Sent as `Authorization: Bearer`. */
535
+ apiKey: string;
536
+ /** API base URL. Defaults to `https://api.getsoundlink.com`. */
537
+ baseUrl?: string;
538
+ /** Request timeout in milliseconds. Default: `30000`. */
539
+ timeout?: number;
540
+ /** Retries on `429` and `5xx`. Default: `2`. */
541
+ maxRetries?: number;
542
+ /** Custom `fetch` implementation (tests, Edge runtimes). */
543
+ fetch?: typeof fetch;
544
+ }
545
+ /** API key string or full options object. */
546
+ type SoundlinkOptions = SoundlinkClientOptions | string;
547
+ /** Query params for {@link CampaignsResource.list}. */
548
+ interface CampaignListParams {
549
+ /** Page number (1-indexed). Default: `1`. */
550
+ page?: number;
551
+ /** Items per page. Default: `10`. Max: **100**. */
552
+ pageSize?: number;
553
+ /** Sort field. Default: `createdAt`. */
554
+ sortBy?: CampaignSortBy;
555
+ /** Sort direction. Default: `desc`. */
556
+ sortOrder?: SortOrder;
557
+ }
558
+ /** Query params for {@link SoundlinksResource.list}. */
559
+ interface SoundlinkListParams {
560
+ /** Page number (1-indexed). Default: `1`. */
561
+ page?: number;
562
+ /** Items per page. Default: `10`. Max: **100**. */
563
+ pageSize?: number;
564
+ /** Sort field. Default: `createdAt`. */
565
+ sortBy?: SoundlinkSortBy;
566
+ /** Sort direction. Default: `desc`. */
567
+ sortOrder?: SortOrder;
568
+ }
569
+ /** Inclusive date range filter (`YYYY-MM-DD`). */
570
+ interface DateRangeParams {
571
+ /** Inclusive start date. */
572
+ startDate?: string;
573
+ /** Inclusive end date. Must not be before `startDate`. */
574
+ endDate?: string;
575
+ }
576
+ /** Self-serve soundlink summary from {@link SoundlinksResource.list}. */
577
+ interface SoundlinkSummary {
578
+ soundlinkId: string;
579
+ organizationId: string;
580
+ name: string;
581
+ /** Public landing page URL (`https://sndl.ink/soundlink/...`). */
582
+ url: string;
583
+ targetType: SoundlinkTargetType | null;
584
+ spotifyUrl: string | null;
585
+ status: SoundlinkStatus;
586
+ /** ISO 8601 creation timestamp. */
587
+ createdAt: string;
588
+ }
589
+ /** Full soundlink detail from {@link SoundlinksResource.get}. */
590
+ interface SoundlinkDetail extends SoundlinkSummary {
591
+ autoFollow: boolean;
592
+ artistIdFollow: string | null;
593
+ metaPixelId: string | null;
594
+ tiktokPixelId: string | null;
595
+ /** Stored Apple Music URL, or `null` when unset. */
596
+ appleMusicUrl: string | null;
597
+ /** Stored YouTube Music URL, or `null` when unset. */
598
+ youtubeMusicUrl: string | null;
599
+ /**
600
+ * When `false`, the landing page skips Spotify login and only tracks the
601
+ * landing-page click.
602
+ */
603
+ attributionEnabled: boolean;
604
+ /**
605
+ * Whether Soundlink Stream Value is on for this soundlink. `true` only when
606
+ * it was set at creation.
607
+ */
608
+ streamValueEventEnabled: boolean;
609
+ }
610
+ /** Body for `POST /v1/soundlinks`. */
611
+ interface CreateSoundlinkRequest {
612
+ name: string;
613
+ /** HTTPS Spotify track or playlist URL. */
614
+ spotifyUrl: string;
615
+ autoFollow?: boolean;
616
+ /** Spotify artist ID for auto-follow on track links. Ignored for playlists. */
617
+ artistIdFollow?: string;
618
+ /**
619
+ * Meta pixel ID. Alone: reuse a pixel already saved via `pixels`.
620
+ * With `metaConversionAccessToken`: save or rotate. Never applies an org default.
621
+ */
622
+ metaPixelId?: string;
623
+ /**
624
+ * Meta Conversions API token. Write-only: accepted on create, never returned.
625
+ * Requires `metaPixelId`.
626
+ */
627
+ metaConversionAccessToken?: string;
628
+ /**
629
+ * Optional HTTPS Apple Music song or playlist URL. The API checks URL shape
630
+ * only and stores an album share-sheet link (`?i=`) as the canonical song URL.
631
+ */
632
+ appleMusicUrl?: string;
633
+ /**
634
+ * Optional HTTPS YouTube Music song or playlist URL. A missing video or
635
+ * playlist returns `400 invalid_request`.
636
+ */
637
+ youtubeMusicUrl?: string;
638
+ /**
639
+ * When `false`, the landing page skips Spotify login and only tracks the
640
+ * landing-page click. Defaults to `true`. Cannot combine with `autoFollow: true`.
641
+ */
642
+ attributionEnabled?: boolean;
643
+ /**
644
+ * When `true`, Soundlink sends a Meta conversion event named
645
+ * "Soundlink Stream Value" for attributed streams on this soundlink.
646
+ * Defaults to `false`. The organization must already be enabled for it, or
647
+ * create returns `403 stream_value_not_enabled`. Cannot combine with
648
+ * `attributionEnabled: false`. Can only be set at creation.
649
+ */
650
+ streamValueEventEnabled?: boolean;
651
+ }
652
+ /** Paginated soundlink list payload. */
653
+ interface SoundlinkListData {
654
+ items: SoundlinkSummary[];
655
+ pagination: Pagination;
656
+ }
657
+ /**
658
+ * Soundlink-level metric totals from {@link SoundlinksResource.metricsOverview}.
659
+ *
660
+ * No financial fields — ads for self-serve soundlinks run in the customer's Meta.
661
+ */
662
+ interface SoundlinkMetricsOverview {
663
+ views: number;
664
+ link_clicks: number | null;
665
+ streams: number;
666
+ listeners: number;
667
+ followers: number;
668
+ streams_per_listener: number;
669
+ ctr_lp: number | null;
670
+ }
671
+ /** One row of the `soundlink_country_daily` v1.0 schema. */
672
+ interface SoundlinkBreakdownRow {
673
+ provider: 'soundlink';
674
+ account_id: string;
675
+ schema_version: string;
676
+ /** UTC calendar date (`YYYY-MM-DD`). */
677
+ report_date: string;
678
+ report_date_timezone: 'UTC';
679
+ exported_at: string;
680
+ soundlink_id: string;
681
+ soundlink_name: string;
682
+ soundlink_target_type: 'track' | 'playlist' | null;
683
+ soundlink_target_isrc: string | null;
684
+ soundlink_target_spotify_track_id: string | null;
685
+ soundlink_target_playlist_id: string | null;
686
+ country_code: string;
687
+ views: number;
688
+ link_clicks: number | null;
689
+ spotify_link_clicks: number;
690
+ apple_music_link_clicks: number;
691
+ youtube_music_link_clicks: number;
692
+ streams: number;
693
+ listeners: number;
694
+ new_listeners: number | null;
695
+ returning_listeners: number | null;
696
+ new_listener_streams: number | null;
697
+ returning_listener_streams: number | null;
698
+ followers: number;
699
+ streams_per_listener: number;
700
+ ctr_lp: number | null;
701
+ }
702
+ /** Paginated soundlink breakdown list payload. */
703
+ interface SoundlinkBreakdownListData {
704
+ schemaVersion: string;
705
+ items: SoundlinkBreakdownRow[];
706
+ pagination: Pagination;
707
+ }
708
+ /** One row of the `soundlink_engagement_daily` v1.0 schema. */
709
+ interface SoundlinkEngagementRow {
710
+ provider: 'soundlink';
711
+ account_id: string;
712
+ schema_version: string;
713
+ report_date: string;
714
+ report_date_timezone: 'UTC';
715
+ exported_at: string;
716
+ soundlink_id: string;
717
+ soundlink_name: string;
718
+ soundlink_target_type: 'track' | 'playlist' | null;
719
+ soundlink_target_isrc: string | null;
720
+ soundlink_target_spotify_track_id: string | null;
721
+ soundlink_target_playlist_id: string | null;
722
+ engagement_context: EngagementContext;
723
+ country_code: string;
724
+ engaged_track_isrc: string | null;
725
+ engaged_spotify_track_id: string;
726
+ engaged_track_name: string;
727
+ playlist_position: number | null;
728
+ new_listeners: number;
729
+ returning_listeners: number;
730
+ listeners: number;
731
+ new_listener_streams: number;
732
+ returning_listener_streams: number;
733
+ streams: number;
734
+ spl: number;
735
+ }
736
+ /** Paginated soundlink engagement list payload. */
737
+ interface SoundlinkEngagementListData {
738
+ schemaVersion: string;
739
+ items: SoundlinkEngagementRow[];
740
+ pagination: Pagination;
741
+ }
742
+ /** Query params for {@link SoundlinkBreakdownMetricsResource.list}. */
743
+ interface SoundlinkBreakdownListParams extends DateRangeParams {
744
+ page?: number;
745
+ /** Default: `50`. Max: **500**. */
746
+ pageSize?: number;
747
+ /** Default: `report_date`. */
748
+ sortBy?: SoundlinkBreakdownSortBy;
749
+ /** Default: `asc`. */
750
+ sortOrder?: SortOrder;
751
+ }
752
+ /**
753
+ * Query params for {@link SoundlinkEngagementMetricsResource.list}.
754
+ *
755
+ * Defaults to the last 90 days ending today; max **90 days** per request.
756
+ */
757
+ interface SoundlinkEngagementListParams extends DateRangeParams {
758
+ page?: number;
759
+ /** Default: `50`. Max: **500**. */
760
+ pageSize?: number;
761
+ /** Filter to a single engagement context. Omit to return both. */
762
+ engagementContext?: EngagementContext;
763
+ /** Default: `report_date`. */
764
+ sortBy?: SoundlinkEngagementSortBy;
765
+ /** Default: `asc`. */
766
+ sortOrder?: SortOrder;
767
+ }
768
+ /** Query params for {@link BreakdownMetricsResource.list}. */
769
+ interface BreakdownListParams extends DateRangeParams {
770
+ page?: number;
771
+ /** Default: `50`. Max: **500**. */
772
+ pageSize?: number;
773
+ /** Default: `report_date`. */
774
+ sortBy?: BreakdownSortBy;
775
+ /** Default: `asc`. */
776
+ sortOrder?: SortOrder;
777
+ }
778
+ /** Query params for engagement JSONL export. */
779
+ interface EngagementExportParams extends DateRangeParams {
780
+ engagementContext?: EngagementContext;
781
+ }
782
+ /** Query params for breakdown JSONL export. Max **90 days** per request. */
783
+ type BreakdownExportParams = DateRangeParams;
784
+ /**
785
+ * One row of the `soundlink_cohort_retention_daily` v1.0 schema.
786
+ * Day-N fields are `null` until that day has passed for the cohort date.
787
+ */
788
+ interface CohortRetentionDailyRow {
789
+ provider: 'soundlink';
790
+ account_id: string;
791
+ schema_version: string;
792
+ /** UTC calendar date (`YYYY-MM-DD`). */
793
+ cohort_date: string;
794
+ cohort_date_timezone: 'UTC';
795
+ exported_at: string;
796
+ soundlink_id: string;
797
+ soundlink_name: string;
798
+ soundlink_target_type: 'track' | 'playlist' | null;
799
+ soundlink_target_isrc?: string | null;
800
+ soundlink_target_spotify_track_id?: string | null;
801
+ soundlink_target_playlist_id?: string | null;
802
+ cohort_size: number;
803
+ returned_on_day_1: number | null;
804
+ retention_by_day_1: number | null;
805
+ returned_on_day_2: number | null;
806
+ retention_by_day_2: number | null;
807
+ returned_on_day_3: number | null;
808
+ retention_by_day_3: number | null;
809
+ returned_on_day_4: number | null;
810
+ retention_by_day_4: number | null;
811
+ returned_on_day_5: number | null;
812
+ retention_by_day_5: number | null;
813
+ returned_on_day_6: number | null;
814
+ retention_by_day_6: number | null;
815
+ returned_on_day_7: number | null;
816
+ retention_by_day_7: number | null;
817
+ }
818
+ /** Payload from campaign/soundlink `metrics/retention`. */
819
+ interface CohortRetentionListData {
820
+ schemaVersion: string;
821
+ items: CohortRetentionDailyRow[];
822
+ }
823
+ /** Path param for listening-insights endpoints. */
824
+ type ListeningInsight = 'other-artists' | 'catalog-dig-in' | 'stream-split';
825
+ /** Date window returned with every listening insight (from the listening graph). */
826
+ interface ListeningInsightWindow {
827
+ startDate: string;
828
+ endDate: string;
829
+ }
830
+ interface OtherArtistsInsightArtist {
831
+ /** Lowercased, trimmed artist name. */
832
+ artist: string;
833
+ listeners: number;
834
+ streams: number;
835
+ }
836
+ interface OtherArtistsListeningInsight {
837
+ soundlinkId: string;
838
+ campaignId: string | null;
839
+ insight: 'other-artists';
840
+ window: ListeningInsightWindow;
841
+ artists: OtherArtistsInsightArtist[];
842
+ }
843
+ interface CatalogDigInInsightArtist {
844
+ artist: string;
845
+ playlistListeners: number;
846
+ playlistStreams: number;
847
+ catalogListeners: number;
848
+ catalogStreams: number;
849
+ catalogTracks: number;
850
+ /** catalogListeners / playlistListeners. Null when playlistListeners is 0. */
851
+ catalogListenerRate: number | null;
852
+ }
853
+ interface CatalogDigInListeningInsight {
854
+ soundlinkId: string;
855
+ campaignId: string | null;
856
+ insight: 'catalog-dig-in';
857
+ window: ListeningInsightWindow;
858
+ artists: CatalogDigInInsightArtist[];
859
+ }
860
+ type StreamSplitEngagementContext = 'promoted' | 'playlist' | 'artist_catalog';
861
+ interface StreamSplitContext {
862
+ engagementContext: StreamSplitEngagementContext;
863
+ listeners: number;
864
+ streams: number;
865
+ tracks: number;
866
+ }
867
+ interface StreamSplitListeningInsight {
868
+ soundlinkId: string;
869
+ campaignId: string | null;
870
+ insight: 'stream-split';
871
+ window: ListeningInsightWindow;
872
+ contexts: StreamSplitContext[];
873
+ }
874
+ /** Discriminated on `insight`. */
875
+ type ListeningInsightsData = OtherArtistsListeningInsight | CatalogDigInListeningInsight | StreamSplitListeningInsight;
876
+
877
+ export type { CreativeDailyParams as $, ApiResponse as A, BreakdownExportParams as B, CampaignStatus as C, DateRangeParams as D, ExportCollection as E, EngagementExportParams as F, SoundlinkEngagementListParams as G, SoundlinkEngagementListData as H, IdempotencyOptions as I, JsonlStream as J, SoundlinkListParams as K, ListeningInsight as L, MetricsOverview as M, SoundlinkListData as N, SoundlinkDetail as O, PingData as P, CreateSoundlinkRequest as Q, SoundlinkMetricsOverview as R, StrategyType as S, CohortRetentionListData as T, UpdatePixelRequest as U, BreakdownRow as V, WalletData as W, BreakdownListParams as X, BreakdownListData as Y, EngagementRow as Z, CreativeMetrics as _, SoundlinkOptions as a, CreativeDailyData as a0, ApiError as a1, ApiMeta as a2, BudgetDecreaseMode as a3, BudgetIncreaseMode as a4, BuiltInStrategyType as a5, CampaignActivityItem as a6, CampaignGeneration as a7, CampaignSortBy as a8, CampaignSummary as a9, SoundlinkClientOptions as aA, SoundlinkEngagementSortBy as aB, SoundlinkSortBy as aC, SoundlinkStatus as aD, SoundlinkSummary as aE, SoundlinkTargetType as aF, StrategyCatalogItem as aG, StreamSplitContext as aH, StreamSplitEngagementContext as aI, StreamSplitListeningInsight as aJ, TierLearningStatus as aK, TierStatusUpdateItem as aL, TierTargeting as aM, CampaignTier as aa, CatalogDigInInsightArtist as ab, CatalogDigInListeningInsight as ac, CohortRetentionDailyRow as ad, CreateCampaignRequestBase as ae, CreateCampaignRequestBuiltIn as af, CreateCampaignRequestCustom as ag, CreativeDailyRow as ah, CreativeDirection as ai, CreativeMetricsChild as aj, CreativeMetricsGroup as ak, CustomTier as al, DoItForMeCreativeDirection as am, EngagementContext as an, FullControlCreativeDirection as ao, Genre as ap, ListeningInsightWindow as aq, OtherArtistsInsightArtist as ar, OtherArtistsListeningInsight as as, Pagination as at, PixelPlatform as au, PixelStatus as av, PublicApiErrorCode as aw, SocialPlatform as ax, SortOrder as ay, SoundlinkBreakdownSortBy as az, StrategiesCatalogData as b, PixelListData as c, Pixel as d, PixelTestEventData as e, CampaignTiersData as f, UpdateCampaignTiersRequest as g, CampaignListParams as h, CampaignListData as i, CampaignDetail as j, CampaignActivityParams as k, CampaignActivityData as l, ListeningInsightsData as m, CreateCampaignRequest as n, CampaignCreateData as o, CampaignStopData as p, IncreaseCampaignBudgetRequest as q, IncreaseCampaignBudgetData as r, DecreaseCampaignBudgetRequest as s, DecreaseCampaignBudgetData as t, UpdateCampaignAutoRenewRequest as u, CampaignAutoRenewData as v, SoundlinkBreakdownRow as w, SoundlinkBreakdownListParams as x, SoundlinkBreakdownListData as y, SoundlinkEngagementRow as z };