@dracoonghost/trndup-sdk 1.3.24 → 1.3.26

package/dist/index.d.mts

@@ -1401,6 +1401,259 @@ declare namespace Insights {
         /** Days per comparison period (14-90, default: 30) */
         period?: number;
     }
+    interface TopPostData {
+        mediaId: string;
+        caption: string | null;
+        mediaType: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM' | 'REELS';
+        thumbnailUrl: string | null;
+        permalink: string;
+        postedAt: string;
+        ageInDays: number;
+    }
+    interface TopPostMetrics {
+        reach: number;
+        views: number;
+        likes: number;
+        comments: number;
+        shares: number;
+        saves: number;
+        engagementRate: number;
+    }
+    interface TopPostComparison {
+        vsAccountAverage: {
+            reach: number;
+            engagement: number;
+            description: string;
+        };
+        standoutReasons: string[];
+    }
+    interface BestPerformingPostData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        topPost: TopPostData;
+        metrics: TopPostMetrics;
+        comparison: TopPostComparison;
+        insight: string;
+        runnersUp: Array<{
+            mediaId: string;
+            caption: string | null;
+            reach: number;
+            thumbnailUrl: string | null;
+        }>;
+    }
+    type BestPerformingPostResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: BestPerformingPostData;
+        _meta: InsightMeta;
+    };
+    type PostingConsistencyStatus = 'excellent' | 'good' | 'needs_improvement' | 'poor' | 'inactive';
+    interface MonthlyPostData {
+        month: string;
+        posts: number;
+        avgGap: number | null;
+    }
+    interface PostingConsistencyData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        consistencyScore: number;
+        status: PostingConsistencyStatus;
+        metrics: {
+            totalPosts: number;
+            avgDaysBetweenPosts: number;
+            postVariance: number;
+            daysSinceLastPost: number;
+            lastPostDate: string | null;
+        };
+        pattern: {
+            isRegular: boolean;
+            typicalGap: string;
+            longestStreak: number;
+            currentStreak: number;
+            trend: 'increasing' | 'stable' | 'decreasing';
+            trendDescription: string;
+        };
+        monthlyBreakdown: MonthlyPostData[];
+        recommendation: {
+            suggested: string;
+            current: string;
+            reason: string;
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type PostingConsistencyResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: PostingConsistencyData;
+        _meta: InsightMeta;
+    };
+    type FollowerQualityLabel = 'excellent' | 'good' | 'fair' | 'needs_attention' | 'concerning';
+    interface FollowerQualityData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        qualityScore: number;
+        scoreLabel: FollowerQualityLabel;
+        metrics: {
+            followsGained: number;
+            unfollows: number;
+            netFollowers: number;
+            retentionRate: number;
+            engagementPerFollower: number;
+            reachPerFollower: number;
+            accountsEngaged: number;
+        };
+        trend: {
+            scoreChange: number;
+            direction: 'improving' | 'stable' | 'declining';
+            description: string;
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type FollowerQualityResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: FollowerQualityData;
+        _meta: InsightMeta;
+    };
+    type InstagramMomentumStatus = 'surging' | 'rising' | 'steady' | 'cooling' | 'dropping';
+    type InstagramMomentumTrend = 'accelerating' | 'stable' | 'decelerating';
+    interface InstagramMetricChange {
+        current: number;
+        previous: number;
+        change: number;
+    }
+    interface InstagramMomentumData {
+        score: number;
+        rawChange: number;
+        status: InstagramMomentumStatus;
+        trend: InstagramMomentumTrend;
+        previousScore: number | null;
+        period: {
+            current: {
+                start: string;
+                end: string;
+            };
+            previous: {
+                start: string;
+                end: string;
+            };
+        };
+        breakdown: {
+            reach: InstagramMetricChange;
+            engagement: InstagramMetricChange;
+            followers: InstagramMetricChange;
+            profileViews: InstagramMetricChange;
+        };
+        insight: string;
+        topDrivers: string[];
+    }
+    type InstagramMomentumResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: InstagramMomentumData;
+        _meta: InsightMeta;
+    };
+    type EngagementStyle = 'passive' | 'active' | 'viral' | 'valuable';
+    interface EngagementMetricBreakdown {
+        count: number;
+        percent: number;
+        trend: number;
+    }
+    interface EngagementBreakdownData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        totalEngagement: number;
+        breakdown: {
+            likes: EngagementMetricBreakdown;
+            comments: EngagementMetricBreakdown;
+            shares: EngagementMetricBreakdown;
+            saves: EngagementMetricBreakdown;
+        };
+        engagementStyle: EngagementStyle;
+        analysis: {
+            strongestType: string;
+            weakestType: string;
+            opportunity: string;
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type EngagementBreakdownResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: EngagementBreakdownData;
+        _meta: InsightMeta;
+    };
+    type InstagramHealthLabel = 'excellent' | 'good' | 'fair' | 'needs_attention' | 'poor';
+    interface HealthScoreComponent {
+        score: number;
+        label: string;
+        trend: number;
+    }
+    interface InstagramHealthScoreData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        overall: number;
+        label: InstagramHealthLabel;
+        components: {
+            consistency: HealthScoreComponent;
+            engagement: HealthScoreComponent;
+            growth: HealthScoreComponent;
+            reach: HealthScoreComponent;
+        };
+        metrics: {
+            postsPerWeek: number;
+            avgEngagementRate: number;
+            followerGrowthRate: number;
+            avgReachPerPost: number;
+        };
+        percentageChanges: {
+            overall: number;
+            components: {
+                consistency: number;
+                engagement: number;
+                growth: number;
+                reach: number;
+            };
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type InstagramHealthScoreResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: InstagramHealthScoreData;
+        _meta: InsightMeta;
+    };
+    interface InstagramAllInsightsData {
+        bestPost: BestPerformingPostResponse;
+        consistency: PostingConsistencyResponse;
+        followerQuality: FollowerQualityResponse;
+        momentum: InstagramMomentumResponse;
+        engagement: EngagementBreakdownResponse;
+        health: InstagramHealthScoreResponse;
+    }
+    interface InstagramAllInsightsResponse {
+        data: InstagramAllInsightsData;
+        meta: {
+            available: string[];
+        };
+    }
+    interface GetInstagramInsightParams {
+        /** Time range (e.g., "30d") */
+        range?: string;
+    }
 }
 declare namespace Activity {
     /**
@@ -1566,6 +1819,10 @@ declare class TrndUpClient {
     patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
     private request;
+    private logRequest;
+    private logResponse;
+    private logError;
+    private truncateObject;
     private buildUrl;
     private buildHeaders;
     private handleResponse;

package/dist/index.d.ts

@@ -1401,6 +1401,259 @@ declare namespace Insights {
         /** Days per comparison period (14-90, default: 30) */
         period?: number;
     }
+    interface TopPostData {
+        mediaId: string;
+        caption: string | null;
+        mediaType: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM' | 'REELS';
+        thumbnailUrl: string | null;
+        permalink: string;
+        postedAt: string;
+        ageInDays: number;
+    }
+    interface TopPostMetrics {
+        reach: number;
+        views: number;
+        likes: number;
+        comments: number;
+        shares: number;
+        saves: number;
+        engagementRate: number;
+    }
+    interface TopPostComparison {
+        vsAccountAverage: {
+            reach: number;
+            engagement: number;
+            description: string;
+        };
+        standoutReasons: string[];
+    }
+    interface BestPerformingPostData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        topPost: TopPostData;
+        metrics: TopPostMetrics;
+        comparison: TopPostComparison;
+        insight: string;
+        runnersUp: Array<{
+            mediaId: string;
+            caption: string | null;
+            reach: number;
+            thumbnailUrl: string | null;
+        }>;
+    }
+    type BestPerformingPostResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: BestPerformingPostData;
+        _meta: InsightMeta;
+    };
+    type PostingConsistencyStatus = 'excellent' | 'good' | 'needs_improvement' | 'poor' | 'inactive';
+    interface MonthlyPostData {
+        month: string;
+        posts: number;
+        avgGap: number | null;
+    }
+    interface PostingConsistencyData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        consistencyScore: number;
+        status: PostingConsistencyStatus;
+        metrics: {
+            totalPosts: number;
+            avgDaysBetweenPosts: number;
+            postVariance: number;
+            daysSinceLastPost: number;
+            lastPostDate: string | null;
+        };
+        pattern: {
+            isRegular: boolean;
+            typicalGap: string;
+            longestStreak: number;
+            currentStreak: number;
+            trend: 'increasing' | 'stable' | 'decreasing';
+            trendDescription: string;
+        };
+        monthlyBreakdown: MonthlyPostData[];
+        recommendation: {
+            suggested: string;
+            current: string;
+            reason: string;
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type PostingConsistencyResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: PostingConsistencyData;
+        _meta: InsightMeta;
+    };
+    type FollowerQualityLabel = 'excellent' | 'good' | 'fair' | 'needs_attention' | 'concerning';
+    interface FollowerQualityData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        qualityScore: number;
+        scoreLabel: FollowerQualityLabel;
+        metrics: {
+            followsGained: number;
+            unfollows: number;
+            netFollowers: number;
+            retentionRate: number;
+            engagementPerFollower: number;
+            reachPerFollower: number;
+            accountsEngaged: number;
+        };
+        trend: {
+            scoreChange: number;
+            direction: 'improving' | 'stable' | 'declining';
+            description: string;
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type FollowerQualityResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: FollowerQualityData;
+        _meta: InsightMeta;
+    };
+    type InstagramMomentumStatus = 'surging' | 'rising' | 'steady' | 'cooling' | 'dropping';
+    type InstagramMomentumTrend = 'accelerating' | 'stable' | 'decelerating';
+    interface InstagramMetricChange {
+        current: number;
+        previous: number;
+        change: number;
+    }
+    interface InstagramMomentumData {
+        score: number;
+        rawChange: number;
+        status: InstagramMomentumStatus;
+        trend: InstagramMomentumTrend;
+        previousScore: number | null;
+        period: {
+            current: {
+                start: string;
+                end: string;
+            };
+            previous: {
+                start: string;
+                end: string;
+            };
+        };
+        breakdown: {
+            reach: InstagramMetricChange;
+            engagement: InstagramMetricChange;
+            followers: InstagramMetricChange;
+            profileViews: InstagramMetricChange;
+        };
+        insight: string;
+        topDrivers: string[];
+    }
+    type InstagramMomentumResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: InstagramMomentumData;
+        _meta: InsightMeta;
+    };
+    type EngagementStyle = 'passive' | 'active' | 'viral' | 'valuable';
+    interface EngagementMetricBreakdown {
+        count: number;
+        percent: number;
+        trend: number;
+    }
+    interface EngagementBreakdownData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        totalEngagement: number;
+        breakdown: {
+            likes: EngagementMetricBreakdown;
+            comments: EngagementMetricBreakdown;
+            shares: EngagementMetricBreakdown;
+            saves: EngagementMetricBreakdown;
+        };
+        engagementStyle: EngagementStyle;
+        analysis: {
+            strongestType: string;
+            weakestType: string;
+            opportunity: string;
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type EngagementBreakdownResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: EngagementBreakdownData;
+        _meta: InsightMeta;
+    };
+    type InstagramHealthLabel = 'excellent' | 'good' | 'fair' | 'needs_attention' | 'poor';
+    interface HealthScoreComponent {
+        score: number;
+        label: string;
+        trend: number;
+    }
+    interface InstagramHealthScoreData {
+        period: {
+            start: string;
+            end: string;
+            days: number;
+        };
+        overall: number;
+        label: InstagramHealthLabel;
+        components: {
+            consistency: HealthScoreComponent;
+            engagement: HealthScoreComponent;
+            growth: HealthScoreComponent;
+            reach: HealthScoreComponent;
+        };
+        metrics: {
+            postsPerWeek: number;
+            avgEngagementRate: number;
+            followerGrowthRate: number;
+            avgReachPerPost: number;
+        };
+        percentageChanges: {
+            overall: number;
+            components: {
+                consistency: number;
+                engagement: number;
+                growth: number;
+                reach: number;
+            };
+        };
+        insight: string;
+        recommendations: string[];
+    }
+    type InstagramHealthScoreResponse = InsufficientDataResponse | {
+        hasData: true;
+        data: InstagramHealthScoreData;
+        _meta: InsightMeta;
+    };
+    interface InstagramAllInsightsData {
+        bestPost: BestPerformingPostResponse;
+        consistency: PostingConsistencyResponse;
+        followerQuality: FollowerQualityResponse;
+        momentum: InstagramMomentumResponse;
+        engagement: EngagementBreakdownResponse;
+        health: InstagramHealthScoreResponse;
+    }
+    interface InstagramAllInsightsResponse {
+        data: InstagramAllInsightsData;
+        meta: {
+            available: string[];
+        };
+    }
+    interface GetInstagramInsightParams {
+        /** Time range (e.g., "30d") */
+        range?: string;
+    }
 }
 declare namespace Activity {
     /**
@@ -1566,6 +1819,10 @@ declare class TrndUpClient {
     patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
     private request;
+    private logRequest;
+    private logResponse;
+    private logError;
+    private truncateObject;
     private buildUrl;
     private buildHeaders;
     private handleResponse;

package/dist/index.js

@@ -83,19 +83,27 @@ var TrndUpClient = class {
       () => controller.abort(),
       timeout ?? this.config.timeout
     );
+    const startTime = Date.now();
     try {
       if (this.config.debug) {
-        console.log(`[TrndUp SDK] ${method} ${url}`, { body, headers: requestHeaders });
+        this.logRequest(method, url, body);
       }
       const response = await fetch(url, {
         ...init,
         signal: signal ?? controller.signal
       });
       clearTimeout(timeoutId);
-      return await this.handleResponse(response, path);
+      const result = await this.handleResponse(response, path);
+      if (this.config.debug) {
+        this.logResponse(method, path, response.status, result, startTime);
+      }
+      return result;
     } catch (error) {
       clearTimeout(timeoutId);
       if (error instanceof TrndUpApiError) {
+        if (this.config.debug) {
+          this.logError(method, path, error, startTime);
+        }
         throw error;
       }
       const networkError = new TrndUpNetworkError(
@@ -103,11 +111,56 @@ var TrndUpClient = class {
         path
       );
       if (this.config.debug) {
-        console.error("[TrndUp SDK] Network error:", networkError);
+        this.logError(method, path, networkError, startTime);
       }
       throw networkError;
     }
   }
+  // =============================================================================
+  // LOGGING HELPERS
+  // =============================================================================
+  logRequest(method, url, body) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[1].slice(0, 12);
+    const bodyPreview = body ? this.truncateObject(body, 200) : void 0;
+    console.log(
+      `\x1B[36m[${timestamp}]\x1B[0m \x1B[33m\u2192 ${method}\x1B[0m ${url}` + (bodyPreview ? `
+  \x1B[90mbody:\x1B[0m ${bodyPreview}` : "")
+    );
+  }
+  logResponse(method, path, status, data, startTime) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[1].slice(0, 12);
+    const duration = Date.now() - startTime;
+    const statusColor = status >= 200 && status < 300 ? "\x1B[32m" : "\x1B[31m";
+    const dataPreview = this.truncateObject(data, 300);
+    console.log(
+      `\x1B[36m[${timestamp}]\x1B[0m ${statusColor}\u2190 ${status}\x1B[0m ${method} ${path} \x1B[90m(${duration}ms)\x1B[0m
+  \x1B[90mdata:\x1B[0m ${dataPreview}`
+    );
+  }
+  logError(method, path, error, startTime) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[1].slice(0, 12);
+    const duration = Date.now() - startTime;
+    if (error instanceof TrndUpApiError) {
+      console.log(
+        `\x1B[36m[${timestamp}]\x1B[0m \x1B[31m\u2715 ${error.status}\x1B[0m ${method} ${path} \x1B[90m(${duration}ms)\x1B[0m
+  \x1B[31merror:\x1B[0m ${error.code || "UNKNOWN"} - ${error.message}`
+      );
+    } else {
+      console.log(
+        `\x1B[36m[${timestamp}]\x1B[0m \x1B[31m\u2715 NETWORK\x1B[0m ${method} ${path} \x1B[90m(${duration}ms)\x1B[0m
+  \x1B[31merror:\x1B[0m ${error.message}`
+      );
+    }
+  }
+  truncateObject(obj, maxLength) {
+    try {
+      const str = JSON.stringify(obj);
+      if (str.length <= maxLength) return str;
+      return str.slice(0, maxLength) + "...";
+    } catch {
+      return "[Unable to serialize]";
+    }
+  }
   buildUrl(path, params) {
     const url = new URL(`${this.config.baseUrl}${path}`);
     if (params) {
@@ -164,9 +217,6 @@ var TrndUpClient = class {
       if (apiError.isAuthError() && this.config.onAuthFailure) {
         await this.config.onAuthFailure();
       }
-      if (this.config.debug) {
-        console.error("[TrndUp SDK] API error:", apiError);
-      }
       throw apiError;
     }
     if (isJson) {