soundlink 2.7.0 → 2.9.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 +12 -0
- package/README.md +3 -0
- package/dist/cjs/index.cjs +22 -1
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +38 -8
- package/dist/esm/index.js +22 -1
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +156 -29
- package/package.json +1 -1
|
@@ -170,6 +170,11 @@ paths:
|
|
|
170
170
|
Returns the Meta pixels configured for the organization. Access tokens
|
|
171
171
|
are never returned. Today each entry has `platform: meta`.
|
|
172
172
|
|
|
173
|
+
Each pixel includes `isDefault` and send-health fields (`status`,
|
|
174
|
+
`lastErrorCode`, `errorSince`). `isDefault` only affects the app's
|
|
175
|
+
soundlink create picker; this API never applies a default pixel on
|
|
176
|
+
create.
|
|
177
|
+
|
|
173
178
|
Requires `pixels:read`. Organizations without custom pixels enabled
|
|
174
179
|
get `403 custom_pixel_not_enabled`.
|
|
175
180
|
tags: [Pixels]
|
|
@@ -190,6 +195,10 @@ paths:
|
|
|
190
195
|
pixels:
|
|
191
196
|
- id: '1234567890123456'
|
|
192
197
|
platform: meta
|
|
198
|
+
isDefault: true
|
|
199
|
+
status: ok
|
|
200
|
+
lastErrorCode: null
|
|
201
|
+
errorSince: null
|
|
193
202
|
meta:
|
|
194
203
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
195
204
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
@@ -202,12 +211,13 @@ paths:
|
|
|
202
211
|
operationId: updatePixel
|
|
203
212
|
summary: Save an organization pixel
|
|
204
213
|
description: |
|
|
205
|
-
Saves the Conversions API access token
|
|
206
|
-
creates the pixel or rotates its token, and
|
|
214
|
+
Saves the Conversions API access token and/or default flag for
|
|
215
|
+
`pixelId`. The same call creates the pixel or rotates its token, and
|
|
216
|
+
both return `200`:
|
|
207
217
|
|
|
208
|
-
- No Meta pixel yet: the pixel is saved.
|
|
218
|
+
- No Meta pixel yet: the pixel is saved (`accessToken` required).
|
|
209
219
|
- `pixelId` matches a Meta pixel the organization already has: its
|
|
210
|
-
access token is replaced.
|
|
220
|
+
access token is replaced when `accessToken` is sent.
|
|
211
221
|
- A different Meta pixel for the same organization: the new pixel is
|
|
212
222
|
saved alongside existing ones.
|
|
213
223
|
- The pixel is configured by another organization: `409
|
|
@@ -215,6 +225,8 @@ paths:
|
|
|
215
225
|
- The access token is already used with another pixel: `400
|
|
216
226
|
invalid_request`.
|
|
217
227
|
- `platform` other than `meta`: `400 invalid_request`.
|
|
228
|
+
- Optional `isDefault` sets or clears the org default for Meta. At
|
|
229
|
+
least one of `accessToken` or `isDefault` is required.
|
|
218
230
|
|
|
219
231
|
The response never includes the access token. Use
|
|
220
232
|
`POST /v1/pixels/{pixelId}/test-events` to check the pixel and token.
|
|
@@ -247,6 +259,7 @@ paths:
|
|
|
247
259
|
example:
|
|
248
260
|
platform: meta
|
|
249
261
|
accessToken: 'EAAB...'
|
|
262
|
+
isDefault: true
|
|
250
263
|
responses:
|
|
251
264
|
'200':
|
|
252
265
|
description: Pixel saved or token rotated
|
|
@@ -258,6 +271,10 @@ paths:
|
|
|
258
271
|
data:
|
|
259
272
|
id: '1234567890123456'
|
|
260
273
|
platform: meta
|
|
274
|
+
isDefault: true
|
|
275
|
+
status: ok
|
|
276
|
+
lastErrorCode: null
|
|
277
|
+
errorSince: null
|
|
261
278
|
meta:
|
|
262
279
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
263
280
|
'400': { $ref: '#/components/responses/UpdatePixelBadRequest' }
|
|
@@ -267,6 +284,45 @@ paths:
|
|
|
267
284
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
268
285
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
269
286
|
|
|
287
|
+
delete:
|
|
288
|
+
operationId: deletePixel
|
|
289
|
+
summary: Delete an organization pixel
|
|
290
|
+
description: |
|
|
291
|
+
Deletes the Meta pixel `pixelId` for the organization.
|
|
292
|
+
|
|
293
|
+
- `204` when deleted.
|
|
294
|
+
- `404 not_found` when the pixel is not configured for the organization.
|
|
295
|
+
- `409 pixel_in_use` when any smart link still uses the pixel as its
|
|
296
|
+
main or side pixel (`details.smartLinkCount`).
|
|
297
|
+
|
|
298
|
+
Requires `pixels:write`. Organizations without custom pixels enabled
|
|
299
|
+
get `403 custom_pixel_not_enabled`.
|
|
300
|
+
|
|
301
|
+
**Auth:** Accepts API key or OAuth Bearer (`pixels:write`).
|
|
302
|
+
tags: [Pixels]
|
|
303
|
+
x-required-scope: pixels:write
|
|
304
|
+
security:
|
|
305
|
+
- apiKeyBearerAuth: []
|
|
306
|
+
- oauthBearer: []
|
|
307
|
+
|
|
308
|
+
parameters:
|
|
309
|
+
- name: pixelId
|
|
310
|
+
in: path
|
|
311
|
+
required: true
|
|
312
|
+
schema:
|
|
313
|
+
type: string
|
|
314
|
+
minLength: 1
|
|
315
|
+
description: Pixel id on the ad platform.
|
|
316
|
+
responses:
|
|
317
|
+
'204':
|
|
318
|
+
description: Pixel deleted
|
|
319
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
320
|
+
'403': { $ref: '#/components/responses/PixelForbidden' }
|
|
321
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
322
|
+
'409': { $ref: '#/components/responses/PixelInUse' }
|
|
323
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
324
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
325
|
+
|
|
270
326
|
/v1/pixels/{pixelId}/test-events:
|
|
271
327
|
post:
|
|
272
328
|
operationId: sendPixelTestEvents
|
|
@@ -2099,6 +2155,9 @@ paths:
|
|
|
2099
2155
|
country_code: US
|
|
2100
2156
|
views: 4821
|
|
2101
2157
|
link_clicks: 890
|
|
2158
|
+
spotify_link_clicks: 820
|
|
2159
|
+
apple_music_link_clicks: 50
|
|
2160
|
+
youtube_music_link_clicks: 10
|
|
2102
2161
|
streams: 203
|
|
2103
2162
|
listeners: 145
|
|
2104
2163
|
new_listeners: 120
|
|
@@ -2183,8 +2242,8 @@ paths:
|
|
|
2183
2242
|
schema:
|
|
2184
2243
|
$ref: '#/components/schemas/SoundlinkCountryDailyRow'
|
|
2185
2244
|
example: |
|
|
2186
|
-
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"US","views":4821,"link_clicks":890,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
|
|
2187
|
-
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"DE","views":2103,"link_clicks":31,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
|
|
2245
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"US","views":4821,"link_clicks":890,"spotify_link_clicks":820,"apple_music_link_clicks":50,"youtube_music_link_clicks":10,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
|
|
2246
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"DE","views":2103,"link_clicks":31,"spotify_link_clicks":28,"apple_music_link_clicks":2,"youtube_music_link_clicks":0,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
|
|
2188
2247
|
'400': { $ref: '#/components/responses/BadRequest' }
|
|
2189
2248
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
2190
2249
|
'403': { $ref: '#/components/responses/Forbidden' }
|
|
@@ -2781,12 +2840,33 @@ components:
|
|
|
2781
2840
|
|
|
2782
2841
|
Pixel:
|
|
2783
2842
|
type: object
|
|
2784
|
-
required: [id, platform]
|
|
2843
|
+
required: [id, platform, isDefault, status, lastErrorCode, errorSince]
|
|
2785
2844
|
properties:
|
|
2786
2845
|
id:
|
|
2787
2846
|
type: string
|
|
2788
2847
|
platform:
|
|
2789
2848
|
$ref: '#/components/schemas/PixelPlatform'
|
|
2849
|
+
isDefault:
|
|
2850
|
+
type: boolean
|
|
2851
|
+
description: |
|
|
2852
|
+
Whether this pixel is the organization's default for its platform.
|
|
2853
|
+
Only drives the app soundlink create picker; create APIs never
|
|
2854
|
+
fall back to it.
|
|
2855
|
+
status:
|
|
2856
|
+
type: string
|
|
2857
|
+
enum: [ok, error]
|
|
2858
|
+
description: |
|
|
2859
|
+
`error` while an open send-error episode exists for this pixel;
|
|
2860
|
+
`ok` otherwise.
|
|
2861
|
+
lastErrorCode:
|
|
2862
|
+
type: string
|
|
2863
|
+
nullable: true
|
|
2864
|
+
description: Platform error code for the open episode, or `null`.
|
|
2865
|
+
errorSince:
|
|
2866
|
+
type: string
|
|
2867
|
+
format: date-time
|
|
2868
|
+
nullable: true
|
|
2869
|
+
description: When the open error episode started, or `null`.
|
|
2790
2870
|
|
|
2791
2871
|
PixelListResponse:
|
|
2792
2872
|
type: object
|
|
@@ -2806,14 +2886,21 @@ components:
|
|
|
2806
2886
|
|
|
2807
2887
|
UpdatePixelRequest:
|
|
2808
2888
|
type: object
|
|
2809
|
-
required: [platform
|
|
2889
|
+
required: [platform]
|
|
2810
2890
|
properties:
|
|
2811
2891
|
platform:
|
|
2812
2892
|
$ref: '#/components/schemas/PixelPlatform'
|
|
2813
2893
|
accessToken:
|
|
2814
2894
|
type: string
|
|
2815
2895
|
minLength: 1
|
|
2816
|
-
description:
|
|
2896
|
+
description: |
|
|
2897
|
+
Conversions API access token. Stored and never returned. Required
|
|
2898
|
+
when creating a new pixel; optional when only updating `isDefault`.
|
|
2899
|
+
isDefault:
|
|
2900
|
+
type: boolean
|
|
2901
|
+
description: |
|
|
2902
|
+
Sets or clears the organization's default Meta pixel. At least one
|
|
2903
|
+
of `accessToken` or `isDefault` must be present.
|
|
2817
2904
|
|
|
2818
2905
|
UpdatePixelResponse:
|
|
2819
2906
|
type: object
|
|
@@ -3023,11 +3110,10 @@ components:
|
|
|
3023
3110
|
- learning_edit_ack_required
|
|
3024
3111
|
- wallet_not_enabled
|
|
3025
3112
|
- premium_plan_required
|
|
3026
|
-
- youtube_music_not_enabled
|
|
3027
|
-
- attribution_not_enabled
|
|
3028
3113
|
- soundlink_plan_required
|
|
3029
3114
|
- custom_pixel_not_enabled
|
|
3030
3115
|
- meta_pixel_conflict
|
|
3116
|
+
- pixel_in_use
|
|
3031
3117
|
- insufficient_credit
|
|
3032
3118
|
- idempotency_key_conflict
|
|
3033
3119
|
- rate_limit_exceeded
|
|
@@ -4475,14 +4561,16 @@ components:
|
|
|
4475
4561
|
metaPixelId:
|
|
4476
4562
|
type: string
|
|
4477
4563
|
description: |
|
|
4478
|
-
Meta pixel ID.
|
|
4479
|
-
|
|
4564
|
+
Meta pixel ID. Send with `metaConversionAccessToken` to save or
|
|
4565
|
+
rotate the token (unchanged). Or send `metaPixelId` alone to reuse
|
|
4566
|
+
a pixel the organization already saved (requires pixel settings).
|
|
4567
|
+
Omit both to skip Meta tracking. Never applies an org default.
|
|
4480
4568
|
metaConversionAccessToken:
|
|
4481
4569
|
type: string
|
|
4482
4570
|
writeOnly: true
|
|
4483
4571
|
description: |
|
|
4484
4572
|
Meta Conversions API access token. Write-only: accepted on create,
|
|
4485
|
-
never returned on GET.
|
|
4573
|
+
never returned on GET. When present, `metaPixelId` is required.
|
|
4486
4574
|
appleMusicUrl:
|
|
4487
4575
|
type: string
|
|
4488
4576
|
format: uri
|
|
@@ -4515,8 +4603,7 @@ components:
|
|
|
4515
4603
|
description: |
|
|
4516
4604
|
When false, the landing page skips Spotify login and only tracks
|
|
4517
4605
|
the landing-page click. Omit or send true to keep attribution.
|
|
4518
|
-
|
|
4519
|
-
attribution off, and cannot be combined with `autoFollow: true`.
|
|
4606
|
+
Cannot be combined with `autoFollow: true`.
|
|
4520
4607
|
|
|
4521
4608
|
SoundlinkDetail:
|
|
4522
4609
|
allOf:
|
|
@@ -4666,6 +4753,9 @@ components:
|
|
|
4666
4753
|
- soundlink_target_type
|
|
4667
4754
|
- country_code
|
|
4668
4755
|
- views
|
|
4756
|
+
- spotify_link_clicks
|
|
4757
|
+
- apple_music_link_clicks
|
|
4758
|
+
- youtube_music_link_clicks
|
|
4669
4759
|
- streams
|
|
4670
4760
|
- listeners
|
|
4671
4761
|
- followers
|
|
@@ -4728,8 +4818,28 @@ components:
|
|
|
4728
4818
|
type: integer
|
|
4729
4819
|
nullable: true
|
|
4730
4820
|
description: |
|
|
4731
|
-
CTA clicks across all DSPs on the landing page
|
|
4732
|
-
|
|
4821
|
+
CTA clicks across all DSPs on the landing page (including DSPs
|
|
4822
|
+
without a dedicated column). Always >= the sum of
|
|
4823
|
+
`spotify_link_clicks` + `apple_music_link_clicks` +
|
|
4824
|
+
`youtube_music_link_clicks` — do not derive a per-DSP count by
|
|
4825
|
+
subtraction. Null if not tracked for this soundlink type.
|
|
4826
|
+
spotify_link_clicks:
|
|
4827
|
+
type: integer
|
|
4828
|
+
description: |
|
|
4829
|
+
Continue sessions to Spotify from the landing page. Safe to sum
|
|
4830
|
+
across countries and days.
|
|
4831
|
+
apple_music_link_clicks:
|
|
4832
|
+
type: integer
|
|
4833
|
+
description: |
|
|
4834
|
+
Continue sessions to Apple Music from the landing page (outbound
|
|
4835
|
+
click only; no Apple Music playback attribution). Safe to sum
|
|
4836
|
+
across countries and days.
|
|
4837
|
+
youtube_music_link_clicks:
|
|
4838
|
+
type: integer
|
|
4839
|
+
description: |
|
|
4840
|
+
Continue sessions to YouTube Music from the landing page (outbound
|
|
4841
|
+
click only; no YouTube Music playback attribution). Often `0` on
|
|
4842
|
+
standalone soundlink marts. Safe to sum across countries and days.
|
|
4733
4843
|
streams:
|
|
4734
4844
|
type: integer
|
|
4735
4845
|
description: |
|
|
@@ -5449,19 +5559,25 @@ components:
|
|
|
5449
5559
|
message: 'Idempotency-Key header is required and must not be empty.'
|
|
5450
5560
|
meta:
|
|
5451
5561
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5452
|
-
|
|
5562
|
+
pixel_token_without_id:
|
|
5453
5563
|
value:
|
|
5454
5564
|
error:
|
|
5455
5565
|
code: invalid_request
|
|
5456
5566
|
message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
|
|
5457
5567
|
meta:
|
|
5458
5568
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5569
|
+
pixel_not_owned:
|
|
5570
|
+
value:
|
|
5571
|
+
error:
|
|
5572
|
+
code: invalid_request
|
|
5573
|
+
message: "This pixel can't be used with this account. Check the pixel ID and access token, or contact support."
|
|
5574
|
+
meta:
|
|
5575
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5459
5576
|
|
|
5460
5577
|
CreateSoundlinkForbidden:
|
|
5461
5578
|
description: |
|
|
5462
|
-
Valid credentials but missing the `soundlinks:write` scope, the
|
|
5463
|
-
organization has no self-serve plan
|
|
5464
|
-
to create a soundlink with attribution off.
|
|
5579
|
+
Valid credentials but missing the `soundlinks:write` scope, or the
|
|
5580
|
+
organization has no self-serve plan.
|
|
5465
5581
|
content:
|
|
5466
5582
|
application/json:
|
|
5467
5583
|
schema:
|
|
@@ -5481,13 +5597,6 @@ components:
|
|
|
5481
5597
|
message: 'Creating a Soundlink requires a self-serve plan.'
|
|
5482
5598
|
meta:
|
|
5483
5599
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5484
|
-
attribution_not_enabled:
|
|
5485
|
-
value:
|
|
5486
|
-
error:
|
|
5487
|
-
code: attribution_not_enabled
|
|
5488
|
-
message: 'This organization cannot create a soundlink with attribution off.'
|
|
5489
|
-
meta:
|
|
5490
|
-
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5491
5600
|
CreateSoundlinkUnprocessable:
|
|
5492
5601
|
description: Request body is well-formed but the Spotify URL is invalid.
|
|
5493
5602
|
content:
|
|
@@ -5568,6 +5677,24 @@ components:
|
|
|
5568
5677
|
meta:
|
|
5569
5678
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5570
5679
|
|
|
5680
|
+
PixelInUse:
|
|
5681
|
+
description: |
|
|
5682
|
+
The pixel is still used by one or more smart links and cannot be deleted.
|
|
5683
|
+
content:
|
|
5684
|
+
application/json:
|
|
5685
|
+
schema:
|
|
5686
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
5687
|
+
examples:
|
|
5688
|
+
pixel_in_use:
|
|
5689
|
+
value:
|
|
5690
|
+
error:
|
|
5691
|
+
code: pixel_in_use
|
|
5692
|
+
message: "This pixel is used by smart links and can't be deleted."
|
|
5693
|
+
details:
|
|
5694
|
+
smartLinkCount: 2
|
|
5695
|
+
meta:
|
|
5696
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
5697
|
+
|
|
5571
5698
|
PixelTestEventBadRequest:
|
|
5572
5699
|
description: |
|
|
5573
5700
|
Meta rejected the event because the pixel id or access token is wrong.
|