json-rest-api 1.0.29 → 2.1.0

package/lib/error-formatter.js

@@ -1,105 +1,250 @@
+// @ts-check
+/** @import { DiagnosticPrimitive, DiagnosticValue, DiagnosticObject, DiagnosticFormattingOptions } from './logger-types.js' */
 /**
  * Error formatting utility for comprehensive error logging
  * Serializes errors with all their properties including custom fields like violations
  */
 
-/**
- * Formats an error object for logging, including all enumerable properties
- * @param {Error} error - The error to format
- * @param {Object} options - Formatting options
- * @param {boolean} options.includeStack - Whether to include stack trace (default: true)
- * @param {number} options.maxDepth - Maximum depth for nested objects (default: 5)
- * @returns {Object} Formatted error object safe for JSON serialization
- */
-export function formatError (error, options = {}) {
-  const { includeStack = true, maxDepth = 5 } = options
+import { types } from 'node:util'
+import { errorMessage, getBinaryDiagnostic, isErrorObject } from './error-context.js'
 
-  if (!error) {
-    return null
+/** @param {unknown} object @param {string | number} key @returns {unknown} */
+export function readDiagnosticProperty (object, key) {
+  try { return object == null ? undefined : Reflect.get(Object(object), key) } catch (error) {
+    return `[Error reading ${key}: ${errorMessage(error)}]`
   }
+}
 
+/** @param {DiagnosticFormattingOptions} [options] */
+function createDiagnosticFormatter ({ includeStack = true, maxDepth = 5, redactFields = [] } = {}) {
+  const redactedFields = new Set(redactFields)
+  /** @param {string} key */
+  const isRedacted = key => redactedFields.has(key)
+  const includeErrorStack = includeStack && !isRedacted('name') && !isRedacted('message')
+  const useCustomJson = includeErrorStack && redactedFields.size === 0
+  const redactedPaths = new Set([...redactedFields].map(field => `data.attributes.${field}`))
   // Handle circular references
   const seen = new WeakSet()
+  let remainingNodes = 256
+  let remainingText = 8192
+  const maxEntries = 50
+  const hasBudget = () => remainingNodes > 0 && remainingText > 0
+
+  /** @overload @param {string} value @returns {string} */
+  /** @overload @param {unknown} value @returns {DiagnosticPrimitive} */
+  /** @param {unknown} value @returns {DiagnosticPrimitive} */
+  function boundedText (value) {
+    if (typeof value === 'string') {
+      const limit = Math.min(2048, remainingText)
+      remainingText -= Math.min(value.length, limit)
+      return value.length > limit ? `${value.slice(0, limit)}[Truncated]` : value
+    }
+    if (value == null || typeof value === 'number' || typeof value === 'boolean') return value
+    if (typeof value === 'bigint' || typeof value === 'symbol') return boundedText(String(value))
+    if (typeof value === 'function') return '[Function]'
+    return '[Non-string diagnostic text]'
+  }
+
+  /** @param {DiagnosticObject} target @param {string} key @param {DiagnosticValue} value */
+  function setValue (target, key, value) {
+    Object.defineProperty(target, boundedText(key), { value: isRedacted(key) ? '[Redacted]' : value, enumerable: true, writable: true, configurable: true })
+  }
+
+  /** @param {unknown} object @param {string} key */
+  function readProperty (object, key) {
+    if (isRedacted(key)) return '[Redacted]'
+    return readDiagnosticProperty(object, key)
+  }
 
+  /** @param {unknown} error @returns {DiagnosticObject} */
+  function errorMetadata (error) {
+    // Native stack formatting can invoke name/message getters and repeat their values.
+    const stack = includeErrorStack ? readProperty(error, 'stack') : undefined
+    return {
+      name: boundedText(readProperty(error, 'name') || 'Error'),
+      message: boundedText(readProperty(error, 'message') || ''),
+      ...(stack ? { stack: boundedText(stack) } : {})
+    }
+  }
+
+  /** @param {unknown} obj @param {number} [depth] @returns {DiagnosticValue} */
   function serialize (obj, depth = 0) {
+    try {
+      return serializeValue(obj, depth)
+    } catch (error) {
+      return boundedText(`[Error serializing: ${errorMessage(error)}]`)
+    }
+  }
+
+  /** @param {unknown} obj @param {number} depth @returns {DiagnosticValue} */
+  function serializeValue (obj, depth) {
+    if (remainingNodes-- <= 0) return '[Truncated]'
     if (depth > maxDepth) {
       return '[Max depth exceeded]'
     }
 
-    if (obj === null || obj === undefined) {
-      return obj
-    }
+    if (obj === null || typeof obj !== 'object') return boundedText(obj)
 
-    if (typeof obj !== 'object') {
-      return obj
-    }
+    const binary = getBinaryDiagnostic(obj)
+    if (binary) return binary
 
     if (seen.has(obj)) {
       return '[Circular reference]'
     }
 
-    if (obj instanceof Date) {
-      return obj.toISOString()
+    if (types.isDate(obj)) {
+      return boundedText(obj.toISOString())
     }
 
-    if (obj instanceof RegExp) {
-      return obj.toString()
+    if (types.isRegExp(obj)) {
+      return boundedText(obj.toString())
     }
 
     seen.add(obj)
 
     if (Array.isArray(obj)) {
-      return obj.map(item => serialize(item, depth + 1))
+      const result = []
+      for (let i = 0; i < obj.length; i++) {
+        if (i >= maxEntries || !hasBudget()) {
+          result.push('[Truncated]')
+          break
+        }
+        result.push(serialize(readDiagnosticProperty(obj, i), depth + 1))
+      }
+      return result
     }
 
-    const result = {}
-    for (const key of Object.keys(obj)) {
+    const field = readProperty(obj, 'field')
+    if (typeof field === 'string' && (isRedacted(field) || redactedPaths.has(field))) {
+      return { field: boundedText(field), rule: boundedText(Object.getOwnPropertyDescriptor(obj, 'rule')?.value), message: '[Redacted]' }
+    }
+
+    const isError = isErrorObject(obj)
+    /** @type {DiagnosticObject} */
+    const result = isError ? errorMetadata(obj) : {}
+    const keys = new Set(Object.keys(obj))
+    if (isError) {
+      // Native causes and AggregateError members are not enumerable.
+      if (Object.hasOwn(obj, 'cause')) keys.add('cause')
+      if (Object.hasOwn(obj, 'errors')) keys.add('errors')
+    }
+    let entries = 0
+    for (const key of keys) {
+      if (entries++ >= maxEntries || !hasBudget()) {
+        result['[Truncated]'] = true
+        break
+      }
+      if (key === 'stack' && !includeErrorStack) continue
+      if (isRedacted(key)) {
+        setValue(result, key, '[Redacted]')
+        continue
+      }
+      if (key === 'toJSON' && !useCustomJson) continue
       try {
-        result[key] = serialize(obj[key], depth + 1)
+        const value = key === 'field' ? field : Reflect.get(obj, key)
+        setValue(result, key, serialize(value, depth + 1))
       } catch (e) {
-        result[key] = `[Error serializing: ${e.message}]`
+        setValue(result, key, boundedText(`[Error serializing: ${errorMessage(e)}]`))
       }
     }
 
     return result
   }
 
+  return { serialize, boundedText, setValue, readProperty, errorMetadata, includeErrorStack, useCustomJson, isRedacted, maxEntries, hasBudget }
+}
+
+/**
+ * Formats arbitrary diagnostic arguments with one shared preview budget.
+ * @param {unknown} value
+ * @param {DiagnosticFormattingOptions} [options]
+ * @returns {DiagnosticValue}
+ */
+export function formatDiagnosticValue (value, options = {}) {
+  return createDiagnosticFormatter(options).serialize(value)
+}
+
+/** @overload @param {object} error @param {DiagnosticFormattingOptions} [options] @returns {DiagnosticObject} */
+/** @overload @param {unknown} error @param {DiagnosticFormattingOptions} [options] @returns {DiagnosticObject | null} */
+/**
+ * Formats an error object for logging, including all enumerable properties
+ * @param {unknown} error - Error or non-Error thrown value.
+ * @param {import('./logger-types.js').DiagnosticFormattingOptions} [options]
+ * @returns {DiagnosticObject | null} Bounded diagnostic properties, or null for an absent/falsy error.
+ */
+export function formatError (error, options = {}) {
+  if (!error) return null
+  let binary
+  try { binary = getBinaryDiagnostic(error) } catch { /* Continue with guarded property reads. */ }
+  if (binary) return { name: 'Error', message: 'Binary value thrown', data: binary }
+  const { serialize, boundedText, setValue, errorMetadata, includeErrorStack, useCustomJson, isRedacted, maxEntries, hasBudget } = createDiagnosticFormatter(options)
+
   // Start with basic error properties
-  const formatted = {
-    name: error.name || 'Error',
-    message: error.message || '',
-    ...(includeStack && error.stack ? { stack: error.stack } : {})
-  }
+  const formatted = errorMetadata(error)
 
-  // If error has a toJSON method, use it
-  if (typeof error.toJSON === 'function') {
-    try {
-      const jsonError = error.toJSON()
-      Object.assign(formatted, serialize(jsonError))
-    } catch (e) {
-      formatted.toJSONError = `Failed to call toJSON: ${e.message}`
+  // Custom conversion can read or relabel values before field/stack filtering.
+  try {
+    /** @type {unknown} */
+    const toJSON = useCustomJson ? Reflect.get(Object(error), 'toJSON') : undefined
+    if (typeof toJSON === 'function') {
+      const jsonError = toJSON.call(error)
+      const serialized = serialize(jsonError)
+      if (serialized && typeof serialized === 'object') {
+        for (const [key, value] of Object.entries(serialized)) setValue(formatted, key, value)
+      } else if (serialized !== undefined) {
+        formatted.toJSONResult = serialized
+      }
     }
+  } catch (e) {
+    formatted.toJSONError = boundedText(`Failed to call toJSON: ${errorMessage(e)}`)
   }
 
   // Add all enumerable properties
-  for (const key of Object.keys(error)) {
+  /** @type {string[]} */
+  let keys = []
+  try {
+    keys = Object.keys(error)
+  } catch (e) {
+    formatted.propertiesError = boundedText(`[Error listing properties: ${errorMessage(e)}]`)
+  }
+  let entries = 0
+  for (const key of keys) {
+    if (entries++ >= maxEntries || !hasBudget()) {
+      formatted['[Truncated]'] = true
+      break
+    }
+    if (key === 'stack' && !includeErrorStack) continue
+    if (isRedacted(key)) {
+      setValue(formatted, key, '[Redacted]')
+      continue
+    }
+    if (key === 'toJSON' && !useCustomJson) continue
     if (!(key in formatted)) {
       try {
-        formatted[key] = serialize(error[key])
+        setValue(formatted, key, serialize(Reflect.get(Object(error), key)))
       } catch (e) {
-        formatted[key] = `[Error serializing: ${e.message}]`
+        setValue(formatted, key, boundedText(`[Error serializing: ${errorMessage(e)}]`))
       }
     }
   }
 
   // Ensure specific error properties are included
-  const importantProps = ['code', 'type', 'details', 'violations', 'subtype', 'path', 'fields']
+  const importantProps = ['code', 'type', 'details', 'violations', 'subtype', 'path', 'fields', 'cause', 'errors']
   for (const prop of importantProps) {
-    if (error[prop] !== undefined && !(prop in formatted)) {
+    if (!hasBudget()) {
+      formatted['[Truncated]'] = true
+      break
+    }
+    if (!(prop in formatted)) {
       try {
-        formatted[prop] = serialize(error[prop])
+        if (isRedacted(prop)) {
+          if (prop in Object(error)) formatted[prop] = '[Redacted]'
+        } else {
+          const value = Reflect.get(Object(error), prop)
+          if (value !== undefined) formatted[prop] = serialize(value)
+        }
       } catch (e) {
-        formatted[prop] = `[Error serializing: ${e.message}]`
+        formatted[prop] = isRedacted(prop) ? '[Redacted]' : boundedText(`[Error serializing: ${errorMessage(e)}]`)
       }
     }
   }
@@ -109,8 +254,8 @@ export function formatError (error, options = {}) {
 
 /**
  * Formats an error as a human-readable string with indentation
- * @param {Error} error - The error to format
- * @param {Object} options - Formatting options
+ * @param {unknown} error - The error to format
+ * @param {DiagnosticFormattingOptions} [options]
  * @returns {string} Formatted error string
  */
 export function formatErrorString (error, options = {}) {
@@ -120,28 +265,43 @@ export function formatErrorString (error, options = {}) {
 
 /**
  * Creates a one-line summary of an error including key details
- * @param {Error} error - The error to summarize
+ * @param {unknown} error - The error to summarize
+ * @param {import('./logger-types.js').DiagnosticFormattingOptions} [options]
  * @returns {string} One-line error summary
  */
-export function formatErrorSummary (error) {
+export function formatErrorSummary (error, options = {}) {
   if (!error) return 'Unknown error'
 
-  const parts = [error.message || 'No message']
+  const { readProperty } = createDiagnosticFormatter(options)
+  const details = readProperty(error, 'details')
+  const formatted = formatError({
+    message: readProperty(error, 'message'),
+    code: readProperty(error, 'code'),
+    details: { violations: readProperty(details, 'violations'), fields: readProperty(details, 'fields') }
+  }, { ...options, includeStack: false })
+  /** @param {unknown} value */
+  const text = value => typeof value === 'string' ? value : JSON.stringify(value)
+  const parts = [text(formatted.message || 'No message')]
 
-  if (error.code) {
-    parts.push(`code: ${error.code}`)
+  if (formatted.code) {
+    parts.push(`code: ${text(formatted.code)}`)
   }
 
-  if (error.details?.violations && Array.isArray(error.details.violations) && error.details.violations.length > 0) {
-    const violationSummary = error.details.violations
-      .map(v => `${v.field}: ${v.message}`)
+  const formattedDetails = readDiagnosticProperty(formatted, 'details')
+  const violations = readDiagnosticProperty(formattedDetails, 'violations')
+  const fields = readDiagnosticProperty(formattedDetails, 'fields')
+  if (Array.isArray(violations) && violations.length > 0) {
+    const violationSummary = violations
+      .map(v => v && typeof v === 'object' ? `${text(readDiagnosticProperty(v, 'field'))}: ${text(readDiagnosticProperty(v, 'message'))}` : text(v))
       .join(', ')
     parts.push(`violations: [${violationSummary}]`)
   }
 
-  if (error.details?.fields && Array.isArray(error.details.fields) && error.details.fields.length > 0) {
-    parts.push(`fields: ${error.details.fields.join(', ')}`)
+  if (Array.isArray(fields) && fields.length > 0) {
+    parts.push(`fields: ${fields.map(text).join(', ')}`)
   }
+  if (formatted['[Truncated]']) parts.push('[Truncated]')
 
-  return parts.join(' | ')
+  const summary = parts.join(' | ')
+  return summary.length > 2048 ? `${summary.slice(0, 2037)}[Truncated]` : summary
 }

package/lib/knex-transaction.js

@@ -0,0 +1,70 @@
+// @ts-check
+/** @import { OwnedTransaction, TransactionOutcome } from './transaction-types.js' */
+/** @import { StorageDatabase } from '../plugins/core/lib/storage/storage-types.js' */
+/** @typedef {{ cleanupErrors?: Array<{ phase: string, error: unknown }>, [serializableTransaction]?: boolean, [readCommittedTransaction]?: boolean }} CleanupContext */
+/** @type {WeakMap<OwnedTransaction, (error?: unknown) => Promise<void>>} */
+const transactionConnections = new WeakMap()
+
+// Internal connector request; HTTP input cannot select transaction isolation.
+export const serializableTransaction = Symbol('serializableTransaction')
+// MySQL's default REPEATABLE READ gap-locks locking reads of missing rows, so
+// concurrent creators of different rows deadlock on insert. PostgreSQL and
+// SQLite already behave as requested.
+export const readCommittedTransaction = Symbol('readCommittedTransaction')
+
+// Own the lease without changing the driver's SQL-completion promise.
+/**
+ * @param {StorageDatabase} knex
+ * @param {CleanupContext} [context]
+ * @returns {Promise<OwnedTransaction>}
+ */
+export async function createKnexTransaction (knex, context = {}) {
+  /** @type {{ __knex__disposed?: unknown }} */
+  const connection = await knex.client.acquireConnection()
+  /** @type {OwnedTransaction | undefined} */
+  let transaction
+  /** @type {Promise<void> | undefined} */
+  let releasePromise
+  /** @param {unknown} [error] */
+  const release = error => {
+    releasePromise ||= (async () => {
+      if (error !== undefined) connection.__knex__disposed = error || true
+      await knex.client.releaseConnection(connection)
+    })()
+    return releasePromise
+  }
+  try {
+    const client = knex.client.config.client
+    const isolationLevel = context[serializableTransaction] === true
+      ? !['sqlite3', 'better-sqlite3'].includes(client) && 'serializable'
+      : context[readCommittedTransaction] === true && ['mysql', 'mysql2'].includes(client) && 'read committed'
+    transaction = await knex.transaction({ connection, ...(isolationLevel ? { isolationLevel } : {}) })
+    transactionConnections.set(transaction, release)
+    transaction.executionPromise.then(
+      () => release(),
+      error => release(error || true)
+    ).catch(() => {})
+    if (transaction.isCompleted()) await transaction.executionPromise
+    return transaction
+  } catch (error) {
+    try { await release(error || true) } catch (releaseError) {
+      (context.cleanupErrors ||= []).push({ phase: 'connectionRelease', error: releaseError })
+    }
+    if (transaction) transactionConnections.delete(transaction)
+    throw error
+  }
+}
+
+/**
+ * @param {OwnedTransaction | null | undefined} transaction
+ * @param {TransactionOutcome | undefined} outcome
+ * @param {unknown} [error]
+ */
+export async function finishKnexTransactionConnection (transaction, outcome, error) {
+  if (!transaction) return
+  const release = transactionConnections.get(transaction)
+  if (!release) return
+  try {
+    await release(outcome === 'committed' || outcome === 'rolledBack' ? undefined : error || true)
+  } finally { transactionConnections.delete(transaction) }
+}

package/lib/logger-types.d.ts

@@ -0,0 +1,22 @@
+import type { StorageFieldDefinition } from '../plugins/core/lib/storage/storage-types.js'
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'trace' | 'fatal' | 'log'
+export type DiagnosticWriter = (...args: unknown[]) => unknown
+export type DiagnosticPrimitive = string | number | boolean | null | undefined
+export type DiagnosticValue = DiagnosticPrimitive | DiagnosticValue[] | DiagnosticObject
+export interface DiagnosticObject { [property: string]: DiagnosticValue }
+export type DiagnosticLogger = Partial<Record<LogLevel, DiagnosticWriter>>
+export interface DiagnosticFormattingOptions {
+  includeStack?: boolean
+  maxDepth?: number
+  redactFields?: readonly string[]
+}
+export interface DiagnosticOptions extends Omit<DiagnosticFormattingOptions, 'maxDepth'> {
+  logFullErrors?: boolean
+  schemaInfo?: { outputFields?: Record<string, StorageFieldDefinition> }
+}
+export interface EnhancedDiagnosticLogger extends DiagnosticLogger {
+  [property: string]: unknown
+  logError: (this: EnhancedDiagnosticLogger & { error: DiagnosticWriter }, message: string, error: unknown, additionalData?: Record<string, unknown>) => unknown
+  logValidationError: (this: EnhancedDiagnosticLogger & { error: DiagnosticWriter }, message: string, error: unknown, additionalData?: Record<string, unknown>) => unknown
+}

package/lib/missing-package.js

@@ -0,0 +1,4 @@
+/** @param {string} packageName @param {string} pluginName @param {string} [description] */
+export function throwMissingPackage (packageName, pluginName, description = '') {
+  throw new Error(`Plugin '${pluginName}' requires '${packageName}'. Install it with npm install ${packageName}. ${description}`)
+}

package/lib/rest-api-errors.js

@@ -1,8 +1,55 @@
-import { HookedApiError } from 'hooked-api'
+import { types } from 'node:util'
+
+export class RestApiError extends Error {
+  /** @param {string} message @param {unknown} [code] */
+  constructor (message, code = 'REST_API_ERROR') {
+    super(message)
+    this.name = this.constructor.name
+    this.code = code
+    Error.captureStackTrace(this, this.constructor)
+  }
+}
 
 export const REST_API_FIELDSET_ERROR_CODE = 'REST_API_FIELDSET_INVALID'
+export const REST_API_INCLUDE_ERROR_CODE = 'REST_API_INCLUDE_INVALID'
 export const REST_API_TEMPORAL_DATA_ERROR_CODE = 'REST_API_TEMPORAL_DATA_INVALID'
 
+const transactionOutcomes = new Set(['none', 'pending', 'committed', 'rolledBack', 'unknown'])
+const writeErrorFields = ['code', 'type', 'subtype', 'details', 'statusCode', 'status', 'path', 'parameter', 'validation']
+
+export class RestApiWriteError extends RestApiError {
+  constructor (message, { cause, transactionOutcome } = {}) {
+    super(message, 'REST_API_WRITE')
+    if (!transactionOutcomes.has(transactionOutcome)) throw new TypeError('Invalid transaction outcome')
+    Object.defineProperty(this, 'cause', { value: cause, configurable: true, writable: true })
+    Object.defineProperty(this, 'transactionOutcome', { value: transactionOutcome, enumerable: true })
+    if (cause && (typeof cause === 'object' || typeof cause === 'function')) {
+      for (const field of writeErrorFields) {
+        let descriptor
+        let owner = cause
+        try {
+          while (owner) {
+            descriptor = Object.getOwnPropertyDescriptor(owner, field)
+            // Proxy prototype links may cycle or invent an unlimited chain.
+            if (descriptor || types.isProxy(owner)) break
+            owner = Object.getPrototypeOf(owner)
+          }
+        } catch { /* Unreadable metadata must not replace the original cause or outcome. */ }
+        if (descriptor && Object.hasOwn(descriptor, 'value')) this[field] = descriptor.value
+      }
+    }
+  }
+
+  toJSON () {
+    return {
+      name: this.name,
+      message: this.message,
+      ...Object.fromEntries(writeErrorFields.filter(field => Object.hasOwn(this, field)).map(field => [field, this[field]])),
+      transactionOutcome: this.transactionOutcome
+    }
+  }
+}
+
 /**
  * REST API specific error classes that can be mapped to HTTP status codes
  * by the HTTP plugin or other protocol plugins
@@ -12,7 +59,11 @@ export const REST_API_TEMPORAL_DATA_ERROR_CODE = 'REST_API_TEMPORAL_DATA_INVALID
  * Validation error for invalid payloads, schema violations, etc.
  * HTTP plugin should map this to 422 Unprocessable Entity
  */
-export class RestApiValidationError extends HookedApiError {
+export class RestApiValidationError extends RestApiError {
+  /**
+   * @param {string} message
+   * @param {{ fields?: string[], violations?: Array<{ field: string, rule?: string, message: string }> }} [options]
+   */
   constructor (message, { fields = [], violations = [] } = {}) {
     super(message, 'REST_API_VALIDATION_ERROR')
     this.code = 'REST_API_VALIDATION'
@@ -39,7 +90,7 @@ export class RestApiValidationError extends HookedApiError {
  * Resource-related errors (not found, conflicts, forbidden access)
  * HTTP plugin should map based on subtype
  */
-export class RestApiResourceError extends HookedApiError {
+export class RestApiResourceError extends RestApiError {
   constructor (message, { subtype, resourceType, resourceId } = {}) {
     super(message, 'REST_API_RESOURCE_ERROR')
     this.code = 'REST_API_RESOURCE'
@@ -64,16 +115,35 @@ export class RestApiResourceError extends HookedApiError {
   }
 }
 
+export class RestApiVersionConflictError extends RestApiResourceError {
+  constructor ({ resourceType, resourceId } = {}) {
+    super('Resource version condition failed', { subtype: 'conflict', resourceType, resourceId })
+    this.code = 'REST_API_VERSION_CONFLICT'
+    this.type = 'rest_api_version_conflict'
+  }
+}
+
+export class RestApiPreconditionFailedError extends RestApiResourceError {
+  constructor ({ resourceType, resourceId } = {}) {
+    super('HTTP representation precondition failed', { subtype: 'precondition_failed', resourceType, resourceId })
+    this.code = 'REST_API_PRECONDITION_FAILED'
+    this.type = 'rest_api_precondition_failed'
+  }
+}
+
 /**
  * Payload structure errors (malformed JSON:API documents)
  * HTTP plugin should map this to 400 Bad Request
  */
-export class RestApiPayloadError extends HookedApiError {
-  constructor (message, { path, expected, received } = {}) {
+export class RestApiPayloadError extends RestApiError {
+  constructor (message, { path, parameter, expected, received, statusCode = 400, cause } = {}) {
     super(message, 'REST_API_PAYLOAD_ERROR')
     this.code = 'REST_API_PAYLOAD'
     this.type = 'rest_api_payload'
+    this.statusCode = statusCode
+    if (cause !== undefined) this.cause = cause
     this.path = path
+    this.parameter = parameter
     this.details = {
       path,
       expected,
@@ -88,6 +158,8 @@ export class RestApiPayloadError extends HookedApiError {
       code: this.code,
       type: this.type,
       path: this.path,
+      parameter: this.parameter,
+      statusCode: this.statusCode,
       details: this.details,
       stack: this.stack
     }
@@ -100,10 +172,12 @@ export class RestApiPayloadError extends HookedApiError {
  * The structured code lets transports distinguish invalid client input from
  * query or include failures without parsing the human-readable message.
  */
-export class RestApiFieldsetError extends HookedApiError {
+export class RestApiFieldsetError extends RestApiError {
   constructor ({ field, resourceType } = {}) {
     super(
-      `Unknown sparse field '${field}' requested for '${resourceType}'`,
+      field === undefined
+        ? `Unknown resource type '${resourceType}' requested in sparse fields`
+        : `Unknown sparse field '${field}' requested for '${resourceType}'`,
       REST_API_FIELDSET_ERROR_CODE
     )
     this.type = 'rest_api_fieldset'
@@ -127,11 +201,32 @@ export class RestApiFieldsetError extends HookedApiError {
   }
 }
 
+export class RestApiIncludeError extends RestApiError {
+  constructor ({ path, resourceType } = {}) {
+    super(`Unsupported include path '${path}' requested for '${resourceType}'`, REST_API_INCLUDE_ERROR_CODE)
+    this.type = 'rest_api_include'
+    this.statusCode = 400
+    this.details = { path, resourceType }
+  }
+
+  toJSON () {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      type: this.type,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    }
+  }
+}
+
 /**
  * A non-null temporal value produced by storage or response enrichment does
  * not satisfy the resource's public temporal contract.
  */
-export class RestApiTemporalDataError extends HookedApiError {
+export class RestApiTemporalDataError extends RestApiError {
   constructor ({ field, resourceType, fieldType, source = 'database' } = {}) {
     const fieldPath = [resourceType, field].filter(Boolean).join('.') || 'unknown field'
     super(