soundlink 2.5.0 → 2.7.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 +32 -0
- package/dist/cjs/index.cjs +136 -10
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +203 -2
- package/dist/esm/index.js +136 -11
- package/dist/esm/index.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# soundlink
|
|
2
2
|
|
|
3
|
+
## 2.7.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#35](https://github.com/Fan-ID/typescript-sdk/pull/35) [`996c60f`](https://github.com/Fan-ID/typescript-sdk/commit/996c60ff063ee181398c3b70535fd07093420fd3) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add cohort retention (`metrics.retention`, `soundlinks.retention`) and listening insights (`campaigns.listeningInsights`, `soundlinks.listeningInsights`) for premium Public API endpoints (SOU-7393). Insights use a 120s per-request timeout.
|
|
8
|
+
|
|
9
|
+
## 2.6.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- [#33](https://github.com/Fan-ID/typescript-sdk/pull/33) [`a251c84`](https://github.com/Fan-ID/typescript-sdk/commit/a251c8444945bdfce96876b1682299d58a59cf29) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add `pixels.list`, `pixels.update`, and `pixels.sendTestEvent` for `/v1/pixels` (SOU-7393). Requires `pixels:read` / `pixels:write`.
|
|
14
|
+
|
|
3
15
|
## 2.5.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -150,6 +150,19 @@ const { data: wallet } = await soundlink.wallet.get();
|
|
|
150
150
|
// wallet.available is balance minus reserved
|
|
151
151
|
```
|
|
152
152
|
|
|
153
|
+
### Pixels (`pixels:read` / `pixels:write`)
|
|
154
|
+
|
|
155
|
+
```typescript
|
|
156
|
+
const { data: pixels } = await soundlink.pixels.list();
|
|
157
|
+
|
|
158
|
+
await soundlink.pixels.update('1234567890123456', {
|
|
159
|
+
platform: 'meta',
|
|
160
|
+
accessToken: process.env.META_CAPI_TOKEN!,
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
await soundlink.pixels.sendTestEvent('1234567890123456');
|
|
164
|
+
```
|
|
165
|
+
|
|
153
166
|
Custom strategy create (requires `tierTargeting`):
|
|
154
167
|
|
|
155
168
|
```typescript
|
|
@@ -209,6 +222,13 @@ const { data: engagement } = await soundlink.soundlinks.engagement.list('sl_abc1
|
|
|
209
222
|
});
|
|
210
223
|
|
|
211
224
|
// JSONL: soundlinks.breakdown.export / soundlinks.engagement.export (same pattern as Metrics below)
|
|
225
|
+
|
|
226
|
+
// Premium: cohort retention + listening insights (same as Metrics section)
|
|
227
|
+
const { data: retention } = await soundlink.soundlinks.retention('sl_abc123');
|
|
228
|
+
const { data: insight } = await soundlink.soundlinks.listeningInsights(
|
|
229
|
+
'sl_abc123',
|
|
230
|
+
'stream-split',
|
|
231
|
+
);
|
|
212
232
|
```
|
|
213
233
|
|
|
214
234
|
## Metrics
|
|
@@ -231,6 +251,18 @@ const { data: breakdown } = await soundlink.metrics.breakdown.list('camp_abc123'
|
|
|
231
251
|
page: 1,
|
|
232
252
|
pageSize: 50,
|
|
233
253
|
});
|
|
254
|
+
|
|
255
|
+
// Cohort retention — premium plan (`403 premium_plan_required` otherwise)
|
|
256
|
+
const { data: retention } = await soundlink.metrics.retention('camp_abc123', {
|
|
257
|
+
startDate: '2026-08-01',
|
|
258
|
+
endDate: '2026-08-31',
|
|
259
|
+
});
|
|
260
|
+
|
|
261
|
+
// Listening insights — premium; SDK uses a 120s timeout (API often takes 30–50s)
|
|
262
|
+
const { data: insight } = await soundlink.campaigns.listeningInsights(
|
|
263
|
+
'camp_abc123',
|
|
264
|
+
'other-artists',
|
|
265
|
+
);
|
|
234
266
|
```
|
|
235
267
|
|
|
236
268
|
### JSONL exports (streaming)
|
package/dist/cjs/index.cjs
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
// src/constants/defaults.ts
|
|
4
4
|
var DEFAULT_BASE_URL = "https://api.getsoundlink.com";
|
|
5
5
|
var DEFAULT_TIMEOUT_MS = 3e4;
|
|
6
|
+
var LISTENING_INSIGHTS_TIMEOUT_MS = 12e4;
|
|
6
7
|
var DEFAULT_MAX_RETRIES = 2;
|
|
7
8
|
var API_KEY_PREFIX = "sk_";
|
|
8
9
|
var CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
@@ -199,15 +200,19 @@ var HttpClient = class {
|
|
|
199
200
|
get resolvedOptions() {
|
|
200
201
|
return this.options;
|
|
201
202
|
}
|
|
202
|
-
async get({ path, query }) {
|
|
203
|
+
async get({ path, query, timeout }) {
|
|
203
204
|
const url = joinUrl(
|
|
204
205
|
this.options.baseUrl,
|
|
205
206
|
`${API_VERSION_PREFIX}${path}${buildQueryString(query ?? {})}`
|
|
206
207
|
);
|
|
207
|
-
return this.requestJson(
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
208
|
+
return this.requestJson(
|
|
209
|
+
url,
|
|
210
|
+
{
|
|
211
|
+
method: "GET",
|
|
212
|
+
headers: this.buildHeaders()
|
|
213
|
+
},
|
|
214
|
+
timeout
|
|
215
|
+
);
|
|
211
216
|
}
|
|
212
217
|
async post({
|
|
213
218
|
path,
|
|
@@ -330,10 +335,10 @@ var HttpClient = class {
|
|
|
330
335
|
...extra
|
|
331
336
|
};
|
|
332
337
|
}
|
|
333
|
-
async requestJson(url, init) {
|
|
338
|
+
async requestJson(url, init, timeoutMs) {
|
|
334
339
|
let response;
|
|
335
340
|
try {
|
|
336
|
-
response = await this.fetchWithRetry(url, init);
|
|
341
|
+
response = await this.fetchWithRetry(url, init, timeoutMs);
|
|
337
342
|
} catch (error) {
|
|
338
343
|
throw toTransportError(error);
|
|
339
344
|
}
|
|
@@ -379,12 +384,13 @@ var HttpClient = class {
|
|
|
379
384
|
...retryAfter !== void 0 ? { retryAfter } : {}
|
|
380
385
|
});
|
|
381
386
|
}
|
|
382
|
-
async fetchWithRetry(url, init) {
|
|
387
|
+
async fetchWithRetry(url, init, timeoutMs) {
|
|
383
388
|
const { maxRetries, timeout, fetch } = this.options;
|
|
389
|
+
const requestTimeout = timeoutMs ?? timeout;
|
|
384
390
|
let attempt = 0;
|
|
385
391
|
let response = await fetch(url, {
|
|
386
392
|
...init,
|
|
387
|
-
signal: AbortSignal.timeout(
|
|
393
|
+
signal: AbortSignal.timeout(requestTimeout)
|
|
388
394
|
});
|
|
389
395
|
while (attempt < maxRetries && (response.status === 429 || response.status >= 500)) {
|
|
390
396
|
const retryAfter = parseRetryAfterHeader(response.headers.get("Retry-After"));
|
|
@@ -393,7 +399,7 @@ var HttpClient = class {
|
|
|
393
399
|
await sleep(delayMs);
|
|
394
400
|
response = await fetch(url, {
|
|
395
401
|
...init,
|
|
396
|
-
signal: AbortSignal.timeout(
|
|
402
|
+
signal: AbortSignal.timeout(requestTimeout)
|
|
397
403
|
});
|
|
398
404
|
}
|
|
399
405
|
return response;
|
|
@@ -511,6 +517,62 @@ var StrategiesResource = class {
|
|
|
511
517
|
return this.http.get({ path: "/strategies" });
|
|
512
518
|
}
|
|
513
519
|
};
|
|
520
|
+
var PixelsResource = class {
|
|
521
|
+
constructor(http) {
|
|
522
|
+
this.http = http;
|
|
523
|
+
}
|
|
524
|
+
http;
|
|
525
|
+
/**
|
|
526
|
+
* List Meta pixels saved for the organization.
|
|
527
|
+
*
|
|
528
|
+
* Maps to `GET /v1/pixels`. Requires `pixels:read`.
|
|
529
|
+
* Returns `403 custom_pixel_not_enabled` when the feature is off.
|
|
530
|
+
*
|
|
531
|
+
* @example
|
|
532
|
+
* ```ts
|
|
533
|
+
* const { data } = await soundlink.pixels.list();
|
|
534
|
+
* ```
|
|
535
|
+
*/
|
|
536
|
+
list() {
|
|
537
|
+
return this.http.get({ path: "/pixels" });
|
|
538
|
+
}
|
|
539
|
+
/**
|
|
540
|
+
* Save or rotate a Meta pixel access token.
|
|
541
|
+
*
|
|
542
|
+
* Maps to `PUT /v1/pixels/{pixelId}`. Requires `pixels:write`.
|
|
543
|
+
* Does not require an `Idempotency-Key`. The access token is never returned.
|
|
544
|
+
*
|
|
545
|
+
* @example
|
|
546
|
+
* ```ts
|
|
547
|
+
* const { data } = await soundlink.pixels.update('1234567890123456', {
|
|
548
|
+
* platform: 'meta',
|
|
549
|
+
* accessToken: process.env.META_CAPI_TOKEN!,
|
|
550
|
+
* });
|
|
551
|
+
* ```
|
|
552
|
+
*/
|
|
553
|
+
update(pixelId, body) {
|
|
554
|
+
return this.http.put({
|
|
555
|
+
path: `/pixels/${encodeURIComponent(pixelId)}`,
|
|
556
|
+
body
|
|
557
|
+
});
|
|
558
|
+
}
|
|
559
|
+
/**
|
|
560
|
+
* Send a live Meta Conversions API test event to a saved pixel.
|
|
561
|
+
*
|
|
562
|
+
* Maps to `POST /v1/pixels/{pixelId}/test-events`. Requires `pixels:write`.
|
|
563
|
+
* This is not a sandbox event — it appears in Events Manager.
|
|
564
|
+
*
|
|
565
|
+
* @example
|
|
566
|
+
* ```ts
|
|
567
|
+
* const { data } = await soundlink.pixels.sendTestEvent('1234567890123456');
|
|
568
|
+
* ```
|
|
569
|
+
*/
|
|
570
|
+
sendTestEvent(pixelId) {
|
|
571
|
+
return this.http.post({
|
|
572
|
+
path: `/pixels/${encodeURIComponent(pixelId)}/test-events`
|
|
573
|
+
});
|
|
574
|
+
}
|
|
575
|
+
};
|
|
514
576
|
var CampaignTiersResource = class {
|
|
515
577
|
constructor(http) {
|
|
516
578
|
this.http = http;
|
|
@@ -600,6 +662,20 @@ var CampaignsResource = class {
|
|
|
600
662
|
}
|
|
601
663
|
});
|
|
602
664
|
}
|
|
665
|
+
/**
|
|
666
|
+
* What listeners who connected through this campaign went on to play.
|
|
667
|
+
*
|
|
668
|
+
* Maps to `GET /v1/campaigns/{campaignId}/listening-insights/{insight}`.
|
|
669
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
670
|
+
* Date window comes from the listening graph — do not send `startDate`/`endDate`.
|
|
671
|
+
* Uses a 120s timeout (insights often take 30–50s).
|
|
672
|
+
*/
|
|
673
|
+
listeningInsights(campaignId, insight) {
|
|
674
|
+
return this.http.get({
|
|
675
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/listening-insights/${encodeURIComponent(insight)}`,
|
|
676
|
+
timeout: LISTENING_INSIGHTS_TIMEOUT_MS
|
|
677
|
+
});
|
|
678
|
+
}
|
|
603
679
|
/**
|
|
604
680
|
* Create a wallet-funded campaign.
|
|
605
681
|
*
|
|
@@ -808,6 +884,36 @@ var SoundlinksResource = class {
|
|
|
808
884
|
}
|
|
809
885
|
});
|
|
810
886
|
}
|
|
887
|
+
/**
|
|
888
|
+
* Cohort retention for a soundlink (`soundlink_cohort_retention_daily`).
|
|
889
|
+
*
|
|
890
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/retention`.
|
|
891
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
892
|
+
* One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
|
|
893
|
+
*/
|
|
894
|
+
retention(soundlinkId, params = {}) {
|
|
895
|
+
return this.http.get({
|
|
896
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/retention`,
|
|
897
|
+
query: {
|
|
898
|
+
startDate: params.startDate,
|
|
899
|
+
endDate: params.endDate
|
|
900
|
+
}
|
|
901
|
+
});
|
|
902
|
+
}
|
|
903
|
+
/**
|
|
904
|
+
* What listeners who connected through this soundlink went on to play.
|
|
905
|
+
*
|
|
906
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/listening-insights/{insight}`.
|
|
907
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
908
|
+
* Date window comes from the listening graph — do not send `startDate`/`endDate`.
|
|
909
|
+
* Uses a 120s timeout (insights often take 30–50s).
|
|
910
|
+
*/
|
|
911
|
+
listeningInsights(soundlinkId, insight) {
|
|
912
|
+
return this.http.get({
|
|
913
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/listening-insights/${encodeURIComponent(insight)}`,
|
|
914
|
+
timeout: LISTENING_INSIGHTS_TIMEOUT_MS
|
|
915
|
+
});
|
|
916
|
+
}
|
|
811
917
|
};
|
|
812
918
|
var SoundlinkBreakdownMetricsResource = class {
|
|
813
919
|
constructor(http) {
|
|
@@ -961,6 +1067,22 @@ var MetricsResource = class {
|
|
|
961
1067
|
}
|
|
962
1068
|
});
|
|
963
1069
|
}
|
|
1070
|
+
/**
|
|
1071
|
+
* Cohort retention for the campaign's linked soundlink (`soundlink_cohort_retention_daily`).
|
|
1072
|
+
*
|
|
1073
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/retention`.
|
|
1074
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
1075
|
+
* One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
|
|
1076
|
+
*/
|
|
1077
|
+
retention(campaignId, params = {}) {
|
|
1078
|
+
return this.http.get({
|
|
1079
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/retention`,
|
|
1080
|
+
query: {
|
|
1081
|
+
startDate: params.startDate,
|
|
1082
|
+
endDate: params.endDate
|
|
1083
|
+
}
|
|
1084
|
+
});
|
|
1085
|
+
}
|
|
964
1086
|
};
|
|
965
1087
|
var BreakdownMetricsResource = class {
|
|
966
1088
|
constructor(http) {
|
|
@@ -1034,6 +1156,8 @@ var Soundlink = class {
|
|
|
1034
1156
|
wallet;
|
|
1035
1157
|
/** Growth strategy catalog. Requires `campaigns:read` scope. */
|
|
1036
1158
|
strategies;
|
|
1159
|
+
/** Organization Meta pixels. Read needs `pixels:read`; write needs `pixels:write`. */
|
|
1160
|
+
pixels;
|
|
1037
1161
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
1038
1162
|
campaigns;
|
|
1039
1163
|
/** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
|
|
@@ -1051,6 +1175,7 @@ var Soundlink = class {
|
|
|
1051
1175
|
this.ping = pingResource.ping.bind(pingResource);
|
|
1052
1176
|
this.wallet = new WalletResource(http);
|
|
1053
1177
|
this.strategies = new StrategiesResource(http);
|
|
1178
|
+
this.pixels = new PixelsResource(http);
|
|
1054
1179
|
this.campaigns = new CampaignsResource(http);
|
|
1055
1180
|
this.soundlinks = new SoundlinksResource(http);
|
|
1056
1181
|
this.metrics = new MetricsResource(http);
|
|
@@ -1063,6 +1188,7 @@ exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
|
|
|
1063
1188
|
exports.DEFAULT_MAX_RETRIES = DEFAULT_MAX_RETRIES;
|
|
1064
1189
|
exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
|
|
1065
1190
|
exports.HttpClient = HttpClient;
|
|
1191
|
+
exports.LISTENING_INSIGHTS_TIMEOUT_MS = LISTENING_INSIGHTS_TIMEOUT_MS;
|
|
1066
1192
|
exports.METRICS_MAX_PAGE_SIZE = METRICS_MAX_PAGE_SIZE;
|
|
1067
1193
|
exports.SOUNDLINKS_MAX_PAGE_SIZE = SOUNDLINKS_MAX_PAGE_SIZE;
|
|
1068
1194
|
exports.Soundlink = Soundlink;
|