📝 Added docs

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Neil Richter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,219 @@
+[![npm version](https://badge.fury.io/js/shlink-client.svg)](https://badge.fury.io/js/shlink-client)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/shlink-client)
+![npm downloads](https://img.shields.io/npm/dt/shlink-client)
+![npm licence](https://img.shields.io/npm/l/shlink-client)
+![GitHub Repo stars](https://img.shields.io/github/stars/noook/shlink-client)
+
+# shlink-client
+
+Interact with your [Shlink.io](https://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
+
+```sh
+$ npm i shlink-client
+
+# Or with yarn
+
+$ yarn add shlink-client
+```
+
+## API
+
+Instanciate a new Shlink Client:
+
+```js
+import { ShlinkClient } from 'shlink-client';
+
+const client = new ShlinkClient({
+  url: 'https://yourdomain.tld',
+  token: 'xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+});
+```
+
+### Main entites declarations
+
+ShortUrl:
+```ts
+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:
+
+```ts
+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.
+
+```ts
+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
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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..
+

package.json

@@ -1,12 +1,17 @@
 {
   "name": "shlink-client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "author": {
     "email": "[email protected]",
     "name": "Neil Richter",
     "url": "https://nook.sh"
   },
   "description": "Shlink JavaScript API client",
+  "homepage": "https://github.com/noook/shlink-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noook/shlink-client.git"
+  },
   "main": "./lib/cjs/index.js",
   "module": "./lib/esm/index.js",
   "files": [
@@ -20,7 +25,9 @@
   "keywords": [
     "shlink",
     "api",
-    "client"
+    "client",
+    "typescript",
+    "short-urls"
   ],
   "license": "MIT",
   "dependencies": {

src/api.ts

@@ -6,11 +6,11 @@ const ROUTES = {
   SHORT_URL: '/rest/v{:version}/short-urls/{:shortCode}',
   SHORTEN_URL: '/rest/v{:version}/short-urls/shorten',
   SHORT_URL_TAGS: '/rest/v{:version}/short-urls/{:shortCode}/tags',
-}
+};
 
 interface RouteParam {
-  url: keyof typeof ROUTES
-  params?:  Record<string, number | string>
+  url: keyof typeof ROUTES;
+  params?: Record<string, number | string>;
 }
 
 export class ApiClient {

src/index.ts

@@ -29,7 +29,7 @@ export class ShlinkClient {
     this.client = new ApiClient(instance);
   }
 
-  public getShortUrls(options: ShortUrlGetOptions) {
+  public getShortUrls(options: ShortUrlGetOptions = {}) {
     return this.client.get<ShortUrlsGetResponse>({ url: 'SHORT_URLS' }, {
       params: options,
     })
@@ -41,7 +41,7 @@ export class ShlinkClient {
       .then(({ data }) => data);
   }
 
-  public editShortUrl(shortCode: string, options: Partial<Pick<ShortUrlOptions, 'longUrl' | 'validSince' | 'validUntil' | 'maxVisits' | 'validateUrl'>>, domain?: string) {
+  public editShortUrl(shortCode: string, options: Partial<Pick<ShortUrlOptions, 'longUrl' | 'validSince' | 'validUntil' | 'maxVisits' | 'validateUrl'>>, domain?: string): Promise<ShortUrl> {
     return this.client.patch({ url: 'SHORT_URL', params: { shortCode }}, options, {
       params: {
         domain,

src/types/endpoints/index.ts

@@ -1,8 +1,8 @@
 export * from './monitoring';
 
 export interface GenericError {
-  type: string
-  title: string
-  detail: string
-  status: number
+  type: string;
+  title: string;
+  detail: string;
+  status: number;
 }

src/types/endpoints/monitoring.ts

@@ -1,24 +1,24 @@
 export interface MonitoringSuccess {
-  status: 'pass'
-  version: string
+  status: 'pass';
+  version: string;
   links: {
-    about: string
-    project: string
-  }
+    about: string;
+    project: string;
+  };
 }
 
 export interface MonitoringError {
-  type: string
-  title: string
-  detail: string
-  status: 0
+  type: string;
+  title: string;
+  detail: string;
+  status: 0;
 }
 
 export interface MonitoringUnavailable {
-  status: 'pass'
-  version: string
+  status: 'pass';
+  version: string;
   links: {
-    about: string
-    project: string
-  }
-}
+    about: string;
+    project: string;
+  };
+}