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.
@@ -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.9.0",
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",