@dracoonghost/trndup-sdk 1.3.12 → 1.3.14

package/README.md

@@ -8,13 +8,13 @@ Official TypeScript SDK for the TrndUp API with Firebase authentication support.
 # In your mobile app
 npm install file:../trndup-service/src/sdk
 # or when published
-npm install @trndup/sdk
+npm install @dracoonghost/trndup-sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { TrndUpSDK } from '@trndup/sdk';
+import { TrndUpSDK } from '@dracoonghost/trndup-sdk';
 import auth from '@react-native-firebase/auth';
 
 // Initialize SDK
@@ -132,7 +132,7 @@ const trending = await sdk.insights.getTrending();
 ## Error Handling
 
 ```typescript
-import { TrndUpApiError, TrndUpNetworkError } from '@trndup/sdk';
+import { TrndUpApiError, TrndUpNetworkError } from '@dracoonghost/trndup-sdk';
 
 try {
   await sdk.youtube.getVideos();
@@ -191,7 +191,7 @@ interface TrndUpClientConfig {
 The SDK is fully typed with TypeScript. All request/response types are available:
 
 ```typescript
-import type { Auth, YouTube, Instagram, Social, Insights } from '@trndup/sdk';
+import type { Auth, YouTube, Instagram, Social, Insights } from '@dracoonghost/trndup-sdk';
 
 // Use types in your code
 const user: Auth.User = await sdk.auth.getCurrentUser();
@@ -216,7 +216,7 @@ npm run type-check
 npm link
 
 # In your mobile app
-npm link @trndup/sdk
+npm link @dracoonghost/trndup-sdk
 ```
 
 ## License

package/dist/index.d.mts

@@ -10,7 +10,7 @@
  * @example
  * ```typescript
  * import { GoogleSignin } from '@react-native-google-signin/google-signin';
- * import { YOUTUBE_SCOPES } from '@trndup/sdk';
+ * import { YOUTUBE_SCOPES } from '@dracoonghost/trndup-sdk';
  *
  * GoogleSignin.configure({
  *   webClientId: 'YOUR_WEB_CLIENT_ID',
@@ -253,6 +253,73 @@ declare namespace YouTube {
     interface GetHealthScoreParams {
         range?: string;
     }
+    /**
+     * Status of a single sync type
+     */
+    interface SyncTypeStatus {
+        /** Current sync status */
+        status: 'never_synced' | 'pending' | 'in_progress' | 'completed' | 'failed';
+        /**
+         * When the backend last fetched data from YouTube API.
+         * UI should store this value and compare on next call.
+         * If lastSyncAt is newer than stored → refetch data from API
+         */
+        lastSyncAt: string | null;
+        /** Last error message if sync failed */
+        lastError: string | null;
+        /** Number of consecutive failed attempts */
+        failedAttempts: number;
+        /** Whether data is older than the refresh interval (backend will auto-sync) */
+        isStale: boolean;
+        /** When the next automatic sync will run */
+        nextSyncAt: string | null;
+        /** Human-readable time until next sync (e.g., "6 hours") */
+        timeUntilNextSync: string;
+        /** Sync interval for this data type (e.g., "12 hours") */
+        interval: string;
+    }
+    /**
+     * Response from GET /v1/platforms/youtube/sync/status
+     *
+     * Use this endpoint to:
+     * 1. Check if any sync is stale (anyStale) - backend will auto-sync
+     * 2. Check if new data available (compare lastSyncAt with stored value)
+     * 3. Show sync status in UI settings/debug screen
+     *
+     * @example
+     * ```typescript
+     * const status = await client.youtube.getUnifiedSyncStatus();
+     *
+     * // Check if backend has newer data than our cache
+     * const storedLastSync = localStorage.get('videosLastSync');
+     * if (status.data.syncs.videos.lastSyncAt > storedLastSync) {
+     *   // Backend synced since our last fetch, refetch videos
+     *   const videos = await client.youtube.getVideos();
+     *   localStorage.set('videosLastSync', status.data.syncs.videos.lastSyncAt);
+     * }
+     * ```
+     */
+    interface UnifiedSyncStatusResponse {
+        /** Whether YouTube account is connected */
+        isConnected: boolean;
+        /** YouTube channel ID */
+        channelId: string | null;
+        /** YouTube channel name */
+        channelName: string | null;
+        /** Total videos stored in database */
+        totalVideos: number;
+        /** Sync status for each data type */
+        syncs: {
+            /** Channel info (subscribers, video count) */
+            channelInfo: SyncTypeStatus;
+            /** Videos list */
+            videos: SyncTypeStatus;
+            /** Channel analytics (daily metrics, demographics) */
+            channelAnalytics: SyncTypeStatus;
+            /** Video analytics (per-video metrics) */
+            videoAnalytics: SyncTypeStatus;
+        };
+    }
     /**
      * Response from GET /v1/platforms/youtube/analytics/channel/sync/status
      */
@@ -420,6 +487,109 @@ declare namespace Insights {
         youtube?: YouTube.Video[];
         instagram?: Instagram.Post[];
     }
+    /** Momentum status labels */
+    type MomentumStatusLabel = 'surging' | 'rising' | 'steady' | 'cooling' | 'dropping';
+    /** Momentum trend direction */
+    type MomentumTrend = 'accelerating' | 'holding' | 'decelerating';
+    /**
+     * Metric breakdown showing current vs previous period
+     */
+    interface MetricComparison {
+        /** Current period value */
+        current: number;
+        /** Previous period value */
+        previous: number;
+        /** Percentage change (-100 to +100+) */
+        change: number;
+    }
+    /**
+     * Momentum Status Response
+     *
+     * Provides a 0-100 score indicating channel momentum:
+     * - 50 = Steady (no change week over week)
+     * - 0 = Severe decline (-100% or worse)
+     * - 100 = Explosive growth (+100% or better)
+     *
+     * Status labels:
+     * - 80-100: Surging 🚀
+     * - 60-79: Rising 📈
+     * - 40-59: Steady ➡️
+     * - 20-39: Cooling 📉
+     * - 0-19: Dropping 🔻
+     */
+    interface MomentumStatusResponse {
+        /** Normalized score 0-100 (50 = no change) */
+        score: number;
+        /** Raw weighted average change before normalization */
+        rawChange: number;
+        /** Human-friendly status label */
+        status: MomentumStatusLabel;
+        /** Trend direction compared to previous period */
+        trend: MomentumTrend;
+        /** Previous period's score (null if first calculation) */
+        previousScore: number | null;
+        /** Time periods being compared */
+        period: {
+            current: {
+                start: string;
+                end: string;
+            };
+            previous: {
+                start: string;
+                end: string;
+            };
+        };
+        /** Breakdown of individual metrics */
+        breakdown: {
+            views: MetricComparison;
+            engagement: MetricComparison;
+            watchTime: MetricComparison;
+            subscribers: MetricComparison;
+        };
+        /** Weights used in calculation */
+        weights: {
+            views: number;
+            engagement: number;
+            watchTime: number;
+            subscribers: number;
+        };
+        /** Human-readable insight summary */
+        insight: string;
+        /** Cache metadata */
+        _meta?: {
+            fromCache: boolean;
+            refreshed?: boolean;
+            cacheValidFor: string;
+            algorithmVersion: string;
+        };
+    }
+    /**
+     * Single history point for momentum graphing
+     */
+    interface MomentumHistoryPoint {
+        /** Date (YYYY-MM-DD) */
+        date: string;
+        /** Momentum score at that time */
+        score: number;
+        /** Status label at that time */
+        status: MomentumStatusLabel;
+    }
+    /**
+     * Momentum history response for graphing
+     */
+    interface MomentumHistoryResponse {
+        /** Historical data points (oldest first) */
+        history: MomentumHistoryPoint[];
+        /** Number of points returned */
+        count: number;
+    }
+    /**
+     * Parameters for momentum history request
+     */
+    interface GetMomentumHistoryParams {
+        /** Max number of data points (default: 30, max: 90) */
+        limit?: number;
+    }
 }
 
 /**
@@ -621,6 +791,29 @@ declare class YouTubeModule {
         message: string;
         jobId?: string;
     }>;
+    /**
+     * Get unified sync status for all YouTube data types.
+     *
+     * Use this for:
+     * - Checking if UI cache needs refresh (compare lastSyncAt)
+     * - Showing sync status in settings/debug screens
+     * - Detecting if background sync is running
+     *
+     * GET /v1/platforms/youtube/sync/status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.youtube.getUnifiedSyncStatus();
+     *
+     * // Check if backend synced since our last fetch
+     * const storedLastSync = await AsyncStorage.getItem('videosLastSync');
+     * if (status.syncs.videos.lastSyncAt > storedLastSync) {
+     *   const videos = await client.youtube.getVideos();
+     *   await AsyncStorage.setItem('videosLastSync', status.syncs.videos.lastSyncAt);
+     * }
+     * ```
+     */
+    getUnifiedSyncStatus(): Promise<YouTube.UnifiedSyncStatusResponse>;
     /**
      * Get channel analytics sync status
      * GET /v1/platforms/youtube/analytics/channel/sync/status
@@ -745,6 +938,73 @@ declare class InsightsModule {
      * GET /v1/insights/trending
      */
     getTrending(): Promise<Insights.TrendingContent>;
+    /**
+     * Get YouTube channel momentum status
+     *
+     * Returns a 0-100 score indicating channel momentum:
+     * - 50 = Steady (no change week over week)
+     * - 0 = Severe decline
+     * - 100 = Explosive growth
+     *
+     * Results are cached for 12 hours. Use `refreshYouTubeMomentum()` to force recalculation.
+     *
+     * @example
+     * ```typescript
+     * const momentum = await client.insights.getYouTubeMomentum();
+     *
+     * console.log(`Score: ${momentum.score}/100`);
+     * console.log(`Status: ${momentum.status}`); // 'surging' | 'rising' | 'steady' | 'cooling' | 'dropping'
+     * console.log(`Trend: ${momentum.trend}`);   // 'accelerating' | 'holding' | 'decelerating'
+     * console.log(momentum.insight);              // Human-readable summary
+     *
+     * // Show breakdown
+     * console.log(`Views: ${momentum.breakdown.views.change}%`);
+     * console.log(`Engagement: ${momentum.breakdown.engagement.change}%`);
+     * ```
+     *
+     * GET /v1/insights/youtube/momentum
+     */
+    getYouTubeMomentum(): Promise<Insights.MomentumStatusResponse>;
+    /**
+     * Get YouTube momentum history for graphing
+     *
+     * Returns historical momentum scores, oldest first.
+     * Use this to plot momentum trends over time.
+     *
+     * @param params - Query parameters
+     * @param params.limit - Max data points (default: 30, max: 90)
+     *
+     * @example
+     * ```typescript
+     * const { history } = await client.insights.getYouTubeMomentumHistory({ limit: 30 });
+     *
+     * // Plot on a chart
+     * const chartData = history.map(point => ({
+     *   x: new Date(point.date),
+     *   y: point.score,
+     *   label: point.status
+     * }));
+     * ```
+     *
+     * GET /v1/insights/youtube/momentum/history
+     */
+    getYouTubeMomentumHistory(params?: Insights.GetMomentumHistoryParams): Promise<Insights.MomentumHistoryResponse>;
+    /**
+     * Force refresh YouTube momentum status (bypass cache)
+     *
+     * Use this after a sync completes to get the latest momentum score.
+     * Results are recalculated and cached for 12 hours.
+     *
+     * @example
+     * ```typescript
+     * // After videos sync completes
+     * const freshMomentum = await client.insights.refreshYouTubeMomentum();
+     * console.log('Updated score:', freshMomentum.score);
+     * ```
+     *
+     * POST /v1/insights/youtube/momentum/refresh
+     */
+    refreshYouTubeMomentum(): Promise<Insights.MomentumStatusResponse>;
 }
 
 /**
@@ -755,7 +1015,7 @@ declare class InsightsModule {
  *
  * @example
  * ```typescript
- * import { TrndUpSDK, YOUTUBE_SCOPES } from '@trndup/sdk';
+ * import { TrndUpSDK, YOUTUBE_SCOPES } from '@dracoonghost/trndup-sdk';
  * import auth from '@react-native-firebase/auth';
  * import { GoogleSignin } from '@react-native-google-signin/google-signin';
  *

package/dist/index.d.ts

@@ -10,7 +10,7 @@
  * @example
  * ```typescript
  * import { GoogleSignin } from '@react-native-google-signin/google-signin';
- * import { YOUTUBE_SCOPES } from '@trndup/sdk';
+ * import { YOUTUBE_SCOPES } from '@dracoonghost/trndup-sdk';
  *
  * GoogleSignin.configure({
  *   webClientId: 'YOUR_WEB_CLIENT_ID',
@@ -253,6 +253,73 @@ declare namespace YouTube {
     interface GetHealthScoreParams {
         range?: string;
     }
+    /**
+     * Status of a single sync type
+     */
+    interface SyncTypeStatus {
+        /** Current sync status */
+        status: 'never_synced' | 'pending' | 'in_progress' | 'completed' | 'failed';
+        /**
+         * When the backend last fetched data from YouTube API.
+         * UI should store this value and compare on next call.
+         * If lastSyncAt is newer than stored → refetch data from API
+         */
+        lastSyncAt: string | null;
+        /** Last error message if sync failed */
+        lastError: string | null;
+        /** Number of consecutive failed attempts */
+        failedAttempts: number;
+        /** Whether data is older than the refresh interval (backend will auto-sync) */
+        isStale: boolean;
+        /** When the next automatic sync will run */
+        nextSyncAt: string | null;
+        /** Human-readable time until next sync (e.g., "6 hours") */
+        timeUntilNextSync: string;
+        /** Sync interval for this data type (e.g., "12 hours") */
+        interval: string;
+    }
+    /**
+     * Response from GET /v1/platforms/youtube/sync/status
+     *
+     * Use this endpoint to:
+     * 1. Check if any sync is stale (anyStale) - backend will auto-sync
+     * 2. Check if new data available (compare lastSyncAt with stored value)
+     * 3. Show sync status in UI settings/debug screen
+     *
+     * @example
+     * ```typescript
+     * const status = await client.youtube.getUnifiedSyncStatus();
+     *
+     * // Check if backend has newer data than our cache
+     * const storedLastSync = localStorage.get('videosLastSync');
+     * if (status.data.syncs.videos.lastSyncAt > storedLastSync) {
+     *   // Backend synced since our last fetch, refetch videos
+     *   const videos = await client.youtube.getVideos();
+     *   localStorage.set('videosLastSync', status.data.syncs.videos.lastSyncAt);
+     * }
+     * ```
+     */
+    interface UnifiedSyncStatusResponse {
+        /** Whether YouTube account is connected */
+        isConnected: boolean;
+        /** YouTube channel ID */
+        channelId: string | null;
+        /** YouTube channel name */
+        channelName: string | null;
+        /** Total videos stored in database */
+        totalVideos: number;
+        /** Sync status for each data type */
+        syncs: {
+            /** Channel info (subscribers, video count) */
+            channelInfo: SyncTypeStatus;
+            /** Videos list */
+            videos: SyncTypeStatus;
+            /** Channel analytics (daily metrics, demographics) */
+            channelAnalytics: SyncTypeStatus;
+            /** Video analytics (per-video metrics) */
+            videoAnalytics: SyncTypeStatus;
+        };
+    }
     /**
      * Response from GET /v1/platforms/youtube/analytics/channel/sync/status
      */
@@ -420,6 +487,109 @@ declare namespace Insights {
         youtube?: YouTube.Video[];
         instagram?: Instagram.Post[];
     }
+    /** Momentum status labels */
+    type MomentumStatusLabel = 'surging' | 'rising' | 'steady' | 'cooling' | 'dropping';
+    /** Momentum trend direction */
+    type MomentumTrend = 'accelerating' | 'holding' | 'decelerating';
+    /**
+     * Metric breakdown showing current vs previous period
+     */
+    interface MetricComparison {
+        /** Current period value */
+        current: number;
+        /** Previous period value */
+        previous: number;
+        /** Percentage change (-100 to +100+) */
+        change: number;
+    }
+    /**
+     * Momentum Status Response
+     *
+     * Provides a 0-100 score indicating channel momentum:
+     * - 50 = Steady (no change week over week)
+     * - 0 = Severe decline (-100% or worse)
+     * - 100 = Explosive growth (+100% or better)
+     *
+     * Status labels:
+     * - 80-100: Surging 🚀
+     * - 60-79: Rising 📈
+     * - 40-59: Steady ➡️
+     * - 20-39: Cooling 📉
+     * - 0-19: Dropping 🔻
+     */
+    interface MomentumStatusResponse {
+        /** Normalized score 0-100 (50 = no change) */
+        score: number;
+        /** Raw weighted average change before normalization */
+        rawChange: number;
+        /** Human-friendly status label */
+        status: MomentumStatusLabel;
+        /** Trend direction compared to previous period */
+        trend: MomentumTrend;
+        /** Previous period's score (null if first calculation) */
+        previousScore: number | null;
+        /** Time periods being compared */
+        period: {
+            current: {
+                start: string;
+                end: string;
+            };
+            previous: {
+                start: string;
+                end: string;
+            };
+        };
+        /** Breakdown of individual metrics */
+        breakdown: {
+            views: MetricComparison;
+            engagement: MetricComparison;
+            watchTime: MetricComparison;
+            subscribers: MetricComparison;
+        };
+        /** Weights used in calculation */
+        weights: {
+            views: number;
+            engagement: number;
+            watchTime: number;
+            subscribers: number;
+        };
+        /** Human-readable insight summary */
+        insight: string;
+        /** Cache metadata */
+        _meta?: {
+            fromCache: boolean;
+            refreshed?: boolean;
+            cacheValidFor: string;
+            algorithmVersion: string;
+        };
+    }
+    /**
+     * Single history point for momentum graphing
+     */
+    interface MomentumHistoryPoint {
+        /** Date (YYYY-MM-DD) */
+        date: string;
+        /** Momentum score at that time */
+        score: number;
+        /** Status label at that time */
+        status: MomentumStatusLabel;
+    }
+    /**
+     * Momentum history response for graphing
+     */
+    interface MomentumHistoryResponse {
+        /** Historical data points (oldest first) */
+        history: MomentumHistoryPoint[];
+        /** Number of points returned */
+        count: number;
+    }
+    /**
+     * Parameters for momentum history request
+     */
+    interface GetMomentumHistoryParams {
+        /** Max number of data points (default: 30, max: 90) */
+        limit?: number;
+    }
 }
 
 /**
@@ -621,6 +791,29 @@ declare class YouTubeModule {
         message: string;
         jobId?: string;
     }>;
+    /**
+     * Get unified sync status for all YouTube data types.
+     *
+     * Use this for:
+     * - Checking if UI cache needs refresh (compare lastSyncAt)
+     * - Showing sync status in settings/debug screens
+     * - Detecting if background sync is running
+     *
+     * GET /v1/platforms/youtube/sync/status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.youtube.getUnifiedSyncStatus();
+     *
+     * // Check if backend synced since our last fetch
+     * const storedLastSync = await AsyncStorage.getItem('videosLastSync');
+     * if (status.syncs.videos.lastSyncAt > storedLastSync) {
+     *   const videos = await client.youtube.getVideos();
+     *   await AsyncStorage.setItem('videosLastSync', status.syncs.videos.lastSyncAt);
+     * }
+     * ```
+     */
+    getUnifiedSyncStatus(): Promise<YouTube.UnifiedSyncStatusResponse>;
     /**
      * Get channel analytics sync status
      * GET /v1/platforms/youtube/analytics/channel/sync/status
@@ -745,6 +938,73 @@ declare class InsightsModule {
      * GET /v1/insights/trending
      */
     getTrending(): Promise<Insights.TrendingContent>;
+    /**
+     * Get YouTube channel momentum status
+     *
+     * Returns a 0-100 score indicating channel momentum:
+     * - 50 = Steady (no change week over week)
+     * - 0 = Severe decline
+     * - 100 = Explosive growth
+     *
+     * Results are cached for 12 hours. Use `refreshYouTubeMomentum()` to force recalculation.
+     *
+     * @example
+     * ```typescript
+     * const momentum = await client.insights.getYouTubeMomentum();
+     *
+     * console.log(`Score: ${momentum.score}/100`);
+     * console.log(`Status: ${momentum.status}`); // 'surging' | 'rising' | 'steady' | 'cooling' | 'dropping'
+     * console.log(`Trend: ${momentum.trend}`);   // 'accelerating' | 'holding' | 'decelerating'
+     * console.log(momentum.insight);              // Human-readable summary
+     *
+     * // Show breakdown
+     * console.log(`Views: ${momentum.breakdown.views.change}%`);
+     * console.log(`Engagement: ${momentum.breakdown.engagement.change}%`);
+     * ```
+     *
+     * GET /v1/insights/youtube/momentum
+     */
+    getYouTubeMomentum(): Promise<Insights.MomentumStatusResponse>;
+    /**
+     * Get YouTube momentum history for graphing
+     *
+     * Returns historical momentum scores, oldest first.
+     * Use this to plot momentum trends over time.
+     *
+     * @param params - Query parameters
+     * @param params.limit - Max data points (default: 30, max: 90)
+     *
+     * @example
+     * ```typescript
+     * const { history } = await client.insights.getYouTubeMomentumHistory({ limit: 30 });
+     *
+     * // Plot on a chart
+     * const chartData = history.map(point => ({
+     *   x: new Date(point.date),
+     *   y: point.score,
+     *   label: point.status
+     * }));
+     * ```
+     *
+     * GET /v1/insights/youtube/momentum/history
+     */
+    getYouTubeMomentumHistory(params?: Insights.GetMomentumHistoryParams): Promise<Insights.MomentumHistoryResponse>;
+    /**
+     * Force refresh YouTube momentum status (bypass cache)
+     *
+     * Use this after a sync completes to get the latest momentum score.
+     * Results are recalculated and cached for 12 hours.
+     *
+     * @example
+     * ```typescript
+     * // After videos sync completes
+     * const freshMomentum = await client.insights.refreshYouTubeMomentum();
+     * console.log('Updated score:', freshMomentum.score);
+     * ```
+     *
+     * POST /v1/insights/youtube/momentum/refresh
+     */
+    refreshYouTubeMomentum(): Promise<Insights.MomentumStatusResponse>;
 }
 
 /**
@@ -755,7 +1015,7 @@ declare class InsightsModule {
  *
  * @example
  * ```typescript
- * import { TrndUpSDK, YOUTUBE_SCOPES } from '@trndup/sdk';
+ * import { TrndUpSDK, YOUTUBE_SCOPES } from '@dracoonghost/trndup-sdk';
  * import auth from '@react-native-firebase/auth';
  * import { GoogleSignin } from '@react-native-google-signin/google-signin';
  *