Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/nick22985/wakatime-api

Last synced: 6 days ago
JSON representation
Host: GitHub
URL: https://github.com/nick22985/wakatime-api
Owner: nick22985
License: mit
Created: 2021-12-26T03:46:39.000Z (almost 3 years ago)
Default Branch: master
Last Pushed: 2024-09-01T23:25:37.000Z (2 months ago)
Last Synced: 2024-09-15T11:29:50.435Z (about 2 months ago)
Language: TypeScript
Homepage: https://www.npmjs.com/package/@nick22985/wakatime-api
Size: 386 KB
Stars: 4
Watchers: 1
Forks: 1
Open Issues: 13
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        
@nick22985/wakatime-api



[![Status](https://img.shields.io/badge/status-active-success.svg)]()

[![GitHub Issues](https://img.shields.io/github/issues/nick22985/wakatime-api.svg)](https://github.com/kylelobo/wakatime-api/issues)

[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/nick22985/wakatime-api.svg)](https://github.com/kylelobo/wakatime-api/pulls)

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)

[![wakatime](https://wakatime.com/badge/github/nick22985/wakatime-api.svg)](https://wakatime.com/badge/github/nick22985/wakatime-api)



---

 A TypeScript NodeJs client for the wakatime API






## 📝 Table of Contents

- [📝 Table of Contents](#-table-of-contents)

- [🧐 About ](#-about-a-name--about)

- [🏁 Getting Started ](#-getting-started-)

	- [Prerequisites](#prerequisites)

	- [Installing](#installing)

- [🎈 Usage ](#-usage-)

	- [API](#api)

		- [Create a api instance](#create-a-api-instance)

		- [Custom Base URL](#custom-base-url)

		- [getUser](#getuser)

		- [getMe](#getme)

		- [getUserAgents](#getuseragents)

		- [getMyAgents](#getmyagents)

		- [getUserSummaries](#getusersummaries)

		- [getMySummaries](#getmysummaries)

		- [getStatsAggregated](#getstatsaggregated)

		- [getStats](#getstats)

		- [getMyStats](#getmystats)

		- [getUserProjects](#getuserprojects)

		- [getMyProjects](#getmyprojects)

		- [getPrivateLeaderboardsLeaders](#getprivateleaderboardsleaders)

		- [getMyPrivateLeaderboardsLeaders](#getmyprivateleaderboardsleaders)

		- [getPrivateLeaderboards](#getprivateleaderboards)

		- [getMyPrivateLeaderboards](#getmyprivateleaderboards)

		- [getUsersOrgs](#getusersorgs)

		- [getMyOrgs](#getmyorgs)

		- [getUsersOrgDashboard](#getusersorgdashboard)

		- [getMyOrgsDashboard](#getmyorgsdashboard)

		- [getOrgDashboardMembers](#getorgdashboardmembers)

		- [getMyOrgDashboardMembers](#getmyorgdashboardmembers)

		- [orgDashboardMemberSummaries](#orgdashboardmembersummaries)

		- [orgDashboardMemberDurations](#orgdashboardmemberdurations)

		- [getMyOrgDashboardMemberDurations](#getmyorgdashboardmemberdurations)

		- [getMeta](#getmeta)

		- [getUserMachineNames](#getusermachinenames)

		- [getMyMachineNames](#getmymachinenames)

		- [getLeaders](#getleaders)

		- [getUserHeartbeats](#getuserheartbeats)

		- [getMyHeartbeats](#getmyheartbeats)

		- [getUserGoals](#getusergoals)

		- [getMyGoals](#getmygoals)

		- [getUserExternalDurations](#getuserexternaldurations)

		- [getMyExternalDurations](#getmyexternaldurations)

		- [getEditors](#geteditors)

		- [getUserDurations](#getuserdurations)

		- [getMyDurations](#getmydurationsstring)

		- [getUserDataDump](#getuserdatadump)

		- [getMyDataDump](#getmydatadump)

		- [getUserCommits](#getusercommits)

		- [getMyCommits](#getmycommits)

		- [getUserCommit](#getusercommit)

		- [getMyCommit](#getmycommit)

		- [getUserAllTimeSinceToday](#getuseralltimesincetoday)

		- [getMyAllTimeSinceToday](#getmyalltimesincetoday)

- [⛏️ Built Using ](#️-built-using-)

- [✍️ Authors ](#️-authors-)

## 🧐 About 


This project is using TypeScript to interact with the wakatime API



## 🏁 Getting Started 

### Prerequisites

What things you need to install the software and how to install them.

```

NodeJs

```

### Installing

```

npm i @nick22985/wakatime-api

```

## 🎈 Usage 

### API

#### Create a api instance

```js

import { WakaTimeApi, RANGE, SLICE_BY, SUMMARY_RANGE } from "@nick22985/wakatime-api";

const client = new wakatime.WakatimeApi("Api-key");

```

or

```js

const wakatime = require("@nick22985/wakatime-api");

const client = new wakatime.WakatimeApi("Api-key");

```

#### Custom Base URL

```js

import { WakaTimeApi, RANGE, SLICE_BY, SUMMARY_RANGE } from "@nick22985/wakatime-api";

const client = new WakatimeApi("Api-key", "Custom-base-URL");

```

#### getUser

- @desc Gets a users stats. 


- @scope email 


- @param userId users wakatime id 


- @returns A single user. 


- @example getUser("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUser = await client.getUser("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```

#### getMe

- @desc Gets your stats 


- @returns Current users waka time data. 


- @example await getMe();

```js

let getMe = await wakaClient.getMe();

```

#### getUserAgents

- @desc List of plugins which have sent data for a user. 


- @scope read_logged_time 


- @param userId users wakatime id


- @returns Gets a users agents.


- @example await getUserAgents("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserAgents = await wakaClient.getUserAgents("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```

#### getMyAgents

- @desc List of plugins which have sent data for this user.


- @returns Gets current users agents.


- @example await getMyAgents();


```js

let getMyAgents = await wakaClient.getMyAgents();

```

#### getUserSummaries

- @desc A user's coding activity for the given time range as an array of summaries segmented by day.


- @scope read_logged_time


- @param userId users wakatime id


- @param start start date in ISO FORMAT


- @param end end date in ISO FORMAT


- @param project optional: project name


- @param branches optional: branch name


- @param timeout optional: timeout in seconds


- @param writes_only optional: only return write data


- @param timezone optional: timezone


- @param range optional: RANGE enum value


- @returns Summary data for a user.


- @example await getUserSummaries("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "2019-01-01", "2020-01-31");

```js

let getUserSummaries = await wakaClient.getUserSummaries("", "2019-01-01", "2020-01-31");

```

#### getMySummaries

- @desc A your coding activity for the given time range as an array of summaries segmented by day. 


- @param start start date in ISO FORMAT


- @param end end date in ISO FORMAT


- @param project optional: project name


- @param branches optional: branch name


- @param timeout optional: timeout in seconds


- @param writes_only optional: only return write data


- @param timezone optional: timezone


- @param range optional: RANGE enum value


- @returns Summary data for current user.


- @example await getUserSummaries("2019-01-01", "2020-01-31");

```js

let getMySummaries = await wakaClient.getMySummaries("2019-01-01", "2020-01-31");

```

#### getStatsAggregated

- @desc Aggregate stats of all WakaTime users over the given time range.


- @param range optional: RANGE enum value (LAST_7_DAYS, LAST_30_DAYS, LAST_6_MONTHS, LAST_YEAR)


- @returns Stats data for current user.


- @example await getStatsAggregated(SUMMARY_RANGE.LAST_7_DAYS);

```js

let getStatsAggregated = await wakaClient.getStatsAggregated(SUMMARY_RANGE.LAST_7_DAYS);

```

#### getStats

- @desc A user's coding activity for the given time range.


- @scope read_stats


- @param userId users wakatime id


- @param range RANGE enum value (LAST_7_DAYS, LAST_30_DAYS, LAST_6_MONTHS, LAST_YEAR)


- @param timeout optional: timeout in seconds


- @param writes_only optional: only return write data


- @param project optional: project name


- @returns Stats data for a user.


- @example await getStats("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", RANGE.LAST_7_DAYS);

```js

let getStats = await wakaClient.getStats("", wakatime.RANGE.LAST_7_DAYS);

```

#### getMyStats

- @desc A user's coding activity for the given time range.


- @scope read_stats


- @param range RANGE enum value (LAST_7_DAYS, LAST_30_DAYS, LAST_6_MONTHS, LAST_YEAR)


- @param timeout optional: timeout in seconds


- @param writes_only optional: only return write data


- @param project optional: project name


- @returns Stats data for a user.


- @example await getStats("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", RANGE.LAST_7_DAYS);

```js

let getMyStats = await wakaClient.getMyStats(wakatime.RANGE.LAST_7_DAYS);

```

#### getUserProjects

- @desc List of WakaTime projects for a user. 


- @scope read_logged_time


- @param userId users wakatime id


- @param query optional: Filter project names by a search term.


- @returns Gets a users projects.


- @example await getUserProjects("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserProjects = await wakaClient.getUserProjects("");

```

#### getMyProjects

- @desc List of WakaTime projects for a user. 


- @scope read_logged_time


- @param query optional: Filter project names by a search term.


- @returns Gets a users projects.


- @example await getUserProjects("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserProjects = await wakaClient.getMyProjects("");

```

#### getPrivateLeaderboardsLeaders

- @desc List of users in this private leaderboard ranked by coding activity in descending order. 


- @scope read_private_leaderboards


- @param userId users wakatime id


- @param board board name


- @param language optional: language name


- @param country_code optional: country code


- @param page optional: page number


- @returns Gets a users Leaderboards.


- @example await getUserLeaderboard("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "wakatime");


```js

let getPrivateLeaderboardsLeaders = await wakaClient.getPrivateLeaderboardsLeaders("", "cee8a02b-147f-4881-9b43-5d193fb77d32");

```

#### getMyPrivateLeaderboardsLeaders

- @desc List of users in this private leaderboard ranked by coding activity in descending order. 


- @param board board name


- @param language optional: language name


- @param country_code optional: country code


- @param page optional: page number


- @returns Gets a users Leaderboards.


- @example await getUserLeaderboard("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "wakatime");


```js

let getMyPrivateLeaderboardsLeaders = await wakaClient.getMyPrivateLeaderboardsLeaders("cee8a02b-147f-4881-9b43-5d193fb77d32");

```

#### getPrivateLeaderboards

- @desc List of users in your private leaderboard ranked by coding activity in descending order. 


- @param board board name 


- @param language optional: language name 


- @param country_code optional: country code 


- @param page optional: page number 


- @returns Gets current users Leaderboards. 


- @example await getPrivateLeaderboards("wakatime");

```js

let getPrivateLeaderboards = await wakaClient.getPrivateLeaderboards("");

```

#### getMyPrivateLeaderboards

- @desc List of users in your private leaderboard ranked by coding activity in descending order. 


- @param board board name


- @param language optional: language name


- @param country_code optional: country code


- @param page optional: page number


- @returns Gets current users Leaderboards.


- @example await getMyPrivateLeaderboardsLeaders("wakatime");

```js

let getMyPrivateLeaderboards = await wakaClient.getMyPrivateLeaderboards("");

```

#### getUsersOrgs

- @desc List a user’s organizations. 


- @scope read_orgs


- @param userId users wakatime id


- @returns Gets a users Orgs.


- @example await getUserOrgs("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUsersOrgs = await wakaClient.getUsersOrgs("");

```

#### getMyOrgs

- @desc List a user’s organizations.

- @returns Gets current users Orgs.

- @example await getMyOrgs();

```js

let getMyOrgs = await wakaClient.getMyOrgs();

```

#### getUsersOrgDashboard

- @desc List a user’s organizations.

- @scope read_orgs

- @param userId users wakatime id

- @param org org UUID

- @returns Gets a users Org Dashboards.

- @example await getUsersOrgDashboard("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "wakatime");

```js

let getUsersOrgDashboard = await wakaClient.getUsersOrgDashboard("", "");

```

#### getMyOrgsDashboard

- @desc List the organization’s dashboards.

- @param org org UUID

- @returns Gets current users Org Dashboards.

- @example await getMyOrgsDashboard("wakatime");

```js

let getMyOrgsDashboard = await wakaClient.getMyOrgsDashboard("");

```

#### getOrgDashboardMembers

- @desc List an organization’s members.

- @scope read_orgs

- @param userId users wakatime id

- @param org org UUID

- @param dashboard dashboard name

- @returns Gets a users Org Dashboard.

```js

let getOrgDashboardMembers = await wakaClient.getOrgDashboardMembers("", "", "");

```

#### getMyOrgDashboardMembers

- @desc List your organization’s members.

- @param org org UUID

- @param dashboard dashboard UUID

- @returns Gets current users Org Projects.

- @example await getMyOrgDashboardMembers("wakatime", "wakatime");

```js

let getMyOrgDashboardMembers = await wakaClient.getMyOrgDashboardMembers("", "");

```

#### orgDashboardMemberSummaries

- @desc An organization dashboard member’s coding activity for the given time range as an array of summaries segmented by day.

- @scope read_orgs

- @param userId users wakatime id

- @param org org UUID

- @param dashboard dashboard UUID

- @param member member name

- @param start start date

- @param end end date

- @param project optional: project name

- @param branches optional: branch name

- @param range optional: RANGE enum value (LAST_7_DAYS, LAST_30_DAYS, LAST_6_MONTHS, LAST_YEAR)

- @returns Gets a users Org Dashboard Summaries.

- @example await orgDashboardMemberSummaries("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "wakatime", "wakatime", "nick22985", "2019-01-01", "2020-01-31");

```js

let orgDashboardMemberSummaries = await wakaClient.orgDashboardMemberSummaries(

	"",

	"",

	"",

	"nick22985",

	"2021-15-12",

	"2021-19-12"

);

```

#### orgDashboardMemberDurations

- @desc A dashboard member's coding activity for the given day as an array of durations.

- @scope read_orgs

- @param userId users wakatime id

- @param org org UUID

- @param dashboard dashboard UUID

- @param member member name

- @param date date

- @param project optional: project name

- @param branches optional: branch name

- @returns Gets a users Org Dashboard Member Durations.

- @example await orgDashboardMemberDurations("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "wakatime", "wakatime", "nick22985", "2019-01-01");

```js

let orgDashboardMemberDurations = await wakaClient.orgDashboardMemberDurations(

	"",

	"",

	"",

	"",

	"2021-15-12"

);

```

#### getMyOrgDashboardMemberDurations

- @desc A dashboard member's coding activity for the given day as an array of durations.

- @param org org UUID

- @param dashboard dashboard UUID

- @param member member name

- @param date date

- @param project optional: project name

- @param branches optional: branch name

- @returns Gets current users Org Projects.

- @example await getMyOrgDashboardMemberDurations("wakatime", "wakatime", "nick22985", "2019-01-01");

```js

let getMyOrgDashboardMemberDurations = await wakaClient.getMyOrgDashboardMemberDurations(

	"",

	"",

	"",

	"2021-15-12"

);

```

#### getMeta

- @desc A dashboard member's coding activity for the given day as an array of durations.

- @returns Gets information about WakaTime.

- @example await getWakaTimeInfo();

```js

let getMeta = await wakaClient.getMeta();

```

#### getUserMachineNames

- @desc List of machines for this user.

- @scope read_logged_time

- @param userId users wakatime id

- @returns Gets a users Machine names.

- @example await getMachines("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserMachineNames = await wakaClient.getUserMachineNames("");

```

#### getMyMachineNames

- @desc List of machines for this user.

- @returns Gets current users Machine names.

- @example await getMyMachineNames();

```js

let getMyMachineNames = await wakaClient.getMyMachineNames("");

```

#### getLeaders

- @desc List of users ranked by coding activity in descending order.

- @param language language name

- @param is_hireable optional: true or false

- @param country_code optional: country code

- @param page optional: page number

- @returns Gets a list of Leaders.

- @example await getLeaders("python");

```js

let getLeaders = await wakaClient.getLeaders("JavaScript");

```

#### getUserHeartbeats

- @desc A user's heartbeats sent from plugins for the given day as an array.

- @scope read_logged_time

- @param userId users wakatime id

- @param date date

- @returns get a users Heartbeats.

- @example await getUserHeartbeats("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "2019-01-01");

```js

let getUserHeartbeats = await wakaClient.getUserHeartbeats("", "2021-28-12");

```

#### getMyHeartbeats

- @desc A user's heartbeats sent from plugins for the given day as an array.

- @param date date

- @returns get current users Heartbeats.

- @example await getMyHeartbeats("2019-01-01");

```js

let getMyHeartbeats = await wakaClient.getMyHeartbeats("2021-28-12");

```

#### getUserGoals

- @desc List a user’s goals.

- @scope read_logged_time

- @param userId users wakatime id

- @returns get a users Heartbeats.

- @example await getUserGoals("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserGoals = await wakaClient.getUserGoals("");

```

#### getMyGoals

- @desc List a user’s goals.

- @returns get current users Heartbeats.

- @example await getMyGoals();

```js

let getMyGoals = await wakaClient.getMyGoals();

```

#### getUserExternalDurations

- @desc A user's external durations for the given day.

- @scope read_logged_time

- @param userId users wakatime id

- @param date date

- @param project optional: project name

- @param branches optional: branch name

- @param timezone optional: timezone

- @returns gets a users external durations on a given day

- @example await getUserExternalDurations("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "2019-01-01");

```js

let getUserExternalDurations = await wakaClient.getUserExternalDurations("", "2021-28-12");

```

#### getMyExternalDurations

- @desc A user's external durations for the given day.

- @param date date

- @param project optional: project name

- @param branches optional: branch name

- @param timezone optional: timezone

- @returns gets a users external durations on a given day

```js

let getMyExternalDurations = await wakaClient.getMyExternalDurations("2021-28-12");

```

#### getEditors

- @desc List of WakaTime IDE plugins, latest plugin versions, and their color used on WakaTime charts.

- @param unreleased Show unreleased editor plugins

- @returns List of WakaTime IDE plugins versions

- @example await getEditors();

```js

let getEditors = await wakaClient.getEditors();

```

#### getUserDurations

- @desc A user's coding activity for the given day as an array of durations

- @scope read_logged_time

- @param userId users wakatime id

- @param date date

- @param project optional: project name

- @param branches optional: branch name

- @param timeout optional: timeout

- @param writes_only optional: true or false

- @param timezone optional: timezone

- @param slice_by optional: DEFAULT Entity enum: entity, language, dependencies, os, editor, category or machine

- @returns Gets a users durations.

- @example await getUserDurations("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "2019-01-01");

```js

let getUserDurations = await wakaClient.getUserDurations("", "2021-28-12");

```

#### getMyDurations

- @desc Your coding activity for the given day as an array of durations

- @scope read_logged_time

- @param date date

- @param project optional: project name

- @param branches optional: branch name

- @param timeout optional: timeout

- @param writes_only optional: true or false

- @param timezone optional: timezone

- @param slice_by optional: DEFAULT Entity enum: entity, language, dependencies, os, editor, category or machine

- @returns Gets a users durations.

- @example await getUserDurations("2019-01-01");

```js

let getMyDurations = await wakaClient.getMyDurations("2021-28-12");

```

#### getUserDataDump

- @desc List data exports for the user.

- @scope read_logged_time

- @param userId users wakatime id

- @returns List of data exports for the user

- @example await getUserDataDump("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserDataDump = await wakaClient.getUserDataDump("");

```

#### getMyDataDump

- @desc List data exports for the user.

- @returns List of data exports for the user

- @example await getMyDataDump();

```js

let getMyDataDump = await wakaClient.getMyDataDump("");

```

#### getUserCommits

- @desc List of commits for a WakaTime project showing the time spent coding in each commit.

- @scope read_logged_time

- @param userId users wakatime id

- @param project project name

- @param author optional: author name

- @param branch optional: branch name

- @param page optional: page number

- @returns List of commits for the user

- @example await getUserCommits("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserCommits = await wakaClient.getUserCommits("");

```

#### getMyCommits

- @desc List of commits for a WakaTime project showing the time spent coding in each commit.

- @param project optional: project name

- @param author optional: author name

- @param branch optional: branch name

- @param page optional: page number

- @returns List of commits for the current user

- @example await getMyCommits();

```js

let getMyCommits = await wakaClient.getMyCommits();

```

#### getUserCommit

- @desc A single commit from a WakaTime project showing the time spent coding on the commit.

- @scope read_logged_time

- @param userId users wakatime id

- @param project project name

- @param hash commit hash

- @param branch optional: branch name

- @returns List a user commits for a given commit hash

- @example await getUserCommit("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e", "my-project", "1234567890");

```js

let getUserCommit = await wakaClient.getUserCommit("", "Dev-Stats", "736ed941e069e2c910b86266243965ea745a8050");

```

#### getMyCommit

- @desc A single commit from a WakaTime project showing the time spent coding on the commit.

- @param project optional: project name

- @param hash optional: commit hash

- @param branch optional: branch name

- @returns List the current user commits for a given commit hash

- @example await getMyCommit("my-project", "1234567890");

```js

let getMyCommit = await wakaClient.getMyCommit("Dev-Stats", "736ed941e069e2c910b86266243965ea745a8050");

```

#### getUserAllTimeSinceToday

- @desc The total time logged since account created, available even for Free accounts.

- @scope read_stats

- @param userId users wakatime id

- @param project optional: project name

- @returns The total time logged since account created. Even for free accounts

- @example await getUserAllTimeSinceToday("1f89b85e-54a8-4f75-86a2-f9b7d47ba30e");

```js

let getUserAllTimeSinceToday = await wakaClient.getUserAllTimeSinceToday("");

```

#### getMyAllTimeSinceToday

- @desc The total time logged since account created, available even for Free accounts.

- @scope read_stats

- @param userId users wakatime id

- @param project optional: project name

- @returns The total time logged since account created. Even for free accounts

- @example await getMyAllTimeSinceToday();

```js

let getMyAllTimeSinceToday = await wakaClient.getMyAllTimeSinceToday("");

```

## ⛏️ Built Using 

- [NodeJs](https://nodejs.org/en/)

## ✍️ Authors 

- [@nick22985](https://github.com/nick22985)