ugcinc 1.0.6 → 1.0.9

package/README.md

@@ -5,16 +5,10 @@ Official TypeScript/JavaScript client for the UGC Inc API.
 ## Installation
 
 ```bash
-npm i ugcinc
+npm install ugcinc
 ```
 
-## Getting Started
-
-### 1. Get Your API Key
-
-Get your API key at **https://ugc.inc**. You'll need this to authenticate all API requests.
-
-### 2. Initialize the Client
+## Quick Start
 
 ```typescript
 import { UGCClient } from 'ugcinc';
@@ -22,1018 +16,39 @@ import { UGCClient } from 'ugcinc';
 const client = new UGCClient({
   apiKey: 'your-api-key-here'
 });
-```
-
-**Important:** Keep your API key secure! Never commit it to version control or expose it in client-side code.
-
-## API Documentation
-
-### Accounts
-
-The `accounts` object provides methods for managing accounts.
-
-#### Get Accounts
-
-Retrieve accounts with optional filters.
-
-```typescript
-const response = await client.accounts.getAccounts({
-  tag: 'influencer',
-  org_group: 'group1',
-  user_group: 'users1'
-});
-
-if (response.ok) {
-  console.log(response.data); // Account[]
-}
-```
-
-#### Get Account Statistics
-
-Get statistics for accounts.
-
-```typescript
-const response = await client.accounts.getStats({
-  accountIds: ['account-id-1', 'account-id-2'],
-  startDate: '2024-01-01',
-  endDate: '2024-12-31'
-});
-
-if (response.ok) {
-  response.data.forEach(stat => {
-    console.log(`Account ${stat.account_id}: ${stat.followers} followers`);
-  });
-}
-```
-
-#### 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.
-
-```typescript
-const response = await client.accounts.getStatus({
-  accountId: 'account-id',
-  includeCompleted: false
-});
-
-if (response.ok) {
-  console.log(response.data); // AccountTask[]
-}
-```
-
-#### Update Account Info
-
-Update account metadata (tag, org_group, user_group).
-
-```typescript
-const response = await client.accounts.updateInfo({
-  accountId: 'account-id',
-  tag: 'influencer',
-  org_group: 'group1',
-  user_group: 'users1'
-});
-
-if (response.ok) {
-  console.log(response.data.message);
-  console.log(response.data.account); // Updated account
-}
-```
-
-#### Update Account Social Profile
-
-Update account social profile information (avatar, nickname, bio).
-
-**Important:** Nicknames can only be updated once every 7 days.
-
-```typescript
-const response = await client.accounts.updateSocial({
-  accountId: 'account-id',
-  nickName: 'New Name',
-  bio: 'New bio text',
-  avatarUrl: 'https://example.com/avatar.jpg'
-});
-
-if (response.ok) {
-  console.log(response.data.message);
-} else {
-  // Error response includes when nickname can be updated again
-  console.error(response.message);
-}
-```
-
-### Tasks
-
-The `tasks` object provides methods for managing tasks.
-
-#### Get Tasks
-
-Retrieve tasks with optional filters.
-
-```typescript
-const response = await client.tasks.getTasks({
-  accountIds: ['account-id-1'],
-  startDate: '2024-01-01',
-  endDate: '2024-12-31',
-  taskType: 'edit_profile'
-});
-
-if (response.ok) {
-  console.log(response.data); // Task[]
-}
-```
-
-### Posts
-
-The `posts` object provides methods for managing posts.
-
-#### Get Posts
-
-Retrieve posts with optional filters.
-
-```typescript
-const response = await client.posts.getPosts({
-  accountIds: ['account-id-1'],
-  startDate: '2024-01-01',
-  endDate: '2024-12-31'
-});
-
-if (response.ok) {
-  console.log(response.data); // Post[]
-}
-```
-
-#### Create Slideshow
-
-Create a slideshow post.
-
-```typescript
-const response = await client.posts.createSlideshow({
-  accountId: 'account-id',
-  imageUrls: [
-    'https://example.com/image1.jpg',
-    'https://example.com/image2.jpg',
-    'https://example.com/image3.jpg'
-  ],
-  caption: 'Check out this slideshow!',
-  musicPostId: 'music-id',
-  postTime: '2024-12-31T12:00:00Z',
-  strict: true
-});
-
-if (response.ok) {
-  console.log(`Post created: ${response.data.id}`);
-}
-```
-
-#### Create Video
-
-Create a video post.
-
-```typescript
-const response = await client.posts.createVideo({
-  accountId: 'account-id',
-  videoUrl: 'https://example.com/video.mp4',
-  caption: 'My awesome video!',
-  musicPostId: 'music-id',
-  postTime: '2024-12-31T12:00:00Z',
-  strict: true
-});
-
-if (response.ok) {
-  console.log(`Post created: ${response.data.id}`);
-}
-```
-
-#### Get Post Statistics
 
-Get statistics for posts.
-
-```typescript
-const response = await client.posts.getStats({
-  postIds: ['post-id-1', 'post-id-2'],
-  startDate: '2024-01-01',
-  endDate: '2024-12-31'
-});
-
-if (response.ok) {
-  response.data.forEach(stat => {
-    console.log(`Post ${stat.post_id}: ${stat.views} views, ${stat.likes} likes`);
-  });
-}
-```
-
-#### 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.
-
-```typescript
-const response = await client.posts.getStatus({
-  postId: 'post-id'
-});
-
-if (response.ok) {
-  console.log(`Post status: ${response.data.status}`);
-}
-```
-
-## Response Handling
-
-All API methods return a response object with the following structure:
-
-### Success Response
-
-```typescript
-{
-  ok: true,
-  code: 200,
-  message: "Success",
-  data: T // The actual response data
-}
-```
-
-### Error Response
-
-```typescript
-{
-  ok: false,
-  code: number, // HTTP status code
-  message: string // Error message
-}
-```
-
-### Type-Safe Response Handling
-
-```typescript
+// Example: Get accounts
 const response = await client.accounts.getAccounts();
 
 if (response.ok) {
-  // TypeScript knows response.data is Account[]
-  response.data.forEach(account => {
-    console.log(account.username);
-  });
-} else {
-  // TypeScript knows response has code and message
-  console.error(`Error ${response.code}: ${response.message}`);
-}
-```
-
-## TypeScript Support
-
-This package is written in TypeScript and provides full type definitions. All types are exported for your convenience:
-
-```typescript
-import type { 
-  Account, 
-  Post, 
-  Task,
-  CreateVideoParams,
-  ApiResponse 
-} from 'ugcinc';
-```
-
-## Error Handling
-
-```typescript
-try {
-  const response = await client.accounts.getAccounts();
-  
-  if (!response.ok) {
-    console.error(`API Error: ${response.message}`);
-    return;
-  }
-  
-  // Handle success
   console.log(response.data);
-} catch (error) {
-  console.error('Network or parsing error:', error);
-}
-```
-
-## Environment Variables
-
-For production use, store your API key securely using environment variables:
-
-```bash
-# .env file
-UGC_API_KEY=your-api-key-here
-```
-
-Then in your code:
-
-```typescript
-import { UGCClient } from 'ugcinc';
-
-const client = new UGCClient({
-  apiKey: process.env.UGC_API_KEY!
-});
-```
-
----
-
-## Complete API Reference
-
-### Accounts API
-
-#### `client.accounts.getAccounts(params?)`
-
-Retrieve accounts with optional filters.
-
-**Endpoint:** `POST /accounts`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tag` | `string` | No | Filter by tag |
-| `org_group` | `string` | No | Filter by organization group |
-| `user_group` | `string` | No | Filter by user group |
-
-**Returns:** `ApiResponse<Account[]>`
-
-Returns an array of Account objects matching the specified filters. If no filters are provided, returns all accounts for your organization.
-
-**Account Object:**
-
-```typescript
-{
-  id: string;              // Unique account identifier
-  type: string;            // Account type ('tiktok' or 'instagram')
-  tag: string | null;      // Custom tag for categorization
-  org_group: string | null;   // Organization group identifier
-  user_group: string | null;  // User group identifier
-  username: string | null;    // Account username/handle
-  nick_name: string | null;   // Account display name
-  pfp_url: string | null;     // Profile picture URL
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Unique account identifier |
-| `type` | `string` | Account platform type (`'tiktok'` or `'instagram'`) |
-| `tag` | `string \| null` | Custom tag for categorization |
-| `org_group` | `string \| null` | Organization group identifier for grouping |
-| `user_group` | `string \| null` | User group identifier for grouping |
-| `username` | `string \| null` | Account username/handle on the platform |
-| `nick_name` | `string \| null` | Display name shown on profile |
-| `pfp_url` | `string \| null` | URL to account's profile picture |
-
-**Example:**
-
-```typescript
-const response = await client.accounts.getAccounts({
-  tag: 'influencer',
-  org_group: 'group1'
-});
-```
-
----
-
-#### `client.accounts.getStats(params?)`
-
-Get account statistics.
-
-**Endpoint:** `POST /accounts/stats`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountIds` | `string[]` | No | Array of account IDs to get stats for |
-| `startDate` | `string` | No | Start date (ISO 8601 format) |
-| `endDate` | `string` | No | End date (ISO 8601 format) |
-| `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 AccountStat objects containing follower counts, views, likes, and other metrics for the specified accounts and date range.
-
-**AccountStat Object:**
-
-```typescript
-{
-  id: string;              // Unique stat record identifier
-  account_id: string;      // Associated account ID
-  followers: number | null;   // Follower count
-  following: number | null;   // Following count
-  views: number | null;       // Total profile views
-  likes: number | null;       // Total likes received
-  created_at: string;         // Timestamp when stat was recorded
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Unique identifier for this stat record |
-| `account_id` | `string` | ID of the account these stats belong to |
-| `followers` | `number \| null` | Total number of followers |
-| `following` | `number \| null` | Total number of accounts being followed |
-| `views` | `number \| null` | Total profile/content views |
-| `likes` | `number \| null` | Total likes received across all content |
-| `created_at` | `string` | ISO 8601 timestamp when this stat was recorded |
-
-**Example:**
-
-```typescript
-const response = await client.accounts.getStats({
-  accountIds: ['account-1', 'account-2'],
-  startDate: '2024-01-01T00:00:00Z',
-  endDate: '2024-12-31T23:59:59Z'
-});
-```
-
----
-
-#### `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.
-
-**Endpoint:** `POST /accounts/status`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountId` | `string` | **Yes** | Account ID to check status for |
-| `includeCompleted` | `boolean` | No | Include completed tasks (default: false) |
-
-**Returns:** `ApiResponse<AccountTask[]>`
-
-Returns an array of AccountTask objects showing pending and (optionally) completed tasks for the specified account. Tasks include profile edits and other account-level operations.
-
-**AccountTask Object:**
-
-```typescript
-{
-  id: string;              // Unique task identifier
-  account_id: string;      // Associated account ID
-  type: string;            // Task type
-  status: string;          // Current task status
-  scheduled_time: string | null;  // When task is scheduled to run
-  edit_profile_info: EditProfileInfo | null;  // Profile update details (if type is 'edit_profile')
-  created_at: string;      // When task was created
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Unique identifier for this task |
-| `account_id` | `string` | ID of the account this task belongs to |
-| `type` | `string` | Task type (e.g., `'edit_profile'`, `'warmup_scroll'`) |
-| `status` | `string` | Current task status (`'scheduled'`, `'pending'`, `'complete'`, `'failed'`) |
-| `scheduled_time` | `string \| null` | ISO 8601 timestamp when task is scheduled to execute |
-| `edit_profile_info` | `EditProfileInfo \| null` | Profile update information (only for `edit_profile` tasks) |
-| `created_at` | `string` | ISO 8601 timestamp when task was created |
-
-**Example:**
-
-```typescript
-const response = await client.accounts.getStatus({
-  accountId: 'account-id',
-  includeCompleted: true
-});
-```
-
----
-
-#### `client.accounts.updateInfo(params)`
-
-Update account metadata (tag, org_group, user_group).
-
-**Endpoint:** `POST /accounts/update-info`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountId` | `string` | **Yes** | Account ID to update |
-| `tag` | `string` | No | New tag value for categorization |
-| `org_group` | `string` | No | New organization group identifier |
-| `user_group` | `string` | No | New user group identifier |
-
-**Note:** At least one of `tag`, `org_group`, or `user_group` must be provided.
-
-**Returns:** `ApiResponse<{ message: string; account: Account }>`
-
-Returns a success message and the updated account object. The update is applied immediately to the database.
-
-**Response Object:**
-
-```typescript
-{
-  message: string;  // Success message (e.g., "Account info updated successfully")
-  account: Account; // Updated account object with new values
-}
-```
-
-**Example:**
-
-```typescript
-const response = await client.accounts.updateInfo({
-  accountId: 'account-id',
-  tag: 'influencer',
-  org_group: 'group1',
-  user_group: 'users1'
-});
+## Get Your API Key
 
-if (response.ok) {
-  console.log(response.data.account.tag); // 'influencer'
-}
-```
-
----
-
-#### `client.accounts.updateSocial(params)`
-
-Update account social profile (avatar, nickname, bio).
-
-**Endpoint:** `POST /accounts/update-social`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountId` | `string` | **Yes** | Account ID to update |
-| `avatarUrl` | `string` | No | New avatar/profile picture URL |
-| `nickName` | `string` | No | New display name |
-| `bio` | `string` | No | New bio text |
-
-**Important:** Nicknames can only be updated **once every 7 days**. If you attempt to update a nickname before the 7-day period has elapsed, the API will return an error with details about when the next update is allowed.
-
-**Returns:** `ApiResponse<{ message: string }>`
-
-Returns a success message when the profile update task has been successfully created and queued. The actual profile update will be processed asynchronously through the GeeLark API.
-
-**Response Object:**
-
-```typescript
-{
-  message: string;  // Success message (e.g., "Profile update task created successfully")
-}
-```
-
-**Error Response (Nickname Restriction):**
-
-If you attempt to update the nickname too soon:
-
-```typescript
-{
-  ok: false,
-  code: 400,
-  message: "Nickname can only be updated once every 7 days. Last update was X days ago. You can update again in Y day(s) on YYYY-MM-DD"
-}
-```
-
-**Example:**
-
-```typescript
-const response = await client.accounts.updateSocial({
-  accountId: 'account-id',
-  nickName: 'Cool Creator',
-  bio: 'Content creator 🎥',
-  avatarUrl: 'https://storage.example.com/avatar.jpg'
-});
-
-if (response.ok) {
-  console.log(response.data.message);
-} else {
-  // Handle nickname restriction error
-  console.error(response.message);
-}
-```
-
----
-
-### Tasks API
-
-#### `client.tasks.getTasks(params?)`
-
-Retrieve tasks with optional filters.
-
-**Endpoint:** `POST /tasks`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountIds` | `string[]` | No | Filter by account IDs |
-| `startDate` | `string` | No | Start date (ISO 8601 format) |
-| `endDate` | `string` | No | End date (ISO 8601 format) |
-| `taskType` | `TaskType` | No | Filter by task type |
-
-**TaskType:** `'warmup_scroll' | 'warmup_search_term' | 'warmup_search_profile' | 'edit_profile'`
-
-**Returns:** `ApiResponse<Task[]>`
-
-Returns an array of Task objects including warmup tasks (scrolling, searching) and profile edit tasks for the specified accounts and date range. Each task includes scheduling information and type-specific parameters.
-
-**Task Object:**
-
-```typescript
-{
-  id: string;              // Unique task identifier
-  account_id: string;      // Associated account ID
-  type: TaskType;          // Task type
-  status: string;          // Current status
-  scheduled_time: string | null;  // When task is scheduled
-  duration: number | null;        // Task duration in seconds
-  keywords: string[] | null;      // Keywords for search tasks
-  edit_profile_info: EditProfileInfo | null;  // Profile info for edit tasks
-  created_at: string;      // Creation timestamp
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Unique identifier for this task |
-| `account_id` | `string` | ID of the account this task belongs to |
-| `type` | `TaskType` | Task type: `'warmup_scroll'`, `'warmup_search_term'`, `'warmup_search_profile'`, or `'edit_profile'` |
-| `status` | `string` | Current status: `'scheduled'`, `'pending'`, `'complete'`, or `'failed'` |
-| `scheduled_time` | `string \| null` | ISO 8601 timestamp when task should execute |
-| `duration` | `number \| null` | Task duration in seconds (for warmup tasks) |
-| `keywords` | `string[] \| null` | Array of keywords (for search tasks) |
-| `edit_profile_info` | `EditProfileInfo \| null` | Profile update details (for `edit_profile` tasks) |
-| `created_at` | `string` | ISO 8601 timestamp when task was created |
-
-**Example:**
-
-```typescript
-const response = await client.tasks.getTasks({
-  accountIds: ['account-1', 'account-2'],
-  taskType: 'edit_profile',
-  startDate: '2024-01-01T00:00:00Z'
-});
-```
+To get your API key:
 
----
+1. Visit [ugc.inc](https://ugc.inc)
+2. Schedule a call with our team
+3. You'll receive your API key after the call
 
-### Posts API
-
-#### `client.posts.getPosts(params?)`
-
-Retrieve posts with optional filters.
-
-**Endpoint:** `POST /post`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountIds` | `string[]` | No | Filter by account IDs |
-| `startDate` | `string` | No | Start date (ISO 8601 format) |
-| `endDate` | `string` | No | End date (ISO 8601 format) |
-
-**Returns:** `ApiResponse<Post[]>`
-
-Returns an array of Post objects (videos and slideshows) for the specified accounts and date range. Includes post status, URLs, captions, and associated media.
-
-**Post Object:**
-
-```typescript
-{
-  id: string;              // Unique post identifier
-  account_id: string;      // Account that posted this
-  type: 'video' | 'slideshow';  // Post type
-  status: string;          // Current post status
-  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
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Unique identifier for this post |
-| `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'` |
-| `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 |
-
-**Example:**
-
-```typescript
-const response = await client.posts.getPosts({
-  accountIds: ['account-1'],
-  startDate: '2024-01-01T00:00:00Z',
-  endDate: '2024-12-31T23:59:59Z'
-});
-```
-
----
-
-#### `client.posts.createSlideshow(params)`
-
-Create a slideshow post from multiple images.
-
-**Endpoint:** `POST /post/slideshow`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountId` | `string` | **Yes** | Account ID to post from |
-| `imageUrls` | `string[]` | **Yes** | Array of image URLs (at least 1 required) |
-| `caption` | `string` | No | Post caption (max 500 characters) |
-| `musicPostId` | `string` | No | Music/audio post ID to use |
-| `postTime` | `string` | No | When to schedule the post (ISO 8601) |
-| `strict` | `boolean` | No | Strict mode (default: true) |
-
-**Returns:** `ApiResponse<Post>`
-
-Returns a Post object for the newly created slideshow. The post will be scheduled for publishing based on the `postTime` parameter (or immediately if not specified). The `status` field indicates whether it's scheduled, pending, or complete.
-
-**Example:**
-
-```typescript
-const response = await client.posts.createSlideshow({
-  accountId: 'account-id',
-  imageUrls: [
-    'https://storage.example.com/img1.jpg',
-    'https://storage.example.com/img2.jpg',
-    'https://storage.example.com/img3.jpg'
-  ],
-  caption: 'Check out these photos! 📸',
-  postTime: '2024-12-25T12:00:00Z'
-});
-```
-
----
-
-#### `client.posts.createVideo(params)`
-
-Create a video post.
-
-**Endpoint:** `POST /post/video`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `accountId` | `string` | **Yes** | Account ID to post from |
-| `videoUrl` | `string` | **Yes** | Video file URL |
-| `caption` | `string` | No | Post caption (max 500 characters) |
-| `musicPostId` | `string` | No | Music/audio post ID to use |
-| `postTime` | `string` | No | When to schedule the post (ISO 8601) |
-| `strict` | `boolean` | No | Strict mode (default: true) |
-
-**Returns:** `ApiResponse<Post>`
-
-Returns a Post object for the newly created video post. The post will be scheduled for publishing based on the `postTime` parameter (or immediately if not specified). The `status` field indicates whether it's scheduled, pending, or complete.
-
-**Example:**
-
-```typescript
-const response = await client.posts.createVideo({
-  accountId: 'account-id',
-  videoUrl: 'https://storage.example.com/video.mp4',
-  caption: 'My awesome video! 🎥 #viral',
-  strict: false
-});
-```
-
----
-
-#### `client.posts.getStats(params?)`
-
-Get post statistics.
-
-**Endpoint:** `POST /post/stats`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `postIds` | `string[]` | No | Array of post IDs to get stats for |
-| `startDate` | `string` | No | Start date (ISO 8601 format) |
-| `endDate` | `string` | No | End date (ISO 8601 format) |
-
-**Returns:** `ApiResponse<PostStat[]>`
-
-Returns an array of PostStat objects containing engagement metrics (views, likes, comments, shares, saves) for the specified posts and date range. Use this to track post performance over time.
-
-**PostStat Object:**
-
-```typescript
-{
-  id: string;              // Unique stat record identifier
-  post_id: string;         // Associated post ID
-  views: number | null;    // View count
-  likes: number | null;    // Like count
-  comments: number | null; // Comment count
-  shares: number | null;   // Share count
-  saves: number | null;    // Save/bookmark count
-  created_at: string;      // When stat was recorded
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Unique identifier for this stat record |
-| `post_id` | `string` | ID of the post these stats belong to |
-| `views` | `number \| null` | Total number of views the post received |
-| `likes` | `number \| null` | Total number of likes the post received |
-| `comments` | `number \| null` | Total number of comments on the post |
-| `shares` | `number \| null` | Total number of times the post was shared |
-| `saves` | `number \| null` | Total number of times the post was saved/bookmarked |
-| `created_at` | `string` | ISO 8601 timestamp when this stat was recorded |
-
-**Example:**
-
-```typescript
-const response = await client.posts.getStats({
-  postIds: ['post-1', 'post-2', 'post-3'],
-  startDate: '2024-01-01T00:00:00Z'
-});
-
-if (response.ok) {
-  response.data.forEach(stat => {
-    console.log(`Post ${stat.post_id}:`);
-    console.log(`  Views: ${stat.views}`);
-    console.log(`  Likes: ${stat.likes}`);
-    console.log(`  Engagement: ${(stat.likes ?? 0) + (stat.comments ?? 0)}`);
-  });
-}
-```
-
----
-
-#### `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.
-
-**Endpoint:** `POST /post/status`
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `postId` | `string` | **Yes** | Post ID to check status for |
+**Important:** Keep your API key secure! Never commit it to version control or expose it in client-side code.
 
-**Returns:** `ApiResponse<{ post_id: string; status: string }>`
+## Documentation
 
-Returns the current status of the specified post. Use this to check if a post has been successfully published or if there were any issues.
+For complete API documentation, including all endpoints, parameters, and examples, visit:
 
-**Response Object:**
+**[docs.ugc.inc](https://docs.ugc.inc)**
 
-```typescript
-{
-  post_id: string;  // ID of the post being checked
-  status: string;   // Current status
-}
-```
-
-**Status Values:** `'scheduled' | 'pending' | 'complete' | 'failed'`
-
-- `'scheduled'` - Post is scheduled to be published at a future time
-- `'pending'` - Post is currently being processed/published
-- `'complete'` - Post was successfully published
-- `'failed'` - Post failed to publish (check error logs)
+## TypeScript Support
 
-**Example:**
+This package is written in TypeScript and provides full type definitions:
 
 ```typescript
-const response = await client.posts.getStatus({
-  postId: 'post-id'
-});
-
-if (response.ok) {
-  console.log(`Post status: ${response.data.status}`);
-}
+import type { Account, Post, Task, ApiResponse } from 'ugcinc';
 ```
 
----
-
 ## License
 
 MIT
-

package/dist/accounts.d.ts

@@ -1,5 +1,5 @@
 import { BaseClient } from './base';
-import type { Account, AccountStat, AccountTask, GetAccountsParams, GetAccountStatsParams, RefreshAccountStatsParams, GetAccountStatusParams, UpdateAccountInfoParams, UpdateAccountSocialParams, ApiResponse } from './types';
+import type { Account, AccountTask, GetAccountsParams, GetAccountStatusParams, UpdateAccountInfoParams, UpdateAccountSocialParams, ApiResponse } from './types';
 /**
  * Client for managing accounts
  */
@@ -9,17 +9,9 @@ export declare class AccountsClient extends BaseClient {
      */
     getAccounts(params?: GetAccountsParams): Promise<ApiResponse<Account[]>>;
     /**
-     * Get account statistics
+     * Get account status (tasks) for one or more accounts
      */
-    getStats(params?: GetAccountStatsParams): Promise<ApiResponse<AccountStat[]>>;
-    /**
-     * Refresh account statistics from TikTok/Instagram API
-     */
-    refreshStats(params?: RefreshAccountStatsParams): Promise<ApiResponse<AccountStat[]>>;
-    /**
-     * Get account status (tasks)
-     */
-    getStatus(params: GetAccountStatusParams): Promise<ApiResponse<AccountTask[]>>;
+    getStatus(params?: GetAccountStatusParams): Promise<ApiResponse<AccountTask[]>>;
     /**
      * Update account metadata (tag, org_group, user_group)
      */

package/dist/accounts.js

@@ -13,22 +13,10 @@ class AccountsClient extends base_1.BaseClient {
         return this.post('/accounts', params ?? {});
     }
     /**
-     * Get account statistics
-     */
-    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)
+     * Get account status (tasks) for one or more accounts
      */
     async getStatus(params) {
-        return this.post('/accounts/status', params);
+        return this.post('/accounts/status', params ?? {});
     }
     /**
      * Update account metadata (tag, org_group, user_group)

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { AccountsClient } from './accounts';
 import { TasksClient } from './tasks';
 import { PostsClient } from './posts';
+import { StatsClient } from './stats';
 import type { ClientConfig } from './base';
 /**
  * Main UGC Inc API Client
@@ -40,5 +41,9 @@ export declare class UGCClient {
      * Client for post-related operations
      */
     posts: PostsClient;
+    /**
+     * Client for statistics operations
+     */
+    stats: StatsClient;
     constructor(config: ClientConfig);
 }

package/dist/client.js

@@ -4,6 +4,7 @@ exports.UGCClient = void 0;
 const accounts_1 = require("./accounts");
 const tasks_1 = require("./tasks");
 const posts_1 = require("./posts");
+const stats_1 = require("./stats");
 /**
  * Main UGC Inc API Client
  *
@@ -34,6 +35,7 @@ class UGCClient {
         this.accounts = new accounts_1.AccountsClient(config);
         this.tasks = new tasks_1.TasksClient(config);
         this.posts = new posts_1.PostsClient(config);
+        this.stats = new stats_1.StatsClient(config);
     }
 }
 exports.UGCClient = UGCClient;

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export { UGCClient } from './client';
 export { AccountsClient } from './accounts';
 export { TasksClient } from './tasks';
 export { PostsClient } from './posts';
+export { StatsClient } from './stats';
 export type { ClientConfig, } from './base';
-export type { SuccessResponse, ErrorResponse, ApiResponse, Account, AccountStat, AccountTask, EditProfileInfo, Task, TaskType, Post, PostType, PostStat, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, UpdateAccountInfoParams, GetTasksParams, GetPostsParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, } from './types';
+export type { SuccessResponse, ErrorResponse, ApiResponse, Account, AccountStat, AccountTask, EditProfileInfo, Task, TaskType, Post, PostType, PostStat, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, UpdateAccountInfoParams, GetTasksParams, GetPostsParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, RefreshStatsParams, RefreshStatsResponse, } from './types';

package/dist/index.js

@@ -5,7 +5,7 @@
  * Official TypeScript/JavaScript client for the UGC Inc API
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PostsClient = exports.TasksClient = exports.AccountsClient = exports.UGCClient = void 0;
+exports.StatsClient = exports.PostsClient = exports.TasksClient = exports.AccountsClient = exports.UGCClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "UGCClient", { enumerable: true, get: function () { return client_1.UGCClient; } });
 var accounts_1 = require("./accounts");
@@ -14,3 +14,5 @@ var tasks_1 = require("./tasks");
 Object.defineProperty(exports, "TasksClient", { enumerable: true, get: function () { return tasks_1.TasksClient; } });
 var posts_1 = require("./posts");
 Object.defineProperty(exports, "PostsClient", { enumerable: true, get: function () { return posts_1.PostsClient; } });
+var stats_1 = require("./stats");
+Object.defineProperty(exports, "StatsClient", { enumerable: true, get: function () { return stats_1.StatsClient; } });

package/dist/posts.d.ts

@@ -1,5 +1,5 @@
 import { BaseClient } from './base';
-import type { Post, PostStat, GetPostsParams, CreateSlideshowParams, GetPostStatsParams, RefreshPostStatsParams, GetPostStatusParams, CreateVideoParams, ApiResponse } from './types';
+import type { Post, GetPostsParams, CreateSlideshowParams, GetPostStatusParams, CreateVideoParams, ApiResponse } from './types';
 /**
  * Client for managing posts
  */
@@ -12,15 +12,6 @@ export declare class PostsClient extends BaseClient {
      * Create a slideshow post
      */
     createSlideshow(params: CreateSlideshowParams): Promise<ApiResponse<Post>>;
-    /**
-     * 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

@@ -18,19 +18,6 @@ class PostsClient extends base_1.BaseClient {
     async createSlideshow(params) {
         return this.post('/post/slideshow', params);
     }
-    /**
-     * Get post statistics
-     */
-    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/stats.d.ts

@@ -0,0 +1,20 @@
+import { BaseClient } from './base';
+import type { AccountStat, PostStat, GetAccountStatsParams, GetPostStatsParams, RefreshStatsParams, RefreshStatsResponse, ApiResponse } from './types';
+/**
+ * Client for managing statistics
+ */
+export declare class StatsClient extends BaseClient {
+    /**
+     * Get account statistics
+     */
+    getAccountStats(params?: GetAccountStatsParams): Promise<ApiResponse<AccountStat[]>>;
+    /**
+     * Get post statistics
+     */
+    getPostStats(params?: GetPostStatsParams): Promise<ApiResponse<PostStat[]>>;
+    /**
+     * Refresh statistics for an account and all its posts
+     * Fetches live data from TikTok/Instagram API and creates new stat records
+     */
+    refresh(params: RefreshStatsParams): Promise<ApiResponse<RefreshStatsResponse>>;
+}

package/dist/stats.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatsClient = void 0;
+const base_1 = require("./base");
+/**
+ * Client for managing statistics
+ */
+class StatsClient extends base_1.BaseClient {
+    /**
+     * Get account statistics
+     */
+    async getAccountStats(params) {
+        return this.post('/stats/accounts', params ?? {});
+    }
+    /**
+     * Get post statistics
+     */
+    async getPostStats(params) {
+        return this.post('/stats/posts', params ?? {});
+    }
+    /**
+     * Refresh statistics for an account and all its posts
+     * Fetches live data from TikTok/Instagram API and creates new stat records
+     */
+    async refresh(params) {
+        return this.post('/stats/refresh', params);
+    }
+}
+exports.StatsClient = StatsClient;

package/dist/types.d.ts

@@ -53,7 +53,7 @@ export interface EditProfileInfo {
 /**
  * Task types
  */
-export type TaskType = 'warmup_scroll' | 'warmup_search_term' | 'warmup_search_profile' | 'edit_profile';
+export type TaskType = 'warmup_scroll' | 'warmup_search_term' | 'warmup_search_profile' | 'edit_profile' | 'update_posts';
 export interface Task {
     id: string;
     account_id: string;
@@ -61,7 +61,7 @@ export interface Task {
     status: string;
     scheduled_time: string | null;
     duration: number | null;
-    keywords: string[] | null;
+    keywords: string | null;
     edit_profile_info: EditProfileInfo | null;
     created_at: string;
 }
@@ -105,14 +105,8 @@ 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;
+    accountIds?: string[];
     includeCompleted?: boolean;
 }
 export interface UpdateAccountInfoParams {
@@ -151,9 +145,6 @@ export interface GetPostStatsParams {
     startDate?: string;
     endDate?: string;
 }
-export interface RefreshPostStatsParams {
-    postIds?: string[];
-}
 export interface GetPostStatusParams {
     postId: string;
 }
@@ -165,3 +156,11 @@ export interface CreateVideoParams {
     videoUrl: string;
     strict?: boolean;
 }
+export interface RefreshStatsParams {
+    accountId: string;
+}
+export interface RefreshStatsResponse {
+    account_stats: AccountStat;
+    post_stats: PostStat[];
+    post_stats_count: number;
+}

package/package.json

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