ugcinc 4.9.0 → 4.11.0

package/README.md

@@ -41,7 +41,7 @@ if (res.ok) {
 
 `UGCClient` groups the API into a few top-level namespaces:
 
-- `client.accounts`: list, create, update, troubleshoot, and manage account lifecycle
+- `client.accounts`: list, create, update, troubleshoot, quarantine/release, and manage account lifecycle
 - `client.posts`: create video/slideshow posts, update them, retry failures, and preview schedule conflicts
 - `client.media`: upload media, create media records, manage tags/names, and work with social audio
 - `client.stats`: fetch account/post analytics, daily aggregates, top performers, and refresh stats
@@ -109,6 +109,23 @@ await client.posts.createVideo({
 });
 ```
 
+## Pausing an Account
+
+When a platform blocks an account — a human-verification prompt, a signed-out
+session, content strikes — quarantine it so its scheduled posts stop failing
+while the block is unresolved. Nothing is deleted: posts stay scheduled and
+become eligible again on release, which restores the account's prior status.
+
+```ts
+await client.accounts.quarantine({
+  accountId,
+  reason: "Platform is asking the account to verify it is human",
+});
+
+// once resolved
+await client.accounts.release({ accountId });
+```
+
 ## Post Tags
 
 Posts carry an optional custom `tag` for categorization (independent of account tags). Set it with

package/dist/accounts.d.ts

@@ -1,5 +1,30 @@
 import { BaseClient } from './base';
 import type { ApiResponse } from './types';
+/**
+ * Lifecycle status of an account.
+ *
+ * `quarantined` means the account is paused and will not post — set when the
+ * platform has blocked it (human-verification prompt, signed-out session,
+ * content strikes) so its scheduled posts stop failing. Nothing is deleted;
+ * releasing restores the status the account held before.
+ */
+export type AccountStatus = 'uninitialized' | 'pending' | 'initialized' | 'setup' | 'warming' | 'warmed' | 'needs_replacement' | 'replacing' | 'pending_cancellation' | 'failed' | 'deleted' | 'reclaimed' | 'quarantined';
+export interface QuarantineAccountParams {
+    accountId: string;
+    /** Why the account is being paused; recorded for whoever resolves it. */
+    reason: string;
+}
+export interface ReleaseAccountParams {
+    accountId: string;
+}
+export interface QuarantineAccountResponse {
+    accountId: string;
+    status: AccountStatus;
+    reason?: string;
+    /** True when the account was already quarantined — the call is idempotent. */
+    alreadyQuarantined?: boolean;
+    released?: boolean;
+}
 export interface Account {
     id: string;
     org_id: string;
@@ -21,7 +46,7 @@ export interface Account {
     niches: string | null;
     age_range: string | null;
     sex: string | null;
-    status: 'uninitialized' | 'pending' | 'initialized' | 'setup' | 'warming' | 'warmed' | 'needs_replacement' | 'replacing' | 'pending_cancellation' | 'failed' | 'deleted' | 'reclaimed';
+    status: AccountStatus;
     phone_type: 'physical_iphone' | 'manual_iphone' | 'physical_android' | 'emulated_android' | 'social_api' | 'custom_provider' | 'tracking' | null;
     approved: boolean;
     replacement_count: number;
@@ -73,7 +98,7 @@ export interface GetAccountsParams {
     tag?: string;
     org_group?: string;
     user_group?: string;
-    status?: 'uninitialized' | 'pending' | 'initialized' | 'setup' | 'warming' | 'warmed' | 'needs_replacement' | 'replacing' | 'failed' | 'deleted' | 'reclaimed';
+    status?: AccountStatus;
     /** Max rows to return. Omit to fetch all matching accounts (no pagination). */
     limit?: number;
     /** Opaque cursor from a previous response's `nextCursor`, to fetch the next page. */
@@ -319,6 +344,21 @@ export declare class AccountsClient extends BaseClient {
      * If delete_activity is true, deletes all warmup tasks instead
      */
     resetWarmup(params: ResetWarmupParams): Promise<ApiResponse<ResetWarmupResponse>>;
+    /**
+     * Pause an account so it stops posting
+     *
+     * Use when the platform has blocked the account — a human-verification
+     * prompt, a signed-out session, content strikes — so its scheduled posts
+     * stop failing until the block is cleared. Nothing is deleted and no post is
+     * lost: posts stay scheduled and become eligible again on release.
+     * Idempotent — repeating returns `alreadyQuarantined: true`.
+     */
+    quarantine(params: QuarantineAccountParams): Promise<ApiResponse<QuarantineAccountResponse>>;
+    /**
+     * Return a quarantined account to posting rotation
+     * Restores the status the account held before it was quarantined
+     */
+    release(params: ReleaseAccountParams): Promise<ApiResponse<QuarantineAccountResponse>>;
     /**
      * Create new account seats for your organization
      * Updates your Stripe subscription billing accordingly

package/dist/accounts.js

@@ -100,6 +100,32 @@ class AccountsClient extends base_1.BaseClient {
     async resetWarmup(params) {
         return this.post('/accounts/reset-warmup', params);
     }
+    /**
+     * Pause an account so it stops posting
+     *
+     * Use when the platform has blocked the account — a human-verification
+     * prompt, a signed-out session, content strikes — so its scheduled posts
+     * stop failing until the block is cleared. Nothing is deleted and no post is
+     * lost: posts stay scheduled and become eligible again on release.
+     * Idempotent — repeating returns `alreadyQuarantined: true`.
+     */
+    async quarantine(params) {
+        return this.post('/accounts/quarantine', {
+            accountId: params.accountId,
+            action: 'quarantine',
+            reason: params.reason,
+        });
+    }
+    /**
+     * Return a quarantined account to posting rotation
+     * Restores the status the account held before it was quarantined
+     */
+    async release(params) {
+        return this.post('/accounts/quarantine', {
+            accountId: params.accountId,
+            action: 'release',
+        });
+    }
     /**
      * Create new account seats for your organization
      * Updates your Stripe subscription billing accordingly

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export type { PortId } from './port-id';
 export { extractTemplateVariables, processTemplate, substituteVariables } from './automations/utils';
 export type { InputType } from './automations/nodes/types';
 export type { ClientConfig } from './base';
-export type { Account, AccountStat, AccountTask, EditProfileInfo, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, AccountInfoUpdate, UpdateAccountInfoParams, AccountInfoUpdateResult, UpdateAccountInfoResponse, AccountSocialUpdate, UpdateAccountSocialParams, AccountSocialUpdateResult, UpdateAccountSocialResponse, DeleteAccountPostsParams, DeleteAccountPostsResponse, ResetWarmupParams, ResetWarmupResponse, NicheSwitchUpdate, NicheSwitchParams, NicheSwitchResult, NicheSwitchResponse, CreateAccountInput, CreateAccountsParams, CreateAccountResult, CreateAccountsResponse, TroubleshootFailReason, TroubleshootAccount, TroubleshootParams, } from './accounts';
+export type { Account, AccountStatus, AccountStat, AccountTask, QuarantineAccountParams, ReleaseAccountParams, QuarantineAccountResponse, EditProfileInfo, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, AccountInfoUpdate, UpdateAccountInfoParams, AccountInfoUpdateResult, UpdateAccountInfoResponse, AccountSocialUpdate, UpdateAccountSocialParams, AccountSocialUpdateResult, UpdateAccountSocialResponse, DeleteAccountPostsParams, DeleteAccountPostsResponse, ResetWarmupParams, ResetWarmupResponse, NicheSwitchUpdate, NicheSwitchParams, NicheSwitchResult, NicheSwitchResponse, CreateAccountInput, CreateAccountsParams, CreateAccountResult, CreateAccountsResponse, TroubleshootFailReason, TroubleshootAccount, TroubleshootParams, } from './accounts';
 export type { TaskType, Task, GetTasksParams } from './tasks';
 export type { PostType, PostStatus, Post, PostStat, CaptionOverlay, GetPostsParams, CreateDraftParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, UpdatePostParams, DeletePostsParams, DeletePostsResponse, RetryPostsParams, SetPostStatusParams, SetPostStatusResponse, PreviewScheduleEntry, PreviewScheduleParams, PreviewScheduleResult, } from './posts';
 export type { RefreshStatsParams, RefreshStatsError, RefreshStatsResponse, RefreshStatsProgressResponse, RefreshStartEvent, RefreshProgressEvent, RefreshDoneEvent, RefreshStreamEvent, DailyAggregatedStat, GetDailyAggregatedStatsParams, DailyAccountStat, GetDailyAccountStatsParams, DailyPostStat, GetDailyPostStatsParams, DashboardDailyStat, GetDashboardDailyStatsParams, TopAccount, GetTopAccountsParams, TopPost, GetTopPostsParams, } from './stats';

package/dist/posts.d.ts

@@ -1,5 +1,18 @@
 import { BaseClient } from './base';
 import type { ApiResponse } from './types';
+/**
+ * Why a post failed, as a stable, client-safe category.
+ *
+ * - `device_error` — the posting device was unavailable or did not respond
+ * - `network_error` — the connection dropped while posting
+ * - `upload_interrupted` — the upload started but could not be confirmed finished
+ * - `account_issue` — the social account was not in a usable state
+ * - `capacity_deferred` — no posting capacity was available; the post will be retried
+ * - `platform_change` — the social app's interface changed and the post could not complete
+ * - `unconfirmed` — posting finished but publication could not be confirmed
+ * - `unknown` — the post failed for an unrecognized reason
+ */
+export type PostFailCategory = 'device_error' | 'network_error' | 'upload_interrupted' | 'account_issue' | 'capacity_deferred' | 'platform_change' | 'unconfirmed' | 'unknown';
 export type PostType = 'video' | 'slideshow';
 export type PostStatus = 'draft' | 'scheduled' | 'pending' | 'complete' | 'failed' | 'retrying' | 'deleting' | 'deleted' | 'hidden' | 'require-approval';
 /**
@@ -184,6 +197,8 @@ export declare class PostsClient extends BaseClient {
         post_id: string;
         status: string;
         postUrl?: string;
+        /** Set when status is "failed"; null otherwise. */
+        fail_category: PostFailCategory | null;
     }>>;
     /**
      * Create a video post

package/package.json

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