soundlink 1.1.0 → 1.2.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,53 +1,246 @@
1
- type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | 'mixed_credentials' | 'insufficient_scope' | 'not_found' | 'campaign_not_found' | 'invalid_query_parameter' | 'invalid_date_range' | 'page_size_exceeded' | 'rate_limit_exceeded' | 'internal_error';
2
- type CampaignStatus = 'creating' | 'active' | 'paused' | 'completed' | 'failed';
1
+ /** Stable snake_case error codes returned by the Soundlink Public API. */
2
+ type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | 'mixed_credentials' | 'insufficient_scope' | 'not_found' | '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' | 'tier_update_cooldown' | 'wallet_not_enabled' | 'insufficient_credit' | 'idempotency_key_conflict' | 'rate_limit_exceeded' | 'invalid_video_url' | 'video_import_limit_exceeded' | 'video_import_session_not_found' | 'internal_error';
3
+ /**
4
+ * Campaign lifecycle status.
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';
10
+ /** Ad platform used by the campaign. */
3
11
  type SocialPlatform = 'meta';
12
+ /**
13
+ * Campaign resource generation.
14
+ *
15
+ * - `1` — Stripe / one-time / subscription / legacy
16
+ * - `2` — managed
17
+ * - `3` — wallet (writable via Public API)
18
+ */
19
+ type CampaignGeneration = 1 | 2 | 3;
20
+ /**
21
+ * Engagement context for per-track metrics.
22
+ *
23
+ * - `catalog` — same-artist spillover and promoted track plays.
24
+ * - `playlist` — per-track performance inside a promoted playlist.
25
+ */
4
26
  type EngagementContext = 'catalog' | 'playlist';
27
+ /** Allowed `sortBy` values for {@link CampaignListParams}. */
5
28
  type CampaignSortBy = 'createdAt' | 'status';
29
+ /** Allowed `sortBy` values for breakdown list requests. */
6
30
  type BreakdownSortBy = 'report_date' | 'spend_total';
7
- type EngagementSortBy = 'report_date' | 'streams' | 'listeners';
31
+ /** Sort direction for list endpoints. */
8
32
  type SortOrder = 'asc' | 'desc';
33
+ /** Growth strategy for campaign create / catalog. */
34
+ type StrategyType = 'maximum_growth' | 'market_discovery' | 'revenue_maximization' | 'custom';
35
+ /** Non-custom strategies (platform default tiering; no `tierTargeting`). */
36
+ type BuiltInStrategyType = Exclude<StrategyType, 'custom'>;
37
+ /** Strictly validated genre list from the Public API. */
38
+ type Genre = 'Alternative/Indie' | 'Ambient/Sleep' | 'Chill/Background' | 'Classical' | 'Country' | 'Electronic/Dance' | 'Hip-Hop/R&B' | 'Latin/Reggaeton' | 'Pop' | 'Rock' | 'Christmas';
39
+ /** Budget increase mode for wallet campaigns. */
40
+ type BudgetIncreaseMode = 'current_cycle' | 'next_renewal' | 'current_and_renewals';
41
+ /** Budget decrease mode for wallet campaigns. */
42
+ type BudgetDecreaseMode = 'current_cycle' | 'current_and_renewals';
43
+ /** Options for write methods that require an `Idempotency-Key` header. */
44
+ interface IdempotencyOptions {
45
+ /** Client-generated key; reused retries must send the same body. */
46
+ idempotencyKey: string;
47
+ }
48
+ /** Server-generated request metadata. Include `requestId` when contacting Soundlink support. */
9
49
  interface ApiMeta {
50
+ /** UUID for this API request. */
10
51
  requestId: string;
11
52
  }
53
+ /** API error returned in `{ data: null, error }` — never thrown by SDK methods. */
12
54
  interface ApiError {
55
+ /** Stable error code from the Public API. */
13
56
  code: PublicApiErrorCode;
57
+ /** Human-readable description. Do not parse programmatically. */
14
58
  message: string;
59
+ /** HTTP status code. */
15
60
  status: number;
61
+ /** Same as `meta.requestId` when present. */
16
62
  requestId?: string;
63
+ /** Seconds to wait before retrying, from the `Retry-After` header on `429`. */
17
64
  retryAfter?: number;
18
- }
65
+ /**
66
+ * Error-code-specific context from the API (e.g. `available` / `required` on
67
+ * `insufficient_credit`). Absent when the API sends no `details`.
68
+ */
69
+ details?: Record<string, unknown> | null;
70
+ }
71
+ /**
72
+ * Standard SDK response shape for every Public API method.
73
+ *
74
+ * @typeParam T - Success payload type. `null` when `error` is set.
75
+ */
19
76
  interface ApiResponse<T> {
77
+ /** Success payload, or `null` when the API returned an error. */
20
78
  data: T | null;
79
+ /** API error details, or `null` on success. */
21
80
  error: ApiError | null;
81
+ /** Request metadata (always present on successful envelope responses). */
22
82
  meta?: ApiMeta;
23
83
  }
84
+ /** Pagination metadata included in list responses. */
24
85
  interface Pagination {
86
+ /** Current page (1-indexed). */
25
87
  page: number;
88
+ /** Items per page. */
26
89
  pageSize: number;
90
+ /** Total items across all pages. */
27
91
  totalCount: number;
92
+ /** Total number of pages. */
28
93
  totalPages: number;
29
94
  }
95
+ /** Campaign summary returned by {@link CampaignsResource.list}. */
30
96
  interface CampaignSummary {
31
97
  campaignId: string;
32
98
  organizationId: string;
33
99
  status: CampaignStatus;
34
100
  socialPlatform: SocialPlatform;
101
+ /** Daily budget in USD. */
35
102
  dailyBudget: number;
103
+ /** Total budget in USD. */
36
104
  totalBudget: number;
105
+ /** Campaign duration in days. */
37
106
  campaignDuration: number;
107
+ /** Resource generation — writable Public API methods require `3`. */
108
+ generation: CampaignGeneration;
109
+ /** ISO 8601 creation timestamp. */
38
110
  createdAt: string;
111
+ /** ISO 8601 last update timestamp. */
39
112
  updatedAt: string;
40
113
  }
114
+ /** Full campaign detail from {@link CampaignsResource.get}. */
41
115
  interface CampaignDetail extends CampaignSummary {
42
- strategyType?: string;
116
+ /** Growth strategy set at creation (e.g. `custom`, `maximum_growth`). */
117
+ strategyType?: StrategyType;
43
118
  }
119
+ /** Paginated campaign list payload. */
44
120
  interface CampaignListData {
45
121
  items: CampaignSummary[];
46
122
  pagination: Pagination;
47
123
  }
124
+ /** Successful `GET /v1/ping` payload. */
48
125
  interface PingData {
49
126
  status: 'ok';
50
127
  }
128
+ /** One entry from `GET /v1/strategies`. */
129
+ interface StrategyCatalogItem {
130
+ strategyType: StrategyType;
131
+ /** When `false`, omit `tierTargeting` on create. */
132
+ tierTargetingAllowed: boolean;
133
+ }
134
+ /** Payload from `GET /v1/strategies`. */
135
+ interface StrategiesCatalogData {
136
+ strategies: StrategyCatalogItem[];
137
+ }
138
+ /** Shared fields for wallet campaign create. */
139
+ interface CreateCampaignRequestBase {
140
+ /** Spotify track or playlist URL. */
141
+ spotifyUrl: string;
142
+ /** USD per day (minimum 10). */
143
+ dailyBudget: number;
144
+ /** Duration in days: 7–30, or 60, or 90. */
145
+ durationDays: number;
146
+ genre: Genre;
147
+ /** Optional; server generates a default when omitted. */
148
+ campaignName?: string;
149
+ creativeDirection?: CreativeDirection;
150
+ trackOptions?: {
151
+ artistIdFollow?: string;
152
+ };
153
+ /** Lineage only — does not copy settings from the source campaign. */
154
+ clonedFromCampaignId?: string;
155
+ }
156
+ interface DoItForMeCreativeDirection {
157
+ type: 'do_it_for_me';
158
+ }
159
+ interface FullControlCreativeDirection {
160
+ type: 'full_control';
161
+ selectedCreatives: Array<{
162
+ videoId: string;
163
+ }>;
164
+ }
165
+ type CreativeDirection = DoItForMeCreativeDirection | FullControlCreativeDirection;
166
+ interface CustomTier {
167
+ name: string;
168
+ percentBudget: number;
169
+ countries?: string[];
170
+ language?: string;
171
+ }
172
+ interface TierTargeting {
173
+ customTierIds?: number[];
174
+ customTiers?: CustomTier[];
175
+ }
176
+ /** Create with a built-in strategy (no `tierTargeting`). */
177
+ interface CreateCampaignRequestBuiltIn extends CreateCampaignRequestBase {
178
+ strategyType: BuiltInStrategyType;
179
+ tierTargeting?: never;
180
+ }
181
+ /** Create with `custom` strategy (requires `tierTargeting`). */
182
+ interface CreateCampaignRequestCustom extends CreateCampaignRequestBase {
183
+ strategyType: 'custom';
184
+ tierTargeting: TierTargeting;
185
+ }
186
+ /** Body for `POST /v1/campaigns`. */
187
+ type CreateCampaignRequest = CreateCampaignRequestBuiltIn | CreateCampaignRequestCustom;
188
+ /** Success payload from campaign create. */
189
+ interface CampaignCreateData {
190
+ campaignId: string;
191
+ status: CampaignStatus;
192
+ }
193
+ /** Success payload from campaign stop. */
194
+ interface CampaignStopData {
195
+ campaignId: string;
196
+ status: CampaignStatus;
197
+ }
198
+ interface IncreaseCampaignBudgetRequest {
199
+ amount: number;
200
+ mode?: BudgetIncreaseMode;
201
+ targetDailyBudget?: number;
202
+ }
203
+ interface IncreaseCampaignBudgetData {
204
+ campaignId: string;
205
+ mode: BudgetIncreaseMode;
206
+ amount: number;
207
+ walletBalance: number;
208
+ walletNextCycleDailyBudget?: number | null;
209
+ }
210
+ interface DecreaseCampaignBudgetRequest {
211
+ targetDailyBudget: number;
212
+ mode?: BudgetDecreaseMode;
213
+ }
214
+ interface DecreaseCampaignBudgetData {
215
+ campaignId: string;
216
+ mode: BudgetDecreaseMode;
217
+ targetDailyBudget: number;
218
+ accepted: true;
219
+ walletNextCycleDailyBudget?: number | null;
220
+ }
221
+ interface CampaignTier {
222
+ tierId: number;
223
+ tierName: string;
224
+ isEnabled: boolean;
225
+ allocationPercent: number;
226
+ }
227
+ interface CampaignTiersData {
228
+ lastUpdate: string | null;
229
+ tiers: CampaignTier[];
230
+ }
231
+ interface TierStatusUpdateItem {
232
+ /**
233
+ * Targeting tier id — same value as `tierId` returned by
234
+ * `campaigns.tiers.get` (`CampaignTier.tierId`).
235
+ */
236
+ targetingTierId: number;
237
+ isEnabled: boolean;
238
+ newAllocationPercent: number;
239
+ }
240
+ interface UpdateCampaignTiersRequest {
241
+ items: TierStatusUpdateItem[];
242
+ }
243
+ /** Campaign-level metric totals from {@link MetricsResource.overview}. */
51
244
  interface MetricsOverview {
52
245
  listeners: number;
53
246
  streams: number;
@@ -55,18 +248,25 @@ interface MetricsOverview {
55
248
  impressions: number | null;
56
249
  ad_clicks: number | null;
57
250
  link_clicks: number | null;
251
+ /** Meta ad spend excluding Soundlink fees (USD). */
58
252
  spend_media: number;
253
+ /** Total billed amount including fees (USD). */
59
254
  spend_total: number;
255
+ /** Soundlink service fee (USD). */
60
256
  fees: number;
61
257
  currency: string;
258
+ /** Cost per listener. */
62
259
  cpl: number;
260
+ /** Cost per follower. */
63
261
  cpf: number;
64
262
  streams_per_listener: number;
65
263
  }
264
+ /** One row of the `campaign_country_daily` v1.0 schema. */
66
265
  interface BreakdownRow {
67
266
  provider: 'soundlink';
68
267
  account_id: string;
69
268
  schema_version: string;
269
+ /** UTC calendar date (`YYYY-MM-DD`). */
70
270
  report_date: string;
71
271
  report_date_timezone: 'UTC';
72
272
  exported_at: string;
@@ -97,6 +297,7 @@ interface BreakdownRow {
97
297
  cost_per_result: number;
98
298
  result_type: 'lp_click' | 'stream' | 'follow' | null;
99
299
  }
300
+ /** One row of the `campaign_engagement_daily` v1.0 schema. */
100
301
  interface EngagementRow {
101
302
  provider: 'soundlink';
102
303
  account_id: string;
@@ -125,57 +326,71 @@ interface EngagementRow {
125
326
  streams: number;
126
327
  spl: number;
127
328
  }
329
+ /** Paginated breakdown list payload. */
128
330
  interface BreakdownListData {
129
331
  schemaVersion: string;
130
332
  items: BreakdownRow[];
131
333
  pagination: Pagination;
132
334
  }
133
- interface EngagementListData {
134
- schemaVersion: string;
135
- items: EngagementRow[];
136
- pagination: Pagination;
137
- }
335
+ /** In-memory result from {@link ExportResource.collect}. */
138
336
  interface ExportCollection<T> {
139
337
  rows: T[];
338
+ /** Same as `rows.length`. */
140
339
  rowCount: number;
141
340
  }
341
+ /** Async iterable JSONL stream from export endpoints. May include `rowCount` from `X-Row-Count`. */
142
342
  interface JsonlStream<T> extends AsyncIterable<T> {
343
+ /** Total rows when the API sent the `X-Row-Count` header. */
143
344
  rowCount?: number;
144
345
  }
346
+ /** Options for {@link Soundlink} and {@link HttpClient}. */
145
347
  interface SoundlinkClientOptions {
348
+ /** Soundlink API key (`sk_<prefix>_<secret>`). Sent as the `x-api-key` header. */
146
349
  apiKey: string;
350
+ /** API base URL. Defaults to `https://api.getsoundlink.com`. */
147
351
  baseUrl?: string;
352
+ /** Request timeout in milliseconds. Default: `30000`. */
148
353
  timeout?: number;
354
+ /** Retries on `429` and `5xx`. Default: `2`. */
149
355
  maxRetries?: number;
356
+ /** Custom `fetch` implementation (tests, Edge runtimes). */
150
357
  fetch?: typeof fetch;
151
358
  }
359
+ /** API key string or full options object. */
152
360
  type SoundlinkOptions = SoundlinkClientOptions | string;
361
+ /** Query params for {@link CampaignsResource.list}. */
153
362
  interface CampaignListParams {
363
+ /** Page number (1-indexed). Default: `1`. */
154
364
  page?: number;
365
+ /** Items per page. Default: `10`. Max: **100**. */
155
366
  pageSize?: number;
367
+ /** Sort field. Default: `createdAt`. */
156
368
  sortBy?: CampaignSortBy;
369
+ /** Sort direction. Default: `desc`. */
157
370
  sortOrder?: SortOrder;
158
371
  }
372
+ /** Inclusive date range filter (`YYYY-MM-DD`). */
159
373
  interface DateRangeParams {
374
+ /** Inclusive start date. */
160
375
  startDate?: string;
376
+ /** Inclusive end date. Must not be before `startDate`. */
161
377
  endDate?: string;
162
378
  }
379
+ /** Query params for {@link BreakdownMetricsResource.list}. */
163
380
  interface BreakdownListParams extends DateRangeParams {
164
381
  page?: number;
382
+ /** Default: `50`. Max: **500**. */
165
383
  pageSize?: number;
384
+ /** Default: `report_date`. */
166
385
  sortBy?: BreakdownSortBy;
386
+ /** Default: `asc`. */
167
387
  sortOrder?: SortOrder;
168
388
  }
169
- interface EngagementListParams extends DateRangeParams {
170
- page?: number;
171
- pageSize?: number;
172
- sortBy?: EngagementSortBy;
173
- sortOrder?: SortOrder;
174
- engagementContext?: EngagementContext;
175
- }
389
+ /** Query params for engagement JSONL export. */
176
390
  interface EngagementExportParams extends DateRangeParams {
177
391
  engagementContext?: EngagementContext;
178
392
  }
393
+ /** Query params for breakdown JSONL export. Max **90 days** per request. */
179
394
  type BreakdownExportParams = DateRangeParams;
180
395
 
181
396
  interface HttpGetOptions {
@@ -185,6 +400,14 @@ interface HttpGetOptions {
185
400
  interface HttpJsonlOptions extends HttpGetOptions {
186
401
  accept?: string;
187
402
  }
403
+ interface HttpMutationOptions {
404
+ path: string;
405
+ body?: unknown;
406
+ query?: Record<string, string | number | boolean | undefined | null>;
407
+ headers?: Record<string, string>;
408
+ /** Sent as the `Idempotency-Key` header when set. */
409
+ idempotencyKey?: string;
410
+ }
188
411
  interface ResolvedSoundlinkClientOptions {
189
412
  apiKey: string;
190
413
  baseUrl: string;
@@ -192,69 +415,326 @@ interface ResolvedSoundlinkClientOptions {
192
415
  maxRetries: number;
193
416
  fetch: typeof fetch;
194
417
  }
418
+ /**
419
+ * Normalize constructor options and validate the API key format.
420
+ *
421
+ * @throws {@link SoundlinkConfigError} When the key is missing or does not start with `sk_`.
422
+ */
195
423
  declare function resolveClientOptions(options: SoundlinkOptions): ResolvedSoundlinkClientOptions;
196
424
  declare class HttpClient {
197
425
  private readonly options;
198
426
  constructor(options: SoundlinkOptions);
199
427
  get resolvedOptions(): ResolvedSoundlinkClientOptions;
200
428
  get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
429
+ post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
430
+ patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
201
431
  getJsonl<T>({ path, query, accept, }: HttpJsonlOptions): Promise<ApiResponse<JsonlStream<T>>>;
432
+ private mutateJson;
202
433
  private buildHeaders;
203
434
  private requestJson;
204
435
  private parseErrorEnvelope;
205
436
  private fetchWithRetry;
206
437
  }
438
+ /**
439
+ * Read `rowCount` from a {@link JsonlStream} when the API sent `X-Row-Count`.
440
+ *
441
+ * @returns Row count, or `undefined` if not available.
442
+ */
207
443
  declare function getStreamRowCount<T>(stream: AsyncIterable<T>): number | undefined;
208
444
 
445
+ /**
446
+ * JSONL export endpoint: stream rows with {@link ExportResource.collect} or iterate the stream directly.
447
+ *
448
+ * @example
449
+ * ```ts
450
+ * const { data: stream } = await soundlink.metrics.breakdown.export(campaignId);
451
+ * for await (const row of stream!) { ... }
452
+ *
453
+ * const { data } = await soundlink.metrics.breakdown.export.collect(campaignId);
454
+ * ```
455
+ */
209
456
  interface ExportResource<T, P extends DateRangeParams> {
457
+ /**
458
+ * Stream export rows as newline-delimited JSON.
459
+ *
460
+ * @param campaignId - Soundlink campaign ID.
461
+ * @param params - Optional date range (max 90 days per request).
462
+ */
210
463
  (campaignId: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
464
+ /**
465
+ * Download all export rows into memory.
466
+ *
467
+ * Prefer {@link ExportResource | the stream} for large datasets.
468
+ */
211
469
  collect(campaignId: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
212
470
  }
471
+ /** System endpoints (`GET /v1/ping`). */
213
472
  declare class PingResource {
214
473
  private readonly http;
215
474
  constructor(http: HttpClient);
475
+ /**
476
+ * Verify connectivity and API key authentication.
477
+ *
478
+ * Accepts any valid v1 key scope. Does not require `campaigns:read` or `metrics:read`.
479
+ *
480
+ * @returns `{ data: { status: 'ok' }, error: null }` on success.
481
+ *
482
+ * @example
483
+ * ```ts
484
+ * const { data, error, meta } = await soundlink.ping();
485
+ * ```
486
+ */
216
487
  ping(): Promise<ApiResponse<PingData>>;
217
488
  }
489
+ /** Strategy catalog (`GET /v1/strategies`). Requires `campaigns:read`. */
490
+ declare class StrategiesResource {
491
+ private readonly http;
492
+ constructor(http: HttpClient);
493
+ /**
494
+ * List growth strategies available for wallet campaign create.
495
+ *
496
+ * Maps to `GET /v1/strategies`.
497
+ *
498
+ * @example
499
+ * ```ts
500
+ * const { data } = await soundlink.strategies.list();
501
+ * ```
502
+ */
503
+ list(): Promise<ApiResponse<StrategiesCatalogData>>;
504
+ }
505
+ /** Campaign tiers (`/v1/campaigns/{id}/tiers`). Wallet only (`generation: 3`). */
506
+ declare class CampaignTiersResource {
507
+ private readonly http;
508
+ constructor(http: HttpClient);
509
+ /**
510
+ * Get current tier allocation for a wallet campaign.
511
+ *
512
+ * Maps to `GET /v1/campaigns/{campaignId}/tiers`. Wallet campaigns only (`generation: 3`).
513
+ */
514
+ get(campaignId: string): Promise<ApiResponse<CampaignTiersData>>;
515
+ /**
516
+ * Update tier enablement and budget shares.
517
+ *
518
+ * Maps to `PATCH /v1/campaigns/{campaignId}/tiers`. Requires `campaigns:write`.
519
+ * Allocation percents across items must sum to 100.
520
+ * Use each tier's `tierId` from {@link CampaignTiersResource.get} as `targetingTierId`.
521
+ * Does not require an `Idempotency-Key` (unlike create / stop / budget).
522
+ */
523
+ update(campaignId: string, body: UpdateCampaignTiersRequest): Promise<ApiResponse<CampaignTiersData>>;
524
+ }
525
+ /** Campaign listing, detail, and wallet write surface (`/v1/campaigns/*`). */
218
526
  declare class CampaignsResource {
219
527
  private readonly http;
528
+ /** Tier allocation for wallet campaigns (`generation: 3`). */
529
+ readonly tiers: CampaignTiersResource;
220
530
  constructor(http: HttpClient);
531
+ /**
532
+ * List campaigns for the authenticated organization.
533
+ *
534
+ * Maps to `GET /v1/campaigns`. Max `pageSize` is **100**. Requires `campaigns:read`.
535
+ *
536
+ * @param params - Pagination and sort options.
537
+ *
538
+ * @example
539
+ * ```ts
540
+ * const { data, error } = await soundlink.campaigns.list({ page: 1, pageSize: 100 });
541
+ * ```
542
+ */
221
543
  list(params?: CampaignListParams): Promise<ApiResponse<CampaignListData>>;
544
+ /**
545
+ * Fetch full details for a single campaign.
546
+ *
547
+ * Maps to `GET /v1/campaigns/{campaignId}`. Requires `campaigns:read`.
548
+ *
549
+ * @param campaignId - Campaign identifier returned by {@link CampaignsResource.list}.
550
+ */
222
551
  get(campaignId: string): Promise<ApiResponse<CampaignDetail>>;
552
+ /**
553
+ * Create a wallet-funded campaign.
554
+ *
555
+ * Maps to `POST /v1/campaigns`. Requires `campaigns:write` and `Idempotency-Key`.
556
+ *
557
+ * @example
558
+ * ```ts
559
+ * const { data, error } = await soundlink.campaigns.create(
560
+ * {
561
+ * spotifyUrl: 'https://open.spotify.com/track/...',
562
+ * dailyBudget: 20,
563
+ * durationDays: 7,
564
+ * genre: 'Pop',
565
+ * strategyType: 'maximum_growth',
566
+ * },
567
+ * { idempotencyKey: 'create-mytrack-01' },
568
+ * );
569
+ * ```
570
+ */
571
+ create(body: CreateCampaignRequest, options: IdempotencyOptions): Promise<ApiResponse<CampaignCreateData>>;
572
+ /**
573
+ * Stop a wallet campaign and refund unspent budget.
574
+ *
575
+ * Maps to `POST /v1/campaigns/{campaignId}/stop`. Requires `campaigns:write`
576
+ * and `Idempotency-Key`. Wallet campaigns only (`generation: 3`).
577
+ */
578
+ stop(campaignId: string, options: IdempotencyOptions): Promise<ApiResponse<CampaignStopData>>;
579
+ /**
580
+ * Increase wallet campaign budget.
581
+ *
582
+ * Maps to `POST /v1/campaigns/{campaignId}/budget/increase`.
583
+ * Requires `campaigns:write` and `Idempotency-Key`. Wallet only (`generation: 3`).
584
+ */
585
+ increaseBudget(campaignId: string, body: IncreaseCampaignBudgetRequest, options: IdempotencyOptions): Promise<ApiResponse<IncreaseCampaignBudgetData>>;
586
+ /**
587
+ * Decrease wallet campaign daily budget.
588
+ *
589
+ * Maps to `POST /v1/campaigns/{campaignId}/budget/decrease`.
590
+ * Requires `campaigns:write` and `Idempotency-Key`. Wallet only (`generation: 3`).
591
+ */
592
+ decreaseBudget(campaignId: string, body: DecreaseCampaignBudgetRequest, options: IdempotencyOptions): Promise<ApiResponse<DecreaseCampaignBudgetData>>;
593
+ /**
594
+ * Async iterator over every campaign across all pages.
595
+ *
596
+ * Stops silently if a page request returns an error.
597
+ *
598
+ * @param params - Same as {@link CampaignsResource.list} except `page` is managed automatically.
599
+ *
600
+ * @example
601
+ * ```ts
602
+ * for await (const campaign of soundlink.campaigns.listAll({ pageSize: 100 })) {
603
+ * console.log(campaign.campaignId);
604
+ * }
605
+ * ```
606
+ */
223
607
  listAll(params?: Omit<CampaignListParams, 'page'>): AsyncGenerator<CampaignListData['items'][number], void, void>;
224
608
  }
609
+ /**
610
+ * Campaign metrics (`/v1/campaigns/{id}/metrics/*`). Requires `metrics:read`.
611
+ *
612
+ * @example
613
+ * ```ts
614
+ * await soundlink.metrics.overview(campaignId);
615
+ * await soundlink.metrics.breakdown.list(campaignId);
616
+ * await soundlink.metrics.engagement.export(campaignId);
617
+ * ```
618
+ */
225
619
  declare class MetricsResource {
226
620
  private readonly http;
621
+ /** Per-day country breakdown and JSONL export. */
227
622
  readonly breakdown: BreakdownMetricsResource;
623
+ /** Per-track engagement JSONL export. */
228
624
  readonly engagement: EngagementMetricsResource;
229
625
  constructor(http: HttpClient);
626
+ /**
627
+ * Campaign-level metric totals for a date range.
628
+ *
629
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/overview`.
630
+ * Aggregates across all countries — use {@link BreakdownMetricsResource.list} for daily rows.
631
+ *
632
+ * @param campaignId - Campaign identifier.
633
+ * @param params - Inclusive `YYYY-MM-DD` date range. Omit for API defaults.
634
+ *
635
+ * @example
636
+ * ```ts
637
+ * const { data } = await soundlink.metrics.overview(campaignId, {
638
+ * startDate: '2026-01-01',
639
+ * endDate: '2026-03-31',
640
+ * });
641
+ * ```
642
+ */
230
643
  overview(campaignId: string, params?: DateRangeParams): Promise<ApiResponse<MetricsOverview>>;
231
644
  }
645
+ /**
646
+ * Country-level daily metrics (`campaign_country_daily` schema).
647
+ *
648
+ * Access via `soundlink.metrics.breakdown`.
649
+ */
232
650
  declare class BreakdownMetricsResource {
233
651
  private readonly http;
652
+ /**
653
+ * Stream full breakdown export as JSONL.
654
+ *
655
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown/export`.
656
+ */
234
657
  readonly export: ExportResource<BreakdownRow, BreakdownExportParams>;
235
658
  constructor(http: HttpClient);
659
+ /**
660
+ * Paginated per-day, per-country breakdown rows.
661
+ *
662
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown`.
663
+ * Max `pageSize` is **500** (default 50).
664
+ *
665
+ * @param campaignId - Campaign identifier.
666
+ * @param params - Date range, pagination, and sort options.
667
+ */
236
668
  list(campaignId: string, params?: BreakdownListParams): Promise<ApiResponse<BreakdownListData>>;
237
669
  }
670
+ /**
671
+ * Per-track engagement metrics (`campaign_engagement_daily` schema).
672
+ *
673
+ * Access via `soundlink.metrics.engagement`. Only JSONL export is shipped.
674
+ */
238
675
  declare class EngagementMetricsResource {
239
676
  private readonly http;
677
+ /**
678
+ * Stream full engagement export as JSONL.
679
+ *
680
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/engagement/export`.
681
+ */
240
682
  readonly export: ExportResource<EngagementRow, EngagementExportParams>;
241
683
  constructor(http: HttpClient);
242
- list(campaignId: string, params?: EngagementListParams): Promise<ApiResponse<EngagementListData>>;
243
684
  }
244
685
 
686
+ /**
687
+ * Official Soundlink Public API client.
688
+ *
689
+ * All methods return `{ data, error, meta? }` and never throw on HTTP/API errors.
690
+ * SDK configuration, parsing, and transport failures throw {@link SoundlinkSdkError}.
691
+ *
692
+ * @example
693
+ * ```ts
694
+ * import { Soundlink } from 'soundlink';
695
+ *
696
+ * const soundlink = new Soundlink(process.env.SOUNDLINK_API_KEY!);
697
+ *
698
+ * const { data, error } = await soundlink.ping();
699
+ * if (error) {
700
+ * console.error(error.code, error.message);
701
+ * } else {
702
+ * console.log(data.status);
703
+ * }
704
+ * ```
705
+ *
706
+ * @see https://docs.getsoundlink.com
707
+ */
245
708
  declare class Soundlink {
709
+ /** Verify connectivity and authentication. Maps to `GET /v1/ping`. */
246
710
  readonly ping: PingResource['ping'];
711
+ /** Growth strategy catalog. Requires `campaigns:read` scope. */
712
+ readonly strategies: StrategiesResource;
713
+ /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
247
714
  readonly campaigns: CampaignsResource;
715
+ /** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
248
716
  readonly metrics: MetricsResource;
717
+ /**
718
+ * Create a Soundlink client.
719
+ *
720
+ * @param options - API key string (`sk_*`) or {@link SoundlinkClientOptions}.
721
+ */
249
722
  constructor(options: SoundlinkOptions);
250
723
  }
251
724
 
725
+ /**
726
+ * Base error for unexpected SDK failures (configuration, parsing, transport).
727
+ *
728
+ * HTTP/API errors from Soundlink are returned as `{ data: null, error }` and do not throw.
729
+ */
252
730
  declare class SoundlinkSdkError extends Error {
253
731
  constructor(message: string);
254
732
  }
733
+ /** Thrown when a response body cannot be parsed or the network request fails unexpectedly. */
255
734
  declare class SoundlinkParseError extends SoundlinkSdkError {
256
735
  constructor(message: string);
257
736
  }
737
+ /** Thrown when the client is misconfigured (missing or invalid API key, etc.). */
258
738
  declare class SoundlinkConfigError extends SoundlinkSdkError {
259
739
  constructor(message: string);
260
740
  }
@@ -266,4 +746,4 @@ declare const API_KEY_PREFIX = "sk_";
266
746
  declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
267
747
  declare const METRICS_MAX_PAGE_SIZE = 500;
268
748
 
269
- export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignDetail, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignSummary, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type EngagementContext, type EngagementExportParams, type EngagementListData, type EngagementListParams, type EngagementRow, type EngagementSortBy, type ExportCollection, type ExportResource, HttpClient, type JsonlStream, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type Pagination, type PingData, type PublicApiErrorCode, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, getStreamRowCount, resolveClientOptions };
749
+ 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 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, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignTiersRequest, getStreamRowCount, resolveClientOptions };