soundlink 2.6.0 → 2.7.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.
@@ -752,10 +752,104 @@ interface EngagementExportParams extends DateRangeParams {
752
752
  }
753
753
  /** Query params for breakdown JSONL export. Max **90 days** per request. */
754
754
  type BreakdownExportParams = DateRangeParams;
755
+ /**
756
+ * One row of the `soundlink_cohort_retention_daily` v1.0 schema.
757
+ * Day-N fields are `null` until that day has passed for the cohort date.
758
+ */
759
+ interface CohortRetentionDailyRow {
760
+ provider: 'soundlink';
761
+ account_id: string;
762
+ schema_version: string;
763
+ /** UTC calendar date (`YYYY-MM-DD`). */
764
+ cohort_date: string;
765
+ cohort_date_timezone: 'UTC';
766
+ exported_at: string;
767
+ soundlink_id: string;
768
+ soundlink_name: string;
769
+ soundlink_target_type: 'track' | 'playlist' | null;
770
+ soundlink_target_isrc?: string | null;
771
+ soundlink_target_spotify_track_id?: string | null;
772
+ soundlink_target_playlist_id?: string | null;
773
+ cohort_size: number;
774
+ returned_on_day_1: number | null;
775
+ retention_by_day_1: number | null;
776
+ returned_on_day_2: number | null;
777
+ retention_by_day_2: number | null;
778
+ returned_on_day_3: number | null;
779
+ retention_by_day_3: number | null;
780
+ returned_on_day_4: number | null;
781
+ retention_by_day_4: number | null;
782
+ returned_on_day_5: number | null;
783
+ retention_by_day_5: number | null;
784
+ returned_on_day_6: number | null;
785
+ retention_by_day_6: number | null;
786
+ returned_on_day_7: number | null;
787
+ retention_by_day_7: number | null;
788
+ }
789
+ /** Payload from campaign/soundlink `metrics/retention`. */
790
+ interface CohortRetentionListData {
791
+ schemaVersion: string;
792
+ items: CohortRetentionDailyRow[];
793
+ }
794
+ /** Path param for listening-insights endpoints. */
795
+ type ListeningInsight = 'other-artists' | 'catalog-dig-in' | 'stream-split';
796
+ /** Date window returned with every listening insight (from the listening graph). */
797
+ interface ListeningInsightWindow {
798
+ startDate: string;
799
+ endDate: string;
800
+ }
801
+ interface OtherArtistsInsightArtist {
802
+ /** Lowercased, trimmed artist name. */
803
+ artist: string;
804
+ listeners: number;
805
+ streams: number;
806
+ }
807
+ interface OtherArtistsListeningInsight {
808
+ soundlinkId: string;
809
+ campaignId: string | null;
810
+ insight: 'other-artists';
811
+ window: ListeningInsightWindow;
812
+ artists: OtherArtistsInsightArtist[];
813
+ }
814
+ interface CatalogDigInInsightArtist {
815
+ artist: string;
816
+ playlistListeners: number;
817
+ playlistStreams: number;
818
+ catalogListeners: number;
819
+ catalogStreams: number;
820
+ catalogTracks: number;
821
+ /** catalogListeners / playlistListeners. Null when playlistListeners is 0. */
822
+ catalogListenerRate: number | null;
823
+ }
824
+ interface CatalogDigInListeningInsight {
825
+ soundlinkId: string;
826
+ campaignId: string | null;
827
+ insight: 'catalog-dig-in';
828
+ window: ListeningInsightWindow;
829
+ artists: CatalogDigInInsightArtist[];
830
+ }
831
+ type StreamSplitEngagementContext = 'promoted' | 'playlist' | 'artist_catalog';
832
+ interface StreamSplitContext {
833
+ engagementContext: StreamSplitEngagementContext;
834
+ listeners: number;
835
+ streams: number;
836
+ tracks: number;
837
+ }
838
+ interface StreamSplitListeningInsight {
839
+ soundlinkId: string;
840
+ campaignId: string | null;
841
+ insight: 'stream-split';
842
+ window: ListeningInsightWindow;
843
+ contexts: StreamSplitContext[];
844
+ }
845
+ /** Discriminated on `insight`. */
846
+ type ListeningInsightsData = OtherArtistsListeningInsight | CatalogDigInListeningInsight | StreamSplitListeningInsight;
755
847
 
756
848
  interface HttpGetOptions {
757
849
  path: string;
758
850
  query?: Record<string, string | number | boolean | undefined | null>;
851
+ /** Override the client timeout for this request only (milliseconds). */
852
+ timeout?: number;
759
853
  }
760
854
  interface HttpJsonlOptions extends HttpGetOptions {
761
855
  accept?: string;
@@ -785,7 +879,7 @@ declare class HttpClient {
785
879
  private readonly options;
786
880
  constructor(options: SoundlinkOptions);
787
881
  get resolvedOptions(): ResolvedSoundlinkClientOptions;
788
- get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
882
+ get<T>({ path, query, timeout }: HttpGetOptions): Promise<ApiResponse<T>>;
789
883
  post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
790
884
  patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
791
885
  put<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
@@ -981,6 +1075,15 @@ declare class CampaignsResource {
981
1075
  * Omit `startDate` for the full history. Max `pageSize` is **100**.
982
1076
  */
983
1077
  activity(campaignId: string, params?: CampaignActivityParams): Promise<ApiResponse<CampaignActivityData>>;
1078
+ /**
1079
+ * What listeners who connected through this campaign went on to play.
1080
+ *
1081
+ * Maps to `GET /v1/campaigns/{campaignId}/listening-insights/{insight}`.
1082
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1083
+ * Date window comes from the listening graph — do not send `startDate`/`endDate`.
1084
+ * Uses a 120s timeout (insights often take 30–50s).
1085
+ */
1086
+ listeningInsights(campaignId: string, insight: ListeningInsight): Promise<ApiResponse<ListeningInsightsData>>;
984
1087
  /**
985
1088
  * Create a wallet-funded campaign.
986
1089
  *
@@ -1126,6 +1229,23 @@ declare class SoundlinksResource {
1126
1229
  * @param params - Inclusive `YYYY-MM-DD` date range.
1127
1230
  */
1128
1231
  metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
1232
+ /**
1233
+ * Cohort retention for a soundlink (`soundlink_cohort_retention_daily`).
1234
+ *
1235
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/retention`.
1236
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1237
+ * One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
1238
+ */
1239
+ retention(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<CohortRetentionListData>>;
1240
+ /**
1241
+ * What listeners who connected through this soundlink went on to play.
1242
+ *
1243
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/listening-insights/{insight}`.
1244
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1245
+ * Date window comes from the listening graph — do not send `startDate`/`endDate`.
1246
+ * Uses a 120s timeout (insights often take 30–50s).
1247
+ */
1248
+ listeningInsights(soundlinkId: string, insight: ListeningInsight): Promise<ApiResponse<ListeningInsightsData>>;
1129
1249
  }
1130
1250
  /**
1131
1251
  * Country-level daily metrics (`soundlink_country_daily` schema).
@@ -1227,6 +1347,14 @@ declare class MetricsResource {
1227
1347
  * Max `pageSize` is **500**.
1228
1348
  */
1229
1349
  creativeDaily(campaignId: string, params?: CreativeDailyParams): Promise<ApiResponse<CreativeDailyData>>;
1350
+ /**
1351
+ * Cohort retention for the campaign's linked soundlink (`soundlink_cohort_retention_daily`).
1352
+ *
1353
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/retention`.
1354
+ * Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
1355
+ * One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
1356
+ */
1357
+ retention(campaignId: string, params?: DateRangeParams): Promise<ApiResponse<CohortRetentionListData>>;
1230
1358
  }
1231
1359
  /**
1232
1360
  * Country-level daily metrics (`campaign_country_daily` schema).
@@ -1333,10 +1461,12 @@ declare class SoundlinkConfigError extends SoundlinkSdkError {
1333
1461
 
1334
1462
  declare const DEFAULT_BASE_URL = "https://api.getsoundlink.com";
1335
1463
  declare const DEFAULT_TIMEOUT_MS = 30000;
1464
+ /** Listening insights often take 30–50s; the Public API recommends ≥120s. */
1465
+ declare const LISTENING_INSIGHTS_TIMEOUT_MS = 120000;
1336
1466
  declare const DEFAULT_MAX_RETRIES = 2;
1337
1467
  declare const API_KEY_PREFIX = "sk_";
1338
1468
  declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
1339
1469
  declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
1340
1470
  declare const METRICS_MAX_PAGE_SIZE = 500;
1341
1471
 
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 };
1472
+ 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