Shortcut SDK

A library for creating a URL shortener service

Usage

Example

import Shortcut, {
    generatePathname,
    generateToken,
} from '@wral/sdk-shortcut';
import { createClient } from '@wral/sdk-publisher/v1';

const shortcutClient = Shortcut({
    publisherClient: createClient({
        apiKey: 'api-key-here',
        baseUrl: 'https://api.wral.com/publisher',
    }),
});

// Create/update a shortcut: wr.al/r9dH4/
const shortcut = await shortcutClient.putShortcut({
    site: 'wr.al',
    path: '/r9dH4/',
    name: 'An example shortcut',
    location: 'https://www.wral.com/news/local/promote-this-article-even-though-it-has-the-longest-slug-in-the-world-10584688/',
    statusCode: 302,  // optional, default 302 (Found)
    date: new Date(), // optional effective date, default current date
    metadata: {
        // Any metadata can go here
        rationale: 'An example promotional shortcut for a QR code that we will print on a hat',
    },
});

// Retrieve an existing shortcut
const shortcut = await shortcutClient.getShortcut({
    site: 'wr.al',
    path: '/r9dH4/',
    date: '2025-07-04T00:00:00.000Z', // optional, must be exact as in timeline
});

// Get a timeline for a shortcut (history)
const timeline = await shortcutClient.getShortcutTimeline({
    site: 'wr.al',
    path: '/r9dH4/',
});
/*
{
    "site": "wr.al",
    "path": "/r9dH4/",
    "timeline": [
        { "date": "2025-07-04T00:00:00.000Z" }
    ]
}
*/

// Utilities
/* Generate a random token of length 5, with optional seed */
const token = generateToken(5, 'random-seed'); // "pMsOm"

/* Generate a URL pathname for a shortcut */
const pathname = generatePathname({
    size: 5,             // default 5
    seed: 'random-seed', // default is random
    prefix: '/',         // default '/'
    trailingSlash: true, // default true
}); // "/foo/pMsOm/"