node-cattr

The public Node.js SDK for the Cattr time-tracking platform. It provides authentication, automatic token renewal, project and task access, time reporting, interval and screenshot submission, activity monitoring, and instance metadata through one CommonJS client.

Requirements

• A reachable Cattr server
• A Cattr user account for authenticated operations

Installation

npm install @amazingcat/node-cattr

Quick start

const Cattr = require('@amazingcat/node-cattr');

const cattr = new Cattr();

// Providers let the application decide where credentials and tokens are stored.
const credentials = {
  value: {
    email: process.env.CATTR_EMAIL,
    password: process.env.CATTR_PASSWORD,
  },
  async get() {
    return this.value;
  },
  async set(value) {
    this.value = value;
  },
};

const tokens = {
  value: null,
  async get() {
    return this.value;
  },
  async set(token, tokenType, tokenExpire) {
    this.value = { token, tokenType, tokenExpire };
  },
};

cattr.credentialsProvider = credentials;
cattr.tokenProvider = tokens;

async function main() {
  // Accepts a Cattr host or API URL and detects the /api/ endpoint.
  await cattr.setBaseUrl('https://cattr.example.com/');

  const login = await cattr.authentication.login(
    process.env.CATTR_EMAIL,
    process.env.CATTR_PASSWORD,
  );
  await tokens.set(
    login.token.token,
    login.token.tokenType,
    login.token.tokenExpire,
  );

  const me = await cattr.authentication.me();
  const projects = await cattr.projects.list();

  console.log(`Signed in as ${me.fullName}`);
  console.log(projects);
}

main().catch(console.error);

Do not hard-code credentials in source code. The in-memory providers above are intentionally minimal; production applications should use an appropriate secure store.

Client setup

Base URL

await cattr.setBaseUrl('cattr.example.com');
console.log(cattr.baseUrl);

setBaseUrl(url) checks the server's status endpoint. If Cattr is not served at the supplied root, the SDK also tries the /api/ path. ping() and isCattrInstance() can be used for later availability checks.

Credential and token providers

Both providers must be objects with asynchronous or synchronous get and set methods:

cattr.credentialsProvider = {
  get: async () => ({ email, password }),
  set: async value => saveCredentials(value),
};

cattr.tokenProvider = {
  get: async () => loadToken(), // { token, tokenType, tokenExpire }
  set: async (token, tokenType, tokenExpire) => {
    await saveToken({ token, tokenType, tokenExpire });
  },
};

Authenticated requests read the current token from tokenProvider. If it is missing or the server reports an expired/unauthorized token, the SDK uses credentialsProvider to log in again, saves the new token, and retries the request once.

Axios configuration

The SDK creates its own Axios instance. Assigning a property recreates that instance with the accumulated configuration:

cattr.axiosConfiguration.timeout = 10_000;
cattr.axiosConfiguration.headers = {
  'User-Agent': 'my-cattr-integration/1.0',
};

Set the base URL with setBaseUrl() rather than assigning axiosConfiguration.baseURL directly when endpoint detection is desired.

API reference

All resource methods are asynchronous.

Client

| Method/property | Description | | --- | --- | | credentialsProvider = provider | Set the credentials storage provider. | | tokenProvider = provider | Set the token storage provider. | | setBaseUrl(url, force?) | Detect and configure the Cattr API base URL. | | baseUrl | Return the configured base URL. | | ping() | Check whether the configured endpoint is a Cattr instance. | | isCattrInstance() | Check the public status response for a Cattr marker. | | reloginAutomatically() | Attempt login with credentials from the provider and persist the returned token. | | get(url, options?) | Perform a low-level GET request. | | post(url, body, options?) | Perform a low-level POST request. | | put(url, body, options?) | Perform a low-level PUT request. | | patch(url, body, options?) | Perform a low-level PATCH request. |

Low-level request options include headers, noAuth, noRelogin, noPaginate, and asFormData. Prefer the resource methods below unless an endpoint is not yet represented by the SDK.

Authentication

Available through cattr.authentication.

| Method | Returns | Description | | --- | --- | --- | | login(email, password) | { token, user } | Authenticate with email and password. This method does not save the token automatically. | | me() | user object | Fetch and normalize the current user. | | logout(fromAll = false) | true | Log out from the current session or all sessions. | | refresh(relogin = false) | token object | Refresh the access token. This method does not save the returned token automatically. | | getSingleClickRedirection() | URL string | Obtain an app-to-web single-click sign-in URL. | | authenticateViaSSO(token) | { token, user } | Exchange a desktop SSO token for a normal session. |

Projects and tasks

const projects = await cattr.projects.list({});
const tasks = await cattr.tasks.list({ project_id: projects[0].id });

const createdTask = await cattr.tasks.create({
  project_id: projects[0].id,
  task_name: 'Prepare release notes',
});

Filtering and creation objects are forwarded to the corresponding Cattr API endpoint. Refer to the Cattr server project for fields supported by your server version.

| Resource | Method | Description | | --- | --- | --- | | projects | list(options?) | List projects without pagination. Returned records normalize dates and common fields. | | tasks | list(options?) | List tasks without pagination. | | tasks | create(options) | Create a task. |

Time reports

const total = await cattr.time.getTotal({
  start_at: '2026-01-01T00:00:00.000Z',
  end_at: '2026-01-31T23:59:59.999Z',
});

const perTask = await cattr.time.getPerTasks({
  start_at: '2026-01-01T00:00:00.000Z',
  end_at: '2026-01-31T23:59:59.999Z',
});

| Method | Description | | --- | --- | | time.getTotal(options?) | Return the total tracked time and selected period. | | time.getPerTasks(options?) | Return tracked time grouped by task. |

Time intervals and activity

const interval = {
  taskId: 42,
  userId: 7,
  start: new Date('2026-01-20T09:00:00Z'),
  end: new Date('2026-01-20T09:10:00Z'),
  systemActivity: 80,
  mouseActivity: 55,
  keyboardActivity: 40,
};

await cattr.intervals.create(interval);
await cattr.intervals.createWithScreenshot(interval, screenshotBuffer);
await cattr.intervals.remove(123);

await cattr.intervals.pushActiveApplicationUpdate({
  executable: '/usr/bin/code',
  title: 'README.md — node-cattr',
  url: 'https://github.com/cattr-app/node-cattr',
});

start and end must be Date objects. Screenshots must be Node.js Buffer instances containing JPG or PNG data.

Screenshots

const screenshot = await cattr.screenshots.upload(
  intervalId,
  screenshotBuffer,
);

screenshots.upload(intervalId, buffer) uploads a screenshot for an existing interval and returns normalized screenshot metadata.

Company and instance information

| Method | Description | | --- | --- | | company.heartbeatInterval() | Return the configured heartbeat period in seconds, or null for an unexpected response. | | company.heartBeat() | Notify the server that the current user is active. | | company.about() | Return application and instance metadata, or null for an unexpected response. |

Offline synchronization

const publicKey = await cattr.offlineSync.getPublicKey();

offlineSync.getPublicKey() returns the server's RSA public key for offline interval synchronization.

Error handling

Resource methods throw specialized errors exposed on each client instance:

try {
  await cattr.projects.list();
} catch (error) {
  if (error instanceof cattr.NetworkError) {
    console.error('The Cattr server could not be reached', error.context);
  } else if (error instanceof cattr.ApiError) {
    console.error(
      `Cattr API error ${error.statusCode}: ${error.code}`,
      error.message,
      error.trace_id,
    );
  } else {
    throw error;
  }
}

• ApiError represents an HTTP error returned by Cattr and carries statusCode, code, message, trace_id, and request context when available.
• NetworkError represents a request that did not receive an HTTP response and carries the original request data and context.
• CredentialsError represents a local authentication failure in a low-level request result, such as a missing token with unsuccessful automatic login. Resource methods surface the failure as an ApiError.
• Invalid method arguments throw TypeError.

Low-level get, post, put, and patch calls return a result envelope ({ success, response } on success or { success: false, ... } on failure). Resource methods convert unsuccessful envelopes into exceptions.

Development

git clone https://github.com/cattr-app/node-cattr.git
cd node-cattr
npm install
npm run lint

When contributing a new endpoint, keep transport concerns in the base client and expose domain behavior through a resource under src/resources/.

Issues and feature requests are tracked in the GitHub issue tracker.

Related project

• Cattr server application

License

MIT © 2020 amazingcat LLC