ugcinc 4.8.1 → 4.10.0

package/README.md

@@ -109,6 +109,24 @@ await client.posts.createVideo({
 });
 ```
 
+## Post Tags
+
+Posts carry an optional custom `tag` for categorization (independent of account tags). Set it with
+the `post_tag` param on `posts.createVideo()`, `posts.createSlideshow()`, `posts.createDraft()`, and
+`posts.updatePost()`; it is returned as `tag` on the `Post` object. Note: on the create endpoints,
+the separate `tag` param filters account auto-selection by ACCOUNT tag and is not stored on the post.
+
+```typescript
+await client.posts.createVideo({
+  accountId: "acc_123",
+  videoUrl: "https://example.com/video.mp4",
+  caption: "Post description",
+  post_tag: "campaign-july",
+});
+
+await client.posts.updatePost({ postId: "post_123", post_tag: "campaign-august" });
+```
+
 ## Useful Exports
 
 - `UGCClient` for API access

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';
 /**
@@ -20,6 +33,8 @@ export interface Post {
     status: PostStatus;
     social_id: string | null;
     caption: string | null;
+    /** Custom tag stored on the post itself (set via `post_tag` on create/update) */
+    tag: string | null;
     /** Only returned by createVideo; other post endpoints omit it */
     caption_overlays?: CaptionOverlay[] | null;
     title: string | null;
@@ -59,9 +74,12 @@ export interface CreateSlideshowParams {
     imageUrls: string[];
     strict?: boolean;
     mustPostBy?: string;
+    /** Account auto-selection filter: only pick accounts whose ACCOUNT tag matches (not stored on the post) */
     tag?: string;
     user_group?: string;
     org_group?: string;
+    /** Tag stored on the created POST itself (returned as `tag` on the Post object) */
+    post_tag?: string;
 }
 export interface GetPostStatsParams {
     postIds?: string[];
@@ -81,9 +99,12 @@ export interface CreateVideoParams {
     videoUrl: string;
     strict?: boolean;
     mustPostBy?: string;
+    /** Account auto-selection filter: only pick accounts whose ACCOUNT tag matches (not stored on the post) */
     tag?: string;
     user_group?: string;
     org_group?: string;
+    /** Tag stored on the created POST itself (returned as `tag` on the Post object) */
+    post_tag?: string;
 }
 export interface DeletePostsParams {
     postIds: string[];
@@ -109,6 +130,8 @@ export interface UpdatePostParams {
     postTime?: string;
     accountId?: string;
     mediaUrls?: string[];
+    /** New tag stored on the post (returned as `tag` on the Post object) */
+    post_tag?: string;
     excludePostIds?: string[];
 }
 export interface SetPostStatusParams {
@@ -130,6 +153,8 @@ export interface CreateDraftParams {
     caption?: string;
     title?: string;
     socialAudioId?: string;
+    /** Tag stored on the created POST itself (returned as `tag` on the Post object) */
+    post_tag?: string;
 }
 export interface PreviewScheduleParams {
     entries: PreviewScheduleEntry[];
@@ -172,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/dist/tools/posts.js

@@ -32,6 +32,7 @@ exports.postTools = [
             tag: zod_1.z.string().optional().describe('Filter accounts by tag (for auto-selection)'),
             user_group: zod_1.z.string().optional().describe('Filter accounts by user group (for auto-selection)'),
             org_group: zod_1.z.string().optional().describe('Filter accounts by org group (for auto-selection)'),
+            post_tag: zod_1.z.string().optional().describe('Tag stored on the created post itself (distinct from the account-filter tag)'),
         }),
         execute: async (client, params) => {
             return client.posts.createVideo(params);
@@ -52,6 +53,7 @@ exports.postTools = [
             tag: zod_1.z.string().optional().describe('Filter accounts by tag (for auto-selection)'),
             user_group: zod_1.z.string().optional().describe('Filter accounts by user group (for auto-selection)'),
             org_group: zod_1.z.string().optional().describe('Filter accounts by org group (for auto-selection)'),
+            post_tag: zod_1.z.string().optional().describe('Tag stored on the created post itself (distinct from the account-filter tag)'),
         }),
         execute: async (client, params) => {
             return client.posts.createSlideshow(params);
@@ -66,6 +68,7 @@ exports.postTools = [
             caption: zod_1.z.string().optional().describe('Post caption'),
             title: zod_1.z.string().optional().describe('Slideshow title'),
             socialAudioId: zod_1.z.string().optional().describe('Social audio ID'),
+            post_tag: zod_1.z.string().optional().describe('Tag stored on the created post'),
         }),
         execute: async (client, params) => {
             return client.posts.createDraft(params);
@@ -92,6 +95,7 @@ exports.postTools = [
             postTime: zod_1.z.string().optional().describe('New scheduled time (ISO 8601)'),
             accountId: zod_1.z.string().optional().describe('Move post to different account'),
             mediaUrls: zod_1.z.array(zod_1.z.string()).optional().describe('New media URLs'),
+            post_tag: zod_1.z.string().optional().describe('New tag stored on the post'),
         }),
         execute: async (client, params) => {
             return client.posts.updatePost(params);

package/package.json

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