### Start AI Image Generation Job (curl)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Initiates an AI image generation job with a specified prompt, record ID, and optional attachment files. The request returns a job ID for status tracking.

```curl
curl -X POST "/plugin/{pluginInstanceId}/create-image-generation-job" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains",
    "recordId": "42",
    "requestAttachmentFiles": []
  }'
```

--------------------------------

### Direct Browser Upload Workflow (TypeScript & JavaScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Demonstrates the complete workflow for frontend direct-to-S3 uploads. It involves getting a signed URL from the backend, uploading the file directly to S3, and then committing the upload to a record.

```javascript
// Frontend JavaScript
async function uploadFile(file, recordId) {
  // 1. Get signed upload URL from backend
  const urlResponse = await fetch('/api/get-upload-url', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      recordId,
      filename: file.name,
      contentType: file.type,
      size: file.size,
    }),
  });
  const { uploadUrl, filePath, uploadExtraParams } = await urlResponse.json();

  // 2. Upload directly to S3
  const headers = { 'Content-Type': file.type };
  if (uploadExtraParams) {
    Object.assign(headers, uploadExtraParams);
  }

  const uploadResponse = await fetch(uploadUrl, {
    method: 'PUT',
    headers,
    body: file,
  });

  if (!uploadResponse.ok) {
    throw new Error('Upload failed');
  }

  // 3. Commit upload to record
  const commitResponse = await fetch('/api/commit-upload', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ recordId, filePath }),
  });

  return commitResponse.json();
}

// Backend Express routes
app.post('/api/get-upload-url', async (req, res) => {
  const { recordId, filename, contentType, size } = req.body;
  const result = await uploadPlugin.getUploadUrl({
    recordId,
    filename,
    contentType,
    size,
  });
  res.json(result);
});

app.post('/api/commit-upload', async (req, res) => {
  const { recordId, filePath } = req.body;
  const result = await uploadPlugin.commitUrlToUpdateExistingRecord({
    recordId,
    filePath,
    adminUser: req.adminUser,
    extra: { headers: req.headers },
  });
  res.json(result);
});
```

--------------------------------

### Plugin REST Endpoints (Bash)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Provides examples of using cURL to interact with the plugin's REST endpoints for file upload URL generation and file download URL retrieval. These endpoints are automatically exposed for frontend integration.

```bash
# Get signed upload URL
curl -X POST "/plugin/{pluginInstanceId}/get_file_upload_url" \
  -H "Content-Type: application/json" \
  -d '{
    "originalFilename": "photo",
    "contentType": "image/png",
    "size": 1024000,
    "originalExtension": "png",
    "recordPk": "42"
  }'
# Response: { "uploadUrl": "...", "filePath": "...", "uploadExtraParams": {...}, "previewUrl": "..." }

# Get download URL for a file
curl -X POST "/plugin/{pluginInstanceId}/get-file-download-url" \
  -H "Content-Type: application/json" \
  -d '{ "filePath": "uploads/abc123.png" }'
# Response: { "url": "https://..." }
```

--------------------------------

### Get File Download URL (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Generates a presigned download URL for a file. The URL has a default expiration of 30 minutes, but this can be customized. Requires the file path and an optional expiration time in seconds.

```typescript
// Get download URL for a file path
const downloadUrl = await uploadPlugin.getFileDownloadUrl(
  'uploads/abc123.png',
  3600 // expires in 1 hour (optional, default 1800 seconds)
);

console.log(downloadUrl);
// 'https://bucket.s3.amazonaws.com/uploads/abc123.png?X-Amz-Signature=...'
```

--------------------------------

### Get Average AI Image Generation Duration Stats (curl)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Fetches statistics on the average duration of AI image generation jobs. It provides total calls, total duration, and the calculated average duration.

```curl
curl -X GET "/plugin/{pluginInstanceId}/averageDuration"
```

--------------------------------

### POST /plugin/{pluginInstanceId}/get-file-download-url

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Retrieves a temporary signed download URL for a stored file.

```APIDOC
## POST /plugin/{pluginInstanceId}/get-file-download-url

### Description
Returns a presigned download URL for a file stored in the configured storage adapter.

### Method
POST

### Endpoint
/plugin/{pluginInstanceId}/get-file-download-url

### Parameters
#### Request Body
- **filePath** (string) - Required - The path of the file to download.

### Request Example
{
  "filePath": "uploads/abc123.png"
}

### Response
#### Success Response (200)
- **url** (string) - The signed download URL.
```

--------------------------------

### Upload File from Buffer to New Record (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Uploads a file from a buffer, creates a new record in the AdminForth resource, and returns the file path, preview URL, and the new record's primary key. This is useful for server-side file processing workflows.

```typescript
import UploadPlugin from '@adminforth/upload';

// Assuming plugin is already configured and attached to a resource
const uploadPlugin: UploadPlugin = getUploadPlugin();

// Upload file from buffer and create new record
const result = await uploadPlugin.uploadFromBufferToNewRecord({
  filename: 'product-image.png',
  contentType: 'image/png',
  buffer: fs.readFileSync('/path/to/image.png'),
  adminUser: { id: 'admin-123', email: 'admin@example.com' },
  extra: { headers: req.headers },
  recordAttributes: {
    title: 'New Product',
    description: 'Product description',
    status: 'active',
  },
});

console.log(result);
// { 
//   path: 'uploads/abc123-uuid.png',
//   previewUrl: 'https://bucket.s3.amazonaws.com/uploads/abc123-uuid.png?signature=...',
//   newRecordPk: 42
// }
```

--------------------------------

### Configure AdminForth Upload Plugin with S3 Storage

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Sets up the AdminForth Upload Plugin, specifying the S3 storage adapter, path column, file restrictions, and optional AI image generation. This configuration is essential for the plugin's core functionality.

```typescript
import UploadPlugin from '@adminforth/upload';
import { S3StorageAdapter } from 'adminforth';

const uploadPlugin = new UploadPlugin({
  // Column in your resource that stores the file path
  pathColumnName: 'image_path',

  // Storage adapter for S3-compatible storage
  storageAdapter: new S3StorageAdapter({
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),

  // Custom file path generator
  filePath: ({ originalFilename, originalExtension, contentType, record }) => {
    const uuid = crypto.randomUUID();
    return `uploads/${uuid}.${originalExtension}`;
  },

  // File restrictions
  allowedFileExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webp'],
  maxFileSize: 10 * 1024 * 1024, // 10MB

  // Preview configuration
  preview: {
    usePreviewComponents: true,
    maxWidth: '200px',
    maxListWidth: '100px',
    maxShowWidth: '400px',
    // Optional CDN URL generator
    previewUrl: ({ filePath }) => `https://cdn.example.com/${filePath}`,
  },

  // Optional AI image generation
  generation: {
    adapter: new OpenAIImageAdapter({
      apiKey: process.env.OPENAI_API_KEY,
    }),
    outputSize: '1024x1024',
    countToGenerate: 3,
    generationPrompt: 'Generate a photo of {{ model }} in {{ color }} color',
    rateLimit: {
      limit: '5/1d', // 5 requests per day
      errorMessage: 'Rate limit exceeded',
    },
  },
});
```

--------------------------------

### Generate Signed Upload URL for Direct Browser Uploads (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Generates a signed URL that allows direct browser-to-storage uploads to an S3 bucket. The response includes the upload URL, the final file path, and any necessary extra parameters for the upload request.

```typescript
// Backend: Generate upload URL
const { uploadUrl, filePath, uploadExtraParams, pathColumnName } =
  await uploadPlugin.getUploadUrl({
    recordId: 42, // optional - for existing record
    filename: 'photo.png',
    contentType: 'image/png',
    size: 1024000, // optional - validates against maxFileSize
  });

// Response to frontend:
// { 
//   uploadUrl: 'https://bucket.s3.amazonaws.com/uploads/uuid.png?X-Amz-Signature=...',
//   filePath: 'uploads/uuid.png',
//   uploadExtraParams: { 'x-amz-acl': 'private' },
//   pathColumnName: 'image_path'
// }
```

--------------------------------

### AI Image Generation API

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Endpoints for initiating and monitoring AI image generation jobs.

```APIDOC
## POST /plugin/{pluginInstanceId}/create-image-generation-job

### Description
Starts an AI image generation job with a given prompt and optional record ID.

### Method
POST

### Endpoint
/plugin/{pluginInstanceId}/create-image-generation-job

### Parameters
#### Path Parameters
- **pluginInstanceId** (string) - Required - The ID of the plugin instance.

#### Query Parameters
None

#### Request Body
- **prompt** (string) - Required - The text prompt for image generation.
- **recordId** (string) - Optional - The ID of the record associated with the image generation.
- **requestAttachmentFiles** (array) - Optional - A list of files to be used as attachments for image generation.

### Request Example
```json
{
  "prompt": "A beautiful sunset over mountains",
  "recordId": "42",
  "requestAttachmentFiles": []
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **jobId** (string) - The ID of the generated job.

#### Response Example
```json
{
  "ok": true,
  "jobId": "uuid-job-id"
}
```

---

## POST /plugin/{pluginInstanceId}/get-image-generation-job-status

### Description
Retrieves the status and results of an AI image generation job.

### Method
POST

### Endpoint
/plugin/{pluginInstanceId}/get-image-generation-job-status

### Parameters
#### Path Parameters
- **pluginInstanceId** (string) - Required - The ID of the plugin instance.

#### Query Parameters
None

#### Request Body
- **jobId** (string) - Required - The ID of the image generation job to check.

### Request Example
```json
{
  "jobId": "uuid-job-id"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **job** (object) - An object containing job details.
  - **status** (string) - The current status of the job (e.g., "completed").
  - **images** (array) - A list of URLs for the generated images.

#### Response Example
```json
{
  "ok": true,
  "job": {
    "status": "completed",
    "images": ["url1", "url2"]
  }
}
```
```

--------------------------------

### POST /plugin/{pluginInstanceId}/get_file_upload_url

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Generates a signed URL for direct-to-S3 file uploads from the browser.

```APIDOC
## POST /plugin/{pluginInstanceId}/get_file_upload_url

### Description
Generates a presigned URL allowing the frontend to upload files directly to storage.

### Method
POST

### Endpoint
/plugin/{pluginInstanceId}/get_file_upload_url

### Parameters
#### Request Body
- **originalFilename** (string) - Required - The name of the file.
- **contentType** (string) - Required - MIME type of the file.
- **size** (number) - Required - File size in bytes.
- **originalExtension** (string) - Required - File extension.
- **recordPk** (string) - Optional - Primary key of the record.

### Request Example
{
  "originalFilename": "photo",
  "contentType": "image/png",
  "size": 1024000,
  "originalExtension": "png",
  "recordPk": "42"
}

### Response
#### Success Response (200)
- **uploadUrl** (string) - The signed URL for the PUT request.
- **filePath** (string) - The path where the file will be stored.
- **uploadExtraParams** (object) - Additional headers required for the upload.
- **previewUrl** (string) - A URL to preview the file.
```

--------------------------------

### Average Generation Duration Stats API

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Retrieves statistics on the average duration of image generation jobs.

```APIDOC
## GET /plugin/{pluginInstanceId}/averageDuration

### Description
Fetches statistics about the average duration of image generation calls.

### Method
GET

### Endpoint
/plugin/{pluginInstanceId}/averageDuration

### Parameters
#### Path Parameters
- **pluginInstanceId** (string) - Required - The ID of the plugin instance.

#### Query Parameters
None

#### Request Body
None

### Request Example
```
GET /plugin/{pluginInstanceId}/averageDuration
```

### Response
#### Success Response (200)
- **totalCalls** (integer) - The total number of generation calls made.
- **totalDuration** (number) - The total duration of all generation calls in seconds.
- **averageDuration** (number) - The average duration of generation calls in seconds.

#### Response Example
```json
{
  "totalCalls": 10,
  "totalDuration": 45.2,
  "averageDuration": 4.52
}
```
```

--------------------------------

### Upload File from Buffer to Existing Record (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Uploads a file from a buffer and updates the path column of an existing AdminForth record. The previous file associated with the record is automatically marked for cleanup based on defined lifecycle rules.

```typescript
// Update existing record with new file
const result = await uploadPlugin.uploadFromBufferToExistingRecord({
  recordId: 42,
  filename: 'updated-image.jpg',
  contentType: 'image/jpeg',
  buffer: imageBuffer,
  adminUser: currentAdmin,
  extra: { headers: req.headers },
});

console.log(result);
// { 
//   path: 'uploads/new-uuid.jpg',
//   previewUrl: 'https://bucket.s3.amazonaws.com/uploads/new-uuid.jpg?signature=...'
// }
```

--------------------------------

### Commit Upload URL to New Record (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Commits a direct upload to create a new record. It sets the file path and any additional attributes for the new record. Requires the file path, admin user, and optional record attributes.

```typescript
const result = await uploadPlugin.commitUrlToNewRecord({
  filePath: 'uploads/uuid.png',
  adminUser: currentAdmin,
  extra: { headers: req.headers },
  recordAttributes: {
    title: 'New Upload',
    category: 'images',
  },
});

console.log(result);
// {
//   path: 'uploads/uuid.png',
//   previewUrl: 'https://cdn.example.com/uploads/uuid.png',
//   newRecordPk: 43
// }
```

--------------------------------

### Mark File for Deletion (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Marks a file for automatic cleanup by S3 lifecycle rules. This is typically called automatically when records are deleted or files are replaced.

```typescript
// Mark file for future deletion by lifecycle rules
await uploadPlugin.markKeyForDeletion('uploads/old-file.png');
```

--------------------------------

### POST /api/commit-upload (Update Record)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Commits a previously uploaded file to an existing database record.

```APIDOC
## POST /api/commit-upload

### Description
Updates an existing record with the file path after the browser completes the direct upload.

### Method
POST

### Endpoint
/api/commit-upload

### Parameters
#### Request Body
- **recordId** (number) - Required - ID of the record to update.
- **filePath** (string) - Required - Path returned from the upload URL request.

### Request Example
{
  "recordId": 42,
  "filePath": "uploads/uuid.png"
}

### Response
#### Success Response (200)
- **path** (string) - The stored file path.
- **previewUrl** (string) - The URL to access the file.
```

--------------------------------

### Mark File for Permanent Storage (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Marks a file as permanently used, preventing its automatic deletion by S3 lifecycle rules. This is typically called automatically during record creation or updates.

```typescript
// Mark file as permanent (not candidate for cleanup)
await uploadPlugin.markKeyForNotDeletion('uploads/important-file.png');
```

--------------------------------

### Commit Upload URL to Update Existing Record (TypeScript)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Commits a direct upload to an existing record. It updates the record's file path and handles cleanup of the old file. Requires the record ID, file path, and admin user information.

```typescript
const result = await uploadPlugin.commitUrlToUpdateExistingRecord({
  recordId: 42,
  filePath: 'uploads/uuid.png', // from getUploadUrl response
  adminUser: currentAdmin,
  extra: { headers: req.headers },
});

console.log(result);
// {
//   path: 'uploads/uuid.png',
//   previewUrl: 'https://bucket.s3.amazonaws.com/uploads/uuid.png?signature=...'
// }
```

--------------------------------

### Check AI Image Generation Job Status (curl)

Source: https://context7.com/devforth/adminforth-upload/llms.txt

Retrieves the status of an AI image generation job using its job ID. The response includes the job status and a list of generated image URLs if completed.

```curl
curl -X POST "/plugin/{pluginInstanceId}/get-image-generation-job-status" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "uuid-job-id" }'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.