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';constclient=newShlinkClient({url: 'https://yourdomain.tld',token: 'xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',});ShortUrl:
interfaceShortUrl{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:
interfaceShortenUrlOptions{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.
interfaceShortUrlGetOptions{// The page to be displayed. Defaults to 1page?: number// A query used to filter results by searching for it on the longUrl and shortCode fieldssearchTerm?: 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 returnedtags?: string[]// The field from which you want to order the resultorderBy?: '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 URLsstartDate?: string// The date (in ISO-8601 format) until which we want to get short URLsendDate?: 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.
interfaceShortUrlPatchOptions{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.
interfaceShortUrlOptions{// URL to shortenlongUrl: string;// Array of tags to attach to this short URLtags?: string[];// The date (in ISO-8601 format) from which the short URL is validvalidSince?: string;// The date (in ISO-8601 format) from which the URL is no longer validvalidUntil?: string;// Set your own short url instead of autogenerating a URLcustomSlug?: string;// Maximum visits allowed on this linkmaxVisits?: number;// Don't create another short URL if another one already uses this longUrlfindIfExists?: boolean;// The domain in which the short code should be saved indomain?: string;// Length of the codeshortCodeLength?: number;// Tells if shlink should validate a status 20x is returned (after following redirects) when trying to shorten a URLvalidateUrl?: 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:
interfaceListTagsOptions{// Whether to add additional details about the tags visits / linkswithStats: 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:
interfaceQRCodeOptions{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:
interfacePaginationOptions{startDate?: string;// ISO-8601 date formatendDate?: string;// ISO-8601 date formatpage?: number;// Page number, defaults to 1itemsPerPage?: 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:
interfacePaginationOptions{startDate?: string;// ISO-8601 date formatendDate?: string;// ISO-8601 date formatpage?: number;// Page number, defaults to 1itemsPerPage?: number;// Items per page, defaults to all results}A paginated response containing visits stats for the given tag.