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