Runn API Client

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

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

People

Method Name	Description	Documentation Link
fetchAll(): Promise<Person[]>	Fetches all people from Runn	link
fetchOne(personId: string): Promise<Person>	Fetches a specific person from Runn	link
create(firstName: string, lastName: string, roleId: 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

Clients

Method Name	Description	Documentation Link
fetchAll(): Promise<Client[]>	Fetches all clients from Runn	link
fetchOne(clientId: string): Promise<Client>	Fetches a specific client from Runn	link
create(name: string, references: string): 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

• Projects
  • fetchAll(): Fetches all projects from Runn
  • create(values): Creates a new project in Runn
  • addNote(projectId, note): Adds a note to a specific project
  • archive(projectId): Archives a specific project
  • unarchive(projectId): Unarchives a specific project
• Team
  • fetchAll(): Fetches all team members from Runn
• Assignments
  • fetchAll(): Fetches all assignments from Runn
  • fetchActive(): Fetches active assignments from Runn
• Custom Fields
  • addCustomSelectFieldValues(projectId, selectId, values): Adds custom select field values to a project

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

Author

Roman Rodomansky @ Ralabs

License

MIT

Dependencies

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