soundlink 2.9.0 → 2.10.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 +10 -0
- package/README.md +35 -0
- package/dist/cjs/api-emulator.cjs +934 -0
- package/dist/cjs/api-emulator.cjs.map +1 -0
- package/dist/esm/api-BCcqXQoy.d.ts +864 -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/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).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "soundlink",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.10.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",
|