ugcinc 1.0.0

package/README.md

@@ -0,0 +1,313 @@
+# ugcinc
+
+Official TypeScript/JavaScript client for the UGC Inc API.
+
+## Installation
+
+```bash
+npm install 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.
+
+### 2. Initialize the Client
+
+```typescript
+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
+});
+```
+
+**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`);
+  });
+}
+```
+
+#### 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 profile information.
+
+```typescript
+const response = await client.accounts.updateInfo({
+  accountId: 'account-id',
+  nickName: 'New Name',
+  bio: 'New bio text',
+  avatarUrl: 'https://example.com/avatar.jpg',
+  site: 'https://example.com'
+});
+
+if (response.ok) {
+  console.log(response.data.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`);
+  });
+}
+```
+
+#### 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
+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!
+});
+```
+
+## License
+
+MIT
+

package/dist/accounts.d.ts

@@ -0,0 +1,25 @@
+import { BaseClient } from './base';
+import type { Account, AccountStat, AccountTask, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, UpdateAccountInfoParams, ApiResponse } from './types';
+/**
+ * Client for managing accounts
+ */
+export declare class AccountsClient extends BaseClient {
+    /**
+     * Get accounts with optional filters
+     */
+    getAccounts(params?: GetAccountsParams): Promise<ApiResponse<Account[]>>;
+    /**
+     * Get account statistics
+     */
+    getStats(params?: GetAccountStatsParams): Promise<ApiResponse<AccountStat[]>>;
+    /**
+     * Get account status (tasks)
+     */
+    getStatus(params: GetAccountStatusParams): Promise<ApiResponse<AccountTask[]>>;
+    /**
+     * Update account profile information
+     */
+    updateInfo(params: UpdateAccountInfoParams): Promise<ApiResponse<{
+        message: string;
+    }>>;
+}

package/dist/accounts.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountsClient = void 0;
+const base_1 = require("./base");
+/**
+ * Client for managing accounts
+ */
+class AccountsClient extends base_1.BaseClient {
+    /**
+     * Get accounts with optional filters
+     */
+    async getAccounts(params) {
+        return this.post('/accounts', params ?? {});
+    }
+    /**
+     * Get account statistics
+     */
+    async getStats(params) {
+        return this.post('/accounts/stats', params ?? {});
+    }
+    /**
+     * Get account status (tasks)
+     */
+    async getStatus(params) {
+        return this.post('/accounts/status', params);
+    }
+    /**
+     * Update account profile information
+     */
+    async updateInfo(params) {
+        return this.post('/accounts/update-info', params);
+    }
+}
+exports.AccountsClient = AccountsClient;

package/dist/base.d.ts

@@ -0,0 +1,12 @@
+import type { ApiResponse } from './types';
+export interface ClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export declare class BaseClient {
+    protected apiKey: string;
+    protected baseUrl: string;
+    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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseClient = void 0;
+class BaseClient {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? 'https://api.ugc.inc';
+    }
+    async request(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.apiKey}`,
+            ...options.headers,
+        };
+        try {
+            const response = await fetch(url, {
+                ...options,
+                headers,
+            });
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: 500,
+                message: error instanceof Error ? error.message : 'Unknown error occurred',
+            };
+        }
+    }
+    async post(endpoint, body) {
+        return this.request(endpoint, {
+            method: 'POST',
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+}
+exports.BaseClient = BaseClient;

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+import { AccountsClient } from './accounts';
+import { TasksClient } from './tasks';
+import { PostsClient } from './posts';
+import type { ClientConfig } from './base';
+/**
+ * Main UGC Inc API Client
+ *
+ * @example
+ * ```typescript
+ * import { UGCClient } from 'ugcinc';
+ *
+ * const client = new UGCClient({
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Get accounts
+ * const accountsResponse = await client.accounts.getAccounts();
+ * if (accountsResponse.ok) {
+ *   console.log(accountsResponse.data);
+ * }
+ *
+ * // Create a video post
+ * const postResponse = await client.posts.createVideo({
+ *   accountId: 'account-id',
+ *   videoUrl: 'https://example.com/video.mp4',
+ *   caption: 'My awesome video!',
+ * });
+ * ```
+ */
+export declare class UGCClient {
+    /**
+     * Client for account-related operations
+     */
+    accounts: AccountsClient;
+    /**
+     * Client for task-related operations
+     */
+    tasks: TasksClient;
+    /**
+     * Client for post-related operations
+     */
+    posts: PostsClient;
+    constructor(config: ClientConfig);
+}

package/dist/client.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UGCClient = void 0;
+const accounts_1 = require("./accounts");
+const tasks_1 = require("./tasks");
+const posts_1 = require("./posts");
+/**
+ * Main UGC Inc API Client
+ *
+ * @example
+ * ```typescript
+ * import { UGCClient } from 'ugcinc';
+ *
+ * const client = new UGCClient({
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Get accounts
+ * const accountsResponse = await client.accounts.getAccounts();
+ * if (accountsResponse.ok) {
+ *   console.log(accountsResponse.data);
+ * }
+ *
+ * // Create a video post
+ * const postResponse = await client.posts.createVideo({
+ *   accountId: 'account-id',
+ *   videoUrl: 'https://example.com/video.mp4',
+ *   caption: 'My awesome video!',
+ * });
+ * ```
+ */
+class UGCClient {
+    constructor(config) {
+        this.accounts = new accounts_1.AccountsClient(config);
+        this.tasks = new tasks_1.TasksClient(config);
+        this.posts = new posts_1.PostsClient(config);
+    }
+}
+exports.UGCClient = UGCClient;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * UGC Inc API Client
+ *
+ * Official TypeScript/JavaScript client for the UGC Inc API
+ */
+export { UGCClient } from './client';
+export { AccountsClient } from './accounts';
+export { TasksClient } from './tasks';
+export { PostsClient } from './posts';
+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';

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * UGC Inc API Client
+ *
+ * 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;
+var client_1 = require("./client");
+Object.defineProperty(exports, "UGCClient", { enumerable: true, get: function () { return client_1.UGCClient; } });
+var accounts_1 = require("./accounts");
+Object.defineProperty(exports, "AccountsClient", { enumerable: true, get: function () { return accounts_1.AccountsClient; } });
+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; } });

package/dist/posts.d.ts

@@ -0,0 +1,30 @@
+import { BaseClient } from './base';
+import type { Post, PostStat, GetPostsParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, ApiResponse } from './types';
+/**
+ * Client for managing posts
+ */
+export declare class PostsClient extends BaseClient {
+    /**
+     * Get posts with optional filters
+     */
+    getPosts(params?: GetPostsParams): Promise<ApiResponse<Post[]>>;
+    /**
+     * Create a slideshow post
+     */
+    createSlideshow(params: CreateSlideshowParams): Promise<ApiResponse<Post>>;
+    /**
+     * Get post statistics
+     */
+    getStats(params?: GetPostStatsParams): Promise<ApiResponse<PostStat[]>>;
+    /**
+     * Get post status
+     */
+    getStatus(params: GetPostStatusParams): Promise<ApiResponse<{
+        post_id: string;
+        status: string;
+    }>>;
+    /**
+     * Create a video post
+     */
+    createVideo(params: CreateVideoParams): Promise<ApiResponse<Post>>;
+}

package/dist/posts.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostsClient = void 0;
+const base_1 = require("./base");
+/**
+ * Client for managing posts
+ */
+class PostsClient extends base_1.BaseClient {
+    /**
+     * Get posts with optional filters
+     */
+    async getPosts(params) {
+        return this.post('/post', params ?? {});
+    }
+    /**
+     * Create a slideshow post
+     */
+    async createSlideshow(params) {
+        return this.post('/post/slideshow', params);
+    }
+    /**
+     * Get post statistics
+     */
+    async getStats(params) {
+        return this.post('/post/stats', params ?? {});
+    }
+    /**
+     * Get post status
+     */
+    async getStatus(params) {
+        return this.post('/post/status', params);
+    }
+    /**
+     * Create a video post
+     */
+    async createVideo(params) {
+        return this.post('/post/video', params);
+    }
+}
+exports.PostsClient = PostsClient;

package/dist/tasks.d.ts

@@ -0,0 +1,11 @@
+import { BaseClient } from './base';
+import type { Task, GetTasksParams, ApiResponse } from './types';
+/**
+ * Client for managing tasks
+ */
+export declare class TasksClient extends BaseClient {
+    /**
+     * Get tasks with optional filters
+     */
+    getTasks(params?: GetTasksParams): Promise<ApiResponse<Task[]>>;
+}

package/dist/tasks.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TasksClient = void 0;
+const base_1 = require("./base");
+/**
+ * Client for managing tasks
+ */
+class TasksClient extends base_1.BaseClient {
+    /**
+     * Get tasks with optional filters
+     */
+    async getTasks(params) {
+        return this.post('/tasks', params ?? {});
+    }
+}
+exports.TasksClient = TasksClient;

package/dist/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * API response types
+ */
+export interface SuccessResponse<T> {
+    code: 200;
+    message: string;
+    data: T;
+    ok: true;
+}
+export interface ErrorResponse {
+    code: number;
+    message: string;
+    ok: false;
+    data?: never;
+}
+export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
+/**
+ * Account types
+ */
+export interface Account {
+    id: string;
+    type: string;
+    tag: string | null;
+    org_group: string | null;
+    user_group: string | null;
+    username: string | null;
+    nick_name: string | null;
+    pfp_url: string | null;
+}
+export interface AccountStat {
+    id: string;
+    account_id: string;
+    followers: number | null;
+    following: number | null;
+    views: number | null;
+    likes: number | null;
+    created_at: string;
+}
+export interface AccountTask {
+    id: string;
+    account_id: string;
+    type: string;
+    status: string;
+    scheduled_time: string | null;
+    edit_profile_info: EditProfileInfo | null;
+    created_at: string;
+}
+export interface EditProfileInfo {
+    avatarUrl?: string;
+    nickName?: string;
+    bio?: string;
+    site?: string;
+}
+/**
+ * Task types
+ */
+export type TaskType = 'warmup_scroll' | 'warmup_search_term' | 'warmup_search_profile' | 'edit_profile';
+export interface Task {
+    id: string;
+    account_id: string;
+    type: TaskType;
+    status: string;
+    scheduled_time: string | null;
+    duration: number | null;
+    keywords: string[] | null;
+    edit_profile_info: EditProfileInfo | null;
+    created_at: string;
+}
+/**
+ * Post types
+ */
+export type PostType = 'video' | 'slideshow';
+export interface Post {
+    id: string;
+    account_id: string;
+    type: PostType;
+    status: string;
+    post_url: string | null;
+    caption: string | null;
+    media_urls: string[] | null;
+    music_post_id: string | null;
+}
+export interface PostStat {
+    id: string;
+    post_id: string;
+    views: number | null;
+    likes: number | null;
+    comments: number | null;
+    shares: number | null;
+    saves: number | null;
+    created_at: string;
+}
+/**
+ * Request parameter types
+ */
+export interface GetAccountsParams {
+    tag?: string;
+    org_group?: string;
+    user_group?: string;
+}
+export interface GetAccountStatsParams {
+    accountIds?: string[];
+    startDate?: string;
+    endDate?: string;
+    tag?: string;
+    org_group?: string;
+    user_group?: string;
+}
+export interface GetAccountStatusParams {
+    accountId: string;
+    includeCompleted?: boolean;
+}
+export interface UpdateAccountInfoParams {
+    accountId: string;
+    scheduledTime?: string;
+    avatarUrl?: string;
+    nickName?: string;
+    bio?: string;
+    site?: string;
+}
+export interface GetTasksParams {
+    accountIds?: string[];
+    startDate?: string;
+    endDate?: string;
+    taskType?: TaskType;
+}
+export interface GetPostsParams {
+    accountIds?: string[];
+    startDate?: string;
+    endDate?: string;
+}
+export interface CreateSlideshowParams {
+    accountId: string;
+    caption?: string;
+    musicPostId?: string;
+    postTime?: string;
+    imageUrls: string[];
+    strict?: boolean;
+}
+export interface GetPostStatsParams {
+    postIds?: string[];
+    startDate?: string;
+    endDate?: string;
+}
+export interface GetPostStatusParams {
+    postId: string;
+}
+export interface CreateVideoParams {
+    accountId: string;
+    caption?: string;
+    musicPostId?: string;
+    postTime?: string;
+    videoUrl: string;
+    strict?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ugcinc",
+  "version": "1.0.0",
+  "description": "TypeScript/JavaScript client for the UGC Inc API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"No tests specified\" && exit 0"
+  },
+  "keywords": [
+    "ugcinc",
+    "api",
+    "client",
+    "tiktok",
+    "automation",
+    "social-media",
+    "content-management"
+  ],
+  "author": "UGC Inc",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {},
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}
+