/shlink-client

Interact with your Shlink.io API more easily. This package covers the endpoints provided by Shlink and types every input and output between your app and your API.

Primary LanguageTypeScriptMIT LicenseMIT

npm version npm bundle size npm downloads npm licence GitHub Repo stars

shlink-client

Interact with your Shlink.io API more easily. This package covers the endpoints provided by Shlink and types every input and output between your app and your API.

Installation

$ npm i shlink-client

# Or with yarn

$ yarn add shlink-client

API

Instanciate a new Shlink Client:

import { ShlinkClient } from 'shlink-client';

const client = new ShlinkClient({
  url: 'https://yourdomain.tld',
  token: 'xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

Main entites declarations

ShortUrl:

interface ShortUrl {
  shortCode: string;
  shortUrl: string;
  longUrl: string;
  dateCreated: string;
  visitsCount: number;
  tags: string[];
  meta: {
    validSince: string | null;
    validUntil: string | null;
    maxVisits: number;
  };
  domain: string | null;
}

client.shortenUrl(baseUrl, apiKey, longUrl, [options])

Creates a short URL in a single API call. Useful for third party integrations. This is the only static method for short URLs.

Parameters

baseUrl: URL of your Shlink API.

apiKey: Your Shlink API Key.

longUrl: URL to shorten

options: Specify the type of the payload you wish to get back:

interface ShortenUrlOptions {
  format: 'json' | 'txt';
}

Response

When no options are provided, the default payload is a ShortUrl object. If txt is chosen, the full shortened URL is returned.

client#getShortUrls([options])

Returns the list of short URLs.

Options

All fields are optional.

interface ShortUrlGetOptions {
  // The page to be displayed. Defaults to 1
  page?: number
  // A query used to filter results by searching for it on the longUrl and shortCode fields
  searchTerm?: string
  // A list of tags used to filter the result set. Only short URLs tagged with at least one of the provided tags will be returned
  tags?: string[]
  // The field from which you want to order the result
  orderBy?:  'longUrl-ASC' | 'longUrl-DESC' | 'shortCode-ASC' | 'shortCode-DESC' | 'dateCreated-ASC' | 'dateCreated-DESC' | 'visits-ASC' | 'visits-DESC'
  // The date (in ISO-8601 format) from which we want to get short URLs
  startDate?: string
  // The date (in ISO-8601 format) until which we want to get short URLs
  endDate?: string
}

Response

interface {
  data: ShortUrl[]
  pagination: {
    currentPage: number
    pagesCount: number
    itemsPerPage: number
    itemsInCurrentPage: number
    totalItems: number
  }
}

client#getShortUrl(shortCode)

Get the long URL behind a short URL's short code.

Parameters

shortCode: The short code to edit.

Response

Returns a single ShortUrl object if found.

client#editShortUrl(shortCode, [options, [domain]])

Update certain meta arguments from an existing short URL.

Parameters

shortCode: The short code to edit.

options: ShortUrl options. At least one field is required.

interface ShortUrlPatchOptions {
  longUrl?: string;
  validSince?: string;
  validUntil?: string;
  maxVisits?: number;
  validateUrl: boolean;
}

domain: The domain in which the short code should be searched for.

Response

Returns the updated ShortUrl object.

client#createShortUrl(options)

Creates a new short URL.

Parameters

Shares most of the specificities of the edit method, except the longUrl property is required.

interface ShortUrlOptions {
  // URL to shorten
  longUrl: string;
  // Array of tags to attach to this short URL
  tags?: string[];
  // The date (in ISO-8601 format) from which the short URL is valid
  validSince?: string;
  // The date (in ISO-8601 format) from which the URL is no longer valid
  validUntil?: string;
  // Set your own short url instead of autogenerating a URL
  customSlug?: string;
  // Maximum visits allowed on this link
  maxVisits?: number;
  // Don't create another short URL if another one already uses this longUrl
  findIfExists?: boolean;
  // The domain in which the short code should be saved in
  domain?: string;
  // Length of the code
  shortCodeLength?: number;
  // Tells if shlink should validate a status 20x is returned (after following redirects) when trying to shorten a URL
  validateUrl?: boolean;
}

Response

Returns the created ShortUrl object.

client#deleteShortUrl(shortCode)

Deletes the short URL for provided short code.

Parameters

shortCode: The short code to delete.

Response

Returns the delete ShortUrl shortCode.

client#setShortUrlTags(shortCode, tags)

Edit the tags on URL identified by provided short code.

Parameters

shortCode: The short code to which you want to set the tags.

tags: Array of tags to assign the this short code. Older tags are not merged, but replaced with the new ones.

Response

Returns the shortCode's new tags.

client#listTags(options)

List all available tags

Parameters

options:

interface ListTagsOptions {
  // Whether to add additional details about the tags visits / links
  withStats: boolean;
}

Response

Returns the list of available tags, and the details if requested

client#renameTag(oldName, newName)

Renames a tag

Parameters

oldName: string of the previous tag name

newName: string of the new tag name

Response

An object with the new tag name, if succeeded.

client#deleteTags(...tags)

Deletes tags

Parameters

tags: Takes as many arguments as tags to remove. Inexistant tags won't throw error.

Response

An object with the list of deleted tags

client#getDomains()

Lists available domains

Response

Returns the list of available domains to create URLs

client#getPixel(shortCode)

Generates a 1px transparent image which can be used to track emails with a short URL

Parameters

shortCode: The short code to which you want to get the pixel.

Response

A base64 encoded string of the pixel

client#getQR(shortCode, options)

Generates a QR code image pointing to a short URL

Parameters

shortCode: The short code to which you want to get the QR Code.

options:

interface QRCodeOptions {
  format?: 'png' | 'svg'; // Format of the response (defaults to png)
  size?: number; // size in px of the QR Code (defaults to 300px)
} 

Response

An objet containing the MIME type of the QR Code, and the data in the requested format

client#countVisits()

Get general visits stats not linked to one specific short URL.

Response

Returns an object containing general data about link statistics

client#getLinkVisits(shortCode, options)

Get the list of visits on the short URL behind provided short code.

Parameters

shortCode: The short code to which you want to get the visits stats.

options:

interface PaginationOptions {
  startDate?: string; // ISO-8601 date format
  endDate?: string; // ISO-8601 date format
  page?: number; // Page number, defaults to 1
  itemsPerPage?: number; // Items per page, defaults to all results
}

Response

A paginated response containing visits stats for the given short code.

client#getTagVisits(tag, options)

Get the list of visits on any short URL which is tagged with provided tag.

Parameters

shortCode: The short code to which you want to get the visits stats.

options:

interface PaginationOptions {
  startDate?: string; // ISO-8601 date format
  endDate?: string; // ISO-8601 date format
  page?: number; // Page number, defaults to 1
  itemsPerPage?: number; // Items per page, defaults to all results
}

Response

A paginated response containing visits stats for the given tag.