Merge pull request #353 from MindscapeHQ/develop

CHANGELOG.md

@@ -1,3 +1,23 @@
+## 2.1.1
+
+- docs: Some documentation improvements around online/offline behaviour. (#333) (2024-10-23)
+- chore(deps): bump cross-spawn from 7.0.3 to 7.0.6 in /examples/express-sample (#345) (2024-12-02)
+- chore(deps): bump debug from 4.3.7 to 4.4.0 (#346) (2025-01-06)
+- chore(deps): bump uuid from 10.0.0 to 11.0.2 (#338) (2024-11-01)
+- chore(deps): bump @types/express from 4.17.21 to 5.0.0 (#335) (2024-11-01)
+- chore(deps-dev): bump typescript from 5.6.3 to 5.7.2 (#349) (2025-01-06)
+- chore(deps-dev): bump typescript-eslint from 8.17.0 to 8.19.0 (#348) (2025-01-06)
+- chore(deps-dev): bump eslint from 9.16.0 to 9.17.0 (#350) (2025-01-06)
+- chore(deps-dev): bump eslint from 9.11.1 to 9.16.0 (#340) (2024-12-03)
+- chore(deps-dev): bump nock from 13.5.5 to 13.5.6 (#341) (2024-12-02)
+- chore(deps-dev): bump prettier from 3.3.3 to 3.4.1 (#342) (2024-12-02)
+- chore(deps-dev): bump @eslint/js from 9.13.0 to 9.16.0 (#343) (2024-12-02)
+- chore(deps-dev): bump @stylistic/eslint-plugin from 2.8.0 to 2.11.0 (#344) (2024-12-02)
+- chore(deps-dev): bump typescript-eslint from 8.3.0 to 8.12.2 (#339) (2024-11-01)
+- chore(deps-dev): bump @eslint/js from 9.11.1 to 9.13.0 (#337) (2024-11-01)
+- chore(deps-dev): bump typescript from 5.5.4 to 5.6.3 (#336) (2024-11-01)
+- chore: Updated package.json to deal with vuln in express dependency (#352) (2025-01-14)
+
 ## 2.1.0
 
 - chore(deps): bump cookie and express (#329) (2024-10-10)

README.md

@@ -95,7 +95,7 @@ Note that `IncomingMessage` can be `null` if the request was stored because the
 `IncomingMessage` is the response from the Raygun API - there's nothing in the body, it's just a status code response. If everything went ok, you'll get a 202 response code. 
 Otherwise, we return 401 for incorrect API keys, 403 if you're over your plan limits, or anything in the 500+ range for internal errors.
 
-We use the nodejs http/https library to make the POST to Raygun, you can see more documentation about that callback here: https://nodejs.org/api/http.html#http_http_request_options_callback .
+We use the nodejs `http`/`https` library to make the POST to Raygun, you can see more documentation about that callback here: https://nodejs.org/api/http.html#http_http_request_options_callback .
 
 You can `await` the call to obtain the result, or use `then/catch`.
 
@@ -444,9 +444,9 @@ const raygunClient = new Raygun.Client().init({
 
 ### Offline caching
 
-Raygun can cache errors thrown by your Node application when it's running in 'offline' mode. By default the offline cache is disabled. Raygun4Node doesn't detect network state change, that is up to the application using the library.
+Raygun can cache errors thrown by your Node application when it's running in 'offline' mode. By default the offline cache is disabled. Raygun4Node does not detect nor manage network state for you. It is up to the application using the library's functionality to manage online/offline state changes. 
 
-Raygun includes an on-disk cache provider out of the box, which required write permissions to the folder you wish to use. You cal also pass in your own cache storage.
+Raygun includes an on-disk cache provider out of the box, which requires write permissions to the folder you wish to use. You can also pass in your own cache storage. The default, on-disk cache provider will store crash reports as individual `.json` files in the specified directory.
 
 ##### Getting setup with the default offline provide
 
@@ -455,17 +455,19 @@ When creating your Raygun client you need to pass through a cache path
 ```javascript
 const raygunClient = new raygun.Client().init({
   apiKey: 'YOUR_API_KEY',
-  isOffline: false,
+  isOffline: true,
   offlineStorageOptions: {
     cachePath: 'raygunCache/',
     cacheLimit: 1000 // defaults to 100 errors if you don't set this
   }
 });
 ```
 
+Setting `isOffline: true` tells the provider to start in `offline` mode. It will also trigger the initialisation of the cache, respectively - if the cache directory already exists - it will connect to the cache as specified in `offlineStorageOptions`.
+
 ##### Changing online/offline state
 
-The Raygun client allows you to set it's online state when your application is running.
+The Raygun client allows you to set its online state when your application is running.
 
 *To mark as offline*
 
@@ -475,7 +477,9 @@ The Raygun client allows you to set it's online state when your application is r
 
     raygunClient.online();
 
-When marking as online any cached errors will be forwarded to Raygun.
+When marking as online any cached errors from the currently configured cache provider will be forwarded to Raygun. This action will respect whatever transport mode (batched or individual HTTP requests) you have currently configured. 
+
+If you change between different cache providers or change the storage directory of the on-disk cache provider, please make sure to trigger processing the offline reports before making such a change.
 
 ##### Custom cache provider
 
@@ -505,7 +509,7 @@ const raygunClient = new raygun.Client().init({
 
 See [lib/raygun.offline.ts](lib/raygun.offline.ts) for an example.
 
-We recommend that you limit the number of errors that you are caching so that you don't swamp the clients internet connection sending errors.
+We recommend that you limit the number of errors that you are caching so that you don't swamp the client's internet connection sending errors.
 
 ### Custom error grouping
 
@@ -621,7 +625,7 @@ View a screencast on creating an app with Node.js and Express.js, then hooking u
 You can enable logging of debug information from the Raygun client by setting the environment variable `DEBUG=raygun`. The client will then log information about transporting and storing errors, including timing information.
 
 ## Contributing
-In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using "npm test".
+In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using `npm run test`, `npm run eslint`, `npm run tseslint` and `npm run prettier`.
 
 ## Release History
 

examples/express-sample/package.json

@@ -11,7 +11,7 @@
     "cookie-parser": "~1.4.7",
     "debug": "^4.3.4",
     "ejs": "~3.1.10",
-    "express": "^4.19.2",
+    "express": "^4.21.2",
     "morgan": "^1.10.0",
     "node-sass-middleware": "^1.1.0",
     "raygun": "file:../..",