soundlink 2.9.0 → 2.11.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 +16 -0
- package/README.md +36 -1
- package/dist/cjs/api-emulator.cjs +934 -0
- package/dist/cjs/api-emulator.cjs.map +1 -0
- package/dist/esm/api-C7t2QZ2d.d.ts +877 -0
- package/dist/esm/api-emulator.d.ts +127 -0
- package/dist/esm/api-emulator.js +930 -0
- package/dist/esm/api-emulator.js.map +1 -0
- package/dist/esm/index.d.ts +3 -863
- package/docs/api-emulator.md +216 -0
- package/openapi/soundlink-public-api-v1.yaml +40 -3
- package/package.json +12 -1
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# Public API emulator
|
|
2
|
+
|
|
3
|
+
Local, stateful stand-in for the Soundlink Public API. Use it in automated tests for wallet campaign flows without Meta spend or a hosted sandbox.
|
|
4
|
+
|
|
5
|
+
Import: `soundlink/api-emulator` (not re-exported from `soundlink`).
|
|
6
|
+
|
|
7
|
+
Works with the SDK **or** plain `fetch` / curl — anything that can hit HTTP on the same machine.
|
|
8
|
+
|
|
9
|
+
## Quick start (SDK)
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { Soundlink } from 'soundlink';
|
|
13
|
+
import { createApiEmulator } from 'soundlink/api-emulator';
|
|
14
|
+
|
|
15
|
+
const apiKey = 'sk_emulator_test';
|
|
16
|
+
const emu = createApiEmulator({
|
|
17
|
+
apiKey,
|
|
18
|
+
initialWalletBalance: 500,
|
|
19
|
+
plan: 'enterprise', // optional — sets the paid-campaign fee
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
const server = await emu.listen(); // 127.0.0.1 only
|
|
23
|
+
const soundlink = new Soundlink({ apiKey, baseUrl: server.baseUrl });
|
|
24
|
+
|
|
25
|
+
const { data: created } = await soundlink.campaigns.create(
|
|
26
|
+
{
|
|
27
|
+
spotifyUrl: 'https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh',
|
|
28
|
+
dailyBudget: 10,
|
|
29
|
+
durationDays: 7,
|
|
30
|
+
genre: 'Pop',
|
|
31
|
+
strategyType: 'maximum_growth',
|
|
32
|
+
},
|
|
33
|
+
{ idempotencyKey: 'demo-1' },
|
|
34
|
+
);
|
|
35
|
+
|
|
36
|
+
await emu.transition(created!.campaignId, 'activate');
|
|
37
|
+
await soundlink.metrics.overview(created!.campaignId);
|
|
38
|
+
await soundlink.campaigns.stop(created!.campaignId, {
|
|
39
|
+
idempotencyKey: 'stop-1',
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
await server.close();
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Same lifecycle without TCP: `emu.dispatch({ method, path, headers, body })`.
|
|
46
|
+
|
|
47
|
+
## Use from another process (fetch / curl)
|
|
48
|
+
|
|
49
|
+
`listen` is a normal HTTP server on **loopback only**. Fix the port, keep the process alive, call it from any other local codebase — no SDK required on the client side.
|
|
50
|
+
|
|
51
|
+
**Process A** (starts the emulator — needs `soundlink`):
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { createApiEmulator } from 'soundlink/api-emulator';
|
|
55
|
+
|
|
56
|
+
const apiKey = 'sk_emulator_test';
|
|
57
|
+
const emu = createApiEmulator({
|
|
58
|
+
apiKey,
|
|
59
|
+
initialWalletBalance: 500,
|
|
60
|
+
plan: 'enterprise',
|
|
61
|
+
});
|
|
62
|
+
const server = await emu.listen({ port: 8787 });
|
|
63
|
+
console.log(`api-emulator at ${server.baseUrl}`);
|
|
64
|
+
// leave this process running
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**Process B** (your app, tests, curl — same machine):
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
const base = 'http://127.0.0.1:8787';
|
|
71
|
+
const apiKey = 'sk_emulator_test';
|
|
72
|
+
|
|
73
|
+
const created = await fetch(`${base}/v1/campaigns`, {
|
|
74
|
+
method: 'POST',
|
|
75
|
+
headers: {
|
|
76
|
+
Authorization: `Bearer ${apiKey}`,
|
|
77
|
+
'Content-Type': 'application/json',
|
|
78
|
+
'Idempotency-Key': 'demo-1',
|
|
79
|
+
},
|
|
80
|
+
body: JSON.stringify({
|
|
81
|
+
spotifyUrl: 'https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh',
|
|
82
|
+
dailyBudget: 10,
|
|
83
|
+
durationDays: 7,
|
|
84
|
+
genre: 'Pop',
|
|
85
|
+
strategyType: 'maximum_growth',
|
|
86
|
+
}),
|
|
87
|
+
}).then((r) => r.json());
|
|
88
|
+
|
|
89
|
+
const campaignId = created.data.campaignId;
|
|
90
|
+
|
|
91
|
+
await fetch(`${base}/__emulator/campaigns/${campaignId}/transition`, {
|
|
92
|
+
method: 'POST',
|
|
93
|
+
headers: { 'Content-Type': 'application/json' },
|
|
94
|
+
body: JSON.stringify({ action: 'activate' }),
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
await fetch(`${base}/v1/campaigns/${campaignId}`, {
|
|
98
|
+
headers: { Authorization: `Bearer ${apiKey}` },
|
|
99
|
+
}).then((r) => r.json());
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
curl -s http://127.0.0.1:8787/v1/ping -H "Authorization: Bearer sk_emulator_test"
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Limits: bind is always `127.0.0.1` (not reachable from other machines / default Docker networks without host networking). Harness routes (`/__emulator/*`) have no auth — that is why listen refuses non-loopback hosts.
|
|
107
|
+
|
|
108
|
+
## Lifecycle
|
|
109
|
+
|
|
110
|
+
| Step | How |
|
|
111
|
+
| ---------- | ----------------------------------------------------------------------------- |
|
|
112
|
+
| Create | `POST /v1/campaigns` — debits `dailyBudget × durationDays`, status `creating` |
|
|
113
|
+
| Activate | harness `activate` → `active` + seeded metrics |
|
|
114
|
+
| Spend | harness `set_spend` with `{ mediaSpendUsd }` (0 … committed) |
|
|
115
|
+
| Stop / end | public `stop` or harness `end` → refunds unspent gross |
|
|
116
|
+
|
|
117
|
+
Wallet after settle: `reserved === 0`, `available === balance`.
|
|
118
|
+
|
|
119
|
+
## Harness
|
|
120
|
+
|
|
121
|
+
No auth. Prefer `emu.transition` / `emu.setWallet` / `emu.reset` in-process when you own the Node process.
|
|
122
|
+
|
|
123
|
+
| Action | Effect |
|
|
124
|
+
| ------------------------- | ---------------------------------------------------- |
|
|
125
|
+
| `activate` | `creating` → `active`; seeds overview listeners |
|
|
126
|
+
| `reject_meta` | → `inactive` **without** refund |
|
|
127
|
+
| `set_spend` | sets media spend (before refund) |
|
|
128
|
+
| `end` | → `ended` + refund |
|
|
129
|
+
| `POST /__emulator/wallet` | `{ balance }` — top-up without clearing campaigns |
|
|
130
|
+
| `POST /__emulator/reset` | wipe campaigns, idempotency, restore initial balance |
|
|
131
|
+
|
|
132
|
+
```http
|
|
133
|
+
POST /__emulator/campaigns/{campaignId}/transition
|
|
134
|
+
Content-Type: application/json
|
|
135
|
+
|
|
136
|
+
{ "action": "set_spend", "mediaSpendUsd": 40 }
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Options
|
|
140
|
+
|
|
141
|
+
| Option | Default | Notes |
|
|
142
|
+
| ---------------------- | ------------------ | ---------------------------------------------------------- |
|
|
143
|
+
| `apiKey` | `sk_emulator_test` | Must start with `sk_`; same value in SDK / `Authorization` |
|
|
144
|
+
| `initialWalletBalance` | `1000` | USD |
|
|
145
|
+
| `plan` | — | Sets the paid-campaign fee. See table below |
|
|
146
|
+
| `feeRate` | `0` (or plan fee) | Always overrides plan fee; must be in `[0, 1)` |
|
|
147
|
+
| `organizationId` | `org_emulator` | Returned on campaign detail |
|
|
148
|
+
|
|
149
|
+
### Plans
|
|
150
|
+
|
|
151
|
+
Local test presets, not the public price list. Pass `feeRate` when the test needs a specific rate.
|
|
152
|
+
|
|
153
|
+
| Plan | Fee |
|
|
154
|
+
| -------------------------------- | ------ |
|
|
155
|
+
| _(omit)_ | `0` |
|
|
156
|
+
| `free` / `artist_pro` / `studio` | `0.2` |
|
|
157
|
+
| `label_power` | `0.15` |
|
|
158
|
+
| `enterprise` | `0.1` |
|
|
159
|
+
|
|
160
|
+
`emu.getPlan()` → fee and premium flag. `premium` is metadata only (does not change `/v1` payloads).
|
|
161
|
+
|
|
162
|
+
## Recipes
|
|
163
|
+
|
|
164
|
+
**Insufficient credit (402)** — top up, then retry with a **new** `Idempotency-Key`:
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
const low = createApiEmulator({ apiKey, initialWalletBalance: 10 });
|
|
168
|
+
await low.listen();
|
|
169
|
+
// create with idempotencyKey 'create-1' → 402 insufficient_credit
|
|
170
|
+
low.setWallet(500);
|
|
171
|
+
// create with idempotencyKey 'create-2' → 201
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Create `402` does not store the key in this emulator, so the same key would also succeed after `setWallet`. Do not rely on that. The public API can replay a recorded `402`, and the documented retry is a new key.
|
|
175
|
+
|
|
176
|
+
**Meta reject** — no wallet credit until you stop:
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
await emu.transition(id, 'reject_meta'); // inactive, balance unchanged
|
|
180
|
+
await soundlink.campaigns.stop(id, { idempotencyKey: 'stop-reject' }); // full refund
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
**Partial spend + fee**:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
const emu = createApiEmulator({
|
|
187
|
+
apiKey,
|
|
188
|
+
plan: 'enterprise',
|
|
189
|
+
initialWalletBalance: 500,
|
|
190
|
+
});
|
|
191
|
+
// create committed 70 → activate → set_spend(40) → stop
|
|
192
|
+
// refund ≈ 25.56; wallet ≈ 455.56
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## Errors (match Public API)
|
|
196
|
+
|
|
197
|
+
| Case | Status / code |
|
|
198
|
+
| ------------------------------- | ------------------------------ |
|
|
199
|
+
| Missing / empty Idempotency-Key | `400 invalid_request` |
|
|
200
|
+
| Idempotency-Key > 255 chars | `400 invalid_request` |
|
|
201
|
+
| Same key, different body | `409 idempotency_key_conflict` |
|
|
202
|
+
| `dailyBudget` below 10 | `422 invalid_daily_budget` |
|
|
203
|
+
| Bad `durationDays` | `422 invalid_duration_days` |
|
|
204
|
+
| Wallet too low on create | `402 insufficient_credit` |
|
|
205
|
+
| Bad / missing API key | `401 invalid_api_key` |
|
|
206
|
+
|
|
207
|
+
Stop Idempotency-Key hashes `{ campaignId }` only. Stopping while `creating` releases the key (same key works after `activate`).
|
|
208
|
+
|
|
209
|
+
## Not production
|
|
210
|
+
|
|
211
|
+
- Default fee is `0` unless you set `plan` / `feeRate`.
|
|
212
|
+
- Harness routes are emulator-only.
|
|
213
|
+
- `reject_meta` does not refund; public `stop` / harness `end` do.
|
|
214
|
+
- Create `402` releases the key (unlike some budget-increase replay paths). Retry with a new key anyway.
|
|
215
|
+
- Genre, Spotify URL shape, and `strategyType` are not validated, so a value production would reject with `422` can return `201` here.
|
|
216
|
+
- Only a subset of `/v1` is implemented (ping, wallet, strategies, campaigns create/get/list/stop, metrics overview).
|
|
@@ -1827,6 +1827,12 @@ paths:
|
|
|
1827
1827
|
Requires the `soundlinks:write` scope and a self-serve plan on the
|
|
1828
1828
|
organization; otherwise returns `403 soundlink_plan_required`.
|
|
1829
1829
|
|
|
1830
|
+
`streamValueEventEnabled: true` turns on Soundlink Stream Value for
|
|
1831
|
+
that soundlink. The organization must already be enabled for it, or
|
|
1832
|
+
the request returns `403 stream_value_not_enabled`. It cannot be
|
|
1833
|
+
combined with `attributionEnabled: false`. Events are sent only when
|
|
1834
|
+
the soundlink has a Meta pixel and conversion access token.
|
|
1835
|
+
|
|
1830
1836
|
`Idempotency-Key` is **required**. Reusing the key with an unchanged
|
|
1831
1837
|
body replays the original `201`; a different body returns
|
|
1832
1838
|
`409 idempotency_key_conflict`. Keys are honored for 24 hours.
|
|
@@ -1857,10 +1863,11 @@ paths:
|
|
|
1857
1863
|
metaPixelId: '1234567890123456'
|
|
1858
1864
|
metaConversionAccessToken: 'EAAB...'
|
|
1859
1865
|
playlist:
|
|
1860
|
-
summary: Playlist soundlink
|
|
1866
|
+
summary: Playlist soundlink with Stream Value
|
|
1861
1867
|
value:
|
|
1862
1868
|
name: Late Night Mix
|
|
1863
1869
|
spotifyUrl: 'https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M'
|
|
1870
|
+
streamValueEventEnabled: true
|
|
1864
1871
|
responses:
|
|
1865
1872
|
'201':
|
|
1866
1873
|
description: Soundlink created
|
|
@@ -1881,6 +1888,7 @@ paths:
|
|
|
1881
1888
|
autoFollow: true
|
|
1882
1889
|
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1883
1890
|
attributionEnabled: true
|
|
1891
|
+
streamValueEventEnabled: false
|
|
1884
1892
|
metaPixelId: '1234567890123456'
|
|
1885
1893
|
tiktokPixelId: null
|
|
1886
1894
|
appleMusicUrl: null
|
|
@@ -1931,6 +1939,7 @@ paths:
|
|
|
1931
1939
|
autoFollow: true
|
|
1932
1940
|
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1933
1941
|
attributionEnabled: true
|
|
1942
|
+
streamValueEventEnabled: false
|
|
1934
1943
|
metaPixelId: '1234567890123456'
|
|
1935
1944
|
tiktokPixelId: null
|
|
1936
1945
|
appleMusicUrl: null
|
|
@@ -1980,6 +1989,7 @@ paths:
|
|
|
1980
1989
|
autoFollow: true
|
|
1981
1990
|
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1982
1991
|
attributionEnabled: true
|
|
1992
|
+
streamValueEventEnabled: false
|
|
1983
1993
|
metaPixelId: '1234567890123456'
|
|
1984
1994
|
tiktokPixelId: null
|
|
1985
1995
|
appleMusicUrl: null
|
|
@@ -3111,6 +3121,7 @@ components:
|
|
|
3111
3121
|
- wallet_not_enabled
|
|
3112
3122
|
- premium_plan_required
|
|
3113
3123
|
- soundlink_plan_required
|
|
3124
|
+
- stream_value_not_enabled
|
|
3114
3125
|
- custom_pixel_not_enabled
|
|
3115
3126
|
- meta_pixel_conflict
|
|
3116
3127
|
- pixel_in_use
|
|
@@ -4604,6 +4615,18 @@ components:
|
|
|
4604
4615
|
When false, the landing page skips Spotify login and only tracks
|
|
4605
4616
|
the landing-page click. Omit or send true to keep attribution.
|
|
4606
4617
|
Cannot be combined with `autoFollow: true`.
|
|
4618
|
+
streamValueEventEnabled:
|
|
4619
|
+
type: boolean
|
|
4620
|
+
default: false
|
|
4621
|
+
description: |
|
|
4622
|
+
When true, Soundlink sends a Meta conversion event named
|
|
4623
|
+
"Soundlink Stream Value" for attributed streams on this soundlink.
|
|
4624
|
+
Requires the organization to be enabled for Soundlink Stream Value,
|
|
4625
|
+
otherwise the request returns `403 stream_value_not_enabled`.
|
|
4626
|
+
Cannot be combined with `attributionEnabled: false`. Omit or send
|
|
4627
|
+
false to leave it off. Can only be set at creation. Events are
|
|
4628
|
+
sent only when the soundlink has a Meta pixel and conversion
|
|
4629
|
+
access token.
|
|
4607
4630
|
|
|
4608
4631
|
SoundlinkDetail:
|
|
4609
4632
|
allOf:
|
|
@@ -4617,6 +4640,7 @@ components:
|
|
|
4617
4640
|
- appleMusicUrl
|
|
4618
4641
|
- youtubeMusicUrl
|
|
4619
4642
|
- attributionEnabled
|
|
4643
|
+
- streamValueEventEnabled
|
|
4620
4644
|
properties:
|
|
4621
4645
|
autoFollow:
|
|
4622
4646
|
type: boolean
|
|
@@ -4655,6 +4679,11 @@ components:
|
|
|
4655
4679
|
description: |
|
|
4656
4680
|
Whether this soundlink keeps Spotify attribution. `false`
|
|
4657
4681
|
means the landing page skips login and only tracks the click.
|
|
4682
|
+
streamValueEventEnabled:
|
|
4683
|
+
type: boolean
|
|
4684
|
+
description: |
|
|
4685
|
+
Whether Soundlink Stream Value is on for this soundlink.
|
|
4686
|
+
`true` only when it was set at creation.
|
|
4658
4687
|
|
|
4659
4688
|
SoundlinkDetailResponse:
|
|
4660
4689
|
type: object
|
|
@@ -5576,8 +5605,9 @@ components:
|
|
|
5576
5605
|
|
|
5577
5606
|
CreateSoundlinkForbidden:
|
|
5578
5607
|
description: |
|
|
5579
|
-
Valid credentials but missing the `soundlinks:write` scope,
|
|
5580
|
-
organization has no self-serve plan
|
|
5608
|
+
Valid credentials but missing the `soundlinks:write` scope, the
|
|
5609
|
+
organization has no self-serve plan, or Soundlink Stream Value was
|
|
5610
|
+
requested for an organization that is not enabled for it.
|
|
5581
5611
|
content:
|
|
5582
5612
|
application/json:
|
|
5583
5613
|
schema:
|
|
@@ -5597,6 +5627,13 @@ components:
|
|
|
5597
5627
|
message: 'Creating a Soundlink requires a self-serve plan.'
|
|
5598
5628
|
meta:
|
|
5599
5629
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5630
|
+
stream_value_not_enabled:
|
|
5631
|
+
value:
|
|
5632
|
+
error:
|
|
5633
|
+
code: stream_value_not_enabled
|
|
5634
|
+
message: 'This organization cannot create a soundlink with stream value enabled.'
|
|
5635
|
+
meta:
|
|
5636
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5600
5637
|
CreateSoundlinkUnprocessable:
|
|
5601
5638
|
description: Request body is well-formed but the Spotify URL is invalid.
|
|
5602
5639
|
content:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "soundlink",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.11.0",
|
|
4
4
|
"description": "Official TypeScript SDK for the Soundlink Public API",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -21,10 +21,21 @@
|
|
|
21
21
|
"types": "./dist/esm/index.d.ts",
|
|
22
22
|
"default": "./dist/cjs/index.cjs"
|
|
23
23
|
}
|
|
24
|
+
},
|
|
25
|
+
"./api-emulator": {
|
|
26
|
+
"import": {
|
|
27
|
+
"types": "./dist/esm/api-emulator.d.ts",
|
|
28
|
+
"default": "./dist/esm/api-emulator.js"
|
|
29
|
+
},
|
|
30
|
+
"require": {
|
|
31
|
+
"types": "./dist/esm/api-emulator.d.ts",
|
|
32
|
+
"default": "./dist/cjs/api-emulator.cjs"
|
|
33
|
+
}
|
|
24
34
|
}
|
|
25
35
|
},
|
|
26
36
|
"files": [
|
|
27
37
|
"dist",
|
|
38
|
+
"docs",
|
|
28
39
|
"openapi",
|
|
29
40
|
"README.md",
|
|
30
41
|
"CHANGELOG.md",
|