soundlink 2.6.0 → 2.8.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.
@@ -660,6 +660,9 @@ interface SoundlinkBreakdownRow {
660
660
  country_code: string;
661
661
  views: number;
662
662
  link_clicks: number | null;
663
+ spotify_link_clicks: number;
664
+ apple_music_link_clicks: number;
665
+ youtube_music_link_clicks: number;
663
666
  streams: number;
664
667
  listeners: number;
665
668
  new_listeners: number | null;
@@ -752,10 +755,104 @@ interface EngagementExportParams extends DateRangeParams {
752
755
  }
753
756
  /** Query params for breakdown JSONL export. Max **90 days** per request. */
754
757
  type BreakdownExportParams = DateRangeParams;
758
+ /**
759
+ * One row of the `soundlink_cohort_retention_daily` v1.0 schema.
760
+ * Day-N fields are `null` until that day has passed for the cohort date.
761
+ */
762
+ interface CohortRetentionDailyRow {
763
+ provider: 'soundlink';
764
+ account_id: string;
765
+ schema_version: string;
766
+ /** UTC calendar date (`YYYY-MM-DD`). */
767
+ cohort_date: string;
768
+ cohort_date_timezone: 'UTC';
769
+ exported_at: string;
770
+ soundlink_id: string;
771
+ soundlink_name: string;
772
+ soundlink_target_type: 'track' | 'playlist' | null;
773
+ soundlink_target_isrc?: string | null;
774
+ soundlink_target_spotify_track_id?: string | null;
775
+ soundlink_target_playlist_id?: string | null;
776
+ cohort_size: number;
777
+ returned_on_day_1: number | null;
778
+ retention_by_day_1: number | null;
779
+ returned_on_day_2: number | null;
780
+ retention_by_day_2: number | null;
781
+ returned_on_day_3: number | null;
782
+ retention_by_day_3: number | null;
783
+ returned_on_day_4: number | null;
784
+ retention_by_day_4: number | null;
785
+ returned_on_day_5: number | null;
786
+ retention_by_day_5: number | null;
787
+ returned_on_day_6: number | null;
788
+ retention_by_day_6: number | null;
789
+ returned_on_day_7: number | null;
790
+ retention_by_day_7: number | null;
791
+ }
792
+ /** Payload from campaign/soundlink `metrics/retention`. */
793
+ interface CohortRetentionListData {
794
+ schemaVersion: string;
795
+ items: CohortRetentionDailyRow[];
796
+ }
797
+ /** Path param for listening-insights endpoints. */
798
+ type ListeningInsight = 'other-artists' | 'catalog-dig-in' | 'stream-split';
799
+ /** Date window returned with every listening insight (from the listening graph). */
800
+ interface ListeningInsightWindow {
801
+ startDate: string;
802
+ endDate: string;
803
+ }
804
+ interface OtherArtistsInsightArtist {
805
+ /** Lowercased, trimmed artist name. */
806
+ artist: string;
807
+ listeners: number;
808
+ streams: number;
809
+ }
810
+ interface OtherArtistsListeningInsight {
811
+ soundlinkId: string;
812
+ campaignId: string | null;
813
+ insight: 'other-artists';
814
+ window: ListeningInsightWindow;
815
+ artists: OtherArtistsInsightArtist[];
816
+ }
817
+ interface CatalogDigInInsightArtist {
818
+ artist: string;
819
+ playlistListeners: number;
820
+ playlistStreams: number;
821
+ catalogListeners: number;
822
+ catalogStreams: number;
823
+ catalogTracks: number;
824
+ /** catalogListeners / playlistListeners. Null when playlistListeners is 0. */
825
+ catalogListenerRate: number | null;
826
+ }
827
+ interface CatalogDigInListeningInsight {
828
+ soundlinkId: string;
829
+ campaignId: string | null;
830
+ insight: 'catalog-dig-in';
831
+ window: ListeningInsightWindow;
832
+ artists: CatalogDigInInsightArtist[];
833
+ }
834
+ type StreamSplitEngagementContext = 'promoted' | 'playlist' | 'artist_catalog';
835
+ interface StreamSplitContext {
836
+ engagementContext: StreamSplitEngagementContext;
837
+ listeners: number;
838
+ streams: number;
839
+ tracks: number;
840
+ }
841
+ interface StreamSplitListeningInsight {
842
+ soundlinkId: string;
843
+ campaignId: string | null;
844
+ insight: 'stream-split';
845
+ window: ListeningInsightWindow;
846
+ contexts: StreamSplitContext[];
847
+ }
848
+ /** Discriminated on `insight`. */
849
+ type ListeningInsightsData = OtherArtistsListeningInsight | CatalogDigInListeningInsight | StreamSplitListeningInsight;
755
850
 
756
851
  interface HttpGetOptions {
757
852
  path: string;
758
853
  query?: Record<string, string | number | boolean | undefined | null>;
854
+ /** Override the client timeout for this request only (milliseconds). */
855
+ timeout?: number;
759
856
  }
760
857
  interface HttpJsonlOptions extends HttpGetOptions {
761
858
  accept?: string;
@@ -785,7 +882,7 @@ declare class HttpClient {
785
882
  private readonly options;
786
883
  constructor(options: SoundlinkOptions);
787
884
  get resolvedOptions(): ResolvedSoundlinkClientOptions;
788
- get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
885
+ get<T>({ path, query, timeout }: HttpGetOptions): Promise<ApiResponse<T>>;
789
886
  post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
790
887
  patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
791
888
  put<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
@@ -981,6 +1078,15 @@ declare class CampaignsResource {
981
1078
  * Omit `startDate` for the full history. Max `pageSize` is **100**.
982
1079
  */
983
1080
  activity(campaignId: string, params?: CampaignActivityParams): Promise<ApiResponse<CampaignActivityData>>;
1081
+ /**
1082
+ * What listeners who connected through this campaign went on to play.
1083
+ *
1084
+ * Maps to `GET /v1/campaigns/{campaignId}/listening-insights/{insight}`.
1085
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1086
+ * Date window comes from the listening graph — do not send `startDate`/`endDate`.
1087
+ * Uses a 120s timeout (insights often take 30–50s).
1088
+ */
1089
+ listeningInsights(campaignId: string, insight: ListeningInsight): Promise<ApiResponse<ListeningInsightsData>>;
984
1090
  /**
985
1091
  * Create a wallet-funded campaign.
986
1092
  *
@@ -1126,6 +1232,23 @@ declare class SoundlinksResource {
1126
1232
  * @param params - Inclusive `YYYY-MM-DD` date range.
1127
1233
  */
1128
1234
  metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
1235
+ /**
1236
+ * Cohort retention for a soundlink (`soundlink_cohort_retention_daily`).
1237
+ *
1238
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/retention`.
1239
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1240
+ * One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
1241
+ */
1242
+ retention(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<CohortRetentionListData>>;
1243
+ /**
1244
+ * What listeners who connected through this soundlink went on to play.
1245
+ *
1246
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/listening-insights/{insight}`.
1247
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1248
+ * Date window comes from the listening graph — do not send `startDate`/`endDate`.
1249
+ * Uses a 120s timeout (insights often take 30–50s).
1250
+ */
1251
+ listeningInsights(soundlinkId: string, insight: ListeningInsight): Promise<ApiResponse<ListeningInsightsData>>;
1129
1252
  }
1130
1253
  /**
1131
1254
  * Country-level daily metrics (`soundlink_country_daily` schema).
@@ -1227,6 +1350,14 @@ declare class MetricsResource {
1227
1350
  * Max `pageSize` is **500**.
1228
1351
  */
1229
1352
  creativeDaily(campaignId: string, params?: CreativeDailyParams): Promise<ApiResponse<CreativeDailyData>>;
1353
+ /**
1354
+ * Cohort retention for the campaign's linked soundlink (`soundlink_cohort_retention_daily`).
1355
+ *
1356
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/retention`.
1357
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1358
+ * One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
1359
+ */
1360
+ retention(campaignId: string, params?: DateRangeParams): Promise<ApiResponse<CohortRetentionListData>>;
1230
1361
  }
1231
1362
  /**
1232
1363
  * Country-level daily metrics (`campaign_country_daily` schema).
@@ -1333,10 +1464,12 @@ declare class SoundlinkConfigError extends SoundlinkSdkError {
1333
1464
 
1334
1465
  declare const DEFAULT_BASE_URL = "https://api.getsoundlink.com";
1335
1466
  declare const DEFAULT_TIMEOUT_MS = 30000;
1467
+ /** Listening insights often take 30–50s; the Public API recommends ≥120s. */
1468
+ declare const LISTENING_INSIGHTS_TIMEOUT_MS = 120000;
1336
1469
  declare const DEFAULT_MAX_RETRIES = 2;
1337
1470
  declare const API_KEY_PREFIX = "sk_";
1338
1471
  declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
1339
1472
  declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
1340
1473
  declare const METRICS_MAX_PAGE_SIZE = 500;
1341
1474
 
1342
- 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 CampaignActivityData, type CampaignActivityItem, type CampaignActivityParams, type CampaignAutoRenewData, 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 CreativeDailyData, type CreativeDailyParams, type CreativeDailyRow, type CreativeDirection, type CreativeMetrics, type CreativeMetricsChild, type CreativeMetricsGroup, 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 Pixel, type PixelListData, type PixelPlatform, type PixelTestEventData, 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 TierLearningStatus, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignAutoRenewRequest, type UpdateCampaignTiersRequest, type UpdatePixelRequest, type WalletData, getStreamRowCount, resolveClientOptions };
1475
+ 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 CampaignActivityData, type CampaignActivityItem, type CampaignActivityParams, type CampaignAutoRenewData, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CatalogDigInInsightArtist, type CatalogDigInListeningInsight, type CohortRetentionDailyRow, type CohortRetentionListData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreateSoundlinkRequest, type CreativeDailyData, type CreativeDailyParams, type CreativeDailyRow, type CreativeDirection, type CreativeMetrics, type CreativeMetricsChild, type CreativeMetricsGroup, 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, LISTENING_INSIGHTS_TIMEOUT_MS, type ListeningInsight, type ListeningInsightWindow, type ListeningInsightsData, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type OtherArtistsInsightArtist, type OtherArtistsListeningInsight, type Pagination, type PingData, type Pixel, type PixelListData, type PixelPlatform, type PixelTestEventData, 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 StreamSplitContext, type StreamSplitEngagementContext, type StreamSplitListeningInsight, type TierLearningStatus, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignAutoRenewRequest, type UpdateCampaignTiersRequest, type UpdatePixelRequest, type WalletData, getStreamRowCount, resolveClientOptions };
package/dist/esm/index.js CHANGED
@@ -1,6 +1,7 @@
1
1
  // src/constants/defaults.ts
2
2
  var DEFAULT_BASE_URL = "https://api.getsoundlink.com";
3
3
  var DEFAULT_TIMEOUT_MS = 3e4;
4
+ var LISTENING_INSIGHTS_TIMEOUT_MS = 12e4;
4
5
  var DEFAULT_MAX_RETRIES = 2;
5
6
  var API_KEY_PREFIX = "sk_";
6
7
  var CAMPAIGNS_MAX_PAGE_SIZE = 100;
@@ -197,15 +198,19 @@ var HttpClient = class {
197
198
  get resolvedOptions() {
198
199
  return this.options;
199
200
  }
200
- async get({ path, query }) {
201
+ async get({ path, query, timeout }) {
201
202
  const url = joinUrl(
202
203
  this.options.baseUrl,
203
204
  `${API_VERSION_PREFIX}${path}${buildQueryString(query ?? {})}`
204
205
  );
205
- return this.requestJson(url, {
206
- method: "GET",
207
- headers: this.buildHeaders()
208
- });
206
+ return this.requestJson(
207
+ url,
208
+ {
209
+ method: "GET",
210
+ headers: this.buildHeaders()
211
+ },
212
+ timeout
213
+ );
209
214
  }
210
215
  async post({
211
216
  path,
@@ -328,10 +333,10 @@ var HttpClient = class {
328
333
  ...extra
329
334
  };
330
335
  }
331
- async requestJson(url, init) {
336
+ async requestJson(url, init, timeoutMs) {
332
337
  let response;
333
338
  try {
334
- response = await this.fetchWithRetry(url, init);
339
+ response = await this.fetchWithRetry(url, init, timeoutMs);
335
340
  } catch (error) {
336
341
  throw toTransportError(error);
337
342
  }
@@ -377,12 +382,13 @@ var HttpClient = class {
377
382
  ...retryAfter !== void 0 ? { retryAfter } : {}
378
383
  });
379
384
  }
380
- async fetchWithRetry(url, init) {
385
+ async fetchWithRetry(url, init, timeoutMs) {
381
386
  const { maxRetries, timeout, fetch } = this.options;
387
+ const requestTimeout = timeoutMs ?? timeout;
382
388
  let attempt = 0;
383
389
  let response = await fetch(url, {
384
390
  ...init,
385
- signal: AbortSignal.timeout(timeout)
391
+ signal: AbortSignal.timeout(requestTimeout)
386
392
  });
387
393
  while (attempt < maxRetries && (response.status === 429 || response.status >= 500)) {
388
394
  const retryAfter = parseRetryAfterHeader(response.headers.get("Retry-After"));
@@ -391,7 +397,7 @@ var HttpClient = class {
391
397
  await sleep(delayMs);
392
398
  response = await fetch(url, {
393
399
  ...init,
394
- signal: AbortSignal.timeout(timeout)
400
+ signal: AbortSignal.timeout(requestTimeout)
395
401
  });
396
402
  }
397
403
  return response;
@@ -654,6 +660,20 @@ var CampaignsResource = class {
654
660
  }
655
661
  });
656
662
  }
663
+ /**
664
+ * What listeners who connected through this campaign went on to play.
665
+ *
666
+ * Maps to `GET /v1/campaigns/{campaignId}/listening-insights/{insight}`.
667
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
668
+ * Date window comes from the listening graph — do not send `startDate`/`endDate`.
669
+ * Uses a 120s timeout (insights often take 30–50s).
670
+ */
671
+ listeningInsights(campaignId, insight) {
672
+ return this.http.get({
673
+ path: `/campaigns/${encodeURIComponent(campaignId)}/listening-insights/${encodeURIComponent(insight)}`,
674
+ timeout: LISTENING_INSIGHTS_TIMEOUT_MS
675
+ });
676
+ }
657
677
  /**
658
678
  * Create a wallet-funded campaign.
659
679
  *
@@ -862,6 +882,36 @@ var SoundlinksResource = class {
862
882
  }
863
883
  });
864
884
  }
885
+ /**
886
+ * Cohort retention for a soundlink (`soundlink_cohort_retention_daily`).
887
+ *
888
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/retention`.
889
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
890
+ * One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
891
+ */
892
+ retention(soundlinkId, params = {}) {
893
+ return this.http.get({
894
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/retention`,
895
+ query: {
896
+ startDate: params.startDate,
897
+ endDate: params.endDate
898
+ }
899
+ });
900
+ }
901
+ /**
902
+ * What listeners who connected through this soundlink went on to play.
903
+ *
904
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/listening-insights/{insight}`.
905
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
906
+ * Date window comes from the listening graph — do not send `startDate`/`endDate`.
907
+ * Uses a 120s timeout (insights often take 30–50s).
908
+ */
909
+ listeningInsights(soundlinkId, insight) {
910
+ return this.http.get({
911
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}/listening-insights/${encodeURIComponent(insight)}`,
912
+ timeout: LISTENING_INSIGHTS_TIMEOUT_MS
913
+ });
914
+ }
865
915
  };
866
916
  var SoundlinkBreakdownMetricsResource = class {
867
917
  constructor(http) {
@@ -1015,6 +1065,22 @@ var MetricsResource = class {
1015
1065
  }
1016
1066
  });
1017
1067
  }
1068
+ /**
1069
+ * Cohort retention for the campaign's linked soundlink (`soundlink_cohort_retention_daily`).
1070
+ *
1071
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/retention`.
1072
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1073
+ * One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
1074
+ */
1075
+ retention(campaignId, params = {}) {
1076
+ return this.http.get({
1077
+ path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/retention`,
1078
+ query: {
1079
+ startDate: params.startDate,
1080
+ endDate: params.endDate
1081
+ }
1082
+ });
1083
+ }
1018
1084
  };
1019
1085
  var BreakdownMetricsResource = class {
1020
1086
  constructor(http) {
@@ -1114,6 +1180,6 @@ var Soundlink = class {
1114
1180
  }
1115
1181
  };
1116
1182
 
1117
- 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 };
1183
+ export { API_KEY_PREFIX, CAMPAIGNS_MAX_PAGE_SIZE, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, HttpClient, LISTENING_INSIGHTS_TIMEOUT_MS, METRICS_MAX_PAGE_SIZE, SOUNDLINKS_MAX_PAGE_SIZE, Soundlink, SoundlinkConfigError, SoundlinkParseError, SoundlinkSdkError, getStreamRowCount, resolveClientOptions };
1118
1184
  //# sourceMappingURL=index.js.map
1119
1185
  //# sourceMappingURL=index.js.map