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-clientAPI
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;
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.