soundlink 2.5.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.
@@ -243,6 +243,28 @@ interface WalletData {
243
243
  /** ISO 8601. `null` when the organization has no credits row. */
244
244
  updatedAt: string | null;
245
245
  }
246
+ /** Ad platform for an organization pixel. Only `meta` is supported today. */
247
+ type PixelPlatform = 'meta';
248
+ /** One pixel from {@link PixelsResource.list} / {@link PixelsResource.update}. */
249
+ interface Pixel {
250
+ id: string;
251
+ platform: PixelPlatform;
252
+ }
253
+ /** Payload from `GET /v1/pixels`. */
254
+ interface PixelListData {
255
+ pixels: Pixel[];
256
+ }
257
+ /** Body for `PUT /v1/pixels/{pixelId}`. */
258
+ interface UpdatePixelRequest {
259
+ platform: PixelPlatform;
260
+ /** Conversions API access token. Stored and never returned. */
261
+ accessToken: string;
262
+ }
263
+ /** Payload from `POST /v1/pixels/{pixelId}/test-events`. */
264
+ interface PixelTestEventData {
265
+ status: 'sent';
266
+ pixelId: string;
267
+ }
246
268
  /** One variant under a creative group (`GET .../metrics/creatives`). */
247
269
  interface CreativeMetricsChild {
248
270
  caption: string | null;
@@ -730,10 +752,104 @@ interface EngagementExportParams extends DateRangeParams {
730
752
  }
731
753
  /** Query params for breakdown JSONL export. Max **90 days** per request. */
732
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;
733
847
 
734
848
  interface HttpGetOptions {
735
849
  path: string;
736
850
  query?: Record<string, string | number | boolean | undefined | null>;
851
+ /** Override the client timeout for this request only (milliseconds). */
852
+ timeout?: number;
737
853
  }
738
854
  interface HttpJsonlOptions extends HttpGetOptions {
739
855
  accept?: string;
@@ -763,7 +879,7 @@ declare class HttpClient {
763
879
  private readonly options;
764
880
  constructor(options: SoundlinkOptions);
765
881
  get resolvedOptions(): ResolvedSoundlinkClientOptions;
766
- get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
882
+ get<T>({ path, query, timeout }: HttpGetOptions): Promise<ApiResponse<T>>;
767
883
  post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
768
884
  patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
769
885
  put<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
@@ -858,6 +974,53 @@ declare class StrategiesResource {
858
974
  */
859
975
  list(): Promise<ApiResponse<StrategiesCatalogData>>;
860
976
  }
977
+ /**
978
+ * Organization Meta pixels (`/v1/pixels`).
979
+ * Read needs `pixels:read`; write and test-events need `pixels:write`.
980
+ */
981
+ declare class PixelsResource {
982
+ private readonly http;
983
+ constructor(http: HttpClient);
984
+ /**
985
+ * List Meta pixels saved for the organization.
986
+ *
987
+ * Maps to `GET /v1/pixels`. Requires `pixels:read`.
988
+ * Returns `403 custom_pixel_not_enabled` when the feature is off.
989
+ *
990
+ * @example
991
+ * ```ts
992
+ * const { data } = await soundlink.pixels.list();
993
+ * ```
994
+ */
995
+ list(): Promise<ApiResponse<PixelListData>>;
996
+ /**
997
+ * Save or rotate a Meta pixel access token.
998
+ *
999
+ * Maps to `PUT /v1/pixels/{pixelId}`. Requires `pixels:write`.
1000
+ * Does not require an `Idempotency-Key`. The access token is never returned.
1001
+ *
1002
+ * @example
1003
+ * ```ts
1004
+ * const { data } = await soundlink.pixels.update('1234567890123456', {
1005
+ * platform: 'meta',
1006
+ * accessToken: process.env.META_CAPI_TOKEN!,
1007
+ * });
1008
+ * ```
1009
+ */
1010
+ update(pixelId: string, body: UpdatePixelRequest): Promise<ApiResponse<Pixel>>;
1011
+ /**
1012
+ * Send a live Meta Conversions API test event to a saved pixel.
1013
+ *
1014
+ * Maps to `POST /v1/pixels/{pixelId}/test-events`. Requires `pixels:write`.
1015
+ * This is not a sandbox event — it appears in Events Manager.
1016
+ *
1017
+ * @example
1018
+ * ```ts
1019
+ * const { data } = await soundlink.pixels.sendTestEvent('1234567890123456');
1020
+ * ```
1021
+ */
1022
+ sendTestEvent(pixelId: string): Promise<ApiResponse<PixelTestEventData>>;
1023
+ }
861
1024
  /** Campaign tiers (`/v1/campaigns/{id}/tiers`). Wallet only (`generation: 3`). */
862
1025
  declare class CampaignTiersResource {
863
1026
  private readonly http;
@@ -912,6 +1075,15 @@ declare class CampaignsResource {
912
1075
  * Omit `startDate` for the full history. Max `pageSize` is **100**.
913
1076
  */
914
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>>;
915
1087
  /**
916
1088
  * Create a wallet-funded campaign.
917
1089
  *
@@ -1057,6 +1229,23 @@ declare class SoundlinksResource {
1057
1229
  * @param params - Inclusive `YYYY-MM-DD` date range.
1058
1230
  */
1059
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>>;
1060
1249
  }
1061
1250
  /**
1062
1251
  * Country-level daily metrics (`soundlink_country_daily` schema).
@@ -1158,6 +1347,14 @@ declare class MetricsResource {
1158
1347
  * Max `pageSize` is **500**.
1159
1348
  */
1160
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>>;
1161
1358
  }
1162
1359
  /**
1163
1360
  * Country-level daily metrics (`campaign_country_daily` schema).
@@ -1229,6 +1426,8 @@ declare class Soundlink {
1229
1426
  readonly wallet: WalletResource;
1230
1427
  /** Growth strategy catalog. Requires `campaigns:read` scope. */
1231
1428
  readonly strategies: StrategiesResource;
1429
+ /** Organization Meta pixels. Read needs `pixels:read`; write needs `pixels:write`. */
1430
+ readonly pixels: PixelsResource;
1232
1431
  /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
1233
1432
  readonly campaigns: CampaignsResource;
1234
1433
  /** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
@@ -1262,10 +1461,12 @@ declare class SoundlinkConfigError extends SoundlinkSdkError {
1262
1461
 
1263
1462
  declare const DEFAULT_BASE_URL = "https://api.getsoundlink.com";
1264
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;
1265
1466
  declare const DEFAULT_MAX_RETRIES = 2;
1266
1467
  declare const API_KEY_PREFIX = "sk_";
1267
1468
  declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
1268
1469
  declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
1269
1470
  declare const METRICS_MAX_PAGE_SIZE = 500;
1270
1471
 
1271
- 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 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 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;
@@ -509,6 +515,62 @@ var StrategiesResource = class {
509
515
  return this.http.get({ path: "/strategies" });
510
516
  }
511
517
  };
518
+ var PixelsResource = class {
519
+ constructor(http) {
520
+ this.http = http;
521
+ }
522
+ http;
523
+ /**
524
+ * List Meta pixels saved for the organization.
525
+ *
526
+ * Maps to `GET /v1/pixels`. Requires `pixels:read`.
527
+ * Returns `403 custom_pixel_not_enabled` when the feature is off.
528
+ *
529
+ * @example
530
+ * ```ts
531
+ * const { data } = await soundlink.pixels.list();
532
+ * ```
533
+ */
534
+ list() {
535
+ return this.http.get({ path: "/pixels" });
536
+ }
537
+ /**
538
+ * Save or rotate a Meta pixel access token.
539
+ *
540
+ * Maps to `PUT /v1/pixels/{pixelId}`. Requires `pixels:write`.
541
+ * Does not require an `Idempotency-Key`. The access token is never returned.
542
+ *
543
+ * @example
544
+ * ```ts
545
+ * const { data } = await soundlink.pixels.update('1234567890123456', {
546
+ * platform: 'meta',
547
+ * accessToken: process.env.META_CAPI_TOKEN!,
548
+ * });
549
+ * ```
550
+ */
551
+ update(pixelId, body) {
552
+ return this.http.put({
553
+ path: `/pixels/${encodeURIComponent(pixelId)}`,
554
+ body
555
+ });
556
+ }
557
+ /**
558
+ * Send a live Meta Conversions API test event to a saved pixel.
559
+ *
560
+ * Maps to `POST /v1/pixels/{pixelId}/test-events`. Requires `pixels:write`.
561
+ * This is not a sandbox event — it appears in Events Manager.
562
+ *
563
+ * @example
564
+ * ```ts
565
+ * const { data } = await soundlink.pixels.sendTestEvent('1234567890123456');
566
+ * ```
567
+ */
568
+ sendTestEvent(pixelId) {
569
+ return this.http.post({
570
+ path: `/pixels/${encodeURIComponent(pixelId)}/test-events`
571
+ });
572
+ }
573
+ };
512
574
  var CampaignTiersResource = class {
513
575
  constructor(http) {
514
576
  this.http = http;
@@ -598,6 +660,20 @@ var CampaignsResource = class {
598
660
  }
599
661
  });
600
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
+ }
601
677
  /**
602
678
  * Create a wallet-funded campaign.
603
679
  *
@@ -806,6 +882,36 @@ var SoundlinksResource = class {
806
882
  }
807
883
  });
808
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
+ }
809
915
  };
810
916
  var SoundlinkBreakdownMetricsResource = class {
811
917
  constructor(http) {
@@ -959,6 +1065,22 @@ var MetricsResource = class {
959
1065
  }
960
1066
  });
961
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
+ }
962
1084
  };
963
1085
  var BreakdownMetricsResource = class {
964
1086
  constructor(http) {
@@ -1032,6 +1154,8 @@ var Soundlink = class {
1032
1154
  wallet;
1033
1155
  /** Growth strategy catalog. Requires `campaigns:read` scope. */
1034
1156
  strategies;
1157
+ /** Organization Meta pixels. Read needs `pixels:read`; write needs `pixels:write`. */
1158
+ pixels;
1035
1159
  /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
1036
1160
  campaigns;
1037
1161
  /** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
@@ -1049,12 +1173,13 @@ var Soundlink = class {
1049
1173
  this.ping = pingResource.ping.bind(pingResource);
1050
1174
  this.wallet = new WalletResource(http);
1051
1175
  this.strategies = new StrategiesResource(http);
1176
+ this.pixels = new PixelsResource(http);
1052
1177
  this.campaigns = new CampaignsResource(http);
1053
1178
  this.soundlinks = new SoundlinksResource(http);
1054
1179
  this.metrics = new MetricsResource(http);
1055
1180
  }
1056
1181
  };
1057
1182
 
1058
- 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 };
1059
1184
  //# sourceMappingURL=index.js.map
1060
1185
  //# sourceMappingURL=index.js.map