@dracoonghost/trndup-sdk 1.3.21 → 1.3.23

package/dist/index.d.mts

@@ -595,6 +595,125 @@ declare namespace Instagram {
         stories: Story[];
         count: number;
     }
+    /** Sync status enum matching backend */
+    type SyncStatus = 'NEVER_SYNCED' | 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
+    /** Individual sync type info */
+    interface SyncTypeInfo {
+        status: SyncStatus;
+        lastSyncAt: string | null;
+        lastError?: string | null;
+        failedAttempts?: number;
+        isStale: boolean;
+        nextSyncAt: string | null;
+        timeUntilNextSync: string;
+        interval: string;
+    }
+    /**
+     * Unified sync status response
+     * GET /v1/platforms/instagram/sync/status
+     */
+    interface UnifiedSyncStatusResponse {
+        isConnected: boolean;
+        igUserId: string | null;
+        username: string | null;
+        totalPosts: number;
+        syncs: {
+            accountInfo: SyncTypeInfo;
+            posts: SyncTypeInfo;
+            accountAnalytics: SyncTypeInfo;
+            postInsights: SyncTypeInfo;
+            stories: SyncTypeInfo;
+        };
+    }
+    /**
+     * Response from POST /v1/platforms/instagram/posts/sync
+     */
+    interface PostsSyncResponse {
+        posts: {
+            total: number;
+            synced: number;
+            oldestPostDate: string | null;
+        };
+        syncStatus: {
+            isFirstSync: boolean;
+            lastSyncAt: string;
+        };
+    }
+    /**
+     * Response from GET /v1/platforms/instagram/posts/sync/status
+     */
+    interface PostsSyncStatusResponse {
+        needsSync: boolean;
+        status: SyncStatus;
+        lastSyncAt: string | null;
+        postCount: number;
+        oldestPostDate: string | null;
+    }
+    /**
+     * Response from POST /v1/platforms/instagram/analytics/account/sync
+     */
+    interface AccountAnalyticsSyncResponse {
+        range: string;
+        metricsCount: number;
+        syncStatus: SyncStatus;
+        lastSyncAt: string;
+    }
+    /**
+     * Response from GET /v1/platforms/instagram/analytics/account/sync/status
+     */
+    interface AccountAnalyticsSyncStatusResponse {
+        needsSync: boolean;
+        status: SyncStatus;
+        insightRecords: number;
+        dateRange: {
+            start: string;
+            end: string;
+        } | null;
+        lastSyncAt: string | null;
+        message: string;
+    }
+    /**
+     * Response from POST /v1/platforms/instagram/analytics/posts/sync
+     * Post insights are queued for background processing via BullMQ
+     */
+    interface PostInsightsSyncResponse {
+        message: string;
+        totalPosts: number;
+        jobsQueued: number;
+        status: SyncStatus;
+        queuedAt: string;
+    }
+    /**
+     * Response when sync is already in progress
+     */
+    interface PostInsightsInProgressResponse {
+        message: string;
+        status: 'in_progress';
+        progress: {
+            waiting: number;
+            active: number;
+            completed: number;
+            failed: number;
+            delayed: number;
+        };
+    }
+    /**
+     * Response from GET /v1/platforms/instagram/analytics/posts/sync/status
+     */
+    interface PostInsightsSyncStatusResponse {
+        needsSync: boolean;
+        status: SyncStatus;
+        totalPosts: number;
+        postsWithInsights: number;
+        coverage: number;
+        lastSyncAt: string | null;
+        metadata?: {
+            postsWithInsights?: number;
+            totalPosts?: number;
+            lastCheckedAt?: string;
+        } | null;
+        message: string;
+    }
     interface SyncResponse {
         message: string;
         profile?: {
@@ -1650,21 +1769,69 @@ declare class YouTubeModule {
  * TrndUp SDK - Instagram Module
  *
  * Instagram analytics and data methods
+ * Route structure mirrors YouTube for UI consistency
  */
 
 declare class InstagramModule {
     private client;
     constructor(client: TrndUpClient);
     /**
-     * Get Instagram initialization status
-     * GET /v1/platforms/instagram/status/init
+     * Get unified sync status for all Instagram data types
+     * GET /v1/platforms/instagram/sync/status
+     *
+     * Shows when each type was last synced and when next sync is due.
      */
-    getInitStatus(): Promise<Instagram.InitStatusResponse>;
+    getSyncStatus(): Promise<Instagram.UnifiedSyncStatusResponse>;
     /**
      * Initialize Instagram data sync
-     * GET /v1/platforms/instagram/init
+     * POST /v1/platforms/instagram/init
      */
     initialize(): Promise<Instagram.InitResponse>;
+    /**
+     * Get Instagram initialization status
+     * GET /v1/platforms/instagram/init/status
+     */
+    getInitStatus(): Promise<Instagram.InitStatusResponse>;
+    /**
+     * Sync all posts from Instagram to database
+     * POST /v1/platforms/instagram/posts/sync
+     */
+    syncPosts(): Promise<Instagram.PostsSyncResponse>;
+    /**
+     * Check posts sync status without triggering a sync
+     * GET /v1/platforms/instagram/posts/sync/status
+     */
+    getPostsSyncStatus(): Promise<Instagram.PostsSyncStatusResponse>;
+    /**
+     * Sync account-level analytics (reach, impressions, engagement)
+     * POST /v1/platforms/instagram/analytics/account/sync
+     * @param range Time range: '7d', '14d', '30d' (default '30d')
+     */
+    syncAccountAnalytics(params?: {
+        range?: string;
+    }): Promise<Instagram.AccountAnalyticsSyncResponse>;
+    /**
+     * Get account analytics sync status
+     * GET /v1/platforms/instagram/analytics/account/sync/status
+     */
+    getAccountAnalyticsSyncStatus(): Promise<Instagram.AccountAnalyticsSyncStatusResponse>;
+    /**
+     * Queue post-level insights sync for all posts (BullMQ-based)
+     * POST /v1/platforms/instagram/analytics/posts/sync
+     *
+     * Jobs are queued and processed in the background.
+     * Poll getPostInsightsSyncStatus() to check progress.
+     *
+     * @returns Response with jobsQueued count and status
+     */
+    syncPostInsights(): Promise<Instagram.PostInsightsSyncResponse>;
+    /**
+     * Get post insights sync status
+     * GET /v1/platforms/instagram/analytics/posts/sync/status
+     *
+     * Use to poll progress while sync is in_progress
+     */
+    getPostInsightsSyncStatus(): Promise<Instagram.PostInsightsSyncStatusResponse>;
     /**
      * Get user profile info
      * GET /v1/platforms/instagram/profile
@@ -1677,7 +1844,7 @@ declare class InstagramModule {
      */
     getAccountOverview(params?: Instagram.GetAccountOverviewParams): Promise<Instagram.AccountOverviewResponse>;
     /**
-     * Get account-level insights
+     * Get account-level insights (historical data)
      * GET /v1/platforms/instagram/account/insights
      * @param range Time range: '7d', '14d', '28d', '30d'
      */
@@ -1698,18 +1865,11 @@ declare class InstagramModule {
      */
     getStories(): Promise<Instagram.StoriesResponse>;
     /**
-     * Trigger manual data sync
+     * Trigger manual data sync (legacy - use specific sync methods)
      * POST /v1/platforms/instagram/sync
+     * @deprecated Use syncPosts, syncAccountAnalytics, syncPostInsights instead
      */
     sync(): Promise<Instagram.SyncResponse>;
-    /**
-     * @deprecated Use getAccountInsights instead
-     */
-    getAccountMetrics(): Promise<Instagram.AccountInsightsResponse>;
-    /**
-     * @deprecated Use sync instead
-     */
-    refresh(): Promise<Instagram.SyncResponse>;
 }
 
 /**

package/dist/index.d.ts

@@ -595,6 +595,125 @@ declare namespace Instagram {
         stories: Story[];
         count: number;
     }
+    /** Sync status enum matching backend */
+    type SyncStatus = 'NEVER_SYNCED' | 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
+    /** Individual sync type info */
+    interface SyncTypeInfo {
+        status: SyncStatus;
+        lastSyncAt: string | null;
+        lastError?: string | null;
+        failedAttempts?: number;
+        isStale: boolean;
+        nextSyncAt: string | null;
+        timeUntilNextSync: string;
+        interval: string;
+    }
+    /**
+     * Unified sync status response
+     * GET /v1/platforms/instagram/sync/status
+     */
+    interface UnifiedSyncStatusResponse {
+        isConnected: boolean;
+        igUserId: string | null;
+        username: string | null;
+        totalPosts: number;
+        syncs: {
+            accountInfo: SyncTypeInfo;
+            posts: SyncTypeInfo;
+            accountAnalytics: SyncTypeInfo;
+            postInsights: SyncTypeInfo;
+            stories: SyncTypeInfo;
+        };
+    }
+    /**
+     * Response from POST /v1/platforms/instagram/posts/sync
+     */
+    interface PostsSyncResponse {
+        posts: {
+            total: number;
+            synced: number;
+            oldestPostDate: string | null;
+        };
+        syncStatus: {
+            isFirstSync: boolean;
+            lastSyncAt: string;
+        };
+    }
+    /**
+     * Response from GET /v1/platforms/instagram/posts/sync/status
+     */
+    interface PostsSyncStatusResponse {
+        needsSync: boolean;
+        status: SyncStatus;
+        lastSyncAt: string | null;
+        postCount: number;
+        oldestPostDate: string | null;
+    }
+    /**
+     * Response from POST /v1/platforms/instagram/analytics/account/sync
+     */
+    interface AccountAnalyticsSyncResponse {
+        range: string;
+        metricsCount: number;
+        syncStatus: SyncStatus;
+        lastSyncAt: string;
+    }
+    /**
+     * Response from GET /v1/platforms/instagram/analytics/account/sync/status
+     */
+    interface AccountAnalyticsSyncStatusResponse {
+        needsSync: boolean;
+        status: SyncStatus;
+        insightRecords: number;
+        dateRange: {
+            start: string;
+            end: string;
+        } | null;
+        lastSyncAt: string | null;
+        message: string;
+    }
+    /**
+     * Response from POST /v1/platforms/instagram/analytics/posts/sync
+     * Post insights are queued for background processing via BullMQ
+     */
+    interface PostInsightsSyncResponse {
+        message: string;
+        totalPosts: number;
+        jobsQueued: number;
+        status: SyncStatus;
+        queuedAt: string;
+    }
+    /**
+     * Response when sync is already in progress
+     */
+    interface PostInsightsInProgressResponse {
+        message: string;
+        status: 'in_progress';
+        progress: {
+            waiting: number;
+            active: number;
+            completed: number;
+            failed: number;
+            delayed: number;
+        };
+    }
+    /**
+     * Response from GET /v1/platforms/instagram/analytics/posts/sync/status
+     */
+    interface PostInsightsSyncStatusResponse {
+        needsSync: boolean;
+        status: SyncStatus;
+        totalPosts: number;
+        postsWithInsights: number;
+        coverage: number;
+        lastSyncAt: string | null;
+        metadata?: {
+            postsWithInsights?: number;
+            totalPosts?: number;
+            lastCheckedAt?: string;
+        } | null;
+        message: string;
+    }
     interface SyncResponse {
         message: string;
         profile?: {
@@ -1650,21 +1769,69 @@ declare class YouTubeModule {
  * TrndUp SDK - Instagram Module
  *
  * Instagram analytics and data methods
+ * Route structure mirrors YouTube for UI consistency
  */
 
 declare class InstagramModule {
     private client;
     constructor(client: TrndUpClient);
     /**
-     * Get Instagram initialization status
-     * GET /v1/platforms/instagram/status/init
+     * Get unified sync status for all Instagram data types
+     * GET /v1/platforms/instagram/sync/status
+     *
+     * Shows when each type was last synced and when next sync is due.
      */
-    getInitStatus(): Promise<Instagram.InitStatusResponse>;
+    getSyncStatus(): Promise<Instagram.UnifiedSyncStatusResponse>;
     /**
      * Initialize Instagram data sync
-     * GET /v1/platforms/instagram/init
+     * POST /v1/platforms/instagram/init
      */
     initialize(): Promise<Instagram.InitResponse>;
+    /**
+     * Get Instagram initialization status
+     * GET /v1/platforms/instagram/init/status
+     */
+    getInitStatus(): Promise<Instagram.InitStatusResponse>;
+    /**
+     * Sync all posts from Instagram to database
+     * POST /v1/platforms/instagram/posts/sync
+     */
+    syncPosts(): Promise<Instagram.PostsSyncResponse>;
+    /**
+     * Check posts sync status without triggering a sync
+     * GET /v1/platforms/instagram/posts/sync/status
+     */
+    getPostsSyncStatus(): Promise<Instagram.PostsSyncStatusResponse>;
+    /**
+     * Sync account-level analytics (reach, impressions, engagement)
+     * POST /v1/platforms/instagram/analytics/account/sync
+     * @param range Time range: '7d', '14d', '30d' (default '30d')
+     */
+    syncAccountAnalytics(params?: {
+        range?: string;
+    }): Promise<Instagram.AccountAnalyticsSyncResponse>;
+    /**
+     * Get account analytics sync status
+     * GET /v1/platforms/instagram/analytics/account/sync/status
+     */
+    getAccountAnalyticsSyncStatus(): Promise<Instagram.AccountAnalyticsSyncStatusResponse>;
+    /**
+     * Queue post-level insights sync for all posts (BullMQ-based)
+     * POST /v1/platforms/instagram/analytics/posts/sync
+     *
+     * Jobs are queued and processed in the background.
+     * Poll getPostInsightsSyncStatus() to check progress.
+     *
+     * @returns Response with jobsQueued count and status
+     */
+    syncPostInsights(): Promise<Instagram.PostInsightsSyncResponse>;
+    /**
+     * Get post insights sync status
+     * GET /v1/platforms/instagram/analytics/posts/sync/status
+     *
+     * Use to poll progress while sync is in_progress
+     */
+    getPostInsightsSyncStatus(): Promise<Instagram.PostInsightsSyncStatusResponse>;
     /**
      * Get user profile info
      * GET /v1/platforms/instagram/profile
@@ -1677,7 +1844,7 @@ declare class InstagramModule {
      */
     getAccountOverview(params?: Instagram.GetAccountOverviewParams): Promise<Instagram.AccountOverviewResponse>;
     /**
-     * Get account-level insights
+     * Get account-level insights (historical data)
      * GET /v1/platforms/instagram/account/insights
      * @param range Time range: '7d', '14d', '28d', '30d'
      */
@@ -1698,18 +1865,11 @@ declare class InstagramModule {
      */
     getStories(): Promise<Instagram.StoriesResponse>;
     /**
-     * Trigger manual data sync
+     * Trigger manual data sync (legacy - use specific sync methods)
      * POST /v1/platforms/instagram/sync
+     * @deprecated Use syncPosts, syncAccountAnalytics, syncPostInsights instead
      */
     sync(): Promise<Instagram.SyncResponse>;
-    /**
-     * @deprecated Use getAccountInsights instead
-     */
-    getAccountMetrics(): Promise<Instagram.AccountInsightsResponse>;
-    /**
-     * @deprecated Use sync instead
-     */
-    refresh(): Promise<Instagram.SyncResponse>;
 }
 
 /**

package/dist/index.js

@@ -486,22 +486,94 @@ var InstagramModule = class {
   constructor(client) {
     this.client = client;
   }
+  // ===== UNIFIED SYNC STATUS =====
+  /**
+   * Get unified sync status for all Instagram data types
+   * GET /v1/platforms/instagram/sync/status
+   * 
+   * Shows when each type was last synced and when next sync is due.
+   */
+  async getSyncStatus() {
+    return this.client.get("/v1/platforms/instagram/sync/status");
+  }
   // ===== INITIALIZATION =====
+  /**
+   * Initialize Instagram data sync
+   * POST /v1/platforms/instagram/init
+   */
+  async initialize() {
+    return this.client.post("/v1/platforms/instagram/init");
+  }
   /**
    * Get Instagram initialization status
-   * GET /v1/platforms/instagram/status/init
+   * GET /v1/platforms/instagram/init/status
    */
   async getInitStatus() {
-    return this.client.get("/v1/platforms/instagram/status/init");
+    return this.client.get("/v1/platforms/instagram/init/status");
   }
+  // ===== POSTS SYNC =====
   /**
-   * Initialize Instagram data sync
-   * GET /v1/platforms/instagram/init
+   * Sync all posts from Instagram to database
+   * POST /v1/platforms/instagram/posts/sync
    */
-  async initialize() {
-    return this.client.get("/v1/platforms/instagram/init");
+  async syncPosts() {
+    return this.client.post("/v1/platforms/instagram/posts/sync");
+  }
+  /**
+   * Check posts sync status without triggering a sync
+   * GET /v1/platforms/instagram/posts/sync/status
+   */
+  async getPostsSyncStatus() {
+    return this.client.get("/v1/platforms/instagram/posts/sync/status");
+  }
+  // ===== ACCOUNT ANALYTICS SYNC =====
+  /**
+   * Sync account-level analytics (reach, impressions, engagement)
+   * POST /v1/platforms/instagram/analytics/account/sync
+   * @param range Time range: '7d', '14d', '30d' (default '30d')
+   */
+  async syncAccountAnalytics(params) {
+    const queryParams = params?.range ? `?range=${params.range}` : "";
+    return this.client.post(
+      `/v1/platforms/instagram/analytics/account/sync${queryParams}`
+    );
+  }
+  /**
+   * Get account analytics sync status
+   * GET /v1/platforms/instagram/analytics/account/sync/status
+   */
+  async getAccountAnalyticsSyncStatus() {
+    return this.client.get(
+      "/v1/platforms/instagram/analytics/account/sync/status"
+    );
+  }
+  // ===== POST INSIGHTS SYNC =====
+  /**
+   * Queue post-level insights sync for all posts (BullMQ-based)
+   * POST /v1/platforms/instagram/analytics/posts/sync
+   * 
+   * Jobs are queued and processed in the background.
+   * Poll getPostInsightsSyncStatus() to check progress.
+   * 
+   * @returns Response with jobsQueued count and status
+   */
+  async syncPostInsights() {
+    return this.client.post(
+      "/v1/platforms/instagram/analytics/posts/sync"
+    );
+  }
+  /**
+   * Get post insights sync status
+   * GET /v1/platforms/instagram/analytics/posts/sync/status
+   * 
+   * Use to poll progress while sync is in_progress
+   */
+  async getPostInsightsSyncStatus() {
+    return this.client.get(
+      "/v1/platforms/instagram/analytics/posts/sync/status"
+    );
   }
-  // ===== ACCOUNT INSIGHTS =====
+  // ===== DATA RETRIEVAL =====
   /**
    * Get user profile info
    * GET /v1/platforms/instagram/profile
@@ -521,7 +593,7 @@ var InstagramModule = class {
     );
   }
   /**
-   * Get account-level insights
+   * Get account-level insights (historical data)
    * GET /v1/platforms/instagram/account/insights
    * @param range Time range: '7d', '14d', '28d', '30d'
    */
@@ -531,7 +603,6 @@ var InstagramModule = class {
       params
     );
   }
-  // ===== MEDIA / POSTS =====
   /**
    * Get Instagram posts
    * GET /v1/platforms/instagram/posts
@@ -551,7 +622,6 @@ var InstagramModule = class {
       `/v1/platforms/instagram/posts/${postId}/insights`
     );
   }
-  // ===== STORIES =====
   /**
    * Get active stories
    * GET /v1/platforms/instagram/stories
@@ -559,27 +629,15 @@ var InstagramModule = class {
   async getStories() {
     return this.client.get("/v1/platforms/instagram/stories");
   }
-  // ===== SYNC =====
+  // ===== LEGACY SYNC (backward compat) =====
   /**
-   * Trigger manual data sync
+   * Trigger manual data sync (legacy - use specific sync methods)
    * POST /v1/platforms/instagram/sync
+   * @deprecated Use syncPosts, syncAccountAnalytics, syncPostInsights instead
    */
   async sync() {
     return this.client.post("/v1/platforms/instagram/sync");
   }
-  // ===== LEGACY (backward compat) =====
-  /**
-   * @deprecated Use getAccountInsights instead
-   */
-  async getAccountMetrics() {
-    return this.getAccountInsights();
-  }
-  /**
-   * @deprecated Use sync instead
-   */
-  async refresh() {
-    return this.sync();
-  }
 };
 
 // modules/social.ts