ugcinc 2.7.0 → 2.8.1

package/README.md

@@ -68,8 +68,11 @@ For complete API documentation, including all endpoints, parameters, and example
 - Delete tasks
 
 ### Statistics
-- Get account statistics
-- Get post statistics
+- Get account statistics (latest or date range)
+- Get post statistics (latest or date range)
+- Get daily aggregated stats (for charts/dashboards)
+- Get top accounts by metric (followers, views, likes, etc.)
+- Get top posts by metric (views, likes, comments, etc.)
 - Refresh statistics
 
 ### Organization
@@ -429,6 +432,58 @@ if (statusResponse.ok && statusResponse.data.status === 'completed') {
 }
 ```
 
+**Statistics:**
+```typescript
+// Get latest stats (one record per account/post)
+const latestAccountStats = await client.stats.getAccountStats();
+const latestPostStats = await client.stats.getPostStats();
+
+// Get stats for a date range
+const rangeStats = await client.stats.getAccountStats({
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+  tag: 'fitness'
+});
+
+// Get daily aggregated stats for charts
+const dailyStats = await client.stats.getDailyAggregated({
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+  org_group: 'group1'
+});
+
+if (dailyStats.ok) {
+  dailyStats.data.forEach(day => {
+    console.log(`${day.date}: +${day.followers} followers, +${day.views} views`);
+  });
+}
+
+// Get top 5 accounts by followers
+const topAccounts = await client.stats.getTopAccounts({
+  metric: 'followers',
+  limit: 5,
+  tag: 'fitness'
+});
+
+// Get top 10 posts by views
+const topPosts = await client.stats.getTopPosts({
+  metric: 'views',
+  limit: 10
+});
+
+// Refresh stats (fetch live data from platforms)
+// Can only be called once per hour per organization
+const refreshResult = await client.stats.refresh({
+  org_group: 'optional-group-filter'
+});
+
+if (refreshResult.ok) {
+  console.log(`Refreshed ${refreshResult.data.accounts_refreshed} accounts`);
+  console.log(`New account stats: ${refreshResult.data.account_stats.length}`);
+  console.log(`New post stats: ${refreshResult.data.post_stats.length}`);
+}
+```
+
 ## TypeScript Support
 
 This package is written in TypeScript and provides full type definitions:

package/dist/stats.d.ts

@@ -1,17 +1,130 @@
 import { BaseClient } from './base';
-import type { AccountStat, PostStat, GetAccountStatsParams, GetPostStatsParams, RefreshStatsParams, RefreshStatsResponse, ApiResponse } from './types';
+import type { AccountStat, PostStat, GetAccountStatsParams, GetPostStatsParams, RefreshStatsParams, RefreshStatsResponse, DailyAggregatedStat, GetDailyAggregatedStatsParams, TopAccount, GetTopAccountsParams, TopPost, GetTopPostsParams, ApiResponse } from './types';
 /**
  * Client for managing statistics
  */
 export declare class StatsClient extends BaseClient {
     /**
      * Get account statistics
+     *
+     * **Behavior:**
+     * - If `startDate` and `endDate` are NOT provided: Returns the latest stat per account (one record per account)
+     * - If `startDate` or `endDate` is provided: Returns all stats within the date range
+     *
+     * @param params - Optional filter parameters
+     * @returns Array of account statistics
+     *
+     * @example
+     * ```typescript
+     * // Get latest stats for all accounts
+     * const latest = await client.stats.getAccountStats();
+     *
+     * // Get stats for a date range
+     * const range = await client.stats.getAccountStats({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31'
+     * });
+     * ```
      */
     getAccountStats(params?: GetAccountStatsParams): Promise<ApiResponse<AccountStat[]>>;
     /**
      * Get post statistics
+     *
+     * **Behavior:**
+     * - If `startDate` and `endDate` are NOT provided: Returns the latest stat per post (one record per post)
+     * - If `startDate` or `endDate` is provided: Returns all stats within the date range
+     *
+     * @param params - Optional filter parameters
+     * @returns Array of post statistics
+     *
+     * @example
+     * ```typescript
+     * // Get latest stats for all posts
+     * const latest = await client.stats.getPostStats();
+     *
+     * // Get stats for a date range
+     * const range = await client.stats.getPostStats({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31'
+     * });
+     * ```
      */
     getPostStats(params?: GetPostStatsParams): Promise<ApiResponse<PostStat[]>>;
+    /**
+     * Get daily aggregated statistics for dashboard charts
+     *
+     * Returns one record per day with total changes across all filtered accounts.
+     * Perfect for rendering time-series charts showing growth over time.
+     *
+     * @param params - Date range and filter parameters (startDate and endDate required)
+     * @returns Array of daily aggregated statistics
+     *
+     * @example
+     * ```typescript
+     * const dailyStats = await client.stats.getDailyAggregated({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31',
+     *   tag: 'fitness'
+     * });
+     *
+     * // Use for charts
+     * dailyStats.data.forEach(day => {
+     *   console.log(`${day.date}: +${day.followers} followers, +${day.views} views`);
+     * });
+     * ```
+     */
+    getDailyAggregated(params: GetDailyAggregatedStatsParams): Promise<ApiResponse<DailyAggregatedStat[]>>;
+    /**
+     * Get top N accounts by a specific metric
+     *
+     * Returns the highest-performing accounts based on the selected metric.
+     * Uses the latest stats for each account.
+     *
+     * @param params - Metric and filter parameters
+     * @returns Array of top accounts sorted by the metric
+     *
+     * @example
+     * ```typescript
+     * // Get top 5 accounts by followers
+     * const topByFollowers = await client.stats.getTopAccounts({
+     *   metric: 'followers',
+     *   limit: 5
+     * });
+     *
+     * // Get top 10 accounts by views in a specific tag
+     * const topByViews = await client.stats.getTopAccounts({
+     *   metric: 'views',
+     *   limit: 10,
+     *   tag: 'fitness'
+     * });
+     * ```
+     */
+    getTopAccounts(params: GetTopAccountsParams): Promise<ApiResponse<TopAccount[]>>;
+    /**
+     * Get top N posts by a specific metric
+     *
+     * Returns the highest-performing posts based on the selected metric.
+     * Uses the latest stats for each post.
+     *
+     * @param params - Metric and filter parameters
+     * @returns Array of top posts sorted by the metric
+     *
+     * @example
+     * ```typescript
+     * // Get top 5 posts by views
+     * const topByViews = await client.stats.getTopPosts({
+     *   metric: 'views',
+     *   limit: 5
+     * });
+     *
+     * // Get top 10 posts by likes
+     * const topByLikes = await client.stats.getTopPosts({
+     *   metric: 'likes',
+     *   limit: 10
+     * });
+     * ```
+     */
+    getTopPosts(params: GetTopPostsParams): Promise<ApiResponse<TopPost[]>>;
     /**
      * Refresh statistics for all accounts in the organization (optionally filtered by org_group)
      * Fetches live data from TikTok/Instagram API and creates new stat records

package/dist/stats.js

@@ -8,16 +8,135 @@ const base_1 = require("./base");
 class StatsClient extends base_1.BaseClient {
     /**
      * Get account statistics
+     *
+     * **Behavior:**
+     * - If `startDate` and `endDate` are NOT provided: Returns the latest stat per account (one record per account)
+     * - If `startDate` or `endDate` is provided: Returns all stats within the date range
+     *
+     * @param params - Optional filter parameters
+     * @returns Array of account statistics
+     *
+     * @example
+     * ```typescript
+     * // Get latest stats for all accounts
+     * const latest = await client.stats.getAccountStats();
+     *
+     * // Get stats for a date range
+     * const range = await client.stats.getAccountStats({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31'
+     * });
+     * ```
      */
     async getAccountStats(params) {
         return this.post('/stats/accounts', params ?? {});
     }
     /**
      * Get post statistics
+     *
+     * **Behavior:**
+     * - If `startDate` and `endDate` are NOT provided: Returns the latest stat per post (one record per post)
+     * - If `startDate` or `endDate` is provided: Returns all stats within the date range
+     *
+     * @param params - Optional filter parameters
+     * @returns Array of post statistics
+     *
+     * @example
+     * ```typescript
+     * // Get latest stats for all posts
+     * const latest = await client.stats.getPostStats();
+     *
+     * // Get stats for a date range
+     * const range = await client.stats.getPostStats({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31'
+     * });
+     * ```
      */
     async getPostStats(params) {
         return this.post('/stats/posts', params ?? {});
     }
+    /**
+     * Get daily aggregated statistics for dashboard charts
+     *
+     * Returns one record per day with total changes across all filtered accounts.
+     * Perfect for rendering time-series charts showing growth over time.
+     *
+     * @param params - Date range and filter parameters (startDate and endDate required)
+     * @returns Array of daily aggregated statistics
+     *
+     * @example
+     * ```typescript
+     * const dailyStats = await client.stats.getDailyAggregated({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31',
+     *   tag: 'fitness'
+     * });
+     *
+     * // Use for charts
+     * dailyStats.data.forEach(day => {
+     *   console.log(`${day.date}: +${day.followers} followers, +${day.views} views`);
+     * });
+     * ```
+     */
+    async getDailyAggregated(params) {
+        return this.post('/stats/aggregated/daily', params);
+    }
+    /**
+     * Get top N accounts by a specific metric
+     *
+     * Returns the highest-performing accounts based on the selected metric.
+     * Uses the latest stats for each account.
+     *
+     * @param params - Metric and filter parameters
+     * @returns Array of top accounts sorted by the metric
+     *
+     * @example
+     * ```typescript
+     * // Get top 5 accounts by followers
+     * const topByFollowers = await client.stats.getTopAccounts({
+     *   metric: 'followers',
+     *   limit: 5
+     * });
+     *
+     * // Get top 10 accounts by views in a specific tag
+     * const topByViews = await client.stats.getTopAccounts({
+     *   metric: 'views',
+     *   limit: 10,
+     *   tag: 'fitness'
+     * });
+     * ```
+     */
+    async getTopAccounts(params) {
+        return this.post('/stats/aggregated/top-accounts', params);
+    }
+    /**
+     * Get top N posts by a specific metric
+     *
+     * Returns the highest-performing posts based on the selected metric.
+     * Uses the latest stats for each post.
+     *
+     * @param params - Metric and filter parameters
+     * @returns Array of top posts sorted by the metric
+     *
+     * @example
+     * ```typescript
+     * // Get top 5 posts by views
+     * const topByViews = await client.stats.getTopPosts({
+     *   metric: 'views',
+     *   limit: 5
+     * });
+     *
+     * // Get top 10 posts by likes
+     * const topByLikes = await client.stats.getTopPosts({
+     *   metric: 'likes',
+     *   limit: 10
+     * });
+     * ```
+     */
+    async getTopPosts(params) {
+        return this.post('/stats/aggregated/top-posts', params);
+    }
     /**
      * Refresh statistics for all accounts in the organization (optionally filtered by org_group)
      * Fetches live data from TikTok/Instagram API and creates new stat records

package/dist/types.d.ts

@@ -219,6 +219,61 @@ export interface RefreshStatsResponse {
     post_stats_count: number;
     errors?: RefreshStatsError[];
 }
+export interface DailyAggregatedStat {
+    date: Date | string;
+    followers: number;
+    following: number;
+    views: number;
+    likes: number;
+}
+export interface GetDailyAggregatedStatsParams {
+    startDate: string;
+    endDate: string;
+    accountIds?: string[];
+    tag?: string;
+    org_group?: string;
+    user_group?: string;
+}
+export interface TopAccount {
+    account_id: string;
+    username: string | null;
+    nick_name: string | null;
+    pfp_url: string | null;
+    type: string;
+    tag: string | null;
+    followers: number | null;
+    following: number | null;
+    views: number | null;
+    likes: number | null;
+    created_at: string;
+}
+export interface GetTopAccountsParams {
+    metric: 'followers' | 'following' | 'views' | 'likes';
+    limit?: number;
+    accountIds?: string[];
+    tag?: string;
+    org_group?: string;
+    user_group?: string;
+}
+export interface TopPost {
+    post_id: string;
+    account_id: string;
+    caption: string | null;
+    media_urls: string[] | null;
+    type: string;
+    social_id: string | null;
+    views: number | null;
+    likes: number | null;
+    comments: number | null;
+    shares: number | null;
+    saves: number | null;
+    created_at: string;
+}
+export interface GetTopPostsParams {
+    metric: 'views' | 'likes' | 'comments' | 'shares' | 'saves';
+    limit?: number;
+    postIds?: string[];
+}
 /**
  * Organization and API Key types
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugcinc",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",