Thru MFT Web Components

A collection of web components for file upload functionality, built with Preact and TypeScript. These components provide a robust, resumable file upload experience with progress tracking, error handling, and more.

Features

• Resumable File Uploads: Automatically resume interrupted uploads
• Chunked File Transfers: Files are split into chunks for efficient uploading
• Progress Tracking: Real-time upload progress with speed and time estimations
• Drag-and-Drop Support: User-friendly file selection interface
• Conflict Resolution: Handles file conflicts with options to resume or overwrite
• Auto-Upload: Configure whether uploads start automatically
• Error Handling: Comprehensive error reporting and recovery options
• Upload Cancellation: Ability to cancel uploads in progress
• Upload Interceptor: Modify upload context before an upload begins
• Multiple File Uploads: Support for uploading multiple files simultaneously
• Server Path Selection: Choose from available server paths or automatically use the first one
• Customizable Retry Logic: Configure retry attempts and delays for failed uploads

Installation

CDN Usage

Add the following to your HTML:

<script type="module" src="https://cdn.jsdelivr.net/npm/thru-mft-webcomponents/dist/assets/main.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/thru-mft-webcomponents/dist/assets/main.css" />

NPM Installation

npm install thru-mft-webcomponents
# or
yarn add thru-mft-webcomponents
# or
pnpm add thru-mft-webcomponents

Usage

Thru Upload Web Component

The thru-upload web component provides resumable file upload functionality with progress tracking and error handling.

<thru-upload
  api-key="your-api-key"
  flow-endpoint-id="123"
  api-url="https://your-api-url.com/api"
  auto-upload="true"
  assume-first-server-path="false"
  min-retry-delay="1000"
  retry-attempts="3"
></thru-upload>

Attributes

| Attribute | Type | Required | Default | Description | | -------------------------- | ------- | -------- | ------- | ------------------------------------------------------------- | | api-key | string | Yes | - | Your API key for authentication | | flow-endpoint-id | number | Yes | - | ID of the flow endpoint to upload to | | api-url | string | Yes | - | Base URL of your API | | auto-upload | boolean | No | true | Whether to start upload automatically when files are selected | | assume-first-server-path | boolean | No | false | Whether to automatically use the first available server path | | min-retry-delay | number | No | - | Minimum delay between retry attempts in milliseconds | | retry-attempts | number | No | - | Maximum number of retry attempts for failed uploads |

Events

The component dispatches the following custom events:

• thru-upload-completed: Fired when an upload is completed successfully

  window.addEventListener("thru-upload-completed", (e) => {
    console.log(e.detail) // Contains upload details including id and uploadContext
  })

• upload-files-added: Fired when files are added to the upload queue

  window.addEventListener("upload-files-added", (e) => {
    console.log(e.detail.files) // Contains file details
  })

Methods

The component exposes the following methods:

• triggerUploads(): Manually trigger the upload of selected files

  const uploadedFiles = await document.querySelector("thru-upload").triggerUploads()

Upload Interceptor

You can add an upload interceptor to modify the upload context before the upload begins:

const thruUploadElement = document.querySelector("thru-upload")
thruUploadElement.uploadInterceptor = async (context) => {
  // Modify context as needed
  context.filePath = "custom/path"
  return context
}

Resume Upload Logic

The component automatically handles resuming uploads in case of interruptions:

1. Upload sessions are saved in localStorage with key upload-session-{flowEndpointId}-{fileName}-{fileSize}
2. When the component is initialized, it checks for existing upload sessions
3. For incomplete uploads, it presents options to resume or restart the upload
4. When resuming, it retrieves the last uploaded chunk from the server and continues from there

Upload Lifecycle

The upload process follows these states:

1. Initial: Upload is being prepared
2. Waiting: Ready to start upload
3. In-progress: Upload is ongoing, showing progress, speed, and time remaining
4. Assembling: All chunks uploaded, server is assembling the file
5. Completed: Upload successfully completed
6. Error: Error occurred during upload (with retry option)

FileUpload Component (React/Preact)

The FileUpload component provides a resumable file upload functionality with progress tracking and error handling.

import { FileUpload } from "thru-mft-webcomponents"

// In your component:
<FileUpload
  id="unique-upload-id"
  fileToUpload={file}
  abortController={new AbortController()}
  initialUploadContext={{
    flowEndpointId: number,
    serverPath: string,
    fileName: string,
    fileSize: number,
    filePath: string
  }}
  updateState={(updatedFile) => {
    // Handle state updates
  }}
  autoUpload={true}
  retryDelayMs={1000} // Optional
  retryAttempts={3} // Optional
/>

Props

| Prop | Type | Required | Description | | ---------------------- | ---------------------- | -------- | -------------------------------------------- | | id | string | Yes | Unique identifier for the upload | | fileToUpload | File | Yes | The file to be uploaded | | abortController | AbortController | Yes | Controller for handling upload cancellation | | initialUploadContext | ResumableUploadContext | Yes | Initial context for the upload | | updateState | (file: any) => void | Yes | Callback for state updates | | autoUpload | boolean | Yes | Whether to start upload automatically | | retryDelayMs | number | No | Delay between retry attempts in milliseconds | | retryAttempts | number | No | Maximum number of retry attempts |

UploadModal Component (React/Preact)

The UploadModal component provides a modal interface for file uploads with drag-and-drop support.

import { UploadModal } from "thru-mft-webcomponents"

// In your component:
<UploadModal
  selectedFlowEndpointId={123}
  flowEnabled={true}
  getUploadInterceptor={() => {
    // Return your interceptor function
  }}
  autoUpload={true}
  assumeFirstServerPath={true}
  retryDelayMs={1000} // Optional
  retryAttempts={3} // Optional
/>

Props

| Prop | Type | Required | Description | | ------------------------ | -------------- | -------- | -------------------------------------------- | | selectedFlowEndpointId | number | Yes | ID of the selected flow endpoint | | flowEnabled | boolean | Yes | Whether the flow is enabled | | getUploadInterceptor | () => Function | Yes | Function to get the upload interceptor | | autoUpload | boolean | Yes | Whether to start upload automatically | | assumeFirstServerPath | boolean | Yes | Whether to assume the first server path | | retryDelayMs | number | No | Delay between retry attempts in milliseconds | | retryAttempts | number | No | Maximum number of retry attempts |

Implementation Guide

Basic HTML Implementation

1. Add the required scripts and styles to your HTML page:

<script type="module" src="https://cdn.jsdelivr.net/npm/thru-mft-webcomponents/dist/assets/main.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/thru-mft-webcomponents/dist/assets/main.css" />

2. Add the web component to your HTML:

<thru-upload
  api-key="your-api-key"
  flow-endpoint-id="123"
  api-url="https://your-api-url.com/api"
></thru-upload>

3. Optionally, add event listeners for upload events:

document.addEventListener("DOMContentLoaded", () => {
  window.addEventListener("thru-upload-completed", (e) => {
    console.log("Upload completed:", e.detail)
  })
})

Advanced Usage

Triggering Uploads Manually

If you set auto-upload="false", you'll need to trigger uploads manually:

// Get the upload component
const uploadComponent = document.querySelector("thru-upload")

// Trigger uploads when a button is clicked
document.querySelector("#upload-button").addEventListener("click", async () => {
  const results = await uploadComponent.triggerUploads()
  console.log("Upload results:", results)
})

Custom Upload Interception

Implement an upload interceptor to modify upload context:

const uploadComponent = document.querySelector("thru-upload")

uploadComponent.uploadInterceptor = async (context) => {
  // Add metadata or modify paths
  context.filePath = `user_${userId}/${context.filePath}`
  
  // You can make API calls here if needed
  const additionalData = await fetchUserUploadPreferences()
  
  // Return the modified context
  return {
    ...context,
    ...additionalData
  }
}

React/Next.js Integration

When using with React or Next.js:

import { useEffect, useRef } from "react"

// Load the web component scripts
useEffect(() => {
  const script = document.createElement("script")
  script.src = "https://cdn.jsdelivr.net/npm/thru-mft-webcomponents/dist/assets/main.js"
  script.type = "module"
  document.head.appendChild(script)
  
  const link = document.createElement("link")
  link.rel = "stylesheet"
  link.href = "https://cdn.jsdelivr.net/npm/thru-mft-webcomponents/dist/assets/main.css"
  document.head.appendChild(link)
  
  return () => {
    document.head.removeChild(script)
    document.head.removeChild(link)
  }
}, [])

// Component that uses the web component
const FileUploader = ({ apiKey, flowEndpointId, apiUrl }) => {
  const uploadRef = useRef(null)
  
  useEffect(() => {
    if (uploadRef.current) {
      // Set up interceptor
      uploadRef.current.uploadInterceptor = (context) => {
        // Modify context
        return context
      }
      
      // Listen for completion events
      const handleUploadComplete = (e) => {
        console.log("Upload completed:", e.detail)
      }
      
      window.addEventListener("thru-upload-completed", handleUploadComplete)
      
      return () => {
        window.removeEventListener("thru-upload-completed", handleUploadComplete)
      }
    }
  }, [uploadRef.current])
  
  return (
    <div>
      <thru-upload
        ref={uploadRef}
        api-key={apiKey}
        flow-endpoint-id={flowEndpointId}
        api-url={apiUrl}
        auto-upload="true"
      ></thru-upload>
      
      <button onClick={() => uploadRef.current?.triggerUploads()}>
        Upload Files
      </button>
    </div>
  )
}

Technical Details

ResumableUploadContext

The upload context contains all the information needed for the upload:

type ResumableUploadContext = {
  flowCode: string
  endpointCode: string
  flowEndpointId: number
  serverPath: string
  fileName: string
  filePath: string
  fileSize: number
  lastUploadedChunkIndex?: number
  sessionUID?: string
  reportId?: string
  chunkSize?: number
  outcome?: {
    success: boolean
    error?: any
  }
}

Chunked Upload Process

Files are uploaded in chunks of 100MB by default:

const CHUNK_SIZE = 100 * 1024 * 1024 // 100MB

The upload process:

1. Create an upload session
2. Upload chunks sequentially
3. Track upload progress
4. Commit the session when all chunks are uploaded
5. Handle errors and allow retries

CSS Customization

The component uses CSS variables for styling that can be overridden:

:root {
  --primary-color: #4051a5;
  --primary-color-bg: rgba(64, 81, 165, 0.1);
  --primary-color-dark: #062491;
  --off-theme-color: #415362;
  --off-theme-color-accent: #5f778a;
  --error-color: #d93025;
  --theme-delete-color: #d93025;
  --loader-color-bg: #e6e6e6;
}