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.
$ npm i shlink-client
# Or with yarn
$ yarn add shlink-clientInstanciate a new Shlink Client:
import { ShlinkClient } from 'shlink-client';
const client = new ShlinkClient({
url: 'https://yourdomain.tld',
token: 'xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});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;
}Creates a short URL in a single API call. Useful for third party integrations. This is the only static method for short URLs.
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';
}When no options are provided, the default payload is a ShortUrl object. If txt is chosen, the full shortened URL is returned.
Returns the list of short URLs.
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
}interface {
data: ShortUrl[]
pagination: {
currentPage: number
pagesCount: number
itemsPerPage: number
itemsInCurrentPage: number
totalItems: number
}
}Get the long URL behind a short URL's short code.
shortCode: The short code to edit.
Returns a single ShortUrl object if found.
Update certain meta arguments from an existing short URL.
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.
Returns the updated ShortUrl object.
Creates a new short URL.
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;
}Returns the created ShortUrl object.
Deletes the short URL for provided short code.
shortCode: The short code to delete.
Returns the delete ShortUrl shortCode.
Edit the tags on URL identified by provided short code.
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.
Returns the shortCode's new tags.
List all available tags
options:
interface ListTagsOptions {
// Whether to add additional details about the tags visits / links
withStats: boolean;
}Returns the list of available tags, and the details if requested
Renames a tag
oldName: string of the previous tag name
newName: string of the new tag name
An object with the new tag name, if succeeded.
Deletes tags
tags: Takes as many arguments as tags to remove. Inexistant tags won't throw error.
An object with the list of deleted tags
Lists available domains
Returns the list of available domains to create URLs
Generates a 1px transparent image which can be used to track emails with a short URL
shortCode: The short code to which you want to get the pixel.
A base64 encoded string of the pixel
Generates a QR code image pointing to a short URL
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)
} An objet containing the MIME type of the QR Code, and the data in the requested format
Get general visits stats not linked to one specific short URL.
Returns an object containing general data about link statistics
Get the list of visits on the short URL behind provided short code.
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
}A paginated response containing visits stats for the given short code.
Get the list of visits on any short URL which is tagged with provided tag.
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
}A paginated response containing visits stats for the given tag.