soundlink 2.13.0 → 2.15.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.15.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#54](https://github.com/Fan-ID/typescript-sdk/pull/54) [`12ace94`](https://github.com/Fan-ID/typescript-sdk/commit/12ace946f1a2d33cc168e3c11e4ff4c300103add) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add optional `delivery_state` on creative metrics children (`disapproved` | `null`, omitted on older APIs). Expose `metrics.creativesBatch`, and teach the local API emulator `GET/POST` creatives metrics plus a `disapprove_creatives` harness transition for integrator tests. Prefer `== null` until every environment returns the field.
8
+
9
+ ## 2.14.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#52](https://github.com/Fan-ID/typescript-sdk/pull/52) [`e31f085`](https://github.com/Fan-ID/typescript-sdk/commit/e31f085287d53ae1484e454dd21f6950a58fd36a) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Support daily cohort retention schema 1.1: optional `groupBy: 'country'`, `country_code`, and `streams_on_day_N` on campaign and soundlink `retention()`. Release only after backend SOU-7646 is deployed — older APIs ignore `groupBy` and omit the new fields.
14
+
3
15
  ## 2.13.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -227,7 +227,9 @@ const { data: engagement } = await soundlink.soundlinks.engagement.list('sl_abc1
227
227
  // JSONL: soundlinks.breakdown.export / soundlinks.engagement.export (same pattern as Metrics below)
228
228
 
229
229
  // Premium: cohort retention + listening insights (same as Metrics section)
230
- const { data: retention } = await soundlink.soundlinks.retention('sl_abc123');
230
+ const { data: retention } = await soundlink.soundlinks.retention('sl_abc123', {
231
+ groupBy: 'country', // optional; omit for the global rollup (requires API schema 1.1+)
232
+ });
231
233
  const { data: insight } = await soundlink.soundlinks.listeningInsights(
232
234
  'sl_abc123',
233
235
  'stream-split',
@@ -256,9 +258,11 @@ const { data: breakdown } = await soundlink.metrics.breakdown.list('camp_abc123'
256
258
  });
257
259
 
258
260
  // Cohort retention — premium plan (`403 premium_plan_required` otherwise)
261
+ // Requires Public API daily retention schema 1.1+ (backend SOU-7646).
259
262
  const { data: retention } = await soundlink.metrics.retention('camp_abc123', {
260
263
  startDate: '2026-08-01',
261
264
  endDate: '2026-08-31',
265
+ groupBy: 'country', // optional; omit for the global rollup
262
266
  });
263
267
 
264
268
  // Listening insights — premium; SDK uses a 120s timeout (API often takes 30–50s)
@@ -170,7 +170,8 @@ function createEmulatorStore(options) {
170
170
  trackName: ids.trackId ? "Emulator Track" : null,
171
171
  createdAt: timestamp,
172
172
  updatedAt: timestamp,
173
- overview: null
173
+ overview: null,
174
+ partnerUploadDisapproved: false
174
175
  };
175
176
  campaigns.set(campaignId, record);
176
177
  return record;
@@ -287,6 +288,48 @@ function createEmulatorStore(options) {
287
288
  cpl: listeners > 0 ? Number((spendMedia / listeners).toFixed(4)) : 0,
288
289
  cpf: followers > 0 ? Number((spendMedia / followers).toFixed(4)) : 0
289
290
  };
291
+ },
292
+ buildCreatives(campaign) {
293
+ const overview = store.buildOverview(campaign);
294
+ const listeners = overview.listeners;
295
+ const followers = overview.followers;
296
+ const linkClicks = overview.link_clicks ?? 0;
297
+ const spendMedia = overview.spend_media;
298
+ const cpl = listeners > 0 ? Number((spendMedia / listeners).toFixed(4)) : 0;
299
+ const cpf = followers > 0 ? Number((spendMedia / followers).toFixed(4)) : 0;
300
+ const cpcLinkclick = linkClicks > 0 ? Number((spendMedia / linkClicks).toFixed(4)) : 0;
301
+ const deliveryState = campaign.partnerUploadDisapproved ? "disapproved" : null;
302
+ const child = {
303
+ caption: "Emulator partner upload",
304
+ language: "en",
305
+ spotify_track_id: campaign.trackId ?? "emulator_track",
306
+ timestamp_start_ms: null,
307
+ timestamp_end_ms: null,
308
+ listeners,
309
+ followers,
310
+ link_clicks: linkClicks,
311
+ cpl,
312
+ cpf,
313
+ cpc_linkclick: cpcLinkclick,
314
+ frequency: 1,
315
+ delivery_state: deliveryState
316
+ };
317
+ return {
318
+ creatives: [
319
+ {
320
+ video_id: "emu_partner_upload_video",
321
+ caption: child.caption,
322
+ listeners,
323
+ followers,
324
+ link_clicks: linkClicks,
325
+ cpl,
326
+ cpf,
327
+ cpc_linkclick: cpcLinkclick,
328
+ frequency: 1,
329
+ children: [child]
330
+ }
331
+ ]
332
+ };
290
333
  }
291
334
  };
292
335
  return store;
@@ -403,6 +446,11 @@ function applyTransition(store, campaignId, action, mediaSpendUsd) {
403
446
  store.updateCampaign(campaign);
404
447
  break;
405
448
  }
449
+ case "disapprove_creatives": {
450
+ campaign.partnerUploadDisapproved = true;
451
+ store.updateCampaign(campaign);
452
+ break;
453
+ }
406
454
  default: {
407
455
  const _exhaustive = action;
408
456
  throw new TransitionError(
@@ -515,8 +563,9 @@ function readIdempotencyKey(headers) {
515
563
  return { key };
516
564
  }
517
565
  function isTransitionAction(value) {
518
- return value === "activate" || value === "reject_meta" || value === "set_spend" || value === "end";
566
+ return value === "activate" || value === "reject_meta" || value === "set_spend" || value === "end" || value === "disapprove_creatives";
519
567
  }
568
+ var CREATIVES_BATCH_MAX_IDS = 50;
520
569
  var BUILT_IN_STRATEGIES = [
521
570
  "maximum_growth",
522
571
  "market_discovery",
@@ -702,6 +751,64 @@ function dispatch(store, request) {
702
751
  }
703
752
  return success(200, store.buildOverview(campaign));
704
753
  }
754
+ const creativesCampaignId = matchPathGroup(
755
+ pathname,
756
+ /^\/v1\/campaigns\/([^/]+)\/metrics\/creatives$/
757
+ );
758
+ if (method === "GET" && creativesCampaignId) {
759
+ const campaign = store.getCampaign(decodeURIComponent(creativesCampaignId));
760
+ if (!campaign) {
761
+ return failure(404, "campaign_not_found", "Campaign not found.");
762
+ }
763
+ return success(200, store.buildCreatives(campaign));
764
+ }
765
+ if (method === "POST" && pathname === "/v1/campaigns/metrics/creatives/batch") {
766
+ if (request.body === null || typeof request.body !== "object" || Array.isArray(request.body)) {
767
+ return failure(400, "invalid_request", "Request body must be a JSON object.");
768
+ }
769
+ const body = request.body;
770
+ if (body.startDate !== void 0 || body.endDate !== void 0) {
771
+ return failure(
772
+ 400,
773
+ "invalid_request",
774
+ "startDate and endDate are not supported. This endpoint returns a lifetime snapshot."
775
+ );
776
+ }
777
+ const campaignIds = body.campaignIds;
778
+ if (!Array.isArray(campaignIds) || campaignIds.length === 0) {
779
+ return failure(400, "invalid_request", "campaignIds must be a non-empty array.");
780
+ }
781
+ if (campaignIds.length > CREATIVES_BATCH_MAX_IDS) {
782
+ return failure(
783
+ 400,
784
+ "invalid_request",
785
+ `campaignIds must contain at most ${String(CREATIVES_BATCH_MAX_IDS)} ids.`
786
+ );
787
+ }
788
+ if (!campaignIds.every(
789
+ (id) => typeof id === "string" && id.trim().length > 0
790
+ )) {
791
+ return failure(
792
+ 400,
793
+ "invalid_request",
794
+ "campaignIds must contain non-empty strings."
795
+ );
796
+ }
797
+ const uniqueIds = [...new Set(campaignIds)];
798
+ const items = uniqueIds.flatMap((campaignId) => {
799
+ const campaign = store.getCampaign(campaignId);
800
+ if (!campaign) {
801
+ return [];
802
+ }
803
+ return [
804
+ {
805
+ campaignId,
806
+ creatives: store.buildCreatives(campaign).creatives
807
+ }
808
+ ];
809
+ });
810
+ return success(200, { items });
811
+ }
705
812
  if (method === "POST" && pathname === "/v1/campaigns") {
706
813
  return handleCreateCampaign(store, request);
707
814
  }
@@ -993,7 +1100,7 @@ function dispatchHarness(store, method, pathname, body) {
993
1100
  return failure(
994
1101
  400,
995
1102
  "invalid_request",
996
- "action must be activate | reject_meta | set_spend | end."
1103
+ "action must be activate | reject_meta | set_spend | end | disapprove_creatives."
997
1104
  );
998
1105
  }
999
1106
  try {