soundlink 2.12.0 → 2.14.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 +230 -7
- package/dist/cjs/api-emulator.cjs.map +1 -1
- package/dist/cjs/index.cjs +8 -6
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/api-emulator.d.ts +5 -5
- package/dist/esm/api-emulator.js +226 -9
- package/dist/esm/api-emulator.js.map +1 -1
- package/dist/esm/{api-C7t2QZ2d.d.ts → api-iOibHCWR.d.ts} +23 -2
- package/dist/esm/chunk-RQQ64IWI.js +14 -0
- package/dist/esm/chunk-RQQ64IWI.js.map +1 -0
- package/dist/esm/index.d.ts +9 -9
- package/dist/esm/index.js +11 -17
- package/dist/esm/index.js.map +1 -1
- package/docs/api-emulator.md +4 -3
- package/openapi/soundlink-public-api-v1.yaml +601 -29
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# soundlink
|
|
2
2
|
|
|
3
|
+
## 2.14.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#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.
|
|
8
|
+
|
|
9
|
+
## 2.13.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- [#50](https://github.com/Fan-ID/typescript-sdk/pull/50) [`2cefa2f`](https://github.com/Fan-ID/typescript-sdk/commit/2cefa2fa7f0b21557622dde3c19a4da852a19851) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add emulator pixel list, save, delete, and test-events. Keep `server_error` through the SDK default retries.
|
|
14
|
+
|
|
3
15
|
## 2.12.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)
|
|
@@ -14,7 +14,28 @@ function computeRefundGrossFromRawSpend(mediaSpendUsd, committedUsd, feeRate) {
|
|
|
14
14
|
const grossEquivSpend = rate > 0 ? mediaSpendUsd / (1 - rate) : mediaSpendUsd;
|
|
15
15
|
return Math.max(0, Number((committedUsd - grossEquivSpend).toFixed(2)));
|
|
16
16
|
}
|
|
17
|
+
|
|
18
|
+
// src/constants/defaults.ts
|
|
19
|
+
var DEFAULT_MAX_RETRIES = 2;
|
|
20
|
+
|
|
21
|
+
// src/emulator/store.ts
|
|
17
22
|
var ORG_EMULATOR_ID = "org_emulator";
|
|
23
|
+
var SERVER_ERROR_FAULT_RESPONSES = DEFAULT_MAX_RETRIES + 1;
|
|
24
|
+
function resolveFaultResponses(fault, maxRetries) {
|
|
25
|
+
if (fault !== "server_error") {
|
|
26
|
+
if (maxRetries !== void 0) {
|
|
27
|
+
return { ok: false, message: "maxRetries applies only to server_error." };
|
|
28
|
+
}
|
|
29
|
+
return { ok: true, responses: 1 };
|
|
30
|
+
}
|
|
31
|
+
if (maxRetries === void 0) {
|
|
32
|
+
return { ok: true, responses: SERVER_ERROR_FAULT_RESPONSES };
|
|
33
|
+
}
|
|
34
|
+
if (typeof maxRetries !== "number" || !Number.isInteger(maxRetries) || maxRetries < 0) {
|
|
35
|
+
return { ok: false, message: "maxRetries must be a non-negative integer." };
|
|
36
|
+
}
|
|
37
|
+
return { ok: true, responses: maxRetries + 1 };
|
|
38
|
+
}
|
|
18
39
|
function nowIso() {
|
|
19
40
|
return (/* @__PURE__ */ new Date()).toISOString();
|
|
20
41
|
}
|
|
@@ -85,7 +106,9 @@ function createEmulatorStore(options) {
|
|
|
85
106
|
let updatedAt = nowIso();
|
|
86
107
|
const campaigns = /* @__PURE__ */ new Map();
|
|
87
108
|
const idempotency = /* @__PURE__ */ new Map();
|
|
109
|
+
const pixels = /* @__PURE__ */ new Map();
|
|
88
110
|
let pendingFault = null;
|
|
111
|
+
let faultRemaining = 0;
|
|
89
112
|
const store = {
|
|
90
113
|
apiKey: options.apiKey,
|
|
91
114
|
feeRate: options.feeRate,
|
|
@@ -96,7 +119,9 @@ function createEmulatorStore(options) {
|
|
|
96
119
|
updatedAt = nowIso();
|
|
97
120
|
campaigns.clear();
|
|
98
121
|
idempotency.clear();
|
|
122
|
+
pixels.clear();
|
|
99
123
|
pendingFault = null;
|
|
124
|
+
faultRemaining = 0;
|
|
100
125
|
},
|
|
101
126
|
getWallet() {
|
|
102
127
|
return {
|
|
@@ -178,14 +203,52 @@ function createEmulatorStore(options) {
|
|
|
178
203
|
deleteIdempotency(key) {
|
|
179
204
|
idempotency.delete(key);
|
|
180
205
|
},
|
|
181
|
-
armFault(fault) {
|
|
206
|
+
armFault(fault, responses) {
|
|
207
|
+
if (pendingFault) {
|
|
208
|
+
return false;
|
|
209
|
+
}
|
|
182
210
|
pendingFault = fault;
|
|
211
|
+
faultRemaining = responses ?? (fault === "server_error" ? SERVER_ERROR_FAULT_RESPONSES : 1);
|
|
212
|
+
return true;
|
|
183
213
|
},
|
|
184
214
|
takeFault() {
|
|
215
|
+
if (!pendingFault || faultRemaining <= 0) {
|
|
216
|
+
return null;
|
|
217
|
+
}
|
|
185
218
|
const fault = pendingFault;
|
|
186
|
-
|
|
219
|
+
faultRemaining -= 1;
|
|
220
|
+
if (faultRemaining === 0) {
|
|
221
|
+
pendingFault = null;
|
|
222
|
+
}
|
|
187
223
|
return fault;
|
|
188
224
|
},
|
|
225
|
+
listPixels() {
|
|
226
|
+
return [...pixels.values()];
|
|
227
|
+
},
|
|
228
|
+
getPixel(pixelId) {
|
|
229
|
+
return pixels.get(pixelId);
|
|
230
|
+
},
|
|
231
|
+
findPixelByAccessToken(accessToken) {
|
|
232
|
+
for (const pixel of pixels.values()) {
|
|
233
|
+
if (pixel.accessToken === accessToken) {
|
|
234
|
+
return pixel;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
return void 0;
|
|
238
|
+
},
|
|
239
|
+
savePixel(pixel) {
|
|
240
|
+
if (pixel.isDefault) {
|
|
241
|
+
for (const existing of pixels.values()) {
|
|
242
|
+
if (existing.id !== pixel.id) {
|
|
243
|
+
existing.isDefault = false;
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
pixels.set(pixel.id, pixel);
|
|
248
|
+
},
|
|
249
|
+
deletePixel(pixelId) {
|
|
250
|
+
pixels.delete(pixelId);
|
|
251
|
+
},
|
|
189
252
|
toCampaignDetail(campaign) {
|
|
190
253
|
return {
|
|
191
254
|
campaignId: campaign.campaignId,
|
|
@@ -555,7 +618,7 @@ function dispatch(store, request) {
|
|
|
555
618
|
}
|
|
556
619
|
const fault = store.takeFault();
|
|
557
620
|
if (fault === "timeout") {
|
|
558
|
-
return { status:
|
|
621
|
+
return { status: 408, json: null, hang: true };
|
|
559
622
|
}
|
|
560
623
|
if (fault === "conflict") {
|
|
561
624
|
return failure(
|
|
@@ -584,6 +647,10 @@ function dispatch(store, request) {
|
|
|
584
647
|
]
|
|
585
648
|
});
|
|
586
649
|
}
|
|
650
|
+
const pixelResponse = dispatchPixel(store, method, pathname, request.body);
|
|
651
|
+
if (pixelResponse) {
|
|
652
|
+
return pixelResponse;
|
|
653
|
+
}
|
|
587
654
|
if (method === "GET" && pathname === "/v1/campaigns") {
|
|
588
655
|
const items = store.listCampaigns().map((campaign) => {
|
|
589
656
|
const detail = store.toCampaignDetail(campaign);
|
|
@@ -742,12 +809,150 @@ function handleStopCampaign(store, campaignId, request) {
|
|
|
742
809
|
});
|
|
743
810
|
return success(200, responseBody);
|
|
744
811
|
}
|
|
812
|
+
function toPublicPixel(pixel) {
|
|
813
|
+
return {
|
|
814
|
+
id: pixel.id,
|
|
815
|
+
platform: "meta",
|
|
816
|
+
isDefault: pixel.isDefault,
|
|
817
|
+
status: "ok",
|
|
818
|
+
lastErrorCode: null,
|
|
819
|
+
errorSince: null
|
|
820
|
+
};
|
|
821
|
+
}
|
|
822
|
+
function decodePixelId(raw) {
|
|
823
|
+
try {
|
|
824
|
+
return decodeURIComponent(raw).trim();
|
|
825
|
+
} catch {
|
|
826
|
+
return raw.trim();
|
|
827
|
+
}
|
|
828
|
+
}
|
|
829
|
+
function parsePixelBody(body) {
|
|
830
|
+
if (body === null || typeof body !== "object" || Array.isArray(body)) {
|
|
831
|
+
return { ok: false, message: "Request body must be a JSON object." };
|
|
832
|
+
}
|
|
833
|
+
const record = body;
|
|
834
|
+
const extra = Object.keys(record).filter(
|
|
835
|
+
(key) => key !== "platform" && key !== "accessToken" && key !== "isDefault"
|
|
836
|
+
);
|
|
837
|
+
const unknownKey = extra[0];
|
|
838
|
+
if (unknownKey) {
|
|
839
|
+
return {
|
|
840
|
+
ok: false,
|
|
841
|
+
message: `Invalid request body at body: Unrecognized key(s) in object: '${unknownKey}'.`
|
|
842
|
+
};
|
|
843
|
+
}
|
|
844
|
+
if (!("platform" in record)) {
|
|
845
|
+
return { ok: false, message: "Invalid request body at platform: Required." };
|
|
846
|
+
}
|
|
847
|
+
if (record.platform !== "meta") {
|
|
848
|
+
return {
|
|
849
|
+
ok: false,
|
|
850
|
+
message: 'Invalid request body at platform: Invalid literal value, expected "meta".'
|
|
851
|
+
};
|
|
852
|
+
}
|
|
853
|
+
let accessToken;
|
|
854
|
+
if ("accessToken" in record) {
|
|
855
|
+
if (typeof record.accessToken !== "string") {
|
|
856
|
+
return {
|
|
857
|
+
ok: false,
|
|
858
|
+
message: `Invalid request body at accessToken: Expected string, received ${typeof record.accessToken}.`
|
|
859
|
+
};
|
|
860
|
+
}
|
|
861
|
+
accessToken = record.accessToken.trim();
|
|
862
|
+
if (!accessToken) {
|
|
863
|
+
return {
|
|
864
|
+
ok: false,
|
|
865
|
+
message: "Invalid request body at accessToken: String must contain at least 1 character(s)."
|
|
866
|
+
};
|
|
867
|
+
}
|
|
868
|
+
}
|
|
869
|
+
let isDefault;
|
|
870
|
+
if ("isDefault" in record) {
|
|
871
|
+
if (typeof record.isDefault !== "boolean") {
|
|
872
|
+
return {
|
|
873
|
+
ok: false,
|
|
874
|
+
message: `Invalid request body at isDefault: Expected boolean, received ${typeof record.isDefault}.`
|
|
875
|
+
};
|
|
876
|
+
}
|
|
877
|
+
isDefault = record.isDefault;
|
|
878
|
+
}
|
|
879
|
+
if (accessToken === void 0 && isDefault === void 0) {
|
|
880
|
+
return {
|
|
881
|
+
ok: false,
|
|
882
|
+
message: "Invalid request body at accessToken: accessToken or isDefault is required."
|
|
883
|
+
};
|
|
884
|
+
}
|
|
885
|
+
return { ok: true, accessToken, isDefault };
|
|
886
|
+
}
|
|
887
|
+
function dispatchPixel(store, method, pathname, body) {
|
|
888
|
+
if (method === "GET" && pathname === "/v1/pixels") {
|
|
889
|
+
return success(200, {
|
|
890
|
+
pixels: store.listPixels().map(toPublicPixel)
|
|
891
|
+
});
|
|
892
|
+
}
|
|
893
|
+
const testPixelId = matchPathGroup(pathname, /^\/v1\/pixels\/([^/]+)\/test-events$/);
|
|
894
|
+
if (testPixelId !== void 0) {
|
|
895
|
+
if (method !== "POST") {
|
|
896
|
+
return failure(404, "not_found", "Not found.");
|
|
897
|
+
}
|
|
898
|
+
const pixelId2 = decodePixelId(testPixelId);
|
|
899
|
+
const pixel = pixelId2 ? store.getPixel(pixelId2) : void 0;
|
|
900
|
+
if (!pixel) {
|
|
901
|
+
return failure(404, "not_found", "Pixel not found.");
|
|
902
|
+
}
|
|
903
|
+
return success(200, { status: "sent", pixelId: pixel.id });
|
|
904
|
+
}
|
|
905
|
+
const rawPixelId = matchPathGroup(pathname, /^\/v1\/pixels\/([^/]+)$/);
|
|
906
|
+
if (rawPixelId === void 0) {
|
|
907
|
+
return null;
|
|
908
|
+
}
|
|
909
|
+
const pixelId = decodePixelId(rawPixelId);
|
|
910
|
+
if (!pixelId) {
|
|
911
|
+
return failure(400, "invalid_request", "pixelId is required.");
|
|
912
|
+
}
|
|
913
|
+
if (method === "PUT") {
|
|
914
|
+
const parsed = parsePixelBody(body);
|
|
915
|
+
if (!parsed.ok) {
|
|
916
|
+
return failure(400, "invalid_request", parsed.message);
|
|
917
|
+
}
|
|
918
|
+
const existing = store.getPixel(pixelId);
|
|
919
|
+
if (!existing && parsed.accessToken === void 0) {
|
|
920
|
+
return failure(404, "not_found", "Pixel not found.");
|
|
921
|
+
}
|
|
922
|
+
if (parsed.accessToken !== void 0) {
|
|
923
|
+
const owner = store.findPixelByAccessToken(parsed.accessToken);
|
|
924
|
+
if (owner && owner.id !== pixelId) {
|
|
925
|
+
return failure(
|
|
926
|
+
400,
|
|
927
|
+
"invalid_request",
|
|
928
|
+
"Access token is already in use with another pixel ID"
|
|
929
|
+
);
|
|
930
|
+
}
|
|
931
|
+
}
|
|
932
|
+
const saved = {
|
|
933
|
+
id: pixelId,
|
|
934
|
+
accessToken: parsed.accessToken ?? existing?.accessToken ?? "",
|
|
935
|
+
isDefault: parsed.isDefault ?? existing?.isDefault ?? false
|
|
936
|
+
};
|
|
937
|
+
store.savePixel(saved);
|
|
938
|
+
return success(200, toPublicPixel(saved));
|
|
939
|
+
}
|
|
940
|
+
if (method === "DELETE") {
|
|
941
|
+
if (!store.getPixel(pixelId)) {
|
|
942
|
+
return failure(404, "not_found", "Pixel not found.");
|
|
943
|
+
}
|
|
944
|
+
store.deletePixel(pixelId);
|
|
945
|
+
return { status: 204, json: null };
|
|
946
|
+
}
|
|
947
|
+
return failure(404, "not_found", "Not found.");
|
|
948
|
+
}
|
|
745
949
|
function isFault(value) {
|
|
746
950
|
return value === "timeout" || value === "conflict" || value === "server_error";
|
|
747
951
|
}
|
|
748
952
|
function dispatchHarness(store, method, pathname, body) {
|
|
749
953
|
if (method === "POST" && pathname === "/__emulator/fault") {
|
|
750
|
-
const
|
|
954
|
+
const record = body && typeof body === "object" ? body : void 0;
|
|
955
|
+
const fault = record?.fault;
|
|
751
956
|
if (!isFault(fault)) {
|
|
752
957
|
return failure(
|
|
753
958
|
400,
|
|
@@ -755,7 +960,14 @@ function dispatchHarness(store, method, pathname, body) {
|
|
|
755
960
|
"fault must be timeout | conflict | server_error."
|
|
756
961
|
);
|
|
757
962
|
}
|
|
758
|
-
|
|
963
|
+
const maxRetries = record?.maxRetries;
|
|
964
|
+
const resolved = resolveFaultResponses(fault, maxRetries);
|
|
965
|
+
if (!resolved.ok) {
|
|
966
|
+
return failure(400, "invalid_request", resolved.message);
|
|
967
|
+
}
|
|
968
|
+
if (!store.armFault(fault, resolved.responses)) {
|
|
969
|
+
return failure(400, "invalid_request", "A fault is already armed.");
|
|
970
|
+
}
|
|
759
971
|
return success(200, { fault });
|
|
760
972
|
}
|
|
761
973
|
if (method === "POST" && pathname === "/__emulator/reset") {
|
|
@@ -882,6 +1094,11 @@ function listen(store, options = {}) {
|
|
|
882
1094
|
return;
|
|
883
1095
|
}
|
|
884
1096
|
const response = dispatch(store, { method, path, headers, body });
|
|
1097
|
+
if (response.status === 204) {
|
|
1098
|
+
res.writeHead(204);
|
|
1099
|
+
res.end();
|
|
1100
|
+
return;
|
|
1101
|
+
}
|
|
885
1102
|
if (response.hang) {
|
|
886
1103
|
req.on("close", () => {
|
|
887
1104
|
if (!res.writableEnded) {
|
|
@@ -962,8 +1179,14 @@ function createApiEmulator(options = {}) {
|
|
|
962
1179
|
setWallet(balance) {
|
|
963
1180
|
return store.setWalletBalance(balance);
|
|
964
1181
|
},
|
|
965
|
-
failNext(fault) {
|
|
966
|
-
|
|
1182
|
+
failNext(fault, maxRetries) {
|
|
1183
|
+
const resolved2 = resolveFaultResponses(fault, maxRetries);
|
|
1184
|
+
if (!resolved2.ok) {
|
|
1185
|
+
throw new Error(resolved2.message);
|
|
1186
|
+
}
|
|
1187
|
+
if (!store.armFault(fault, resolved2.responses)) {
|
|
1188
|
+
throw new Error("A fault is already armed.");
|
|
1189
|
+
}
|
|
967
1190
|
},
|
|
968
1191
|
transition(campaignId, action, mediaSpendUsd) {
|
|
969
1192
|
return applyTransition(store, campaignId, action, mediaSpendUsd);
|