rpc-express-toolkit 4.2.1 → 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,14 +172,14 @@ 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
@@ -142,6 +219,8 @@ 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

package/examples/introspection/client.js

@@ -1,68 +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);
+/**
+ * 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

@@ -1,89 +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');
-});
+/**
+ * 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');
+});