ugcinc 4.10.0 → 4.12.0

package/README.md

@@ -41,9 +41,9 @@ 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.media`: upload media, create media records, search profile-picture candidates, manage tags/names, and work with social audio
 - `client.stats`: fetch account/post analytics, daily aggregates, top performers, and refresh stats
 - `client.org`: manage organizations, API keys, and integration keys
 - `client.billing`: inspect subscription state and handle account deactivation, replacements, and refunds
@@ -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,12 +25,12 @@ 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';
 export type { Org, ApiKey, DeleteApiKeyParams, EditApiKeyParams, IntegrationKey, IntegrationProvider, UpsertIntegrationKeyParams, DeleteIntegrationKeyParams } from './org';
-export type { UserMedia, MediaUse, SocialAudio, Media, GetMediaParams, GetSocialAudioParams, UploadMediaParams, UploadMediaResponse, MediaTagUpdate, UpdateMediaTagsParams, MediaTagUpdateResult, UpdateMediaTagsResponse, UpdateMediaTagParams, UpdateMediaNameParams, DeleteMediaParams, DeleteMediaResponse, CreateSocialAudioParams, ImportTextParams, ImportTextResponse, CreateMediaFromUrlParams, GetMediaUseParams, GetMediaUseResponse, FilterMediaParams, FilterMediaResponse, GetUploadTokenParams, UploadTokenResponse, } from './media';
+export type { UserMedia, MediaUse, SocialAudio, Media, GetMediaParams, GetSocialAudioParams, UploadMediaParams, UploadMediaResponse, MediaTagUpdate, UpdateMediaTagsParams, MediaTagUpdateResult, UpdateMediaTagsResponse, UpdateMediaTagParams, UpdateMediaNameParams, DeleteMediaParams, DeleteMediaResponse, CreateSocialAudioParams, ImportTextParams, ImportTextResponse, CreateMediaFromUrlParams, GetMediaUseParams, GetMediaUseResponse, FilterMediaParams, FilterMediaResponse, PfpSearchParams, PfpSearchResponse, PfpCandidate, GetUploadTokenParams, UploadTokenResponse, } from './media';
 export type { CommentStatus, Comment, CreateCommentParams, CreateCommentResponse, GetCommentsParams, } from './comments';
 export type { BillingInfo, PortalUrlResponse, CancelAccountParams, CancelAccountResponse, ReactivateAccountParams, ReactivateAccountResponse, CancelSubscriptionResponse, RequestReplacementParams, RequestReplacementResponse, RequestRefundParams, RequestRefundResponse, BillingRequestInfo, PortalParams, } from './billing';
 export type { RenderJobResponse, RenderJobStatus, SubmitImageRenderJobParams, SubmitVideoRenderJobParams, SubmitScreenshotAnimationRenderJobParams, SubmitAutoCaptionRenderJobParams, SubmitSceneSplitJobParams, SceneSplitDetectorConfig, SubmitInstagramDmRenderJobParams, SubmitIMessageDmRenderJobParams, IgDmMessage, ImDmMessage, RenderVideoEditorConfig, } from './render';

package/dist/media.d.ts

@@ -131,6 +131,25 @@ export interface FilterMediaResponse {
     used_count: number;
     available_count: number;
 }
+export interface PfpSearchParams {
+    /** What to search for, e.g. "black girl selfie" or "asian woman aesthetic". */
+    search_term: string;
+    /** How many pictures to return. Defaults to 12, capped at 40. */
+    count?: number;
+}
+export interface PfpCandidate {
+    /** Stable id for this picture at the source. */
+    source_id: string;
+    /** Full-resolution image — the one an account's avatar is set to. */
+    url: string;
+    /** Smaller variant, for rendering a grid of options. */
+    preview_url: string;
+}
+export interface PfpSearchResponse {
+    pictures: PfpCandidate[];
+    search_term: string;
+    count: number;
+}
 export interface GetUploadTokenParams {
     filename: string;
     contentType?: string;
@@ -212,4 +231,18 @@ export declare class MediaClient extends BaseClient {
      * @param params.name - Use case identifier (e.g., "profile_picture")
      */
     filter(params: FilterMediaParams): Promise<ApiResponse<FilterMediaResponse>>;
+    /**
+     * Search for profile-picture candidates for a search term.
+     *
+     * Pictures already in use as a profile picture are removed before the result
+     * comes back, so two accounts cannot end up wearing the same face. Sourcing
+     * and filtering are one call for that reason — a caller who forgot the second
+     * step would get duplicates across their accounts and find out much later.
+     *
+     * Requires the `media:search` scope on a restricted key.
+     *
+     * @param params.search_term - What to search for
+     * @param params.count - How many to return (default 12, max 40)
+     */
+    pfpSearch(params: PfpSearchParams): Promise<ApiResponse<PfpSearchResponse>>;
 }

package/dist/media.js

@@ -99,5 +99,21 @@ class MediaClient extends base_1.BaseClient {
     async filter(params) {
         return this.post('/media/filter', params);
     }
+    /**
+     * Search for profile-picture candidates for a search term.
+     *
+     * Pictures already in use as a profile picture are removed before the result
+     * comes back, so two accounts cannot end up wearing the same face. Sourcing
+     * and filtering are one call for that reason — a caller who forgot the second
+     * step would get duplicates across their accounts and find out much later.
+     *
+     * Requires the `media:search` scope on a restricted key.
+     *
+     * @param params.search_term - What to search for
+     * @param params.count - How many to return (default 12, max 40)
+     */
+    async pfpSearch(params) {
+        return this.post('/media/pfp-search', params);
+    }
 }
 exports.MediaClient = MediaClient;

package/package.json

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