json-rest-api 1.0.23 → 1.0.25

package/README.md

@@ -9,7 +9,8 @@ A powerful REST API plugin for [hooked-api](https://github.com/mobily-enterprise
 * **JSON:API Compliant** - Full support for the JSON:API specification
 * **Relationship Support** - `belongsTo`, `hasMany`, and many-to-many relationships, including polymorphic
 * **Advanced Querying** - Filtering, sorting, pagination, and field selection (sparse fieldsets)
-* **File Uploads** - Built-in support for file handling with multiple storage adapters (local, S3)
+* **Server-Side Row Policies** - Apply mandatory visibility rules before pagination, counts, and relationship loading
+* **File Uploads** - Built-in support for file handling with local storage and a mock S3-style demo adapter
 * **Framework Agnostic** - Works with raw Node.js HTTP, Express, and other Node.js frameworks via flexible connectors
 * **Validation** - Schema-based validation with detailed error messages and custom rules
 * **Simplified Mode** - A developer-friendly option to work with plain JavaScript objects instead of verbose JSON:API structure
@@ -72,4 +73,25 @@ app.listen(3000, () => {
 - [Quick Start](QUICKSTART.md) - Quick start
 - [Complete guide](GUIDE/) - Comprehensive guide
 - [API Reference](API.md) - API reference
-- [Why json-rest-api?](docs/COMPARISON.md) - Step-by-step tutorial
+- [Why json-rest-api?](docs/COMPARISON.md) - Step-by-step tutorial
+
+## Development
+
+```bash
+# Run the normalizeId contract suites under the default backend and AnyAPI,
+# then rebuild the checked-in docs site
+npm run verify
+
+# Run lint separately
+npm run lint
+
+# Run the focused normalizeId suites directly
+npm run test:id-contracts
+npm run test:id-contracts:anyapi
+
+# Rebuild the checked-in docs site
+npm run docs
+
+# Serve the docs locally with live rebuild
+npm run docs:dev
+```

package/docs/API.md

@@ -14,6 +14,8 @@ This reference provides comprehensive documentation for all methods, parameters,
 
 4. **All parameters must be passed within a single params object** as the first argument to each method.
 
+5. **Simplified shorthand is payload-only**: when you pass attributes directly (for example, `post({ title: 'Hello' })`), that plain object is treated as the resource payload. If you also need per-call options such as `transaction`, `queryParams`, `simplified`, or `returnFullRecord`, put the record under `inputRecord` and keep those options at the top level of `params`.
+
 ## Table of Contents
 
 1. [Core API Methods](#core-api-methods)
@@ -291,6 +293,8 @@ const result = await api.resources.[resourceType].get(params, context)
 | `simplified` | Boolean | No | Override simplified mode setting (default: true) |
 | `transaction` | Object | No | Database transaction object |
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 **JSON:API Mode (simplified: false):**
@@ -423,21 +427,25 @@ const result = await api.resources.[resourceType].post(params, context)
   },
   simplified: Boolean,      // Override simplified mode (default: true for API)
   transaction: Object,      // Database transaction object
-  returnFullRecord: String  // Override return setting ('no', 'minimal', 'full')
+  returnFullRecord: String|Boolean  // Override return setting ('no', 'minimal', 'full')
 }
 ```
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `inputRecord` | Object | Yes | Resource data to create |
+| `inputRecord.id` | String | No (simplified) | Optional explicit logical resource ID |
 | `inputRecord.data` | Object | Yes (JSON:API) | Resource data container |
+| `inputRecord.data.id` | String | No (JSON:API) | Optional explicit logical resource ID |
 | `inputRecord.data.type` | String | Yes (JSON:API) | Resource type |
 | `inputRecord.data.attributes` | Object | Yes (JSON:API) | Resource attributes |
 | `inputRecord.data.relationships` | Object | No | Related resources |
 | `queryParams` | Object | No | For includes/fields in response |
 | `simplified` | Boolean | No | Override simplified mode (default: true) |
 | `transaction` | Object | No | Database transaction object |
-| `returnFullRecord` | String | No | Override return setting ('no', 'minimal', 'full') |
+| `returnFullRecord` | String\|Boolean | No | Override return setting (`'no'`, `'minimal'`, `'full'`; legacy `true` = `'full'`, `false` = `'no'`) |
+
+When an explicit resource id is provided, `normalizeId` runs before persistence and before any follow-up record fetch used for the return payload. If the normalized id is empty, the request fails as `REST_API_VALIDATION` on `data.id`.
 
 #### Return Value Behavior
 
@@ -452,6 +460,8 @@ The return value depends on `returnFullRecord` setting and whether it's an API o
 - `'minimal'`: Returns resource with ID only
 - `'full'`: Returns complete resource with all fields
 
+Boolean values are accepted for backward compatibility: `true` is normalized to `'full'` and `false` is normalized to `'no'`. New code should use the string values.
+
 #### HTTP Equivalent
 
 ```http
@@ -515,6 +525,25 @@ const result = await api.resources.articles.post({
 });
 ```
 
+**Create with Explicit ID and Normalization:**
+```javascript
+// With normalizeId configured to trim and uppercase ids,
+// this record is stored as ARTICLE-42
+const result = await api.resources.articles.post({
+  inputRecord: {
+    data: {
+      type: 'articles',
+      id: '  article-42  ',
+      attributes: {
+        title: 'Canonical ID Example',
+        content: 'Stored under the normalized id'
+      }
+    }
+  },
+  simplified: false
+});
+```
+
 **Create with Multiple Relationships:**
 ```javascript
 // Create article with author and tags (simplified)
@@ -584,22 +613,26 @@ const result = await api.resources.[resourceType].put(params, context)
   },
   simplified: Boolean,      // Override simplified mode (default: true for API)
   transaction: Object,      // Database transaction object
-  returnFullRecord: String  // Override return setting ('no', 'minimal', 'full')
+  returnFullRecord: String|Boolean  // Override return setting ('no', 'minimal', 'full')
 }
 ```
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `inputRecord` | Object | Yes | Complete resource data |
-| `inputRecord.id` | String | Yes (simplified) | Resource ID |
-| `inputRecord.data.id` | String | Yes (JSON:API) | Must match the resource ID |
+| `inputRecord.id` | String | Yes (simplified) | Logical resource ID |
+| `inputRecord.data.id` | String | Yes (JSON:API) | Logical resource ID |
 | `inputRecord.data.type` | String | Yes (JSON:API) | Resource type |
 | `inputRecord.data.attributes` | Object | Yes (JSON:API) | All resource attributes |
 | `inputRecord.data.relationships` | Object | No | All relationships (missing ones are nulled) |
 | `queryParams` | Object | No | For response formatting |
 | `simplified` | Boolean | No | Override simplified mode (default: true) |
 | `transaction` | Object | No | Database transaction object |
-| `returnFullRecord` | String | No | Override return setting |
+| `returnFullRecord` | String\|Boolean | No | Override return setting (`'no'`, `'minimal'`, `'full'`; legacy `true` = `'full'`, `false` = `'no'`) |
+
+`inputRecord.id` and `inputRecord.data.id` always refer to the logical resource id. `idProperty` and storage mapping affect the backing column name, not the API field name, and the resource id is not part of `attributes`.
+
+If both the URL id and body id are present, both are normalized before the equality check. If either id normalizes to an empty value, the operation fails before storage is touched.
 
 #### Return Value
 
@@ -711,22 +744,24 @@ const result = await api.resources.[resourceType].patch(params, context)
   },
   simplified: Boolean,      // Override simplified mode (default: true for API)
   transaction: Object,      // Database transaction object
-  returnFullRecord: String  // Override return setting ('no', 'minimal', 'full')
+  returnFullRecord: String|Boolean  // Override return setting ('no', 'minimal', 'full')
 }
 ```
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `inputRecord` | Object | Yes | Partial resource data |
-| `inputRecord.id` | String | Yes (simplified) | Resource ID |
-| `inputRecord.data.id` | String | Yes (JSON:API) | Resource ID |
+| `inputRecord.id` | String | Yes (simplified) | Logical resource ID |
+| `inputRecord.data.id` | String | Yes (JSON:API) | Logical resource ID |
 | `inputRecord.data.type` | String | Yes (JSON:API) | Resource type |
 | `inputRecord.data.attributes` | Object | No | Attributes to update |
 | `inputRecord.data.relationships` | Object | No | Relationships to update |
 | `queryParams` | Object | No | For response formatting |
 | `simplified` | Boolean | No | Override simplified mode (default: true) |
 | `transaction` | Object | No | Database transaction object |
-| `returnFullRecord` | String | No | Override return setting |
+| `returnFullRecord` | String\|Boolean | No | Override return setting (`'no'`, `'minimal'`, `'full'`; legacy `true` = `'full'`, `false` = `'no'`) |
+
+If both the URL id and body id are present, both are normalized before the equality check. If either id normalizes to an empty value, the operation fails before storage is touched.
 
 #### Return Value
 
@@ -849,6 +884,8 @@ const result = await api.resources.[resourceType].delete(params, context)
 | `id` | String\|Number | Yes | ID of resource to delete |
 | `transaction` | Object | No | Database transaction object |
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -935,6 +972,8 @@ const result = await api.resources.[resourceType].getRelated(params, context)
 | `queryParams` | Object | No | Standard query parameters for related resources |
 | `transaction` | Object | No | Database transaction object |
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 JSON:API response with related resources (supports all query features like filtering, pagination, etc.)
@@ -1007,6 +1046,8 @@ const result = await api.resources.[resourceType].getRelationship(params, contex
 }
 ```
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 JSON:API relationship document with resource identifiers only
@@ -1081,6 +1122,8 @@ const result = await api.resources.[resourceType].postRelationship(params, conte
 }
 ```
 
+The parent `id` is normalized with the parent resource's normalizer. Each `relationshipData[*].id` is normalized with the related target resource's normalizer before validation and persistence.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -1116,6 +1159,8 @@ await api.resources.articles.postRelationship({
 // Existing tags remain, new tags are added
 ```
 
+If `normalizeId` is configured, both the parent id and each relationship identifier are normalized before the relationship is written.
+
 ---
 
 ### patchRelationship - Replace Relationship
@@ -1138,6 +1183,8 @@ const result = await api.resources.[resourceType].patchRelationship(params, cont
 }
 ```
 
+The parent `id` is normalized with the parent resource's normalizer. Each relationship identifier inside `relationshipData` is normalized with the related target resource's normalizer before validation and persistence.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -1219,6 +1266,8 @@ const result = await api.resources.[resourceType].deleteRelationship(params, con
 }
 ```
 
+The parent `id` is normalized with the parent resource's normalizer. Each `relationshipData[*].id` is normalized with the related target resource's normalizer before validation and persistence.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -1268,7 +1317,7 @@ Each API method has its own specific hook execution order. Here's the exact sequ
 ```
 1. beforeData
 2. beforeDataQuery
-3. knexQueryFiltering (multiple times for different filter types)
+3. knexQueryFiltering (multiple handlers for built-in filters and optional server-side policies)
    - polymorphicFiltersHook
    - crossTableFiltersHook
    - basicFiltersHook
@@ -1403,7 +1452,7 @@ Each API method has its own specific hook execution order. Here's the exact sequ
 1. **Processing Hooks**: Only POST, PUT, and PATCH have `beforeProcessing` hooks
 2. **Schema Validation**: Only POST, PUT, and PATCH have schema validation hooks
 3. **Permission Hooks**: GET uses `checkDataPermissions`, while relationship methods use `checkPermissions`
-4. **Query Filtering**: Only QUERY method triggers `knexQueryFiltering` hooks
+4. **Query Filtering**: Collection queries and storage-backed scoped lookups trigger `knexQueryFiltering`; use `RowPolicyPlugin` for mandatory visibility rather than relying on method-specific hook assumptions
 5. **Enrichment**: Only GET and QUERY have `enrichRecord` hooks
 6. **Relationships**: Only GET has `enrichRecordWithRelationships`
 7. **Transactions**: All write methods (POST, PUT, PATCH, DELETE) can trigger `afterCommit`/`afterRollback`
@@ -2075,24 +2124,30 @@ api.resource('articles').hook('afterDataQuery', async (context) => {
 ### Plugin Configuration
 
 ```javascript
-const restApiPlugin = new RestApiPlugin({
+await api.use(RestApiPlugin, {
   // API behavior
   simplifiedApi: true,              // Use simplified mode for programmatic calls (default: true)
   simplifiedTransport: false,       // Use JSON:API for HTTP transport (default: false)
+  normalizeId: (value) => {
+    if (value === null || value === undefined) {
+      return null
+    }
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toUpperCase() : null
+  },
   
   // Return record configuration
   returnRecordApi: {
     post: 'full',                   // Return full record after create (default)
     put: 'full',                    // Return full record after replace (default)
-    patch: 'full',                  // Return full record after update (default)
-    delete: 'no'                    // Return nothing after delete (default)
+    patch: 'full'                   // Return full record after update (default)
   },
   
   returnRecordTransport: {
     post: 'no',                     // Return 204 for HTTP POST (default)
     put: 'no',                      // Return 204 for HTTP PUT (default)
-    patch: 'no',                    // Return 204 for HTTP PATCH (default)
-    delete: 'no'                    // Return 204 for HTTP DELETE (default)
+    patch: 'no'                     // Return 204 for HTTP PATCH (default)
   },
   
   // Query limits
@@ -2103,15 +2158,7 @@ const restApiPlugin = new RestApiPlugin({
   includeDepthLimit: 3,             // Maximum relationship nesting depth
   
   // Performance
-  enablePaginationCounts: true,     // Execute count queries for total pages
-  
-  // Error handling
-  exposeErrors: false,              // Include error details in responses
-  
-  // Custom serializers
-  serializers: {
-    articles: customArticleSerializer
-  }
+  enablePaginationCounts: true      // Execute count queries for total pages
 });
 ```
 
@@ -2126,7 +2173,7 @@ api.addResource({
   name: 'articles',
   
   // Primary key configuration
-  idProperty: 'id',                 // Custom primary key field (default: 'id')
+  idProperty: 'id',                 // Physical primary-key column name for table-backed resources
   
   schema: {
     // Attributes
@@ -2247,7 +2294,8 @@ api.addResource({
     
     // No built-in permissions option exists here.
     // Use permission hooks for access decisions, and optional plugins
-    // such as AutoFilterPlugin for dataset scoping.
+    // such as AutoFilterPlugin for equality-based dataset scoping or
+    // RowPolicyPlugin for mandatory SQL visibility predicates.
     
     // Soft delete configuration
     softDelete: {
@@ -2273,19 +2321,95 @@ api.addResource({
 
 #### ID Property Configuration
 ```javascript
-// Custom primary key
+// Physical primary key column: user_id
 api.addResource({
   name: 'users',
-  idProperty: 'user_id',  // Use 'user_id' instead of 'id'
+  idProperty: 'user_id',
   schema: {
-    attributes: {
-      user_id: { type: 'number', required: true },
-      email: { type: 'string', required: true }
+    id: { type: 'id', required: true, storage: { column: 'user_id' } },
+    email: { type: 'string', required: true },
+    displayName: { type: 'string' }
+  }
+});
+```
+
+`idProperty` names the physical primary-key column for table-backed resources. At the API layer, the resource id remains `id`, so writes use `inputRecord.id` or `inputRecord.data.id`, reads return `id` or `data.id`, and the resource id is not part of `attributes`.
+
+#### Resource ID Normalization
+
+`normalizeId` canonicalizes resource identifiers before the library reads, writes, validates, or links records.
+
+The default normalizer:
+
+- trims surrounding whitespace from strings
+- converts finite numbers and bigints to strings
+- rejects values that normalize to an empty identifier
+
+Provide a custom normalizer when your ids need additional canonicalization:
+
+```javascript
+await api.use(RestApiPlugin, {
+  normalizeId: (value) => {
+    if (value === null || value === undefined) {
+      return null
     }
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toUpperCase() : null
+  }
+});
+```
+
+Resource-level overrides take precedence over the plugin-level default:
+
+```javascript
+await api.addResource('countries', {
+  normalizeId: (value) => {
+    if (value === null || value === undefined) {
+      return null
+    }
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toLowerCase() : null
+  },
+  schema: {
+    name: { type: 'string', required: true }
+  }
+});
+```
+
+Normalization is applied to:
+
+- parent ids used by `get`, `put`, `patch`, `delete`, `getRelated`, and `getRelationship`
+- explicit `POST`, `PUT`, and `PATCH` document ids
+- relationship identifiers used by `postRelationship`, `patchRelationship`, and `deleteRelationship`
+
+Relationship identifiers use the normalizer of the related target resource, not the parent resource.
+
+If an id normalizes to an empty value:
+
+- existing-resource operations fail as `REST_API_RESOURCE` with subtype `not_found`
+- explicit `POST` document ids fail as `REST_API_VALIDATION` on `data.id`
+
+#### Storage Column Naming
+
+Table-backed resources use snake_case physical columns by default. For example, `displayName` maps to `display_name`.
+
+Use `storage.column` when a field needs a specific column name:
+
+```javascript
+api.addResource({
+  name: 'profiles',
+  schema: {
+    id: { type: 'id' },
+    displayName: { type: 'string', required: true },
+    legacyRef: { type: 'string', storage: { column: 'legacy_profile_ref' } }
   }
 });
 ```
 
+If physical columns should match logical field names exactly for an entire resource, use `storage: { naming: 'exact' }`.
+
 #### Virtual Fields
 Virtual fields are excluded from database operations but can be used for temporary UI state:
 

package/docs/GUIDE/GUIDE_1_Initial_Setup.md

@@ -242,7 +242,7 @@ console.log('Refetched Country:', inspect(countryUsRefetched));
 // }
 ```
 
-(Note that the full JSON:API record includes links to resources, which are automatically generated based on the request headers.)
+(Note that the full JSON:API record includes links to resources, which are generated from explicit URL configuration such as the connector `mountPath` or `publicBaseUrl`.)
 
 As you can see, when `simplified: false` is used:
 
@@ -325,6 +325,8 @@ const result = await api.resources.countries.post({
 });
 ```
 
+If you need per-call options such as `transaction`, `returnFullRecord`, or `queryParams`, move the record under `inputRecord` and keep those options at the top level of the params object.
+
 By default, `simplifiedApi` is `true` for programmatic usage, making it easier to work with the API in your code while still maintaining full JSON:API compliance internally.
 
 #### API usage and returning records
@@ -338,11 +340,13 @@ There are TWO separate settings for this:
 
 This separation allows you to have different behaviors for internal API usage versus external HTTP clients. For example, your internal code might want full records for convenience, while HTTP clients might prefer minimal responses for performance.
 
-Both settings accept three string values:
+Both settings prefer three string values:
 - **`'full'`**: Returns the complete record with all attributes, relationships, computed fields, and links
 - **`'minimal'`**: Returns only the resource type and ID
 - **`'no'`**: Returns nothing (undefined in programmatic calls, 204 No Content in HTTP)
 
+Boolean values are accepted for backward compatibility: `true` is normalized to `'full'` and `false` is normalized to `'no'`. New code should use the string values.
+
 Here's how these settings work:
 
 ```javascript
@@ -778,6 +782,7 @@ Here is a full list of parameters and their respective variables:
 | `simplifiedApi` | `vars.simplifiedApi` | `true` | Use simplified format for programmatic API calls | ✓ |
 | `simplifiedTransport` | `vars.simplifiedTransport` | `false` | Use simplified format for HTTP/REST endpoints | ✓ |
 | `idProperty` | `vars.idProperty` | `'id'` | Name of the ID field in resources | ✓ |
+| `normalizeId` | `vars.normalizeId` | trim strings, stringify finite numbers | Normalize resource identifiers before lookups and writes | ✓ |
 | `returnRecordApi` | `vars.returnRecordApi` | `{ post: 'full', put: 'full', patch: 'full' }` | What to return for programmatic API write operations | ✓ |
 | `returnRecordTransport` | `vars.returnRecordTransport` | `{ post: 'no', put: 'no', patch: 'no' }` | What to return for HTTP/REST write operations | ✓ |
 
@@ -793,11 +798,82 @@ Here is a full list of parameters and their respective variables:
 - `returnRecordApi` and `returnRecordTransport` can be either:
   - A string: `'no'`, `'minimal'`, or `'full'` (applies to all methods)
   - An object: `{ post: 'full', put: 'minimal', patch: 'no' }` (per-method configuration)
+  - Legacy booleans: `true` is treated as `'full'`, `false` as `'no'`
 - All parameters support the cascade: per-call → resource-level → plugin-level default
 
-# Custom ID parameter
+# Logical IDs and Physical Columns
+
+For table-backed resources, `idProperty` defines the physical primary-key column. The API surface still uses the logical resource id.
+
+- simplified writes use `inputRecord.id`
+- JSON:API writes use `inputRecord.data.id`
+- responses expose `id` or `data.id`
+- the resource id is not part of `attributes`
+
+```javascript
+await api.addResource('profiles', {
+  idProperty: 'user_id',
+  schema: {
+    id: { type: 'id', required: true, storage: { column: 'user_id' } },
+    displayName: { type: 'string', required: true },
+    loginCount: { type: 'number', defaultTo: 0 }
+  },
+  tableName: 'profiles'
+});
+```
+
+For table-backed resources, storage columns default to snake_case, so `displayName` maps to `display_name` and `loginCount` maps to `login_count`. Use `storage.column` for a per-field override, or `storage: { naming: 'exact' }` when physical column names should match logical field names exactly.
+
+## ID normalization
+
+`normalizeId` lets you canonicalize resource identifiers before the library reads, writes, validates, or links records.
+
+The default normalizer already handles the common cases:
+
+- trims surrounding whitespace from strings
+- converts finite numbers and bigints to strings
+- rejects values that normalize to an empty identifier
+
+You only need to provide `normalizeId` when your resource ids need additional canonicalization, such as uppercasing, lowercasing, or removing formatting characters.
+
+```javascript
+await api.use(RestApiPlugin, {
+  normalizeId: (value) => {
+    if (value === null || value === undefined) return null
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toUpperCase() : null
+  }
+})
+
+await api.addResource('countries', {
+  // Override the plugin-wide normalizer for this one resource
+  normalizeId: (value) => {
+    if (value === null || value === undefined) return null
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toLowerCase() : null
+  },
+  schema: {
+    name: { type: 'string', required: true }
+  }
+})
+```
+
+Normalization is applied consistently to:
+
+- `get`, `put`, `patch`, `delete`, `getRelated`, and `getRelationship` parent ids
+- explicit resource ids in `POST`, `PUT`, and `PATCH` documents
+- relationship identifiers supplied to `postRelationship`, `patchRelationship`, and `deleteRelationship`
+
+The resource-level `normalizeId` override also applies to relationship identifiers when that resource appears as the related target.
+
+If an id normalizes to an empty value:
+
+- existing-resource operations behave as `not_found`
+- explicit `POST` document ids are rejected as validation errors on `data.id`
 
-TODO: Explain how idParam works, clarify that for the api it's always 'id' and there is no ID in the attributes
+For full examples of table creation, physical column naming, and migration generation, see [Knex Schema and Migrations](GUIDE_X_Knex_Schema_And_Migrations.md).
 
 # Helpers and Methods Provided by REST API Plugins
 
@@ -828,8 +904,14 @@ When you install the REST API plugins, the following helpers are added to `api.h
   const trx = await api.helpers.newTransaction();
   try {
     // Use transaction in multiple operations
-    await api.resources.countries.post({ name: 'France', code: 'FR' }, { transaction: trx });
-    await api.resources.publishers.post({ name: 'French Press', country: 1 }, { transaction: trx });
+    await api.resources.countries.post({
+      inputRecord: { name: 'France', code: 'FR' },
+      transaction: trx
+    });
+    await api.resources.publishers.post({
+      inputRecord: { name: 'French Press', country: 1 },
+      transaction: trx
+    });
     await trx.commit();
   } catch (error) {
     await trx.rollback();

package/docs/GUIDE/GUIDE_2_1_The_Starting_Point.md

@@ -23,9 +23,9 @@ const knex = knexLib({
 const api = new Api({ name: 'book-catalog-api' });
 
 // Install plugins
-await api.use(RestApiPlugin); // URLs auto-detected from request headers
+await api.use(RestApiPlugin);
 await api.use(RestApiKnexPlugin, { knex });
-await api.use(ExpressPlugin, {  mountPath: '/api' }); // Added: Express Plugin
+await api.use(ExpressPlugin, { mountPath: '/api' }); // Links are generated under /api
 
 /// *** ...programmatic calls here... ***
 
@@ -85,4 +85,4 @@ This design provides the best of both worlds: backend developers get full databa
 
 ---
 
-[Back to Guide](./README.md) | [Next: 2.2 Manipulating and searching tables with no relationships](./GUIDE_2_2_Manipulating_And_Searching_Tables.md)
+[Back to Guide](./README.md) | [Next: 2.2 Manipulating and searching tables with no relationships](./GUIDE_2_2_Manipulating_And_Searching_Tables.md)

package/docs/GUIDE/GUIDE_3_Field_Transformations.md

@@ -132,6 +132,8 @@ await api.addResource('users', {
 });
 ```
 
+If a setter throws or rejects, the write fails with a validation error and the transaction rolls back instead of storing the untransformed value.
+
 ### Getters - Transform After Retrieval
 
 ```javascript

package/docs/GUIDE/GUIDE_7_Hooks_Data_Management_And_Plugins.md

@@ -1186,7 +1186,7 @@ api.addScope('articles', {}, {
 
 ### knexQueryFiltering
 
-The `knexQueryFiltering` hook is called during QUERY operations to apply filter conditions. This is a special hook that allows complex query modifications.
+The `knexQueryFiltering` hook is called while storage-backed resource selections are being built. Collection queries run it before sorting and pagination; scoped lookup and relationship paths can also run it. This is a special hook that allows complex query modifications. Use the supported [Row Policies](GUIDE_X_Row_Policies.md) contract for mandatory resource visibility.
 
 **When**: During `dataQuery` execution, before sorting and pagination  
 **Purpose**: Apply filters, add JOINs, modify query conditions