@govishbucket/govishbucketuploader

Multer-like middleware for uploading files to GovishBucket storage service with API key authentication.

Installation

Install from local directory

# In your backend project
npm install /path/to/govishbucketuploader
# or if in the same workspace
npm install ../govishbucketuploader

Option 2: Install from npm (when published)

npm install @govishbucket/govishbucketuploader

Quick Start

import express, { Request, Response } from 'express';
import { createGovishBucketUploader } from '@govishbucket/govishbucketuploader';
import { UploadRequest } from '@govishbucket/govishbucketuploader';

const app = express();

// Initialize the uploader
const uploader = createGovishBucketUploader({
  apiUrl: process.env.GOVISHBUCKET_API_URL || 'http://localhost:4000/api/v1/storage',
  accessKeyId: process.env.GOVISHBUCKET_ACCESS_KEY_ID || 'ak_your_access_key_id',
  secretAccessKey: process.env.GOVISHBUCKET_SECRET_ACCESS_KEY || 'your_secret_access_key',
  bucket: process.env.GOVISHBUCKET_BUCKET || 'my-bucket',
});

// Single file upload
app.post('/upload', uploader.single('file'), (req: Request, res: Response) => {
  const uploadReq = req as UploadRequest;
  if (!uploadReq.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }
  
  res.json({
    message: 'File uploaded successfully',
    file: uploadReq.file.govishBucket
  });
});

// Multiple files upload
app.post('/upload-multiple', uploader.array('files'), (req: Request, res: Response) => {
  const uploadReq = req as UploadRequest;
  const files = uploadReq.files;
  if (!files || files.length === 0) {
    return res.status(400).json({ error: 'No files uploaded' });
  }
  
  res.json({
    message: 'Files uploaded successfully',
    files: files.map(file => file.govishBucket)
  });
});

// Error handling
app.use((err: Error, req: Request, res: Response, next: any) => {
  console.error('Upload error:', err);
  res.status(500).json({ error: 'Upload failed', message: err.message });
});

app.listen(3000);

Features

• ✅ Multer-compatible API (.single(), .array(), .fields(), etc.)
• ✅ API key authentication
• ✅ Environment variable support
• ✅ Dynamic bucket selection
• ✅ Custom key generators
• ✅ File size and type limits
• ✅ Metadata and tags support
• ✅ TypeScript support

Configuration

Basic Options

const uploader = createGovishBucketUploader({
  apiUrl: 'https://api.example.com/api/v1/storage',  // Required: Your GovishBucket API URL
  accessKeyId: 'ak_...',                              // Required: Your API key ID
  secretAccessKey: 'secret...',                       // Required: Your API key secret
  bucket: 'my-bucket'                                 // Required: Bucket name
});

Environment Variables

You can configure the uploader using environment variables:

GOVISHBUCKET_API_URL=http://localhost:4000/api/v1/storage
GOVISHBUCKET_ACCESS_KEY_ID=ak_your_access_key_id
GOVISHBUCKET_SECRET_ACCESS_KEY=your_secret_access_key
GOVISHBUCKET_BUCKET=my-bucket

Advanced Options

const uploader = createGovishBucketUploader({
  // Required options
  apiUrl: 'https://api.example.com/api/v1/storage',
  accessKeyId: process.env.GOVISHBUCKET_ACCESS_KEY_ID!,
  secretAccessKey: process.env.GOVISHBUCKET_SECRET_ACCESS_KEY!,
  
  // Dynamic bucket from request
  bucket: (req) => req.params.bucketName,
  
  // Custom key generator
  keyGenerator: (req, file) => {
    return `uploads/${req.user.id}/${Date.now()}-${file.originalname}`;
  },
  
  // File limits
  limits: {
    fileSize: 10 * 1024 * 1024,  // 10MB
    files: 5
  },
  
  // File filter
  fileFilter: (req, file, cb) => {
    if (file.mimetype.startsWith('image/')) {
      cb(null, true);
    } else {
      cb(new Error('Only images allowed'));
    }
  },
  
  // Metadata
  metadata: (req, file) => ({
    uploadedBy: req.user.id,
    originalName: file.originalname
  }),
  
  // Tags
  tags: {
    environment: 'production',
    source: 'web-upload'
  }
});

Usage Examples

Single File Upload

app.post('/upload', uploader.single('file'), (req: Request, res: Response) => {
  const uploadReq = req as UploadRequest;
  if (!uploadReq.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }
  
  res.json({
    message: 'File uploaded successfully',
    file: uploadReq.file.govishBucket
  });
});

Multiple Files

app.post('/upload-multiple', uploader.array('files'), (req: Request, res: Response) => {
  const uploadReq = req as UploadRequest;
  const files = uploadReq.files;
  if (!files || files.length === 0) {
    return res.status(400).json({ error: 'No files uploaded' });
  }
  
  res.json({
    message: 'Files uploaded successfully',
    files: files.map(file => file.govishBucket)
  });
});

Named Fields

app.post('/upload-fields', uploader.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 10 }
]), (req: Request, res: Response) => {
  const uploadReq = req as UploadRequest;
  const files = uploadReq.files as { [fieldname: string]: Express.Multer.File[] };
  
  res.json({
    message: 'Files uploaded successfully',
    avatar: files.avatar?.[0]?.govishBucket,
    gallery: files.gallery?.map(f => f.govishBucket)
  });
});

Any Files

app.post('/upload-any', uploader.any(), (req: Request, res: Response) => {
  const uploadReq = req as UploadRequest;
  res.json({ files: uploadReq.files });
});

API Key Authentication

API keys can be provided in several ways:

1. Constructor options (recommended for single tenant)
2. Environment variables: GOVISHBUCKET_ACCESS_KEY_ID and GOVISHBUCKET_SECRET_ACCESS_KEY
3. Per-request (via request extension - advanced)

The client uses Bearer token format: Authorization: Bearer accessKeyId:secretAccessKey

Response Format

After upload, files have a govishBucket property with upload details:

{
  bucket: string;
  key: string;
  versionId: string;
  etag: string;
  size: number;
  contentType: string;
}

Example response:

{
  "message": "File uploaded successfully",
  "file": {
    "bucket": "my-bucket",
    "key": "uploads/1234567890-example.jpg",
    "versionId": "abc123-def456-ghi789",
    "etag": "d41d8cd98f00b204e9800998ecf8427e",
    "size": 1024,
    "contentType": "image/jpeg"
  }
}

Error Handling

import { GovishBucketUploadError, GovishBucketAuthenticationError } from '@govishbucket/govishbucketuploader';

app.use((err: Error, req: Request, res: Response, next: any) => {
  if (err instanceof GovishBucketAuthenticationError) {
    return res.status(401).json({ error: 'Authentication failed' });
  }
  
  if (err instanceof GovishBucketUploadError) {
    return res.status(err.statusCode).json({ error: err.message });
  }
  
  console.error('Upload error:', err);
  res.status(500).json({ error: 'Upload failed', message: err.message });
});

License

MIT