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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# soundlink
|
|
2
2
|
|
|
3
|
+
## 1.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#3](https://github.com/Fan-ID/lib/pull/3) [`279a718`](https://github.com/Fan-ID/lib/commit/279a718eb13c19d57e6f0db2e3a9fbb29af0b0a8) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add Public API write surface: strategies catalog, campaign create / stop / budget / tiers with `Idempotency-Key`, `generation` on campaign types, expanded error codes. Remove unshipped `metrics.engagement.list`. Sync OpenAPI to the current v1 contract. ([SOU-6003](https://linear.app/getsoundlink/issue/SOU-6003))
|
|
8
|
+
|
|
9
|
+
## 1.1.1
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- [`57ed16a`](https://github.com/Fan-ID/lib/commit/57ed16a090e91297845608935cbec8c074d6e15c) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add TSDoc comments on public methods and types for IDE hover hints and IntelliSense.
|
|
14
|
+
|
|
3
15
|
## 1.1.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Official TypeScript SDK for the [Soundlink Public API](https://docs.getsoundlink
|
|
|
8
8
|
npm install soundlink
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
> **Version note:** `1.0.0` on npm was an empty placeholder.
|
|
11
|
+
> **Version note:** `1.0.0` on npm was an empty placeholder. Use **`>=1.1.0`** for the SDK. Write surface (create / budget / stop / tiers) ships in **`1.2.0`**.
|
|
12
12
|
|
|
13
13
|
Requires **Node.js 18+** (native `fetch`). Works in Edge Runtime when `fetch` is available.
|
|
14
14
|
|
|
@@ -44,6 +44,8 @@ The SDK sends it in the `x-api-key` header on every request.
|
|
|
44
44
|
|
|
45
45
|
Your organization is determined from the key. Do not send Firebase Bearer tokens on the Public API host.
|
|
46
46
|
|
|
47
|
+
Write methods require the `campaigns:write` scope and an `Idempotency-Key` (passed as `idempotencyKey` on the method options).
|
|
48
|
+
|
|
47
49
|
## Response pattern
|
|
48
50
|
|
|
49
51
|
Every method returns:
|
|
@@ -82,11 +84,75 @@ const { data, error } = await soundlink.campaigns.list({
|
|
|
82
84
|
});
|
|
83
85
|
|
|
84
86
|
const { data: campaign } = await soundlink.campaigns.get('camp_abc123');
|
|
87
|
+
// campaign.generation === 3 → wallet (writable)
|
|
85
88
|
|
|
86
89
|
// Async iterator across all pages
|
|
87
90
|
for await (const item of soundlink.campaigns.listAll({ pageSize: 100 })) {
|
|
88
|
-
console.log(item.campaignId);
|
|
91
|
+
console.log(item.campaignId, item.generation);
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Create, budget, tiers, stop (wallet / `generation: 3`)
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
const { data: strategies } = await soundlink.strategies.list();
|
|
99
|
+
|
|
100
|
+
const { data: created, error: createError } = await soundlink.campaigns.create(
|
|
101
|
+
{
|
|
102
|
+
spotifyUrl: 'https://open.spotify.com/track/...',
|
|
103
|
+
dailyBudget: 20,
|
|
104
|
+
durationDays: 7,
|
|
105
|
+
genre: 'Pop',
|
|
106
|
+
strategyType: 'maximum_growth',
|
|
107
|
+
},
|
|
108
|
+
{ idempotencyKey: 'create-mytrack-01' },
|
|
109
|
+
);
|
|
110
|
+
|
|
111
|
+
if (createError || !created) {
|
|
112
|
+
console.error(createError);
|
|
113
|
+
return;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
await soundlink.campaigns.increaseBudget(
|
|
117
|
+
created.campaignId,
|
|
118
|
+
{ amount: 50, mode: 'current_and_renewals' },
|
|
119
|
+
{ idempotencyKey: 'budget-inc-01' },
|
|
120
|
+
);
|
|
121
|
+
|
|
122
|
+
// GET returns `tierId`; PATCH expects the same value as `targetingTierId`
|
|
123
|
+
const { data: tiers } = await soundlink.campaigns.tiers.get(created.campaignId);
|
|
124
|
+
if (!tiers) {
|
|
125
|
+
return;
|
|
89
126
|
}
|
|
127
|
+
await soundlink.campaigns.tiers.update(created.campaignId, {
|
|
128
|
+
items: tiers.tiers.map((tier) => ({
|
|
129
|
+
targetingTierId: tier.tierId,
|
|
130
|
+
isEnabled: tier.isEnabled,
|
|
131
|
+
newAllocationPercent: tier.allocationPercent,
|
|
132
|
+
})),
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
await soundlink.campaigns.stop(created.campaignId, {
|
|
136
|
+
idempotencyKey: 'stop-01',
|
|
137
|
+
});
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Custom strategy create (requires `tierTargeting`):
|
|
141
|
+
|
|
142
|
+
```typescript
|
|
143
|
+
const { data: created } = await soundlink.campaigns.create(
|
|
144
|
+
{
|
|
145
|
+
spotifyUrl: 'https://open.spotify.com/track/...',
|
|
146
|
+
dailyBudget: 20,
|
|
147
|
+
durationDays: 7,
|
|
148
|
+
genre: 'Pop',
|
|
149
|
+
strategyType: 'custom',
|
|
150
|
+
tierTargeting: {
|
|
151
|
+
customTiers: [{ name: 'US focus', countries: ['US'], percentBudget: 100 }],
|
|
152
|
+
},
|
|
153
|
+
},
|
|
154
|
+
{ idempotencyKey: 'create-custom-01' },
|
|
155
|
+
);
|
|
90
156
|
```
|
|
91
157
|
|
|
92
158
|
## Metrics
|
|
@@ -145,33 +211,38 @@ const soundlink = new Soundlink({
|
|
|
145
211
|
apiKey: process.env.SOUNDLINK_API_KEY!,
|
|
146
212
|
baseUrl: 'https://api.getsoundlink.com', // default
|
|
147
213
|
timeout: 30_000, // ms, default
|
|
148
|
-
maxRetries: 2, // retries on 429/5xx, default
|
|
214
|
+
maxRetries: 2, // retries on 429/5xx (same Idempotency-Key on writes), default
|
|
149
215
|
fetch: customFetch, // optional, for Edge/tests
|
|
150
216
|
});
|
|
151
217
|
```
|
|
152
218
|
|
|
153
219
|
## Error codes
|
|
154
220
|
|
|
155
|
-
| Code
|
|
156
|
-
|
|
|
157
|
-
| `invalid_api_key`
|
|
158
|
-
| `api_key_revoked`
|
|
159
|
-
| `api_key_expired`
|
|
160
|
-
| `mixed_credentials`
|
|
161
|
-
| `insufficient_scope`
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
|
|
170
|
-
|
|
221
|
+
| Code | Typical HTTP |
|
|
222
|
+
| -------------------------- | ------------ |
|
|
223
|
+
| `invalid_api_key` | 401 |
|
|
224
|
+
| `api_key_revoked` | 401 |
|
|
225
|
+
| `api_key_expired` | 401 |
|
|
226
|
+
| `mixed_credentials` | 401 |
|
|
227
|
+
| `insufficient_scope` | 403 |
|
|
228
|
+
| `wallet_not_enabled` | 403 |
|
|
229
|
+
| `not_found` | 404 |
|
|
230
|
+
| `campaign_not_found` | 404 |
|
|
231
|
+
| `invalid_request` | 400 |
|
|
232
|
+
| `invalid_query_parameter` | 400 |
|
|
233
|
+
| `invalid_date_range` | 400 |
|
|
234
|
+
| `page_size_exceeded` | 400 |
|
|
235
|
+
| `insufficient_credit` | 402 |
|
|
236
|
+
| `idempotency_key_conflict` | 409 |
|
|
237
|
+
| `tier_update_cooldown` | 409 |
|
|
238
|
+
| `rate_limit_exceeded` | 429 |
|
|
239
|
+
| `internal_error` | 500 |
|
|
240
|
+
|
|
241
|
+
Include `meta.requestId` (or `error.requestId`) when contacting Soundlink support. On `402 insufficient_credit`, check `error.details` for `available` / `required` wallet amounts.
|
|
171
242
|
|
|
172
243
|
## API reference
|
|
173
244
|
|
|
174
|
-
Full endpoint documentation: [getsoundlink.com
|
|
245
|
+
Full endpoint documentation: [docs.getsoundlink.com](https://docs.getsoundlink.com).
|
|
175
246
|
|
|
176
247
|
OpenAPI spec shipped with this package: `openapi/soundlink-public-api-v1.yaml`.
|
|
177
248
|
|
|
@@ -193,19 +264,27 @@ SOUNDLINK_API_KEY=sk_your_prefix_your_secret npm run test:live
|
|
|
193
264
|
npm run test:live -- sk_your_prefix_your_secret
|
|
194
265
|
```
|
|
195
266
|
|
|
196
|
-
The script runs: `ping` → `campaigns.list` → `campaigns.get` → `metrics.overview` (best effort).
|
|
267
|
+
The script runs: `ping` → `strategies.list` → `campaigns.list` (checks `generation`) → `campaigns.get` → `metrics.overview` (best effort).
|
|
268
|
+
|
|
269
|
+
Opt-in write smoke (debits wallet — use a sandbox org):
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
SOUNDLINK_LIVE_WRITE=1 \
|
|
273
|
+
SOUNDLINK_LIVE_SPOTIFY_URL='https://open.spotify.com/track/...' \
|
|
274
|
+
SOUNDLINK_API_KEY=sk_... \
|
|
275
|
+
npm run test:live
|
|
276
|
+
```
|
|
197
277
|
|
|
198
278
|
## Roadmap
|
|
199
279
|
|
|
200
|
-
- `
|
|
201
|
-
- `campaigns.create` — when `campaigns:write` scope opens in v2
|
|
280
|
+
- Video import helpers (`videos:write`) — when prioritized
|
|
202
281
|
- Webhook helpers — when Public API webhooks ship
|
|
203
282
|
|
|
204
283
|
## Releases
|
|
205
284
|
|
|
206
285
|
GitHub Releases are created automatically when a **Version packages** PR is merged. Release notes come from `CHANGELOG.md`, with PR/issue links when referenced in changesets.
|
|
207
286
|
|
|
208
|
-
See [CONTRIBUTING.md](./CONTRIBUTING.md
|
|
287
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full flow.
|
|
209
288
|
|
|
210
289
|
## Contributing
|
|
211
290
|
|
package/dist/cjs/index.cjs
CHANGED
|
@@ -25,12 +25,14 @@ function isApiEnvelopeSuccess(body) {
|
|
|
25
25
|
return "data" in record && typeof record.meta === "object" && record.meta !== null;
|
|
26
26
|
}
|
|
27
27
|
function toApiError(envelope, status, retryAfter) {
|
|
28
|
+
const { details } = envelope.error;
|
|
28
29
|
return {
|
|
29
30
|
code: envelope.error.code,
|
|
30
31
|
message: envelope.error.message,
|
|
31
32
|
status,
|
|
32
33
|
requestId: envelope.meta.requestId,
|
|
33
|
-
...retryAfter !== void 0 ? { retryAfter } : {}
|
|
34
|
+
...retryAfter !== void 0 ? { retryAfter } : {},
|
|
35
|
+
...details !== void 0 ? { details } : {}
|
|
34
36
|
};
|
|
35
37
|
}
|
|
36
38
|
function successResponse(data, meta) {
|
|
@@ -206,6 +208,36 @@ var HttpClient = class {
|
|
|
206
208
|
headers: this.buildHeaders()
|
|
207
209
|
});
|
|
208
210
|
}
|
|
211
|
+
async post({
|
|
212
|
+
path,
|
|
213
|
+
body,
|
|
214
|
+
query,
|
|
215
|
+
headers,
|
|
216
|
+
idempotencyKey
|
|
217
|
+
}) {
|
|
218
|
+
return this.mutateJson("POST", {
|
|
219
|
+
path,
|
|
220
|
+
body,
|
|
221
|
+
query,
|
|
222
|
+
headers,
|
|
223
|
+
idempotencyKey
|
|
224
|
+
});
|
|
225
|
+
}
|
|
226
|
+
async patch({
|
|
227
|
+
path,
|
|
228
|
+
body,
|
|
229
|
+
query,
|
|
230
|
+
headers,
|
|
231
|
+
idempotencyKey
|
|
232
|
+
}) {
|
|
233
|
+
return this.mutateJson("PATCH", {
|
|
234
|
+
path,
|
|
235
|
+
body,
|
|
236
|
+
query,
|
|
237
|
+
headers,
|
|
238
|
+
idempotencyKey
|
|
239
|
+
});
|
|
240
|
+
}
|
|
209
241
|
async getJsonl({
|
|
210
242
|
path,
|
|
211
243
|
query,
|
|
@@ -244,10 +276,27 @@ var HttpClient = class {
|
|
|
244
276
|
error: null
|
|
245
277
|
};
|
|
246
278
|
}
|
|
247
|
-
|
|
279
|
+
mutateJson(method, { path, body, query, headers, idempotencyKey }) {
|
|
280
|
+
const url = joinUrl(
|
|
281
|
+
this.options.baseUrl,
|
|
282
|
+
`${API_VERSION_PREFIX}${path}${buildQueryString(query ?? {})}`
|
|
283
|
+
);
|
|
284
|
+
const requestHeaders = this.buildHeaders({
|
|
285
|
+
...body !== void 0 ? { "Content-Type": "application/json" } : {},
|
|
286
|
+
...idempotencyKey !== void 0 ? { "Idempotency-Key": idempotencyKey } : {},
|
|
287
|
+
...headers
|
|
288
|
+
});
|
|
289
|
+
return this.requestJson(url, {
|
|
290
|
+
method,
|
|
291
|
+
headers: requestHeaders,
|
|
292
|
+
...body !== void 0 ? { body: JSON.stringify(body) } : {}
|
|
293
|
+
});
|
|
294
|
+
}
|
|
295
|
+
buildHeaders(extra = {}) {
|
|
248
296
|
return {
|
|
249
297
|
"x-api-key": this.options.apiKey,
|
|
250
|
-
Accept: "application/json"
|
|
298
|
+
Accept: "application/json",
|
|
299
|
+
...extra
|
|
251
300
|
};
|
|
252
301
|
}
|
|
253
302
|
async requestJson(url, init) {
|
|
@@ -377,15 +426,91 @@ var PingResource = class {
|
|
|
377
426
|
this.http = http;
|
|
378
427
|
}
|
|
379
428
|
http;
|
|
429
|
+
/**
|
|
430
|
+
* Verify connectivity and API key authentication.
|
|
431
|
+
*
|
|
432
|
+
* Accepts any valid v1 key scope. Does not require `campaigns:read` or `metrics:read`.
|
|
433
|
+
*
|
|
434
|
+
* @returns `{ data: { status: 'ok' }, error: null }` on success.
|
|
435
|
+
*
|
|
436
|
+
* @example
|
|
437
|
+
* ```ts
|
|
438
|
+
* const { data, error, meta } = await soundlink.ping();
|
|
439
|
+
* ```
|
|
440
|
+
*/
|
|
380
441
|
ping() {
|
|
381
442
|
return this.http.get({ path: "/ping" });
|
|
382
443
|
}
|
|
383
444
|
};
|
|
445
|
+
var StrategiesResource = class {
|
|
446
|
+
constructor(http) {
|
|
447
|
+
this.http = http;
|
|
448
|
+
}
|
|
449
|
+
http;
|
|
450
|
+
/**
|
|
451
|
+
* List growth strategies available for wallet campaign create.
|
|
452
|
+
*
|
|
453
|
+
* Maps to `GET /v1/strategies`.
|
|
454
|
+
*
|
|
455
|
+
* @example
|
|
456
|
+
* ```ts
|
|
457
|
+
* const { data } = await soundlink.strategies.list();
|
|
458
|
+
* ```
|
|
459
|
+
*/
|
|
460
|
+
list() {
|
|
461
|
+
return this.http.get({ path: "/strategies" });
|
|
462
|
+
}
|
|
463
|
+
};
|
|
464
|
+
var CampaignTiersResource = class {
|
|
465
|
+
constructor(http) {
|
|
466
|
+
this.http = http;
|
|
467
|
+
}
|
|
468
|
+
http;
|
|
469
|
+
/**
|
|
470
|
+
* Get current tier allocation for a wallet campaign.
|
|
471
|
+
*
|
|
472
|
+
* Maps to `GET /v1/campaigns/{campaignId}/tiers`. Wallet campaigns only (`generation: 3`).
|
|
473
|
+
*/
|
|
474
|
+
get(campaignId) {
|
|
475
|
+
return this.http.get({
|
|
476
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/tiers`
|
|
477
|
+
});
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* Update tier enablement and budget shares.
|
|
481
|
+
*
|
|
482
|
+
* Maps to `PATCH /v1/campaigns/{campaignId}/tiers`. Requires `campaigns:write`.
|
|
483
|
+
* Allocation percents across items must sum to 100.
|
|
484
|
+
* Use each tier's `tierId` from {@link CampaignTiersResource.get} as `targetingTierId`.
|
|
485
|
+
* Does not require an `Idempotency-Key` (unlike create / stop / budget).
|
|
486
|
+
*/
|
|
487
|
+
update(campaignId, body) {
|
|
488
|
+
return this.http.patch({
|
|
489
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/tiers`,
|
|
490
|
+
body
|
|
491
|
+
});
|
|
492
|
+
}
|
|
493
|
+
};
|
|
384
494
|
var CampaignsResource = class {
|
|
385
495
|
constructor(http) {
|
|
386
496
|
this.http = http;
|
|
497
|
+
this.tiers = new CampaignTiersResource(http);
|
|
387
498
|
}
|
|
388
499
|
http;
|
|
500
|
+
/** Tier allocation for wallet campaigns (`generation: 3`). */
|
|
501
|
+
tiers;
|
|
502
|
+
/**
|
|
503
|
+
* List campaigns for the authenticated organization.
|
|
504
|
+
*
|
|
505
|
+
* Maps to `GET /v1/campaigns`. Max `pageSize` is **100**. Requires `campaigns:read`.
|
|
506
|
+
*
|
|
507
|
+
* @param params - Pagination and sort options.
|
|
508
|
+
*
|
|
509
|
+
* @example
|
|
510
|
+
* ```ts
|
|
511
|
+
* const { data, error } = await soundlink.campaigns.list({ page: 1, pageSize: 100 });
|
|
512
|
+
* ```
|
|
513
|
+
*/
|
|
389
514
|
list(params = {}) {
|
|
390
515
|
return this.http.get({
|
|
391
516
|
path: "/campaigns",
|
|
@@ -397,11 +522,96 @@ var CampaignsResource = class {
|
|
|
397
522
|
}
|
|
398
523
|
});
|
|
399
524
|
}
|
|
525
|
+
/**
|
|
526
|
+
* Fetch full details for a single campaign.
|
|
527
|
+
*
|
|
528
|
+
* Maps to `GET /v1/campaigns/{campaignId}`. Requires `campaigns:read`.
|
|
529
|
+
*
|
|
530
|
+
* @param campaignId - Campaign identifier returned by {@link CampaignsResource.list}.
|
|
531
|
+
*/
|
|
400
532
|
get(campaignId) {
|
|
401
533
|
return this.http.get({
|
|
402
534
|
path: `/campaigns/${encodeURIComponent(campaignId)}`
|
|
403
535
|
});
|
|
404
536
|
}
|
|
537
|
+
/**
|
|
538
|
+
* Create a wallet-funded campaign.
|
|
539
|
+
*
|
|
540
|
+
* Maps to `POST /v1/campaigns`. Requires `campaigns:write` and `Idempotency-Key`.
|
|
541
|
+
*
|
|
542
|
+
* @example
|
|
543
|
+
* ```ts
|
|
544
|
+
* const { data, error } = await soundlink.campaigns.create(
|
|
545
|
+
* {
|
|
546
|
+
* spotifyUrl: 'https://open.spotify.com/track/...',
|
|
547
|
+
* dailyBudget: 20,
|
|
548
|
+
* durationDays: 7,
|
|
549
|
+
* genre: 'Pop',
|
|
550
|
+
* strategyType: 'maximum_growth',
|
|
551
|
+
* },
|
|
552
|
+
* { idempotencyKey: 'create-mytrack-01' },
|
|
553
|
+
* );
|
|
554
|
+
* ```
|
|
555
|
+
*/
|
|
556
|
+
create(body, options) {
|
|
557
|
+
return this.http.post({
|
|
558
|
+
path: "/campaigns",
|
|
559
|
+
body,
|
|
560
|
+
idempotencyKey: options.idempotencyKey
|
|
561
|
+
});
|
|
562
|
+
}
|
|
563
|
+
/**
|
|
564
|
+
* Stop a wallet campaign and refund unspent budget.
|
|
565
|
+
*
|
|
566
|
+
* Maps to `POST /v1/campaigns/{campaignId}/stop`. Requires `campaigns:write`
|
|
567
|
+
* and `Idempotency-Key`. Wallet campaigns only (`generation: 3`).
|
|
568
|
+
*/
|
|
569
|
+
stop(campaignId, options) {
|
|
570
|
+
return this.http.post({
|
|
571
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/stop`,
|
|
572
|
+
idempotencyKey: options.idempotencyKey
|
|
573
|
+
});
|
|
574
|
+
}
|
|
575
|
+
/**
|
|
576
|
+
* Increase wallet campaign budget.
|
|
577
|
+
*
|
|
578
|
+
* Maps to `POST /v1/campaigns/{campaignId}/budget/increase`.
|
|
579
|
+
* Requires `campaigns:write` and `Idempotency-Key`. Wallet only (`generation: 3`).
|
|
580
|
+
*/
|
|
581
|
+
increaseBudget(campaignId, body, options) {
|
|
582
|
+
return this.http.post({
|
|
583
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/budget/increase`,
|
|
584
|
+
body,
|
|
585
|
+
idempotencyKey: options.idempotencyKey
|
|
586
|
+
});
|
|
587
|
+
}
|
|
588
|
+
/**
|
|
589
|
+
* Decrease wallet campaign daily budget.
|
|
590
|
+
*
|
|
591
|
+
* Maps to `POST /v1/campaigns/{campaignId}/budget/decrease`.
|
|
592
|
+
* Requires `campaigns:write` and `Idempotency-Key`. Wallet only (`generation: 3`).
|
|
593
|
+
*/
|
|
594
|
+
decreaseBudget(campaignId, body, options) {
|
|
595
|
+
return this.http.post({
|
|
596
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/budget/decrease`,
|
|
597
|
+
body,
|
|
598
|
+
idempotencyKey: options.idempotencyKey
|
|
599
|
+
});
|
|
600
|
+
}
|
|
601
|
+
/**
|
|
602
|
+
* Async iterator over every campaign across all pages.
|
|
603
|
+
*
|
|
604
|
+
* Stops silently if a page request returns an error.
|
|
605
|
+
*
|
|
606
|
+
* @param params - Same as {@link CampaignsResource.list} except `page` is managed automatically.
|
|
607
|
+
*
|
|
608
|
+
* @example
|
|
609
|
+
* ```ts
|
|
610
|
+
* for await (const campaign of soundlink.campaigns.listAll({ pageSize: 100 })) {
|
|
611
|
+
* console.log(campaign.campaignId);
|
|
612
|
+
* }
|
|
613
|
+
* ```
|
|
614
|
+
*/
|
|
405
615
|
async *listAll(params = {}) {
|
|
406
616
|
let page = 1;
|
|
407
617
|
let totalPages = 1;
|
|
@@ -425,8 +635,27 @@ var MetricsResource = class {
|
|
|
425
635
|
this.engagement = new EngagementMetricsResource(http);
|
|
426
636
|
}
|
|
427
637
|
http;
|
|
638
|
+
/** Per-day country breakdown and JSONL export. */
|
|
428
639
|
breakdown;
|
|
640
|
+
/** Per-track engagement JSONL export. */
|
|
429
641
|
engagement;
|
|
642
|
+
/**
|
|
643
|
+
* Campaign-level metric totals for a date range.
|
|
644
|
+
*
|
|
645
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/overview`.
|
|
646
|
+
* Aggregates across all countries — use {@link BreakdownMetricsResource.list} for daily rows.
|
|
647
|
+
*
|
|
648
|
+
* @param campaignId - Campaign identifier.
|
|
649
|
+
* @param params - Inclusive `YYYY-MM-DD` date range. Omit for API defaults.
|
|
650
|
+
*
|
|
651
|
+
* @example
|
|
652
|
+
* ```ts
|
|
653
|
+
* const { data } = await soundlink.metrics.overview(campaignId, {
|
|
654
|
+
* startDate: '2026-01-01',
|
|
655
|
+
* endDate: '2026-03-31',
|
|
656
|
+
* });
|
|
657
|
+
* ```
|
|
658
|
+
*/
|
|
430
659
|
overview(campaignId, params = {}) {
|
|
431
660
|
return this.http.get({
|
|
432
661
|
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/overview`,
|
|
@@ -450,7 +679,21 @@ var BreakdownMetricsResource = class {
|
|
|
450
679
|
);
|
|
451
680
|
}
|
|
452
681
|
http;
|
|
682
|
+
/**
|
|
683
|
+
* Stream full breakdown export as JSONL.
|
|
684
|
+
*
|
|
685
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown/export`.
|
|
686
|
+
*/
|
|
453
687
|
export;
|
|
688
|
+
/**
|
|
689
|
+
* Paginated per-day, per-country breakdown rows.
|
|
690
|
+
*
|
|
691
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown`.
|
|
692
|
+
* Max `pageSize` is **500** (default 50).
|
|
693
|
+
*
|
|
694
|
+
* @param campaignId - Campaign identifier.
|
|
695
|
+
* @param params - Date range, pagination, and sort options.
|
|
696
|
+
*/
|
|
454
697
|
list(campaignId, params = {}) {
|
|
455
698
|
return this.http.get({
|
|
456
699
|
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/breakdown`,
|
|
@@ -479,32 +722,34 @@ var EngagementMetricsResource = class {
|
|
|
479
722
|
);
|
|
480
723
|
}
|
|
481
724
|
http;
|
|
725
|
+
/**
|
|
726
|
+
* Stream full engagement export as JSONL.
|
|
727
|
+
*
|
|
728
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/engagement/export`.
|
|
729
|
+
*/
|
|
482
730
|
export;
|
|
483
|
-
list(campaignId, params = {}) {
|
|
484
|
-
return this.http.get({
|
|
485
|
-
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/engagement`,
|
|
486
|
-
query: {
|
|
487
|
-
startDate: params.startDate,
|
|
488
|
-
endDate: params.endDate,
|
|
489
|
-
page: params.page,
|
|
490
|
-
pageSize: params.pageSize,
|
|
491
|
-
sortBy: params.sortBy,
|
|
492
|
-
sortOrder: params.sortOrder,
|
|
493
|
-
engagementContext: params.engagementContext
|
|
494
|
-
}
|
|
495
|
-
});
|
|
496
|
-
}
|
|
497
731
|
};
|
|
498
732
|
|
|
499
733
|
// src/client/soundlink.ts
|
|
500
734
|
var Soundlink = class {
|
|
735
|
+
/** Verify connectivity and authentication. Maps to `GET /v1/ping`. */
|
|
501
736
|
ping;
|
|
737
|
+
/** Growth strategy catalog. Requires `campaigns:read` scope. */
|
|
738
|
+
strategies;
|
|
739
|
+
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
502
740
|
campaigns;
|
|
741
|
+
/** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
|
|
503
742
|
metrics;
|
|
743
|
+
/**
|
|
744
|
+
* Create a Soundlink client.
|
|
745
|
+
*
|
|
746
|
+
* @param options - API key string (`sk_*`) or {@link SoundlinkClientOptions}.
|
|
747
|
+
*/
|
|
504
748
|
constructor(options) {
|
|
505
749
|
const http = new HttpClient(options);
|
|
506
750
|
const pingResource = new PingResource(http);
|
|
507
751
|
this.ping = pingResource.ping.bind(pingResource);
|
|
752
|
+
this.strategies = new StrategiesResource(http);
|
|
508
753
|
this.campaigns = new CampaignsResource(http);
|
|
509
754
|
this.metrics = new MetricsResource(http);
|
|
510
755
|
}
|