@dropper/core

The framework-agnostic core library for Dropper file management. Use it directly in Node.js, vanilla JavaScript, or as a foundation for framework-specific packages.

Features

  • ✅ Pure TypeScript - No framework dependencies
  • ✅ Type-safe - Full TypeScript support
  • ✅ Tree-shakeable - Only import what you need
  • ✅ Universal - Works in any JavaScript environment
  • ✅ Lightweight - Minimal dependencies (axios, zod)

Installation

npm install @dropper/core

Or with your preferred package manager:

# pnpm
pnpm add @dropper/core

# yarn
yarn add @dropper/core

Quick Start

import { DropperClient } from '@dropper/core'

// Initialize the client
const client = new DropperClient({
  publishableKey: 'pk_dropper_test_xxx',
  baseUrl: 'https://api.dropper.com', // optional
})

// Upload a file
const file = new File(['content'], 'example.txt')
const result = await client.uploadFile(file, {
  onProgress: (progress) => console.log(`Progress: ${progress}%`),
})

console.log('Uploaded:', result.url)

Core Concepts

DropperClient

The main client for interacting with the Dropper API. Handles authentication, file uploads, and all file/folder operations.

const client = new DropperClient({
  publishableKey: 'pk_dropper_test_xxx',
  baseUrl: 'https://api.dropper.com', // optional
})

File Upload

Upload files with progress tracking and error handling:

const result = await client.uploadFile(file, {
  folderId: 'folder_123', // optional
  metadata: { userId: '123' }, // optional
  onProgress: (progress) => {
    console.log(`Upload progress: ${progress}%`)
  },
})

Upload Queue

Handle multiple concurrent uploads with automatic retry:

import { UploadQueue } from '@dropper/core'

const queue = new UploadQueue(client)

await queue.addFiles(files, {
  maxConcurrent: 3,
  onProgress: (item) => {
    console.log(`${item.file.name}: ${item.progress}%`)
  },
  onSuccess: (item, result) => {
    console.log(`Uploaded: ${result.url}`)
  },
  onError: (item, error) => {
    console.error(`Failed: ${item.file.name}`, error)
  },
})

Main Features

File Operations

  • Upload Files - Single or batch uploads with progress tracking
  • List Files - Paginated file listing with filters
  • Get File - Retrieve file details
  • Delete File - Remove files from storage

Folder Operations

  • Create Folders - Organize files in folders
  • List Folders - Navigate folder hierarchy
  • Get Folder - Retrieve folder details
  • Delete Folder - Remove folders and contents

Validation

Built-in validation for file types, sizes, and counts:

import { validateFiles } from '@dropper/core'

const errors = validateFiles(files, {
  accept: 'image/*',
  maxSize: 5 * 1024 * 1024, // 5MB
  maxFiles: 10,
})

if (errors.length > 0) {
  errors.forEach((error) => {
    console.error(error.message)
  })
}

Utilities

Helpful utility functions for common tasks:

import {
  formatFileSize,
  getFileExtension,
  isImage,
  isVideo,
  generateId,
} from '@dropper/core'

formatFileSize(1024) // "1 KB"
getFileExtension('photo.jpg') // "jpg"
isImage(file) // true/false
isVideo(file) // true/false
generateId() // "abc123..."

Next Steps

TypeScript Support

Full TypeScript support with exported types:

import type {
  FileResponseDto,
  FolderResponseDto,
  DropperClientConfig,
  UploadOptions,
  ListFilesParams,
} from '@dropper/core'

Framework Adapters

This core library is used by framework-specific packages:

  • React: @dropper/react - React hooks and components
  • Angular: @dropper/angular - Angular services (coming soon)
  • Vue: @dropper/vue - Vue composables (coming soon)