@ircg/ios

TypeScript/JavaScript SDK for the IRCG Image Optimization Service.

Installation

npm install @ircg/ios

Basic usage

Run uploads on a server so the API key is never exposed to the browser:

import { File } from 'node:buffer'
import { readFile } from 'node:fs/promises'
import { IOSClient } from '@ircg/ios'

const apiKey = process.env.IRCG_API_KEY
if (!apiKey) throw new Error('Set IRCG_API_KEY')

const image = new File([await readFile('./product.jpg')], 'product.jpg', { type: 'image/jpeg' })
const ios = new IOSClient({ apiKey, lang: 'en' })
const { optimizedImage, error } = await ios.upload({
	image,
	requireSignedURLs: false,
	fields: ['imageId', 'currentVariants'],
})

if (error) console.error(error.message)
else console.log(ios.getImageUrl(optimizedImage.imageId, '500x500'))

requireSignedURLs is optional and defaults to false. Only construct a public URL when it is false; private images must use signImage().

Dry run

Dry-run mode returns typed synthetic responses without making HTTP requests or consuming credits:

const ios = new IOSClient({ apiKey: 'unused', dryRun: true })
const result = await ios.upload({ image, fields: ['imageId', 'currentVariants'] })

if (!result.error) console.log(result.optimizedImage.imageId) // "dry-run-image"

All remote methods, including Unsafe variants, are simulated. Listings return an empty array; lookups, signatures and deletions return recognizable dry-run data. This mode validates the SDK integration, not authentication, resource existence or server-side limits. getImageUrl() remains a synchronous local URL builder and behaves identically with or without dry-run mode.

Variants and dimensions

getImageUrl() and signImage() accept either an available variant name, such as product, or its available dimensions, such as 500x500:

ios.getImageUrl(imageId, 'product')
ios.getImageUrl(imageId, '500x500')

getImageUrl() is synchronous and does not require await. It returns https://media.ircg.dev/i/<imageId>/<variant> by default. For a local or preview media Worker, pass mediaUrl when constructing the client.

SVG uploads keep the same variant paths and per-request billing as raster images. Delivery always uses sanitized output; SVG variants are not resized even when the path names a configured size.

Upload, retrieve, and delete

All read methods require an explicit fields array. Safe methods return data or error; Unsafe methods throw.

const uploaded = await ios.upload({
	image,
	fields: ['imageId', 'name', 'createdAt', 'currentVariants'],
})

const listed = await ios.getAll({
	page: 1,
	amount: 50,
	fields: ['imageId', 'name', 'createdAt', 'requests'],
})

const selected = await ios.getById({
	imageId,
	fields: ['imageId', 'name', 'currentVariants', 'placeholderBase64'],
})

const deleted = await ios.delete({ imageId })

Image listings support imageId, requireSignedURLs, name, createdAt, and requests. Upload and single-image retrieval additionally support currentVariants and placeholderBase64. Request currentVariants to discover the available variant names, dimensions, and URLs. placeholderBase64 is a low-resolution data URL generated from the placeholder variant (32x32); store it with the image metadata and display it while the final image loads.

Signed images

const { optimizedImage, reusedSignature, error } = await ios.signImage({
	imageId,
	variant: '500x500',
	reuseSignature: true,
	fields: ['sig', 'exp', 'imageId', 'signedUrl', 'requests'],
})

if (error) console.error(error.message)
else console.log(optimizedImage.signedUrl, reusedSignature)

Available signature fields are sig, exp, imageId, signedUrl, and requests.

Rate limits

IOS has two independent rate-limit layers:

• Authenticated API operations default to 600 requests per 60 seconds and 15,000 per 3,600 seconds per API key. Approved organization-specific API limits may differ.
• Image delivery from media.ircg.dev does not use the API key quota. Its defensive limits are 3,000 requests per 60 seconds per organization and client address, 30,000 per image, and 60,000 per organization. These approximate limits apply per delivery location and may temporarily return 429 with Retry-After: 60.

One API upload can therefore produce many more image deliveries. Signing a URL uses the API limit; each GET or HEAD made with the resulting URL uses the separate delivery limits.

Uploads accept PNG, JPEG, GIF, WebP, or SVG files up to 10 MB. Each active image costs 5 credits per billing cycle, and every served image costs 1 credit regardless of its variant or response size. Generating or reusing a URL signature does not consume credits.

Keep production API keys on the server. Cross-origin image uploads are supported, but embedding a key in browser code exposes it to users.