@yhn/sdk

Official TypeScript/JavaScript SDK for y.hn — The shortest URL shortener.

Create 7-character short links, track clicks, and manage links programmatically.

Install

npm install @yhn/sdk

Quick Start

import { YHN } from '@yhn/sdk'

const yhn = new YHN('your-api-key')

// Shorten a URL
const link = await yhn.shorten('https://example.com')
console.log(link.shortUrl) // https://y.hn/abc

// With custom slug
const custom = await yhn.shorten({
  url: 'https://example.com',
  customSlug: 'my-link',
})
console.log(custom.shortUrl) // https://y.hn/my-link

// Get click analytics
const stats = await yhn.stats(link.id)
console.log(stats.totalClicks)
console.log(stats.countries) // [{ country: 'US', clicks: 42 }, ...]

API

new YHN(apiKey)

Create a client with your API key. Get your key at y.hn/settings.

yhn.shorten(url | options)

Create a short link.

// Simple
await yhn.shorten('https://example.com')

// With options
await yhn.shorten({
  url: 'https://example.com',
  customSlug: 'my-link',      // optional
  password: 'secret',          // optional
  expiresAt: '2026-12-31',    // optional
  maxClicks: 1000,             // optional
  ogTitle: 'Custom OG Title',  // optional
})

yhn.list(options?)

List your links with pagination.

const { links, total, page, totalPages } = await yhn.list({
  page: 1,
  limit: 20,
  search: 'example',
})

yhn.get(linkId)

Get link details.

yhn.update(linkId, data)

Update a link's target URL, expiry, password, etc.

yhn.delete(linkId)

Delete a link.

yhn.stats(linkId, days?)

Get click analytics. Returns countries, cities, devices, browsers, OS, referrers, UTM data, and hourly distribution.

const stats = await yhn.stats(link.id, 30) // last 30 days
console.log(stats.totalClicks)
console.log(stats.uniqueClicks)
console.log(stats.devices)   // [{ device: 'Mobile', clicks: 80 }, ...]
console.log(stats.countries) // [{ country: 'US', clicks: 42 }, ...]

yhn.qr(linkId)

Generate a QR code for a link.

yhn.bulkShorten(urls)

Shorten multiple URLs at once.

const links = await yhn.bulkShorten([
  'https://example.com/page1',
  'https://example.com/page2',
])

Error Handling

import { YHN, YHNError } from '@yhn/sdk'

try {
  await yhn.shorten('invalid-url')
} catch (err) {
  if (err instanceof YHNError) {
    console.log(err.message) // "Invalid URL"
    console.log(err.status)  // 400
  }
}

Links

• y.hn — Create short links
• API Documentation — Full API reference
• Dashboard — Manage your links
• Pricing — Free and Pro plans

License

MIT