@dracoonghost/trndup-sdk 1.3.26 → 1.5.0

package/dist/index.d.mts

@@ -1754,6 +1754,172 @@ declare namespace Activity {
         limit?: number;
     }
 }
+declare namespace Trends {
+    /** Trend categories */
+    type Category = 'SPORTS' | 'NEWS' | 'TECH' | 'ENTERTAINMENT' | 'GAMING' | 'LIFESTYLE' | 'FINANCE' | 'EDUCATION' | 'OTHER';
+    /** How fast the trend is growing */
+    type Velocity = 'SLOW' | 'MEDIUM' | 'FAST' | 'VIRAL';
+    /** Predicted viral potential */
+    type ViralPrediction = 'LOW' | 'MEDIUM' | 'HIGH_VIRAL';
+    /** Current trend status */
+    type Status = 'NEW' | 'TRENDING' | 'PEAKING' | 'COOLING';
+    /** Content idea difficulty level */
+    type Difficulty = 'EASY' | 'MEDIUM' | 'HARD';
+    /**
+     * Content idea for a trend
+     */
+    interface ContentIdea {
+        /** How hard it is to create */
+        difficulty: Difficulty;
+        /** Idea title */
+        title: string;
+        /** Detailed description */
+        description: string;
+    }
+    /**
+     * Example content from other creators
+     */
+    interface TopExample {
+        /** Link to the video */
+        videoUrl: string;
+        /** Creator's name */
+        creatorName?: string;
+        /** View count display (e.g., "1.2M views") */
+        views?: string;
+        /** Thumbnail image URL */
+        thumbnail?: string;
+    }
+    /**
+     * Trend list item (compact)
+     */
+    interface TrendListItem {
+        /** Unique trend ID */
+        id: string;
+        /** Trend topic title */
+        topic: string;
+        /** Brief summary */
+        summary: string;
+        /** Content category */
+        category: Category;
+        /** Growth velocity */
+        velocity: Velocity;
+        /** Viral potential prediction */
+        viralPrediction: ViralPrediction;
+        /** Relevance score (0-100) */
+        relevanceScore: number;
+        /** Current status */
+        status: Status;
+        /** Growth label (e.g., "🔥 Viral") */
+        growthLabel: string;
+        /** Peak timing hint (e.g., "🎯 Peak NOW") */
+        peakWindow: string | null;
+        /** Relevant platforms */
+        platforms: string[];
+        /** Related hashtags */
+        hashtags: string[];
+        /** When first detected */
+        firstSeen: string;
+        /** Number of content ideas */
+        contentIdeasCount: number;
+    }
+    /**
+     * Full trend details
+     */
+    interface TrendDetail {
+        /** Unique trend ID */
+        id: string;
+        /** Trend topic title */
+        topic: string;
+        /** Detailed summary */
+        summary: string;
+        /** Content category */
+        category: Category;
+        /** Growth velocity */
+        velocity: Velocity;
+        /** Viral potential prediction */
+        viralPrediction: ViralPrediction;
+        /** Relevance score (0-100) */
+        relevanceScore: number;
+        /** Number of times spotted */
+        sightingCount: number;
+        /** Peak strength (1-5) */
+        peakStrength: number;
+        /** Current status */
+        status: Status;
+        /** Growth label */
+        growthLabel: string;
+        /** Peak timing hint */
+        peakWindow: string | null;
+        /** When first detected */
+        firstSeen: string;
+        /** Last activity timestamp */
+        lastActivity: string;
+        /** Relevant platforms */
+        platforms: string[];
+        /** Related hashtags */
+        hashtags: string[];
+        /** Target creator types */
+        targetCreators: string[];
+        /** Content ideas */
+        contentIdeas: ContentIdea[];
+        /** Example content */
+        topExamples: TopExample[];
+        /** Recommended video duration */
+        recommendedDuration: string | null;
+        /** Last updated */
+        updatedAt: string;
+    }
+    /**
+     * Response for list trends endpoint
+     */
+    interface ListResponse {
+        trends: TrendListItem[];
+        total: number;
+        limit: number;
+        offset: number;
+    }
+    /**
+     * Category with trend count
+     */
+    interface CategoryCount {
+        category: string;
+        count: number;
+    }
+    /**
+     * Platform with trend count
+     */
+    interface PlatformCount {
+        platform: string;
+        count: number;
+    }
+    /**
+     * Sync status info
+     */
+    interface SyncStatus {
+        lastSyncedAt: string | null;
+        lastSyncStatus: 'SUCCESS' | 'FAILED' | null;
+        trendsProcessed: number;
+        trendsDeleted: number;
+        totalTrends: number;
+    }
+    /**
+     * Parameters for listing trends
+     */
+    interface ListParams {
+        /** Filter by category */
+        category?: Category;
+        /** Filter by velocity */
+        velocity?: Velocity;
+        /** Filter by status */
+        status?: Status;
+        /** Filter by platform */
+        platform?: string;
+        /** Max results (default: 20, max: 100) */
+        limit?: number;
+        /** Pagination offset */
+        offset?: number;
+    }
+}
 
 /**
  * TrndUp SDK - Base Client
@@ -2528,6 +2694,156 @@ declare class InsightsModule {
      * GET /v1/insights/youtube/all
      */
     getYouTubeAllInsights(): Promise<Insights.AllInsightsResponse>;
+    /**
+     * Instagram insights sub-module
+     */
+    instagram: {
+        /**
+         * Get all Instagram insights in one call
+         *
+         * Efficient for dashboard display - fetches all insights in parallel.
+         *
+         * @example
+         * ```typescript
+         * const all = await client.insights.instagram.getAll({ range: '30d' });
+         *
+         * // Check which insights are available
+         * if (all.data.health.hasData) {
+         *   console.log(`Health Score: ${all.data.health.data.overall}/100`);
+         * }
+         *
+         * if (all.data.bestPost.hasData) {
+         *   console.log(`Best Post: ${all.data.bestPost.data.post.caption}`);
+         * }
+         * ```
+         *
+         * GET /v1/insights/instagram
+         */
+        getAll: (params?: Insights.GetInstagramInsightParams) => Promise<Insights.InstagramAllInsightsResponse>;
+        /**
+         * Get Instagram health score
+         *
+         * Overall account health based on consistency, engagement, growth, and reach.
+         * Score ranges from 0-100 with labels: excellent, good, fair, needs_attention, poor.
+         *
+         * @example
+         * ```typescript
+         * const health = await client.insights.instagram.getHealthScore({ range: '30d' });
+         *
+         * if (health.hasData) {
+         *   console.log(`Score: ${health.data.overall}/100 (${health.data.label})`);
+         *   console.log(`Consistency: ${health.data.components.consistency.score}`);
+         *   console.log(`Engagement: ${health.data.components.engagement.score}`);
+         *   console.log(`Growth: ${health.data.components.growth.score}`);
+         *   console.log(`Reach: ${health.data.components.reach.score}`);
+         * }
+         * ```
+         *
+         * GET /v1/insights/instagram/health
+         */
+        getHealthScore: (params?: Insights.GetInstagramInsightParams) => Promise<Insights.InstagramHealthScoreResponse>;
+        /**
+         * Get best performing post
+         *
+         * Identifies the top performing post in the period based on engagement rate.
+         * Includes analysis of why it worked and comparison to average.
+         *
+         * @example
+         * ```typescript
+         * const best = await client.insights.instagram.getBestPost({ range: '30d' });
+         *
+         * if (best.hasData) {
+         *   console.log(`Post: ${best.data.post.caption}`);
+         *   console.log(`Engagement: ${best.data.post.metrics.engagementRate}%`);
+         *   console.log(`Above average: ${best.data.comparison.vsAverage.engagement}%`);
+         * }
+         * ```
+         *
+         * GET /v1/insights/instagram/best-post
+         */
+        getBestPost: (params?: Insights.GetInstagramInsightParams) => Promise<Insights.BestPerformingPostResponse>;
+        /**
+         * Get posting consistency analysis
+         *
+         * Analyzes posting frequency patterns and consistency.
+         * Identifies best posting days and gaps in schedule.
+         *
+         * @example
+         * ```typescript
+         * const consistency = await client.insights.instagram.getConsistency({ range: '90d' });
+         *
+         * if (consistency.hasData) {
+         *   console.log(`Posts/week: ${consistency.data.frequency.current.postsPerWeek}`);
+         *   console.log(`Score: ${consistency.data.consistency.score}/100`);
+         *   console.log(`Best day: ${consistency.data.patterns.mostActiveDay}`);
+         * }
+         * ```
+         *
+         * GET /v1/insights/instagram/consistency
+         */
+        getConsistency: (params?: Insights.GetInstagramInsightParams) => Promise<Insights.PostingConsistencyResponse>;
+        /**
+         * Get follower quality analysis
+         *
+         * Measures the quality and engagement of followers.
+         * Shows growth metrics and engagement rates.
+         *
+         * @example
+         * ```typescript
+         * const quality = await client.insights.instagram.getFollowerQuality({ range: '30d' });
+         *
+         * if (quality.hasData) {
+         *   console.log(`Quality: ${quality.data.qualityScore}/100`);
+         *   console.log(`Engagement rate: ${quality.data.metrics.engagementRate}%`);
+         *   console.log(`Growth: +${quality.data.growth.netChange} followers`);
+         * }
+         * ```
+         *
+         * GET /v1/insights/instagram/follower-quality
+         */
+        getFollowerQuality: (params?: Insights.GetInstagramInsightParams) => Promise<Insights.FollowerQualityResponse>;
+        /**
+         * Get account momentum
+         *
+         * Shows current account trajectory: surging, growing, stable, declining, or stalling.
+         * Compares recent performance to previous periods.
+         *
+         * @example
+         * ```typescript
+         * const momentum = await client.insights.instagram.getMomentum();
+         *
+         * if (momentum.hasData) {
+         *   console.log(`Status: ${momentum.data.current.status}`);
+         *   console.log(`Score: ${momentum.data.current.score}`);
+         *   console.log(`vs Last Week: ${momentum.data.comparison.vsLastWeek}%`);
+         * }
+         * ```
+         *
+         * GET /v1/insights/instagram/momentum
+         */
+        getMomentum: () => Promise<Insights.InstagramMomentumResponse>;
+        /**
+         * Get engagement breakdown
+         *
+         * Breaks down engagement by type: likes, comments, shares, saves.
+         * Identifies engagement style and opportunities.
+         *
+         * @example
+         * ```typescript
+         * const engagement = await client.insights.instagram.getEngagement({ range: '30d' });
+         *
+         * if (engagement.hasData) {
+         *   console.log(`Total: ${engagement.data.totalEngagement}`);
+         *   console.log(`Style: ${engagement.data.engagementStyle}`);
+         *   console.log(`Likes: ${engagement.data.breakdown.likes.percent}%`);
+         *   console.log(`Comments: ${engagement.data.breakdown.comments.percent}%`);
+         * }
+         * ```
+         *
+         * GET /v1/insights/instagram/engagement
+         */
+        getEngagement: (params?: Insights.GetInstagramInsightParams) => Promise<Insights.EngagementBreakdownResponse>;
+    };
 }
 
 /**
@@ -2587,6 +2903,114 @@ declare class ActivityModule {
     getLatest(jobType: Activity.JobType): Promise<Activity.LogEntry | null>;
 }
 
+/**
+ * Trends Module
+ *
+ * Methods for fetching trending content ideas from TrendPulse.
+ */
+
+declare class TrendsModule {
+    private client;
+    constructor(client: TrndUpClient);
+    /**
+     * List trending topics with optional filters
+     *
+     * @param params - Filter and pagination options
+     * @returns Paginated list of trends sorted by relevance
+     *
+     * @example
+     * ```typescript
+     * // Get top trends
+     * const trends = await sdk.trends.list();
+     *
+     * // Filter by category
+     * const sportsTrends = await sdk.trends.list({ category: 'SPORTS' });
+     *
+     * // Filter by velocity
+     * const viralTrends = await sdk.trends.list({ velocity: 'VIRAL' });
+     *
+     * // Paginate
+     * const page2 = await sdk.trends.list({ limit: 20, offset: 20 });
+     * ```
+     */
+    list(params?: Trends.ListParams): Promise<Trends.ListResponse>;
+    /**
+     * Get full details of a specific trend
+     *
+     * @param trendId - The unique trend ID
+     * @returns Full trend details including content ideas and examples
+     *
+     * @example
+     * ```typescript
+     * const trend = await sdk.trends.getById('trend_123');
+     * console.log(trend.contentIdeas);
+     * console.log(trend.topExamples);
+     * ```
+     */
+    getById(trendId: string): Promise<Trends.TrendDetail>;
+    /**
+     * Get all categories with trend counts
+     *
+     * @returns List of categories and their trend counts
+     *
+     * @example
+     * ```typescript
+     * const categories = await sdk.trends.getCategories();
+     * // [{ category: 'SPORTS', count: 15 }, { category: 'TECH', count: 12 }, ...]
+     * ```
+     */
+    getCategories(): Promise<Trends.CategoryCount[]>;
+    /**
+     * Get all platforms with trend counts
+     *
+     * @returns List of platforms and their trend counts
+     *
+     * @example
+     * ```typescript
+     * const platforms = await sdk.trends.getPlatforms();
+     * // [{ platform: 'YouTube', count: 25 }, { platform: 'Instagram', count: 18 }, ...]
+     * ```
+     */
+    getPlatforms(): Promise<Trends.PlatformCount[]>;
+    /**
+     * Get sync status information
+     *
+     * @returns Current sync status and statistics
+     *
+     * @example
+     * ```typescript
+     * const status = await sdk.trends.getSyncStatus();
+     * console.log(status.lastSyncedAt);
+     * console.log(status.totalTrends);
+     * ```
+     */
+    getSyncStatus(): Promise<Trends.SyncStatus>;
+    /**
+     * Get viral trends (velocity = VIRAL)
+     * Convenience method for filtering viral trends
+     *
+     * @param limit - Max results (default: 10)
+     * @returns List of viral trends
+     */
+    getViral(limit?: number): Promise<Trends.ListResponse>;
+    /**
+     * Get peaking trends (status = PEAKING)
+     * Convenience method for filtering trends at peak
+     *
+     * @param limit - Max results (default: 10)
+     * @returns List of peaking trends
+     */
+    getPeaking(limit?: number): Promise<Trends.ListResponse>;
+    /**
+     * Get trends for a specific platform
+     *
+     * @param platform - Platform name (e.g., 'YouTube', 'Instagram')
+     * @param limit - Max results (default: 20)
+     * @returns List of trends for the platform
+     */
+    getByPlatform(platform: string, limit?: number): Promise<Trends.ListResponse>;
+}
+
 /**
  * TrndUp API SDK
  *
@@ -2632,9 +3056,10 @@ declare class TrndUpSDK extends TrndUpClient {
     social: SocialModule;
     insights: InsightsModule;
     activity: ActivityModule;
+    trends: TrendsModule;
     constructor(config: TrndUpClientConfig);
 }
 
 declare const SDK_VERSION = "1.0.0";
 
-export { Activity, Auth, INSTAGRAM_SCOPES, Insights, Instagram, type RequestOptions, SDK_VERSION, Social, TrndUpApiError, type TrndUpClientConfig, TrndUpNetworkError, TrndUpSDK, YOUTUBE_SCOPES, YouTube };
+export { Activity, Auth, INSTAGRAM_SCOPES, Insights, Instagram, type RequestOptions, SDK_VERSION, Social, Trends, TrndUpApiError, type TrndUpClientConfig, TrndUpNetworkError, TrndUpSDK, YOUTUBE_SCOPES, YouTube };