@dracoonghost/trndup-sdk 1.3.17 → 1.3.18

package/dist/index.d.mts

@@ -594,6 +594,467 @@ declare namespace Insights {
         /** Max number of data points (default: 30, max: 90) */
         limit?: number;
     }
+    /**
+     * How we calculated this insight - shown to user for transparency
+     */
+    interface CalculationExplanation {
+        /** Short description of the methodology */
+        method: string;
+        /** Time range analyzed */
+        timeRange: string;
+        /** Key factors that influenced the result */
+        factors: string[];
+        /** Data quality/reliability indicator */
+        dataQuality: 'high' | 'medium' | 'low';
+        /** Why data quality might be limited */
+        dataQualityNote?: string;
+    }
+    /**
+     * Common metadata for all insights
+     */
+    interface InsightMeta {
+        /** When this insight was calculated */
+        calculatedAt: string;
+        /** When this insight expires (should be recalculated) */
+        validUntil: string;
+        /** Algorithm version for tracking changes */
+        algorithmVersion: string;
+        /** Whether result came from cache */
+        fromCache: boolean;
+        /** How this was calculated (for transparency) */
+        howWeCalculatedThis: CalculationExplanation;
+    }
+    /**
+     * Response when there's not enough data for an insight
+     */
+    interface InsufficientDataResponse {
+        hasData: false;
+        reason: string;
+        minimumRequired: string;
+        currentAmount: string;
+        suggestion: string;
+    }
+    interface TopVideoData {
+        videoId: string;
+        title: string;
+        thumbnailUrl: string | null;
+        publishedAt: string;
+        /** Link to watch on YouTube */
+        watchUrl: string;
+    }
+    interface TopVideoMetrics {
+        views: number;
+        likes: number;
+        comments: number;
+        estimatedMinutesWatched: number;
+        engagementRate: number;
+    }
+    interface TopVideoComparison {
+        /** Performance vs user's average video */
+        vsChannelAverage: {
+            views: number;
+            engagement: number;
+            description: string;
+        };
+        /** Why this video performed well */
+        standoutReasons: string[];
+    }
+    interface BestPerformingVideoData {
+        /** Time range analyzed */
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        /** The top performing video */
+        topVideo: TopVideoData;
+        /** Video's metrics for this period */
+        metrics: TopVideoMetrics;
+        /** How it compares to your other content */
+        comparison: TopVideoComparison;
+        /** Human-readable summary */
+        insight: string;
+        /** Runner-up videos (for context) */
+        runnersUp: Array<{
+            videoId: string;
+            title: string;
+            views: number;
+            thumbnailUrl: string | null;
+        }>;
+    }
+    type BestPerformingVideoResponse = (InsufficientDataResponse) | {
+        hasData: true;
+        data: BestPerformingVideoData;
+        _meta: InsightMeta;
+    };
+    interface DecayingVideo {
+        videoId: string;
+        title: string;
+        thumbnailUrl: string | null;
+        publishedAt: string;
+        watchUrl: string;
+        /** Age of video in days */
+        ageInDays: number;
+        /** Views in current period */
+        currentViews: number;
+        /** Views in previous period */
+        previousViews: number;
+        /** Decay rate as percentage (negative = declining) */
+        decayRate: number;
+        /** Severity of decay */
+        severity: 'severe' | 'moderate' | 'mild';
+        /** Actionable suggestion */
+        suggestion: string;
+    }
+    interface ContentDecayData {
+        /** Time range analyzed */
+        period: {
+            current: {
+                start: string;
+                end: string;
+            };
+            previous: {
+                start: string;
+                end: string;
+            };
+            days: number;
+        };
+        /** Number of videos analyzed */
+        videosAnalyzed: number;
+        /** Videos experiencing significant decay */
+        decayingVideos: DecayingVideo[];
+        /** Summary stats */
+        summary: {
+            totalDecaying: number;
+            severeCount: number;
+            moderateCount: number;
+            mildCount: number;
+            /** Combined view loss from all decaying videos */
+            totalViewsLost: number;
+        };
+        /** Human-readable summary */
+        insight: string;
+        /** What content decay means */
+        whatThisMeans: string;
+    }
+    type ContentDecayResponse = (InsufficientDataResponse) | {
+        hasData: true;
+        data: ContentDecayData;
+        _meta: InsightMeta;
+    };
+    interface DayPerformance {
+        day: string;
+        avgFirstDayViews: number;
+        avgEngagement: number;
+        videoCount: number;
+        /** Confidence in this data */
+        confidence: 'high' | 'medium' | 'low';
+    }
+    interface TimeSlotPerformance {
+        slot: string;
+        label: string;
+        avgFirstDayViews: number;
+        videoCount: number;
+        confidence: 'high' | 'medium' | 'low';
+    }
+    interface AudienceActivityData {
+        /** How many videos were analyzed */
+        videosAnalyzed: number;
+        /** Day when your audience is most active */
+        mostActiveDay: {
+            day: string;
+            confidence: 'high' | 'medium' | 'low';
+            /** Why this day shows highest activity */
+            reason: string;
+        };
+        /** Time slot when your audience is most active */
+        mostActiveTimeSlot: {
+            slot: string;
+            label: string;
+            confidence: 'high' | 'medium' | 'low';
+            reason: string;
+        };
+        /** Full breakdown by day */
+        dayBreakdown: DayPerformance[];
+        /** Full breakdown by time slot (if enough data) */
+        timeBreakdown: TimeSlotPerformance[] | null;
+        /** Human-readable summary */
+        insight: string;
+        /** Disclaimer about the data */
+        disclaimer: string;
+    }
+    type AudienceActivityResponse = (InsufficientDataResponse) | {
+        hasData: true;
+        data: AudienceActivityData;
+        _meta: InsightMeta;
+    };
+    /** @deprecated Use AudienceActivityData instead */
+    type BestUploadTimeData = AudienceActivityData;
+    /** @deprecated Use AudienceActivityResponse instead */
+    type BestUploadTimeResponse = AudienceActivityResponse;
+    interface FadingHitVideo {
+        videoId: string;
+        title: string;
+        thumbnailUrl: string | null;
+        publishedAt: string;
+        watchUrl: string;
+        /** How old the video is in days */
+        ageInDays: number;
+        /** Performance during peak period (actual peak, not just first 14 days) */
+        peakPerformance: {
+            /** Average daily views during peak window */
+            dailyViews: number;
+            /** Comparison to channel average (e.g., "45% above average") */
+            vsChannelAverage: string;
+            /** Was this a top performer (2x+ channel average)? */
+            wasTopPerformer: boolean;
+            /** When the actual peak occurred */
+            peakPeriod: {
+                start: string;
+                end: string;
+                /** How many days after upload the peak occurred */
+                daysAfterUpload: number;
+                /** True if video went viral later (not at launch) - delayed virality */
+                wasDelayedViral: boolean;
+            };
+        };
+        /** Performance in recent period (last 14 days) */
+        currentPerformance: {
+            /** Current average daily views */
+            dailyViews: number;
+            /** Percentage decline from peak (negative number) */
+            declineFromPeak: number;
+        };
+        /** How likely revival efforts would work */
+        revivalPotential: 'high' | 'medium' | 'low';
+        /** Why this video might be worth reviving */
+        whyRevive: string;
+        /** Specific suggestions to revive this video */
+        suggestions: string[];
+    }
+    interface FadingHitsData {
+        /** Time period for "current" performance check */
+        period: {
+            current: {
+                start: string;
+                end: string;
+            };
+            label: string;
+        };
+        /** Number of videos analyzed */
+        videosAnalyzed: number;
+        /** Videos that were performing above average but are now declining */
+        fadingHits: FadingHitVideo[];
+        /** Summary stats */
+        summary: {
+            totalFading: number;
+            highPotentialCount: number;
+            mediumPotentialCount: number;
+            lowPotentialCount: number;
+            /** Combined daily views being lost */
+            totalDailyViewsLost: number;
+        };
+        /** Human-readable summary */
+        insight: string;
+        /** What fading hits means */
+        whatThisMeans: string;
+    }
+    type FadingHitsResponse = (InsufficientDataResponse) | {
+        hasData: true;
+        data: FadingHitsData;
+        _meta: InsightMeta;
+    };
+    type SubscriberQualityLabel = 'excellent' | 'good' | 'fair' | 'needs_attention' | 'concerning';
+    interface SubscriberQualityData {
+        /** Time range analyzed */
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        /** Overall quality score (0-100) */
+        qualityScore: number;
+        /** Score interpretation */
+        scoreLabel: SubscriberQualityLabel;
+        /** Core metrics */
+        metrics: {
+            /** Total subscribers gained */
+            subscribersGained: number;
+            /** Total subscribers lost */
+            subscribersLost: number;
+            /** Net subscriber change */
+            netSubscribers: number;
+            /** Retention rate (how many stay) */
+            retentionRate: number;
+            /** Average watch time per view */
+            avgWatchTimeMinutes: number;
+            /** Views per subscriber (engagement proxy) */
+            viewsPerSubscriber: number;
+        };
+        /** Comparison to previous period */
+        trend: {
+            scoreChange: number;
+            direction: 'improving' | 'stable' | 'declining';
+            description: string;
+        };
+        /** Human-readable summary */
+        insight: string;
+        /** Specific recommendations */
+        recommendations: string[];
+    }
+    type SubscriberQualityResponse = (InsufficientDataResponse) | {
+        hasData: true;
+        data: SubscriberQualityData;
+        _meta: InsightMeta;
+    };
+    type FatigueLevel = 'none' | 'low' | 'moderate' | 'high' | 'critical';
+    interface FatigueSignal {
+        /** Name of the signal */
+        name: string;
+        /** Current period value */
+        current: number;
+        /** Previous period value */
+        previous: number;
+        /** Change percentage (negative = declining) */
+        changePercent: number;
+        /** Whether this signal indicates fatigue */
+        indicatesFatigue: boolean;
+        /** Description of what this means */
+        interpretation: string;
+    }
+    interface AudienceFatigueData {
+        /** Time periods compared */
+        period: {
+            current: {
+                start: string;
+                end: string;
+            };
+            previous: {
+                start: string;
+                end: string;
+            };
+            daysPerPeriod: number;
+        };
+        /** Overall fatigue index (0-100, higher = more fatigue) */
+        fatigueIndex: number;
+        /** Human-readable fatigue level */
+        fatigueLevel: FatigueLevel;
+        /** Individual signals that contribute to the score */
+        signals: {
+            watchTimePerView: FatigueSignal;
+            engagementRate: FatigueSignal;
+            subscriberChurn: FatigueSignal;
+            viewsPerVideo: FatigueSignal;
+        };
+        /** Summary of signals */
+        summary: {
+            signalsIndicatingFatigue: number;
+            totalSignals: number;
+            primaryConcern: string | null;
+        };
+        /** Human-readable insight */
+        insight: string;
+        /** What to do about it */
+        recommendations: string[];
+    }
+    type AudienceFatigueResponse = (InsufficientDataResponse) | {
+        hasData: true;
+        data: AudienceFatigueData;
+        _meta: InsightMeta;
+    };
+    interface LengthBucketPerformance {
+        /** Bucket name (e.g., "5-10 minutes") */
+        bucket: string;
+        /** Bucket range in seconds */
+        range: {
+            min: number;
+            max: number | null;
+        };
+        /** Number of videos in this bucket */
+        videoCount: number;
+        /** Average retention as percentage */
+        avgRetention: number;
+        /** Average engagement rate */
+        avgEngagement: number;
+        /** Average views per video */
+        avgViews: number;
+        /** Combined performance score (0-100) */
+        performanceScore: number;
+        /** Is this the optimal bucket? */
+        isOptimal: boolean;
+    }
+    interface OptimalVideoLengthData {
+        /** How many videos were analyzed */
+        videosAnalyzed: number;
+        /** The recommended optimal length range */
+        optimalLength: {
+            bucket: string;
+            range: {
+                min: number;
+                max: number | null;
+            };
+            confidence: 'high' | 'medium' | 'low';
+            reason: string;
+        };
+        /** Performance breakdown by length bucket */
+        breakdown: LengthBucketPerformance[];
+        /** Key findings */
+        findings: {
+            bestRetention: {
+                bucket: string;
+                value: number;
+            };
+            bestEngagement: {
+                bucket: string;
+                value: number;
+            };
+            mostCommon: {
+                bucket: string;
+                count: number;
+            };
+        };
+        /** Human-readable insight */
+        insight: string;
+        /** Specific recommendations */
+        recommendations: string[];
+    }
+    type OptimalVideoLengthResponse = (InsufficientDataResponse) | {
+        hasData: true;
+        data: OptimalVideoLengthData;
+        _meta: InsightMeta;
+    };
+    interface AllInsightsData {
+        bestPerformingVideo: BestPerformingVideoResponse;
+        contentDecay: ContentDecayResponse;
+        audienceActivity: AudienceActivityResponse;
+        subscriberQuality: SubscriberQualityResponse;
+        fadingHits: FadingHitsResponse;
+        audienceFatigue: AudienceFatigueResponse;
+        optimalLength: OptimalVideoLengthResponse;
+    }
+    interface AllInsightsResponse {
+        data: AllInsightsData;
+        _meta: {
+            calculatedAt: string;
+            insightsAvailable: string[];
+        };
+    }
+    interface GetBestVideoParams {
+        /** Number of days to analyze (1-90, default: 30) */
+        period?: number;
+    }
+    interface GetContentDecayParams {
+        /** Days per comparison period (3-14, default: 7) */
+        period?: number;
+    }
+    interface GetSubscriberQualityParams {
+        /** Number of days to analyze (14-180, default: 90) */
+        period?: number;
+    }
+    interface GetAudienceFatigueParams {
+        /** Days per comparison period (14-90, default: 30) */
+        period?: number;
+    }
 }
 declare namespace Activity {
     /**
@@ -1092,6 +1553,244 @@ declare class InsightsModule {
      * GET /v1/insights/youtube/momentum/history
      */
     getYouTubeMomentumHistory(params?: Insights.GetMomentumHistoryParams): Promise<Insights.MomentumHistoryResponse>;
+    /**
+     * 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
+     */
+    getYouTubeBestVideo(params?: Insights.GetBestVideoParams): Promise<Insights.BestPerformingVideoResponse>;
+    /**
+     * 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
+     */
+    getYouTubeContentDecay(params?: Insights.GetContentDecayParams): Promise<Insights.ContentDecayResponse>;
+    /**
+     * 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
+     */
+    getYouTubeAudienceActivity(): Promise<Insights.AudienceActivityResponse>;
+    /**
+     * @deprecated Use `getYouTubeAudienceActivity()` instead
+     */
+    getYouTubeBestUploadTime(): Promise<Insights.BestUploadTimeResponse>;
+    /**
+     * 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
+     */
+    getYouTubeFadingHits(): Promise<Insights.FadingHitsResponse>;
+    /**
+     * 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
+     */
+    getYouTubeSubscriberQuality(params?: Insights.GetSubscriberQualityParams): Promise<Insights.SubscriberQualityResponse>;
+    /**
+     * 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
+     */
+    getYouTubeAudienceFatigue(params?: Insights.GetAudienceFatigueParams): Promise<Insights.AudienceFatigueResponse>;
+    /**
+     * 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
+     */
+    getYouTubeOptimalLength(): Promise<Insights.OptimalVideoLengthResponse>;
+    /**
+     * 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
+     */
+    getYouTubeAllInsights(): Promise<Insights.AllInsightsResponse>;
 }
 
 /**