ugcinc 1.0.3 → 1.0.5

package/README.md

@@ -66,6 +66,24 @@ if (response.ok) {
 }
 ```
 
+#### Refresh Account Statistics
+
+Fetch live statistics from TikTok/Instagram API and create new stat records.
+
+```typescript
+const response = await client.accounts.refreshStats({
+  accountIds: ['account-id-1', 'account-id-2'],
+  tag: 'influencer'
+});
+
+if (response.ok) {
+  console.log(`Refreshed stats for ${response.data.length} accounts`);
+  response.data.forEach(stat => {
+    console.log(`Account ${stat.account_id}: ${stat.followers} followers`);
+  });
+}
+```
+
 #### Get Account Status
 
 Get the status of tasks for a specific account.
@@ -200,6 +218,23 @@ if (response.ok) {
 }
 ```
 
+#### Refresh Post Statistics
+
+Fetch live statistics from TikTok/Instagram API and create new stat records.
+
+```typescript
+const response = await client.posts.refreshStats({
+  postIds: ['post-id-1', 'post-id-2']
+});
+
+if (response.ok) {
+  console.log(`Refreshed stats for ${response.data.length} posts`);
+  response.data.forEach(stat => {
+    console.log(`Post ${stat.post_id}: ${stat.views} views, ${stat.likes} likes`);
+  });
+}
+```
+
 #### Get Post Status
 
 Get the status of a specific post.
@@ -424,6 +459,49 @@ const response = await client.accounts.getStats({
 
 ---
 
+#### `client.accounts.refreshStats(params?)`
+
+Refresh account statistics by fetching live data from TikTok/Instagram API.
+
+**Endpoint:** `POST /accounts/stats/refresh`
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `accountIds` | `string[]` | No | Array of account IDs to refresh stats for |
+| `tag` | `string` | No | Filter by tag |
+| `org_group` | `string` | No | Filter by organization group |
+| `user_group` | `string` | No | Filter by user group |
+
+**Returns:** `ApiResponse<AccountStat[]>`
+
+Returns an array of newly created AccountStat objects with live data from TikTok or Instagram. This endpoint fetches fresh statistics directly from the platform APIs and creates new stat records in the database. Use this when you need up-to-date metrics instead of historical data. The API automatically determines which platform to query based on the account type.
+
+**Key Differences from `getStats()`:**
+- `refreshStats()` fetches **live data** from TikTok/Instagram API and creates new records
+- `getStats()` retrieves **historical data** from your database
+
+**Example:**
+
+```typescript
+const response = await client.accounts.refreshStats({
+  accountIds: ['account-1', 'account-2'],
+  tag: 'influencer'
+});
+
+if (response.ok) {
+  console.log(`Successfully refreshed ${response.data.length} accounts`);
+  response.data.forEach(stat => {
+    console.log(`Account ${stat.account_id}:`);
+    console.log(`  Followers: ${stat.followers}`);
+    console.log(`  Views: ${stat.views}`);
+  });
+}
+```
+
+---
+
 #### `client.accounts.getStatus(params)`
 
 Get account status and pending tasks.
@@ -609,7 +687,7 @@ Returns an array of Post objects (videos and slideshows) for the specified accou
   account_id: string;      // Account that posted this
   type: 'video' | 'slideshow';  // Post type
   status: string;          // Current post status
-  post_url: string | null;      // URL to the live post
+  social_id: string | null;     // Platform post ID (TikTok video ID or Instagram reel code)
   caption: string | null;       // Post caption/description
   media_urls: string[] | null;  // URLs to media files
   music_post_id: string | null; // Associated music/audio ID
@@ -622,7 +700,7 @@ Returns an array of Post objects (videos and slideshows) for the specified accou
 | `account_id` | `string` | ID of the account that created this post |
 | `type` | `'video' \| 'slideshow'` | Type of post content |
 | `status` | `string` | Current status: `'scheduled'`, `'pending'`, `'complete'`, or `'failed'` |
-| `post_url` | `string \| null` | URL to the live post on the platform (available after posting) |
+| `social_id` | `string \| null` | Platform-specific post ID (TikTok video ID or Instagram reel code, available after posting) |
 | `caption` | `string \| null` | Post caption/description text (max 500 characters) |
 | `media_urls` | `string[] \| null` | Array of URLs to video/image files used in the post |
 | `music_post_id` | `string \| null` | ID of the music/audio track used in the post |
@@ -775,6 +853,52 @@ if (response.ok) {
 
 ---
 
+#### `client.posts.refreshStats(params?)`
+
+Refresh post statistics by fetching live data from TikTok/Instagram API.
+
+**Endpoint:** `POST /post/stats/refresh`
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `postIds` | `string[]` | No | Array of post IDs to refresh stats for |
+
+**Returns:** `ApiResponse<PostStat[]>`
+
+Returns an array of newly created PostStat objects with live data from TikTok or Instagram. This endpoint fetches fresh statistics directly from the platform APIs and creates new stat records in the database. Use this when you need up-to-date engagement metrics instead of historical data. The API automatically determines which platform to query based on the account type.
+
+**Key Differences from `getStats()`:**
+- `refreshStats()` fetches **live data** from TikTok/Instagram API and creates new records
+- `getStats()` retrieves **historical data** from your database
+
+**Important:** Posts must have a valid `social_id` (TikTok video ID or Instagram reel code) to refresh statistics. The endpoint uses this ID to fetch live metrics from the platform.
+
+**Example:**
+
+```typescript
+const response = await client.posts.refreshStats({
+  postIds: ['post-1', 'post-2', 'post-3']
+});
+
+if (response.ok) {
+  console.log(`Successfully refreshed ${response.data.length} posts`);
+  response.data.forEach(stat => {
+    console.log(`Post ${stat.post_id}:`);
+    console.log(`  Views: ${stat.views}`);
+    console.log(`  Likes: ${stat.likes}`);
+    console.log(`  Comments: ${stat.comments}`);
+    console.log(`  Engagement Rate: ${((stat.likes ?? 0) / (stat.views ?? 1) * 100).toFixed(2)}%`);
+  });
+}
+
+// Refresh all posts (no filters)
+const allPostsResponse = await client.posts.refreshStats();
+```
+
+---
+
 #### `client.posts.getStatus(params)`
 
 Get the status of a specific post.

package/dist/accounts.d.ts

@@ -1,5 +1,5 @@
 import { BaseClient } from './base';
-import type { Account, AccountStat, AccountTask, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, UpdateAccountInfoParams, ApiResponse } from './types';
+import type { Account, AccountStat, AccountTask, GetAccountsParams, GetAccountStatsParams, RefreshAccountStatsParams, GetAccountStatusParams, UpdateAccountInfoParams, ApiResponse } from './types';
 /**
  * Client for managing accounts
  */
@@ -12,6 +12,10 @@ export declare class AccountsClient extends BaseClient {
      * Get account statistics
      */
     getStats(params?: GetAccountStatsParams): Promise<ApiResponse<AccountStat[]>>;
+    /**
+     * Refresh account statistics from TikTok/Instagram API
+     */
+    refreshStats(params?: RefreshAccountStatsParams): Promise<ApiResponse<AccountStat[]>>;
     /**
      * Get account status (tasks)
      */

package/dist/accounts.js

@@ -18,6 +18,12 @@ class AccountsClient extends base_1.BaseClient {
     async getStats(params) {
         return this.post('/accounts/stats', params ?? {});
     }
+    /**
+     * Refresh account statistics from TikTok/Instagram API
+     */
+    async refreshStats(params) {
+        return this.post('/accounts/stats/refresh', params ?? {});
+    }
     /**
      * Get account status (tasks)
      */

package/dist/posts.d.ts

@@ -1,5 +1,5 @@
 import { BaseClient } from './base';
-import type { Post, PostStat, GetPostsParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, ApiResponse } from './types';
+import type { Post, PostStat, GetPostsParams, CreateSlideshowParams, GetPostStatsParams, RefreshPostStatsParams, GetPostStatusParams, CreateVideoParams, ApiResponse } from './types';
 /**
  * Client for managing posts
  */
@@ -16,6 +16,10 @@ export declare class PostsClient extends BaseClient {
      * Get post statistics
      */
     getStats(params?: GetPostStatsParams): Promise<ApiResponse<PostStat[]>>;
+    /**
+     * Refresh post statistics from TikTok/Instagram API
+     */
+    refreshStats(params?: RefreshPostStatsParams): Promise<ApiResponse<PostStat[]>>;
     /**
      * Get post status
      */

package/dist/posts.js

@@ -24,6 +24,12 @@ class PostsClient extends base_1.BaseClient {
     async getStats(params) {
         return this.post('/post/stats', params ?? {});
     }
+    /**
+     * Refresh post statistics from TikTok/Instagram API
+     */
+    async refreshStats(params) {
+        return this.post('/post/stats/refresh', params ?? {});
+    }
     /**
      * Get post status
      */

package/dist/types.d.ts

@@ -75,7 +75,7 @@ export interface Post {
     account_id: string;
     type: PostType;
     status: string;
-    post_url: string | null;
+    social_id: string | null;
     caption: string | null;
     media_urls: string[] | null;
     music_post_id: string | null;
@@ -106,6 +106,12 @@ export interface GetAccountStatsParams {
     org_group?: string;
     user_group?: string;
 }
+export interface RefreshAccountStatsParams {
+    accountIds?: string[];
+    tag?: string;
+    org_group?: string;
+    user_group?: string;
+}
 export interface GetAccountStatusParams {
     accountId: string;
     includeCompleted?: boolean;
@@ -142,6 +148,9 @@ export interface GetPostStatsParams {
     startDate?: string;
     endDate?: string;
 }
+export interface RefreshPostStatsParams {
+    postIds?: string[];
+}
 export interface GetPostStatusParams {
     postId: string;
 }

package/package.json

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