ugcinc 2.23.0 → 2.24.1

package/README.md

@@ -81,6 +81,15 @@ For complete API documentation, including all endpoints, parameters, and example
 - Delete API keys
 - Edit API key names
 
+### Media
+- Get all media (user_media + social_audio combined) with filters (ids, tag)
+- Get social audio with filters (ids, tag)
+- Create media from URLs (for files already uploaded to blob storage)
+- Create social audio from TikTok video or music URLs
+- Update media tags
+- Delete media (also removes files from blob storage)
+- Get upload handler URL for client-side uploads with @vercel/blob
+
 ### Render
 - Render videos from editor configurations (supports video, audio, text, image segments)
 - Render static images from editor configurations (supports text and image segments only)
@@ -479,6 +488,142 @@ if (statusResponse.ok && statusResponse.data.status === 'completed') {
 }
 ```
 
+**Get media with filters:**
+```typescript
+// Get all media (user_media + social_audio combined)
+const response = await client.media.getMedia();
+
+// Get media by specific IDs
+const response = await client.media.getMedia({
+  ids: ['media-uuid-1', 'media-uuid-2']
+});
+
+// Get media by tag
+const response = await client.media.getMedia({
+  tag: 'product-shots'
+});
+
+if (response.ok) {
+  response.data.forEach(item => {
+    console.log(`${item.id}: ${item.name} (${item.media_type})`);
+    // media_type is 'user_media' or 'social_audio'
+  });
+}
+```
+
+**Get social audio:**
+```typescript
+// Get all social audio
+const response = await client.media.getSocialAudio();
+
+// Get social audio by IDs
+const response = await client.media.getSocialAudio({
+  ids: ['audio-uuid-1']
+});
+
+// Get social audio by tag
+const response = await client.media.getSocialAudio({
+  tag: 'trending-sounds'
+});
+
+if (response.ok) {
+  response.data.forEach(audio => {
+    console.log(`${audio.name}: ${audio.audio_url}`);
+    console.log(`Preview: ${audio.preview_url}`);
+    console.log(`TikTok link: ${audio.social_audio_link}`);
+  });
+}
+```
+
+**Create media from URLs:**
+```typescript
+// Create media records from URLs (files already in blob storage)
+const response = await client.media.create({
+  urls: [
+    'https://your-blob-storage.com/video1.mp4',
+    'https://your-blob-storage.com/image1.jpg'
+  ],
+  tag: 'campaign-assets'
+});
+
+if (response.ok) {
+  console.log(`Created ${response.data.data.length} media items`);
+  response.data.data.forEach(item => {
+    console.log(`  - ${item.name}: ${item.url}`);
+  });
+}
+```
+
+**Create social audio from TikTok:**
+```typescript
+// Import audio from a TikTok video URL
+const response = await client.media.createSocialAudio({
+  url: 'https://www.tiktok.com/@username/video/1234567890',
+  tag: 'viral-sounds'
+});
+
+// Or import from a TikTok music/sound URL
+const response = await client.media.createSocialAudio({
+  url: 'https://www.tiktok.com/music/original-sound-1234567890',
+  tag: 'trending'
+});
+
+if (response.ok) {
+  const audio = response.data;
+  console.log(`Imported: ${audio.name}`);
+  console.log(`Audio URL: ${audio.audio_url}`);
+  console.log(`Preview image: ${audio.preview_url}`);
+  console.log(`Original TikTok post: ${audio.social_post_link}`);
+}
+```
+
+**Update media tag:**
+```typescript
+const response = await client.media.updateTag({
+  id: 'media-uuid',
+  tag: 'new-tag-name'
+});
+
+if (response.ok) {
+  console.log(`Updated tag for ${response.data.name}`);
+}
+```
+
+**Delete media:**
+```typescript
+// Delete one or more media items (also removes files from blob storage)
+const response = await client.media.delete({
+  ids: ['media-uuid-1', 'media-uuid-2']
+});
+
+if (response.ok) {
+  console.log(`Deleted: ${response.data.deleted.join(', ')}`);
+  if (response.data.failed?.length) {
+    console.log('Failed to delete:', response.data.failed);
+  }
+}
+```
+
+**Client-side uploads with @vercel/blob:**
+```typescript
+import { upload } from '@vercel/blob/client';
+
+// Get the upload handler URL
+const uploadUrl = client.media.getUploadHandlerUrl();
+
+// Upload file directly from browser
+const blob = await upload(file.name, file, {
+  access: 'public',
+  handleUploadUrl: uploadUrl
+});
+
+// Then create the media record
+const response = await client.media.create({
+  urls: [blob.url],
+  tag: 'user-uploads'
+});
+```
+
 **Statistics:**
 ```typescript
 // Get latest stats (one record per account/post)
@@ -536,7 +681,16 @@ if (refreshResult.ok) {
 This package is written in TypeScript and provides full type definitions:
 
 ```typescript
-import type { Account, Post, Task, ApiKey, ApiResponse } from 'ugcinc';
+import type { 
+  Account, 
+  Post, 
+  Task, 
+  ApiKey, 
+  Media, 
+  UserMedia, 
+  SocialAudio, 
+  ApiResponse 
+} from 'ugcinc';
 ```
 
 ## License

package/dist/media.d.ts

@@ -1,14 +1,20 @@
 import { BaseClient } from './base';
-import type { Media, UserMedia, SocialAudio, GetMediaParams, UploadMediaResponse, UpdateMediaTagParams, DeleteMediaParams, DeleteMediaResponse, CreateSocialAudioParams, CreateMediaFromUrlParams, ApiResponse } from './types';
+import type { Media, UserMedia, SocialAudio, GetMediaParams, GetSocialAudioParams, UploadMediaResponse, UpdateMediaTagParams, DeleteMediaParams, DeleteMediaResponse, CreateSocialAudioParams, CreateMediaFromUrlParams, ApiResponse } from './types';
 /**
  * Client for managing media files
  */
 export declare class MediaClient extends BaseClient {
     /**
-     * Get all media for the organization
+     * Get media for the organization
      * Returns both user_media and social_audio combined
+     * Can filter by ids or tag
      */
     getMedia(params?: GetMediaParams): Promise<ApiResponse<Media[]>>;
+    /**
+     * Get social audio for the organization
+     * Can filter by ids or tag
+     */
+    getSocialAudio(params?: GetSocialAudioParams): Promise<ApiResponse<SocialAudio[]>>;
     /**
      * Create media from URL(s)
      * Creates media records from files already uploaded to blob storage
@@ -27,7 +33,6 @@ export declare class MediaClient extends BaseClient {
     updateTag(params: UpdateMediaTagParams): Promise<ApiResponse<UserMedia | SocialAudio>>;
     /**
      * Delete one or more media items
-     * Supports both single id and bulk ids
      * Also deletes the files from blob storage
      */
     delete(params: DeleteMediaParams): Promise<ApiResponse<DeleteMediaResponse>>;
@@ -36,13 +41,4 @@ export declare class MediaClient extends BaseClient {
      * Extracts audio and cover image from TikTok video or music URL
      */
     createSocialAudio(params: CreateSocialAudioParams): Promise<ApiResponse<SocialAudio>>;
-    /**
-     * Get a media item by ID
-     * Returns either user_media or social_audio based on what's found
-     */
-    getById(id: string): Promise<ApiResponse<Media>>;
-    /**
-     * Get a social audio by ID
-     */
-    getSocialAudioById(id: string): Promise<ApiResponse<SocialAudio>>;
 }

package/dist/media.js

@@ -7,12 +7,20 @@ const base_1 = require("./base");
  */
 class MediaClient extends base_1.BaseClient {
     /**
-     * Get all media for the organization
+     * Get media for the organization
      * Returns both user_media and social_audio combined
+     * Can filter by ids or tag
      */
     async getMedia(params) {
         return this.post('/media', params ?? {});
     }
+    /**
+     * Get social audio for the organization
+     * Can filter by ids or tag
+     */
+    async getSocialAudio(params) {
+        return this.post('/media/social-audio', params ?? {});
+    }
     /**
      * Create media from URL(s)
      * Creates media records from files already uploaded to blob storage
@@ -41,7 +49,6 @@ class MediaClient extends base_1.BaseClient {
     }
     /**
      * Delete one or more media items
-     * Supports both single id and bulk ids
      * Also deletes the files from blob storage
      */
     async delete(params) {
@@ -52,20 +59,7 @@ class MediaClient extends base_1.BaseClient {
      * Extracts audio and cover image from TikTok video or music URL
      */
     async createSocialAudio(params) {
-        return this.post('/media/social-audio', params);
-    }
-    /**
-     * Get a media item by ID
-     * Returns either user_media or social_audio based on what's found
-     */
-    async getById(id) {
-        return this.post(`/media/${id}`, {});
-    }
-    /**
-     * Get a social audio by ID
-     */
-    async getSocialAudioById(id) {
-        return this.post(`/media/social-audio/${id}`, {});
+        return this.post('/media/social-audio/upload', params);
     }
 }
 exports.MediaClient = MediaClient;

package/dist/types.d.ts

@@ -668,6 +668,11 @@ export interface SocialAudio {
 }
 export type Media = UserMedia | SocialAudio;
 export interface GetMediaParams {
+    ids?: string[];
+    tag?: string;
+}
+export interface GetSocialAudioParams {
+    ids?: string[];
     tag?: string;
 }
 export interface UploadMediaParams {

package/package.json

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