Merge pull request #65 from strapi/feat/update-file-metadata

Update file metadata

Author: jhoward1994

README.md

@@ -209,6 +209,7 @@ The `files` property provides access to the Strapi Media Library through the Upl
 
 - `find(params?: FileQueryParams): Promise<FileListResponse>` - Retrieves a list of file metadata based on optional query parameters
 - `findOne(fileId: number): Promise<FileResponse>` - Retrieves the metadata for a single file by its ID
+- `update(fileId: number, fileInfo: FileUpdateData): Promise<FileResponse>` - Updates metadata for an existing file
 
 #### Example: Finding Files
 
@@ -250,6 +251,26 @@ console.log(file.url); // The file URL
 console.log(file.mime); // The file MIME type
 ```
 
+#### Example: Updating File Metadata
+
+```typescript
+// Initialize the client
+const client = strapi({
+  baseURL: 'http://localhost:1337/api',
+  auth: 'your-api-token',
+});
+
+// Update file metadata
+const updatedFile = await client.files.update(1, {
+  name: 'New file name',
+  alternativeText: 'Descriptive alt text for accessibility',
+  caption: 'A caption for the file',
+});
+
+console.log(updatedFile.name); // Updated file name
+console.log(updatedFile.alternativeText); // Updated alt text
+```
+
 ## 🐛 Debug
 
 This section provides guidance on enabling and managing debug logs for the SDK,

demo/node-javascript/src/index.js

@@ -1,5 +1,6 @@
 const { strapi } = require('@strapi/client');
 require('dotenv').config();
+const os = require('os');
 
 const api_token = process.env.FULL_ACCESS_TOKEN; // READ_ONLY_TOKEN is also available
 
@@ -20,7 +21,9 @@ async function main() {
   // Create a collection type query manager for the categories
   const categories = client.collection('categories');
 
-  console.log('\n=== Basic Category Data ===\n');
+  console.log(os.EOL);
+  console.log('=== Basic Category Data ===');
+  console.log(os.EOL);
 
   // Fetch the list of all categories (basic demo)
   const basicCategoryData = await categories.find();
@@ -33,7 +36,9 @@ async function main() {
   });
 
   // Example: Category with image files
-  console.log('\n=== Categories with their images ===\n');
+  console.log(os.EOL);
+  console.log('=== Categories with their images ===');
+  console.log(os.EOL);
 
   // Fetch all categories with their related images
   const result = await categories.find({
@@ -57,7 +62,9 @@ async function main() {
   }
 
   // Example: Direct file operations
-  console.log('\n=== Direct file queries ===\n');
+  console.log(os.EOL);
+  console.log('=== Direct file queries ===');
+  console.log(os.EOL);
 
   const techCategoryResult = await categories.find({
     filters: {
@@ -68,7 +75,7 @@ async function main() {
     populate: ['image'],
   });
 
-  if (techCategoryResult.data) {
+  if (techCategoryResult.data && techCategoryResult.data.length > 0) {
     const categoryData = techCategoryResult.data[0];
     console.log(`Working with category: ${categoryData.name} (ID: ${categoryData.id})`);
 
@@ -78,7 +85,8 @@ async function main() {
 
       // Get the specific file by ID
       const fileInfo = await client.files.findOne(imageId);
-      console.log('\nFile details:');
+      console.log(os.EOL);
+      console.log('File details:');
       console.log(`  Name: ${fileInfo.name}`);
       console.log(`  Alternative Text: ${fileInfo.alternativeText || 'None'}`);
       console.log(`  Caption: ${fileInfo.caption || 'None'}`);
@@ -89,6 +97,53 @@ async function main() {
       console.log(`  URL: ${fileInfo.url}`);
     }
   }
+
+  // Example: Update file metadata
+  console.log(os.EOL);
+  console.log('=== File Update Operations ===');
+  console.log(os.EOL);
+
+  if (techCategoryResult.data && techCategoryResult.data.length > 0) {
+    const categoryData = techCategoryResult.data[0];
+
+    // Only proceed if the category has an image
+    if (categoryData.image) {
+      const imageId = categoryData.image.id;
+      console.log(`Working with image: ${categoryData.image.name} (ID: ${imageId})`);
+
+      // Update the file metadata
+      // For demo purposes, we'll update the alternative text and caption
+      const updatedAltText = `Updated alt text for ${categoryData.image.name} - ${new Date().toISOString()}`;
+      const updatedCaption = `Updated caption - ${new Date().toISOString()}`;
+
+      console.log(os.EOL);
+      console.log('Updating file metadata...');
+      console.log(`  New Alt Text: ${updatedAltText}`);
+      console.log(`  New Caption: ${updatedCaption}`);
+
+      try {
+        const updatedFile = await client.files.update(imageId, {
+          alternativeText: updatedAltText,
+          caption: updatedCaption,
+        });
+
+        console.log(os.EOL);
+        console.log('File metadata updated successfully!');
+        console.log(`  Name: ${updatedFile.name}`);
+        console.log(`  Alternative Text: ${updatedFile.alternativeText || 'None'}`);
+        console.log(`  Caption: ${updatedFile.caption || 'None'}`);
+        console.log(`  Updated At: ${new Date(updatedFile.updatedAt).toLocaleString()}`);
+      } catch (error) {
+        console.error('Error updating file:', error);
+      }
+    } else {
+      console.log('No image associated with this category to update');
+    }
+  } else {
+    console.log(
+      'Tech category not found. Make sure you have a category with slug "tech" in your Strapi instance.'
+    );
+  }
 }
 
 main().catch(console.error);

demo/node-typescript/src/index.ts

@@ -1,5 +1,6 @@
 import { strapi } from '@strapi/client';
 import * as dotenv from 'dotenv';
+import * as os from 'os';
 dotenv.config();
 
 const api_token = process.env.FULL_ACCESS_TOKEN; // READ_ONLY_TOKEN is also available
@@ -74,10 +75,13 @@ async function runDemo() {
   await demonstrateBasicCategoryFunctionality();
   await demonstrateCategoryImageInteractions();
   await demonstrateDirectFileOperations();
+  await demonstrateFileUpdates();
 }
 
 async function demonstrateBasicCategoryFunctionality() {
-  console.log('\n=== Basic Category Data ===\n');
+  console.log(os.EOL);
+  console.log('=== Basic Category Data ===');
+  console.log(os.EOL);
 
   const categories = client.collection('categories');
 
@@ -90,7 +94,9 @@ async function demonstrateBasicCategoryFunctionality() {
 }
 
 async function demonstrateCategoryImageInteractions() {
-  console.log('\n=== Categories with their images ===\n');
+  console.log(os.EOL);
+  console.log('=== Categories with their images ===');
+  console.log(os.EOL);
 
   const categories = client.collection('categories');
 
@@ -115,7 +121,9 @@ async function demonstrateCategoryImageInteractions() {
 }
 
 async function demonstrateDirectFileOperations() {
-  console.log('\n=== Direct file queries ===\n');
+  console.log(os.EOL);
+  console.log('=== Direct file queries ===');
+  console.log(os.EOL);
 
   const categories = client.collection('categories');
 
@@ -139,7 +147,9 @@ async function demonstrateDirectFileOperations() {
 
       // Get the specific file by ID
       const fileInfo = (await client.files.findOne(imageId)) as unknown as FileAttributes;
-      console.log('\nFile details:');
+
+      console.log(os.EOL);
+      console.log('File details:');
       console.log(`  Name: ${fileInfo.name}`);
       console.log(`  Alternative Text: ${fileInfo.alternativeText || 'None'}`);
       console.log(`  Caption: ${fileInfo.caption || 'None'}`);
@@ -152,6 +162,66 @@ async function demonstrateDirectFileOperations() {
   }
 }
 
+async function demonstrateFileUpdates() {
+  console.log(os.EOL);
+  console.log('=== File Update Operations ===');
+  console.log(os.EOL);
+
+  const categories = client.collection('categories');
+
+  // Get a specific category using find with a filter
+  const techCategoryResult = (await categories.find({
+    filters: {
+      slug: {
+        $eq: 'tech',
+      },
+    },
+    populate: ['image'],
+  })) as unknown as CategoryResponse;
+
+  if (techCategoryResult.data && techCategoryResult.data.length > 0) {
+    const categoryData = techCategoryResult.data[0];
+
+    // Only proceed if the category has an image
+    if (categoryData.image) {
+      const imageId = categoryData.image.id;
+      console.log(`Working with image: ${categoryData.image.name} (ID: ${imageId})`);
+
+      // Update the file metadata
+      // For demo purposes, we'll update the alternative text and caption
+      const updatedAltText = `Updated alt text for ${categoryData.image.name} - ${new Date().toISOString()}`;
+      const updatedCaption = `Updated caption - ${new Date().toISOString()}`;
+
+      console.log(os.EOL);
+      console.log('Updating file metadata...');
+      console.log(`  New Alt Text: ${updatedAltText}`);
+      console.log(`  New Caption: ${updatedCaption}`);
+
+      try {
+        const updatedFile = await client.files.update(imageId, {
+          alternativeText: updatedAltText,
+          caption: updatedCaption,
+        });
+
+        console.log(os.EOL);
+        console.log('File metadata updated successfully!');
+        console.log(`  Name: ${updatedFile.name}`);
+        console.log(`  Alternative Text: ${updatedFile.alternativeText || 'None'}`);
+        console.log(`  Caption: ${updatedFile.caption || 'None'}`);
+        console.log(`  Updated At: ${new Date(updatedFile.updatedAt).toLocaleString()}`);
+      } catch (error) {
+        console.error('Error updating file:', error);
+      }
+    } else {
+      console.log('No image associated with this category to update');
+    }
+  } else {
+    console.log(
+      'Tech category not found. Make sure you have a category with slug "tech" in your Strapi instance.'
+    );
+  }
+}
+
 // Helper function to format file sizes
 function formatFileSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
@@ -163,7 +233,8 @@ function formatFileSize(bytes: number): string {
 // Run the demo
 runDemo()
   .then(() => {
-    console.log('\nDemo completed successfully!');
+    console.log(os.EOL);
+    console.log('Demo completed successfully!');
   })
   .catch((error) => {
     console.error('Error running demo:', error);

src/files/constants.ts

@@ -1 +1 @@
-export const FILE_API_PREFIX = '/upload/files';
+export const FILE_API_PREFIX = '/upload';

src/files/manager.ts

@@ -5,7 +5,7 @@ import { URLHelper } from '../utilities';
 
 import { FILE_API_PREFIX } from './constants';
 import { FileErrorMapper } from './errors';
-import { FileQueryParams, FileListResponse, FileResponse } from './types';
+import { FileQueryParams, FileListResponse, FileResponse, FileUpdateData } from './types';
 
 const debug = createDebug('strapi:files');
 
@@ -90,7 +90,7 @@ export class FilesManager {
     debug('finding files');
 
     try {
-      let url = FILE_API_PREFIX;
+      let url = `${FILE_API_PREFIX}/files`;
 
       if (queryParams) {
         url = URLHelper.appendQueryParams(url, queryParams);
@@ -130,7 +130,7 @@ export class FilesManager {
   async findOne(fileId: number): Promise<FileResponse> {
     debug('finding file with ID %o', fileId);
 
-    const url = `${FILE_API_PREFIX}/${fileId}`;
+    const url = `${FILE_API_PREFIX}/files/${fileId}`;
     const client = this.createFileHttpClient(fileId);
 
     try {
@@ -146,4 +146,50 @@ export class FilesManager {
       throw error;
     }
   }
+
+  /**
+   * Updates metadata for an existing file.
+   *
+   * @param fileId - The numeric identifier of the file to update.
+   * @param fileInfo - An object containing the fields to update.
+   * @returns A promise that resolves to the updated file object.
+   *
+   * @throws {FileNotFoundError} if the file with the specified ID does not exist.
+   * @throws {HTTPError} if the HTTP client encounters connection issues, the server is unreachable, or authentication fails.
+   *
+   * @example
+   * ```typescript
+   * const filesManager = new FilesManager(httpClient);
+   *
+   * const updatedFile = await filesManager.update(1, {
+   *   name: 'New file name',
+   *   alternativeText: 'Descriptive alt text for accessibility',
+   *   caption: 'A caption for the file'
+   * });
+   *
+   * console.log(updatedFile); // Updated file object
+   * ```
+   */
+  async update(fileId: number, fileInfo: FileUpdateData): Promise<FileResponse> {
+    debug('updating file with ID %o with data %o', fileId, fileInfo);
+
+    try {
+      const url = `${FILE_API_PREFIX}?id=${fileId}`;
+      const client = this.createFileHttpClient(fileId);
+
+      // Create FormData and add fileInfo as JSON string
+      const formData = new FormData();
+      formData.append('fileInfo', JSON.stringify(fileInfo));
+
+      const response = await client.post(url, formData);
+      const json = await response.json();
+
+      debug('successfully updated file with ID %o', fileId);
+
+      return json;
+    } catch (error) {
+      debug('error updating file with ID %o: %o', fileId, error);
+      throw error;
+    }
+  }
 }

src/files/types.ts

@@ -18,6 +18,15 @@ export interface FileQueryParams {
   sort?: string | string[];
 }
 
+/**
+ * Interface defining the fields that can be updated for a file.
+ */
+export interface FileUpdateData {
+  name?: string;
+  alternativeText?: string;
+  caption?: string;
+}
+
 /**
  * Response structure for a single file from the Strapi upload plugin.
  * This interface represents the actual response structure from the API.