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.