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.
@@ -1,865 +1,5 @@
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' | '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
- /** Body for `POST /v1/soundlinks`. */
606
- interface CreateSoundlinkRequest {
607
- name: string;
608
- /** HTTPS Spotify track or playlist URL. */
609
- spotifyUrl: string;
610
- autoFollow?: boolean;
611
- /** Spotify artist ID for auto-follow on track links. Ignored for playlists. */
612
- artistIdFollow?: string;
613
- /**
614
- * Meta pixel ID. Alone: reuse a pixel already saved via `pixels`.
615
- * With `metaConversionAccessToken`: save or rotate. Never applies an org default.
616
- */
617
- metaPixelId?: string;
618
- /**
619
- * Meta Conversions API token. Write-only: accepted on create, never returned.
620
- * Requires `metaPixelId`.
621
- */
622
- metaConversionAccessToken?: string;
623
- /**
624
- * Optional HTTPS Apple Music song or playlist URL. The API checks URL shape
625
- * only and stores an album share-sheet link (`?i=`) as the canonical song URL.
626
- */
627
- appleMusicUrl?: string;
628
- /**
629
- * Optional HTTPS YouTube Music song or playlist URL. A missing video or
630
- * playlist returns `400 invalid_request`.
631
- */
632
- youtubeMusicUrl?: string;
633
- /**
634
- * When `false`, the landing page skips Spotify login and only tracks the
635
- * landing-page click. Defaults to `true`. Cannot combine with `autoFollow: true`.
636
- */
637
- attributionEnabled?: boolean;
638
- }
639
- /** Paginated soundlink list payload. */
640
- interface SoundlinkListData {
641
- items: SoundlinkSummary[];
642
- pagination: Pagination;
643
- }
644
- /**
645
- * Soundlink-level metric totals from {@link SoundlinksResource.metricsOverview}.
646
- *
647
- * No financial fields — ads for self-serve soundlinks run in the customer's Meta.
648
- */
649
- interface SoundlinkMetricsOverview {
650
- views: number;
651
- link_clicks: number | null;
652
- streams: number;
653
- listeners: number;
654
- followers: number;
655
- streams_per_listener: number;
656
- ctr_lp: number | null;
657
- }
658
- /** One row of the `soundlink_country_daily` v1.0 schema. */
659
- interface SoundlinkBreakdownRow {
660
- provider: 'soundlink';
661
- account_id: string;
662
- schema_version: string;
663
- /** UTC calendar date (`YYYY-MM-DD`). */
664
- report_date: string;
665
- report_date_timezone: 'UTC';
666
- exported_at: string;
667
- soundlink_id: string;
668
- soundlink_name: string;
669
- soundlink_target_type: 'track' | 'playlist' | null;
670
- soundlink_target_isrc: string | null;
671
- soundlink_target_spotify_track_id: string | null;
672
- soundlink_target_playlist_id: string | null;
673
- country_code: string;
674
- views: number;
675
- link_clicks: number | null;
676
- spotify_link_clicks: number;
677
- apple_music_link_clicks: number;
678
- youtube_music_link_clicks: number;
679
- streams: number;
680
- listeners: number;
681
- new_listeners: number | null;
682
- returning_listeners: number | null;
683
- new_listener_streams: number | null;
684
- returning_listener_streams: number | null;
685
- followers: number;
686
- streams_per_listener: number;
687
- ctr_lp: number | null;
688
- }
689
- /** Paginated soundlink breakdown list payload. */
690
- interface SoundlinkBreakdownListData {
691
- schemaVersion: string;
692
- items: SoundlinkBreakdownRow[];
693
- pagination: Pagination;
694
- }
695
- /** One row of the `soundlink_engagement_daily` v1.0 schema. */
696
- interface SoundlinkEngagementRow {
697
- provider: 'soundlink';
698
- account_id: string;
699
- schema_version: string;
700
- report_date: string;
701
- report_date_timezone: 'UTC';
702
- exported_at: string;
703
- soundlink_id: string;
704
- soundlink_name: string;
705
- soundlink_target_type: 'track' | 'playlist' | null;
706
- soundlink_target_isrc: string | null;
707
- soundlink_target_spotify_track_id: string | null;
708
- soundlink_target_playlist_id: string | null;
709
- engagement_context: EngagementContext;
710
- country_code: string;
711
- engaged_track_isrc: string | null;
712
- engaged_spotify_track_id: string;
713
- engaged_track_name: string;
714
- playlist_position: number | null;
715
- new_listeners: number;
716
- returning_listeners: number;
717
- listeners: number;
718
- new_listener_streams: number;
719
- returning_listener_streams: number;
720
- streams: number;
721
- spl: number;
722
- }
723
- /** Paginated soundlink engagement list payload. */
724
- interface SoundlinkEngagementListData {
725
- schemaVersion: string;
726
- items: SoundlinkEngagementRow[];
727
- pagination: Pagination;
728
- }
729
- /** Query params for {@link SoundlinkBreakdownMetricsResource.list}. */
730
- interface SoundlinkBreakdownListParams extends DateRangeParams {
731
- page?: number;
732
- /** Default: `50`. Max: **500**. */
733
- pageSize?: number;
734
- /** Default: `report_date`. */
735
- sortBy?: SoundlinkBreakdownSortBy;
736
- /** Default: `asc`. */
737
- sortOrder?: SortOrder;
738
- }
739
- /**
740
- * Query params for {@link SoundlinkEngagementMetricsResource.list}.
741
- *
742
- * Defaults to the last 90 days ending today; max **90 days** per request.
743
- */
744
- interface SoundlinkEngagementListParams extends DateRangeParams {
745
- page?: number;
746
- /** Default: `50`. Max: **500**. */
747
- pageSize?: number;
748
- /** Filter to a single engagement context. Omit to return both. */
749
- engagementContext?: EngagementContext;
750
- /** Default: `report_date`. */
751
- sortBy?: SoundlinkEngagementSortBy;
752
- /** Default: `asc`. */
753
- sortOrder?: SortOrder;
754
- }
755
- /** Query params for {@link BreakdownMetricsResource.list}. */
756
- interface BreakdownListParams extends DateRangeParams {
757
- page?: number;
758
- /** Default: `50`. Max: **500**. */
759
- pageSize?: number;
760
- /** Default: `report_date`. */
761
- sortBy?: BreakdownSortBy;
762
- /** Default: `asc`. */
763
- sortOrder?: SortOrder;
764
- }
765
- /** Query params for engagement JSONL export. */
766
- interface EngagementExportParams extends DateRangeParams {
767
- engagementContext?: EngagementContext;
768
- }
769
- /** Query params for breakdown JSONL export. Max **90 days** per request. */
770
- type BreakdownExportParams = DateRangeParams;
771
- /**
772
- * One row of the `soundlink_cohort_retention_daily` v1.0 schema.
773
- * Day-N fields are `null` until that day has passed for the cohort date.
774
- */
775
- interface CohortRetentionDailyRow {
776
- provider: 'soundlink';
777
- account_id: string;
778
- schema_version: string;
779
- /** UTC calendar date (`YYYY-MM-DD`). */
780
- cohort_date: string;
781
- cohort_date_timezone: 'UTC';
782
- exported_at: string;
783
- soundlink_id: string;
784
- soundlink_name: string;
785
- soundlink_target_type: 'track' | 'playlist' | null;
786
- soundlink_target_isrc?: string | null;
787
- soundlink_target_spotify_track_id?: string | null;
788
- soundlink_target_playlist_id?: string | null;
789
- cohort_size: number;
790
- returned_on_day_1: number | null;
791
- retention_by_day_1: number | null;
792
- returned_on_day_2: number | null;
793
- retention_by_day_2: number | null;
794
- returned_on_day_3: number | null;
795
- retention_by_day_3: number | null;
796
- returned_on_day_4: number | null;
797
- retention_by_day_4: number | null;
798
- returned_on_day_5: number | null;
799
- retention_by_day_5: number | null;
800
- returned_on_day_6: number | null;
801
- retention_by_day_6: number | null;
802
- returned_on_day_7: number | null;
803
- retention_by_day_7: number | null;
804
- }
805
- /** Payload from campaign/soundlink `metrics/retention`. */
806
- interface CohortRetentionListData {
807
- schemaVersion: string;
808
- items: CohortRetentionDailyRow[];
809
- }
810
- /** Path param for listening-insights endpoints. */
811
- type ListeningInsight = 'other-artists' | 'catalog-dig-in' | 'stream-split';
812
- /** Date window returned with every listening insight (from the listening graph). */
813
- interface ListeningInsightWindow {
814
- startDate: string;
815
- endDate: string;
816
- }
817
- interface OtherArtistsInsightArtist {
818
- /** Lowercased, trimmed artist name. */
819
- artist: string;
820
- listeners: number;
821
- streams: number;
822
- }
823
- interface OtherArtistsListeningInsight {
824
- soundlinkId: string;
825
- campaignId: string | null;
826
- insight: 'other-artists';
827
- window: ListeningInsightWindow;
828
- artists: OtherArtistsInsightArtist[];
829
- }
830
- interface CatalogDigInInsightArtist {
831
- artist: string;
832
- playlistListeners: number;
833
- playlistStreams: number;
834
- catalogListeners: number;
835
- catalogStreams: number;
836
- catalogTracks: number;
837
- /** catalogListeners / playlistListeners. Null when playlistListeners is 0. */
838
- catalogListenerRate: number | null;
839
- }
840
- interface CatalogDigInListeningInsight {
841
- soundlinkId: string;
842
- campaignId: string | null;
843
- insight: 'catalog-dig-in';
844
- window: ListeningInsightWindow;
845
- artists: CatalogDigInInsightArtist[];
846
- }
847
- type StreamSplitEngagementContext = 'promoted' | 'playlist' | 'artist_catalog';
848
- interface StreamSplitContext {
849
- engagementContext: StreamSplitEngagementContext;
850
- listeners: number;
851
- streams: number;
852
- tracks: number;
853
- }
854
- interface StreamSplitListeningInsight {
855
- soundlinkId: string;
856
- campaignId: string | null;
857
- insight: 'stream-split';
858
- window: ListeningInsightWindow;
859
- contexts: StreamSplitContext[];
860
- }
861
- /** Discriminated on `insight`. */
862
- type ListeningInsightsData = OtherArtistsListeningInsight | CatalogDigInListeningInsight | StreamSplitListeningInsight;
1
+ import { a as SoundlinkOptions, A as ApiResponse, J as JsonlStream, D as DateRangeParams, E as ExportCollection, P as PingData, W as WalletData, b as StrategiesCatalogData, c as PixelListData, U as UpdatePixelRequest, d as Pixel, e as PixelTestEventData, f as CampaignTiersData, g as UpdateCampaignTiersRequest, h as CampaignListParams, i as CampaignListData, j as CampaignDetail, k as CampaignActivityParams, l as CampaignActivityData, L as ListeningInsight, m as ListeningInsightsData, n as CreateCampaignRequest, I as IdempotencyOptions, o as CampaignCreateData, p as CampaignStopData, q as IncreaseCampaignBudgetRequest, r as IncreaseCampaignBudgetData, s as DecreaseCampaignBudgetRequest, t as DecreaseCampaignBudgetData, u as UpdateCampaignAutoRenewRequest, v as CampaignAutoRenewData, w as SoundlinkBreakdownRow, B as BreakdownExportParams, x as SoundlinkBreakdownListParams, y as SoundlinkBreakdownListData, z as SoundlinkEngagementRow, F as EngagementExportParams, G as SoundlinkEngagementListParams, H as SoundlinkEngagementListData, K as SoundlinkListParams, N as SoundlinkListData, O as SoundlinkDetail, Q as CreateSoundlinkRequest, R as SoundlinkMetricsOverview, T as CohortRetentionListData, V as BreakdownRow, X as BreakdownListParams, Y as BreakdownListData, Z as EngagementRow, M as MetricsOverview, _ as CreativeMetrics, $ as CreativeDailyParams, a0 as CreativeDailyData } from './api-C7t2QZ2d.js';
2
+ export { a1 as ApiError, a2 as ApiMeta, a3 as BudgetDecreaseMode, a4 as BudgetIncreaseMode, a5 as BuiltInStrategyType, a6 as CampaignActivityItem, a7 as CampaignGeneration, a8 as CampaignSortBy, C as CampaignStatus, a9 as CampaignSummary, aa as CampaignTier, ab as CatalogDigInInsightArtist, ac as CatalogDigInListeningInsight, ad as CohortRetentionDailyRow, ae as CreateCampaignRequestBase, af as CreateCampaignRequestBuiltIn, ag as CreateCampaignRequestCustom, ah as CreativeDailyRow, ai as CreativeDirection, aj as CreativeMetricsChild, ak as CreativeMetricsGroup, al as CustomTier, am as DoItForMeCreativeDirection, an as EngagementContext, ao as FullControlCreativeDirection, ap as Genre, aq as ListeningInsightWindow, ar as OtherArtistsInsightArtist, as as OtherArtistsListeningInsight, at as Pagination, au as PixelPlatform, av as PixelStatus, aw as PublicApiErrorCode, ax as SocialPlatform, ay as SortOrder, az as SoundlinkBreakdownSortBy, aA as SoundlinkClientOptions, aB as SoundlinkEngagementSortBy, aC as SoundlinkSortBy, aD as SoundlinkStatus, aE as SoundlinkSummary, aF as SoundlinkTargetType, aG as StrategyCatalogItem, S as StrategyType, aH as StreamSplitContext, aI as StreamSplitEngagementContext, aJ as StreamSplitListeningInsight, aK as TierLearningStatus, aL as TierStatusUpdateItem, aM as TierTargeting } from './api-C7t2QZ2d.js';
863
3
 
864
4
  interface HttpGetOptions {
865
5
  path: string;
@@ -1499,4 +639,4 @@ declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
1499
639
  declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
1500
640
  declare const METRICS_MAX_PAGE_SIZE = 500;
1501
641
 
1502
- 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 CatalogDigInInsightArtist, type CatalogDigInListeningInsight, type CohortRetentionDailyRow, type CohortRetentionListData, 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, LISTENING_INSIGHTS_TIMEOUT_MS, type ListeningInsight, type ListeningInsightWindow, type ListeningInsightsData, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type OtherArtistsInsightArtist, type OtherArtistsListeningInsight, type Pagination, type PingData, type Pixel, type PixelListData, type PixelPlatform, type PixelStatus, type PixelTestEventData, 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 StreamSplitContext, type StreamSplitEngagementContext, type StreamSplitListeningInsight, type TierLearningStatus, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignAutoRenewRequest, type UpdateCampaignTiersRequest, type UpdatePixelRequest, type WalletData, getStreamRowCount, resolveClientOptions };
642
+ export { API_KEY_PREFIX, ApiResponse, BreakdownExportParams, BreakdownListData, BreakdownListParams, BreakdownRow, CAMPAIGNS_MAX_PAGE_SIZE, CampaignActivityData, CampaignActivityParams, CampaignAutoRenewData, CampaignCreateData, CampaignDetail, CampaignListData, CampaignListParams, CampaignStopData, CampaignTiersData, CohortRetentionListData, CreateCampaignRequest, CreateSoundlinkRequest, CreativeDailyData, CreativeDailyParams, CreativeMetrics, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DateRangeParams, DecreaseCampaignBudgetData, DecreaseCampaignBudgetRequest, EngagementExportParams, EngagementRow, ExportCollection, type ExportResource, HttpClient, IdempotencyOptions, IncreaseCampaignBudgetData, IncreaseCampaignBudgetRequest, JsonlStream, LISTENING_INSIGHTS_TIMEOUT_MS, ListeningInsight, ListeningInsightsData, METRICS_MAX_PAGE_SIZE, MetricsOverview, PingData, Pixel, PixelListData, PixelTestEventData, SOUNDLINKS_MAX_PAGE_SIZE, Soundlink, SoundlinkBreakdownListData, SoundlinkBreakdownListParams, SoundlinkBreakdownRow, SoundlinkConfigError, SoundlinkDetail, SoundlinkEngagementListData, SoundlinkEngagementListParams, SoundlinkEngagementRow, SoundlinkListData, SoundlinkListParams, SoundlinkMetricsOverview, SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, StrategiesCatalogData, UpdateCampaignAutoRenewRequest, UpdateCampaignTiersRequest, UpdatePixelRequest, WalletData, getStreamRowCount, resolveClientOptions };