@ircg/uss

URL Shortener Service (USS) SDK for IRCG.

Installation

pnpm add @ircg/uss

Usage

import { USSClient } from '@ircg/uss';

// Initialize the client
const uss = new USSClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://ircg.dev' // optional, defaults to https://ircg.dev
});

// Create a shortened URL
const result = await uss.create({
  url: 'https://example.com/very/long/url'
});

console.log(result.shortenedUrl.urlKey); // e.g., "abc123"
console.log(`Short URL: https://ircg.dev/l/${result.shortenedUrl.urlKey}`);

// Get all shortened URLs
const urls = await uss.getAll({
  page: 1,
  amount: 50,
  ascending: false,
  fields: ['urlKey', 'originalUrl', 'id', 'hits', 'active', 'createdAt']
});

console.log(urls.shortenedUrls);
console.log(`Total: ${urls.totalAmount}`);

// Get a specific shortened URL by key
const url = await uss.getByKey('abc123');
console.log(url.shortenedUrl.originalUrl);

// Delete a shortened URL
await uss.delete('abc123');

API Reference

USSClient

Constructor

new USSClient(config: IRCGClientConfig)

• config.apiKey (required): Your IRCG API key
• config.baseUrl (optional): Base URL for the API (default: 'https://ircg.dev')

Methods

create(data)

Create a shortened URL.

• data.url (required): The URL to shorten
• data.fields (required): Array of fields to include in the response
• data.lang (optional): Language for error messages ('es' | 'en')

Returns: Promise<{ shortenedUrl?, error? }>

getAll(options)

Get all shortened URLs with pagination.

• options.page (optional): Page number (default: 1)
• options.amount (optional): Items per page (default: 50)
• options.ascending (optional): Sort order (default: false)
• options.fields (required): Array of fields to include in the response
• options.lang (optional): Language for error messages ('es' | 'en')

Returns: Promise<{ shortenedUrls?, totalAmount?, error? }>

getByKey(urlKey, fields)

Get a shortened URL by its key.

• urlKey (required): The URL key
• fields (required): Array of fields to include in the response

Returns: Promise<{ shortenedUrl?, error? }>

delete(urlKey)

Delete a shortened URL.

• urlKey (required): The URL key to delete

Returns: Promise<DeleteShortenedUrlResponse>

Error Handling

import { USSClient } from '@ircg/uss';
import { IRCGError, IRCGAuthenticationError, IRCGValidationError } from '@ircg/core';

const uss = new USSClient({ apiKey: 'your-api-key' });

try {
  await uss.create({ url: 'invalid-url' });
} catch (error) {
  if (error instanceof IRCGAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof IRCGValidationError) {
    console.error('Validation error:', error.details);
  } else if (error instanceof IRCGError) {
    console.error('IRCG error:', error.message);
  }
}

License

MIT