@dracoonghost/trndup-sdk 1.3.13 → 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',
@@ -297,11 +297,6 @@ declare namespace YouTube {
      *   const videos = await client.youtube.getVideos();
      *   localStorage.set('videosLastSync', status.data.syncs.videos.lastSyncAt);
      * }
-     *
-     * // Show user that refresh is happening
-     * if (status.data.summary.anyInProgress) {
-     *   showRefreshIndicator();
-     * }
      * ```
      */
     interface UnifiedSyncStatusResponse {
@@ -324,17 +319,6 @@ declare namespace YouTube {
             /** Video analytics (per-video metrics) */
             videoAnalytics: SyncTypeStatus;
         };
-        /** Summary flags for quick checks */
-        summary: {
-            /** All sync types completed at least once with data */
-            allSynced: boolean;
-            /** At least one sync type is older than its refresh interval */
-            anyStale: boolean;
-            /** At least one sync type failed */
-            anyFailed: boolean;
-            /** At least one sync is currently in progress */
-            anyInProgress: boolean;
-        };
     }
     /**
      * Response from GET /v1/platforms/youtube/analytics/channel/sync/status
@@ -503,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;
+    }
 }
 
 /**
@@ -851,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>;
 }
 
 /**
@@ -861,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',
@@ -297,11 +297,6 @@ declare namespace YouTube {
      *   const videos = await client.youtube.getVideos();
      *   localStorage.set('videosLastSync', status.data.syncs.videos.lastSyncAt);
      * }
-     *
-     * // Show user that refresh is happening
-     * if (status.data.summary.anyInProgress) {
-     *   showRefreshIndicator();
-     * }
      * ```
      */
     interface UnifiedSyncStatusResponse {
@@ -324,17 +319,6 @@ declare namespace YouTube {
             /** Video analytics (per-video metrics) */
             videoAnalytics: SyncTypeStatus;
         };
-        /** Summary flags for quick checks */
-        summary: {
-            /** All sync types completed at least once with data */
-            allSynced: boolean;
-            /** At least one sync type is older than its refresh interval */
-            anyStale: boolean;
-            /** At least one sync type failed */
-            anyFailed: boolean;
-            /** At least one sync is currently in progress */
-            anyInProgress: boolean;
-        };
     }
     /**
      * Response from GET /v1/platforms/youtube/analytics/channel/sync/status
@@ -503,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;
+    }
 }
 
 /**
@@ -851,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>;
 }
 
 /**
@@ -861,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.js

@@ -534,6 +534,88 @@ var InsightsModule = class {
   async getTrending() {
     return this.client.get("/v1/insights/trending");
   }
+  // =========================================================================
+  // YOUTUBE MOMENTUM
+  // =========================================================================
+  /**
+   * 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
+   */
+  async getYouTubeMomentum() {
+    return this.client.get("/v1/insights/youtube/momentum");
+  }
+  /**
+   * 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
+   */
+  async getYouTubeMomentumHistory(params) {
+    const query = params?.limit ? `?limit=${params.limit}` : "";
+    return this.client.get(
+      `/v1/insights/youtube/momentum/history${query}`
+    );
+  }
+  /**
+   * 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
+   */
+  async refreshYouTubeMomentum() {
+    return this.client.post(
+      "/v1/insights/youtube/momentum/refresh",
+      {}
+    );
+  }
 };
 
 // types.ts