JavaScript SDK

The official JavaScript / TypeScript SDK wraps the REST API with a typed client, automatic retries, a resolve-and-wait helper, typed error classes, and webhook verification.

npm

@linkskipper/sdk · v0.2.1

GitHub

Source, issues, and changelog.

Install

npm install @linkskipper/sdk

Requires Node 18+ (for global fetch), a modern browser, or a custom fetch passed in. Ships ESM with TypeScript types.

Use the SDK from a server, not the browser, so your API key stays secret. See Authentication.

Initialize

import { LinkSkipper } from "@linkskipper/sdk";

const client = new LinkSkipper({
  apiKey: process.env.LINKSKIPPER_API_KEY!,
});

Client options

string

required

Your sk_live_… key. Throws LinkSkipperError if missing.

string

default:"https://api.linkskipper.app"

Override the API base URL.

number

default:"30000"

Per-request timeout in milliseconds.

number

default:"2000"

Default poll interval for resolveAndWait.

number

default:"120000"

Default overall deadline for resolveAndWait.

Partial<RetryConfig>

Retry tuning: { maxAttempts: 3, initialDelayMs: 500, maxDelayMs: 8000, backoffFactor: 2 }. Retries 429 and 5xx, honoring Retry-After, with exponential backoff and jitter.

typeof fetch

Custom fetch implementation (for older Node or testing).

string

Override the default User-Agent.

Methods

resolve

resolve(url, options?) => Promise<ResolveResult> Submits a URL to POST /v1/resolve. Returns immediately — a cached link comes back with status: "done", a new one with status: "queued" and a jobId.

string

required

The shortener URL to resolve.

string

Sent as the Idempotency-Key header to de-duplicate retries.

const result = await client.resolve("https://ouo.io/abc123", {
  idempotencyKey: "order-42",
});

if (result.status === "done") {
  console.log(result.targetUrl, result.cached);
} else {
  console.log("queued:", result.jobId);
}

The ResolveResult exposes jobId, status, url, targetUrl, provider, tier, creditsCharged, cached, balance, queuePosition, and pollUrl (camelCase mappings of the resolve response).

resolveAndWait

resolveAndWait(url, options?) => Promise<ResolvedLink> The high-level helper: submits the resolve, then polls the job until it is terminal and returns the resolved link. A cached hit returns without polling.

string

required

The shortener URL to resolve.

string

De-duplicate retries.

number

default:"2000"

How often to poll the job.

number

default:"120000"

Overall deadline. Exceeding it throws TimeoutError.

AbortSignal

Cancel the wait loop.

import { LinkSkipper, JobFailedError, TimeoutError } from "@linkskipper/sdk";

const client = new LinkSkipper({ apiKey: process.env.LINKSKIPPER_API_KEY! });

try {
  const link = await client.resolveAndWait("https://ouo.io/abc123", {
    maxWaitMs: 60_000,
    pollIntervalMs: 2_000,
  });

  console.log(link.targetUrl);
  console.log(
    `${link.provider} (${link.tier}) · ${link.creditsCharged} credits · cached=${link.cached}`,
  );
} catch (error) {
  if (error instanceof JobFailedError) {
    console.error("Resolve failed:", error.reason);
  } else if (error instanceof TimeoutError) {
    console.error("Timed out, still pending:", error.jobId);
  } else {
    throw error;
  }
}

The ResolvedLink has a guaranteed targetUrl plus jobId, provider, tier, creditsCharged, balance, and cached.

getJob

getJob(jobId, signal?) => Promise<Job> Reads GET /v1/jobs/{jobId} once. Use it to poll manually or check a job from a webhook.

const job = await client.getJob("9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f");
if (job.status === "done") {
  console.log(job.targetUrl);
}

account

account() => Promise<Account> Reads GET /v1/account: telegramId, balance, subscriptionUntil, and providers.

const account = await client.account();
console.log(`${account.balance} credits left`);

providers

providers() => Promise<ProviderEntry[]> Reads GET /v1/providers. Each entry has provider, label, hosts, tier, and latency.

const providers = await client.providers();
for (const p of providers) {
  console.log(`${p.label}: ${p.hosts.join(", ")}`);
}

Errors

Every failed API call rejects with an ApiError subclass keyed to the response error code. JobFailedError, TimeoutError, NetworkError, and WebhookVerificationError cover the non-HTTP cases. All extend LinkSkipperError.

Class	Triggered by
`InvalidRequestError`	`invalid_request` (400)
`InvalidKeyError`	`invalid_key` (401)
`OutOfCreditsError`	`out_of_credits` (402) — `.balance`
`ForbiddenScopeError`	`forbidden_scope` (403)
`NotFoundError`	`not_found` (404)
`LinkRemovedError`	`link_removed` (410)
`UnsupportedLinkError`	`unsupported_link` (422)
`RateLimitedError`	`rate_limited` (429) — `.retryAfter`
`QuotaExceededError`	`quota_exceeded` (429) — `.retryAfter`
`ResolveFailedError`	`resolve_failed` (502)
`ProviderDownError`	`provider_down` (503)
`JobFailedError`	A polled job ended `failed`/`invalid` — `.reason`, `.job`
`TimeoutError`	`resolveAndWait` deadline passed — `.jobId`, `.waitedMs`
`NetworkError`	Transport failure after retries — `.cause`
`WebhookVerificationError`	`verifyWebhook` rejected a payload

Every ApiError carries status, code, title, detail, type, balance, retryAfter, and the raw problem object.

import {
  ApiError,
  OutOfCreditsError,
  RateLimitedError,
} from "@linkskipper/sdk";

try {
  await client.resolveAndWait("https://ouo.io/abc123");
} catch (error) {
  if (error instanceof OutOfCreditsError) {
    console.error("Top up — balance:", error.balance);
  } else if (error instanceof RateLimitedError) {
    console.error("Back off for", error.retryAfter, "seconds");
  } else if (error instanceof ApiError) {
    console.error(error.code, error.status, error.detail);
  } else {
    throw error;
  }
}

Webhook verification

verifyWebhook(payload, signatureHeader, secret, toleranceSeconds?) checks the X-LinkSkipper-Signature header, the timestamp tolerance (default 300s), and the HMAC, then returns the typed WebhookEvent. It throws WebhookVerificationError on any failure.

import express from "express";
import { verifyWebhook, WebhookVerificationError } from "@linkskipper/sdk";

app.post(
  "/webhooks/linkskipper",
  express.raw({ type: "application/json" }),
  (req, res) => {
    try {
      const event = verifyWebhook(
        req.body.toString("utf8"),
        req.header("X-LinkSkipper-Signature"),
        process.env.LINKSKIPPER_WEBHOOK_SECRET,
      );
      if (event.event === "resolve.done") {
        saveTarget(event.job_id, event.target_url);
      }
      res.sendStatus(204);
    } catch (error) {
      if (error instanceof WebhookVerificationError) {
        res.sendStatus(400);
      } else {
        throw error;
      }
    }
  },
);

Pass the raw request body (e.g. via express.raw), not a re-serialized object, or the signature won’t match. See Webhooks.

Exported types

The package exports Account, AccountProvider, Job, JobStatus, ProviderEntry, ProviderTier, ResolveResult, ResolveStatus, ResolvedLink, ProblemDetails, WebhookEvent/WebhookPayload, WebhookEventName, ClientOptions, ResolveOptions, ResolveAndWaitOptions, RetryConfig, ErrorCode, and the ERROR_CODES constant.

Get started

API

Reference

SDKs

npm

GitHub

Install

Initialize

Client options

Methods

resolve

resolveAndWait

getJob

account

providers

Errors

Webhook verification

Exported types

npm

GitHub

​Install

​Initialize

​Client options

​Methods

​resolve

​resolveAndWait

​getJob

​account

​providers

​Errors

​Webhook verification

​Exported types

Install

Initialize

Client options

Methods

resolve

resolveAndWait

getJob

account

providers

Errors

Webhook verification

Exported types