rpc-express-toolkit 4.2.0 → 4.3.2

package/README.md

@@ -42,9 +42,61 @@ app.listen(3000);
 ### Client
 
 ```javascript
-const { RpcClient } = require('rpc-express-toolkit');
+const { RpcClient, RpcSafeClient } = require('rpc-express-toolkit');
+
 const client = new RpcClient('http://localhost:3000/api');
 const sum = await client.call('add', { a: 1, b: 2 });
+
+const safeClient = new RpcSafeClient('http://localhost:3000/api');
+await safeClient.notify('add', { a: 0, b: 0 });
+```
+
+`RpcClient` and `RpcSafeClient` are re-exported from the shared `rpc-toolkit-js-client` package, so existing Node.js imports from `rpc-express-toolkit` continue to work.
+
+### Browser Client Assets
+
+Serve the shared browser client bundles from the endpoint:
+
+```javascript
+const { RpcEndpoint } = require('rpc-express-toolkit');
+
+RpcEndpoint.serveScripts(app);
+```
+
+Default paths:
+
+```text
+/vendor/rpc-client/rpc-client.js
+/vendor/rpc-client/rpc-client.min.js
+/vendor/rpc-client/rpc-client.mjs
+/vendor/rpc-client/rpc-client.min.mjs
+```
+
+Classic browser script:
+
+```html
+<script src="/vendor/rpc-client/rpc-client.min.js"></script>
+<script>
+  const client = new RpcToolkitClient.RpcClient('/api');
+  const safeClient = new RpcToolkitClient.RpcSafeClient('/api');
+
+  client.call('add', { a: 1, b: 2 }).then(console.log);
+  safeClient.notify('add', { a: 0, b: 0 });
+</script>
+```
+
+Module script:
+
+```html
+<script type="module">
+  import { RpcClient, RpcSafeClient } from '/vendor/rpc-client/rpc-client.mjs';
+
+  const client = new RpcClient('/api');
+  const safeClient = new RpcSafeClient('/api');
+
+  console.log(await client.call('add', { a: 1, b: 2 }));
+  await safeClient.notify('add', { a: 0, b: 0 });
+</script>
 ```
 
 ### Safe Type Disambiguation (optional)
@@ -60,6 +112,31 @@ Safe type disambiguation is disabled by default for maximum JSON-RPC 2.0 compati
 - `client.batch([...])`: batch.
 - `client.notify(method, params?)`: notification.
 
+## Authentication And Method Restrictions
+
+Authentication is supported through the built-in `auth` middleware. The `auth` option is a function that receives the Express request. Returning a truthy value allows the RPC call; returning a falsy value rejects it with JSON-RPC error `-32001` and message `Authentication required`. Throwing also rejects the call and returns a JSON-RPC error based on the thrown error.
+
+```js
+const rpc = new RpcEndpoint(app, context, {
+  auth: async (req) => {
+    const token = req.headers.authorization;
+    return token === 'Bearer secret-token';
+  },
+});
+
+rpc.addMethod('ping', () => 'pong');
+```
+
+For simple method-level restriction, use `methodWhitelist`:
+
+```js
+const rpc = new RpcEndpoint(app, context, {
+  methodWhitelist: ['ping', 'status.read'],
+});
+```
+
+Calls to methods outside the whitelist are rejected. This is a basic method restriction mechanism, not a complete role or permission system. Project-specific authorization rules can be implemented with middleware hooks such as `beforeCall`; see `README_ADVANCED.md`.
+
 ### Safe Import (opt-in)
 
 [![npm (proxy)](https://img.shields.io/npm/v/rpc-express-toolkit-safe.svg)](https://www.npmjs.com/package/rpc-express-toolkit-safe)
@@ -70,16 +147,16 @@ When you control both client and server and want safer type round-trips, import
 ```js
 // Server (safe preset)
 const express = require('express');
-const { createSafeEndpoint } = require('rpc-express-toolkit/safe');
+const { RpcSafeEndpoint } = require('rpc-express-toolkit/safe');
 
 const app = express();
 app.use(express.json());
 
-const rpc = createSafeEndpoint(app, {}, { endpoint: '/api' /* strictMode: true by default */ });
+const rpc = new RpcSafeEndpoint(app, {}, { endpoint: '/api' /* strictMode: true by default */ });
 
 // Client (safe preset)
-const { createSafeClient } = require('rpc-express-toolkit/safe');
-const client = createSafeClient('http://localhost:3000/api');
+const { RpcSafeClient } = require('rpc-express-toolkit/safe');
+const client = new RpcSafeClient('http://localhost:3000/api');
 ```
 
 This keeps JSON-RPC 2.0 compliance as default for the main entrypoint, while offering a convenient safe-mode import for projects that prefer explicit type disambiguation.
@@ -95,20 +172,69 @@ npm install rpc-express-toolkit-safe
 ```js
 // Server
 const express = require('express');
-const { createSafeEndpoint } = require('rpc-express-toolkit-safe');
+const { RpcSafeEndpoint } = require('rpc-express-toolkit-safe');
 const app = express();
 app.use(express.json());
-const rpc = createSafeEndpoint(app, {}, { endpoint: '/api' });
+const rpc = new RpcSafeEndpoint(app, {}, { endpoint: '/api' });
 
 // Client
-const { createSafeClient } = require('rpc-express-toolkit-safe');
-const client = createSafeClient('http://localhost:3000/api');
+const { RpcSafeClient } = require('rpc-express-toolkit-safe');
+const client = new RpcSafeClient('http://localhost:3000/api');
+```
+
+## Introspection Methods
+
+Enable introspection to expose metadata about registered methods via reserved `__rpc.*` methods:
+
+```javascript
+const rpc = new RpcEndpoint(app, context, {
+  enableIntrospection: true  // Enable __rpc.* methods
+});
+
+// Register methods with public schemas
+rpc.addMethod('add', async (req, ctx, params) => {
+  return params.a + params.b;
+}, {
+  schema: {
+    type: 'object',
+    properties: {
+      a: { type: 'number' },
+      b: { type: 'number' }
+    },
+    required: ['a', 'b']
+  },
+  exposeSchema: true,        // Make schema publicly queryable
+  description: 'Add two numbers'
+});
+
+// Available introspection methods:
+// __rpc.listMethods() → ["add", "multiply", ...]
+// __rpc.describe({method: "add"}) → {name, schema, description}
+// __rpc.describeAll() → [{name, schema, description}, ...]
+// __rpc.version() → {toolkit, version, expressVersion, nodeVersion}
+// __rpc.capabilities() → {safeMode, batch, introspection, ...}
+
+// Client usage
+const methods = await client.call('__rpc.listMethods');
+const addInfo = await client.call('__rpc.describe', { method: 'add' });
 ```
 
+In `__rpc.capabilities`, `auth` is a boolean indicating whether authentication middleware is configured. It does not expose roles, scopes, or permission rules.
+
+**Note:** The introspection prefix is configurable via `introspectionPrefix` option (default: `__rpc`). User methods starting with this prefix are rejected to prevent conflicts.
+
 ## Full Details
 
 For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.
 
+## 🔗 Related Projects
+
+- [rpc-php-toolkit](https://github.com/n-car/rpc-php-toolkit) - PHP implementation
+- [rpc-dotnet-toolkit](https://github.com/n-car/rpc-dotnet-toolkit) - .NET implementation
+- [rpc-arduino-toolkit](https://github.com/n-car/rpc-arduino-toolkit) - Arduino/ESP32 implementation
+- [rpc-java-toolkit](https://github.com/n-car/rpc-java-toolkit) - Java & Android implementation
+- [node-red-contrib-rpc-toolkit](https://github.com/n-car/node-red-contrib-rpc-toolkit) - Node-RED visual programming
+
 ## Contributing
 
 ```bash

package/examples/introspection/client.js

@@ -0,0 +1,68 @@
+/**
+ * Introspection Example - Client
+ * Demonstrates how to use __rpc.* introspection methods
+ */
+
+const { RpcClient } = require('../..');
+
+async function main() {
+  const client = new RpcClient('http://localhost:3000/api');
+
+  console.log('=== RPC Introspection Demo ===\n');
+
+  // 1. List all methods
+  console.log('1. __rpc.listMethods():');
+  const methods = await client.call('__rpc.listMethods');
+  console.log('  Available methods:', methods);
+  console.log('');
+
+  // 2. Get version info
+  console.log('2. __rpc.version():');
+  const version = await client.call('__rpc.version');
+  console.log('  Toolkit:', version.toolkit);
+  console.log('  Version:', version.version);
+  console.log('  Express:', version.expressVersion);
+  console.log('  Node:', version.nodeVersion);
+  console.log('');
+
+  // 3. Get server capabilities
+  console.log('3. __rpc.capabilities():');
+  const caps = await client.call('__rpc.capabilities');
+  console.log('  Safe Mode:', caps.safeMode);
+  console.log('  Batch Support:', caps.batch);
+  console.log('  Introspection:', caps.introspection);
+  console.log('  Method Count:', caps.methodCount);
+  console.log('');
+
+  // 4. Describe a specific method
+  console.log('4. __rpc.describe({ method: "add" }):');
+  const addInfo = await client.call('__rpc.describe', { method: 'add' });
+  console.log('  Name:', addInfo.name);
+  console.log('  Description:', addInfo.description);
+  console.log('  Schema:', JSON.stringify(addInfo.schema, null, 2));
+  console.log('');
+
+  // 5. Describe all public methods
+  console.log('5. __rpc.describeAll():');
+  const allMethods = await client.call('__rpc.describeAll');
+  allMethods.forEach((method) => {
+    console.log(`  - ${method.name}: ${method.description}`);
+  });
+  console.log('');
+
+  // 6. Try to describe a private method (should fail)
+  console.log('6. Try to describe private method:');
+  try {
+    await client.call('__rpc.describe', { method: 'internalCalculation' });
+  } catch (error) {
+    console.log('  Error:', error.message);
+  }
+  console.log('');
+
+  // 7. Test a public method
+  console.log('7. Call add method:');
+  const sum = await client.call('add', { a: 5, b: 3 });
+  console.log('  5 + 3 =', sum);
+}
+
+main().catch(console.error);

package/examples/introspection/server.js

@@ -0,0 +1,89 @@
+/**
+ * Introspection Example - Server
+ * Demonstrates how to enable and use __rpc.* introspection methods
+ */
+
+const express = require('express');
+const { RpcEndpoint } = require('../..');
+
+const app = express();
+app.use(express.json());
+
+// Context for methods
+const context = {
+  database: 'mock-db',
+  config: { maxValue: 1000 },
+};
+
+// Create endpoint with introspection enabled
+const rpc = new RpcEndpoint(app, context, {
+  endpoint: '/api',
+  enableIntrospection: true, // Enable __rpc.* methods
+  introspectionPrefix: '__rpc', // Optional: customize prefix (default: __rpc)
+});
+
+// Public method with exposed schema
+rpc.addMethod('add', async (req, ctx, params) => params.a + params.b, {
+  schema: {
+    type: 'object',
+    properties: {
+      a: { type: 'number' },
+      b: { type: 'number' },
+    },
+    required: ['a', 'b'],
+  },
+  exposeSchema: true,
+  description: 'Add two numbers and return the sum',
+});
+
+// Public method with exposed schema
+rpc.addMethod('multiply', async (req, ctx, params) => params.a * params.b, {
+  schema: {
+    type: 'object',
+    properties: {
+      a: { type: 'number' },
+      b: { type: 'number' },
+    },
+    required: ['a', 'b'],
+  },
+  exposeSchema: true,
+  description: 'Multiply two numbers',
+});
+
+// Private method (schema not exposed)
+rpc.addMethod(
+  'internalCalculation',
+  async (req, ctx, params) => params.value * 2 + 42,
+  {
+    schema: {
+      type: 'object',
+      properties: {
+        value: { type: 'number' },
+      },
+      required: ['value'],
+    },
+    exposeSchema: false, // Schema is private
+    description: 'Internal calculation (not exposed)',
+  }
+);
+
+// Public method without schema
+rpc.addMethod('echo', async (req, ctx, params) => params, {
+  exposeSchema: true,
+  description: 'Echo back the parameters',
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(
+    `RPC Server with introspection running on http://localhost:${PORT}/api`
+  );
+  console.log('\nAvailable introspection methods:');
+  console.log('- __rpc.listMethods()');
+  console.log('- __rpc.describe({method: "add"})');
+  console.log('- __rpc.describeAll()');
+  console.log('- __rpc.version()');
+  console.log('- __rpc.capabilities()');
+  console.log('\nTry: node client.js');
+});

package/package.json

@@ -1,126 +1,124 @@
-{
-    "name":  "rpc-express-toolkit",
-    "version":  "4.2.0",
-    "description":  "Enterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, structured logging, middleware system, schema validation, comprehensive BigInt/Date support. JSON middleware validation and explicit configuration.",
-    "main":  "src/index.js",
-    "types":  "src/index.d.ts",
-    "exports":  {
-                    ".":  {
-                              "types":  "./src/index.d.ts",
-                              "require":  "./src/index.js",
-                              "import":  "./src/index.js"
-                          },
-                    "./safe":  {
-                                   "types":  "./src/safe.d.ts",
-                                   "require":  "./src/safe.js",
-                                   "import":  "./src/safe.js"
-                               }
-                },
-    "files":  [
-                  "src/",
-                  "examples/",
-                  "README.md",
-                  "LICENSE"
-              ],
-    "scripts":  {
-                    "test":  "jest",
-                    "test:coverage":  "jest --coverage",
-                    "test:watch":  "jest --watch",
-                    "lint":  "eslint src/ examples/",
-                    "lint:fix":  "eslint src/ examples/ --fix",
-                    "clean":  "node -e \"require(\u0027fs\u0027).existsSync(\u0027dist\u0027) \u0026\u0026 require(\u0027fs\u0027).rmSync(\u0027dist\u0027, {recursive: true})\"",
-                    "build":  "npm run build:minify",
-                    "build:minify":  "npm run build:js \u0026\u0026 npm run build:mjs",
-                    "build:js":  "terser src/clients/rpc-client.js -o src/clients/rpc-client.min.js --compress --mangle --comments false --ecma 2020",
-                    "build:mjs":  "terser src/clients/rpc-client.mjs -o src/clients/rpc-client.min.mjs --compress --mangle --comments false --module --ecma 2020",
-                    "prepublishOnly":  "npm run build",
-                    "precommit":  "npm run lint \u0026\u0026 npm test"
-                },
-    "repository":  {
-                       "type":  "git",
-                       "url":  "git+https://github.com/n-car/rpc-express-toolkit.git"
-                   },
-    "keywords":  [
-                     "json-rpc",
-                     "jsonrpc",
-                     "json-rpc-2.0",
-                     "express",
-                     "toolkit",
-                     "rpc",
-                     "server",
-                     "client",
-                     "middleware",
-                     "validation",
-                     "schema",
-                     "ajv",
-                     "bigint",
-                     "date",
-                     "enterprise",
-                     "nodejs",
-                     "node",
-                     "browser",
-                     "ssl",
-                     "self-signed",
-                     "secure",
-                     "fetch",
-                     "batch",
-                     "typescript",
-                     "logging",
-                     "cors",
-                     "rate-limit",
-                     "authentication"
-                 ],
-    "author":  "Nicola Carpanese \u003cnicola.carpanese@gmail.com\u003e",
-    "license":  "MIT",
-    "bugs":  {
-                 "url":  "https://github.com/n-car/rpc-express-toolkit/issues"
-             },
-    "homepage":  "https://github.com/n-car/rpc-express-toolkit#readme",
-    "engines":  {
-                    "node":  "\u003e=18.0.0"
-                },
-    "devDependencies":  {
-                            "eslint":  "^8.57.1",
-                            "eslint-config-airbnb-base":  "^15.0.0",
-                            "eslint-config-prettier":  "^9.1.2",
-                            "eslint-plugin-import":  "^2.31.0",
-                            "eslint-plugin-prettier":  "^5.5.3",
-                            "husky":  "^8.0.0",
-                            "jest":  "^29.7.0",
-                            "lint-staged":  "^13.0.0",
-                            "prettier":  "^3.6.2",
-                            "supertest":  "^6.3.3",
-                            "terser":  "^5.43.1"
-                        },
-    "dependencies":  {
-                         "ajv":  "^8.12.0",
-                         "ajv-formats":  "^2.1.1",
-                         "express":  "^4.21.2",
-                         "nested-error-stacks":  "^2.1.1"
-                     },
-    "optionalDependencies":  {
-                                 "node-fetch":  "^2.7.0"
-                             },
-    "contributors":  [
-                         {
-                             "name":  "Nicola Carpanese",
-                             "email":  "nicola.carpanese@gmail.com",
-                             "url":  "https://github.com/n-car"
-                         }
-                     ],
-    "husky":  {
-                  "hooks":  {
-                                "pre-commit":  "lint-staged"
-                            }
-              },
-    "lint-staged":  {
-                        "src/**/*.js":  [
-                                            "eslint --fix",
-                                            "prettier --write"
-                                        ],
-                        "examples/**/*.js":  [
-                                                 "eslint --fix",
-                                                 "prettier --write"
-                                             ]
-                    }
-}
+{
+    "name":  "rpc-express-toolkit",
+    "version":  "4.3.2",
+    "description":  "Enterprise-ready JSON-RPC 2.0 toolkit for Express.js with simplified APIs, structured logging, middleware system, schema validation, comprehensive BigInt/Date support. JSON middleware validation and explicit configuration.",
+    "main":  "src/index.js",
+    "types":  "src/index.d.ts",
+    "exports":  {
+                    ".":  {
+                              "types":  "./src/index.d.ts",
+                              "require":  "./src/index.js",
+                              "import":  "./src/index.js"
+                          },
+                    "./safe":  {
+                                   "types":  "./src/safe.d.ts",
+                                   "require":  "./src/safe.js",
+                                   "import":  "./src/safe.js"
+                               }
+                },
+    "files":  [
+                  "src/",
+                  "examples/",
+                  "README.md",
+                  "LICENSE"
+              ],
+    "scripts":  {
+                    "test":  "jest",
+                    "test:coverage":  "jest --coverage",
+                    "test:watch":  "jest --watch",
+                    "lint":  "eslint src/ examples/",
+                    "lint:fix":  "eslint src/ examples/ --fix",
+                    "clean":  "node -e \"require(\u0027fs\u0027).existsSync(\u0027dist\u0027) \u0026\u0026 require(\u0027fs\u0027).rmSync(\u0027dist\u0027, {recursive: true})\"",
+                    "build":  "node -e \"require.resolve(\u0027rpc-toolkit-js-client\u0027)\"",
+                    "prepublishOnly":  "npm run build",
+                    "precommit":  "npm run lint \u0026\u0026 npm test"
+                },
+    "repository":  {
+                       "type":  "git",
+                       "url":  "git+https://github.com/n-car/rpc-express-toolkit.git"
+                   },
+    "keywords":  [
+                     "json-rpc",
+                     "jsonrpc",
+                     "json-rpc-2.0",
+                     "express",
+                     "toolkit",
+                     "rpc",
+                     "server",
+                     "client",
+                     "middleware",
+                     "validation",
+                     "schema",
+                     "ajv",
+                     "bigint",
+                     "date",
+                     "enterprise",
+                     "nodejs",
+                     "node",
+                     "browser",
+                     "ssl",
+                     "self-signed",
+                     "secure",
+                     "fetch",
+                     "batch",
+                     "typescript",
+                     "logging",
+                     "cors",
+                     "rate-limit",
+                     "authentication"
+                 ],
+    "author":  "Nicola Carpanese \u003cnicola.carpanese@gmail.com\u003e",
+    "license":  "MIT",
+    "bugs":  {
+                 "url":  "https://github.com/n-car/rpc-express-toolkit/issues"
+             },
+    "homepage":  "https://github.com/n-car/rpc-express-toolkit#readme",
+    "engines":  {
+                    "node":  "\u003e=18.0.0"
+                },
+    "devDependencies":  {
+                            "eslint":  "^8.57.1",
+                            "eslint-config-airbnb-base":  "^15.0.0",
+                            "eslint-config-prettier":  "^9.1.2",
+                            "eslint-plugin-import":  "^2.31.0",
+                            "eslint-plugin-prettier":  "^5.5.3",
+                            "husky":  "^8.0.0",
+                            "jest":  "^29.7.0",
+                            "lint-staged":  "^13.0.0",
+                            "prettier":  "^3.6.2",
+                            "supertest":  "^6.3.3",
+                            "terser":  "^5.43.1"
+                        },
+    "dependencies":  {
+                         "ajv":  "^8.12.0",
+                         "ajv-formats":  "^2.1.1",
+                         "express":  "^4.21.2",
+                         "nested-error-stacks":  "^2.1.1",
+                         "rpc-toolkit-js-client":  "https://github.com/n-car/rpc-toolkit-js-client/archive/refs/tags/v1.1.0.tar.gz"
+                     },
+    "optionalDependencies":  {
+                                 "node-fetch":  "^2.7.0"
+                             },
+    "contributors":  [
+                         {
+                             "name":  "Nicola Carpanese",
+                             "email":  "nicola.carpanese@gmail.com",
+                             "url":  "https://github.com/n-car"
+                         }
+                     ],
+    "husky":  {
+                  "hooks":  {
+                                "pre-commit":  "lint-staged"
+                            }
+              },
+    "lint-staged":  {
+                        "src/**/*.js":  [
+                                            "eslint --fix",
+                                            "prettier --write"
+                                        ],
+                        "examples/**/*.js":  [
+                                                 "eslint --fix",
+                                                 "prettier --write"
+                                             ]
+                    }
+}