Runn API Client

API integration with Runn.io - a resource planning and project forecasting platform.

Ralabs is a software dev company, who creates integration between 3rd parties (Salesforce, PowerBI, etc).

Author

Roman Rodomansky, roman@ralabs.org @ Ralabs

Description

This package provides a simple and intuitive way to interact with the Runn API. It includes support for all of the methods described on Runn API documentation and Runn API reference;

Installation

npm install runn-api-client

Requirements

• Node.js 14 or higher
• A valid Runn API key (get it from your Runn account API settings)

Usage

const RunnApiClient = require('runn-api-client');

// Initialize the client
const runnApi = new RunnApiClient('YOUR_API_KEY', {
  logLevel: 'debug',  // Optional: debug, info, warn, error
  isDryRun: false     // Optional: simulate API calls without making actual requests
});

// Fetch all clients
const clients = await runnApi.clients.fetchAll();

// Create a new client
const newClient = await runnApi.clients.create('Client Name', [
  { referenceName: 'salesforce.Id', externalId: 'SF123' }
]);

// Fetch active assignments
const assignments = await runnApi.assignments.fetchActive();

// Create a new project
const project = await runnApi.projects.create({
  name: 'Project Name',
  clientId: 123,
  ...
});

// Add a note to a project
await runnApi.projects.addNote(project.id, 'Project note content');

Configuration

The client accepts the following configuration options:

{
  logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error'
  isDryRun: false,   // Simulate API calls without making actual requests
  RUNN_API_URL: 'https://api.runn.io/api/v0' // Optional: override API URL
}

Features

• Comprehensive error handling
• Rate limiting support
• Dry run mode for testing
• Detailed logging
• Pagination handling

API Documentation

For detailed API documentation, visit the Runn Developer Portal.

Methods

Activity

Method Name	Description	Runn API Reference
fetchAll({ onlyActive: boolean, modifiedAfter: string }): Promise<Activity[]>	Fetches all activities from Runn	link

Actuals

Method Name	Description	Runn API Reference
fetchAll({ onlyActive: boolean, modifiedAfter: string }): Promise<Actual[]>	Fetches all actuals from Runn	link

Assignments

Method Name	Description	Runn API Reference
fetchAll({ onlyActive: boolean, modifiedAfter: string }): Promise<Assignment[]>	Fetches all assignments from Runn	link

Clients

Method Name	Description	Runn API Reference
fetchAll({ onlyActive: boolean, modifiedAfter: string }): Promise<Client[]>	Fetches all clients from Runn	link
fetchOneById(clientId: string): Promise<Client>	Fetches a specific client from Runn	link
create(name: string, references: string[], values: object): Promise<Client>	Creates a new client in Runn	link
update(clientId: string, values: object): Promise<Client>	Updates a specific client in Runn	link
archive(clientId: string): Promise<Client>	Archives a specific client in Runn	link
unarchive(clientId: string): Promise<Client>	Unarchives a specific client in Runn	link
listProjects(clientId: string): Promise<Project[]>	Fetches all projects assigned to a specific client	link

Contracts

Method Name	Description	Runn API Reference
fetchAll({ onlyActive: boolean, modifiedAfter: string }): Promise<Contract[]>	Fetches all contracts from Runn	link

Custom Fields

Method Name	Description	Runn API Reference
fetchAllSelectFields(): Promise<CustomField[]>	Fetches all custom fields from Runn	link
fetchProjectsSelectCustomFields(): Promise<CustomField[]>`	Fetches all custom fields from Runn	link
createSelectCustomField(name: string, model: string, options: CustomFieldOption[], params: object): Promise`	Creates a new custom field in Runn	link

Holiday Groups

Method Name	Description	Runn API Reference
fetchAll(): Promise<HolidayGroup[]>	Fetches all holiday groups from Runn	link

Milestones

Method Name	Description	Runn API Reference
fetchAll(): Promise<Milestone[]>	Fetches all milestones from Runn	link

Other Expenses

Method Name	Description	Runn API Reference
fetchAll(): Promise<OtherExpense[]>	Fetches all other expenses from Runn	link

People

Method Name	Description	Runn API Reference
fetchAll({ onlyActive: boolean, modifiedAfter: string }): Promise<Person[]>	Fetches all people from Runn	link
fetchOneById(personId: string): Promise<Person>	Fetches a specific person from Runn	link
fetchOneByEmail(email: string): Promise<Person>	Fetches a specific person by email from Runn	link
create(firstName: string, lastName: string, roleIdOrName: number/string, otherValues: object): Promise<Person>	Creates a new person in Runn	link
update(personId: string, values: object): Promise<Person>	Updates a specific person in Runn	link
fetchContracts(personId: string): Promise<Contract[]>	Fetches all contracts assigned on person	link
addContract(personId: string, roleId: string, options: object): Promise<Contract>	Adds a new contract to a specific person	link
fetchTeams(personId: string): Promise<Team[]>	Fetches all teams where person is assigned	link
addToTeam(personId: string, teamId: string): Promise<Team>	Adds a specific person to a specific team	link
removeFromTeam(personId: string, teamId: string): Promise<Team>	Removes a specific team from a specific person	link
archive(personId: string): Promise<Person>	Archives a specific person in Runn	link
unarchive(personId: string): Promise<Person>	Unarchives a specific person in Runn	link
delete(personId: string): Promise<Person>	Deletes a specific person in Runn	link

Phases

Method Name	Description	Runn API Reference
fetchAll(): Promise<Phase[]>	Fetches all phases from Runn	link

Project Tags

Method Name	Description	Runn API Reference
fetchAll(): Promise<ProjectTag[]>	Fetches all project tags from Runn	link
create(values): Promise<ProjectTag>	Creates a new project tag in Runn	link
addToProject(projectTagId: string, projectId: string): Promise<ProjectTag>	Adds a project tag to a specific project	link
createOrUpdate(values): Promise<ProjectTag>	Creates or updates a project tag in Runn	link

Projects

Method Name	Description	Runn API Reference
fetchAll(): Promise<Project[]>	Fetches all projects from Runn	link
fetchOneById(projectId: string): Promise<Project>	Fetches a specific project from Runn	link
create(name, clientId, values): Creates a new project in Runn	link
addCustomSelectFieldValues(projectId: string, customSelectFieldId: string, values: object): Promise<Project>	Adds custom select field values to a specific project	link
update(projectId: string, values: object): Promise<Project>	Updates a specific project in Runn	link
archive(projectId): Archives a specific project	link
unarchive(projectId): Unarchives a specific project	link
delete(projectId): Deletes a specific project in Runn	link
addNote(projectId, note): Adds a note to a specific project	link

Rate Cards

Method Name	Description	Runn API Reference
fetchAll(): Promise<RateCard[]>	Fetches all rate cards from Runn	link
create(name, values): Promise<RateCard>	Creates a new rate card in Runn	link
delete(rateCardId: string): Promise<RateCard>	Deletes a specific rate card in Runn	link

Roles

Method Name	Description	Runn API Reference
fetchAll(): Promise<Role[]>	Fetches all roles from Runn	link
getRoleId(roleName: string): Promise<number>	Retrieves the ID of a role by name	link
create(roleName: string, values): Promise<Role>	Creates a new role in Runn	link
update(roleId: string, values: object): Promise<Role>	Updates a specific role in Runn	link

Teams

Method Name	Description	Runn API Reference
fetchAll({ modifiedAfter = null }): Promise<TeamMember[]>	Fetches all team members from Runn	link
create(values): Promise<TeamMember>	Creates a new team member in Runn	link

Users

Method Name	Description	Runn API Reference
fetchAll({ modifiedAfter = null }): Promise<User[]>	Fetches all users from Runn	link

Development

For local development:

git clone https://github.com/ralabs-team/runn-api-client.git
cd runn-api-client
npm install
npm link runn-api-client

License

MIT

Dependencies

• axios: HTTP client
• kleur: Terminal string styling
• lodash: Utility functions
• qs: Query string parsing and stringifying