Clockodo

Unofficial JavaScript SDK for the Clockodo API. Written in Typescript.

Installation and usage

npm install clockodo --save

Then require the package. For the constructor arguments, you must get the user (email) and clockodo api key from the "My area" section of Clockodo's website.

import { Clockodo } from "clockodo";

const clockodoApi = new Clockodo({
    authentication: {
        user: "test-user@example.com",
        apiKey: "kjfdskj643fgnlksf343kdslm",
    },
});

It is also possible to create a Clockodo instance with caching. This means the request responses are cached until a POST, PUT, DELETE or PATCH is send to the very same url or the cache time is over.

import { Clockodo } from "clockodo";
import { cachePlugin } from "clockodo/plugins/cache";

const clockodoApi = new Clockodo({
    authentication: {
        user: "test-user@example.com",
        apiKey: "kjfdskj643fgnlksf343kdslm",
    },
});

clockodoApi.use(cachePlugin({ cacheTime: 15 * 60 * 1000 })); // cache of 15 minutes

Example

import { Clockodo } from "clockodo";

const clockodo = new Clockodo({
    authentication: {
        user: "test-user@example.com",
        apiKey: "kjfdskj643fgnlksf343kdslm",
    },
});

// Find the ID of your employee named Hagrid
const { users } = await clockodo.getUsers();

const matches = users.filter((user) => user.name === "Hagrid");

console.log(matches[0].id); // 98070

Config

authentication: Specify a user and an apiKey to authenticate every request
baseUrl: Points to the Clockodo API. Defaults to https://my.clockodo.com/api

You can update the configuration later like this:

clockodo.api.config({
    authentication: {
        /* ... */
    },
});

API

We have provided methods for each of the endpoints available by the Clockodo API. In order to provide a seamless API to JavaScript, we renamed the request and response object keys from what you will see in the Clockodo docs by removing special characters and converting to camel casing. If you are interested, you can find the mappings in the mappings.ts file.

In general, the first argument for these functions is an object consisting of required parameters. The second is an "options" object for optional parameters.

For any questions about the different properties please consult the official Clockodo-API.

Get methods
Post methods
Put methods
Delete methods

Some constants are also available for import:

export const ENTRY_UNBILLABLE = 0;
export const ENTRY_BILLABLE = 1;
export const ENTRY_BILLED = 2;
export const ABSENCE_TYPE_REGULAR_HOLIDAY = 1;
export const ABSENCE_TYPE_SPECIAL_LEAVE = 2;
export const ABSENCE_TYPE_REDUCTION_OF_OVERTIME = 3;
export const ABSENCE_TYPE_SICK_DAY = 4;
export const ABSENCE_TYPE_SICK_DAY_OF_CHILD = 5;
export const ABSENCE_TYPE_SCHOOL_FURTHER_EDUCATION = 6;
export const ABSENCE_TYPE_MATERNITY_PROTECTION = 7;
export const ABSENCE_TYPE_HOME_OFFICE = 8;
export const ABSENCE_TYPE_WORK_OUT_OF_OFFICE = 9;
export const ABSENCE_STATUS_REPORTED = 0;
export const ABSENCE_STATUS_APPROVED = 1;
export const ABSENCE_STATUS_DECLINED = 2;
export const ABSENCE_STATUS_APPROVAL_CANCELLED = 3;
export const ABSENCE_STATUS_REQUEST_CANCELLED = 4;

Get Methods

getAbsence()

Gets a selected absence by its ID.

Example:

await clockodo.getAbsence({ id: 7 });

getAbsences()

Gets a list of absences in the provided year

Example:

await clockodo.getAbsences({ year: 2018 });

getClock()

Get currently running entry for the credentials attached to Clockodo object.

Example:

await clockodo.getClock();

getClockUpdate()

Get status information of the clock for the credentials attached to Clockodo object.

Example:

await clockodo.getClockUpdate();

getCustomer()

Get specific customer by ID

Example:

await clockodo.getCustomer({ id: 777 });

getCustomers()

Get list of customers

Example:

await clockodo.getCustomers();

getEntry()

Get an entry by its ID.

Example:

await clockodo.getEntry({ id: 4 });

getEntries()

Gets list of Clockodo activity entries.

Example:

import { ENTRY_BILLED } from "clockodo";

await clockodo.getEntries(
    { timeSince: "2017-08-18T00:00:00Z", timeUntil: "2018-02-09T00:00:00Z" },
    { filterBillable: ENTRY_BILLED }
);

getEntryGroups()

Get a group of entries defined by your criteria.

Example:

await clockodo.getEntryGroups(
    {
        timeSince: "2017-08-18T00:00:00Z",
        timeUntil: "2018-02-09T00:00:00Z",
        grouping: ["customers_id", "projects_id"],
    },
    { roundToMinutes: 15 }
);

getProject()

Get a project by its ID. For a list of projects, use getCustomers().

Example:

await clockodo.getProject({ id: 1985 });

getSearchTexts()

Get the description(s) of the requested entries.

Example:

await clockodo.getSearchTexts({
    projectsId: 300,
});

getService()

Get a service by its ID.

Example:

await clockodo.getService({ id: 10 });

getServices()

Get list of all services

Example:

await clockodo.getServices();

getLumpSumServices()

Get a list of all lump sum services

Example:

await clockodo.getLumpSumServices();

getSingleTargetHourSet()

Get a specific target hour period for a specific user by its ID (not the ID of the user)

Example:

await clockodo.getSingleTargetHourSet({ id: 1234 });

getTargetHours()

Get list of target hours for all users, with option to pass an object with an usersId to filter the history of target hours to a specific user.

Example:

await clockodo.getTargetHours();
// or
await clockodo.getTargetHours({ usersId: 346923 });

getTasks()

Get Clockodo Tasks (grouped entries).

Example:

await clockodo.getTasks({
    count: 6,
});

getTaskDuration()

Get individual Clockodo Task by its ID.

Example:

await clockodo.getTaskDuration(
    {
        taskCustomersId: 23,
        taskProjectsId: 25,
        taskServicesId: 42,
        taskText: "clean the dishes",
        taskBillable: 1,
    },
    { excludeIds: [217, 450] }
);

getUser()

Get a co-worker by their ID.

Example:

await clockodo.getUser({ id: 1263 });

getUsers()

Get list of users

Example:

await clockodo.getUsers();

getUserReport()

Get a co-worker by their ID.

Example:

await clockodo.getUserReport({ id: 1263, year: 2017 });

getUserReports()

Get an employee/user's report, which contains data such as hours worked and holidays taken.

Example:

await clockodo.getUserReports({ year: 2017 }, { type: 1 });

Post Methods

addAbsence()

Default behavior adds an absence for the user attached to the credentials given to the clockodo object. To add the absence for another user you can use the usersId option if you have the permissions.

Example:

import { ABSENCE_TYPE_SPECIAL_LEAVE } from "clockodo";

await clockodo.addAbsence(
    {
        dateSince: "2017-08-18T00:00:00Z",
        dateUntil: "2018-02-09T00:00:00Z",
        type: ABSENCE_TYPE_SPECIAL_LEAVE,
    },
    {
        note: "elternzeit",
        usersId: 12321,
    }
);

addCustomer()

Adds a customer to the organization.

Example:

await clockodo.addCustomer({ name: "Weyland-Yutani" });

addEntry()

Creates an entry for either the user attached to the Clockodo instance or the passed in usersId. Depending on the type of entry different properties are required:

Type of entry	Required properties
Time entry	`customersId`, `servicesId`, `billable`, `timeSince`, `timeUntil`
Lump sum entry	`customersId`, `servicesId`, `billable`, `timeSince`, `lumpSum`
Recurring lump sum entry	`customersId`, `lumpSumsAmount`, `lumpSumsId`, `billable`, `timeSince`

Example:

import { ENTRY_BILLABLE } from "clockodo";

await clockodo.addEntry({
    customersId: 1,
    servicesId: 2,
    billable: ENTRY_BILLABLE,
    timeSince: "2018-10-01T00:00:00Z",
    timeUntil: "2018-10-01T03:00:00Z",
});

addProject()

Creates a project for an existing customer.

Example:

await clockodo.addProject({ name: "Clockodo Api Wrapper", customersId: 1 });

addService()

Adds to the list of services offered by your organization.

Example:

await clockodo.addService({ name: "Thinking" });

addUser()

Creates new user in organization.

Example:

await clockodo.addUser({
    name: "Merkel",
    number: "08",
    email: "angela@eu.eu",
    role: "Chancellor",
});

startClock()

Get Clockodo Tasks (grouped entries).

Example:

import { ENTRY_BILLABLE } from "clockodo";

await clockodo.startClock(
    { customersId: 24, servicesId: 7, billable: ENTRY_BILLABLE },
    { projectsId: 365 }
);

Put methods

changeClockDuration()

Changes the duration of an entry. Because the ID returned by clock methods is just the entry ID, and this function can only be used after an entry is finished, there seems to be no difference from using editEntry().

Example:

await clockodo.changeClockDuration(
    { entryId: 7082, duration: 540, durationBefore: 300 },
    { offsetBefore: 60 }
);

editAbsence()

Edit existing Clockodo absence.

Example:

await clockodo.editAbsence(
    { absenceId: 74 },
    { note: "I know what he did last summer" }
);

editCustomer()

Edit existing Clockodo customer.

Example:

await clockodo.editCustomer({ customersId: 15 }, { name: "The Mystery Gang" });

editEntry()

Changes the values of a Clockodo entry. Unlike changeClockDuration(), editEntry() can seemingly mutate any of the accepted parameters even when the entry is running.

Example:

await clockodo.editEntry({ entryId: 365 }, { duration: 540 });

editEntryGroup()

Allows for mass edit of entries based on a set of filters.

Example:

import { ENTRY_UNBILLABLE } from "clockodo";

await clockodo.editEntryGroup(
    { timeSince: "2017-08-18T00:00:00Z", timeUntil: "2018-02-09T00:00:00Z" },
    { filterText: "Browsing Reddit", billable: ENTRY_UNBILLABLE }
);

editProject()

Edit existing project.

Example:

await clockodo.editProject({ projectsId: 20 }, options);

editService()

Edit existing service.

Example:

await clockodo.editService({ servicesId: 23 }, { name: "Room Service" });

editUser()

Edit existing user.

Example:

await clockodo.editUser({ usersId: 33 }, { name: "Moalo Loco" });

Delete methods

deactivateCustomer()

Deactivates (not deletes) customer.

Example:

await clockodo.deactivateCustomer({ customersId: 343 });

deactivateProject()

Deactivates (not deletes) project.

Example:

await clockodo.deactivateProject({ projectsId: 8 });

deactivateService()

Deactivates (not deletes) service.

Example:

await clockodo.deactivateService({ servicesId: 94 });

deactivateUser()

Deactivates (not deletes) user.

Example:

await clockodo.deactivateUser({ usersId: 7 });

deleteAbsence()

Deletes absence (go figure).

Example:

await clockodo.deleteAbsence({ absenceId: 31 });

deleteEntryGroup()

Deletes one or more entries based on a series of filters that builds an "entry group".

Example:

await clockodo.deleteEntryGroup(
    { timeSince: "2017-08-18T00:00:00Z", timeUntil: "2018-02-09T00:00:00Z" },
    { text: "chilin everyday" }
);

stopClock()

Stops a running clock/entry.

Example:

await clockodo.stopClock({ entryId: 7082 });

Development

To run integration tests you need to create an .env by copying the .env.example and entering credentials of a dev-user, as you don't want to mess up your real clockodo data.

License

Unlicense

Name		Name	Last commit message	Last commit date
Latest commit History 153 Commits
.github/workflows		.github/workflows
plugins		plugins
src		src
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json

License

jhnns/clockodo

Folders and files

Latest commit

History

Repository files navigation

Clockodo

Installation and usage

Example

Config

API

Get Methods

getAbsence()

Example:

getAbsences()

Example:

getClock()

Example:

getClockUpdate()

Example:

getCustomer()

Example:

getCustomers()

Example:

getEntry()

Example:

getEntries()

Example:

getEntryGroups()

Example:

getProject()

Example:

getSearchTexts()

Example:

getService()

Example:

getServices()

Example:

getLumpSumServices()

Example:

getSingleTargetHourSet()

Example:

getTargetHours()

Example:

getTasks()

Example:

getTaskDuration()

Example:

getUser()

Example:

getUsers()

Example:

getUserReport()

Example:

getUserReports()

Example:

Post Methods

addAbsence()

Example:

addCustomer()

Example:

addEntry()

Example:

addProject()

Example:

addService()

Example:

addUser()

Example:

startClock()

Example:

Put methods

changeClockDuration()

Example:

editAbsence()

Example:

editCustomer()

Example:

editEntry()

Example: