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, [email protected] @ 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](https://developer.runn.io/reference/get_custom-fields-select) | createSelectCustomField(name: string, model: string, options: CustomFieldOption[], params: object): Promise<CustomField> | 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