@dracoonghost/trndup-sdk 1.4.0 → 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