feat: add handle cache, update docs

CHANGELOG.md

@@ -1,3 +1,43 @@
+## Version 1.0.5 2026-03-05
+
+**PATCH RELEASE — Fix 11 Incorrect v3 API Endpoints**
+
+### Bug Fixes — AppsDeployment.js (4 fixes)
+
+- **`getStats()` wrong v3 endpoint**: Was `/v3/apps/:guid/stats` → Fixed to `/v3/apps/:guid/processes/web/stats` (v3 stats are per-process)
+- **`associateRoute()` wrong v3 method & endpoint**: Was `PUT /v3/apps/:guid/routes/:routeGuid` → Fixed to `POST /v3/routes/:routeGuid/destinations` with `{ destinations: [{ app: { guid } }] }` body
+- **`getServiceBindings()` wrong v3 endpoint**: Was `/v3/apps/:guid/service_credential_bindings` → Fixed to `/v3/service_credential_bindings?app_guids=:guid` (top-level endpoint with filter)
+- **`_uploadV3()` wrong single-step upload**: Was single request to `/v3/apps/:guid/bits` → Fixed to 2-step: create package via `POST /v3/packages` then upload bits to `POST /v3/packages/:guid/upload`
+
+### Bug Fixes — Organizations.js (3 fixes)
+
+- **`_getUsersV3()` wrong endpoint**: Was `/v3/organizations/:guid/relationships/users` → Fixed to `/v3/roles?organization_guids=:guid&types=organization_user`
+- **`_getManagersV3()` wrong endpoint**: Was `/v3/organizations/:guid/relationships/managers` → Fixed to `/v3/roles?organization_guids=:guid&types=organization_manager`
+- **`_getAuditorsV3()` wrong endpoint**: Was `/v3/organizations/:guid/relationships/auditors` → Fixed to `/v3/roles?organization_guids=:guid&types=organization_auditor`
+
+### Bug Fixes — Spaces.js (4 fixes)
+
+- **`_getUsersV3()` wrong endpoint**: Was `/v3/spaces/:guid/relationships/members` → Fixed to `/v3/roles?space_guids=:guid`
+- **`_getManagersV3()` wrong endpoint**: Was `/v3/spaces/:guid/relationships/managers` → Fixed to `/v3/roles?space_guids=:guid&types=space_manager`
+- **`_getDevelopersV3()` wrong endpoint**: Was `/v3/spaces/:guid/relationships/developers` → Fixed to `/v3/roles?space_guids=:guid&types=space_developer`
+- **`_getAuditorsV3()` wrong endpoint**: Was `/v3/spaces/:guid/relationships/auditors` → Fixed to `/v3/roles?space_guids=:guid&types=space_auditor`
+
+### Enhancements
+- **`Spaces.getSpaceApps()`**: Added backward-compatibility alias for `Spaces.getApps()` — existing consumer code referencing the old method name continues to work
+
+### Audit Summary
+- 27 additional files scanned & confirmed clean — no issues found in Apps.js, AppsCopy.js, Routes.js, Domains.js, ServiceBindings.js, ServiceInstances.js, ServicePlans.js, Services.js, Events.js, Jobs.js, BuildPacks.js, Stacks.js, Users.js, UserProvidedServices.js, OrganizationsQuota.js, SpacesQuota.js, UsersUAA.js, Logs.js, HttpUtils.js, HttpStatus.js, ApiConfig.js, ApiVersionManager.js, ConfigManagerService.js, ErrorService.js, CacheService.js, CloudController.js, CloudControllerBase.js
+
+### Files Modified
+- `lib/model/cloudcontroller/AppsDeployment.js`
+- `lib/model/cloudcontroller/Organizations.js`
+- `lib/model/cloudcontroller/Spaces.js`
+
+### Tests
+- All **93 passing**, 0 failing
+
+---
+
 ## Version 1.0.4 2026-03-05
 
 **HOTFIX RELEASE — Critical: v3 Authentication Flow Broken**

MIGRATION_GUIDE.md

@@ -1,5 +1,15 @@
 # Migration Guide: cf-nodejs-client → cf-node-client v1.0.0
 
+## Important: v1.0.5 — 11 Incorrect v3 Endpoints Fixed
+
+If you are using v1.0.0–v1.0.4 in **v3 mode (default)**, the following methods called wrong endpoints:
+
+- `AppsDeployment`: `getStats()`, `associateRoute()`, `getServiceBindings()`, `upload()` (v3 path)
+- `Organizations`: `getUsers()`, `getManagers()`, `getAuditors()` (v3 path)
+- `Spaces`: `getUsers()`, `getManagers()`, `getDevelopers()`, `getAuditors()` (v3 path)
+
+**Upgrade to v1.0.5** to get correct v3 API endpoints. No consumer code changes needed.
+
 ## Important: v1.0.4 Hotfix — Authentication Flow
 
 If you upgraded to v1.0.0–v1.0.3 and hit the error:

README.md

@@ -330,7 +330,11 @@ Contributions are welcome! We want to make contributing as easy and transparent
 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. Ensure all tests pass (`npm test`)
+4. Run the precheck before committing:
+   ```bash
+   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**

RELEASE_NOTES.md

@@ -1,3 +1,53 @@
+# cf-node-client v1.0.5 — Fix 11 Incorrect v3 API Endpoints
+
+**Package**: cf-node-client v1.0.5  
+**Release Date**: March 5, 2026  
+**Status**: Production Ready  
+**Severity**: **Important — v3 Endpoint Corrections**
+
+## What's Fixed in v1.0.5
+
+Full audit of all 30 library files found 11 incorrect v3 API endpoints across 3 files. All corrected to match the official [CF API v3 specification](https://v3-apidocs.cloudfoundry.org/).
+
+### AppsDeployment.js — 4 Fixes
+
+| Method | Before (broken) | After (correct) |
+|--------|-----------------|-----------------|
+| `getStats()` | `/v3/apps/:guid/stats` | `/v3/apps/:guid/processes/web/stats` |
+| `associateRoute()` | `PUT /v3/apps/:guid/routes/:routeGuid` | `POST /v3/routes/:routeGuid/destinations` with body |
+| `getServiceBindings()` | `/v3/apps/:guid/service_credential_bindings` | `/v3/service_credential_bindings?app_guids=:guid` |
+| `_uploadV3()` | Single-step upload | 2-step: create package → upload bits |
+
+### Organizations.js — 3 Fixes
+
+| Method | Before (broken) | After (correct) |
+|--------|-----------------|-----------------|
+| `_getUsersV3()` | `/v3/organizations/:guid/relationships/users` | `/v3/roles?organization_guids=:guid&types=organization_user` |
+| `_getManagersV3()` | `/v3/organizations/:guid/relationships/managers` | `/v3/roles?organization_guids=:guid&types=organization_manager` |
+| `_getAuditorsV3()` | `/v3/organizations/:guid/relationships/auditors` | `/v3/roles?organization_guids=:guid&types=organization_auditor` |
+
+### Spaces.js — 4 Fixes
+
+| Method | Before (broken) | After (correct) |
+|--------|-----------------|-----------------|
+| `_getUsersV3()` | `/v3/spaces/:guid/relationships/members` | `/v3/roles?space_guids=:guid` |
+| `_getManagersV3()` | `/v3/spaces/:guid/relationships/managers` | `/v3/roles?space_guids=:guid&types=space_manager` |
+| `_getDevelopersV3()` | `/v3/spaces/:guid/relationships/developers` | `/v3/roles?space_guids=:guid&types=space_developer` |
+| `_getAuditorsV3()` | `/v3/spaces/:guid/relationships/auditors` | `/v3/roles?space_guids=:guid&types=space_auditor` |
+
+### Additional Enhancement
+
+- **`Spaces.getSpaceApps(guid, filter)`**: Added backward-compatibility alias for `Spaces.getApps()` so existing consumer code continues to work.
+
+### Audit Scope
+
+27 additional files scanned and confirmed clean — no issues found.
+
+### Tests
+- All **93 tests passing**, 0 failing
+
+---
+
 # cf-node-client v1.0.4 — Hotfix: v3 getInfo() Broken Authentication Flow
 
 **Package**: cf-node-client v1.0.4  

doc/Apps.html

@@ -50,7 +50,10 @@ <h1 class="page-title">Class: Apps</h1>
 
         <h2><span class="attribs"><span class="type-signature"></span></span>Apps<span class="signature">()</span><span class="type-signature"></span></h2>
 
-            <div class="class-description">Apps — unified facade combining core CRUD, deployment, and copy operations.Extends AppsCore directly; mixes in methods from AppsDeployment and AppsCopy.Backward-compatible: `new Apps(endPoint, options)` works exactly as before.</div>
+            <div class="class-description">Apps — unified facade combining core CRUD, deployment, and copy operations.
+Extends AppsCore directly; mixes in methods from AppsDeployment and AppsCopy.
+
+Backward-compatible: `new Apps(endPoint, options)` works exactly as before.</div>
 
 
 </header>
@@ -181,7 +184,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Apps.html
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Thu Mar 05 2026 16:22:04 GMT+0700 (Indochina Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Thu Mar 05 2026 17:22:07 GMT+0700 (Indochina Time)
 </footer>
 
 <script> prettyPrint(); </script>

doc/AppsCopy.html

@@ -50,7 +50,8 @@ <h1 class="page-title">Class: AppsCopy</h1>
 
         <h2><span class="attribs"><span class="type-signature"></span></span>AppsCopy<span class="signature">()</span><span class="type-signature"></span></h2>
 
-            <div class="class-description">AppsCopy — copy and download operations for CF Applications.Methods: copyBits, copyPackage, downloadBits, downloadDroplet</div>
+            <div class="class-description">AppsCopy — copy and download operations for CF Applications.
+Methods: copyBits, copyPackage, downloadBits, downloadDroplet</div>
 
 
 </header>
@@ -859,7 +860,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Apps.html
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Thu Mar 05 2026 16:22:04 GMT+0700 (Indochina Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Thu Mar 05 2026 17:22:07 GMT+0700 (Indochina Time)
 </footer>
 
 <script> prettyPrint(); </script>

doc/AppsCore.html

@@ -50,7 +50,8 @@ <h1 class="page-title">Class: AppsCore</h1>
 
         <h2><span class="attribs"><span class="type-signature"></span></span>AppsCore<span class="signature">()</span><span class="type-signature"></span></h2>
 
-            <div class="class-description">AppsCore — CRUD and lifecycle operations for CF Applications.Methods: getApps, getApp, add, update, stop, start, restart, getSummary, remove</div>
+            <div class="class-description">AppsCore — CRUD and lifecycle operations for CF Applications.
+Methods: getApps, getApp, add, update, stop, start, restart, getSummary, remove</div>
 
 
 </header>
@@ -332,7 +333,10 @@ <h4 class="name" id="getAllApps"><span class="type-signature"></span>getAllApps<
 
 
 <div class="description">
-    Get ALL apps across all pages (auto-pagination).Returns a flat array of every app resource.Results are cached when caching is enabled.
+    Get ALL apps across all pages (auto-pagination).
+Returns a flat array of every app resource.
+
+Results are cached when caching is enabled.
 </div>
 
 
@@ -437,7 +441,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line245">line 245</a>
+        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line263">line 263</a>
     </li></ul></dd>
 
 
@@ -658,7 +662,12 @@ <h4 class="name" id="getAppByName"><span class="type-signature"></span>getAppByN
 
 
 <div class="description">
-    Find an Application by name using server-side filtering.Returns the first matching resource or null if not found.Optionally filter by space GUID.v2: Uses q=name:{name} filter (and q=space_guid:{spaceGuid} if provided)v3: Uses names={name} filter (and space_guids={spaceGuid} if provided)
+    Find an Application by name using server-side filtering.
+Returns the first matching resource or null if not found.
+Optionally filter by space GUID.
+
+v2: Uses q=name:{name} filter (and q=space_guid:{spaceGuid} if provided)
+v3: Uses names={name} filter (and space_guids={spaceGuid} if provided)
 </div>
 
 
@@ -1120,7 +1129,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line202">line 202</a>
+        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line220">line 220</a>
     </li></ul></dd>
 
 
@@ -1275,7 +1284,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line218">line 218</a>
+        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line236">line 236</a>
     </li></ul></dd>
 
 
@@ -1430,7 +1439,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line193">line 193</a>
+        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line211">line 211</a>
     </li></ul></dd>
 
 
@@ -1493,6 +1502,8 @@ <h4 class="name" id="start"><span class="type-signature"></span>start<span class
 
 <div class="description">
     Start an application.
+v2: PUT /v2/apps/:guid { state: "STARTED" }
+v3: POST /v3/apps/:guid/actions/start
 </div>
 
 
@@ -1585,7 +1596,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line182">line 182</a>
+        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line193">line 193</a>
     </li></ul></dd>
 
 
@@ -1648,6 +1659,8 @@ <h4 class="name" id="stop"><span class="type-signature"></span>stop<span class="
 
 <div class="description">
     Stop an application.
+v2: PUT /v2/apps/:guid { state: "STOPPED" }
+v3: POST /v3/apps/:guid/actions/stop
 </div>
 
 
@@ -1740,7 +1753,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line171">line 171</a>
+        <a href="model_cloudcontroller_AppsCore.js.html">model/cloudcontroller/AppsCore.js</a>, <a href="model_cloudcontroller_AppsCore.js.html#line173">line 173</a>
     </li></ul></dd>
 
 
@@ -1988,7 +2001,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Apps.html
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Thu Mar 05 2026 16:22:04 GMT+0700 (Indochina Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Thu Mar 05 2026 17:22:07 GMT+0700 (Indochina Time)
 </footer>
 
 <script> prettyPrint(); </script>