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

---

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

Cloud Foundry 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

• Cloud Foundry API Docs
• Cloud Foundry v3 API Docs
• CF Developer Mailing List
• SAP BTP Cloud Foundry Docs

---

Contributing

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

How to contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Write or improve tests — this is the most impactful way to help
4. 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.
5. Commit your changes (git commit -m 'feat: add some feature')
6. Push to the branch (git push origin feature/my-feature)
7. 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:

• prosociallearnEU/cf-nodejs-client/issues
• IBM-Cloud/cf-nodejs-client/issues

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.