meadow-endpoints 4.0.5 → 4.0.9

package/docs/crud/count.md

@@ -0,0 +1,168 @@
+# Count Endpoints
+
+> Aggregate record counts with filtering
+
+The Count endpoints return the number of records matching given criteria. They support the same filter expressions as the Read endpoints and provide field-specific counting via the CountBy variant.
+
+## Routes
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{v}/{entity}/s/Count` | Total record count |
+| GET | `/{v}/{entity}/s/Count/FilteredTo/:Filter` | Filtered record count |
+| GET | `/{v}/{entity}/s/Count/By/:ByField/:ByValue` | Count by field value |
+
+## Count
+
+**Request:** `GET /1.0/Book/s/Count`
+
+**Response:**
+
+```json
+{
+	"Count": 157
+}
+```
+
+### Filtered Count
+
+**Request:** `GET /1.0/Book/s/Count/FilteredTo/Author~Herbert`
+
+**Response:**
+
+```json
+{
+	"Count": 12
+}
+```
+
+## CountBy
+
+**Request:** `GET /1.0/Book/s/Count/By/Author/Frank Herbert`
+
+**Response:**
+
+```json
+{
+	"Count": 6
+}
+```
+
+## Count Request Lifecycle
+
+```
+GET /{v}/{entity}/s/Count
+  |
+  v
+Build query, parse filter expression (if FilteredTo)
+  |
+  v
+[Count-QueryConfiguration]          <-- add security filters
+  |
+  v
+DAL.doCount(query)
+  |
+  v
+Send response ({Count: N})
+```
+
+## CountBy Request Lifecycle
+
+```
+GET /{v}/{entity}/s/Count/By/:ByField/:ByValue
+  |
+  v
+Build query, add field = value filter
+  |
+  v
+[CountBy-QueryConfiguration]        <-- add security filters
+  |
+  v
+DAL.doCount(query)
+  |
+  v
+Send response ({Count: N})
+```
+
+## Behavior Injection Points
+
+### Count-QueryConfiguration
+
+Runs after any filter expression is parsed and applied, but before the DAL count executes. Use this to add security filters so counts reflect only the records the user has access to.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Count-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Multi-tenant security: restrict count to user's customer
+		if (pRequestState.SessionData.UserRoleIndex < 5)
+		{
+			pRequestState.Query.addFilter('IDCustomer',
+				pRequestState.SessionData.CustomerID);
+		}
+		return fCallback();
+	});
+```
+
+### CountBy-QueryConfiguration
+
+Runs after the field value filter is applied on CountBy requests. Operates the same as `Count-QueryConfiguration` but is specific to the `CountBy` endpoint, allowing different behavior for field-specific counts.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('CountBy-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Add tenant filter for CountBy as well
+		pRequestState.Query.addFilter('IDCustomer',
+			pRequestState.SessionData.CustomerID);
+
+		// Log which field is being counted
+		_Fable.log.info(`CountBy: ${pRequest.params.ByField} = ${pRequest.params.ByValue}`);
+
+		return fCallback();
+	});
+```
+
+## Filter Expressions
+
+Count supports the same filter syntax as Read endpoints:
+
+```
+GET /1.0/Book/s/Count/FilteredTo/Author~Herbert
+GET /1.0/Book/s/Count/FilteredTo/PublishYear>2000
+GET /1.0/Book/s/Count/FilteredTo/Author~Herbert;PublishYear>2000
+```
+
+| Operator | Meaning |
+|----------|---------|
+| `=` | Equals |
+| `!=` | Not equals |
+| `>` | Greater than |
+| `<` | Less than |
+| `>=` | Greater than or equal |
+| `<=` | Less than or equal |
+| `~` | Contains (LIKE) |
+
+## Real-World Example: Dashboard Metrics
+
+```javascript
+// Set up security filtering for count operations
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Count-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Non-admin users only see their customer's records
+		if (pRequestState.SessionData.UserRoleIndex < 5)
+		{
+			pRequestState.Query.addFilter('IDCustomer',
+				pRequestState.SessionData.CustomerID);
+		}
+		return fCallback();
+	});
+
+// The frontend can then call:
+//   GET /1.0/Book/s/Count                          -> total books
+//   GET /1.0/Book/s/Count/FilteredTo/Status=Draft  -> draft books
+//   GET /1.0/Book/s/Count/By/Author/Frank Herbert  -> books by author
+//
+// All counts will automatically be filtered by the user's customer ID.
+```

package/docs/crud/create.md

@@ -0,0 +1,194 @@
+# Create Endpoints
+
+> Insert new records through REST with full lifecycle hooks
+
+The Create endpoints handle single-record and bulk-record creation. Both variants use the same underlying `Meadow-Operation-Create` function, which runs behavior injection hooks around the actual DAL create call.
+
+## Routes
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| POST | `/{v}/{entity}` | Create a single record |
+| POST | `/{v}/{entity}/s` | Bulk create (array of records) |
+
+## Single Create
+
+**Request:** `POST /1.0/Book`
+
+```json
+{
+	"Title": "Dune",
+	"Author": "Frank Herbert"
+}
+```
+
+**Response:** The complete created record, including auto-generated fields:
+
+```json
+{
+	"IDBook": 42,
+	"GUIDBook": "0x12ab34cd...",
+	"Title": "Dune",
+	"Author": "Frank Herbert",
+	"CreateDate": "2024-01-15T10:30:00.000Z",
+	"CreatingIDUser": 1,
+	"UpdateDate": "2024-01-15T10:30:00.000Z",
+	"UpdatingIDUser": 1,
+	"Deleted": 0
+}
+```
+
+## Bulk Create
+
+**Request:** `POST /1.0/Book/s`
+
+Send an array of records in the request body:
+
+```json
+[
+	{ "Title": "Dune", "Author": "Frank Herbert" },
+	{ "Title": "Neuromancer", "Author": "William Gibson" },
+	{ "Title": "Snow Crash", "Author": "Neal Stephenson" }
+]
+```
+
+**Response:** An array of created records. Each record in the array is processed through the full Create operation lifecycle individually, so all behavior hooks fire for each record.
+
+## Request Lifecycle
+
+The Create operation delegates to `Meadow-Operation-Create`, which runs the following waterfall:
+
+```
+POST /{v}/{entity}
+  |
+  v
+Validate request body is an object
+  |
+  v
+Set IDCustomer from session (if schema has IDCustomer)
+  |
+  v
+[Create-PreOperation]              <-- validate, authorize, transform
+  |
+  v
+Build query: addRecord(record), setIDUser(SessionData.UserID)
+  |
+  v
+[Create-QueryConfiguration]        <-- modify query before execution
+  |
+  v
+DAL.doCreate(query)                <-- insert + re-read the new record
+  |
+  v
+[Create-PostOperation]             <-- audit, notify, enrich
+  |
+  v
+Send response (created record)
+```
+
+For bulk creates, each record in the array passes through this same lifecycle independently. Errors on individual records do not halt the batch -- the error is attached to that record's response entry.
+
+## Behavior Injection Points
+
+### Create-PreOperation
+
+Runs **before** the query is built. The record to be created is available on `pRequestState.RecordToCreate`. Use this hook for validation, authorization, or to modify the record before it is persisted.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Create-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Validate required fields
+		if (!pRequestState.RecordToCreate.Title)
+		{
+			return fCallback({ Code: 400, Message: 'Title is required' });
+		}
+
+		// Set defaults
+		if (!pRequestState.RecordToCreate.Status)
+		{
+			pRequestState.RecordToCreate.Status = 'Draft';
+		}
+
+		return fCallback();
+	});
+```
+
+### Create-QueryConfiguration
+
+Runs **after** the FoxHound query is configured with the record and user ID, but **before** `DAL.doCreate()` executes. Use this to modify the query object directly.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Create-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Add extra query configuration
+		pRequestState.Query.setLogLevel(5);
+		return fCallback();
+	});
+```
+
+### Create-PostOperation
+
+Runs **after** the record has been created and re-read from the database. The complete record (including auto-generated fields like identity and timestamps) is available on `pRequestState.Record`.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Create-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Log an audit entry
+		let tmpAuditRecord = {
+			Action: 'Create',
+			EntityType: 'Book',
+			EntityID: pRequestState.Record.IDBook,
+			UserID: pRequestState.SessionData.UserID
+		};
+		_Fable.log.info(`Book created: ${JSON.stringify(tmpAuditRecord)}`);
+		return fCallback();
+	});
+```
+
+## Automatic Field Handling
+
+The Create operation automatically handles several fields:
+
+| Field | Behavior |
+|-------|----------|
+| `IDCustomer` | Set from `SessionData.CustomerID` if the schema includes it and the field is not already set |
+| `CreatingIDUser` | Set by the DAL from `Query.IDUser` (which comes from `SessionData.UserID`) |
+| `CreateDate` | Set automatically by the DAL |
+| `UpdatingIDUser` | Set by the DAL (same as CreatingIDUser on create) |
+| `UpdateDate` | Set automatically by the DAL (same as CreateDate on create) |
+| `Deleted` | Defaults to `0` |
+
+## Error Handling
+
+Errors returned to `fCallback` in any behavior hook halt the waterfall. The error object should include a `Code` (HTTP status) and `Message`:
+
+```javascript
+return fCallback({ Code: 400, Message: 'Validation failed: Title is required' });
+```
+
+For bulk creates, individual record errors are captured in the response without stopping the remaining records. Each errored record will include an `Error` property in its response entry.
+
+## Real-World Example: Authorization Check
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Create-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Only managers (role index >= 3) can create books
+		if (pRequestState.SessionData.UserRoleIndex < 3)
+		{
+			return fCallback({
+				Code: 403,
+				Message: 'Insufficient permissions to create records'
+			});
+		}
+
+		// Force the customer ID to match the session
+		pRequestState.RecordToCreate.IDCustomer = pRequestState.SessionData.CustomerID;
+
+		return fCallback();
+	});
+```

package/docs/crud/delete.md

@@ -0,0 +1,237 @@
+# Delete Endpoints
+
+> Soft-delete and restore records with full authorization hooks
+
+The Delete endpoints handle record deletion and undeletion. By default, Meadow uses soft deletes -- setting a `Deleted` column to `1` rather than removing the row. The delete lifecycle includes a pre-read of the target record, providing a checkpoint for authorization before the delete executes.
+
+## Routes
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| DELETE | `/{v}/{entity}/:IDRecord` | Delete a record by URL parameter |
+| DELETE | `/{v}/{entity}` | Delete a record (ID in request body) |
+| GET | `/{v}/{entity}/Undelete/:IDRecord` | Undelete a soft-deleted record |
+
+## Delete
+
+**Request:** `DELETE /1.0/Book/42`
+
+Or with the ID in the request body:
+
+```
+DELETE /1.0/Book
+Content-Type: application/json
+
+{ "IDBook": 42 }
+```
+
+**Response:** A count of deleted records:
+
+```json
+{
+	"Count": 1
+}
+```
+
+## Undelete
+
+**Request:** `GET /1.0/Book/Undelete/42`
+
+**Response:** A count of undeleted records:
+
+```json
+{
+	"Count": 1
+}
+```
+
+The Undelete endpoint verifies that the schema includes a `Deleted` column and that the target record actually has `Deleted = 1` before restoring it.
+
+## Delete Request Lifecycle
+
+```
+DELETE /{v}/{entity}/:IDRecord
+  |
+  v
+Extract record ID (from URL param or request body)
+Validate ID > 0
+  |
+  v
+Build query with ID filter, set IDUser from session
+  |
+  v
+[Delete-QueryConfiguration]         <-- modify query before record load
+  |
+  v
+DAL.doRead(query)                   <-- load the record for security checks
+  |
+  v
+[Delete-PreOperation]               <-- authorize, validate, prevent
+  |
+  v
+DAL.doDelete(query)                 <-- execute soft-delete
+  |
+  v
+[Delete-PostOperation]              <-- audit, cascade, cleanup
+  |
+  v
+Send response ({Count: N})
+```
+
+## Undelete Request Lifecycle
+
+```
+GET /{v}/{entity}/Undelete/:IDRecord
+  |
+  v
+Extract record ID, validate ID > 0
+  |
+  v
+Verify schema has a 'Deleted' type column
+  |
+  v
+Build query: filter by ID + Deleted = 1
+  |
+  v
+DAL.doRead(query)                   <-- find the deleted record
+  |
+  v
+[Undelete-PreOperation]             <-- authorize the restore
+  |
+  v
+DAL.doUndelete(query)               <-- set Deleted = 0
+  |
+  v
+[Undelete-PostOperation]            <-- audit, notify
+  |
+  v
+Send response ({Count: N})
+```
+
+## Behavior Injection Points
+
+### Delete-QueryConfiguration
+
+Runs after the initial query is built with the record ID filter and user ID, but before the record is loaded from the database. Use this to add additional query constraints.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Delete-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Add tenant filter to prevent cross-tenant deletes
+		pRequestState.Query.addFilter('IDCustomer',
+			pRequestState.SessionData.CustomerID);
+		return fCallback();
+	});
+```
+
+### Delete-PreOperation
+
+Runs after the target record is loaded from the database, but before the delete executes. The record is available on `pRequestState.Record`. This is the primary hook for authorization -- you can inspect the record's ownership, status, or relationships before allowing the delete.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Delete-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Only the record creator or admins can delete
+		if (pRequestState.Record.CreatingIDUser !== pRequestState.SessionData.UserID &&
+			pRequestState.SessionData.UserRoleIndex < 5)
+		{
+			return fCallback({
+				Code: 403,
+				Message: 'Only the record creator or an admin can delete this record'
+			});
+		}
+
+		// Prevent deletion of published records
+		if (pRequestState.Record.Status === 'Published')
+		{
+			return fCallback({
+				Code: 409,
+				Message: 'Cannot delete a published record. Unpublish it first.'
+			});
+		}
+
+		return fCallback();
+	});
+```
+
+### Delete-PostOperation
+
+Runs after the record has been deleted (soft-delete). Use this for audit logging, cascading deletes to related entities, or sending notifications.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Delete-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Log the deletion
+		_Fable.log.info(`Record ${pRequestState.IDRecord} deleted by user ${pRequestState.SessionData.UserID}`);
+
+		// Cascade soft-delete to child records
+		let tmpChildQuery = _ChapterDAL.query;
+		tmpChildQuery.addFilter('IDBook', pRequestState.IDRecord);
+		_ChapterDAL.doReads(tmpChildQuery,
+			(pError, pQuery, pRecords) =>
+			{
+				if (pRecords && pRecords.length > 0)
+				{
+					// Soft-delete each child record
+					_Fable.log.info(`Cascading delete to ${pRecords.length} chapters`);
+				}
+				return fCallback();
+			});
+	});
+```
+
+### Undelete-PreOperation
+
+Runs after the deleted record is located (verified to exist with `Deleted = 1`), before the undelete executes. The record is available on `pRequestState.Record`.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Undelete-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Only admins can undelete
+		if (pRequestState.SessionData.UserRoleIndex < 5)
+		{
+			return fCallback({
+				Code: 403,
+				Message: 'Only administrators can restore deleted records'
+			});
+		}
+		return fCallback();
+	});
+```
+
+### Undelete-PostOperation
+
+Runs after the record has been restored. Use this for audit logging or re-enabling related records.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Undelete-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		_Fable.log.info(`Record ${pRequest.params.IDRecord} undeleted by user ${pRequestState.SessionData.UserID}`);
+		return fCallback();
+	});
+```
+
+## Soft Delete vs Hard Delete
+
+Meadow's delete is always a soft delete -- it sets the `Deleted` column to `1`. This means:
+
+- **Deleted records are excluded from normal reads** -- the DAL automatically filters `Deleted = 0` on Read and Reads operations
+- **Deleted records can be restored** via the Undelete endpoint
+- **No data is permanently lost** through the standard API
+
+If your schema does not include a `Deleted` column, the Undelete endpoint will return a `500` error with the message "No undelete bit on record."
+
+## Record ID Resolution
+
+The Delete endpoint accepts the record ID from two sources, checked in order:
+
+1. **URL parameter:** `DELETE /1.0/Book/42` -- `pRequest.params.IDRecord`
+2. **Request body (number):** `{ "IDBook": 42 }` -- `pRequest.body[defaultIdentifier]`
+3. **Request body (string):** `{ "IDBook": "42" }` -- string-to-number conversion
+
+If no valid ID is found (ID < 1), the endpoint returns a `500` error.