ugcinc 1.0.0 → 1.0.1

package/README.md

@@ -5,14 +5,14 @@ Official TypeScript/JavaScript client for the UGC Inc API.
 ## Installation
 
 ```bash
-npm install ugcinc
+npm i ugcinc
 ```
 
 ## Getting Started
 
 ### 1. Get Your API Key
 
-Contact UGC Inc to obtain your API key. You'll need this to authenticate all API requests.
+Get your API key at **https://ugc.inc**. You'll need this to authenticate all API requests.
 
 ### 2. Initialize the Client
 
@@ -20,8 +20,7 @@ Contact UGC Inc to obtain your API key. You'll need this to authenticate all API
 import { UGCClient } from 'ugcinc';
 
 const client = new UGCClient({
-  apiKey: 'your-api-key-here',
-  baseUrl: 'https://api.ugcinc.com' // Optional, only needed if using a custom endpoint
+  apiKey: 'your-api-key-here'
 });
 ```
 
@@ -307,6 +306,521 @@ const client = new UGCClient({
 });
 ```
 
+---
+
+## 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.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 profile information.
+
+**Endpoint:** `POST /accounts/update-info`
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `accountId` | `string` | **Yes** | Account ID to update |
+| `scheduledTime` | `string` | No | When to schedule the update (ISO 8601 format) |
+| `avatarUrl` | `string` | No | New avatar/profile picture URL |
+| `nickName` | `string` | No | New display name |
+| `bio` | `string` | No | New bio text |
+| `site` | `string` | No | New website URL |
+
+**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.
+
+**Response Object:**
+
+```typescript
+{
+  message: string;  // Success message (e.g., "Profile update task created successfully")
+}
+```
+
+**Example:**
+
+```typescript
+const response = await client.accounts.updateInfo({
+  accountId: 'account-id',
+  nickName: 'Cool Creator',
+  bio: 'Content creator 🎥',
+  avatarUrl: 'https://storage.example.com/avatar.jpg'
+});
+```
+
+---
+
+### 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'
+});
+```
+
+---
+
+### 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
+  post_url: string | null;      // URL to the live post
+  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'` |
+| `post_url` | `string \| null` | URL to the live post on the platform (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.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 |
+
+**Returns:** `ApiResponse<{ post_id: string; status: string }>`
+
+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.
+
+**Response Object:**
+
+```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)
+
+**Example:**
+
+```typescript
+const response = await client.posts.getStatus({
+  postId: 'post-id'
+});
+
+if (response.ok) {
+  console.log(`Post status: ${response.data.status}`);
+}
+```
+
+---
+
 ## License
 
 MIT

package/dist/base.d.ts

@@ -1,11 +1,10 @@
 import type { ApiResponse } from './types';
 export interface ClientConfig {
     apiKey: string;
-    baseUrl?: string;
 }
 export declare class BaseClient {
     protected apiKey: string;
-    protected baseUrl: string;
+    private readonly baseUrl;
     constructor(config: ClientConfig);
     protected request<T>(endpoint: string, options?: RequestInit): Promise<ApiResponse<T>>;
     protected post<T>(endpoint: string, body?: unknown): Promise<ApiResponse<T>>;

package/dist/base.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseClient = void 0;
 class BaseClient {
     constructor(config) {
+        this.baseUrl = 'https://api.ugc.inc';
         this.apiKey = config.apiKey;
-        this.baseUrl = config.baseUrl ?? 'https://api.ugc.inc';
     }
     async request(endpoint, options = {}) {
         const url = `${this.baseUrl}${endpoint}`;

package/package.json

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