@ircg/sdk

Complete TypeScript/JavaScript SDK for IRCG services:

• TES — Transactional Email Service
• IOS — Image Optimization Service
• USS — URL Shortener Service
• FSS — File Storage Service
• PGS — PDF Generation Service

Installation

pnpm add @ircg/sdk

Install an individual package instead when an application only uses one service.

Clients

import { FSSClient, IOSClient, PGSClient, TESClient, USSClient } from '@ircg/sdk'

const apiKey = process.env.IRCG_API_KEY!
const fss = new FSSClient({ apiKey, lang: 'en' })
const ios = new IOSClient({ apiKey, lang: 'en' })
const pgs = new PGSClient({ apiKey, lang: 'en' })
const tes = new TESClient({ apiKey, lang: 'en' })
const uss = new USSClient({ apiKey, lang: 'en' })

Keep production API keys on the server. Client configuration accepts a custom baseUrl, lang: 'es' | 'en', and service-specific options such as dryRun. IOS and FSS also accept a custom mediaUrl for local or preview delivery.

Safe and unsafe methods

Methods without an Unsafe suffix return a discriminated result containing either error or the operation's success shape. For example, TES returns { email_sent }, while PGS returns both the PDF response and its billing metadata:

const result = await tes.sendText({
	fields: ['id', 'createdAt'],
	from: '[email protected]',
	subject: 'Welcome',
	text: 'Your account is ready.',
	to: '[email protected]',
})

if (result.error) console.error(result.error.status, result.error.message)
else console.log(result.email_sent.id)

Most remote methods also have an Unsafe variant that throws typed IRCG errors. The exception is FSS abortMultipartUpload(), which only exposes its safe result:

import { IRCGAuthenticationError, IRCGError, IRCGRateLimitError, IRCGValidationError } from '@ircg/sdk'

try {
	const { email_sent: email } = await tes.sendTextUnsafe({
		fields: ['id'],
		from: '[email protected]',
		subject: 'Welcome',
		text: 'Your account is ready.',
		to: '[email protected]',
	})
	console.log(email.id)
} catch (error) {
	if (error instanceof IRCGAuthenticationError) console.error('Invalid API key')
	else if (error instanceof IRCGValidationError) console.error('Invalid request', error.details)
	else if (error instanceof IRCGRateLimitError) console.error('Rate limit exceeded')
	else if (error instanceof IRCGError) console.error(error.status, error.message)
}

Service examples

Service operations that support selectable JSON metadata require an explicit fields array so the response type contains only the selected fields. PGS does not accept fields: it returns a PDF stream plus fixed billing metadata.

Optimize an image

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

if (uploaded.error) throw new Error(uploaded.error.message)
console.log(ios.getImageUrl(uploaded.optimizedImage.imageId, '500x500'))

Shorten a URL

const shortened = await uss.create({
	url: 'https://example.com/a/very/long/path',
	fields: ['urlKey', 'originalUrl'],
})

if (shortened.error) throw new Error(shortened.error.message)
console.log(`https://ircg.dev/l/${shortened.shortenedUrl.urlKey}`)

Stream a file

const download = await fss.download({ fileId: 'd290f1ee-6c54-4b01-90e6-d701748f0851' })

if (download.error) throw new Error(download.error.message)
return download.response

Generate a PDF

import { createWriteStream } from 'node:fs'
import { Readable } from 'node:stream'
import { pipeline } from 'node:stream/promises'

const pdf = await pgs.generate({
	fileName: 'invoice.pdf',
	url: 'https://example.com/invoices/123',
})

if (pdf.error) throw new Error(pdf.error.message)
if (!pdf.response.body) throw new Error('PGS returned an empty PDF stream')
await pipeline(Readable.from(pdf.response.body), createWriteStream('invoice.pdf'))
console.log(pdf.billing)

Types and errors

The aggregate package re-exports every public type from @ircg/core and each service package, together with the core error classes:

import type { GeneratePDFRequest, SendEmailRequest, StoredFile } from '@ircg/sdk'
import {
	IRCGAuthenticationError,
	IRCGError,
	IRCGRateLimitError,
	IRCGServerError,
	IRCGValidationError,
} from '@ircg/sdk'

Individual packages

pnpm add @ircg/tes # Transactional email
pnpm add @ircg/ios # Image optimization
pnpm add @ircg/uss # URL shortening
pnpm add @ircg/fss # File storage
pnpm add @ircg/pgs # Server-side PDF generation

Documentation

• TES documentation
• IOS documentation
• USS documentation
• FSS documentation
• PGS documentation

License

MIT