@thednp/rpc 0.0.13 → 0.1.1

package/AGENTS.md

@@ -17,16 +17,18 @@ pnpm fix:ts # deno lint src --fix
 pnpm check:ts # tsc -noEmit
 pnpm format # deno fmt src
 pnpm build # tsdown (outputs to dist/)
-pnpm up:examples # Update all example deps
-pnpm up:src # Update all src deps
+pnpm up:examples # Update all example deps (to latest published @thednp/rpc + latest example deps)
+pnpm up:examples:lib # Sync examples to the latest published @thednp/rpc version
 pnpm up:root # Update root deps
-pnpm upd # Update all deps (up:examples + up:src + up:root)
-pnpm prepublishOnly # upd + lint + check:ts + format + build
+pnpm up:deno # deno update + sync deno.json deps
+pnpm upd # Update all deps (up:examples + up:examples:lib + up:root)
+pnpm prepareOnly # upd + up:deno + lint + format + audit:src + build
+pnpm release # Publish npm + jsr (scripts/release.js)
 ```
 
 ## Build Order
 
-`lint -> check:ts -> format -> build` (verified in `prepublishOnly`)
+`lint -> check:ts -> format -> build` (verified in `prepareOnly`)
 
 ## Examples
 
@@ -81,7 +83,7 @@ The tsdown.config.ts produces multiple entries:
 
 ## Important Notes
 
-- In dev mode, **only** the Vite dev server and Express/Connect middleware are available, which means adapters don't work in DEV mode
+- In dev mode, **only** the Vite dev server ([Connect](https://github.com/senchalabs/connect) powered) and Express middleware are available, which means adapters don't work in DEV mode
 - Uses `deno` for linting and formatting (not eslint/prettier)
 - Uses `tsdown` for bundling (not rollup/vite directly)
 - Uses `vitest` for testing with `istanbul` coverage
@@ -131,12 +133,12 @@ The framework's security boundary is the **RPC prefix-gated HTTP endpoint**. Inp
 
 ## Documentation
 
-- `wiki/index.md` — Overview
-- `wiki/getting-started.md` — Quick start
-- `wiki/setup.md` — Project structure and configuration
-- `wiki/server-functions.md` — Creating server functions
-- `wiki/client-usage.md` — Client-side usage
-- `wiki/configuration.md` — Configuration reference
-- `wiki/adapters.md` — Framework adapters
+- `wiki/quickstart.md` — Rebuild the Express SSR example from `create-vite` in under a minute (copy-paste)
+- `wiki/getting-started.md` — Installation, project structure, auto-scanning, and your first function
+- `wiki/configuration.md` — Configuration reference (`rpc.config.ts`, `vite.config.ts`, options)
+- `wiki/server-functions.md` — `createServerFunction` API, methods, validation
+- `wiki/client-usage.md` — Client-side usage, type safety, react-query integration
+- `wiki/wire-protocol.md` — HTTP contract, request/response bodies, curl debugging
+- `wiki/adapters.md` — Framework adapters (Express, Fastify, Hono, Koa)
 - `wiki/security.md` — Security hardening
-- `wiki/best-practices.md` — Tips and best practices
+- `wiki/best-practices.md` — Production patterns (auth, rate limiting, body limits, CSRF)

package/CHANGELOG.md

@@ -0,0 +1,276 @@
+# Changelog
+
+## [0.1.1] - 2026-08-07
+
+### Security
+
+- Unexpected exceptions no longer expose their message in development responses: `formatError` returns the generic `{ error: "Internal Server Error" }` for any non-`RPCError` error in every environment. `RPCError` payloads (developer-authored `message`, `code`, optional `data`) are still included in development so client-side error handling keeps working, while diagnostics stay server-side via the middleware's `console.error` logging (addresses the GitHub CodeQL `js/exception-information-leak` finding)
+
+### Refactor
+
+- `scanForServerFiles` lazy-imports Vite inside the scan function instead of importing it statically at the top of the module — the standalone server entry no longer carries a static Vite dependency, so serverless function bundles that register API modules directly no longer drag Vite's node chunk (which imports esbuild, absent with Vite 8's rolldown) into the bundle
+- Drop the redundant `config as ScanConfig` casts in `scanForServerFiles` (the merged config is already typed)
+
+### Fixes
+
+- Netlify serverless deployment: externalize Vite from the function bundle via `[functions] external_node_modules = ["vite"]` in `netlify.toml`, so `@netlify/zip-it-and-ship-it` no longer fails with "Could not resolve 'esbuild'" when bundling the RPC function
+- Fix broken documentation links in all 6 example READMEs (`wiki/setup.md` → `wiki/wire-protocol.md`, the former never existed)
+- Remove stale `demo/src/render-bak.ts`; clean up the pnpm lockfile
+
+### Docs
+
+- Update `wiki/security.md`, `wiki/wire-protocol.md`, `README.md`, and `llms.txt` to reflect that unexpected exception details never reach clients — only `RPCError` payloads, and only in development
+
+### Tests
+
+- `formatError` dev-mode tests updated to assert the generic message for unexpected exceptions (plain `Error` and non-`Error` values), keeping the `RPCError` payload assertions
+
+### Chores
+
+- Sync demo and all 6 examples to `@thednp/rpc ^0.1.0`
+- Remove the leftover `0.0.14` changelog header (its entry was merged into `0.1.0`)
+
+## [0.1.0] - 2026-08-06
+
+### Features
+
+- **Typed errors with env-aware responses**: new `RPCError` class (`message` + `code` + optional `data`) and `formatError` helper. All adapters now return `{ error: "Internal Server Error" }` in production (no message/stack leak) and include the error message (plus `code`/`data` for `RPCError`) in development
+- **Duplicate server function detection**: the scan throws in development when two files export functions with the same registered name, so the conflict surfaces at dev-server startup; in production it warns and keeps the first registration
+- **Glob server file scanning**: new `serverFiles: "glob"` option recursively matches `*.server.{ts,js,mjs,mts}` under the scan root, complementing the classic exact `server.ts|js|mjs|mts` names
+- **`scanRoot` option**: point scanning at any directory (relative to the Vite root), e.g. a shared RPC package in a monorepo
+- **`multipart/form-data` content type**: the `contentType` option and `BodyResult` now include multipart; adapters detect multipart bodies from framework parsers (`multer`, `@fastify/multipart`, `koa-body`, Hono form helpers) and pass the parsed fields as the function argument, falling back to `{ raw: <body> }` on the raw stream path
+
+### Refactor
+
+- `src/index.ts` imports `scanForServerFiles`/`getClientModules`/`serverFunctionsMap` from source modules instead of the `@thednp/rpc/server` self-reference (which resolved to stale `dist/` types during type-checking)
+- Plugin `options` initialized from `defaultRPCOptions` at creation time, so hooks can be invoked without `configResolved` having run
+
+### Tests
+
+- `formatError` unit tests (production vs development, `RPCError` code/data)
+- Multipart `readBody` tests for all four adapters (pre-parsed and raw stream paths)
+- Scan tests: glob mode (recursive + explicit `scanRoot`), duplicate detection (throw in dev, warn in production)
+
+### Chores
+
+- Rename the `prepublishOnly` script to `prepareOnly` in `package.json` (keeping `prepublishOnly_` as a non-triggering alias) so `npm publish` inside the release script no longer auto-runs the full pipeline
+- Import `createRPCMiddleware` from the `@thednp/rpc/express` subpath export in `src/index.ts` instead of the relative `./express/createMiddleware.ts`; add `@thednp/rpc/express` to the tsdown externals and the vitest alias map
+- Refactor `getClientModules` to build the generated client modules into a local `entries` const before assembling the output
+- Publish workflow: remove the npm debug-log diagnostic step
+- Sync all 6 examples to `@thednp/rpc ^0.0.13`; bump `@fastify/compress` to `^9.1.1` in the fastify example and add it to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`
+
+## [0.0.13] - 2026-08-04
+
+### Chores
+
+- Bump version to `0.0.13`
+- Add `hono@4.13.0` and `@hono/node-server@2.1.0` to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` so pnpm 11's default 1-day minimum release age doesn't hold back the freshly published versions
+- Update dependencies: `hono ^4.13.0`, `@hono/node-server ^2.1.0`, `fastify ^5.11.2`; sync all 6 examples to `@thednp/rpc ^0.0.12`
+- Restore the `prepublishOnly` script name in `package.json`
+
+### Docs
+
+- Clarify `wiki/client-usage.md` and `wiki/security.md`, `README.md`, and `tsdown.config.ts` comments
+
+## [0.0.12] - 2026-08-03
+
+### Chores
+
+- Bump version to `0.0.12`
+- Publish workflow: drop `--provenance` from the npm publish step to match the vite-style publish flow (npm 11 auto-attaches provenance in trusted-publishing mode; the raw well-formed PUT fallback remains the working publish path)
+- Add `scripts/update-examples.js` — syncs all examples to the latest published `@thednp/rpc` version — wired as `up:examples:lib` and included in `up:examples`
+- Update all 6 examples to `@thednp/rpc ^0.0.11`
+
+## [0.0.11] - 2026-08-02
+
+### Chores
+
+- Bump version to `0.0.11`
+- Publish workflow: use npm only
+
+## [0.0.10] - 2026-08-02
+
+### Chores
+
+- Bump version to `0.0.10`
+- Publish workflow: pin `npm i -g npm@latest` (verified against npm 12.0.2 — OIDC token exchange `201` + sigstore provenance still published, but the `npm publish` PUT remains masked-403), strip the diagnostic capture/bisect steps and the `debug_403` dispatch input, and move `scripts/npm-request-recorder.js` to `experiments/`
+
+## [0.0.9] - 2026-08-02
+
+### Chores
+
+- Bump version to `0.0.9`
+- Publish workflow: drop `--allow-slow-types` from the jsr publish step (verified clean via `deno publish --dry-run`, no slow-types diagnostics)
+
+## [0.0.8] - 2026-08-02
+
+### Chores
+
+- Bump version to `0.0.8`
+- Publish workflow: move the header bisect diagnostic after the raw PUT fallback so probes always replay against the already-published version (never publish a fresh one); add a jsr version guard so release-triggered re-runs are no-ops
+
+## [0.0.7] - 2026-08-02
+
+### Chores
+
+- Bump version to `0.0.7`
+- Publish workflow: attempt plain `npm publish --provenance` (OIDC trusted publishing with provenance enabled) before falling back to the raw well-formed PUT; gate the CLI-403 diagnostic steps (request capture + header bisect) behind a `debug_403` workflow_dispatch input so release runs stay clean
+
+## [0.0.6] - 2026-08-02
+
+### Docs
+
+- Add a **Body Size Limits** section to each framework's section in `wiki/adapters.md` (Express `express.json({ limit })`, Fastify `bodyLimit`, Hono `hono/body-limit`, Koa `koaBody({ jsonLimit })`), each matching its `examples/<framework>/server.js` implementation
+- Clarify in `wiki/security.md` that Koa's official `koa-body` and Hono's built-in `hono/body-limit` middleware are the body size limiting enforcement points
+
+### Chores
+
+- Bump version to `0.0.6`
+- Add `scripts/npm-request-recorder.js` — an in-process HTTP(S) request/response recorder injected into `npm publish` via `NODE_OPTIONS="--import"` that dumps the exact request headers/body and the server response to diagnose the CLI's masked 403 publish error
+- Publish workflow: skip the CLI publish if the version already exists on the registry, add a "Capture CLI 403 (diagnostic)" step, and move `npm pack` output to `/tmp` so the git tree stays clean
+
+## [0.0.5] - 2026-08-02
+
+### TypeScript
+
+- Export the `InnerModReturn` helper type from `src/types.d.ts` instead of declaring it locally in `src/helpers.ts`, so consumers can reference the `{ data, cancel }` return shape of `innerModule`
+- Move all remaining module-local type/interface definitions into their closest `types.d.ts`, exporting them: `ScanConfig` and `RpcPluginOptionsInternal` → `src/types.d.ts`, `FastifyRPCPlugin`/`FastifyPlugin`/`RegisteredFastifyRPCPlugin` → `src/fastify/types.d.ts`, `IncomingWithBody` → `src/hono/types.d.ts`; removed now-unused imports (`ResolvedConfig`, `FastifyInstance`, `FastifyPlugin`) from their origin files
+
+### Docs
+
+- Update all 6 examples (`spa`, `express`, `fastify`, `hono`, `koa`, `ssr`) to `@thednp/rpc ^0.0.4`
+- Clarify in the README "Why this exists" section the niche `@thednp/rpc` targets: RPC without the weight of an entire framework (Vite sites, static SPAs, single-middleware servers) — no meta-framework, full-stack router, or vendor required
+
+### Chores
+
+- Bump version to `0.0.5`
+- `scripts/dev-test.js`: the default `@thednp/rpc` version used when restoring example deps is now read from the root `package.json` (as `^<version>`) instead of removing the dependency when no original value was saved
+- Rebuild `dist/` to pick up the exported types
+
+## [0.0.4] - 2026-08-02
+
+### Breaking
+
+- Restrict RPC dispatch to configured HTTP methods: server functions default to `POST` and are now rejected with `405 Method Not Allowed` on any other method (previously any method was accepted)
+
+### Features
+
+- Add `method` option to `ServerFunctionOptions` (`"GET" | "POST"`, default `"POST"`) for per-function HTTP method control
+- Add `origin` option to `MiddlewareOptions` — when set, requests with a mismatching `Origin` header are rejected with `403 Forbidden` (requests without an `Origin` header, e.g. curl, pass)
+- GET function dispatch: generated client modules send args as a URL-encoded `?args=` JSON query parameter (no request body)
+
+### Security
+
+- Enforce method + origin checks in all 4 adapters (Express, Fastify, Hono, Koa) with anchored prefix matching already in place
+- Hono adapter: guard `env.incoming` with optional chaining so bare serverless environments without an incoming stream no longer crash
+
+### Fixes
+
+- Scan server files by exact filename (`.ts`/`.mjs`/`.cjs` in the configured directory) instead of substring matching, so files like `server.tsx` are no longer picked up
+- Bump `@hono/node-server` to `^2.0.5` via `pnpm-workspace.yaml` override (fixes GHSA-frvp-7c67-39w9 audit advisory pulled in transitively by `@hono/vite-dev-server`)
+
+### Docs
+
+- Add `wiki/best-practices.md` sections on rate limiting and Origin/CSRF protection with framework-specific middleware snippets
+- Document the `method` option in `wiki/server-functions.md`
+- Add Method Enforcement and Origin Validation sections to `wiki/security.md`
+- Document exact scan filename matching in `wiki/setup.md`
+- Add an "HTTP Method" section to `wiki/server-functions.md` explaining why only GET and POST are supported (RPC has no resource semantics, OPTIONS is reserved for CORS preflight, minimal attack surface)
+- Add a method-restriction security note (GET/POST only) to the README security section
+
+### Chores
+
+- Bump version to `0.0.4`
+- Add test coverage for method dispatch (POST default, GET with `?args=`, 405 enforcement), origin validation (mismatch 403, absent origin passes), and exact scan matching
+- Reach 100% test coverage (232 tests): add `validateMethod` suite, GET client-module fetch test, and GET dispatch coverage for Hono and Koa
+- Add a GET server function demo (`getServerTime`) with a "Get time" UI and shareable link to all 6 examples; add `tsconfig.json` to the `ssr` example and `types: ["vite/client"]` to example tsconfigs
+- Move `dev-test.js` to `scripts/dev-test.js` and enhance it: switch examples to `link:../..` before testing and restore the published version afterwards, verify GET dispatch, install with `--no-frozen-lockfile`
+- Add `scripts/audit-src.js` — audits only the root package's dependencies in a temp project (344 deps vs 413 for the full workspace) — wired into `prepublishOnly` as `audit:src`
+- Add `scripts/update-deno.js` to sync JSR metadata (`version`, `description`, `keywords`, `license`) from `package.json` into `deno.json`; add `up:deno` task
+- Refactor `deno.json` tasks to `deno task` self-references; `prepublishOnly` is now `upd` + `lint` + `format` + `audit:src` + `build`
+- Run `pnpm audit` in CI and trigger workflows on `pnpm-workspace.yaml` changes
+- Sync `deno.json` keywords with `package.json` (`vite`, `vite-plugin` added)
+
+## [0.0.3] - 2026-07-30
+
+### Docs
+
+- Add comprehensive JSDoc to all exported functions across the codebase (~50 symbols) with `@param` and `@returns` tags
+- Add `@module` JSDoc to all 8 entrypoints for JSR documentation generation
+- Add JSDoc to all exported types, interfaces, and their properties (framework hooks, middleware options, JSON types, adapter types) for JSR documentation scoring
+
+### Chores
+
+- Add `description`, `author`, and `keywords` to `deno.json` for JSR metadata
+- Add `imports` map to `deno.json` for JSR self-referencing resolution
+- Bump version to `0.0.3`
+
+## [0.0.2] - 2026-07-30
+
+### Breaking
+
+- Rename `rpcPreffix` → `rpcPrefix` across all configs, adapters, types, and docs (the old typo is no longer recognized)
+
+### Features
+
+- Add `credentials` option to `ServerFunctionOptions` (`"same-origin" | "include" | "omit"`, default `"same-origin"`)
+- Add `validateCredentials()` to validate the credentials option at build time
+- Rename `rpcPreffix` internal variable consistently to `rpcPrefix`
+- Thread `credentials` through generated client modules and `innerModule`
+
+### Refactor
+
+- Centralize all error/warning messages into `src/constants.ts`
+- Extract validation functions (`validateIdentifier`, `validatePathSegment`) into `src/validate.ts` with 100% test coverage
+- Move safe-identifier regex patterns from `constants.ts` to `validate.ts` (implementation detail)
+- Add explicit return types to all adapter helpers and core functions
+- Add `RequestDetails` and `ResponseDetails` types to Express adapter
+- Add `InnerModReturn` helper type to `helpers.ts`
+- Fully type Fastify plugin with explicit interface
+- Type `serverFunctionsMap` explicitly in `functionsMap.ts`
+- Convert `defineConfig` and `loadRPCConfig` to typed arrow functions
+
+### Fixes
+
+- Publish workflow: remove `--provenance`, Node version 24
+- Fix AGENTS.md express command, fix Koa adapter docs
+- README GitHub URLs: `rpcv` → `rpc`
+- Proper pnpm workspace setup for StackBlitz
+- StackBlitz compatibility for examples
+- Remove `prepare` script to prevent rolldown native binding error on StackBlitz
+- SPA proxy server: cast `createRPCMiddleware` options for type safety
+- Move adapter deps from `devDependencies` to `dependencies` for correct runtime resolution
+
+### Docs
+
+- Expand Authentication section in best-practices with Basic Authorization + Per-Function Authorization examples
+- Add CONTRIBUTING section to README
+- Update all wiki docs to use `rpcPrefix`
+- Clarify isomorphic nature of server functions in wiki
+- Add README.md to each example
+- Use full wiki URLs in example READMEs
+- Fix broken link in security.md (`best-practives.md` → `best-practices.md`)
+- Fix cancellation description in client-usage.md to match actual behavior
+
+### Chores
+
+- Create CHANGELOG.md
+- Update `dist/` with latest builds
+- Update examples dependencies
+- Bump version to `0.0.2`
+- Add `keywords` field to package.json
+- Move `picocolors` from root to examples/spa
+
+## [0.0.1] - 2026-07-28
+
+### Initial Release
+
+- Vite plugin for automatic RPC generation
+- Framework-agnostic core with adapters for Express, Fastify, Hono, and Koa
+- Auto-scanning of server functions via `scanForServerFiles`
+- Client-side module generation at build time
+- Request cancellation via `AbortController`
+- Prefix-gated RPC endpoint with regex boundary protection
+- Code injection prevention in client module generation
+- SSR and SPA support
+- Configuration via `rpc.config.ts`

package/README.md

@@ -16,9 +16,9 @@ The server functions run **isomorphically** within any Vite powered runtime.
 
 ## Why this exists
 
-Most RPC solutions ask you to adopt a new way of thinking, require learning a complex API, some are vendor locked, some even allow you to blend in with your client code (via `"use server"` directive), for sure they are powerful and work well, they provide excellent DX, but complexity always comes with its own drawbacks.
+Many RPC solutions like to overcomplicate things to the point where you no longer ship features, you're maintaining a framework. RPC should be a bridge, not a metropolis.
 
-`@thednp/rpc` carves out the niche that wants to do RPC **without the weight of an entire framework**. If your app is a Vite site, a static SPA, or a small server powered by a single middleware — but you still want typed, cancellable, server-only functions callable from the client — you shouldn't have to adopt a full meta-framework, a full-stack router, or a build-time convention just to bridge the two. This plugin gives you that bridge alone: no framework to learn, no runtime to adopt, no vendor to sign up with.
+`@thednp/rpc` allows you to supercharge any vite powered SPA/SSR starter template in minutes. To prove it, we made a quick guide to [recreate our Express SSR example](./wiki/quickstart.md).
 
 ### Simplicity is best
 
@@ -26,7 +26,7 @@ Most RPC solutions ask you to adopt a new way of thinking, require learning a co
 <details>
 <summary><b>Server functions should just be functions</b></summary>
 
-You define them in a file, import and call them where you need them. The plugin handles everything in between — system wide configuration, scanning, type inference, client stub generation, middleware registration, request cancellation — without asking you to restructure your codebase.
+You define them in a file, import and call them where you need them. The plugin handles everything in between — system wide configuration, scanning, type inference, client fetch modules generation, middleware registration, request cancellation — without asking you to restructure your codebase.
 </details>
 
 <details>
@@ -34,7 +34,8 @@ You define them in a file, import and call them where you need them. The plugin
 
 * `createFunction.ts` — server-side definition (wrapped handler with `AbortController`)
 * `getClientModules.ts` — build-time code generation (string template with validation)
-* `helpers.ts` — client-side runtime (thin `fetch` based modules)
+* `client-helpers.ts` — client-side runtime (thin `fetch` based modules)
+* `server-helpers.ts` — server-only utilities (`RPCError`, error formatting, glob file walking)
 * `scanForServerFiles.ts` — file discovery
 * **Adapters** — thin middleware wrappers
 </details>
@@ -80,6 +81,18 @@ Every server function call returns a handle with a `cancel()` helper. Under the
 The core plugin doesn't care whether you're running Express, Fastify, Hono, or Koa. Adapters for all four are bundled with the package — you import the one you need, register it as middleware, and you're done. If you're building a plain SPA with no server framework at all, the Vite dev server handles RPC requests directly in development. No adapter needed.
 </details>
 
+<details>
+<summary><b>Flexible server file discovery</b></summary>
+
+Scan `src/api/` for classic `server.ts|js|mjs|mts` files, or switch to glob mode (`serverFiles: 'glob'`) to recursively pick up `*.server.{ts,js,mjs,mts}` files — handy for feature-based layouts. A `scanRoot` option points scanning at a shared package directory in monorepos. Duplicate function names throw in development so the conflict is fixed immediately (warning in production).
+</details>
+
+<details>
+<summary><b>Typed errors, safe by default</b></summary>
+
+Server errors return a generic `Internal Server Error` — no messages, codes, or stacks leak to clients, in any environment. Only `RPCError` payloads (developer-authored `message`/`code`/`data`) reach the client, and only in development, so you can debug instantly. `multipart/form-data` content type is supported for file uploads via your framework's multipart parser.
+</details>
+
 <details>
 <summary><b>TypeScript throughout</b></summary>
 
@@ -170,7 +183,7 @@ Check [Configuration Guide](wiki/configuration.md) for details.
 Create `src/api/server.ts`:
 
 ```ts
-import { createServerFunction } from "@thednp/rpc/server";
+import { createServerFunction, RPCError } from "@thednp/rpc/server";
 
 export const greet = createServerFunction("greet", (signal, name: string) => {
   // access AbortSignal
@@ -178,11 +191,16 @@ export const greet = createServerFunction("greet", (signal, name: string) => {
 
   // add validation and other server ONLY functionality
 
+  // throw typed errors for server-side failures
+  if (!name) throw new RPCError("Name is required", "EMPTY_NAME");
+
   // return the result of processing
   return `Hello, ${name}!`;
 });
 ```
 
+`RPCError` is the typed error helper — in development its message (and `code`/`data`) reach the client for instant debugging; in production the response is always a generic `Internal Server Error`.
+
 Create `src/api/index.ts`:
 
 ```ts
@@ -231,7 +249,7 @@ pnpm test-ui      # Run tests with UI
 pnpm test --run   # Single run
 ```
 
-Tests use **Vitest** with **Istanbul** coverage. There are 6 test files covering all adapters plus the plugin.
+Tests use **Vitest** with **Istanbul** coverage — 8 test files covering the plugin, scanning, client/server helpers, and all four adapters, at 100% coverage.
 
 ### Live Testing
 
@@ -307,11 +325,12 @@ The full threat model, including edge cases and configuration options for tighte
 
 ## Documentation
 
-- [Getting Started](./wiki/getting-started.md)
-- [Setup Guide](./wiki/setup.md)
+- [Quick Start](./wiki/quickstart.md) — Rebuild the Express SSR example from `create-vite` in under a minute
+- [Getting Started](./wiki/getting-started.md) — Installation, project structure, and your first function
 - [Configuration](./wiki/configuration.md)
 - [Server Functions](./wiki/server-functions.md)
 - [Client Usage](./wiki/client-usage.md)
+- [Wire Protocol](./wiki/wire-protocol.md) — The HTTP contract behind the generated clients (curl debugging)
 - [Adapters](./wiki/adapters.md)
 - [Best Practices](./wiki/best-practices.md)
 - [Security](./wiki/security.md)

package/dist/express/express.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"express.d.mts","names":[],"sources":["../../src/express/types.d.ts","../../src/express/createMiddleware.ts","../../src/express/helpers.ts"],"mappings":";;;;;;;;KAgBY,2BAA2B;;;;;KAM3B,uBACV,UAAU,yCAEV,iBAAiB,QAAQ,8BACtB;;;;UAKY;;;;;;;EAOf,UACE,KAAK,kBAAkB,SACvB,KAAK,iBAAiB,UACtB,MAAM,QAAQ,eAAe,iBAC1B;;;;;;KAOK;;EAEV;;EAEA,YAAY,cAAc;;EAE1B;;EAEA,gBAAgB;;EAEhB,eAAe,cAAc,QAAQ,eAAe;;;;;KAM1C;;EAEV;;EAEA;;EAEA,cAAc;;EAEd,SAAS;;EAET;;;;;;;;;;;cCtCW,kBAAkB;;;;;;;;cAyElB,qBAAqB;;;;;;;;iBC5FZ,UAAU,KAAK,UAAO;;;;;;iBAW5B,WAAW,KAAK,SAAS,MAAM;;;;;;;;cAWlC,WAAQ,KACd,UAAiB,oBACrB,QAAQ;;;;;;cA2DE,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;cASG,oBAAiB,KACvB,iBAAiB,aACrB,OAAO;;;;;;;cAUG,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;;cAUG,oBAAiB,SACnB,UAAiB,oBACzB;;;;;;;cAqBU,qBAAkB,UACnB,WAAkB,mBAC3B"}
+{"version":3,"file":"express.d.mts","names":[],"sources":["../../src/express/types.d.ts","../../src/express/createMiddleware.ts","../../src/express/helpers.ts"],"mappings":";;;;;;;;KAgBY,2BAA2B;;;;;KAM3B,uBACV,UAAU,yCAEV,iBAAiB,QAAQ,8BACtB;;;;UAKY;;;;;;;EAOf,UACE,KAAK,kBAAkB,SACvB,KAAK,iBAAiB,UACtB,MAAM,QAAQ,eAAe,iBAC1B;;;;;;KAOK;;EAEV;;EAEA,YAAY,cAAc;;EAE1B;;EAEA,gBAAgB;;EAEhB,eAAe,cAAc,QAAQ,eAAe;;;;;KAM1C;;EAEV;;EAEA;;EAEA,cAAc;;EAEd,SAAS;;EAET;;;;;;;;;;;cCvCW,kBAAkB;;;;;;;;cAyElB,qBAAqB;;;;;;;;iBC3FZ,UAAU,KAAK,UAAO;;;;;;iBAc5B,WAAW,KAAK,SAAS,MAAM;;;;;;;;cAWlC,WAAQ,KACd,UAAiB,oBACrB,QAAQ;;;;;;cAyEE,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;cASG,oBAAiB,KACvB,iBAAiB,aACrB,OAAO;;;;;;;cAUG,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;;cAUG,oBAAiB,SACnB,UAAiB,oBACzB;;;;;;;cAqBU,qBAAkB,UACnB,WAAkB,mBAC3B"}

package/dist/express/express.mjs

@@ -2,7 +2,9 @@ import { scanForServerFiles, serverFunctionsMap } from "@thednp/rpc/server";
 //#region src/options.ts
 const defaultRPCOptions = {
 	rpcPrefix: "__rpc",
-	adapter: "express"
+	adapter: "express",
+	serverFiles: "exact",
+	scanRoot: void 0
 };
 const defaultMiddlewareOptions = {
 	rpcPrefix: void 0,
@@ -39,10 +41,12 @@ function attachVite(app, vite) {
 const readBody = (req) => {
 	return new Promise((resolve, reject) => {
 		if (hasPreParsedBody(req) && req.body !== void 0) {
-			const isJSON = (req.headers["content-type"]?.toLowerCase() || "").includes("json");
+			const contentType = req.headers["content-type"]?.toLowerCase() || "";
+			const isJSON = contentType.includes("json");
+			const isMultipart = contentType.includes("multipart/form-data");
 			resolve({
-				contentType: isJSON ? "application/json" : "text/plain",
-				data: isJSON ? req.body : String(req.body)
+				contentType: isMultipart ? "multipart/form-data" : isJSON ? "application/json" : "text/plain",
+				data: isMultipart ? req.body : isJSON ? req.body : String(req.body)
 			});
 			return;
 		}
@@ -58,12 +62,14 @@ const readBody = (req) => {
 		};
 		const onEnd = () => {
 			toggleListeners();
-			const isJSON = (req.headers["content-type"]?.toLowerCase() || "").includes("json");
+			const incomingType = req.headers["content-type"]?.toLowerCase() || "";
+			const isJSON = incomingType.includes("json");
+			const isMultipart = incomingType.includes("multipart/form-data");
 			try {
-				const data = JSON.parse(body);
+				const data = isMultipart ? { raw: body } : JSON.parse(body);
 				resolve({
-					contentType: isJSON ? "application/json" : "text/plain",
-					data
+					contentType: isMultipart ? "multipart/form-data" : isJSON ? "application/json" : "text/plain",
+					data: isMultipart ? data : data
 				});
 			} catch (_e) {
 				resolve({
@@ -173,6 +179,45 @@ const CLIENT_DISCONNECTED = "client disconnected";
 /** Returns a warning when a middleware name is reused, preventing registration conflicts. @param name - The duplicate middleware name */
 const MIDDLEWARE_NAME_USED = (name) => `The middleware name "${name}" is already used.`;
 //#endregion
+//#region src/server-helpers.ts
+/**
+* A typed error thrown from server functions.
+* The middleware serializes the `message` and `code` in the response,
+* allowing clients to recognise and handle specific error conditions.
+*/
+var RPCError = class extends Error {
+	/** Machine-readable error code (e.g. "VALIDATION_FAILED", "UNAUTHORIZED") */
+	code;
+	/** Optional diagnostic payload */
+	data;
+	constructor(message, code = "INTERNAL", data) {
+		super(message);
+		this.name = "RPCError";
+		this.code = code;
+		this.data = data;
+	}
+};
+/**
+* Formats an error for the RPC middleware response.
+* In development the full `RPCError` payload is included so developers
+* can quickly identify issues. Unexpected exceptions never expose their
+* message — only the generic "Internal Server Error" is sent, preventing
+* information disclosure; server-side diagnostics are preserved via the
+* middleware's `console.error` logging.
+*/
+const formatError = (err, isProduction) => {
+	if (isProduction) return { error: INTERNAL_SERVER_ERROR };
+	if (err instanceof RPCError) {
+		const payload = {
+			error: err.message || "Internal Server Error",
+			code: err.code
+		};
+		if (err.data !== void 0) payload.data = err.data;
+		return payload;
+	}
+	return { error: INTERNAL_SERVER_ERROR };
+};
+//#endregion
 //#region src/express/createMiddleware.ts
 let middlewareCount = 0;
 const middlewareStack = /* @__PURE__ */ new Set();
@@ -261,7 +306,8 @@ const createRPCMiddleware = (initialOptions = {}) => {
 				if (!res.headersSent) sendResponse(200, { data: result });
 			} catch (err) {
 				console.error(String(err));
-				sendResponse(500, { error: INTERNAL_SERVER_ERROR });
+				const isProduction = process.env.NODE_ENV === "production";
+				sendResponse(500, formatError(err, isProduction));
 			}
 		}
 	});