soundlink 2.0.0 → 2.2.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.
@@ -1,5 +1,5 @@
1
1
  /** Stable snake_case error codes returned by the Soundlink Public API. */
2
- type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | 'mixed_credentials' | 'insufficient_scope' | 'not_found' | 'campaign_not_found' | 'invalid_query_parameter' | 'invalid_date_range' | 'page_size_exceeded' | 'invalid_request' | 'invalid_genre' | 'invalid_duration_or_budget' | 'invalid_daily_budget' | 'invalid_duration_days' | 'invalid_spotify_url' | 'invalid_tier_budget_allocation' | 'invalid_tier_status' | 'tier_update_cooldown' | 'wallet_not_enabled' | 'insufficient_credit' | 'idempotency_key_conflict' | 'rate_limit_exceeded' | 'invalid_video_url' | 'video_import_limit_exceeded' | 'video_import_session_not_found' | 'internal_error';
2
+ type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | 'invalid_token' | 'insufficient_scope' | 'access_denied' | 'not_found' | 'campaign_not_found' | 'invalid_query_parameter' | 'invalid_date_range' | 'page_size_exceeded' | 'invalid_request' | 'invalid_genre' | 'invalid_duration_or_budget' | 'invalid_daily_budget' | 'invalid_duration_days' | 'invalid_spotify_url' | 'invalid_tier_budget_allocation' | 'invalid_tier_status' | 'tier_update_cooldown' | 'wallet_not_enabled' | 'insufficient_credit' | 'idempotency_key_conflict' | 'rate_limit_exceeded' | 'invalid_video_url' | 'video_import_limit_exceeded' | 'video_import_session_not_found' | 'internal_error';
3
3
  /**
4
4
  * Campaign lifecycle status.
5
5
  *
@@ -26,10 +26,20 @@ type CampaignGeneration = 1 | 2 | 3;
26
26
  type EngagementContext = 'catalog' | 'playlist';
27
27
  /** Allowed `sortBy` values for {@link CampaignListParams}. */
28
28
  type CampaignSortBy = 'createdAt' | 'status';
29
+ /** Allowed `sortBy` values for {@link SoundlinkListParams}. */
30
+ type SoundlinkSortBy = 'createdAt';
29
31
  /** Allowed `sortBy` values for breakdown list requests. */
30
32
  type BreakdownSortBy = 'report_date' | 'spend_total';
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';
31
37
  /** Sort direction for list endpoints. */
32
38
  type SortOrder = 'asc' | 'desc';
39
+ /** Lifecycle status for a self-serve soundlink. */
40
+ type SoundlinkStatus = 'draft' | 'active' | 'archived';
41
+ /** Spotify resource type promoted by a soundlink. */
42
+ type SoundlinkTargetType = 'track' | 'album' | 'playlist';
33
43
  /** Growth strategy for campaign create / catalog. */
34
44
  type StrategyType = 'maximum_growth' | 'market_discovery' | 'revenue_maximization' | 'custom';
35
45
  /** Non-custom strategies (platform default tiering; no `tierTargeting`). */
@@ -369,6 +379,17 @@ interface CampaignListParams {
369
379
  /** Sort direction. Default: `desc`. */
370
380
  sortOrder?: SortOrder;
371
381
  }
382
+ /** Query params for {@link SoundlinksResource.list}. */
383
+ interface SoundlinkListParams {
384
+ /** Page number (1-indexed). Default: `1`. */
385
+ page?: number;
386
+ /** Items per page. Default: `10`. Max: **100**. */
387
+ pageSize?: number;
388
+ /** Sort field. Default: `createdAt`. */
389
+ sortBy?: SoundlinkSortBy;
390
+ /** Sort direction. Default: `desc`. */
391
+ sortOrder?: SortOrder;
392
+ }
372
393
  /** Inclusive date range filter (`YYYY-MM-DD`). */
373
394
  interface DateRangeParams {
374
395
  /** Inclusive start date. */
@@ -376,6 +397,138 @@ interface DateRangeParams {
376
397
  /** Inclusive end date. Must not be before `startDate`. */
377
398
  endDate?: string;
378
399
  }
400
+ /** Self-serve soundlink summary from {@link SoundlinksResource.list}. */
401
+ interface SoundlinkSummary {
402
+ soundlinkId: string;
403
+ organizationId: string;
404
+ name: string;
405
+ /** Public landing page URL (`https://sndl.ink/soundlink/...`). */
406
+ url: string;
407
+ targetType: SoundlinkTargetType | null;
408
+ spotifyUrl: string | null;
409
+ status: SoundlinkStatus;
410
+ /** ISO 8601 creation timestamp. */
411
+ createdAt: string;
412
+ }
413
+ /** Full soundlink detail from {@link SoundlinksResource.get}. */
414
+ interface SoundlinkDetail extends SoundlinkSummary {
415
+ autoFollow: boolean;
416
+ metaPixelId: string | null;
417
+ tiktokPixelId: string | null;
418
+ }
419
+ /** Paginated soundlink list payload. */
420
+ interface SoundlinkListData {
421
+ items: SoundlinkSummary[];
422
+ pagination: Pagination;
423
+ }
424
+ /**
425
+ * Soundlink-level metric totals from {@link SoundlinksResource.metricsOverview}.
426
+ *
427
+ * No financial fields — ads for self-serve soundlinks run in the customer's Meta.
428
+ */
429
+ interface SoundlinkMetricsOverview {
430
+ views: number;
431
+ link_clicks: number | null;
432
+ streams: number;
433
+ listeners: number;
434
+ followers: number;
435
+ streams_per_listener: number;
436
+ ctr_lp: number | null;
437
+ }
438
+ /** One row of the `soundlink_country_daily` v1.0 schema. */
439
+ interface SoundlinkBreakdownRow {
440
+ provider: 'soundlink';
441
+ account_id: string;
442
+ schema_version: string;
443
+ /** UTC calendar date (`YYYY-MM-DD`). */
444
+ report_date: string;
445
+ report_date_timezone: 'UTC';
446
+ exported_at: string;
447
+ soundlink_id: string;
448
+ soundlink_name: string;
449
+ soundlink_target_type: 'track' | 'playlist' | null;
450
+ soundlink_target_isrc: string | null;
451
+ soundlink_target_spotify_track_id: string | null;
452
+ soundlink_target_playlist_id: string | null;
453
+ country_code: string;
454
+ views: number;
455
+ link_clicks: number | null;
456
+ streams: number;
457
+ listeners: number;
458
+ new_listeners: number | null;
459
+ returning_listeners: number | null;
460
+ new_listener_streams: number | null;
461
+ returning_listener_streams: number | null;
462
+ followers: number;
463
+ streams_per_listener: number;
464
+ ctr_lp: number | null;
465
+ }
466
+ /** Paginated soundlink breakdown list payload. */
467
+ interface SoundlinkBreakdownListData {
468
+ schemaVersion: string;
469
+ items: SoundlinkBreakdownRow[];
470
+ pagination: Pagination;
471
+ }
472
+ /** One row of the `soundlink_engagement_daily` v1.0 schema. */
473
+ interface SoundlinkEngagementRow {
474
+ provider: 'soundlink';
475
+ account_id: string;
476
+ schema_version: string;
477
+ report_date: string;
478
+ report_date_timezone: 'UTC';
479
+ exported_at: string;
480
+ soundlink_id: string;
481
+ soundlink_name: string;
482
+ soundlink_target_type: 'track' | 'playlist' | null;
483
+ soundlink_target_isrc: string | null;
484
+ soundlink_target_spotify_track_id: string | null;
485
+ soundlink_target_playlist_id: string | null;
486
+ engagement_context: EngagementContext;
487
+ country_code: string;
488
+ engaged_track_isrc: string | null;
489
+ engaged_spotify_track_id: string;
490
+ engaged_track_name: string;
491
+ playlist_position: number | null;
492
+ new_listeners: number;
493
+ returning_listeners: number;
494
+ listeners: number;
495
+ new_listener_streams: number;
496
+ returning_listener_streams: number;
497
+ streams: number;
498
+ spl: number;
499
+ }
500
+ /** Paginated soundlink engagement list payload. */
501
+ interface SoundlinkEngagementListData {
502
+ schemaVersion: string;
503
+ items: SoundlinkEngagementRow[];
504
+ pagination: Pagination;
505
+ }
506
+ /** Query params for {@link SoundlinkBreakdownMetricsResource.list}. */
507
+ interface SoundlinkBreakdownListParams extends DateRangeParams {
508
+ page?: number;
509
+ /** Default: `50`. Max: **500**. */
510
+ pageSize?: number;
511
+ /** Default: `report_date`. */
512
+ sortBy?: SoundlinkBreakdownSortBy;
513
+ /** Default: `asc`. */
514
+ sortOrder?: SortOrder;
515
+ }
516
+ /**
517
+ * Query params for {@link SoundlinkEngagementMetricsResource.list}.
518
+ *
519
+ * Defaults to the last 90 days ending today; max **90 days** per request.
520
+ */
521
+ interface SoundlinkEngagementListParams extends DateRangeParams {
522
+ page?: number;
523
+ /** Default: `50`. Max: **500**. */
524
+ pageSize?: number;
525
+ /** Filter to a single engagement context. Omit to return both. */
526
+ engagementContext?: EngagementContext;
527
+ /** Default: `report_date`. */
528
+ sortBy?: SoundlinkEngagementSortBy;
529
+ /** Default: `asc`. */
530
+ sortOrder?: SortOrder;
531
+ }
379
532
  /** Query params for {@link BreakdownMetricsResource.list}. */
380
533
  interface BreakdownListParams extends DateRangeParams {
381
534
  page?: number;
@@ -457,16 +610,16 @@ interface ExportResource<T, P extends DateRangeParams> {
457
610
  /**
458
611
  * Stream export rows as newline-delimited JSON.
459
612
  *
460
- * @param campaignId - Soundlink campaign ID.
613
+ * @param id - Campaign or soundlink ID.
461
614
  * @param params - Optional date range (max 90 days per request).
462
615
  */
463
- (campaignId: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
616
+ (id: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
464
617
  /**
465
618
  * Download all export rows into memory.
466
619
  *
467
620
  * Prefer {@link ExportResource | the stream} for large datasets.
468
621
  */
469
- collect(campaignId: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
622
+ collect(id: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
470
623
  }
471
624
  /** System endpoints (`GET /v1/ping`). */
472
625
  declare class PingResource {
@@ -606,6 +759,112 @@ declare class CampaignsResource {
606
759
  */
607
760
  listAll(params?: Omit<CampaignListParams, 'page'>): AsyncGenerator<CampaignListData['items'][number], void, void>;
608
761
  }
762
+ /**
763
+ * Self-serve soundlinks (`/v1/soundlinks/*`). Requires `soundlinks:read`.
764
+ *
765
+ * Only soundlinks that are **not** linked to a campaign. Campaign-backed
766
+ * soundlinks are served by the Campaigns API.
767
+ *
768
+ * @example
769
+ * ```ts
770
+ * await soundlink.soundlinks.list();
771
+ * await soundlink.soundlinks.get(soundlinkId);
772
+ * await soundlink.soundlinks.metricsOverview(soundlinkId);
773
+ * await soundlink.soundlinks.breakdown.list(soundlinkId);
774
+ * await soundlink.soundlinks.engagement.export(soundlinkId);
775
+ * ```
776
+ */
777
+ declare class SoundlinksResource {
778
+ private readonly http;
779
+ /** Per-day country breakdown and JSONL export. */
780
+ readonly breakdown: SoundlinkBreakdownMetricsResource;
781
+ /** Per-day track engagement and JSONL export. */
782
+ readonly engagement: SoundlinkEngagementMetricsResource;
783
+ constructor(http: HttpClient);
784
+ /**
785
+ * List self-serve soundlinks for the authenticated organization.
786
+ *
787
+ * Maps to `GET /v1/soundlinks`. Max `pageSize` is **100**. Requires `soundlinks:read`.
788
+ *
789
+ * @param params - Pagination and sort options.
790
+ *
791
+ * @example
792
+ * ```ts
793
+ * const { data, error } = await soundlink.soundlinks.list({ page: 1, pageSize: 100 });
794
+ * ```
795
+ */
796
+ list(params?: SoundlinkListParams): Promise<ApiResponse<SoundlinkListData>>;
797
+ /**
798
+ * Fetch details for a single self-serve soundlink.
799
+ *
800
+ * Maps to `GET /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:read`.
801
+ * Campaign-linked soundlinks return `404`.
802
+ *
803
+ * @param soundlinkId - Identifier returned by {@link SoundlinksResource.list}.
804
+ */
805
+ get(soundlinkId: string): Promise<ApiResponse<SoundlinkDetail>>;
806
+ /**
807
+ * Soundlink-level metric totals for a date range.
808
+ *
809
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/overview`.
810
+ * Omit `startDate` to default to the soundlink creation date.
811
+ * No financial fields. Requires `soundlinks:read`.
812
+ *
813
+ * @param soundlinkId - Soundlink identifier.
814
+ * @param params - Inclusive `YYYY-MM-DD` date range.
815
+ */
816
+ metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
817
+ }
818
+ /**
819
+ * Country-level daily metrics (`soundlink_country_daily` schema).
820
+ *
821
+ * Access via `soundlink.soundlinks.breakdown`.
822
+ */
823
+ declare class SoundlinkBreakdownMetricsResource {
824
+ private readonly http;
825
+ /**
826
+ * Stream full breakdown export as JSONL.
827
+ *
828
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
829
+ */
830
+ readonly export: ExportResource<SoundlinkBreakdownRow, BreakdownExportParams>;
831
+ constructor(http: HttpClient);
832
+ /**
833
+ * Paginated per-day, per-country breakdown rows.
834
+ *
835
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
836
+ * Max `pageSize` is **500** (default 50).
837
+ *
838
+ * @param soundlinkId - Soundlink identifier.
839
+ * @param params - Date range, pagination, and sort options.
840
+ */
841
+ list(soundlinkId: string, params?: SoundlinkBreakdownListParams): Promise<ApiResponse<SoundlinkBreakdownListData>>;
842
+ }
843
+ /**
844
+ * Per-track engagement metrics (`soundlink_engagement_daily` schema).
845
+ *
846
+ * Access via `soundlink.soundlinks.engagement`.
847
+ */
848
+ declare class SoundlinkEngagementMetricsResource {
849
+ private readonly http;
850
+ /**
851
+ * Stream full engagement export as JSONL.
852
+ *
853
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
854
+ */
855
+ readonly export: ExportResource<SoundlinkEngagementRow, EngagementExportParams>;
856
+ constructor(http: HttpClient);
857
+ /**
858
+ * Paginated per-day, per-track engagement rows.
859
+ *
860
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
861
+ * Max `pageSize` is **500** (default 50).
862
+ *
863
+ * @param soundlinkId - Soundlink identifier.
864
+ * @param params - Date range, engagement context filter, pagination, and sort.
865
+ */
866
+ list(soundlinkId: string, params?: SoundlinkEngagementListParams): Promise<ApiResponse<SoundlinkEngagementListData>>;
867
+ }
609
868
  /**
610
869
  * Campaign metrics (`/v1/campaigns/{id}/metrics/*`). Requires `metrics:read`.
611
870
  *
@@ -712,6 +971,8 @@ declare class Soundlink {
712
971
  readonly strategies: StrategiesResource;
713
972
  /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
714
973
  readonly campaigns: CampaignsResource;
974
+ /** Self-serve soundlinks (list, detail, metrics). Requires `soundlinks:read` scope. */
975
+ readonly soundlinks: SoundlinksResource;
715
976
  /** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
716
977
  readonly metrics: MetricsResource;
717
978
  /**
@@ -744,6 +1005,7 @@ declare const DEFAULT_TIMEOUT_MS = 30000;
744
1005
  declare const DEFAULT_MAX_RETRIES = 2;
745
1006
  declare const API_KEY_PREFIX = "sk_";
746
1007
  declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
1008
+ declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
747
1009
  declare const METRICS_MAX_PAGE_SIZE = 500;
748
1010
 
749
- 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, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignTiersRequest, getStreamRowCount, resolveClientOptions };
1011
+ 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 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
@@ -4,6 +4,7 @@ var DEFAULT_TIMEOUT_MS = 3e4;
4
4
  var DEFAULT_MAX_RETRIES = 2;
5
5
  var API_KEY_PREFIX = "sk_";
6
6
  var CAMPAIGNS_MAX_PAGE_SIZE = 100;
7
+ var SOUNDLINKS_MAX_PAGE_SIZE = 100;
7
8
  var METRICS_MAX_PAGE_SIZE = 500;
8
9
  var API_VERSION_PREFIX = "/v1";
9
10
 
@@ -395,14 +396,14 @@ function getStreamRowCount(stream) {
395
396
 
396
397
  // src/resources/index.ts
397
398
  function createExportResource(http, buildPath, buildQuery) {
398
- const exportFn = ((campaignId, params = {}) => {
399
+ const exportFn = ((id, params = {}) => {
399
400
  return http.getJsonl({
400
- path: buildPath(campaignId),
401
+ path: buildPath(id),
401
402
  query: buildQuery(params)
402
403
  });
403
404
  });
404
- exportFn.collect = async (campaignId, params = {}) => {
405
- const response = await exportFn(campaignId, params);
405
+ exportFn.collect = async (id, params = {}) => {
406
+ const response = await exportFn(id, params);
406
407
  if (response.error || !response.data) {
407
408
  return {
408
409
  data: null,
@@ -626,6 +627,159 @@ var CampaignsResource = class {
626
627
  }
627
628
  }
628
629
  };
630
+ var SoundlinksResource = class {
631
+ constructor(http) {
632
+ this.http = http;
633
+ this.breakdown = new SoundlinkBreakdownMetricsResource(http);
634
+ this.engagement = new SoundlinkEngagementMetricsResource(http);
635
+ }
636
+ http;
637
+ /** Per-day country breakdown and JSONL export. */
638
+ breakdown;
639
+ /** Per-day track engagement and JSONL export. */
640
+ engagement;
641
+ /**
642
+ * List self-serve soundlinks for the authenticated organization.
643
+ *
644
+ * Maps to `GET /v1/soundlinks`. Max `pageSize` is **100**. Requires `soundlinks:read`.
645
+ *
646
+ * @param params - Pagination and sort options.
647
+ *
648
+ * @example
649
+ * ```ts
650
+ * const { data, error } = await soundlink.soundlinks.list({ page: 1, pageSize: 100 });
651
+ * ```
652
+ */
653
+ list(params = {}) {
654
+ return this.http.get({
655
+ path: "/soundlinks",
656
+ query: {
657
+ page: params.page,
658
+ pageSize: params.pageSize,
659
+ sortBy: params.sortBy,
660
+ sortOrder: params.sortOrder
661
+ }
662
+ });
663
+ }
664
+ /**
665
+ * Fetch details for a single self-serve soundlink.
666
+ *
667
+ * Maps to `GET /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:read`.
668
+ * Campaign-linked soundlinks return `404`.
669
+ *
670
+ * @param soundlinkId - Identifier returned by {@link SoundlinksResource.list}.
671
+ */
672
+ get(soundlinkId) {
673
+ return this.http.get({
674
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}`
675
+ });
676
+ }
677
+ /**
678
+ * Soundlink-level metric totals for a date range.
679
+ *
680
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/overview`.
681
+ * Omit `startDate` to default to the soundlink creation date.
682
+ * No financial fields. Requires `soundlinks:read`.
683
+ *
684
+ * @param soundlinkId - Soundlink identifier.
685
+ * @param params - Inclusive `YYYY-MM-DD` date range.
686
+ */
687
+ metricsOverview(soundlinkId, params = {}) {
688
+ return this.http.get({
689
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/overview`,
690
+ query: {
691
+ startDate: params.startDate,
692
+ endDate: params.endDate
693
+ }
694
+ });
695
+ }
696
+ };
697
+ var SoundlinkBreakdownMetricsResource = class {
698
+ constructor(http) {
699
+ this.http = http;
700
+ this.export = createExportResource(
701
+ http,
702
+ (soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown/export`,
703
+ (params) => ({
704
+ startDate: params.startDate,
705
+ endDate: params.endDate
706
+ })
707
+ );
708
+ }
709
+ http;
710
+ /**
711
+ * Stream full breakdown export as JSONL.
712
+ *
713
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
714
+ */
715
+ export;
716
+ /**
717
+ * Paginated per-day, per-country breakdown rows.
718
+ *
719
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
720
+ * Max `pageSize` is **500** (default 50).
721
+ *
722
+ * @param soundlinkId - Soundlink identifier.
723
+ * @param params - Date range, pagination, and sort options.
724
+ */
725
+ list(soundlinkId, params = {}) {
726
+ return this.http.get({
727
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown`,
728
+ query: {
729
+ startDate: params.startDate,
730
+ endDate: params.endDate,
731
+ page: params.page,
732
+ pageSize: params.pageSize,
733
+ sortBy: params.sortBy,
734
+ sortOrder: params.sortOrder
735
+ }
736
+ });
737
+ }
738
+ };
739
+ var SoundlinkEngagementMetricsResource = class {
740
+ constructor(http) {
741
+ this.http = http;
742
+ this.export = createExportResource(
743
+ http,
744
+ (soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement/export`,
745
+ (params) => ({
746
+ startDate: params.startDate,
747
+ endDate: params.endDate,
748
+ engagementContext: params.engagementContext
749
+ })
750
+ );
751
+ }
752
+ http;
753
+ /**
754
+ * Stream full engagement export as JSONL.
755
+ *
756
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
757
+ */
758
+ export;
759
+ /**
760
+ * Paginated per-day, per-track engagement rows.
761
+ *
762
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
763
+ * Max `pageSize` is **500** (default 50).
764
+ *
765
+ * @param soundlinkId - Soundlink identifier.
766
+ * @param params - Date range, engagement context filter, pagination, and sort.
767
+ */
768
+ list(soundlinkId, params = {}) {
769
+ return this.http.get({
770
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement`,
771
+ query: {
772
+ startDate: params.startDate,
773
+ endDate: params.endDate,
774
+ engagementContext: params.engagementContext,
775
+ page: params.page,
776
+ pageSize: params.pageSize,
777
+ sortBy: params.sortBy,
778
+ sortOrder: params.sortOrder
779
+ }
780
+ });
781
+ }
782
+ };
629
783
  var MetricsResource = class {
630
784
  constructor(http) {
631
785
  this.http = http;
@@ -736,6 +890,8 @@ var Soundlink = class {
736
890
  strategies;
737
891
  /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
738
892
  campaigns;
893
+ /** Self-serve soundlinks (list, detail, metrics). Requires `soundlinks:read` scope. */
894
+ soundlinks;
739
895
  /** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
740
896
  metrics;
741
897
  /**
@@ -749,10 +905,11 @@ var Soundlink = class {
749
905
  this.ping = pingResource.ping.bind(pingResource);
750
906
  this.strategies = new StrategiesResource(http);
751
907
  this.campaigns = new CampaignsResource(http);
908
+ this.soundlinks = new SoundlinksResource(http);
752
909
  this.metrics = new MetricsResource(http);
753
910
  }
754
911
  };
755
912
 
756
- export { API_KEY_PREFIX, CAMPAIGNS_MAX_PAGE_SIZE, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, HttpClient, METRICS_MAX_PAGE_SIZE, Soundlink, SoundlinkConfigError, SoundlinkParseError, SoundlinkSdkError, getStreamRowCount, resolveClientOptions };
913
+ export { API_KEY_PREFIX, CAMPAIGNS_MAX_PAGE_SIZE, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, HttpClient, METRICS_MAX_PAGE_SIZE, SOUNDLINKS_MAX_PAGE_SIZE, Soundlink, SoundlinkConfigError, SoundlinkParseError, SoundlinkSdkError, getStreamRowCount, resolveClientOptions };
757
914
  //# sourceMappingURL=index.js.map
758
915
  //# sourceMappingURL=index.js.map