The Node.js SDK
A typed client over /v1 — generated from the same OpenAPI spec these docs derive from, with Retry-After handling built in. Node 18+, ESM and CJS, TypeScript types included.
Install
npm install riilinkOne package, zero runtime dependencies. Types ship inside — no @types twin to chase.
SHELL
npm install riilink
# pnpm add riilink · yarn add riilink · bun add riilink
Initialize the client
new RiiLink(key)Pass the key from the environment — never inline it. The client reads nothing else; base URL and retries have working defaults.
NODE.JS
import { RiiLink } from 'riilink';
const rii = new RiiLink(process.env.RII_KEY);
Create and route a link
rii.links.createThe same shape as POST /v1/links — url required, everything else defaulted. Attach routing rules inline or later via rii.links.update.
NODE.JS
const link = await rii.links.create({
url: 'https://example.com/summer',
slug: 'summer',
routing: [
{ if: { country: 'DE' }, to: 'https://example.de/sommer' },
],
});
console.log(link.short_url); // https://rii.link/summer
YOU SHOULD SEE —the full link object — id, short_url, and the routing array in evaluation order
Handle errors and limits
RiiLinkErrorEvery non-2xx throws RiiLinkError carrying the envelope’s stable code — match on it, never on the message. 429s retry automatically, honoring Retry-After, up to three attempts before the error surfaces.
NODE.JS
try {
await rii.links.create({ url, slug: 'summer' });
} catch (err) {
if (err instanceof RiiLinkError && err.code === 'slug_taken') {
// pick another slug — the envelope names the conflict
}
}