@dracoonghost/trndup-sdk 1.3.26 → 1.5.0

package/dist/index.mjs

@@ -727,6 +727,203 @@ var SocialModule = class {
 var InsightsModule = class {
   constructor(client) {
     this.client = client;
+    // =========================================================================
+    // INSTAGRAM INSIGHTS
+    // =========================================================================
+    /**
+     * Instagram insights sub-module
+     */
+    this.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) => {
+        const queryParams = new URLSearchParams();
+        if (params?.range) queryParams.set("range", params.range);
+        const query = queryParams.toString();
+        return this.client.get(
+          `/v1/insights/instagram${query ? `?${query}` : ""}`
+        );
+      },
+      /**
+       * 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) => {
+        const queryParams = new URLSearchParams();
+        if (params?.range) queryParams.set("range", params.range);
+        const query = queryParams.toString();
+        return this.client.get(
+          `/v1/insights/instagram/health${query ? `?${query}` : ""}`
+        );
+      },
+      /**
+       * 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) => {
+        const queryParams = new URLSearchParams();
+        if (params?.range) queryParams.set("range", params.range);
+        const query = queryParams.toString();
+        return this.client.get(
+          `/v1/insights/instagram/best-post${query ? `?${query}` : ""}`
+        );
+      },
+      /**
+       * 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) => {
+        const queryParams = new URLSearchParams();
+        if (params?.range) queryParams.set("range", params.range);
+        const query = queryParams.toString();
+        return this.client.get(
+          `/v1/insights/instagram/consistency${query ? `?${query}` : ""}`
+        );
+      },
+      /**
+       * 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) => {
+        const queryParams = new URLSearchParams();
+        if (params?.range) queryParams.set("range", params.range);
+        const query = queryParams.toString();
+        return this.client.get(
+          `/v1/insights/instagram/follower-quality${query ? `?${query}` : ""}`
+        );
+      },
+      /**
+       * 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: () => {
+        return this.client.get("/v1/insights/instagram/momentum");
+      },
+      /**
+       * 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) => {
+        const queryParams = new URLSearchParams();
+        if (params?.range) queryParams.set("range", params.range);
+        const query = queryParams.toString();
+        return this.client.get(
+          `/v1/insights/instagram/engagement${query ? `?${query}` : ""}`
+        );
+      }
+    };
   }
   /**
    * Get cross-platform metrics
@@ -1216,6 +1413,133 @@ var ActivityModule = class {
   }
 };
 
+// modules/trends.ts
+var TrendsModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async list(params = {}) {
+    const queryParams = {};
+    if (params.category) queryParams.category = params.category;
+    if (params.velocity) queryParams.velocity = params.velocity;
+    if (params.status) queryParams.status = params.status;
+    if (params.platform) queryParams.platform = params.platform;
+    if (params.limit) queryParams.limit = params.limit;
+    if (params.offset) queryParams.offset = params.offset;
+    return this.client.get("/v1/trends", queryParams);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getById(trendId) {
+    return this.client.get(`/v1/trends/${trendId}`);
+  }
+  /**
+   * 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 }, ...]
+   * ```
+   */
+  async getCategories() {
+    return this.client.get("/v1/trends/meta/categories");
+  }
+  /**
+   * 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 }, ...]
+   * ```
+   */
+  async getPlatforms() {
+    return this.client.get("/v1/trends/meta/platforms");
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getSyncStatus() {
+    return this.client.get("/v1/trends/meta/sync-status");
+  }
+  /**
+   * Get viral trends (velocity = VIRAL)
+   * Convenience method for filtering viral trends
+   * 
+   * @param limit - Max results (default: 10)
+   * @returns List of viral trends
+   */
+  async getViral(limit = 10) {
+    return this.list({ velocity: "VIRAL", limit });
+  }
+  /**
+   * Get peaking trends (status = PEAKING)
+   * Convenience method for filtering trends at peak
+   * 
+   * @param limit - Max results (default: 10)
+   * @returns List of peaking trends
+   */
+  async getPeaking(limit = 10) {
+    return this.list({ status: "PEAKING", limit });
+  }
+  /**
+   * 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
+   */
+  async getByPlatform(platform, limit = 20) {
+    return this.list({ platform, limit });
+  }
+};
+
 // types.ts
 var YOUTUBE_SCOPES = [
   "openid",
@@ -1243,6 +1567,7 @@ var TrndUpSDK = class extends TrndUpClient {
     this.social = new SocialModule(this);
     this.insights = new InsightsModule(this);
     this.activity = new ActivityModule(this);
+    this.trends = new TrendsModule(this);
   }
 };
 var SDK_VERSION = "1.0.0";