Plung TypeScript SDK

Official TypeScript SDK for the Plung API.

Installation

pnpm add @plung/sdk

Quick start

import { PlungClient } from '@plung/sdk';

const client = new PlungClient(process.env.PLUNG_API_KEY!);

const { data, meta } = await client.links.create({
  url: 'https://example.com',
});

console.log(data.shortUrl);
console.log(meta.rateLimit.remaining);

Example response shape:

{
  data: {
    shortUrl: 'https://plu.ng/hello-world',
    shortCode: 'hello-world',
    url: 'https://example.com',
    createdAt: '2026-03-27T00:00:00.000Z'
  },
  meta: {
    apiKeyName: 'primary',
    rateLimit: {
      limit: 100,
      remaining: 99,
      reset: 1710000000
    },
    plan: 'PRO',
    usage: {
      apiCallsUsed: 1,
      apiCallsLimit: 1000,
      apiCallsRemaining: 999,
      reset: 1775001600
    }
  }
}

Available methods

| Resource | Method | Signature | | --- | --- | --- | | Links | links.create | (input: CreateLinkInput) => Promise<PlungResponse<Link>> | | Links | links.batchCreate | (items: CreateLinkInput[]) => Promise<PlungResponse<BatchCreateResponse>> | | QR | qr.get | (shortCode: string, options?: QrOptions) => Promise<QrResponse> | | Analytics | analytics.get | (shortCode: string) => Promise<PlungResponse<LinkStats>> |

Error handling

import {
  PlungAuthError,
  PlungRateLimitError,
  PlungValidationError,
  PlungClient,
} from '@plung/sdk';

const client = new PlungClient(process.env.PLUNG_API_KEY!);

try {
  await client.links.create({ url: 'not-a-valid-url' });
} catch (error) {
  if (error instanceof PlungValidationError) {
    console.log('Validation failed:', error.message);
  } else if (error instanceof PlungAuthError) {
    console.log('Authentication failed:', error.message);
  } else if (error instanceof PlungRateLimitError) {
    console.log('Rate limited:', error.retryAfter);
  }
}

Response metadata

Every successful SDK response includes a meta object.

• meta.apiKeyName: API key label returned by the backend, when available.
• meta.rateLimit.limit: Current rate-limit ceiling for the authenticated key.
• meta.rateLimit.remaining: Remaining requests in the current rate-limit window.
• meta.rateLimit.reset: Unix timestamp in seconds for the rate-limit reset time.
• meta.plan: Current Plung plan identifier returned by the backend.
• meta.usage.apiCallsUsed: API calls already used in the current billing period.
• meta.usage.apiCallsLimit: API call limit for the current billing period, when finite.
• meta.usage.apiCallsRemaining: Remaining API calls for the current billing period, when finite.
• meta.usage.reset: Unix timestamp in seconds for the next usage reset time.

Requirements

• Node >=24.14.1