imgfans-js

Imgfans JavaScript Client

Official JavaScript/TypeScript client library for Imgfans - A free, fast, and reliable image hosting service.

Features

• 🚀 Easy to use API
• 🔄 Automatic input format detection
• 📦 TypeScript support
• 🔒 Secure file uploads
• 💪 Comprehensive error handling
• 🛠 Multiple reference format support
• 📝 Detailed documentation

Installation

npm install imgfans-js
# or
yarn add imgfans-js

Quick Start

import ImgfansClient from 'imgfans-js';

// Initialize the client
const client = new ImgfansClient({
  token: 'your_api_token'
});

// Upload an image
const uploadImage = async () => {
  try {
    // Upload from URL
    const urlResponse = await client.upload('https://example.com/image.jpg');
    
    // Upload from file path
    const fileResponse = await client.upload('/path/to/local/image.png');
    
    // Upload from base64
    const base64Response = await client.upload('data:image/png;base64,iVBORw0KGgo...');
    
    // Upload from buffer
    const bufferResponse = await client.upload(imageBuffer);
    
    // Get references
    const refs = client.getAllReferences(urlResponse);
    console.log('Direct Link:', refs.directLink);
    console.log('Markdown:', refs.markdown);
    console.log('HTML:', refs.html);
  } catch (error) {
    if (error instanceof ImgfansError) {
      console.error('Upload failed:', error.message);
    }
  }
};

Supported Input Types

The upload method accepts various input formats:

• URLs (http:// or https://)
• File paths (local files)
• Base64 encoded images
• Buffers
• Blobs
• ReadableStreams

The library automatically detects the input type and processes it accordingly.

API Reference

Constructor

new ImgfansClient(config: ImgfansConfig)

Configuration options:

• token (required): Your Imgfans API token
• baseURL (optional): Custom API endpoint (defaults to https://imgfans.com/api/v1)

Methods

upload(input, filename?)

Upload a file to Imgfans.

Parameters:

• input: URL, file path, base64 string, Buffer, Blob, or ReadableStream
• filename (optional): Custom filename for the upload

Returns: Promise with upload response

getDirectLink(response)

Get direct link from upload response.

getMarkdownCode(response)

Get markdown code from upload response.

getHtmlCode(response)

Get HTML code from upload response.

getAllReferences(response)

Get all reference codes (direct link, download link, BBCode, HTML, Markdown).

Error Handling

The library provides detailed error messages for common issues:

try {
  await client.upload(input);
} catch (error) {
  if (error instanceof ImgfansError) {
    console.error(`Error: ${error.message}`);
    console.error(`Status code: ${error.statusCode}`);
    // Errors include user-friendly messages for common issues:
    // - File size too large
    // - Unsupported file type
    // - Invalid token
    // - Network connectivity issues
    // - Invalid input format
  }
}

Examples

Upload from URL

const response = await client.upload('https://example.com/image.jpg');

Upload from File Path

const response = await client.upload('/path/to/local/image.png');

Upload from Base64

const response = await client.upload('data:image/png;base64,iVBORw0KGgo...');

Upload with Custom Filename

const response = await client.upload(imageBuffer, 'custom-name.jpg');

Get All Reference Formats

const refs = client.getAllReferences(response);
console.log(refs.directLink);    // Direct link
console.log(refs.downloadLink);  // Download link
console.log(refs.bbcode);       // BBCode
console.log(refs.html);         // HTML code
console.log(refs.markdown);     // Markdown code

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details

Support

• Visit Imgfans for more information
• Submit issues on GitHub