soundlink 2.1.0 → 2.3.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 +17 -0
- package/README.md +18 -7
- package/dist/cjs/index.cjs +112 -18
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +165 -71
- package/dist/esm/index.js +112 -18
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +1033 -151
- package/package.json +2 -2
package/dist/esm/index.d.ts
CHANGED
|
@@ -30,10 +30,10 @@ type CampaignSortBy = 'createdAt' | 'status';
|
|
|
30
30
|
type SoundlinkSortBy = 'createdAt';
|
|
31
31
|
/** Allowed `sortBy` values for breakdown list requests. */
|
|
32
32
|
type BreakdownSortBy = 'report_date' | 'spend_total';
|
|
33
|
-
/** Allowed `sortBy` values for soundlink
|
|
34
|
-
type
|
|
35
|
-
/** Allowed `sortBy` values for soundlink engagement
|
|
36
|
-
type SoundlinkEngagementSortBy = '
|
|
33
|
+
/** Allowed `sortBy` values for soundlink breakdown list requests. */
|
|
34
|
+
type SoundlinkBreakdownSortBy = 'report_date' | 'country_code';
|
|
35
|
+
/** Allowed `sortBy` values for soundlink engagement list requests. */
|
|
36
|
+
type SoundlinkEngagementSortBy = 'report_date';
|
|
37
37
|
/** Sort direction for list endpoints. */
|
|
38
38
|
type SortOrder = 'asc' | 'desc';
|
|
39
39
|
/** Lifecycle status for a self-serve soundlink. */
|
|
@@ -397,32 +397,6 @@ interface DateRangeParams {
|
|
|
397
397
|
/** Inclusive end date. Must not be before `startDate`. */
|
|
398
398
|
endDate?: string;
|
|
399
399
|
}
|
|
400
|
-
/** Query params for {@link SoundlinksResource.metricsTimeseries}. */
|
|
401
|
-
interface SoundlinkTimeseriesParams extends DateRangeParams {
|
|
402
|
-
page?: number;
|
|
403
|
-
/** Default: `50`. Max: **500**. */
|
|
404
|
-
pageSize?: number;
|
|
405
|
-
/** Default: `report_date`. */
|
|
406
|
-
sortBy?: SoundlinkTimeseriesSortBy;
|
|
407
|
-
/** Default: `asc`. */
|
|
408
|
-
sortOrder?: SortOrder;
|
|
409
|
-
}
|
|
410
|
-
/**
|
|
411
|
-
* Query params for {@link SoundlinksResource.engagement}.
|
|
412
|
-
*
|
|
413
|
-
* `startDate`/`endDate` snap to Insights windows only (yesterday, last 7 days
|
|
414
|
-
* ending today, or all-time). Arbitrary ranges resolve to all-time.
|
|
415
|
-
* Omitting `startDate` always uses all-time (not createdAt).
|
|
416
|
-
*/
|
|
417
|
-
interface SoundlinkEngagementParams extends DateRangeParams {
|
|
418
|
-
page?: number;
|
|
419
|
-
/** Default: `10`. Max: **100**. */
|
|
420
|
-
pageSize?: number;
|
|
421
|
-
/** Default: `totalStreams`. */
|
|
422
|
-
sortBy?: SoundlinkEngagementSortBy;
|
|
423
|
-
/** Default: `desc`. */
|
|
424
|
-
sortOrder?: SortOrder;
|
|
425
|
-
}
|
|
426
400
|
/** Self-serve soundlink summary from {@link SoundlinksResource.list}. */
|
|
427
401
|
interface SoundlinkSummary {
|
|
428
402
|
soundlinkId: string;
|
|
@@ -439,9 +413,26 @@ interface SoundlinkSummary {
|
|
|
439
413
|
/** Full soundlink detail from {@link SoundlinksResource.get}. */
|
|
440
414
|
interface SoundlinkDetail extends SoundlinkSummary {
|
|
441
415
|
autoFollow: boolean;
|
|
416
|
+
artistIdFollow: string | null;
|
|
442
417
|
metaPixelId: string | null;
|
|
443
418
|
tiktokPixelId: string | null;
|
|
444
419
|
}
|
|
420
|
+
/** Body for `POST /v1/soundlinks`. */
|
|
421
|
+
interface CreateSoundlinkRequest {
|
|
422
|
+
name: string;
|
|
423
|
+
/** HTTPS Spotify track or playlist URL. */
|
|
424
|
+
spotifyUrl: string;
|
|
425
|
+
autoFollow?: boolean;
|
|
426
|
+
/** Spotify artist ID for auto-follow on track links. Ignored for playlists. */
|
|
427
|
+
artistIdFollow?: string;
|
|
428
|
+
/** Must be sent together with `metaConversionAccessToken`. */
|
|
429
|
+
metaPixelId?: string;
|
|
430
|
+
/**
|
|
431
|
+
* Meta Conversions API token. Write-only: accepted on create, never returned.
|
|
432
|
+
* Must be sent together with `metaPixelId`.
|
|
433
|
+
*/
|
|
434
|
+
metaConversionAccessToken?: string;
|
|
435
|
+
}
|
|
445
436
|
/** Paginated soundlink list payload. */
|
|
446
437
|
interface SoundlinkListData {
|
|
447
438
|
items: SoundlinkSummary[];
|
|
@@ -457,16 +448,12 @@ interface SoundlinkMetricsOverview {
|
|
|
457
448
|
link_clicks: number | null;
|
|
458
449
|
streams: number;
|
|
459
450
|
listeners: number;
|
|
460
|
-
new_listeners: number | null;
|
|
461
|
-
returning_listeners: number | null;
|
|
462
|
-
new_listener_streams: number | null;
|
|
463
|
-
returning_listener_streams: number | null;
|
|
464
451
|
followers: number;
|
|
465
452
|
streams_per_listener: number;
|
|
466
453
|
ctr_lp: number | null;
|
|
467
454
|
}
|
|
468
|
-
/** One row of the `
|
|
469
|
-
interface
|
|
455
|
+
/** One row of the `soundlink_country_daily` v1.0 schema. */
|
|
456
|
+
interface SoundlinkBreakdownRow {
|
|
470
457
|
provider: 'soundlink';
|
|
471
458
|
account_id: string;
|
|
472
459
|
schema_version: string;
|
|
@@ -476,10 +463,11 @@ interface SoundlinkDailyRow {
|
|
|
476
463
|
exported_at: string;
|
|
477
464
|
soundlink_id: string;
|
|
478
465
|
soundlink_name: string;
|
|
479
|
-
soundlink_target_type:
|
|
466
|
+
soundlink_target_type: 'track' | 'playlist' | null;
|
|
480
467
|
soundlink_target_isrc: string | null;
|
|
481
468
|
soundlink_target_spotify_track_id: string | null;
|
|
482
469
|
soundlink_target_playlist_id: string | null;
|
|
470
|
+
country_code: string;
|
|
483
471
|
views: number;
|
|
484
472
|
link_clicks: number | null;
|
|
485
473
|
streams: number;
|
|
@@ -492,25 +480,72 @@ interface SoundlinkDailyRow {
|
|
|
492
480
|
streams_per_listener: number;
|
|
493
481
|
ctr_lp: number | null;
|
|
494
482
|
}
|
|
495
|
-
/** Paginated soundlink
|
|
496
|
-
interface
|
|
483
|
+
/** Paginated soundlink breakdown list payload. */
|
|
484
|
+
interface SoundlinkBreakdownListData {
|
|
497
485
|
schemaVersion: string;
|
|
498
|
-
items:
|
|
486
|
+
items: SoundlinkBreakdownRow[];
|
|
499
487
|
pagination: Pagination;
|
|
500
488
|
}
|
|
501
|
-
/** One
|
|
502
|
-
interface
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
489
|
+
/** One row of the `soundlink_engagement_daily` v1.0 schema. */
|
|
490
|
+
interface SoundlinkEngagementRow {
|
|
491
|
+
provider: 'soundlink';
|
|
492
|
+
account_id: string;
|
|
493
|
+
schema_version: string;
|
|
494
|
+
report_date: string;
|
|
495
|
+
report_date_timezone: 'UTC';
|
|
496
|
+
exported_at: string;
|
|
497
|
+
soundlink_id: string;
|
|
498
|
+
soundlink_name: string;
|
|
499
|
+
soundlink_target_type: 'track' | 'playlist' | null;
|
|
500
|
+
soundlink_target_isrc: string | null;
|
|
501
|
+
soundlink_target_spotify_track_id: string | null;
|
|
502
|
+
soundlink_target_playlist_id: string | null;
|
|
503
|
+
engagement_context: EngagementContext;
|
|
504
|
+
country_code: string;
|
|
505
|
+
engaged_track_isrc: string | null;
|
|
506
|
+
engaged_spotify_track_id: string;
|
|
507
|
+
engaged_track_name: string;
|
|
508
|
+
playlist_position: number | null;
|
|
509
|
+
new_listeners: number;
|
|
510
|
+
returning_listeners: number;
|
|
511
|
+
listeners: number;
|
|
512
|
+
new_listener_streams: number;
|
|
513
|
+
returning_listener_streams: number;
|
|
514
|
+
streams: number;
|
|
515
|
+
spl: number;
|
|
516
|
+
}
|
|
517
|
+
/** Paginated soundlink engagement list payload. */
|
|
518
|
+
interface SoundlinkEngagementListData {
|
|
519
|
+
schemaVersion: string;
|
|
520
|
+
items: SoundlinkEngagementRow[];
|
|
512
521
|
pagination: Pagination;
|
|
513
522
|
}
|
|
523
|
+
/** Query params for {@link SoundlinkBreakdownMetricsResource.list}. */
|
|
524
|
+
interface SoundlinkBreakdownListParams extends DateRangeParams {
|
|
525
|
+
page?: number;
|
|
526
|
+
/** Default: `50`. Max: **500**. */
|
|
527
|
+
pageSize?: number;
|
|
528
|
+
/** Default: `report_date`. */
|
|
529
|
+
sortBy?: SoundlinkBreakdownSortBy;
|
|
530
|
+
/** Default: `asc`. */
|
|
531
|
+
sortOrder?: SortOrder;
|
|
532
|
+
}
|
|
533
|
+
/**
|
|
534
|
+
* Query params for {@link SoundlinkEngagementMetricsResource.list}.
|
|
535
|
+
*
|
|
536
|
+
* Defaults to the last 90 days ending today; max **90 days** per request.
|
|
537
|
+
*/
|
|
538
|
+
interface SoundlinkEngagementListParams extends DateRangeParams {
|
|
539
|
+
page?: number;
|
|
540
|
+
/** Default: `50`. Max: **500**. */
|
|
541
|
+
pageSize?: number;
|
|
542
|
+
/** Filter to a single engagement context. Omit to return both. */
|
|
543
|
+
engagementContext?: EngagementContext;
|
|
544
|
+
/** Default: `report_date`. */
|
|
545
|
+
sortBy?: SoundlinkEngagementSortBy;
|
|
546
|
+
/** Default: `asc`. */
|
|
547
|
+
sortOrder?: SortOrder;
|
|
548
|
+
}
|
|
514
549
|
/** Query params for {@link BreakdownMetricsResource.list}. */
|
|
515
550
|
interface BreakdownListParams extends DateRangeParams {
|
|
516
551
|
page?: number;
|
|
@@ -563,6 +598,7 @@ declare class HttpClient {
|
|
|
563
598
|
get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
|
|
564
599
|
post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
565
600
|
patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
601
|
+
delete<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
566
602
|
getJsonl<T>({ path, query, accept, }: HttpJsonlOptions): Promise<ApiResponse<JsonlStream<T>>>;
|
|
567
603
|
private mutateJson;
|
|
568
604
|
private buildHeaders;
|
|
@@ -592,16 +628,16 @@ interface ExportResource<T, P extends DateRangeParams> {
|
|
|
592
628
|
/**
|
|
593
629
|
* Stream export rows as newline-delimited JSON.
|
|
594
630
|
*
|
|
595
|
-
* @param
|
|
631
|
+
* @param id - Campaign or soundlink ID.
|
|
596
632
|
* @param params - Optional date range (max 90 days per request).
|
|
597
633
|
*/
|
|
598
|
-
(
|
|
634
|
+
(id: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
|
|
599
635
|
/**
|
|
600
636
|
* Download all export rows into memory.
|
|
601
637
|
*
|
|
602
638
|
* Prefer {@link ExportResource | the stream} for large datasets.
|
|
603
639
|
*/
|
|
604
|
-
collect(
|
|
640
|
+
collect(id: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
|
|
605
641
|
}
|
|
606
642
|
/** System endpoints (`GET /v1/ping`). */
|
|
607
643
|
declare class PingResource {
|
|
@@ -742,20 +778,27 @@ declare class CampaignsResource {
|
|
|
742
778
|
listAll(params?: Omit<CampaignListParams, 'page'>): AsyncGenerator<CampaignListData['items'][number], void, void>;
|
|
743
779
|
}
|
|
744
780
|
/**
|
|
745
|
-
* Self-serve soundlinks (`/v1/soundlinks/*`).
|
|
781
|
+
* Self-serve soundlinks (`/v1/soundlinks/*`).
|
|
746
782
|
*
|
|
747
|
-
*
|
|
748
|
-
* soundlinks are
|
|
783
|
+
* List, get, and metrics require `soundlinks:read`. Create and delete require
|
|
784
|
+
* `soundlinks:write`. Only soundlinks that are **not** linked to a campaign.
|
|
785
|
+
* Campaign-backed soundlinks are served by the Campaigns API.
|
|
749
786
|
*
|
|
750
787
|
* @example
|
|
751
788
|
* ```ts
|
|
752
789
|
* await soundlink.soundlinks.list();
|
|
753
790
|
* await soundlink.soundlinks.get(soundlinkId);
|
|
791
|
+
* await soundlink.soundlinks.create({ name, spotifyUrl }, { idempotencyKey });
|
|
792
|
+
* await soundlink.soundlinks.delete(soundlinkId);
|
|
754
793
|
* await soundlink.soundlinks.metricsOverview(soundlinkId);
|
|
755
794
|
* ```
|
|
756
795
|
*/
|
|
757
796
|
declare class SoundlinksResource {
|
|
758
797
|
private readonly http;
|
|
798
|
+
/** Per-day country breakdown and JSONL export. */
|
|
799
|
+
readonly breakdown: SoundlinkBreakdownMetricsResource;
|
|
800
|
+
/** Per-day track engagement and JSONL export. */
|
|
801
|
+
readonly engagement: SoundlinkEngagementMetricsResource;
|
|
759
802
|
constructor(http: HttpClient);
|
|
760
803
|
/**
|
|
761
804
|
* List self-serve soundlinks for the authenticated organization.
|
|
@@ -779,6 +822,31 @@ declare class SoundlinksResource {
|
|
|
779
822
|
* @param soundlinkId - Identifier returned by {@link SoundlinksResource.list}.
|
|
780
823
|
*/
|
|
781
824
|
get(soundlinkId: string): Promise<ApiResponse<SoundlinkDetail>>;
|
|
825
|
+
/**
|
|
826
|
+
* Create a self-serve soundlink.
|
|
827
|
+
*
|
|
828
|
+
* Maps to `POST /v1/soundlinks`. Requires `soundlinks:write` and
|
|
829
|
+
* `Idempotency-Key`. Does not create a campaign.
|
|
830
|
+
*
|
|
831
|
+
* @example
|
|
832
|
+
* ```ts
|
|
833
|
+
* const { data, error } = await soundlink.soundlinks.create(
|
|
834
|
+
* {
|
|
835
|
+
* name: 'Midnight Drive',
|
|
836
|
+
* spotifyUrl: 'https://open.spotify.com/track/...',
|
|
837
|
+
* },
|
|
838
|
+
* { idempotencyKey: 'create-midnight-drive-01' },
|
|
839
|
+
* );
|
|
840
|
+
* ```
|
|
841
|
+
*/
|
|
842
|
+
create(body: CreateSoundlinkRequest, options: IdempotencyOptions): Promise<ApiResponse<SoundlinkDetail>>;
|
|
843
|
+
/**
|
|
844
|
+
* Archive a self-serve soundlink (`status: archived`). Same as Archive in the app.
|
|
845
|
+
*
|
|
846
|
+
* Maps to `DELETE /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:write`.
|
|
847
|
+
* Does not send `Idempotency-Key`. List and detail still return the row.
|
|
848
|
+
*/
|
|
849
|
+
delete(soundlinkId: string): Promise<ApiResponse<SoundlinkDetail>>;
|
|
782
850
|
/**
|
|
783
851
|
* Soundlink-level metric totals for a date range.
|
|
784
852
|
*
|
|
@@ -790,30 +858,56 @@ declare class SoundlinksResource {
|
|
|
790
858
|
* @param params - Inclusive `YYYY-MM-DD` date range.
|
|
791
859
|
*/
|
|
792
860
|
metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
|
|
861
|
+
}
|
|
862
|
+
/**
|
|
863
|
+
* Country-level daily metrics (`soundlink_country_daily` schema).
|
|
864
|
+
*
|
|
865
|
+
* Access via `soundlink.soundlinks.breakdown`.
|
|
866
|
+
*/
|
|
867
|
+
declare class SoundlinkBreakdownMetricsResource {
|
|
868
|
+
private readonly http;
|
|
793
869
|
/**
|
|
794
|
-
*
|
|
870
|
+
* Stream full breakdown export as JSONL.
|
|
795
871
|
*
|
|
796
|
-
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/
|
|
797
|
-
|
|
872
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
|
|
873
|
+
*/
|
|
874
|
+
readonly export: ExportResource<SoundlinkBreakdownRow, BreakdownExportParams>;
|
|
875
|
+
constructor(http: HttpClient);
|
|
876
|
+
/**
|
|
877
|
+
* Paginated per-day, per-country breakdown rows.
|
|
878
|
+
*
|
|
879
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
|
|
880
|
+
* Max `pageSize` is **500** (default 50).
|
|
798
881
|
*
|
|
799
882
|
* @param soundlinkId - Soundlink identifier.
|
|
800
883
|
* @param params - Date range, pagination, and sort options.
|
|
801
884
|
*/
|
|
802
|
-
|
|
885
|
+
list(soundlinkId: string, params?: SoundlinkBreakdownListParams): Promise<ApiResponse<SoundlinkBreakdownListData>>;
|
|
886
|
+
}
|
|
887
|
+
/**
|
|
888
|
+
* Per-track engagement metrics (`soundlink_engagement_daily` schema).
|
|
889
|
+
*
|
|
890
|
+
* Access via `soundlink.soundlinks.engagement`.
|
|
891
|
+
*/
|
|
892
|
+
declare class SoundlinkEngagementMetricsResource {
|
|
893
|
+
private readonly http;
|
|
803
894
|
/**
|
|
804
|
-
*
|
|
895
|
+
* Stream full engagement export as JSONL.
|
|
805
896
|
*
|
|
806
|
-
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
|
|
807
|
-
|
|
897
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
|
|
898
|
+
*/
|
|
899
|
+
readonly export: ExportResource<SoundlinkEngagementRow, EngagementExportParams>;
|
|
900
|
+
constructor(http: HttpClient);
|
|
901
|
+
/**
|
|
902
|
+
* Paginated per-day, per-track engagement rows.
|
|
808
903
|
*
|
|
809
|
-
*
|
|
810
|
-
*
|
|
811
|
-
* `startDate` always uses all-time (not createdAt).
|
|
904
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
|
|
905
|
+
* Max `pageSize` is **500** (default 50).
|
|
812
906
|
*
|
|
813
907
|
* @param soundlinkId - Soundlink identifier.
|
|
814
|
-
* @param params - Date range, pagination, and sort
|
|
908
|
+
* @param params - Date range, engagement context filter, pagination, and sort.
|
|
815
909
|
*/
|
|
816
|
-
|
|
910
|
+
list(soundlinkId: string, params?: SoundlinkEngagementListParams): Promise<ApiResponse<SoundlinkEngagementListData>>;
|
|
817
911
|
}
|
|
818
912
|
/**
|
|
819
913
|
* Campaign metrics (`/v1/campaigns/{id}/metrics/*`). Requires `metrics:read`.
|
|
@@ -921,7 +1015,7 @@ declare class Soundlink {
|
|
|
921
1015
|
readonly strategies: StrategiesResource;
|
|
922
1016
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
923
1017
|
readonly campaigns: CampaignsResource;
|
|
924
|
-
/** Self-serve soundlinks
|
|
1018
|
+
/** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
|
|
925
1019
|
readonly soundlinks: SoundlinksResource;
|
|
926
1020
|
/** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
|
|
927
1021
|
readonly metrics: MetricsResource;
|
|
@@ -958,4 +1052,4 @@ declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
|
958
1052
|
declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
|
|
959
1053
|
declare const METRICS_MAX_PAGE_SIZE = 500;
|
|
960
1054
|
|
|
961
|
-
export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, type BudgetDecreaseMode, type BudgetIncreaseMode, type BuiltInStrategyType, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreativeDirection, type CustomTier, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type DecreaseCampaignBudgetData, type DecreaseCampaignBudgetRequest, type DoItForMeCreativeDirection, type EngagementContext, type EngagementExportParams, type EngagementRow, type ExportCollection, type ExportResource, type FullControlCreativeDirection, type Genre, HttpClient, type IdempotencyOptions, type IncreaseCampaignBudgetData, type IncreaseCampaignBudgetRequest, type JsonlStream, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type Pagination, type PingData, type PublicApiErrorCode, SOUNDLINKS_MAX_PAGE_SIZE, type SocialPlatform, type SortOrder, Soundlink, type
|
|
1055
|
+
export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, type BudgetDecreaseMode, type BudgetIncreaseMode, type BuiltInStrategyType, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreateSoundlinkRequest, type CreativeDirection, type CustomTier, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type DecreaseCampaignBudgetData, type DecreaseCampaignBudgetRequest, type DoItForMeCreativeDirection, type EngagementContext, type EngagementExportParams, type EngagementRow, type ExportCollection, type ExportResource, type FullControlCreativeDirection, type Genre, HttpClient, type IdempotencyOptions, type IncreaseCampaignBudgetData, type IncreaseCampaignBudgetRequest, type JsonlStream, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type Pagination, type PingData, type PublicApiErrorCode, SOUNDLINKS_MAX_PAGE_SIZE, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkBreakdownListData, type SoundlinkBreakdownListParams, type SoundlinkBreakdownRow, type SoundlinkBreakdownSortBy, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkDetail, type SoundlinkEngagementListData, type SoundlinkEngagementListParams, type SoundlinkEngagementRow, type SoundlinkEngagementSortBy, type SoundlinkListData, type SoundlinkListParams, type SoundlinkMetricsOverview, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type SoundlinkSortBy, type SoundlinkStatus, type SoundlinkSummary, type SoundlinkTargetType, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignTiersRequest, getStreamRowCount, resolveClientOptions };
|
package/dist/esm/index.js
CHANGED
|
@@ -237,6 +237,21 @@ var HttpClient = class {
|
|
|
237
237
|
idempotencyKey
|
|
238
238
|
});
|
|
239
239
|
}
|
|
240
|
+
async delete({
|
|
241
|
+
path,
|
|
242
|
+
body,
|
|
243
|
+
query,
|
|
244
|
+
headers,
|
|
245
|
+
idempotencyKey
|
|
246
|
+
}) {
|
|
247
|
+
return this.mutateJson("DELETE", {
|
|
248
|
+
path,
|
|
249
|
+
body,
|
|
250
|
+
query,
|
|
251
|
+
headers,
|
|
252
|
+
idempotencyKey
|
|
253
|
+
});
|
|
254
|
+
}
|
|
240
255
|
async getJsonl({
|
|
241
256
|
path,
|
|
242
257
|
query,
|
|
@@ -396,14 +411,14 @@ function getStreamRowCount(stream) {
|
|
|
396
411
|
|
|
397
412
|
// src/resources/index.ts
|
|
398
413
|
function createExportResource(http, buildPath, buildQuery) {
|
|
399
|
-
const exportFn = ((
|
|
414
|
+
const exportFn = ((id, params = {}) => {
|
|
400
415
|
return http.getJsonl({
|
|
401
|
-
path: buildPath(
|
|
416
|
+
path: buildPath(id),
|
|
402
417
|
query: buildQuery(params)
|
|
403
418
|
});
|
|
404
419
|
});
|
|
405
|
-
exportFn.collect = async (
|
|
406
|
-
const response = await exportFn(
|
|
420
|
+
exportFn.collect = async (id, params = {}) => {
|
|
421
|
+
const response = await exportFn(id, params);
|
|
407
422
|
if (response.error || !response.data) {
|
|
408
423
|
return {
|
|
409
424
|
data: null,
|
|
@@ -630,8 +645,14 @@ var CampaignsResource = class {
|
|
|
630
645
|
var SoundlinksResource = class {
|
|
631
646
|
constructor(http) {
|
|
632
647
|
this.http = http;
|
|
648
|
+
this.breakdown = new SoundlinkBreakdownMetricsResource(http);
|
|
649
|
+
this.engagement = new SoundlinkEngagementMetricsResource(http);
|
|
633
650
|
}
|
|
634
651
|
http;
|
|
652
|
+
/** Per-day country breakdown and JSONL export. */
|
|
653
|
+
breakdown;
|
|
654
|
+
/** Per-day track engagement and JSONL export. */
|
|
655
|
+
engagement;
|
|
635
656
|
/**
|
|
636
657
|
* List self-serve soundlinks for the authenticated organization.
|
|
637
658
|
*
|
|
@@ -668,6 +689,41 @@ var SoundlinksResource = class {
|
|
|
668
689
|
path: `/soundlinks/${encodeURIComponent(soundlinkId)}`
|
|
669
690
|
});
|
|
670
691
|
}
|
|
692
|
+
/**
|
|
693
|
+
* Create a self-serve soundlink.
|
|
694
|
+
*
|
|
695
|
+
* Maps to `POST /v1/soundlinks`. Requires `soundlinks:write` and
|
|
696
|
+
* `Idempotency-Key`. Does not create a campaign.
|
|
697
|
+
*
|
|
698
|
+
* @example
|
|
699
|
+
* ```ts
|
|
700
|
+
* const { data, error } = await soundlink.soundlinks.create(
|
|
701
|
+
* {
|
|
702
|
+
* name: 'Midnight Drive',
|
|
703
|
+
* spotifyUrl: 'https://open.spotify.com/track/...',
|
|
704
|
+
* },
|
|
705
|
+
* { idempotencyKey: 'create-midnight-drive-01' },
|
|
706
|
+
* );
|
|
707
|
+
* ```
|
|
708
|
+
*/
|
|
709
|
+
create(body, options) {
|
|
710
|
+
return this.http.post({
|
|
711
|
+
path: "/soundlinks",
|
|
712
|
+
body,
|
|
713
|
+
idempotencyKey: options.idempotencyKey
|
|
714
|
+
});
|
|
715
|
+
}
|
|
716
|
+
/**
|
|
717
|
+
* Archive a self-serve soundlink (`status: archived`). Same as Archive in the app.
|
|
718
|
+
*
|
|
719
|
+
* Maps to `DELETE /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:write`.
|
|
720
|
+
* Does not send `Idempotency-Key`. List and detail still return the row.
|
|
721
|
+
*/
|
|
722
|
+
delete(soundlinkId) {
|
|
723
|
+
return this.http.delete({
|
|
724
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}`
|
|
725
|
+
});
|
|
726
|
+
}
|
|
671
727
|
/**
|
|
672
728
|
* Soundlink-level metric totals for a date range.
|
|
673
729
|
*
|
|
@@ -687,18 +743,38 @@ var SoundlinksResource = class {
|
|
|
687
743
|
}
|
|
688
744
|
});
|
|
689
745
|
}
|
|
746
|
+
};
|
|
747
|
+
var SoundlinkBreakdownMetricsResource = class {
|
|
748
|
+
constructor(http) {
|
|
749
|
+
this.http = http;
|
|
750
|
+
this.export = createExportResource(
|
|
751
|
+
http,
|
|
752
|
+
(soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown/export`,
|
|
753
|
+
(params) => ({
|
|
754
|
+
startDate: params.startDate,
|
|
755
|
+
endDate: params.endDate
|
|
756
|
+
})
|
|
757
|
+
);
|
|
758
|
+
}
|
|
759
|
+
http;
|
|
760
|
+
/**
|
|
761
|
+
* Stream full breakdown export as JSONL.
|
|
762
|
+
*
|
|
763
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
|
|
764
|
+
*/
|
|
765
|
+
export;
|
|
690
766
|
/**
|
|
691
|
-
*
|
|
767
|
+
* Paginated per-day, per-country breakdown rows.
|
|
692
768
|
*
|
|
693
|
-
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/
|
|
694
|
-
* Max `pageSize` is **500** (default 50).
|
|
769
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
|
|
770
|
+
* Max `pageSize` is **500** (default 50).
|
|
695
771
|
*
|
|
696
772
|
* @param soundlinkId - Soundlink identifier.
|
|
697
773
|
* @param params - Date range, pagination, and sort options.
|
|
698
774
|
*/
|
|
699
|
-
|
|
775
|
+
list(soundlinkId, params = {}) {
|
|
700
776
|
return this.http.get({
|
|
701
|
-
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/
|
|
777
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown`,
|
|
702
778
|
query: {
|
|
703
779
|
startDate: params.startDate,
|
|
704
780
|
endDate: params.endDate,
|
|
@@ -709,25 +785,43 @@ var SoundlinksResource = class {
|
|
|
709
785
|
}
|
|
710
786
|
});
|
|
711
787
|
}
|
|
788
|
+
};
|
|
789
|
+
var SoundlinkEngagementMetricsResource = class {
|
|
790
|
+
constructor(http) {
|
|
791
|
+
this.http = http;
|
|
792
|
+
this.export = createExportResource(
|
|
793
|
+
http,
|
|
794
|
+
(soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement/export`,
|
|
795
|
+
(params) => ({
|
|
796
|
+
startDate: params.startDate,
|
|
797
|
+
endDate: params.endDate,
|
|
798
|
+
engagementContext: params.engagementContext
|
|
799
|
+
})
|
|
800
|
+
);
|
|
801
|
+
}
|
|
802
|
+
http;
|
|
712
803
|
/**
|
|
713
|
-
*
|
|
804
|
+
* Stream full engagement export as JSONL.
|
|
714
805
|
*
|
|
715
|
-
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
|
|
716
|
-
|
|
806
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
|
|
807
|
+
*/
|
|
808
|
+
export;
|
|
809
|
+
/**
|
|
810
|
+
* Paginated per-day, per-track engagement rows.
|
|
717
811
|
*
|
|
718
|
-
*
|
|
719
|
-
*
|
|
720
|
-
* `startDate` always uses all-time (not createdAt).
|
|
812
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
|
|
813
|
+
* Max `pageSize` is **500** (default 50).
|
|
721
814
|
*
|
|
722
815
|
* @param soundlinkId - Soundlink identifier.
|
|
723
|
-
* @param params - Date range, pagination, and sort
|
|
816
|
+
* @param params - Date range, engagement context filter, pagination, and sort.
|
|
724
817
|
*/
|
|
725
|
-
|
|
818
|
+
list(soundlinkId, params = {}) {
|
|
726
819
|
return this.http.get({
|
|
727
820
|
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement`,
|
|
728
821
|
query: {
|
|
729
822
|
startDate: params.startDate,
|
|
730
823
|
endDate: params.endDate,
|
|
824
|
+
engagementContext: params.engagementContext,
|
|
731
825
|
page: params.page,
|
|
732
826
|
pageSize: params.pageSize,
|
|
733
827
|
sortBy: params.sortBy,
|
|
@@ -846,7 +940,7 @@ var Soundlink = class {
|
|
|
846
940
|
strategies;
|
|
847
941
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
848
942
|
campaigns;
|
|
849
|
-
/** Self-serve soundlinks
|
|
943
|
+
/** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
|
|
850
944
|
soundlinks;
|
|
851
945
|
/** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
|
|
852
946
|
metrics;
|