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 +12 -0
- package/README.md +5 -1
- package/dist/cjs/api-emulator.cjs +110 -3
- package/dist/cjs/api-emulator.cjs.map +1 -1
- package/dist/cjs/index.cjs +20 -6
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/{api-C7t2QZ2d.d.ts → api-CuAH3b0I.d.ts} +38 -2
- package/dist/esm/api-emulator.d.ts +4 -2
- package/dist/esm/api-emulator.js +110 -3
- package/dist/esm/api-emulator.js.map +1 -1
- package/dist/esm/index.d.ts +16 -9
- package/dist/esm/index.js +20 -6
- package/dist/esm/index.js.map +1 -1
- package/docs/api-emulator.md +20 -10
- package/openapi/soundlink-public-api-v1.yaml +616 -29
- package/package.json +1 -1
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 {
|