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.
- package/CHANGELOG.md +12 -0
- package/README.md +103 -24
- package/dist/cjs/index.cjs +262 -17
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +499 -19
- package/dist/esm/index.js +262 -17
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +1309 -211
- package/package.json +1 -1
package/dist/esm/index.d.ts
CHANGED
|
@@ -1,53 +1,246 @@
|
|
|
1
|
-
|
|
2
|
-
type
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 };
|