@zudojs/rpc 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,12 @@
 # @zudojs/rpc
 
-Type-safe RPC — define procedures, apply middleware, dispatch calls, and serve over HTTP or your own transport.
+Type-safe RPC — define procedures, apply middleware, dispatch calls, and serve them over your own transport.
+
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-rpc](https://zudojs.oyinlola.site/docs/packages-rpc) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-rpc.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
 
 ## When to use
 
@@ -8,9 +14,14 @@ Import this when you need:
 
 - a typed RPC layer between services (gateway ↔ microservice, frontend ↔ backend)
 - procedure-level middleware (auth, tracing, rate limit)
-- a dispatcher that picks the right transport
+- a server that validates frames and maps every failure to a wire code
 - structured RPC errors
 
+The package is transport-agnostic: `RPCServer.handle` takes a request frame
+and returns a response frame, and `RPCClient` sends through any object
+implementing `RPCTransport`. It ships no HTTP or WebSocket transport of its
+own.
+
 For request/response inside one process, prefer `@zudojs/api`.
 
 ## Installation
@@ -24,8 +35,11 @@ npm install @zudojs/rpc
 ```typescript
 import {
   createRPCProcedure,
-  RPCDispatcher,
+  createRPCRequest,
   RPCServer,
+  RPCClient,
+  RPCDispatcher,
+  RPCProcedureRegistry,
   RPCMiddlewareStack,
   createRPCContext,
   type RPCContext,
@@ -33,24 +47,121 @@ import {
   type RPCProcedure,
   type RPCRequest,
   type RPCResponse,
+  type RPCTransport,
   type RPCErrorOptions,
 } from "@zudojs/rpc";
 ```
 
 ## Usage
 
+A procedure is `createRPCProcedure(name, handler, options?)`. Names are
+dot-separated identifiers (`"math.sum"`); the handler is positional,
+`(input, context)`; `options.input` / `options.output` are `@zudojs/schema`
+schemas (anything with `safeParse`) the payload and result are checked
+against.
+
 ```typescript
-import { createRPCProcedure, RPCDispatcher } from "@zudojs/rpc";
+import { createRPCProcedure, createRPCRequest, RPCServer } from "@zudojs/rpc";
+import { schema } from "@zudojs/schema";
 
-const sum = createRPCProcedure({
-  name: "sum",
-  input: { a: "number", b: "number" },
-  handler: ({ input }) => input.a + input.b,
-});
+const sum = createRPCProcedure(
+  "math.sum",
+  async (input: { a: number; b: number }) => input.a + input.b,
+  { input: schema.object({ a: schema.number(), b: schema.number() }) },
+);
+
+const server = new RPCServer();
+server.register(sum);
+
+const response = await server.handle(
+  createRPCRequest({ id: "req-1", procedure: "math.sum", payload: { a: 1, b: 2 } }),
+);
+// { id: "req-1", success: true, result: 3 }
+```
+
+`handle` never throws for a bad request: a malformed frame, an unknown
+procedure, a payload the input schema rejects, a timeout or a handler error
+each come back as `{ success: false, error: { code, message, details? } }`.
+The frame's `metadata` is optional.
+
+### Calling through a transport
+
+`RPCClient` needs an `RPCTransport` — an object whose `send(request, options)`
+delivers the frame and resolves with the response. `options.signal` aborts the
+call and `options.timeout` is the deadline in milliseconds, so a transport can
+set its own socket timeout. The in-process transport below is the smallest
+possible one:
+
+```typescript
+import { RPCClient, type RPCTransport } from "@zudojs/rpc";
+
+const transport: RPCTransport = { send: (request) => server.handle(request) };
+const client = new RPCClient(transport, { timeout: 5_000 });
 
-const dispatcher = new RPCDispatcher();
-dispatcher.register(sum);
-const result = await dispatcher.call("sum", { a: 1, b: 2 });
+const total = await client.call<{ a: number; b: number }, number>("math.sum", { a: 1, b: 2 });
+// 3
+```
+
+A failed call rejects with a typed error rebuilt from the wire code
+(`RPCTimeoutError`, `RPCCancelledError`, `RPCUnavailableError`, or an
+`RPCError` carrying the server's `code` and `details`).
+
+### Middleware and trusted identity
+
+Everything in a frame, `metadata` included, is written by the caller: any
+client can send `metadata: { userId: "admin" }`. Never authorise on it.
+Identity your transport has verified (a checked bearer token, an mTLS peer,
+a server-side session) goes in the second argument of `handle`, and reaches
+middleware and handlers as the frozen `context.auth`:
+
+```typescript
+import { RPCMiddlewareStack, RPCAuthenticationError } from "@zudojs/rpc";
+
+const stack = new RPCMiddlewareStack([
+  async (context, next) => {
+    if (typeof context.auth?.userId !== "string") {
+      throw new RPCAuthenticationError("Sign in first.");
+    }
+    context.set("actor", context.auth.userId);
+    return next();
+  },
+]);
+
+const server = new RPCServer(undefined, stack);
+
+// In the transport, after verifying the caller's credentials yourself:
+await server.handle(frame, { auth: { userId: verifiedUserId } });
+```
+
+Each middleware may call `next()` once. Input validation runs before the
+stack. `context.input` holds the payload as the procedure's schema parsed
+it (unknown keys stripped, defaults applied, values coerced), so authorise
+on `context.input`, not on `context.request.payload`, which stays the raw
+frame value.
+
+## Errors
+
+Every error class from `@zudojs/errors`' RPC family is re-exported. The
+server maps them to wire codes (`RPC_PROCEDURE_NOT_FOUND`,
+`RPC_VALIDATION_ERROR`, `RPC_UNAUTHENTICATED`, `RPC_FORBIDDEN`,
+`RPC_RATE_LIMITED`, `RPC_TIMEOUT`, …). A custom `RPCError` subclass keeps its
+own `code`.
+
+What reaches the caller follows the error's `expose` flag. Anything thrown
+with `expose: false` — an `RPCInternalError`, an `RPCSerializationError`, a
+plain `new RPCError(...)` (whose default is `expose: false`), or any
+non-RPC error — is answered with the fixed `INTERNAL_ERROR_MESSAGE`; the
+original error is handed to `onInternalError(error, requestId)` so it can be
+logged against the request id. A handler result that fails the procedure's
+`output` schema is treated the same way: it is the server's fault, not the
+caller's.
+
+```typescript
+const server = new RPCServer(undefined, undefined, {
+  limits: { maxPayloadBytes: 256 * 1024 },
+  dispatch: { defaultTimeout: 10_000 },
+  onInternalError: (error, requestId) => logger.error({ requestId, error }),
+});
 ```
 
 ## License

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { RPCError, RPCProcedureNotFoundError, RPCInvalidRequestError, RPCValidat
 export type { RPCHandler, RPCProcedure, RPCProcedureOptions, } from "./rpc/procedure/index.js";
 export { createRPCProcedure } from "./rpc/procedure/index.js";
 export { RPCProcedureRegistry, RPCProcedureRouter, } from "./rpc/procedure/index.js";
-export type { RPCContext } from "./rpc/context/index.js";
+export type { RPCAuthContext, RPCContext, RPCContextOptions, } from "./rpc/context/index.js";
 export { createRPCContext } from "./rpc/context/index.js";
 export type { RPCMiddleware } from "./rpc/middleware/index.js";
 export { RPCMiddlewareStack } from "./rpc/middleware/index.js";

package/dist/rpc/client/rpcClient.core.js

@@ -64,8 +64,14 @@ export class RPCClient {
                 payload: input,
                 metadata: options.metadata,
             });
+            // The transport is told the deadline as well as given the signal:
+            // `RPCTransportRequestOptions.timeout` exists so a transport can set
+            // its own socket or request timeout, and it was never populated.
             const races = [
-                this.transport.send(request, { signal: controller.signal }),
+                this.transport.send(request, {
+                    signal: controller.signal,
+                    ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
+                }),
                 this.abortPromise(controller.signal, procedure),
             ];
             if (timeout) {
@@ -170,8 +176,19 @@ export class RPCClient {
         const message = response.error?.message ?? "RPC call failed.";
         const code = response.error?.code;
         switch (code) {
-            case "RPC_TIMEOUT":
-                return new RPCTimeoutError(0, procedure);
+            case "RPC_TIMEOUT": {
+                // The constructor derives its message from a duration the wire
+                // does not carry; keep the type and restore the server's message
+                // rather than reporting "timed out after 0ms".
+                const timeout = new RPCTimeoutError(0, procedure);
+                Object.defineProperty(timeout, "message", {
+                    value: message,
+                    enumerable: false,
+                    configurable: true,
+                    writable: true,
+                });
+                return timeout;
+            }
             case "RPC_CANCELLED":
                 return new RPCCancelledError(message, procedure);
             case "RPC_UNAVAILABLE":

package/dist/rpc/context/index.d.ts

@@ -1,3 +1,7 @@
-export type { RPCContext } from "./rpcContext.type.js";
+/**
+ * RPC execution context: per-call state, the caller's (untrusted) frame
+ * metadata, the transport's trusted `auth`, and the validated `input`.
+ */
+export type { RPCAuthContext, RPCContext, RPCContextOptions, } from "./rpcContext.type.js";
 export { createRPCContext } from "./rpcContext.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rpc/context/index.js

@@ -1,2 +1,6 @@
+/**
+ * RPC execution context: per-call state, the caller's (untrusted) frame
+ * metadata, the transport's trusted `auth`, and the validated `input`.
+ */
 export { createRPCContext } from "./rpcContext.type.js";
 //# sourceMappingURL=index.js.map

package/dist/rpc/context/rpcContext.type.d.ts

@@ -1,18 +1,57 @@
 import type { RPCMetadata } from "../types/rpcMetadata.type.js";
 import type { RPCRequest } from "../types/rpcRequest.type.js";
+/**
+ * Identity and other facts established by the transport (a verified
+ * bearer token, an mTLS peer, a session looked up server-side).
+ *
+ * Unlike frame `metadata`, which the caller writes, this is supplied by
+ * the server's own code through `RPCServer.handle(request, { auth })`, so
+ * it is the only context field safe to authorise on.
+ */
+export type RPCAuthContext = Readonly<Record<string, unknown>>;
+/**
+ * Extra, server-supplied values for {@link createRPCContext}.
+ */
+export interface RPCContextOptions {
+    /** Trusted, transport-derived identity. See {@link RPCAuthContext}. */
+    readonly auth?: RPCAuthContext;
+}
 /**
  * Context passed through the RPC execution pipeline.
  */
 export interface RPCContext {
     readonly request: RPCRequest;
+    /**
+     * Frame metadata exactly as the caller sent it. Untrusted: any client
+     * can set `userId`, `tenantId` or any other key. Authorise on
+     * {@link RPCContext.auth} instead.
+     */
     readonly metadata: RPCMetadata;
+    /**
+     * Trusted identity supplied by the transport through
+     * `RPCServer.handle(request, { auth })`; `undefined` when none was given.
+     */
+    readonly auth: RPCAuthContext | undefined;
+    /**
+     * The payload after the procedure's input schema has parsed it
+     * (stripped, defaulted, coerced), or the raw payload when the procedure
+     * declares no input schema. `undefined` until validation has run, i.e.
+     * in an interceptor before it calls `next()`. `request.payload` always
+     * stays the raw, unvalidated value.
+     */
+    readonly input: unknown;
     readonly signal: AbortSignal;
     readonly state: Map<string, unknown>;
     get<T>(key: string): T | undefined;
     set<T>(key: string, value: T): void;
 }
+/**
+ * Records the validated input on a context. Called by the dispatcher
+ * once, after input validation and before the middleware stack runs.
+ */
+export declare function bindRPCContextInput(context: RPCContext, input: unknown): void;
 /**
  * Creates a new RPC context.
  */
-export declare function createRPCContext(request: RPCRequest, signal: AbortSignal): RPCContext;
+export declare function createRPCContext(request: RPCRequest, signal: AbortSignal, options?: RPCContextOptions): RPCContext;
 //# sourceMappingURL=rpcContext.type.d.ts.map

package/dist/rpc/context/rpcContext.type.js

@@ -1,11 +1,26 @@
+const inputs = new WeakMap();
+/**
+ * Records the validated input on a context. Called by the dispatcher
+ * once, after input validation and before the middleware stack runs.
+ */
+export function bindRPCContextInput(context, input) {
+    inputs.set(context, input);
+}
 /**
  * Creates a new RPC context.
  */
-export function createRPCContext(request, signal) {
+export function createRPCContext(request, signal, options = {}) {
     const state = new Map();
+    const auth = options.auth === undefined ? undefined : Object.freeze({ ...options.auth });
     const context = {
         request,
-        metadata: request.metadata,
+        // A frame decoded from JSON may omit `metadata`; middleware reads
+        // `context.metadata.userId` and the like without guarding.
+        metadata: request.metadata ?? {},
+        auth,
+        get input() {
+            return inputs.get(context);
+        },
         signal,
         state,
         get(key) {

package/dist/rpc/dispatcher/rpcDispatcher.core.d.ts

@@ -3,6 +3,7 @@ import type { RPCResponse } from "../types/rpcResponse.type.js";
 import type { RPCProcedure } from "../procedure/rpcProcedure.type.js";
 import type { RPCMiddlewareStack } from "../middleware/rpcMiddleware.core.js";
 import type { RPCInterceptor } from "../interceptor/rpcInterceptor.type.js";
+import type { RPCContextOptions } from "../context/rpcContext.type.js";
 /**
  * Options controlling dispatch.
  */
@@ -46,8 +47,12 @@ export declare class RPCDispatcher {
     }, middleware: RPCMiddlewareStack, options?: RPCDispatcherOptions);
     /**
      * Dispatches an RPC request.
+     *
+     * `trusted` carries server-supplied context (`auth`) that the caller
+     * cannot forge; it is exposed to middleware and handlers as
+     * `context.auth`.
      */
-    dispatch(request: RPCRequest): Promise<RPCResponse>;
+    dispatch(input: RPCRequest, trusted?: RPCContextOptions): Promise<RPCResponse>;
     /**
      * Runs the interceptor chain around the dispatch.
      *

package/dist/rpc/dispatcher/rpcDispatcher.core.js

@@ -1,4 +1,4 @@
-import { createRPCContext } from "../context/rpcContext.type.js";
+import { bindRPCContextInput, createRPCContext, } from "../context/rpcContext.type.js";
 import { createRPCResponse } from "../types/rpcResponse.type.js";
 import { RPCCancelledError } from "../errors/rpc.errors.js";
 import { DEFAULT_RPC_TIMEOUT } from "../constants/rpcConstants.core.js";
@@ -26,11 +26,19 @@ export class RPCDispatcher {
     }
     /**
      * Dispatches an RPC request.
+     *
+     * `trusted` carries server-supplied context (`auth`) that the caller
+     * cannot forge; it is exposed to middleware and handlers as
+     * `context.auth`.
      */
-    async dispatch(request) {
+    async dispatch(input, trusted = {}) {
+        // Tolerate a frame without `metadata`: the field is optional when a
+        // request is built by hand or decoded from JSON, and everything below
+        // — deadline reading, the context's `metadata` — reads it as an object.
+        const request = input.metadata === undefined ? { ...input, metadata: {} } : input;
         const procedure = this.registry.require(request.procedure);
         const controller = new AbortController();
-        const context = createRPCContext(request, controller.signal);
+        const context = createRPCContext(request, controller.signal, trusted);
         const timeoutMs = this.resolveTimeout(request, procedure);
         // A deadline already in the past is rejected before any work runs.
         if (this.options.honourDeadline ?? true) {
@@ -45,6 +53,7 @@ export class RPCDispatcher {
                 const input = procedure.options?.input
                     ? parseInput(procedure.options.input, request.payload, request.procedure)
                     : request.payload;
+                bindRPCContextInput(context, input);
                 const result = await this.middleware.execute(context, async () => {
                     return procedure.handler(input, context);
                 });

package/dist/rpc/server/rpcServer.core.d.ts

@@ -3,6 +3,7 @@ import type { RPCResponse } from "../types/rpcResponse.type.js";
 import type { RPCProcedure } from "../procedure/rpcProcedure.type.js";
 import { RPCProcedureRegistry } from "../procedure/rpcProcedureRegistry.core.js";
 import { RPCMiddlewareStack } from "../middleware/rpcMiddleware.core.js";
+import type { RPCContextOptions } from "../context/rpcContext.type.js";
 import type { RPCDispatcherOptions } from "../dispatcher/rpcDispatcher.core.js";
 import type { RPCRequestLimits } from "../validation/rpcValidation.core.js";
 /**
@@ -49,8 +50,13 @@ export declare class RPCServer {
      * `onInternalError` and answered with a fixed message: internal
      * exception text can name hosts, paths, credentials or queries, and
      * the caller is an untrusted peer.
+     *
+     * Everything in `request` comes from that peer, including
+     * `request.metadata.userId`. Identity the transport has verified goes
+     * in `trusted.auth` and reaches middleware and handlers as
+     * `context.auth`; authorise on that, never on frame metadata.
      */
-    handle(request: RPCRequest): Promise<RPCResponse>;
+    handle(request: RPCRequest, trusted?: RPCContextOptions): Promise<RPCResponse>;
     /**
      * Returns the procedure registry.
      */

package/dist/rpc/server/rpcServer.core.js

@@ -2,7 +2,7 @@ import { RPCProcedureRegistry } from "../procedure/rpcProcedureRegistry.core.js"
 import { RPCMiddlewareStack } from "../middleware/rpcMiddleware.core.js";
 import { RPCDispatcher } from "../dispatcher/rpcDispatcher.core.js";
 import { createRPCErrorResponse } from "../types/rpcResponse.type.js";
-import { isRPCError, RPCAuthenticationError, RPCCancelledError, RPCDeadlineExceededError, RPCDeserializationError, RPCForbiddenError, RPCInvalidRequestError, RPCProcedureNotFoundError, RPCRateLimitedError, RPCSerializationError, RPCTimeoutError, RPCUnavailableError, RPCValidationError, } from "../errors/rpc.errors.js";
+import { isRPCError, RPCAuthenticationError, RPCCancelledError, RPCDeadlineExceededError, RPCDeserializationError, RPCForbiddenError, RPCInternalError, RPCInvalidRequestError, RPCProcedureNotFoundError, RPCRateLimitedError, RPCSerializationError, RPCTimeoutError, RPCUnavailableError, RPCValidationError, } from "../errors/rpc.errors.js";
 import { INTERNAL_ERROR_MESSAGE } from "../constants/rpcConstants.core.js";
 import { assertValidRequest } from "../validation/rpcValidation.core.js";
 /**
@@ -23,7 +23,10 @@ const ERROR_CODES = [
     [RPCTimeoutError, "RPC_TIMEOUT"],
     [RPCCancelledError, "RPC_CANCELLED"],
     [RPCUnavailableError, "RPC_UNAVAILABLE"],
-    [RPCSerializationError, "RPC_SERIALIZATION_ERROR"],
+    // A serialization failure is a server fault (500, `expose: false`) whose
+    // message names what could not be encoded; the code travels, the
+    // message goes to `onInternalError`.
+    [RPCSerializationError, "RPC_SERIALIZATION_ERROR", true],
     [RPCDeserializationError, "RPC_DESERIALIZATION_ERROR"],
 ];
 /**
@@ -62,14 +65,24 @@ export class RPCServer {
      * `onInternalError` and answered with a fixed message: internal
      * exception text can name hosts, paths, credentials or queries, and
      * the caller is an untrusted peer.
+     *
+     * Everything in `request` comes from that peer, including
+     * `request.metadata.userId`. Identity the transport has verified goes
+     * in `trusted.auth` and reaches middleware and handlers as
+     * `context.auth`; authorise on that, never on frame metadata.
      */
-    async handle(request) {
+    async handle(request, trusted = {}) {
         const requestId = typeof request?.id === "string"
             ? request.id
             : "";
         try {
             assertValidRequest(request, this.options.limits);
-            return await this.dispatcher.dispatch(request);
+            // `metadata` is optional on the wire (`createRPCRequest` fills it in,
+            // a hand-built or JSON-decoded frame need not). Every consumer below
+            // reads it as an object, so a frame without it used to fail with a
+            // TypeError reported as an internal error.
+            const frame = request.metadata === undefined ? { ...request, metadata: {} } : request;
+            return await this.dispatcher.dispatch(frame, trusted);
         }
         catch (error) {
             const mapped = this.mapError(error);
@@ -80,7 +93,21 @@ export class RPCServer {
                     message: INTERNAL_ERROR_MESSAGE,
                 });
             }
-            return createRPCErrorResponse(requestId, mapped);
+            if (mapped.internal) {
+                // The error is typed, so the caller keeps its code, but it was
+                // constructed with `expose: false`: its message is server detail
+                // and goes to the log, not the wire.
+                this.options.onInternalError?.(error, requestId);
+                return createRPCErrorResponse(requestId, {
+                    code: mapped.code,
+                    message: INTERNAL_ERROR_MESSAGE,
+                });
+            }
+            return createRPCErrorResponse(requestId, {
+                code: mapped.code,
+                message: mapped.message,
+                ...(mapped.details !== undefined ? { details: mapped.details } : {}),
+            });
         }
     }
     /**
@@ -96,13 +123,22 @@ export class RPCServer {
      * answers with a generic internal error.
      */
     mapError(error) {
-        for (const [type, code] of ERROR_CODES) {
+        // An RPCInternalError *is* the generic internal failure: it carries
+        // `expose: false` and a message written for the log. Mapping it like
+        // any other RPCError put that message on the wire.
+        if (error instanceof RPCInternalError) {
+            return undefined;
+        }
+        for (const [type, code, internal] of ERROR_CODES) {
             if (error instanceof type) {
                 const payload = {
                     code,
                     message: error.message,
+                    ...(internal ? { internal: true } : {}),
                 };
-                if (error instanceof RPCValidationError && error.issues !== undefined) {
+                if (error instanceof RPCValidationError &&
+                    error.issues !== undefined &&
+                    error.issues.length > 0) {
                     payload.details = error.issues;
                 }
                 if (error instanceof RPCRateLimitedError &&
@@ -113,9 +149,15 @@ export class RPCServer {
             }
         }
         // A custom RPCError subclass is still a deliberate, caller-facing
-        // error; honour its own code rather than hiding it.
+        // error; honour its own code rather than hiding it. Its message only
+        // travels when the error was built to be exposed — `RPCError`
+        // defaults to `expose: false`.
         if (isRPCError(error)) {
-            return { code: error.code, message: error.message };
+            return {
+                code: error.code,
+                message: error.message,
+                internal: error.expose === false,
+            };
         }
         return undefined;
     }

package/dist/rpc/validation/rpcValidation.core.d.ts

@@ -74,8 +74,13 @@ export declare function parseInput<T>(schema: RPCSchema<T>, value: unknown, proc
  * Parses a handler's result against its output schema.
  *
  * An invalid output is a server defect rather than a caller mistake, so
- * the issues describe internal shape and stay server-side: the thrown
- * error carries no issue detail.
+ * it is thrown as an `RPCInternalError` (`expose: false`): the server
+ * answers with the generic internal error and hands the detail — the
+ * failing paths and codes — to `onInternalError`. Throwing a validation
+ * error here told the caller *its* request was invalid, with an empty
+ * issue list, for a fault that is entirely the handler's.
+ *
+ * @throws {RPCInternalError}
  */
 export declare function parseOutput<T>(schema: RPCSchema<T>, value: unknown, procedureName: string): T;
 //# sourceMappingURL=rpcValidation.core.d.ts.map

package/dist/rpc/validation/rpcValidation.core.js

@@ -6,7 +6,7 @@
  * Requests arrive from an untrusted peer over a transport, so these are
  * the first checks the server runs, not the last.
  */
-import { RPCInvalidRequestError, RPCValidationError, } from "../errors/rpc.errors.js";
+import { RPCInternalError, RPCInvalidRequestError, RPCValidationError, } from "../errors/rpc.errors.js";
 import { MAX_PROCEDURE_NAME_LENGTH, MAX_RPC_PAYLOAD_SIZE, PROCEDURE_NAME_PATTERN, } from "../constants/rpcConstants.core.js";
 /**
  * Validates a procedure name.
@@ -112,14 +112,22 @@ export function parseInput(schema, value, procedureName) {
  * Parses a handler's result against its output schema.
  *
  * An invalid output is a server defect rather than a caller mistake, so
- * the issues describe internal shape and stay server-side: the thrown
- * error carries no issue detail.
+ * it is thrown as an `RPCInternalError` (`expose: false`): the server
+ * answers with the generic internal error and hands the detail — the
+ * failing paths and codes — to `onInternalError`. Throwing a validation
+ * error here told the caller *its* request was invalid, with an empty
+ * issue list, for a fault that is entirely the handler's.
+ *
+ * @throws {RPCInternalError}
  */
 export function parseOutput(schema, value, procedureName) {
     const result = schema.safeParse(value);
     if (result.success) {
         return result.data;
     }
-    throw new RPCValidationError(`Procedure "${procedureName}" produced a response that does not match its output schema.`, undefined, procedureName);
+    const where = toValidationIssues(result.issues)
+        .map((issue) => `${issue.path || "(root)"}: ${issue.code}`)
+        .join(", ");
+    throw new RPCInternalError(`Procedure "${procedureName}" produced a response that does not match its output schema at ${where}.`, procedureName);
 }
 //# sourceMappingURL=rpcValidation.core.js.map

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/rpc",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Remote procedure call infrastructure for Zudojs applications.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,10 +27,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0",
-    "@zudojs/types": "1.0.0",
-    "@zudojs/schema": "1.0.0"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/types": "1.1.0",
+    "@zudojs/schema": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",