💥 added Visits stats, docs, and releasing first full coverage version

Author: noook

README.md

@@ -300,3 +300,53 @@ interface QRCodeOptions {
 #### 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`:
+```ts
+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`:
+```ts
+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.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "shlink-client",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "author": {
     "email": "[email protected]",
     "name": "Neil Richter",

src/api.ts

@@ -12,6 +12,11 @@ const ROUTES = {
   /* Tags */
   TAGS: '/rest/v{:version}/tags',
 
+  /* Visits */
+  VISITS: '/rest/v{:version}/visits',
+  LINK_VISITS: '/rest/v{:version}/short-urls/{:shortCode}/visits',
+  TAG_VISITS: '/rest/v{:version}/tags/{:tag}/visits',
+
   /* Domains */
   DOMAINS: '/rest/v{:version}/domains',
 

src/index.ts

@@ -10,7 +10,8 @@ import {
   QRCodeOptions,
   QRCodeDefaultOptions,
 } from './types/endpoints/short-urls';
-import { DomainsListItem, DomainsListResponse, ListTagsOptions, TagsListResponse } from './types/endpoints';
+import { DomainsListItem, DomainsListResponse, ListTagsOptions, PaginationOptions, TagsListResponse, VisitData, VisitsPaginationOptions, VisitsStats } from './types/endpoints';
+import { Paginated } from './types/endpoints/utils';
 export class ShlinkClient {
   private url: string;
   private token: string;
@@ -87,6 +88,25 @@ export class ShlinkClient {
       .then(({ data }) => data);
   }
 
+  public countVisits(): Promise<VisitsStats> {
+    return this.client.get<{ visits: VisitsStats }>({ url: 'VISITS' })
+      .then(({ data }) => data.visits);
+  }
+
+  public getLinkVisits(shortCode: string, options: VisitsPaginationOptions = {}): Promise<Paginated<VisitData>> {
+    return this.client.get<{ visits: Paginated<VisitData> }>({ url: 'LINK_VISITS', params: { shortCode }}, {
+      params: options,
+    })
+      .then(({ data }) => data.visits);
+  }
+
+  public getTagVisits(tag: string, options: PaginationOptions = {}): Promise<Paginated<VisitData>> {
+    return this.client.get<{ visits: Paginated<VisitData> }>({ url: 'TAG_VISITS', params: { tag }}, {
+      params: options,
+    })
+      .then(({ data }) => data.visits);
+  }
+
   public listTags(options: ListTagsOptions<false>): Promise<TagsListResponse<ListTagsOptions<false>>>
   public listTags(options: ListTagsOptions<true>): Promise<TagsListResponse<ListTagsOptions<true>>>
   public listTags(options: ListTagsOptions = { withStats: false }): Promise<TagsListResponse<ListTagsOptions>> {

src/types/endpoints/index.ts

@@ -1,6 +1,7 @@
 export * from './monitoring';
 export * from './tags';
 export * from './domains';
+export * from './visits';
 
 export interface GenericError {
   type: string;

src/types/endpoints/utils.ts

@@ -0,0 +1,12 @@
+export interface Paginated<T> {
+  data: T[];
+  pagination: Pagination
+}
+
+export interface Pagination {
+  currentPAge: number;
+  pagesCount: number;
+  itemsPerPage: number;
+  itemsInCurrentPage: number;
+  totalItems: number;
+}

src/types/endpoints/visits.ts

@@ -0,0 +1,31 @@
+export interface VisitsStats {
+  visitsCounts: number;
+}
+
+export interface VisitLocation {
+  cityName: string;
+  countryCode: string;
+  countryName: string;
+  latitude: number;
+  longitude: number;
+  regionName: string;
+  timezone: string;
+}
+
+export interface VisitData {
+  referer: string;
+  date: string;
+  userAgent: string;
+  visitLocation: VisitLocation | null;
+}
+
+export type VisitsPaginationOptions = {
+  domain?: string;
+} & PaginationOptions
+
+export interface PaginationOptions {
+  startDate?: string;
+  endDate?: string;
+  page?: number;
+  itemsPerPage?: number;
+}