Insomma SDK

A powerful, Cloudinary-like SDK for media management. Upload, transform, and deliver images with ease.

⚠️ Security Warning

NEVER use this SDK in frontend/browser code!

Your API key grants full access to your bucket (upload, delete, list files). If exposed in client-side code, anyone can access your files.

✅ Use this SDK on your backend server only (Node.js, Express, Next.js API routes, etc.)

❌ Never import this SDK in React, Vue, or any browser code

// ❌ WRONG - Never do this in frontend code!
// This exposes your API key to everyone
const insomma = createClient({
  bucket: 'my-app',
  apiKey: 'mp_xxxxx'  // EXPOSED!
});

// ✅ CORRECT - Use on your backend server
// server.js (Node.js/Express)
const insomma = createClient({
  bucket: process.env.INSOMMA_BUCKET,
  apiKey: process.env.INSOMMA_API_KEY
});

// Then create API endpoints for your frontend
app.post('/api/upload', authMiddleware, async (req, res) => {
  const file = await insomma.upload(req.file);
  res.json({ url: file.transformUrl });
});

Installation

npm install insomma-sdk

Quick Start

import { createClient } from 'insomma-sdk';

// Initialize with your bucket name and API key
const insomma = createClient({
  bucket: 'my-project',           // Your bucket/project name
  apiKey: 'ins_your_api_key_here' // Your bucket's API key
});

// Upload a file
const file = await insomma.upload(myFile);

// Get a transformed thumbnail
const thumbUrl = insomma.transform(file.id)
  .resize(200, 200)
  .webp(80)
  .toUrl();

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | bucket | string | Yes | Your bucket/project name | | apiKey | string | Yes | API key for the bucket | | apiUrl | string | No | Custom API URL (default: api.insomma.cloud) | | timeout | number | No | Request timeout in ms (default: 30000) | | retries | number | No | Retry attempts (default: 3) |

const insomma = createClient({
  bucket: 'my-app-production',
  apiKey: 'ins_abc123...',
  timeout: 60000,  // 60 seconds for large uploads
  retries: 5
});

Image Transformations

The SDK provides a fluent API for building transformation URLs, similar to Cloudinary.

Basic Transformations

// Resize
const url = insomma.transform(fileId)
  .resize(800, 600)
  .toUrl();

// Resize with fit mode
const url = insomma.transform(fileId)
  .resize(400, 400)
  .fit('cover')  // cover, contain, fill, inside, outside
  .toUrl();

// Just width (maintains aspect ratio)
const url = insomma.transform(fileId)
  .width(500)
  .toUrl();

// Crop specific region
const url = insomma.transform(fileId)
  .crop(100, 100, 300, 300)  // left, top, width, height
  .toUrl();

Rotation & Flip

// Rotate
const url = insomma.transform(fileId)
  .rotate(90)
  .toUrl();

// Flip vertical
const url = insomma.transform(fileId)
  .flip()
  .toUrl();

// Flip horizontal
const url = insomma.transform(fileId)
  .flop()
  .toUrl();

Format & Quality

// Convert to WebP with quality
const url = insomma.transform(fileId)
  .webp(80)
  .toUrl();

// Convert to AVIF
const url = insomma.transform(fileId)
  .avif(75)
  .toUrl();

// Auto-detect best format (WebP/AVIF based on browser)
const url = insomma.transform(fileId)
  .auto()
  .toUrl();

// Set quality separately
const url = insomma.transform(fileId)
  .format('jpeg')
  .quality(85)
  .toUrl();

Filters

// Blur
const url = insomma.transform(fileId)
  .blur(10)  // 1-100
  .toUrl();

// Sharpen
const url = insomma.transform(fileId)
  .sharpen()
  .toUrl();

// Grayscale
const url = insomma.transform(fileId)
  .grayscale()
  .toUrl();

// Sepia
const url = insomma.transform(fileId)
  .sepia()
  .toUrl();

// Color adjustments
const url = insomma.transform(fileId)
  .brightness(1.2)   // 0.5 to 2
  .contrast(1.1)     // 0.5 to 2
  .saturation(0.8)   // 0 to 2
  .toUrl();

Watermarks

// Text watermark
const url = insomma.transform(fileId)
  .watermark('© 2025 MyBrand', 'southeast', 0.7)
  .toUrl();

// Positions: center, northwest, northeast, southwest, southeast

Chaining Transformations

// Combine multiple transformations
const url = insomma.transform(fileId)
  .resize(800, 600)
  .fit('cover')
  .grayscale()
  .blur(2)
  .watermark('PREVIEW', 'center', 0.3)
  .webp(80)
  .toUrl();

File Operations

Upload

// Simple upload
const file = await insomma.upload(fileInput);

// Upload with options
const file = await insomma.files.upload(fileInput, {
  filename: 'my-image.jpg',
  folder: 'avatars',
  tags: ['profile', 'user-123'],
});

// Upload with progress
const file = await insomma.files.upload(fileInput, {
  onProgress: ({ percent }) => console.log(`${percent}%`)
});

List & Query

// List all files
const { files, pagination } = await insomma.files.list();

// Filter and sort
const images = await insomma.files
  .type('image')
  .search('vacation')
  .order('createdAt', 'desc')
  .range(1, 20)
  .list();

Get & Delete

// Get file info
const file = await insomma.files.get(fileId);

// Check existence
const exists = await insomma.files.exists(fileId);

// Delete
await insomma.files.delete(fileId);

// Delete multiple
const { deleted, failed } = await insomma.files.deleteMany([id1, id2, id3]);

Error Handling

import { InsommaError } from 'insomma-sdk';

try {
  await insomma.files.get('invalid_id');
} catch (err) {
  if (err instanceof InsommaError) {
    console.log(err.code);   // 'NOT_FOUND'
    console.log(err.status); // 404
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  FileInfo,
  TransformOptions,
  UploadOptions,
} from 'insomma-sdk';

Links

• Documentation
• Dashboard
• GitHub

License

MIT