ugcinc 1.0.3 → 1.0.4

package/README.md

@@ -66,6 +66,24 @@ if (response.ok) {
 }
 ```
 
+#### Refresh Account Statistics
+
+Fetch live statistics from TikTok 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 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 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. This endpoint fetches fresh statistics directly from the TikTok API and creates new stat records in the database. Use this when you need up-to-date metrics instead of historical data.
+
+**Key Differences from `getStats()`:**
+- `refreshStats()` fetches **live data** from TikTok 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.
@@ -775,6 +853,52 @@ if (response.ok) {
 
 ---
 
+#### `client.posts.refreshStats(params?)`
+
+Refresh post statistics by fetching live data from TikTok 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. This endpoint fetches fresh statistics directly from the TikTok API and creates new stat records in the database. Use this when you need up-to-date engagement metrics instead of historical data.
+
+**Key Differences from `getStats()`:**
+- `refreshStats()` fetches **live data** from TikTok API and creates new records
+- `getStats()` retrieves **historical data** from your database
+
+**Important:** Posts must have a valid `post_url` to refresh statistics. The endpoint extracts the TikTok post ID from the URL to fetch live metrics.
+
+**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 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 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 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 API
+     */
+    async refreshStats(params) {
+        return this.post('/post/stats/refresh', params ?? {});
+    }
     /**
      * Get post status
      */

package/dist/types.d.ts

@@ -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.4",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",