{"id":17949936,"url":"https://github.com/noook/shlink-client","last_synced_at":"2025-03-24T23:32:05.816Z","repository":{"id":46817779,"uuid":"315132757","full_name":"noook/shlink-client","owner":"noook","description":"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.","archived":false,"fork":false,"pushed_at":"2022-11-28T15:40:00.000Z","size":27,"stargazers_count":7,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-15T02:48:32.019Z","etag":null,"topics":["client","shlink","shorturl","urlshortener","urlshortener-api"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/shlink-client","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-22T21:10:33.000Z","updated_at":"2023-06-26T13:54:16.000Z","dependencies_parsed_at":"2023-01-23T12:31:07.888Z","dependency_job_id":null,"html_url":"https://github.com/noook/shlink-client","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noook%2Fshlink-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noook%2Fshlink-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noook%2Fshlink-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noook%2Fshlink-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noook","download_url":"https://codeload.github.com/noook/shlink-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245372193,"owners_count":20604487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","shlink","shorturl","urlshortener","urlshortener-api"],"created_at":"2024-10-29T09:35:46.676Z","updated_at":"2025-03-24T23:32:05.384Z","avatar_url":"https://github.com/noook.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/shlink-client.svg)](https://badge.fury.io/js/shlink-client)\n![npm bundle size](https://img.shields.io/bundlephobia/minzip/shlink-client)\n![npm downloads](https://img.shields.io/npm/dt/shlink-client)\n![npm licence](https://img.shields.io/npm/l/shlink-client)\n![GitHub Repo stars](https://img.shields.io/github/stars/noook/shlink-client)\n\n# shlink-client\n\nInteract with your [Shlink.io](https://shlink.io) API more easily. This package covers the endpoints\nprovided by Shlink and types every input and output between your app and your API.\n\n## Installation\n\n```sh\n$ npm i shlink-client\n\n# Or with yarn\n\n$ yarn add shlink-client\n```\n\n## API\n\nInstanciate a new Shlink Client:\n\n```js\nimport { ShlinkClient } from 'shlink-client';\n\nconst client = new ShlinkClient({\n  url: 'https://yourdomain.tld',\n  token: 'xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',\n});\n```\n\n### Main entites declarations\n\nShortUrl:\n```ts\ninterface ShortUrl {\n  shortCode: string;\n  shortUrl: string;\n  longUrl: string;\n  dateCreated: string;\n  visitsCount: number;\n  tags: string[];\n  meta: {\n    validSince: string | null;\n    validUntil: string | null;\n    maxVisits: number;\n  };\n  domain: string | null;\n}\n```\n\n\n### client.shortenUrl(baseUrl, apiKey, longUrl, [options])\n\nCreates a short URL in a single API call. Useful for third party integrations. This is the only static method for short URLs.\n\n#### Parameters\n\n`baseUrl`: URL of your Shlink API.\n\n`apiKey`: Your Shlink API Key.\n\n`longUrl`: URL to shorten\n\n`options`: Specify the type of the payload you wish to get back:\n\n```ts\ninterface ShortenUrlOptions {\n  format: 'json' | 'txt';\n}\n```\n\n### Response\n\nWhen no options are provided, the default payload is a `ShortUrl` object. If `txt` is chosen, the full shortened URL is returned.\n\n### client#getShortUrls([options])\n\nReturns the list of short URLs.\n\n#### Options\n\nAll fields are optional.\n\n```ts\ninterface ShortUrlGetOptions {\n  // The page to be displayed. Defaults to 1\n  page?: number\n  // A query used to filter results by searching for it on the longUrl and shortCode fields\n  searchTerm?: string\n  // 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\n  tags?: string[]\n  // The field from which you want to order the result\n  orderBy?:  'longUrl-ASC' | 'longUrl-DESC' | 'shortCode-ASC' | 'shortCode-DESC' | 'dateCreated-ASC' | 'dateCreated-DESC' | 'visits-ASC' | 'visits-DESC'\n  // The date (in ISO-8601 format) from which we want to get short URLs\n  startDate?: string\n  // The date (in ISO-8601 format) until which we want to get short URLs\n  endDate?: string\n}\n```\n\n#### Response\n\n```ts\ninterface {\n  data: ShortUrl[]\n  pagination: {\n    currentPage: number\n    pagesCount: number\n    itemsPerPage: number\n    itemsInCurrentPage: number\n    totalItems: number\n  }\n}\n```\n\n### client#getShortUrl(shortCode)\n\nGet the long URL behind a short URL's short code.\n\n#### Parameters\n\n`shortCode`: The short code to edit.\n\n#### Response\n\nReturns a single `ShortUrl` object if found.\n\n### client#editShortUrl(shortCode, [options, [domain]])\n\nUpdate certain meta arguments from an existing short URL.\n\n#### Parameters\n\n`shortCode`: The short code to edit.\n\n`options`: ShortUrl options. At least one field is required.\n\n```ts\ninterface ShortUrlPatchOptions {\n  longUrl?: string;\n  validSince?: string;\n  validUntil?: string;\n  maxVisits?: number;\n  validateUrl: boolean;\n}\n```\n\n`domain`: The domain in which the short code should be searched for.\n\n#### Response\n\nReturns the updated `ShortUrl` object.\n\n### client#createShortUrl(options)\n\nCreates a new short URL.\n\n#### Parameters\n\nShares most of the specificities of the edit method, except the `longUrl` property is required.\n\n```ts\ninterface ShortUrlOptions {\n  // URL to shorten\n  longUrl: string;\n  // Array of tags to attach to this short URL\n  tags?: string[];\n  // The date (in ISO-8601 format) from which the short URL is valid\n  validSince?: string;\n  // The date (in ISO-8601 format) from which the URL is no longer valid\n  validUntil?: string;\n  // Set your own short url instead of autogenerating a URL\n  customSlug?: string;\n  // Maximum visits allowed on this link\n  maxVisits?: number;\n  // Don't create another short URL if another one already uses this longUrl\n  findIfExists?: boolean;\n  // The domain in which the short code should be saved in\n  domain?: string;\n  // Length of the code\n  shortCodeLength?: number;\n  // Tells if shlink should validate a status 20x is returned (after following redirects) when trying to shorten a URL\n  validateUrl?: boolean;\n}\n```\n\n#### Response\n\nReturns the created `ShortUrl` object.\n\n### client#deleteShortUrl(shortCode)\n\nDeletes the short URL for provided short code.\n\n#### Parameters\n\n`shortCode`: The short code to delete.\n\n#### Response\n\nReturns the delete `ShortUrl` shortCode.\n\n### client#setShortUrlTags(shortCode, tags)\n\nEdit the tags on URL identified by provided short code.\n\n#### Parameters\n\n`shortCode`: The short code to which you want to set the tags.\n\n`tags`: Array of tags to assign the this short code. Older tags are not merged, but replaced with the new ones.\n\n#### Response\n\nReturns the shortCode's new tags.\n\n### client#listTags(options)\n\nList all available tags\n\n#### Parameters\n\n`options`:\n```ts\ninterface ListTagsOptions {\n  // Whether to add additional details about the tags visits / links\n  withStats: boolean;\n}\n```\n\n#### Response\n\nReturns the list of available tags, and the details if requested\n\n### client#renameTag(oldName, newName)\n\nRenames a tag\n\n#### Parameters\n\n`oldName`: string of the previous tag name\n\n`newName`: string of the new tag name\n\n\n#### Response\n\nAn object with the new tag name, if succeeded.\n\n### client#deleteTags(...tags)\n\nDeletes tags\n\n#### Parameters\n\n`tags`: Takes as many arguments as tags to remove. Inexistant tags won't throw error.\n\n#### Response\n\nAn object with the list of deleted tags\n\n### client#getDomains()\n\nLists available domains\n\n#### Response\n\nReturns the list of available domains to create URLs\n\n### client#getPixel(shortCode)\n\nGenerates a 1px transparent image which can be used to track emails with a short URL\n\n#### Parameters\n\n`shortCode`: The short code to which you want to get the pixel.\n\n#### Response\n\nA base64 encoded string of the pixel\n### client#getQR(shortCode, options)\n\nGenerates a QR code image pointing to a short URL\n\n#### Parameters\n\n`shortCode`: The short code to which you want to get the QR Code.\n\n`options`:\n```ts\ninterface QRCodeOptions {\n  format?: 'png' | 'svg'; // Format of the response (defaults to png)\n  size?: number; // size in px of the QR Code (defaults to 300px)\n} \n```\n\n#### Response\n\nAn objet containing the MIME type of the QR Code, and the data in the requested format\n### client#countVisits()\n\nGet general visits stats not linked to one specific short URL.\n\n#### Response\n\nReturns an object containing general data about link statistics\n\n### client#getLinkVisits(shortCode, options)\n\nGet the list of visits on the short URL behind provided short code.\n\n#### Parameters\n\n`shortCode`: The short code to which you want to get the visits stats.\n\n`options`:\n```ts\ninterface PaginationOptions {\n  startDate?: string; // ISO-8601 date format\n  endDate?: string; // ISO-8601 date format\n  page?: number; // Page number, defaults to 1\n  itemsPerPage?: number; // Items per page, defaults to all results\n}\n```\n\n#### Response\n\nA paginated response containing visits stats for the given short code.\n### client#getTagVisits(tag, options)\n\nGet the list of visits on any short URL which is tagged with provided tag.\n\n#### Parameters\n\n`shortCode`: The short code to which you want to get the visits stats.\n\n`options`:\n```ts\ninterface PaginationOptions {\n  startDate?: string; // ISO-8601 date format\n  endDate?: string; // ISO-8601 date format\n  page?: number; // Page number, defaults to 1\n  itemsPerPage?: number; // Items per page, defaults to all results\n}\n```\n\n#### Response\n\nA paginated response containing visits stats for the given tag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoook%2Fshlink-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoook%2Fshlink-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoook%2Fshlink-client/lists"}