leotrinh/cf-node-client

A Cloud Foundry Client for Node.js based on stopped maintenance codebas. NPM pkg: https://www.npmjs.com/package/cf-node-client?activeTab=readme

View on GitHub →

cf-node-client

A Node.js client library for the Cloud Foundry API (v2 & v3), with built-in TypeScript support.

Maintained by leotrinh — forked from prosociallearnEU/cf-nodejs-client by Juan Antonio Breña Moral.

Ship by Claude Kit

Ship faster with AI Dev Team — DISCOUNT 25% - PAY ONE TIME, LIFETIME LIFETIME UPDATE

Claude Kit

Supported Cloud Foundry Platforms

This library works with any platform that implements the Cloud Foundry API:

Platform	Provider	Status
SAP BTP Cloud Foundry	SAP	✅ Supported
Tanzu Platform (formerly Pivotal / TAS)	Broadcom / VMware	✅ Supported
IBM Cloud Foundry	IBM	✅ Supported
SUSE Cloud Application Platform	SUSE	✅ Supported
Open Source Cloud Foundry	Cloud Foundry Foundation	✅ Supported
Any CF-compatible API endpoint	—	✅ Supported

Architecture Overview

SAP BTP Cloud Foundry
SAP BTP CF Architecture

Cloud Foundry Architecture

CF Architecture

UML Diagram

Documentation

Document	Description
JSDoc API Reference	Full generated API documentation (all classes, methods, params)
Usage Guide	Configuration & API usage examples
Service Usage	CF Service integration guide
System Architecture	Internal architecture overview

Documentation Detail

The JSDoc API Reference covers every public class and method in the library:

Class	Description	JSDoc
`CloudController`	CF API info & version	View
`Apps`	Application lifecycle (CRUD, start, stop, env, routes)	View
`Organizations`	Org management, quotas, domains, users	View
`Spaces`	Space management, apps, services per space	View
`Services`	Service offerings & plans	View
`ServiceInstances`	Service instance CRUD & bindings	View
`ServiceBindings`	Service binding management	View
`ServicePlans`	Service plan listing & management	View
`UserProvidedServices`	User-provided service instances	View
`Routes`	Route management & mappings	View
`Domains`	Domain management	View
`BuildPacks`	Buildpack management	View
`Stacks`	Stack listing	View
`Users`	User management	View
`Events`	Audit events	View
`Jobs`	Background tasks	View
`OrganizationsQuota`	Org quota definitions	View
`SpacesQuota`	Space quota definitions	View
`UsersUAA`	UAA authentication (login, tokens)	View
`Logs`	Application log streaming	View
`HttpUtils`	HTTP request utilities	View

Generate Docs Locally

# Generate JSDoc HTML into doc/ folder
npm run docs

# Generate + serve on localhost:9000 + open browser
npm run docs:serve

Installation

npm install cf-node-client

Quick Start

JavaScript

const { CloudController, UsersUAA, Apps } = require("cf-node-client");

// Step 1: Get UAA endpoint from Cloud Controller
const cc = new CloudController("https://api.<your-cf-domain>");
const authEndpoint = await cc.getAuthorizationEndpoint();

// Step 2: Authenticate
const uaa = new UsersUAA();
uaa.setEndPoint(authEndpoint);
const token = await uaa.login("user", "pass");

// Step 3: Use the token
const apps = new Apps("https://api.<your-cf-domain>");
apps.setToken(token);
const result = await apps.getApps();
console.log(result.resources);

TypeScript

import {
  CloudController,
  UsersUAA,
  Apps,
  Spaces,
  Organizations,
  OAuthToken
} from "cf-node-client";

const cc = new CloudController("https://api.<your-cf-domain>");
const authEndpoint: string = await cc.getAuthorizationEndpoint();

const uaa = new UsersUAA();
uaa.setEndPoint(authEndpoint);
const token: OAuthToken = await uaa.login("user", "pass");

const apps = new Apps("https://api.<your-cf-domain>");
apps.setToken(token);
const result = await apps.getApps();
console.log(result.resources);

Built-in TypeScript declarations are included — no additional @types package needed.

Available Types

Type	Description
`OAuthToken`	UAA authentication token
`FilterOptions`	Pagination and query filters
`DeleteOptions`	Delete operation options
`ApiResponse<T>`	Typed API response wrapper
`CloudControllerBaseOptions`	Base constructor options

See examples/ for more usage patterns.

Convenience Methods

Find resources by name using server-side filtering — a single API call instead of fetching all resources and looping:

const { Organizations, Spaces, Apps, ServiceInstances } = require("cf-node-client");

const orgs = new Organizations("https://api.<your-cf-domain>");
const spaces = new Spaces("https://api.<your-cf-domain>");
const apps = new Apps("https://api.<your-cf-domain>");
const si = new ServiceInstances("https://api.<your-cf-domain>");

orgs.setToken(token); spaces.setToken(token);
apps.setToken(token); si.setToken(token);

// Find by name (returns first match or null)
const org   = await orgs.getOrganizationByName("my-org");
const space = await spaces.getSpaceByName("dev", orgGuid);       // orgGuid optional
const app   = await apps.getAppByName("my-app", spaceGuid);      // spaceGuid optional
const inst  = await si.getInstanceByName("my-db", spaceGuid);    // spaceGuid optional

// Get by GUID (direct lookup)
const org   = await orgs.getOrganization(orgGuid);
const space = await spaces.getSpace(spaceGuid);
const app   = await apps.getApp(appGuid);
const inst  = await si.getInstance(instanceGuid);

Resource	List All	Get by GUID	Find by Name	Get ALL (paginated)
Organizations	`getOrganizations()`	`getOrganization(guid)`	`getOrganizationByName(name)`	`getAllOrganizations(filter?)`
Spaces	`getSpaces()`	`getSpace(guid)`	`getSpaceByName(name, orgGuid?)`	`getAllSpaces(filter?)`
Apps	`getApps()`	`getApp(guid)`	`getAppByName(name, spaceGuid?)`	`getAllApps(filter?)`
ServiceInstances	`getInstances()`	`getInstance(guid)`	`getInstanceByName(name, spaceGuid?)`	`getAllInstances(filter?)`

Works with both v2 (q=name:X) and v3 (names=X) APIs automatically.

Auto-Pagination

No more manual pagination loops — the library pages through every page and returns a flat array:

const allOrgs   = await orgs.getAllOrganizations();
const allSpaces = await spaces.getAllSpaces();
const allApps   = await apps.getAllApps({ q: "space_guid:xxx" });
const allSIs    = await si.getAllInstances();

Handles both v2 (next_url) and v3 (pagination.next) transparently. v3 fetches 200 per page; v2 fetches 100 per page.

Memory Cache

Opt-in, in-memory cache with configurable TTL (default 30 s). Reduces redundant API calls when the same data is requested multiple times:

// Enable at construction time
const orgs = new Organizations(api, { cache: true, cacheTTL: 60000 });
orgs.setToken(token);

await orgs.getAllOrganizations();   // API call → result cached
await orgs.getAllOrganizations();   // cache hit — 0 HTTP calls

// Toggle at runtime
orgs.enableCache();          // default 30 s TTL
orgs.enableCache(60000);     // custom 60 s TTL
orgs.clearCache();           // clear entries, keep cache enabled
orgs.disableCache();         // turn off + clear all

API Reference

v3 Endpoints (Default)

All API calls use v3 by default. No additional configuration needed.

Resource	Docs
Apps	API
Spaces	API
Service Instances	API
Service Bindings	API
Organizations	API
Users	API
Other v3 endpoints	Full v3 API Reference

v2 Endpoints (Legacy)

Note: CF API v2 is deprecated by Cloud Foundry. Use v2 only if your platform has not yet migrated to v3.

To enable v2, pass { apiVersion: "v2" } when creating any resource instance:

const { Apps, Spaces, Organizations } = require("cf-node-client");

// v2 mode
const apps = new Apps("https://api.<your-cf-domain>", { apiVersion: "v2" });
const spaces = new Spaces("https://api.<your-cf-domain>", { apiVersion: "v2" });
const orgs = new Organizations("https://api.<your-cf-domain>", { apiVersion: "v2" });

Resource	Docs
Apps	API
Buildpacks	API
Domains	API
Jobs	API
Organizations	API
Organizations Quotas	API
Routes	API
Services	API
Service Bindings	API
Service Instances	API
Service Plans	API
Spaces	API
Spaces Quotas	API
Stacks	API
User Provided Services	API
Users	API

Testing

# Run test suite
npm test

# Run unit tests only
npm run test:unit

# Code coverage
istanbul cover node_modules/mocha/bin/_mocha -- -R spec

Changelog

See CHANGELOG.md for version history.

References

Contributing

Contributions are welcome! We want to make contributing as easy and transparent as possible.

How to contribute:

Fork the repository
Create your feature branch (git checkout -b feature/my-feature)
Write or improve tests — this is the most impactful way to help
Run the precheck before committing:
```
npm run precheck
```
This runs TypeScript compilation (tsc) and the full test suite (lint + unit tests). Your PR will not be accepted if precheck fails.
Commit your changes (git commit -m 'feat: add some feature')
Push to the branch (git push origin feature/my-feature)
Open a Pull Request

First time? Look for issues labeled good first issue — writing tests is a great way to start. Every PR with new test coverage is highly appreciated!

Upstream Issues Tracker

This fork tracks and resolves issues from the original upstream repositories:

Individual issue docs: docs/issues/

✅ Resolved in This Fork

#	Origin	Issue	Doc
#199	prosociallearnEU	HANA Cloud DB start/stop control — Fixed v1.0.8	Details
#196	prosociallearnEU	Copy bits between apps — Fixed v1.0.8 (verified existing)	Details
#183	prosociallearnEU	Log timestamp missing — Fixed v1.0.8	Details
#173	prosociallearnEU	Respect `.cfignore` on upload — Fixed v1.0.8 (CfIgnoreHelper utility)	Details
#158	prosociallearnEU	Download droplet from app — Fixed v1.0.8 (verified existing)	Details
#157	prosociallearnEU	Download bits from app — Fixed v1.0.8 (verified existing)	Details
#156	prosociallearnEU	URL validation in constructors — Fixed v1.0.8 (verified existing)	Details
#44	IBM-Cloud	APIKey auth (instead of user/password) — Fixed v1.0.8	Details
#47	IBM-Cloud	Same-name services in different spaces — Fixed v1.0.8 (verified existing)	Details
#15	IBM-Cloud	`getTokenInfo(accessToken)` method — Fixed v1.0.8 (verified existing)	Details
#198	prosociallearnEU	`Apps.upload()` broken on Node 12+ (restler) — Fixed v1.0.6	Details
#50	IBM-Cloud	Node security alerts (multiple deps) — Fixed v1.0.2	Details
#52	IBM-Cloud	protobufjs vulnerability — Fixed (v7.0.0)	Details
#192	prosociallearnEU	Async service creation (`accepts_incomplete`) — Implemented	Details
#45	IBM-Cloud	Events/Logs TypeError at runtime — Fixed	Details
#191	prosociallearnEU	Set environment variables (`cf set-env` equivalent)	Details
#190	prosociallearnEU	Works with any CF environment + space handling	Details
#188	prosociallearnEU	Travis CI build broken → migrated to GitHub Actions	Details
#179	prosociallearnEU	How to create a CF app (documented)	Details
#43	IBM-Cloud	Any CF env support (documented)	Details

🔧 Open / In Progress

#	Origin	Issue	Priority	Doc
#161	prosociallearnEU	Improve JSDocs / TypeScript types (ongoing)	Low	Details

Issues

If you have any questions or find a bug, please create an issue.

License

Licensed under the Apache License, Version 2.0.

cf-node-client

Ship by Claude Kit

Supported Cloud Foundry Platforms

Architecture Overview

Documentation

Documentation Detail

Generate Docs Locally

Installation

Quick Start

JavaScript

TypeScript

Available Types

Convenience Methods

Auto-Pagination

Memory Cache

API Reference

v3 Endpoints (Default)

v2 Endpoints (Legacy)

Testing

Changelog

References

Contributing

Upstream Issues Tracker

✅ Resolved in This Fork

🔧 Open / In Progress

Issues

License

Clone repository

cf-node-client

Ship by Claude Kit

Supported Cloud Foundry Platforms

Architecture Overview

Documentation

Documentation Detail

Generate Docs Locally

Installation

Quick Start

JavaScript

TypeScript

Available Types

Convenience Methods

Auto-Pagination

Memory Cache

API Reference

v3 Endpoints (Default)

v2 Endpoints (Legacy)

Testing

Changelog

References

Contributing

Upstream Issues Tracker

✅ Resolved in This Fork

🔧 Open / In Progress

Issues

License