Client Setup

The DropperClient is the main entry point for interacting with the Dropper API. It handles authentication, file uploads, and all file/folder operations.

Installation

First, install the core package:

npm install @dropper/core

Basic Initialization

Create a new client instance with your publishable key:

import { DropperClient } from '@dropper/core'

const client = new DropperClient({
  publishableKey: 'pk_dropper_test_xxx',
})

Configuration Options

DropperClientConfig

interface DropperClientConfig {
  publishableKey: string  // Required: Your Dropper publishable key
  baseUrl?: string        // Optional: Custom API URL (default: http://localhost:5000)
}

Custom Base URL

For production or self-hosted instances, specify a custom base URL:

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

Authentication

The client automatically handles authentication using your publishable key. Every request includes an Authorization header with a Bearer token.

Publishable Key Format

Publishable keys follow this format:

pk_dropper_{environment}_{key}
  • Environment: test or live
  • Key: Alphanumeric string

Examples:

  • Test: pk_dropper_test_abc123xyz
  • Live: pk_dropper_live_xyz789abc

Getting Your API Key

  1. Sign up at dropper.dev
  2. Create a new app in your dashboard
  3. Copy your publishable key from the API keys section

Security Note: Publishable keys are safe to use in client-side code. They only allow file uploads and reads, not administrative operations.

Error Handling

The client includes automatic error handling with structured error responses:

try {
  const file = await client.uploadFile(file)
  console.log('Upload successful:', file)
} catch (error) {
  // Error is automatically formatted as ApiError
  console.error('Upload failed:', error.message)
  console.error('Status code:', error.statusCode)
}

ApiError Interface

interface ApiError {
  message: string      // Human-readable error message
  statusCode: number   // HTTP status code
  error?: string       // Error type
  details?: unknown    // Additional error details
}

Request Interceptors

The client uses Axios interceptors for:

  1. Request Interceptor: Adds Authorization header to every request
  2. Response Interceptor: Formats errors into consistent ApiError objects

Client Methods

Once initialized, the client provides methods for:

  • File Operations: Upload, list, get, delete files
  • Folder Operations: Create, list, get, update, delete folders

See the following pages for detailed documentation:

Complete Example

import { DropperClient } from '@dropper/core'

// Initialize client
const client = new DropperClient({
  publishableKey: process.env.DROPPER_KEY!,
  baseUrl: 'https://api.dropper.com',
})

// Upload a file
async function uploadFile(file: File) {
  try {
    const result = await client.uploadFile(file, {
      onProgress: (progress) => {
        console.log(`Upload progress: ${progress}%`)
      },
    })
    
    console.log('File uploaded successfully!')
    console.log('URL:', result.url)
    console.log('File ID:', result.id)
    
    return result
  } catch (error) {
    console.error('Upload failed:', error)
    throw error
  }
}

// List files
async function listFiles() {
  try {
    const response = await client.listFiles({
      page: 1,
      limit: 20,
      sortBy: 'createdAt',
      sortOrder: 'desc',
    })
    
    console.log(`Found ${response.total} files`)
    response.data.forEach((file) => {
      console.log(`- ${file.originalFilename} (${file.size} bytes)`)
    })
    
    return response
  } catch (error) {
    console.error('Failed to list files:', error)
    throw error
  }
}

Environment Variables

Store your API key in environment variables:

Next.js

# .env.local
NEXT_PUBLIC_DROPPER_KEY=pk_dropper_test_xxx

Vite

# .env
VITE_DROPPER_KEY=pk_dropper_test_xxx

Node.js

# .env
DROPPER_KEY=pk_dropper_test_xxx

Then use it in your code:

const client = new DropperClient({
  publishableKey: process.env.NEXT_PUBLIC_DROPPER_KEY!, // Next.js
  // or
  publishableKey: import.meta.env.VITE_DROPPER_KEY,     // Vite
  // or
  publishableKey: process.env.DROPPER_KEY!,             // Node.js
})

TypeScript Support

The client is fully typed with TypeScript:

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

const config: DropperClientConfig = {
  publishableKey: 'pk_dropper_test_xxx',
}

const client = new DropperClient(config)

Next Steps