warplo: URL shortener SDK and CLI for Node.js

The official JavaScript and TypeScript client for Warplo, the link shortener at warplo.link. Shorten URLs with custom slugs, list your links, read click analytics by day and country, and delete links from your Node.js backend, serverless functions, CI or terminal.

• Zero dependencies. The SDK only needs fetch, which is built into Node 18+.
• TypeScript types included.
• Every destination is checked against phishing and malware lists before a link is created.
• Short links redirect from Cloudflare's global network.

Website: app.warplo.link · API docs and keys: app.warplo.link/developers · Free QR code generator: app.warplo.link/qr-code-generator

Install

npm install warplo

pnpm add warplo
yarn add warplo
bun add warplo

Get an API key

Sign in at app.warplo.link/developers and create a key. It starts with wpl_ and is shown once. Keep it secret: use it from servers, scripts and CI, never in a web page.

export WARPLO_API_KEY=wpl_your_key_here

Shorten a URL in Node.js

import { Warplo } from "warplo";

const warplo = new Warplo(); // reads WARPLO_API_KEY, or pass { apiKey }

const short = await warplo.shorten("https://example.com/very-long-product-url?utm_source=newsletter");
console.log(short); // https://warplo.link/x7Kq2a

Custom slug and expiry

const link = await warplo.create({
  url: "https://github.com/your-org/your-repo",
  slug: "my-repo",     // https://warplo.link/my-repo
  expiresInDays: 30,   // optional; never expires if left out
});

console.log(link.shortUrl);  // https://warplo.link/my-repo
console.log(link.expiresAt); // Unix seconds, or null

Click analytics

const stats = await warplo.stats("my-repo", { days: 30 }); // up to 90 on Free, 365 on Pro

console.log(stats.total);     // 265
console.log(stats.byCountry); // [{ country: "IN", clicks: 142 }, { country: "US", clicks: 89 }, ...]
console.log(stats.byDay);     // [{ date: "2026-10-25", clicks: 45 }, ...]

List and delete links

for await (const link of warplo.links()) {
  console.log(link.slug, "->", link.url);
}

await warplo.delete("my-repo");

Handle errors

import { WarploError } from "warplo";

try {
  await warplo.create({ url: "https://example.com", slug: "my-repo" });
} catch (err) {
  if (err instanceof WarploError && err.code === "slug_taken") {
    // pick another slug
  }
}

console.log(warplo.rateLimit); // { limit: 100, remaining: 97 }

CLI: shorten links from your terminal

npx warplo https://example.com/some-long-link
npx warplo https://example.com/some-long-link --slug custom-name --expires 30
npx warplo list
npx warplo stats custom-name --days 90
npx warplo delete custom-name
npx warplo whoami

Add --json for machine-readable output, or --key wpl_... to pass the key directly.

API reference

| Method | Returns | | --- | --- | | create({ url, slug?, expiresInDays? }) or create(url) | The new link: slug, shortUrl, url, expiresAt | | shorten(url, options?) | The short URL as a string | | list({ cursor? }) | One page: { links, cursor } | | links() | Async iterator over every link | | stats(slug, { days? }) | { total, days, byDay, byCountry } | | delete(slug) | Nothing; the link stops working | | me() | Your plan, limits and link count |

Error codes

| Code | Meaning | | --- | --- | | invalid_api_key | Missing, wrong or deleted key | | api_quota_exceeded | Today's API calls are used up | | link_limit | Active link limit reached for your plan | | slug_taken | Someone already uses that slug | | invalid_url, invalid_slug, invalid_expiry | Bad input | | unsafe_url | The destination is on a phishing or malware list | | rate_limited | More than 20 new links in a minute |

Use cases

• SMS and email campaigns: shorten long tracking URLs before sending, and see clicks by country.
• E-commerce and social: clean warplo.link links for product pages, invoices and bios, then make a matching QR code in the dashboard.
• CI/CD and bots: shorten preview deployment URLs in GitHub Actions, Slack or Discord bots.

Plans

| | Free | Pro ($5/month) | | --- | --- | --- | | Active links | 50 | Unlimited | | Click history | 90 days | 1 year | | API keys | 1 | 10 | | API calls a day | 100 | 10,000 |

Upgrade at app.warplo.link.

FAQ

Is there a free URL shortener API for Node.js? Yes. Warplo's API and this package are free to use with one API key and 100 calls a day. Pro raises that to 10 keys and 10,000 calls a day.

Does it work outside Node.js? The SDK only needs fetch, so it can run anywhere fetch exists. The REST API works from any language: see app.warplo.link/developers.

Are links checked for safety? Yes. Every destination is checked against phishing and malware lists before a link is created, and reported links are taken down.

Links

• Website: https://app.warplo.link
• Developer docs: https://app.warplo.link/developers
• npm: https://www.npmjs.com/package/warplo
• Support: [email protected]

License

MIT