soundlink 1.0.0 → 1.1.1
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 +19 -0
- package/LICENSE +21 -0
- package/README.md +216 -0
- package/dist/cjs/index.cjs +627 -0
- package/dist/cjs/index.cjs.map +1 -0
- package/dist/esm/index.d.ts +536 -0
- package/dist/esm/index.js +613 -0
- package/dist/esm/index.js.map +1 -0
- package/openapi/soundlink-public-api-v1.yaml +1289 -0
- package/package.json +88 -7
- package/index.js +0 -1
|
@@ -0,0 +1,627 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// src/constants/defaults.ts
|
|
4
|
+
var DEFAULT_BASE_URL = "https://api.getsoundlink.com";
|
|
5
|
+
var DEFAULT_TIMEOUT_MS = 3e4;
|
|
6
|
+
var DEFAULT_MAX_RETRIES = 2;
|
|
7
|
+
var API_KEY_PREFIX = "sk_";
|
|
8
|
+
var CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
9
|
+
var METRICS_MAX_PAGE_SIZE = 500;
|
|
10
|
+
var API_VERSION_PREFIX = "/v1";
|
|
11
|
+
|
|
12
|
+
// src/core/api-response.ts
|
|
13
|
+
function isApiEnvelopeError(body) {
|
|
14
|
+
if (typeof body !== "object" || body === null) {
|
|
15
|
+
return false;
|
|
16
|
+
}
|
|
17
|
+
const record = body;
|
|
18
|
+
return typeof record.error === "object" && record.error !== null && typeof record.error.code === "string" && typeof record.error.message === "string";
|
|
19
|
+
}
|
|
20
|
+
function isApiEnvelopeSuccess(body) {
|
|
21
|
+
if (typeof body !== "object" || body === null) {
|
|
22
|
+
return false;
|
|
23
|
+
}
|
|
24
|
+
const record = body;
|
|
25
|
+
return "data" in record && typeof record.meta === "object" && record.meta !== null;
|
|
26
|
+
}
|
|
27
|
+
function toApiError(envelope, status, retryAfter) {
|
|
28
|
+
return {
|
|
29
|
+
code: envelope.error.code,
|
|
30
|
+
message: envelope.error.message,
|
|
31
|
+
status,
|
|
32
|
+
requestId: envelope.meta.requestId,
|
|
33
|
+
...retryAfter !== void 0 ? { retryAfter } : {}
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
function successResponse(data, meta) {
|
|
37
|
+
return {
|
|
38
|
+
data,
|
|
39
|
+
error: null,
|
|
40
|
+
meta
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
function errorResponse(error) {
|
|
44
|
+
return {
|
|
45
|
+
data: null,
|
|
46
|
+
error,
|
|
47
|
+
...error.requestId ? { meta: { requestId: error.requestId } } : {}
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
function parseRetryAfterHeader(value) {
|
|
51
|
+
if (!value) {
|
|
52
|
+
return void 0;
|
|
53
|
+
}
|
|
54
|
+
const seconds = Number.parseInt(value, 10);
|
|
55
|
+
if (Number.isFinite(seconds) && seconds >= 0) {
|
|
56
|
+
return seconds;
|
|
57
|
+
}
|
|
58
|
+
const dateMs = Date.parse(value);
|
|
59
|
+
if (Number.isFinite(dateMs)) {
|
|
60
|
+
const deltaSeconds = Math.ceil((dateMs - Date.now()) / 1e3);
|
|
61
|
+
return Math.max(deltaSeconds, 0);
|
|
62
|
+
}
|
|
63
|
+
return void 0;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// src/errors/sdk-error.ts
|
|
67
|
+
var SoundlinkSdkError = class _SoundlinkSdkError extends Error {
|
|
68
|
+
constructor(message) {
|
|
69
|
+
super(message);
|
|
70
|
+
this.name = "SoundlinkSdkError";
|
|
71
|
+
Object.setPrototypeOf(this, _SoundlinkSdkError.prototype);
|
|
72
|
+
}
|
|
73
|
+
};
|
|
74
|
+
var SoundlinkParseError = class _SoundlinkParseError extends SoundlinkSdkError {
|
|
75
|
+
constructor(message) {
|
|
76
|
+
super(message);
|
|
77
|
+
this.name = "SoundlinkParseError";
|
|
78
|
+
Object.setPrototypeOf(this, _SoundlinkParseError.prototype);
|
|
79
|
+
}
|
|
80
|
+
};
|
|
81
|
+
var SoundlinkConfigError = class _SoundlinkConfigError extends SoundlinkSdkError {
|
|
82
|
+
constructor(message) {
|
|
83
|
+
super(message);
|
|
84
|
+
this.name = "SoundlinkConfigError";
|
|
85
|
+
Object.setPrototypeOf(this, _SoundlinkConfigError.prototype);
|
|
86
|
+
}
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
// src/core/jsonl.ts
|
|
90
|
+
async function* parseNdjsonStream(body, onMalformedLine) {
|
|
91
|
+
if (!body) {
|
|
92
|
+
return;
|
|
93
|
+
}
|
|
94
|
+
const reader = body.getReader();
|
|
95
|
+
const decoder = new TextDecoder();
|
|
96
|
+
let buffer = "";
|
|
97
|
+
try {
|
|
98
|
+
for (; ; ) {
|
|
99
|
+
const { done, value } = await reader.read();
|
|
100
|
+
if (done) {
|
|
101
|
+
break;
|
|
102
|
+
}
|
|
103
|
+
buffer += decoder.decode(value, { stream: true });
|
|
104
|
+
const lines = buffer.split("\n");
|
|
105
|
+
buffer = lines.pop() ?? "";
|
|
106
|
+
for (const line of lines) {
|
|
107
|
+
const trimmed = line.trim();
|
|
108
|
+
if (!trimmed) {
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
try {
|
|
112
|
+
yield JSON.parse(trimmed);
|
|
113
|
+
} catch (error) {
|
|
114
|
+
onMalformedLine?.(trimmed, error);
|
|
115
|
+
throw new SoundlinkParseError("Failed to parse JSONL export line.");
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
const trailing = buffer.trim();
|
|
120
|
+
if (trailing) {
|
|
121
|
+
try {
|
|
122
|
+
yield JSON.parse(trailing);
|
|
123
|
+
} catch (error) {
|
|
124
|
+
onMalformedLine?.(trailing, error);
|
|
125
|
+
throw new SoundlinkParseError("Failed to parse JSONL export line.");
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
} finally {
|
|
129
|
+
reader.releaseLock();
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
async function collectNdjsonStream(stream) {
|
|
133
|
+
const rows = [];
|
|
134
|
+
for await (const row of stream) {
|
|
135
|
+
rows.push(row);
|
|
136
|
+
}
|
|
137
|
+
return {
|
|
138
|
+
rows,
|
|
139
|
+
rowCount: rows.length
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
// src/utils/query.ts
|
|
144
|
+
function buildQueryString(params) {
|
|
145
|
+
const searchParams = new URLSearchParams();
|
|
146
|
+
for (const [key, value] of Object.entries(params)) {
|
|
147
|
+
if (value === void 0 || value === null || value === "") {
|
|
148
|
+
continue;
|
|
149
|
+
}
|
|
150
|
+
searchParams.set(key, String(value));
|
|
151
|
+
}
|
|
152
|
+
const query = searchParams.toString();
|
|
153
|
+
return query ? `?${query}` : "";
|
|
154
|
+
}
|
|
155
|
+
function joinUrl(baseUrl, path) {
|
|
156
|
+
const normalizedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
|
|
157
|
+
const normalizedPath = path.startsWith("/") ? path : `/${path}`;
|
|
158
|
+
return `${normalizedBase}${normalizedPath}`;
|
|
159
|
+
}
|
|
160
|
+
function sleep(ms) {
|
|
161
|
+
return new Promise((resolve) => {
|
|
162
|
+
setTimeout(resolve, ms);
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
function calculateBackoffMs(attempt) {
|
|
166
|
+
const base = 250;
|
|
167
|
+
const jitter = Math.floor(Math.random() * 100);
|
|
168
|
+
return base * 2 ** attempt + jitter;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// src/client/http-client.ts
|
|
172
|
+
function resolveClientOptions(options) {
|
|
173
|
+
const normalized = typeof options === "string" ? { apiKey: options } : options;
|
|
174
|
+
const apiKey = normalized.apiKey.trim();
|
|
175
|
+
if (!apiKey) {
|
|
176
|
+
throw new SoundlinkConfigError("apiKey is required.");
|
|
177
|
+
}
|
|
178
|
+
if (!apiKey.startsWith(API_KEY_PREFIX)) {
|
|
179
|
+
throw new SoundlinkConfigError(
|
|
180
|
+
`Invalid API key format. Expected a key starting with "${API_KEY_PREFIX}".`
|
|
181
|
+
);
|
|
182
|
+
}
|
|
183
|
+
return {
|
|
184
|
+
apiKey,
|
|
185
|
+
baseUrl: normalized.baseUrl ?? DEFAULT_BASE_URL,
|
|
186
|
+
timeout: normalized.timeout ?? DEFAULT_TIMEOUT_MS,
|
|
187
|
+
maxRetries: normalized.maxRetries ?? DEFAULT_MAX_RETRIES,
|
|
188
|
+
fetch: normalized.fetch ?? globalThis.fetch.bind(globalThis)
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
var HttpClient = class {
|
|
192
|
+
options;
|
|
193
|
+
constructor(options) {
|
|
194
|
+
this.options = resolveClientOptions(options);
|
|
195
|
+
}
|
|
196
|
+
get resolvedOptions() {
|
|
197
|
+
return this.options;
|
|
198
|
+
}
|
|
199
|
+
async get({ path, query }) {
|
|
200
|
+
const url = joinUrl(
|
|
201
|
+
this.options.baseUrl,
|
|
202
|
+
`${API_VERSION_PREFIX}${path}${buildQueryString(query ?? {})}`
|
|
203
|
+
);
|
|
204
|
+
return this.requestJson(url, {
|
|
205
|
+
method: "GET",
|
|
206
|
+
headers: this.buildHeaders()
|
|
207
|
+
});
|
|
208
|
+
}
|
|
209
|
+
async getJsonl({
|
|
210
|
+
path,
|
|
211
|
+
query,
|
|
212
|
+
accept = "application/x-ndjson"
|
|
213
|
+
}) {
|
|
214
|
+
const url = joinUrl(
|
|
215
|
+
this.options.baseUrl,
|
|
216
|
+
`${API_VERSION_PREFIX}${path}${buildQueryString(query ?? {})}`
|
|
217
|
+
);
|
|
218
|
+
let response;
|
|
219
|
+
try {
|
|
220
|
+
response = await this.fetchWithRetry(url, {
|
|
221
|
+
method: "GET",
|
|
222
|
+
headers: {
|
|
223
|
+
...this.buildHeaders(),
|
|
224
|
+
Accept: accept
|
|
225
|
+
}
|
|
226
|
+
});
|
|
227
|
+
} catch (error) {
|
|
228
|
+
throw toTransportError(error);
|
|
229
|
+
}
|
|
230
|
+
const retryAfter = parseRetryAfterHeader(response.headers.get("Retry-After"));
|
|
231
|
+
if (!response.ok) {
|
|
232
|
+
return this.parseErrorEnvelope(response, retryAfter);
|
|
233
|
+
}
|
|
234
|
+
const contentType = response.headers.get("Content-Type") ?? "";
|
|
235
|
+
if (contentType.includes("application/json")) {
|
|
236
|
+
return this.parseErrorEnvelope(response, retryAfter);
|
|
237
|
+
}
|
|
238
|
+
const rowCountHeader = response.headers.get("X-Row-Count");
|
|
239
|
+
const parsedRowCount = rowCountHeader !== null ? Number.parseInt(rowCountHeader, 10) : void 0;
|
|
240
|
+
const stream = parseNdjsonStream(response.body);
|
|
241
|
+
const data = attachRowCountMetadata(stream, parsedRowCount);
|
|
242
|
+
return {
|
|
243
|
+
data,
|
|
244
|
+
error: null
|
|
245
|
+
};
|
|
246
|
+
}
|
|
247
|
+
buildHeaders() {
|
|
248
|
+
return {
|
|
249
|
+
"x-api-key": this.options.apiKey,
|
|
250
|
+
Accept: "application/json"
|
|
251
|
+
};
|
|
252
|
+
}
|
|
253
|
+
async requestJson(url, init) {
|
|
254
|
+
let response;
|
|
255
|
+
try {
|
|
256
|
+
response = await this.fetchWithRetry(url, init);
|
|
257
|
+
} catch (error) {
|
|
258
|
+
throw toTransportError(error);
|
|
259
|
+
}
|
|
260
|
+
const retryAfter = parseRetryAfterHeader(response.headers.get("Retry-After"));
|
|
261
|
+
if (!response.ok) {
|
|
262
|
+
return this.parseErrorEnvelope(response, retryAfter);
|
|
263
|
+
}
|
|
264
|
+
let body;
|
|
265
|
+
try {
|
|
266
|
+
body = await response.json();
|
|
267
|
+
} catch {
|
|
268
|
+
throw new SoundlinkParseError(
|
|
269
|
+
"Failed to parse JSON response from Soundlink API."
|
|
270
|
+
);
|
|
271
|
+
}
|
|
272
|
+
if (isApiEnvelopeError(body)) {
|
|
273
|
+
return errorResponse(toApiError(body, response.status, retryAfter));
|
|
274
|
+
}
|
|
275
|
+
if (isApiEnvelopeSuccess(body)) {
|
|
276
|
+
return successResponse(body.data, body.meta);
|
|
277
|
+
}
|
|
278
|
+
throw new SoundlinkParseError("Unexpected response shape from Soundlink API.");
|
|
279
|
+
}
|
|
280
|
+
async parseErrorEnvelope(response, retryAfter) {
|
|
281
|
+
let body = null;
|
|
282
|
+
try {
|
|
283
|
+
body = await response.json();
|
|
284
|
+
} catch {
|
|
285
|
+
return errorResponse({
|
|
286
|
+
code: "internal_error",
|
|
287
|
+
message: `Request failed with status ${String(response.status)}.`,
|
|
288
|
+
status: response.status,
|
|
289
|
+
...retryAfter !== void 0 ? { retryAfter } : {}
|
|
290
|
+
});
|
|
291
|
+
}
|
|
292
|
+
if (isApiEnvelopeError(body)) {
|
|
293
|
+
return errorResponse(toApiError(body, response.status, retryAfter));
|
|
294
|
+
}
|
|
295
|
+
return errorResponse({
|
|
296
|
+
code: "internal_error",
|
|
297
|
+
message: `Request failed with status ${String(response.status)}.`,
|
|
298
|
+
status: response.status,
|
|
299
|
+
...retryAfter !== void 0 ? { retryAfter } : {}
|
|
300
|
+
});
|
|
301
|
+
}
|
|
302
|
+
async fetchWithRetry(url, init) {
|
|
303
|
+
const { maxRetries, timeout, fetch } = this.options;
|
|
304
|
+
let attempt = 0;
|
|
305
|
+
let response = await fetch(url, {
|
|
306
|
+
...init,
|
|
307
|
+
signal: AbortSignal.timeout(timeout)
|
|
308
|
+
});
|
|
309
|
+
while (attempt < maxRetries && (response.status === 429 || response.status >= 500)) {
|
|
310
|
+
const retryAfter = parseRetryAfterHeader(response.headers.get("Retry-After"));
|
|
311
|
+
const delayMs = retryAfter !== void 0 ? retryAfter * 1e3 : calculateBackoffMs(attempt);
|
|
312
|
+
attempt += 1;
|
|
313
|
+
await sleep(delayMs);
|
|
314
|
+
response = await fetch(url, {
|
|
315
|
+
...init,
|
|
316
|
+
signal: AbortSignal.timeout(timeout)
|
|
317
|
+
});
|
|
318
|
+
}
|
|
319
|
+
return response;
|
|
320
|
+
}
|
|
321
|
+
};
|
|
322
|
+
function toTransportError(error) {
|
|
323
|
+
if (error instanceof Error) {
|
|
324
|
+
return new SoundlinkParseError(`Network request failed: ${error.message}`);
|
|
325
|
+
}
|
|
326
|
+
return new SoundlinkParseError("Network request failed.");
|
|
327
|
+
}
|
|
328
|
+
function attachRowCountMetadata(stream, rowCount) {
|
|
329
|
+
const jsonlStream = {
|
|
330
|
+
async *[Symbol.asyncIterator]() {
|
|
331
|
+
for await (const row of stream) {
|
|
332
|
+
yield row;
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
};
|
|
336
|
+
if (rowCount !== void 0 && !Number.isNaN(rowCount)) {
|
|
337
|
+
jsonlStream.rowCount = rowCount;
|
|
338
|
+
}
|
|
339
|
+
return jsonlStream;
|
|
340
|
+
}
|
|
341
|
+
function getStreamRowCount(stream) {
|
|
342
|
+
if (typeof stream === "object" && "rowCount" in stream) {
|
|
343
|
+
const value = stream.rowCount;
|
|
344
|
+
return typeof value === "number" ? value : void 0;
|
|
345
|
+
}
|
|
346
|
+
return void 0;
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
// src/resources/index.ts
|
|
350
|
+
function createExportResource(http, buildPath, buildQuery) {
|
|
351
|
+
const exportFn = ((campaignId, params = {}) => {
|
|
352
|
+
return http.getJsonl({
|
|
353
|
+
path: buildPath(campaignId),
|
|
354
|
+
query: buildQuery(params)
|
|
355
|
+
});
|
|
356
|
+
});
|
|
357
|
+
exportFn.collect = async (campaignId, params = {}) => {
|
|
358
|
+
const response = await exportFn(campaignId, params);
|
|
359
|
+
if (response.error || !response.data) {
|
|
360
|
+
return {
|
|
361
|
+
data: null,
|
|
362
|
+
error: response.error,
|
|
363
|
+
meta: response.meta
|
|
364
|
+
};
|
|
365
|
+
}
|
|
366
|
+
const collected = await collectNdjsonStream(response.data);
|
|
367
|
+
return {
|
|
368
|
+
data: collected,
|
|
369
|
+
error: null,
|
|
370
|
+
meta: response.meta
|
|
371
|
+
};
|
|
372
|
+
};
|
|
373
|
+
return exportFn;
|
|
374
|
+
}
|
|
375
|
+
var PingResource = class {
|
|
376
|
+
constructor(http) {
|
|
377
|
+
this.http = http;
|
|
378
|
+
}
|
|
379
|
+
http;
|
|
380
|
+
/**
|
|
381
|
+
* Verify connectivity and API key authentication.
|
|
382
|
+
*
|
|
383
|
+
* Accepts any valid v1 key scope. Does not require `campaigns:read` or `metrics:read`.
|
|
384
|
+
*
|
|
385
|
+
* @returns `{ data: { status: 'ok' }, error: null }` on success.
|
|
386
|
+
*
|
|
387
|
+
* @example
|
|
388
|
+
* ```ts
|
|
389
|
+
* const { data, error, meta } = await soundlink.ping();
|
|
390
|
+
* ```
|
|
391
|
+
*/
|
|
392
|
+
ping() {
|
|
393
|
+
return this.http.get({ path: "/ping" });
|
|
394
|
+
}
|
|
395
|
+
};
|
|
396
|
+
var CampaignsResource = class {
|
|
397
|
+
constructor(http) {
|
|
398
|
+
this.http = http;
|
|
399
|
+
}
|
|
400
|
+
http;
|
|
401
|
+
/**
|
|
402
|
+
* List campaigns for the authenticated organization.
|
|
403
|
+
*
|
|
404
|
+
* Maps to `GET /v1/campaigns`. Max `pageSize` is **100**.
|
|
405
|
+
*
|
|
406
|
+
* @param params - Pagination and sort options.
|
|
407
|
+
*
|
|
408
|
+
* @example
|
|
409
|
+
* ```ts
|
|
410
|
+
* const { data, error } = await soundlink.campaigns.list({ page: 1, pageSize: 100 });
|
|
411
|
+
* ```
|
|
412
|
+
*/
|
|
413
|
+
list(params = {}) {
|
|
414
|
+
return this.http.get({
|
|
415
|
+
path: "/campaigns",
|
|
416
|
+
query: {
|
|
417
|
+
page: params.page,
|
|
418
|
+
pageSize: params.pageSize,
|
|
419
|
+
sortBy: params.sortBy,
|
|
420
|
+
sortOrder: params.sortOrder
|
|
421
|
+
}
|
|
422
|
+
});
|
|
423
|
+
}
|
|
424
|
+
/**
|
|
425
|
+
* Fetch full details for a single campaign.
|
|
426
|
+
*
|
|
427
|
+
* Maps to `GET /v1/campaigns/{campaignId}`.
|
|
428
|
+
*
|
|
429
|
+
* @param campaignId - Campaign identifier returned by {@link CampaignsResource.list}.
|
|
430
|
+
*/
|
|
431
|
+
get(campaignId) {
|
|
432
|
+
return this.http.get({
|
|
433
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}`
|
|
434
|
+
});
|
|
435
|
+
}
|
|
436
|
+
/**
|
|
437
|
+
* Async iterator over every campaign across all pages.
|
|
438
|
+
*
|
|
439
|
+
* Stops silently if a page request returns an error.
|
|
440
|
+
*
|
|
441
|
+
* @param params - Same as {@link CampaignsResource.list} except `page` is managed automatically.
|
|
442
|
+
*
|
|
443
|
+
* @example
|
|
444
|
+
* ```ts
|
|
445
|
+
* for await (const campaign of soundlink.campaigns.listAll({ pageSize: 100 })) {
|
|
446
|
+
* console.log(campaign.campaignId);
|
|
447
|
+
* }
|
|
448
|
+
* ```
|
|
449
|
+
*/
|
|
450
|
+
async *listAll(params = {}) {
|
|
451
|
+
let page = 1;
|
|
452
|
+
let totalPages = 1;
|
|
453
|
+
while (page <= totalPages) {
|
|
454
|
+
const response = await this.list({ ...params, page });
|
|
455
|
+
if (response.error || !response.data) {
|
|
456
|
+
return;
|
|
457
|
+
}
|
|
458
|
+
for (const item of response.data.items) {
|
|
459
|
+
yield item;
|
|
460
|
+
}
|
|
461
|
+
totalPages = response.data.pagination.totalPages;
|
|
462
|
+
page += 1;
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
};
|
|
466
|
+
var MetricsResource = class {
|
|
467
|
+
constructor(http) {
|
|
468
|
+
this.http = http;
|
|
469
|
+
this.breakdown = new BreakdownMetricsResource(http);
|
|
470
|
+
this.engagement = new EngagementMetricsResource(http);
|
|
471
|
+
}
|
|
472
|
+
http;
|
|
473
|
+
/** Per-day country breakdown and JSONL export. */
|
|
474
|
+
breakdown;
|
|
475
|
+
/** Per-track engagement breakdown and JSONL export. */
|
|
476
|
+
engagement;
|
|
477
|
+
/**
|
|
478
|
+
* Campaign-level metric totals for a date range.
|
|
479
|
+
*
|
|
480
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/overview`.
|
|
481
|
+
* Aggregates across all countries — use {@link BreakdownMetricsResource.list} for daily rows.
|
|
482
|
+
*
|
|
483
|
+
* @param campaignId - Campaign identifier.
|
|
484
|
+
* @param params - Inclusive `YYYY-MM-DD` date range. Omit for API defaults.
|
|
485
|
+
*
|
|
486
|
+
* @example
|
|
487
|
+
* ```ts
|
|
488
|
+
* const { data } = await soundlink.metrics.overview(campaignId, {
|
|
489
|
+
* startDate: '2026-01-01',
|
|
490
|
+
* endDate: '2026-03-31',
|
|
491
|
+
* });
|
|
492
|
+
* ```
|
|
493
|
+
*/
|
|
494
|
+
overview(campaignId, params = {}) {
|
|
495
|
+
return this.http.get({
|
|
496
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/overview`,
|
|
497
|
+
query: {
|
|
498
|
+
startDate: params.startDate,
|
|
499
|
+
endDate: params.endDate
|
|
500
|
+
}
|
|
501
|
+
});
|
|
502
|
+
}
|
|
503
|
+
};
|
|
504
|
+
var BreakdownMetricsResource = class {
|
|
505
|
+
constructor(http) {
|
|
506
|
+
this.http = http;
|
|
507
|
+
this.export = createExportResource(
|
|
508
|
+
http,
|
|
509
|
+
(campaignId) => `/campaigns/${encodeURIComponent(campaignId)}/metrics/breakdown/export`,
|
|
510
|
+
(params) => ({
|
|
511
|
+
startDate: params.startDate,
|
|
512
|
+
endDate: params.endDate
|
|
513
|
+
})
|
|
514
|
+
);
|
|
515
|
+
}
|
|
516
|
+
http;
|
|
517
|
+
/**
|
|
518
|
+
* Stream full breakdown export as JSONL.
|
|
519
|
+
*
|
|
520
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown/export`.
|
|
521
|
+
*/
|
|
522
|
+
export;
|
|
523
|
+
/**
|
|
524
|
+
* Paginated per-day, per-country breakdown rows.
|
|
525
|
+
*
|
|
526
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown`.
|
|
527
|
+
* Max `pageSize` is **500** (default 50).
|
|
528
|
+
*
|
|
529
|
+
* @param campaignId - Campaign identifier.
|
|
530
|
+
* @param params - Date range, pagination, and sort options.
|
|
531
|
+
*/
|
|
532
|
+
list(campaignId, params = {}) {
|
|
533
|
+
return this.http.get({
|
|
534
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/breakdown`,
|
|
535
|
+
query: {
|
|
536
|
+
startDate: params.startDate,
|
|
537
|
+
endDate: params.endDate,
|
|
538
|
+
page: params.page,
|
|
539
|
+
pageSize: params.pageSize,
|
|
540
|
+
sortBy: params.sortBy,
|
|
541
|
+
sortOrder: params.sortOrder
|
|
542
|
+
}
|
|
543
|
+
});
|
|
544
|
+
}
|
|
545
|
+
};
|
|
546
|
+
var EngagementMetricsResource = class {
|
|
547
|
+
constructor(http) {
|
|
548
|
+
this.http = http;
|
|
549
|
+
this.export = createExportResource(
|
|
550
|
+
http,
|
|
551
|
+
(campaignId) => `/campaigns/${encodeURIComponent(campaignId)}/metrics/engagement/export`,
|
|
552
|
+
(params) => ({
|
|
553
|
+
startDate: params.startDate,
|
|
554
|
+
endDate: params.endDate,
|
|
555
|
+
engagementContext: params.engagementContext
|
|
556
|
+
})
|
|
557
|
+
);
|
|
558
|
+
}
|
|
559
|
+
http;
|
|
560
|
+
/**
|
|
561
|
+
* Stream full engagement export as JSONL.
|
|
562
|
+
*
|
|
563
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/engagement/export`.
|
|
564
|
+
*/
|
|
565
|
+
export;
|
|
566
|
+
/**
|
|
567
|
+
* Paginated per-day, per-track engagement rows.
|
|
568
|
+
*
|
|
569
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/engagement`.
|
|
570
|
+
* Max `pageSize` is **500** (default 50).
|
|
571
|
+
*
|
|
572
|
+
* @param campaignId - Campaign identifier.
|
|
573
|
+
* @param params - Date range, pagination, sort, and optional `engagementContext` filter.
|
|
574
|
+
*/
|
|
575
|
+
list(campaignId, params = {}) {
|
|
576
|
+
return this.http.get({
|
|
577
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/engagement`,
|
|
578
|
+
query: {
|
|
579
|
+
startDate: params.startDate,
|
|
580
|
+
endDate: params.endDate,
|
|
581
|
+
page: params.page,
|
|
582
|
+
pageSize: params.pageSize,
|
|
583
|
+
sortBy: params.sortBy,
|
|
584
|
+
sortOrder: params.sortOrder,
|
|
585
|
+
engagementContext: params.engagementContext
|
|
586
|
+
}
|
|
587
|
+
});
|
|
588
|
+
}
|
|
589
|
+
};
|
|
590
|
+
|
|
591
|
+
// src/client/soundlink.ts
|
|
592
|
+
var Soundlink = class {
|
|
593
|
+
/** Verify connectivity and authentication. Maps to `GET /v1/ping`. */
|
|
594
|
+
ping;
|
|
595
|
+
/** List and fetch campaigns. Requires `campaigns:read` scope. */
|
|
596
|
+
campaigns;
|
|
597
|
+
/** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
|
|
598
|
+
metrics;
|
|
599
|
+
/**
|
|
600
|
+
* Create a Soundlink client.
|
|
601
|
+
*
|
|
602
|
+
* @param options - API key string (`sk_*`) or {@link SoundlinkClientOptions}.
|
|
603
|
+
*/
|
|
604
|
+
constructor(options) {
|
|
605
|
+
const http = new HttpClient(options);
|
|
606
|
+
const pingResource = new PingResource(http);
|
|
607
|
+
this.ping = pingResource.ping.bind(pingResource);
|
|
608
|
+
this.campaigns = new CampaignsResource(http);
|
|
609
|
+
this.metrics = new MetricsResource(http);
|
|
610
|
+
}
|
|
611
|
+
};
|
|
612
|
+
|
|
613
|
+
exports.API_KEY_PREFIX = API_KEY_PREFIX;
|
|
614
|
+
exports.CAMPAIGNS_MAX_PAGE_SIZE = CAMPAIGNS_MAX_PAGE_SIZE;
|
|
615
|
+
exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
|
|
616
|
+
exports.DEFAULT_MAX_RETRIES = DEFAULT_MAX_RETRIES;
|
|
617
|
+
exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
|
|
618
|
+
exports.HttpClient = HttpClient;
|
|
619
|
+
exports.METRICS_MAX_PAGE_SIZE = METRICS_MAX_PAGE_SIZE;
|
|
620
|
+
exports.Soundlink = Soundlink;
|
|
621
|
+
exports.SoundlinkConfigError = SoundlinkConfigError;
|
|
622
|
+
exports.SoundlinkParseError = SoundlinkParseError;
|
|
623
|
+
exports.SoundlinkSdkError = SoundlinkSdkError;
|
|
624
|
+
exports.getStreamRowCount = getStreamRowCount;
|
|
625
|
+
exports.resolveClientOptions = resolveClientOptions;
|
|
626
|
+
//# sourceMappingURL=index.cjs.map
|
|
627
|
+
//# sourceMappingURL=index.cjs.map
|