The official JavaScript/TypeScript SDK for VIUCraft provides a type-safe, chainable API for image transformations, uploads, and management.
Installation
cURL
npm install viucraft
Quick Start
Typescript
import { ViucraftClient } from 'viucraft';
const client = new ViucraftClient({
apiKey: process.env.VIUCRAFT_API_KEY,
subdomain: 'mycompany', // your subdomain (paid plans)
});
// Build a transformation URL using the chainable API
const url = client.image('image-uuid')
.resize(800, 600)
.grayscale()
.quality(85)
.toURL();
// => https://mycompany.viucraft.com/resize_width_800_height_600/grayscale/quality_value_85/image-uuid.jpg
// Upload an image (Node.js)
const result = await client.uploadImage(buffer);
console.log(result.image_id);
Configuration Options
The ViucraftClient constructor accepts a configuration object:
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | (required) | Your VIUCraft API key |
subdomain | string | — | Your dedicated subdomain (paid plans) |
baseUrl | string | https://api.viucraft.com | API base URL |
accountId | string | — | Account ID for free-tier shared endpoint |
timeout | number | 30000 | Request timeout in milliseconds |
retry | RetryConfig | false | See below | Retry configuration, or false to disable |
enforceHttps | boolean | true | Warn when using HTTP instead of HTTPS |
Example with All Options
Typescript
const client = new ViucraftClient({
apiKey: 'your-api-key',
subdomain: 'mycompany',
baseUrl: 'https://api.viucraft.com',
timeout: 15000,
retry: {
maxRetries: 5,
initialDelayMs: 500,
maxDelayMs: 60000,
backoffMultiplier: 2,
},
});
Free-Tier URL Format
If you are on the free plan, pass accountId instead of subdomain:
Typescript
const client = new ViucraftClient({
apiKey: 'your-api-key',
accountId: 'acc_12345',
});
const url = client.image('image-uuid').resize(300, 200).toURL();
// => https://api.viucraft.com/free/acc_12345/resize_width_300_height_200/image-uuid.jpg
URL Formats
The SDK supports two URL formats — standard (default) and short.
Standard Format
Typescript
const url = client.image('img-uuid')
.resize(300, 200)
.toURL();
// => .../resize_width_300_height_200/img-uuid.jpg
Short Format
Typescript
const url = client.image('img-uuid')
.resize(300, 200)
.useShort()
.toURL();
// => .../resize-300-200/img-uuid.jpg
Short format produces more compact URLs. See the Image Transformations article for the full short-format mapping table.
TypeScript Support
The SDK is written in TypeScript and ships with full type definitions. All interfaces are exported:
Typescript
import {
ViucraftClient,
ImageBuilder,
ViucraftClientConfig,
UploadResponse,
ImageInfo,
ImageListResponse,
DeleteResponse,
ProcessingInstructions,
OutputFormat,
RetryConfig,
RateLimitInfo,
} from 'viucraft';
Updating Configuration
You can update the API key or timeout after construction:
Typescript
client.updateConfig({ apiKey: 'new-key' });
client.updateConfig({ timeout: 5000 });
Security Tips
- Never hardcode API keys in source code. Use environment variables.
- The SDK warns if you use
http://instead ofhttps://. Suppress withenforceHttps: falseif you intentionally use HTTP (e.g. local development). - Use
getMaskedApiKey()for logging — it returns a string likeabcdwxyz.
Next Steps
- Image Transformations — full ImageBuilder method reference
- Image Management — upload, delete, list images