ugcinc 2.24.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/package.json

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