ShortyyDocs
Dashboard

TypeScript / JavaScript SDK (@g/shortyy)

Official client library for Node.js, Next.js, and browser environments with TypeScript support.

Official TypeScript SDK: @g/shortyy

The official Shortyy TypeScript SDK provides end-to-end typed access to the Shortyy public REST API with automatic rate-limit backoff, typed error contracts, and custom agent support.

Installation

bash
# pnpm
pnpm add @g/shortyy

# npm
npm install @g/shortyy

# yarn
yarn add @g/shortyy

Initialization

Initialize the client with your secret API key:

typescript
import { createShortyy } from '@g/shortyy';

const shortyy = createShortyy({
  apiKey: process.env.SHORTYY_API_KEY!,
  // Optional configuration:
  baseUrl: 'https://api.shortyy.com/v1', // default
  timeoutMs: 10000,                      // 10 second timeout
  defaultExpiresIn: '2h',                // default expiration for created links
});

Creating Short Links

typescript
try {
  const link = await shortyy.links.create({
    url: 'https://developer.mozilla.org/en-US/',
    expiresIn: '1d',
    customCode: 'mdn-web',
  });

  console.log('Short Link:', link.shortUrl);
  console.log('UUID:', link.id);
  console.log('Expires:', link.expiresAt);
} catch (error) {
  console.error('Failed to create link:', error);
}

Error Handling & retryAfterSeconds

The SDK exports typed exceptions: ShortyyError, RateLimitError, AuthenticationError, and ValidationError.

typescript
import { RateLimitError, ShortyyError } from '@g/shortyy';

try {
  await shortyy.links.create({ url: 'https://example.com' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.warn(`Rate limited. Refill in ${error.retryAfterSeconds} seconds.`);
    // error.retryAfterSeconds contains the exact wait time
  } else if (error instanceof ShortyyError) {
    console.error(`API Error [${error.code}]: ${error.message}`);
  }
}

Full SDK Reference

MethodReturn TypeDescription
shortyy.links.create(params)Promise<ShortLink>Mint a new short URL
shortyy.links.get(id)Promise<ShortLink>Retrieve metadata by UUID
shortyy.links.list(query)Promise<PaginatedLinks>List paginated links
shortyy.links.delete(id)Promise<void>Delete and tombstone link
shortyy.links.analytics(id)Promise<LinkAnalytics>Retrieve link click stats
shortyy.me.profile()Promise<UserProfile>Get authenticated user
shortyy.me.plan()Promise<PlanEntitlements>Get plan limits