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 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)
@@ -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(url, {
208
- method: "GET",
209
- headers: this.buildHeaders()
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(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(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;