@dracoonghost/trndup-sdk 1.3.17 → 1.3.18

package/dist/index.mjs

@@ -593,6 +593,304 @@ var InsightsModule = class {
       `/v1/insights/youtube/momentum/history${query}`
     );
   }
+  // =========================================================================
+  // YOUTUBE BEST PERFORMING VIDEO
+  // =========================================================================
+  /**
+   * Get the best performing video in a time period
+   * 
+   * Identifies your top video by views and explains WHY it performed well.
+   * 
+   * @param params - Query parameters
+   * @param params.period - Days to analyze (1-90, default: 30)
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.insights.getYouTubeBestVideo({ period: 30 });
+   * 
+   * if (result.hasData) {
+   *   console.log(`🏆 ${result.data.topVideo.title}`);
+   *   console.log(`Views: ${result.data.metrics.views}`);
+   *   console.log(`${result.data.comparison.vsChannelAverage.description}`);
+   *   console.log(result.data.insight);
+   *   
+   *   // Show how it was calculated
+   *   console.log(result._meta.howWeCalculatedThis.method);
+   * } else {
+   *   console.log(result.suggestion);
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/best-video
+   */
+  async getYouTubeBestVideo(params) {
+    const query = params?.period ? `?period=${params.period}` : "";
+    return this.client.get(
+      `/v1/insights/youtube/best-video${query}`
+    );
+  }
+  // =========================================================================
+  // YOUTUBE CONTENT DECAY
+  // =========================================================================
+  /**
+   * Find videos that are losing momentum
+   * 
+   * Compares current period vs previous period to identify declining videos.
+   * Provides actionable suggestions for each decaying video.
+   * 
+   * @param params - Query parameters
+   * @param params.period - Days per comparison period (3-14, default: 7)
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.insights.getYouTubeContentDecay({ period: 7 });
+   * 
+   * if (result.hasData) {
+   *   console.log(result.data.insight);
+   *   console.log(`${result.data.summary.totalDecaying} videos declining`);
+   *   
+   *   for (const video of result.data.decayingVideos) {
+   *     console.log(`📉 ${video.title}: ${video.decayRate}%`);
+   *     console.log(`   ${video.suggestion}`);
+   *   }
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/content-decay
+   */
+  async getYouTubeContentDecay(params) {
+    const query = params?.period ? `?period=${params.period}` : "";
+    return this.client.get(
+      `/v1/insights/youtube/content-decay${query}`
+    );
+  }
+  // =========================================================================
+  // YOUTUBE AUDIENCE ACTIVITY
+  // =========================================================================
+  /**
+   * Get when your audience is most active
+   * 
+   * Unlike generic advice, this is based on YOUR audience's behavior.
+   * Analyzes first-day performance by publish day and time to identify
+   * when your audience is most engaged.
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.insights.getYouTubeAudienceActivity();
+   * 
+   * if (result.hasData) {
+   *   console.log(`📅 Most active day: ${result.data.mostActiveDay.day}`);
+   *   console.log(`⏰ Peak time: ${result.data.mostActiveTimeSlot.label}`);
+   *   console.log(result.data.insight);
+   *   
+   *   // Show day breakdown
+   *   for (const day of result.data.dayBreakdown) {
+   *     console.log(`${day.day}: ${day.avgFirstDayViews} avg views`);
+   *   }
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/audience-activity
+   */
+  async getYouTubeAudienceActivity() {
+    return this.client.get(
+      "/v1/insights/youtube/audience-activity"
+    );
+  }
+  /**
+   * @deprecated Use `getYouTubeAudienceActivity()` instead
+   */
+  async getYouTubeBestUploadTime() {
+    return this.getYouTubeAudienceActivity();
+  }
+  // =========================================================================
+  // YOUTUBE FADING HITS
+  // =========================================================================
+  /**
+   * Find videos that were hits but are now declining
+   * 
+   * Identifies videos that performed above your channel average initially
+   * but have since lost momentum. These are revival opportunities.
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.insights.getYouTubeFadingHits();
+   * 
+   * if (result.hasData) {
+   *   console.log(result.data.insight);
+   *   console.log(`${result.data.summary.totalFading} videos could use a boost`);
+   *   
+   *   for (const video of result.data.fadingHits) {
+   *     console.log(`📉 ${video.title}`);
+   *     console.log(`   Peak: ${video.peakPeriod.avgDailyViews} views/day`);
+   *     console.log(`   Now: ${video.currentPeriod.avgDailyViews} views/day`);
+   *     console.log(`   Decline: ${video.decline.percentage}%`);
+   *     console.log(`   Revival potential: ${video.revivalPotential}`);
+   *     console.log(`   ${video.whyRevive}`);
+   *     for (const suggestion of video.suggestions) {
+   *       console.log(`   💡 ${suggestion}`);
+   *     }
+   *   }
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/fading-hits
+   */
+  async getYouTubeFadingHits() {
+    return this.client.get(
+      "/v1/insights/youtube/fading-hits"
+    );
+  }
+  // =========================================================================
+  // YOUTUBE SUBSCRIBER QUALITY
+  // =========================================================================
+  /**
+   * Measure subscriber quality score (0-100)
+   * 
+   * Analyzes whether new subscribers are engaged or just numbers.
+   * Helps identify fake growth or low-quality audiences.
+   * 
+   * @param params - Query parameters
+   * @param params.period - Days to analyze (7-90, default: 30)
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.insights.getYouTubeSubscriberQuality({ period: 90 });
+   * 
+   * if (result.hasData) {
+   *   console.log(`Quality Score: ${result.data.qualityScore}/100 (${result.data.scoreLabel})`);
+   *   console.log(`Retention: ${result.data.metrics.retentionRate}%`);
+   *   console.log(result.data.insight);
+   *   
+   *   // Show recommendations
+   *   for (const rec of result.data.recommendations) {
+   *     console.log(`💡 ${rec}`);
+   *   }
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/subscriber-quality
+   */
+  async getYouTubeSubscriberQuality(params) {
+    const query = params?.period ? `?period=${params.period}` : "";
+    return this.client.get(
+      `/v1/insights/youtube/subscriber-quality${query}`
+    );
+  }
+  // =========================================================================
+  // YOUTUBE AUDIENCE FATIGUE
+  // =========================================================================
+  /**
+   * Detect if your audience is getting tired of your content
+   * 
+   * Compares key engagement metrics between recent and previous periods
+   * to identify declining audience interest before it becomes critical.
+   * 
+   * @param params - Query parameters
+   * @param params.period - Days per comparison period (14-90, default: 30)
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.insights.getYouTubeAudienceFatigue({ period: 30 });
+   * 
+   * if (result.hasData) {
+   *   console.log(`Fatigue Index: ${result.data.fatigueIndex}/100`);
+   *   console.log(`Level: ${result.data.fatigueLevel}`);
+   *   console.log(result.data.insight);
+   *   
+   *   // Check individual signals
+   *   if (result.data.signals.watchTimePerView.indicatesFatigue) {
+   *     console.log('⚠️ Watch time is declining');
+   *   }
+   *   
+   *   // Get recommendations
+   *   for (const rec of result.data.recommendations) {
+   *     console.log(`💡 ${rec}`);
+   *   }
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/audience-fatigue
+   */
+  async getYouTubeAudienceFatigue(params) {
+    const query = params?.period ? `?period=${params.period}` : "";
+    return this.client.get(
+      `/v1/insights/youtube/audience-fatigue${query}`
+    );
+  }
+  // =========================================================================
+  // YOUTUBE OPTIMAL VIDEO LENGTH
+  // =========================================================================
+  /**
+   * Find the ideal video length for YOUR audience
+   * 
+   * Unlike generic "8-12 minutes is best" advice, this is personalized
+   * based on how YOUR videos perform at different lengths.
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.insights.getYouTubeOptimalLength();
+   * 
+   * if (result.hasData) {
+   *   console.log(`Optimal: ${result.data.optimalLength.bucket}`);
+   *   console.log(`Confidence: ${result.data.optimalLength.confidence}`);
+   *   console.log(result.data.insight);
+   *   
+   *   // Show breakdown by length
+   *   for (const bucket of result.data.breakdown) {
+   *     const marker = bucket.isOptimal ? '🏆' : '  ';
+   *     console.log(`${marker} ${bucket.bucket}: ${bucket.avgRetention}% retention, ${bucket.avgEngagement}% engagement`);
+   *   }
+   *   
+   *   // Recommendations
+   *   for (const rec of result.data.recommendations) {
+   *     console.log(`💡 ${rec}`);
+   *   }
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/optimal-length
+   */
+  async getYouTubeOptimalLength() {
+    return this.client.get(
+      "/v1/insights/youtube/optimal-length"
+    );
+  }
+  // =========================================================================
+  // YOUTUBE ALL INSIGHTS
+  // =========================================================================
+  /**
+   * Get all YouTube insights in one call
+   * 
+   * Efficient for dashboard display - fetches all insights in parallel.
+   * Each insight has `hasData: boolean` to check availability.
+   * 
+   * @example
+   * ```typescript
+   * const all = await client.insights.getYouTubeAllInsights();
+   * 
+   * // Check which insights are available
+   * console.log('Available:', all._meta.insightsAvailable);
+   * 
+   * // Use each insight
+   * if (all.data.bestPerformingVideo.hasData) {
+   *   console.log(`Best: ${all.data.bestPerformingVideo.data.topVideo.title}`);
+   * }
+   * 
+   * if (all.data.audienceFatigue.hasData) {
+   *   console.log(`Fatigue: ${all.data.audienceFatigue.data.fatigueLevel}`);
+   * }
+   * 
+   * if (all.data.optimalLength.hasData) {
+   *   console.log(`Optimal Length: ${all.data.optimalLength.data.optimalLength.bucket}`);
+   * }
+   * ```
+   * 
+   * GET /v1/insights/youtube/all
+   */
+  async getYouTubeAllInsights() {
+    return this.client.get("/v1/insights/youtube/all");
+  }
 };
 
 // modules/activity.ts