jxp 3.0.0 → 4.1.0

package/docs/changelog.md

@@ -1,56 +1,283 @@
 # Changelog
 
-## v1.0.0
+Notable changes to [JXP](https://github.com/WorkSpaceMan/jxp).
 
-- Mongoose v5
+## v4.1.0 — 2026-05-25
 
-## v1.0.1
+API docs browser security: gated model explorer, real API login, and brute-force limits.
 
-- Closed bad security hole in groups - now only admins can set groups. (Will probably change this in future so that only those defined in the usergroup model can change groups.)
+### Added
 
-## v1.0.12
+- **Docs access control** (`DOCS_ACCESS`) — `protected` (default), `disabled`, or `public`. Home (`/`) and usage guides (`/docs/md/*`) stay open; model explorer (`/docs/api`, `/docs/model/*`) requires sign-in.
+- **Docs sign-in flow** — `/docs/login` calls `POST /login`, then `POST /docs/session` to store an HttpOnly cookie; API key auto-fills for “Try it” panels (`GET /docs/session`).
+- **Login rate limiting** — per-IP token bucket on `POST /login` and `POST /docs/session` (default: burst 8, 12/min). Env: `LOGIN_RATE_LIMIT_*`; HTTP **429** when exceeded.
+- **`src/libs/docs-auth.ts`**, **`src/libs/login_rate_limit.ts`** — middleware, session cookie, and throttle helpers.
+- **Tests** — `test/docs_auth.test.js`, `test/login_rate_limit.test.js`.
 
-- Select individual fields in populate joins
+### Changed
 
-## v1.0.16
+- **Docs browser default** — model explorer is no longer world-readable; guides and landing page remain public in `protected` mode.
+- **Configuration** — [configuration.md](configuration.md) documents `DOCS_*` and `LOGIN_RATE_LIMIT_*` variables.
 
-- Add a /query endpoint, that allows you to POST { query } for advanced queries
+### Fixed
 
-## v1.2.3
+- **Restify async routes** — docs login/session handlers use `(req, res)` only; redirects use `sendRedirect()` where `res.redirect()` requires `next`.
 
-- Throttling
+## v4.0.0 — 2026-05-19
 
-## v1.2.4
+Major release: complete TypeScript rewrite and configuration overhaul.
 
-- Time log includes operation number
+### Breaking changes
 
-## v2.0.1-0
+- **Security hardening (4.0)** — see [migration](#security-hardening-migration) below.
+- **No `config` package** — configuration via `.env` / environment variables and `jxp/libs/load-config` (compiled to `dist/libs/load-config.js`). Removed `/config/*.json` and [node-config](https://www.npmjs.com/package/config).
+- **TypeScript** — framework source under `src/`; npm package ships compiled `dist/` with `.d.ts` types.
+- **Build from source** — `npm run build` when developing from a git clone; npm registry installs ship prebuilt `dist/`.
+- **Entry point** — `main` / `types` → `dist/libs/jxp.js` and `dist/libs/jxp.d.ts`.
+- **Node 22+** — `engines.node` is `>=22.0.0`.
+- **Relative paths** — `model_dir` and `log` resolve from `process.cwd()`, not the server script directory.
+- **Built-in models** — compile from `src/models/*.ts` to `dist/models/`; consumer apps still use `*_model.js` in `MODEL_DIR`.
 
-- Start v2!
-- Move to "connection_string" for MongoDB connection - allows connectivity to Atlas, for example
-- Use our own (much smarter) Schema class
+### Added
 
-## v2.0.1-1
+- **`loadJxpConfig()`** — builds `JXP()` options from environment variables (`.env`, `.env.test`).
+- **`package.json` `exports` map** — `jxp`, `jxp/libs/query_manipulation`, `jxp/libs/load-config`, `jxp/globals`.
+- **Globals types** — `/// <reference types="jxp/globals" />` for JavaScript model authoring.
+- **[docs/typescript.md](typescript.md)** — v4 migration guide.
+- **Built-in documentation UI** — landing page, MkDocs nav sidebar, per-model API reference.
+- **Interactive API console** — try REST endpoints from model pages; optional API key in docs navbar.
+- **Query limits** (from v3.1) — env/config `query_limits`; default limit on all list/query requests; required explicit `?limit=` on large collections.
+- **Security modules** — `query_sanitize`, `aggregate_guard`, `bulkwrite_guard`, `call_guard`, `response_sanitize`, `link_index`, `safe_error`.
+- **Schema options** — `callable_statics` (string array); `advanced_queries: { query?, aggregate?, bulkwrite? }` (bulkwrite off by default).
+- **Config / env** — `security.strip_fields`, `cors.origins`; `QUERY_LIMITS_DEFAULT`, `QUERY_LIMITS_SKIP_COUNT_UNLESS_PAGINATED`, `CORS_ORIGINS` (see [configuration.md](configuration.md)).
+- **Startup helpers** — Node 22+ deprecation warnings; `quiet_startup` option.
 
-- Tokens as the preferred login methodology
+### Changed
 
-## v2.4.x
+- **List responses** — `count` and `page_count` are omitted unless the client passes `?count=true` or `?page=` (avoids `countDocuments` on every list request).
+- **CORS** — origins read from `config.cors.origins` (default `["*"]` if unset).
+- **`/update/:model/:id`** — uses document load + `save()` (validators/hooks) instead of deprecated `Model.update()`.
+- **Delete** — referrer checks use a pre-built link index and run in parallel.
+- **`admin_only` middleware** — passes errors via `next(err)` for correct Restify handling.
+- **Mongoose 6.13.9** (pinned).
+- **Cache** — in-process [node-cache](https://www.npmjs.com/package/node-cache) *(replaces apicache from v2.6)*.
+- **CSV** — `@json2csv/plainjs` replaces `json2csv`.
+- **Email** — `nodemailer` 8.x; removed `nodemailer-smtp-transport`.
+- **Docs rendering** — `markdown-it`; MkDocs pages from `docs/*.md`.
+- **Tests** — Mocha 11; `test/env.js` loads `.env.test`; `test/security_hardening.test.js` for guards and allowlists.
+- **Documentation** — full MkDocs audit for v4 behavior; security notes in [api.md](api.md), [queries.md](queries.md), [aggregations.md](aggregations.md), [bulk_writes.md](bulk_writes.md), [caching.md](caching.md), [schemas.md](schemas.md), [special.md](special.md).
 
-- Websockets
-- Bulk uploads
-- Advanced queries
+### Fixed
 
-## v2.5.x
+- **`actionCallItem`** — `findById` is awaited; deleted documents are rejected; request body is passed to the static.
+- **`apiKeyAuth`** — missing `await` on `User.findOne` when resolving API key users.
+- **`middlewareModel`** — returns 404 when model name is unknown (no silent `undefined` model).
+- **Filter depth** — exceeding max depth returns 400 instead of passing raw input through.
 
-- Documentation system
+### Security hardening migration
 
-## 2.6.x
+Consumer apps (e.g. RevEngine) should adjust clients and models as follows:
 
-- Replace home-grown cache with apicache
-- Major performance boost when getting large collections (50secs to < 1 sec)
-- /setup/data endpoint for scaffolding a complete system
+| Area | Before | After |
+|------|--------|--------|
+| List GET / POST `/query` | Unbounded or large default on small collections | Default `?limit=100` when omitted; collections ≥10k docs still require explicit `?limit=` |
+| Totals in list JSON | `count` always present | Pass `?count=true` or `?page=` when you need `count` / `page_count` |
+| `/call/:model/:method` | Any schema static callable | Only names listed in `callable_statics` |
+| `/cache/stats`, `/cache/clear` | No auth | Admin login required |
+| `password_override=1` | Any authenticated user | Admin only |
+| User PUT | Could set `admin` / `password` | Non-admins have privilege fields stripped |
+| `?filter[$where]=…` | Accepted | **400** — operator denied |
+| POST `/aggregate` | Any pipeline stage | Allowlisted stages; `$out` / `$merge` / `$function` need admin |
+| POST `/bulkwrite` | Open | **Disabled per model** unless `advanced_queries.bulkwrite: true`; op allowlist |
+| List passwords | Could leak on `GET /api/user` | Stripped from list/query/aggregate responses |
 
-## 2.7.x
+Example model opts:
 
-- Permanent Delete
-- Cascade Delete
+```js
+new JXPSchema({ ... }, {
+  perms: { admin: "crud", user: "r" },
+  callable_statics: ["preview_segment", "apply_segment"],
+  advanced_queries: { bulkwrite: true }, // only if HTTP bulkwrite is required
+});
+```
+
+---
+
+## v3.1.0 — 2026-05-19
+
+- **Query limits for large collections** — `query_limits` config; `GET /api/<model>`, `GET /csv/<model>`, and `POST /query/<model>` require `?limit=` when collection size exceeds threshold (default 10,000 documents).
+- New `query_limits.js` module, tests, and API documentation.
+
+---
+
+## v3.0.0 — 2025-04-17
+
+Repository refresh and dependency modernization:
+
+- Better MongoDB connection handling.
+- Proper HTTP errors on login failure.
+- Additional request logging.
+- Package upgrades; Docker and ESLint scaffolding.
+
+### Patch-level (same era)
+
+- **2025-04-17** — Correct documentation for `x-api-key` header.
+- **2025-04-05** — Fix `deepExtend` bug.
+
+---
+
+## v2.15.0 — 2025-03-25
+
+- Fix potential stack size exceeded errors.
+- Fix documentation circular reference errors.
+- Dependency updates.
+- Date range handling improvements.
+
+---
+
+## v2.14.6 — 2024-01-24
+
+- Package upgrades.
+- Log Mongoose version on startup.
+
+## v2.14.5 — 2023-12-21
+
+- Maintenance release.
+
+## v2.14.4 — 2023-12-21
+
+- Dependency bumps.
+
+## v2.14.3 — 2023-12-21
+
+- `jxp-helper` version update.
+
+## v2.14.0 — 2023-02-27
+
+- **`.env` support** — environment-based configuration instructions and loading.
+- Link to external docs instead of inline documentation.
+- Repository moved to [WorkSpaceMan/jxp](https://github.com/WorkSpaceMan/jxp) (2023-07-10).
+- Dependency upgrades.
+
+### Caching (v2.14 era, 2023-01)
+
+- In-memory response caching with smarter invalidation.
+- Invalidate whole cache when links complicate partial invalidation.
+- Don't crash when cache object isn't configured.
+
+---
+
+## v2.12.3 — 2023-01-18
+
+- Dependency upgrades.
+- Require Mongoose as peer dependency.
+
+## v2.12.0 — 2022-12-05
+
+- Better error handling; server stays up on non-fatal errors.
+- Tests passing again.
+- Mongoose and Restify upgrades.
+- Default to `127.0.0.1` instead of `localhost`.
+- Show JXP version on load; reduce noisy logging.
+- `--legacy-peer-deps` note for source installs.
+
+## v2.11.0 — 2022-11-28
+
+- Pass `__user` on `get` and `getOne` actions.
+- Async/`next` fixes.
+- **Note:** Node versions above 17 were unsupported at this release.
+
+---
+
+## v2.7.0 — 2021-02-09
+
+- **Permanent delete** — `?_permaDelete=1`.
+- **Cascade delete** — `?_cascade=1`.
+- **`_updated_by_id`** set on PUT; populated as `_updated_by`.
+- Default `count` returns `-1` on very large collections (performance).
+- `/setup/data` casts `_id` fields to ObjectIds and sets `_deleted: false`.
+
+## v2.6.x — 2021-01-06
+
+- **apicache** replaces home-grown cache; configurable cache timeout.
+- Major **GET performance** improvement on large collections.
+- **Built-in documentation system** (MkDocs + in-server docs routes).
+- Default port changed to **4001** (conflict on M1 Macs).
+- Model docs refactored to separate library.
+- Dependency upgrades (including Axios security fix).
+- Return 404 for missing model.
+
+## v2.5.x — 2021-01-06
+
+- Documentation system introduced (see v2.6.x).
+
+## v2.4.x — 2020-07 – 2020-08
+
+- **WebSockets** — subscribe to model/item changes; auth via basic, apikey, or bearer token; filtering on subscriptions.
+- **Bulk writes** — `/bulkwrite/<model>` endpoint.
+- **`/query/<model>`** — POST advanced MongoDB queries.
+- **`/aggregate/<model>`** — aggregation pipelines; `allowDiskUse` query param; inline ObjectId and Date strings.
+- **`relative_date()`** in aggregation pipelines.
+- **`/count/<model>`** endpoint.
+- Populate `_owner_id` as `_owner`.
+- OAuth login uses renewable API keys (2022-01).
+
+## v2.0.x — 2020-05-06 – 2020-07
+
+Major v2 rewrite ([PR #11](https://github.com/WorkSpaceMan/jxp/pull/11)):
+
+- Renamed project to **JXP**; MongoDB **connection string** (Atlas-compatible).
+- **JXPSchema** — links, autopopulate, `ObjectId`/`Mixed` globals, automagic `_owner_id` / `_deleted`.
+- **Bearer tokens** and refresh tokens as preferred auth.
+- **Stored procedures** via `/call/<model>/<static>`.
+- **Hooks** — `pre_hooks` / `post_hooks` on server config.
+- Response shape `{ data }` for single records.
+- Setup scaffolding (`jxp-setup`), link model, soft delete.
+- Pre/post Mongoose middleware documented.
+- WebSocket support started (completed in v2.4).
+
+---
+
+## v1.x — 2016 – 2019
+
+### v1.2.4 — 2019-11-06
+
+- Time log includes operation number.
+
+### v1.2.3 — 2019-11-06
+
+- Request **throttling**.
+
+### v1.0.16 — 2019-05-02
+
+- **`POST /query/<model>`** for advanced queries.
+
+### v1.0.12 — 2019-04-03
+
+- Select individual fields in populate joins.
+
+### v1.0.1 — 2019-02-13
+
+- **Security:** only admins can assign user groups.
+
+### Earlier v1 highlights
+
+- **2019-03** — CSV export; async/await refactor; non-blocking bcrypt password checks; caching (early).
+- **2019-02** — Renamed to JXP; CORS plugin; Mongoose 5; full-text search.
+- **2018-12** — Soft delete (`_deleted`); `showDeleted`; refactor from Q to async/await; `bcryptjs`.
+- **2018-02** — Password field auto-encryption; config module.
+- **2017** — Setup endpoint; pre-hooks; `model_dir` (relative/absolute); field selection; groups.
+- **2016-05** — Initial release: REST CRUD from Mongoose models, auth, populate, filter, search, pagination, permissions, `jexpress-setup` CLI.
+
+---
+
+## Version notes
+
+| Era | Mongoose | Node (documented) |
+|-----|----------|-------------------|
+| v4 | 6.13.9 | 22+ |
+| v3.x | 6.x | — |
+| v2.11 | — | ≤17 (warning in release) |
+| v1 / early v2 | 5.x | — |
+
+See the [v4.0.0 release](https://github.com/WorkSpaceMan/jxp/releases/tag/v4.0.0) and [compare view since v3.1.0](https://github.com/WorkSpaceMan/jxp/compare/7224093...v4.0.0).

package/docs/configuration.md

@@ -1,162 +1,173 @@
-# Configuring JXP
+# Configuration
 
-## Connecting to MongoDB
+JXP 4 uses **environment variables** and [dotenv](https://github.com/motdotla/dotenv). Copy [`.env.sample`](../.env.sample) to `.env` and adjust values.
 
-JXP uses MongoDB for storage. You can use a local MongoDB instance, or a hosted one such as Mongo Atlas.
+_As of version 4, there is no `config` npm package and no `/config/*.json` hierarchy._
 
-The configuration for the MongoDB connection is set as environmental variables (for instance, if running in Docker), or in the `.env` file. Alternatively, you can set the connection string in the config file as described below, although this is not recommended.
+## MongoDB
+
+Set a full connection string:
+
+```
+MONGO_CONNECTION_STRING=mongodb://127.0.0.1:27017/myapp
+```
+
+Or build from parts (common in Docker):
 
 ```
 MONGODB_HOST=127.0.0.1
 MONGODB_PORT=27017
-MONGODB_NAME=jxp
+MONGODB_NAME=myapp
+MONGODB_USER=
+MONGODB_PASSWORD=
 MONGODB_AUTH_DB=admin
-MONGODB_USER=user
-MONGODB_PASS=pass
 ```
 
-## Config files
-
-The config files are stored in `/config` in strict JSON format. (Remember to enclose your keys in inverted commas!) Typically, you'd use `/config/default.json` for a simple configuration, or `/config/development.json` and `/config/production.json` for separating development and production. 
+Optional driver options as JSON:
 
-If you used the `jxp-setup` command for setting everything up, you should have a basic `/config/default.json` file ready to go.
+```
+MONGO_OPTIONS={"maxPoolSize":50}
+```
 
-JXP uses [config](https://www.npmjs.com/package/config) for configuration. This allows you to have different configuration files for development, staging and production, set config variables through [environmental variables](https://github.com/lorenwest/node-config/wiki/Environment-Variables) or [command line overrides](https://github.com/lorenwest/node-config/wiki/Command-Line-Overrides), and do lots of other cool config magic. 
+## Server
 
-## Port
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | HTTP port | `4001` |
+| `API_URL` / `API_SERVER` | Public base URL | `http://localhost:{PORT}` |
+| `MODEL_DIR` | Path to `*_model.js` files | `./dist/models` (sample server) |
+| `LOG_FILE` | Access log path | `access.log` |
+| `SHARED_SECRET` | JWT / recovery signing | — |
+| `TOKEN_EXPIRY` | Access token TTL (seconds) | `86400` |
+| `REFRESH_TOKEN_EXPIRY` | Refresh token TTL (seconds) | `2678400` |
+| `APIKEY` | Internal API key for schema helpers | — |
 
-The `port` key defines the port you want the server to run on. The default is `4001`.
-```json
-"port": 4001,
-```
+## API docs browser
 
-## Model Directory
+| `DOCS_ACCESS` | Behavior |
+|---------------|----------|
+| `protected` (default) | Home (`/`) and guides (`/docs/md/*`) are public; model explorer (`/docs/api`, `/docs/model/*`) requires sign-in |
+| `disabled` | Model explorer routes return 404 |
+| `public` | Model explorer open without sign-in |
 
-JXP will search for a model directory with "user_model.js" in it, else you can override this with the config parameter `model_dir`. (This should be an absolute directory.)
+Sign-in uses the normal `POST /login` endpoint (same credentials as the API). The docs UI then stores a session cookie via `POST /docs/session` and auto-fills the API key for “Try it” panels.
 
-## MongoDB
+| Variable | Description |
+|----------|-------------|
+| `DOCS_USER_EMAIL` | Optional email pre-fill on the docs sign-in form |
+| `DOCS_COOKIE_SECURE` | Set to `true` for `Secure` on the docs session cookie (HTTPS) |
 
-The `connection_string` can include port, username and password, options, and other fancy stuff. If you have advanced needs, you can find out more (here)[https://docs.mongodb.com/manual/reference/connection-string/].
+You can also set `docs: { access, user_email }` on the object passed to `JXP()`.
 
-If you use Atlas, it will give you a connection string that you can use as-is.
+## Login rate limiting
 
-The `options` allow you to pass extra options such as `poolSize`, `useNewUrlParser`, `useCreateIndex`, and `authSource`, amongst others. We use Mongoose's connection, so you can find out about the connection options (here)[https://mongoosejs.com/docs/connections.html]. Typically we only use `poolSize` and `authSource` in production, and no options in development.
+Enabled by default on `POST /login` and `POST /docs/session` (docs sign-in after login):
 
-A simple, local connection:
-```json
-"mongo": {
-    "connection_string": "mongodb://localhost/test",
-    "options": {}
-},
-```
-
-A Mongo Atlas connection:
-```json
-"mongo": {
-    "connection_string": "mongodb+srv://admin:<your password>@<your server>.gcp.mongodb.net/<your database>?retryWrites=true&w=majority",
-    "options": {
-            "readPreference": "nearest",
-            "poolSize": 20,
-            "authSource": "admin"
-    }
-},
-```
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOGIN_RATE_LIMIT_ENABLED` | `true` | Set `false` to disable |
+| `LOGIN_RATE_BURST` | `8` | Short burst of attempts per client |
+| `LOGIN_RATE_PER_MINUTE` | `12` | Sustained attempts per minute per client |
+| `LOGIN_RATE_LIMIT_XFF` | `false` | Use `X-Forwarded-For` when behind a reverse proxy |
 
-## Token lifespans
+Over-limit clients receive HTTP **429**. Response headers include rate-limit hints when supported by Restify.
 
-Set how long you want your users' tokens to live for. Defaults to 24 hours for a token and 30 days for a refresh token.
+## Cache
 
-```json
-"token_expiry": 86400,
-"refresh_token_expiry": 2678400
+```
+CACHE_ENABLED=true
+CACHE_DEBUG=false
+CACHE_TTL=300
 ```
 
-## Log
+When enabled, JXP uses an in-process cache ([node-cache](https://www.npmjs.com/package/node-cache)). GET responses may include `jxp-cache` (`hit` / `miss`) and `jxp-cache-key` headers. Admin endpoints (**require admin login**):
 
-You can define an access log as follows:
-```json
-"log": "/var/log/openmembers/access.log",
-```
+- `GET /cache/stats` — cache statistics, or `{ cache_enabled: false }` when disabled
+- `GET /cache/clear` — flush all cached entries
 
-## Memcached
+See [Caching](caching.md) for details.
 
-Memcached is entirely optional. Leave it out completely to not use Memcached.
+## Query limits
 
-```json
-"memcached": {
-    "server": "localhost:11211",
-    "lifetime": 604800
-},
+```
+QUERY_LIMITS_ENABLED=true
+QUERY_LIMITS_LARGE_COLLECTION_THRESHOLD=10000
+QUERY_LIMITS_MAX=1000
+QUERY_LIMITS_DEFAULT=100
+QUERY_LIMITS_SKIP_COUNT_UNLESS_PAGINATED=true
+CORS_ORIGINS=http://localhost:3000,http://localhost:4001
 ```
 
 ## Throttling
 
-You can throttle the API performance. In the following example, we offer 5 requests per second, 10 concurrent requests, throttle by IP, and allow clients from 192.168.1.1 to go crazy.
-```json
-"throttle": {
-    "burst": 10,
-    "rate": 5,
-    "ip": true,
-    "overrides": {
-        "192.168.1.1": {
-            "rate": 0,
-            "burst": 0
-        }
-    }
-}
-```
+Optional JSON blob:
 
-## Password recovery setup
+```
+THROTTLE_JSON={"burst":100,"rate":50,"ip":true}
+```
 
-We have a secret that we share with the front end in order to create Javascript Web Tokens as a login option. This would allow you to send a link to a client that would auto-log them in. We also use it for password recovery links. If you used `jxp-setup` it would have generated a random one for you.
+## Model directory
 
-We also configure a recovery url, which is a front-end page you'll want to hit, such as a password reset page.
+JXP discovers models by scanning `MODEL_DIR` for `*_model.js`. You can also pass `model_dir` in the object given to `JXP(apiconfig)`.
 
-We configure an SMTP connection to send out forgotten password links. 
+Relative `model_dir` paths resolve from `process.cwd()` (typical for npm scripts), not from the server script path.
 
-```json
-"shared_secret": "SomeRandomString",
-"password_recovery_url": "https://blah.com/login/reset",
-"smtp": {
-    "host": "smtp.gmail.com",
-    "port": 587,
-    "auth": {
-            "user": "blah@blah.com",
-            "pass": "blah"
-    },
-    "secureConnection": true
-},
-```
+## Programmatic config
 
-## oAuth
+Apps typically build an options object and pass it to `JXP()`:
 
-If you want users to be able to log in with an oAuth 2 provider, such as Google or Facebook, you would set it up as follows.
+```javascript
+const JXP = require("jxp");
+const server = JXP({
+  port: 4001,
+  mongo: { connection_string: process.env.MONGO_CONNECTION_STRING },
+  model_dir: "./models",
+  pre_hooks: { get: (req, res, next) => next() },
+});
+```
 
-We have a `success_uri` and `fail_uri` that will direct the user to your front end's success and failure page, respectively.
+The sample JXP server uses `loadJxpConfig()` from `jxp/libs/load-config` (resolved via `package.json` `exports` to compiled `dist/libs/load-config.js`) to build the same shape from `.env`.
 
-Then, for each service you'd like to support, define the `app_id`, `app_secret`, `scope`, `auth_uri`, `token_uri` and `api_uri`.
+### SMTP and password recovery
 
-Here are some examples. We used to support LinkedIn but they made some weird decisions that effectively broke their oAuth2 support. 
+SMTP and password-recovery URLs are **not** read from environment variables by `loadJxpConfig()`. Pass them on the `JXP()` options object:
 
+```javascript
+JXP({
+  smtp_server: "mail.example.com",
+  smtp_username: "user",
+  smtp_password: "secret",
+  smtp_from: "noreply@example.com",
+  password_recovery_url: "https://myapp.example.com/reset",
+});
 ```
-"oauth": {
-    "success_uri": "https://my.workshop17.co.za/login/oauth",
-    "fail_uri": "https://my.workshop17.co.za/login/oauth/fail",
-    "facebook": {
-        "app_id": "<your app id>",
-        "app_secret": "<your app secret>",
-        "scope": "email",
-        "auth_uri": "https://www.facebook.com/dialog/oauth",
-        "token_uri": "https://graph.facebook.com/v2.3/oauth/access_token",
-        "api_uri": "https://graph.facebook.com/me?fields=id,name,about,age_range,email,picture"
+
+Used by `POST /login/recover` (see [Authentication](authentication.md)).
+
+### OAuth
+
+OAuth2 providers are configured programmatically on the `oauth` key:
+
+```javascript
+JXP({
+  url: "http://localhost:4001",
+  oauth: {
+    success_uri: "https://myapp.example.com/oauth/success",
+    fail_uri: "https://myapp.example.com/oauth/fail",
+    google: {
+      auth_uri: "https://accounts.google.com/o/oauth2/v2/auth",
+      token_uri: "https://oauth2.googleapis.com/token",
+      api_uri: "https://www.googleapis.com/oauth2/v2/userinfo",
+      app_id: "...",
+      app_secret: "...",
+      scope: "email profile",
     },
-    "google": {
-        "app_id": "<your app id>",
-        "app_secret": "<your app secret>",
-        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
-        "scope": "email+profile",
-        "api_uri": "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
-        "token_uri": "https://www.googleapis.com/oauth2/v3/token"
-    }
-},
-```
+  },
+});
+```
+
+Routes: `GET /login/oauth/:provider` and `GET /login/oauth/callback/:provider`. See [Authentication](authentication.md).
+
+## Tests
+
+Tests load `.env.test` via `test/env.js` (see `npm test`). Set `NODE_ENV=test` and `MONGO_CONNECTION_STRING` for your local Mongo instance.

package/docs/hooks.md

@@ -1,8 +1,8 @@
 # Hooks
 
-In `/bin/server.js` you will find some pre-operation hooks. These will run after `auth` but before the operation. 
+In your app's server bootstrap (eg. `dist/bin/server.js` compiled from `src/bin/server.ts`), configure `pre_hooks` and `post_hooks` on the object passed to `JXP()`. These run after authentication but before (or after, for post-hooks) the operation.
 
-We've used callbacks to add parameters on `get` and `getOne` to our queries to limit what certain users see in the results. We've also use the `post`, `put` and `delete` to fire emits on an external Websocket server.
+We've used pre-hooks on `get` and `getOne` to add query constraints so certain users only see allowed rows. We've also used `post`, `put`, and `delete` hooks alongside JXP's built-in WebSocket emitter to notify subscribed clients of changes.
 
 ```javascript
 config.pre_hooks = {
@@ -21,19 +21,23 @@ config.pre_hooks = {
 	put: (req, res, next) => {
 		next();
 	},
+	update: (req, res, next) => {
+		next();
+	},
 	delete: (req, res, next) => {
 		next();
 	},
 };
 ```
 
-For _login_ there's also a post-hook, eg. if you need to inject more information into the login result.
+For _login_ there is also a post-hook if you need to inject more information into the login result:
 
 ```javascript
-config.post_hooks = (req, res, next) => {
-	res.result.some_field = "Some Value";
-	next();
-}
+config.post_hooks = {
+	login: (req, res) => {
+		res.result.some_field = "Some Value";
+	},
+};
 ```
 
-To suppress a callback, pass `_silence=true` as a parameter. This helps avoid infinite loops, for instance when your PUT updates the same model.
+To suppress model callbacks (eg. to avoid infinite loops when a PUT updates the same model), pass `_silence=true` as a query parameter or in the request body.