@ircg/uss

TypeScript/JavaScript SDK for the IRCG URL Shortener Service.

Installation

npm install @ircg/uss

Basic usage

import { USSClient } from '@ircg/uss'

const uss = new USSClient({ apiKey: process.env.IRCG_API_KEY!, lang: 'en' })
const { shortenedUrl, error } = await uss.create({
	url: 'https://example.com/a/very/long/path',
	fields: ['urlKey', 'originalUrl'],
})

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

Dry run

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

const uss = new USSClient({ apiKey: 'unused', dryRun: true })
const result = await uss.create({
	url: 'https://example.com/a/very/long/path',
	fields: ['urlKey', 'originalUrl'],
})

if (!result.error) console.log(result.shortenedUrl.urlKey) // "DR"

Every remote method, including Unsafe variants, is simulated. Listings return an empty array; lookups and updates return synthetic data based on the requested key, while deletion returns success. The client does not retain shortened URLs between calls, and dry-run mode does not validate authentication, resource existence or server-side URL rules.

Operations

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

const list = await uss.getAll({
	page: 1,
	amount: 50,
	ascending: false,
	fields: ['urlKey', 'originalUrl', 'visits', 'active'],
})

const selected = await uss.getByKey({
	urlKey: '2F',
	fields: ['urlKey', 'originalUrl', 'visits'],
})

const updated = await uss.update({
	urlKey: '2F',
	active: false,
	fields: ['urlKey', 'active', 'updatedAt'],
})

const deleted = await uss.delete({ urlKey: '2F' })

Available response fields are id, serviceId, urlKey, originalUrl, createdAt, updatedAt, visits, and active.

Calling update() without fields, or with an empty array, returns { success: true } after the update. Deletion returns { success: true } and the REST endpoint responds with 204 No Content.

Keep production API keys on the server. The client supports lang: 'es' | 'en' globally and on individual safe calls.

Limits and costs

Creating short URLs and recording the redirect event represented by the visits metric do not consume credits. The default rate limit is 60 requests per 60 seconds and 1,000 per 3,600 seconds per API key; both windows apply independently. Approved organization-specific limits may differ.