@cullet/erp-core 1.0.9 → 1.0.11

package/dist/validation-error.js

@@ -80,6 +80,19 @@ function compactMetadata$1(input) {
 }
 //#endregion
 //#region src/core/errors/authorization-error.ts
+/**
+* Raised when an authenticated actor is not allowed to perform a business
+* action — the "you may not" error, distinct from authentication ("who are
+* you"). Maps to an HTTP 403 at the edge.
+*
+* The discriminating {@link reason} records *why* access was denied (a flat
+* forbid, a missing role/capability, an out-of-scope target, or a policy
+* decision) so the boundary can shape the response without re-deriving it. The
+* metadata is deliberately built around a stable business `action` and a
+* type/id resource reference rather than an HTTP route or full payload, keeping
+* sensitive data out of logs. Instances are frozen. Construct through the
+* static factories, never directly.
+*/
 var AuthorizationError = class AuthorizationError extends AppError {
 	constructor(params) {
 		super(params.message, params.code, {
@@ -96,6 +109,12 @@ var AuthorizationError = class AuthorizationError extends AppError {
 		this.reason = params.reason;
 		Object.freeze(this);
 	}
+	/**
+	* A flat denial with no more specific reason — the actor simply may not
+	* perform this action. Reach for a more precise factory
+	* ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+	* {@link AuthorizationError.policyDenied}) when the cause is known.
+	*/
 	static forbidden(input) {
 		return new AuthorizationError({
 			message: "Action not allowed",
@@ -108,6 +127,15 @@ var AuthorizationError = class AuthorizationError extends AppError {
 			...extractAppErrorOptions(input)
 		});
 	}
+	/**
+	* The action was denied by an evaluated policy. Captures the deciding
+	* policy's id, version, and evaluation instant into the metadata (with
+	* `decision: "deny"`) so the denial is auditable back to the exact policy
+	* that produced it.
+	*
+	* @param input - Factory options plus the required `policyId`,
+	*   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+	*/
 	static policyDenied(input) {
 		return new AuthorizationError({
 			message: "Action denied by policy",
@@ -121,6 +149,13 @@ var AuthorizationError = class AuthorizationError extends AppError {
 			...extractAppErrorOptions(input)
 		});
 	}
+	/**
+	* The actor lacks a required role or capability. The expected
+	* {@link AuthorizationRequirement} is recorded so the boundary can tell the
+	* caller precisely what grant is missing.
+	*
+	* @param input - Factory options plus the `required` role/capability/scope.
+	*/
 	static missingCapability(input) {
 		return new AuthorizationError({
 			message: "Insufficient capability to perform the action",
@@ -133,6 +168,14 @@ var AuthorizationError = class AuthorizationError extends AppError {
 			...extractAppErrorOptions(input)
 		});
 	}
+	/**
+	* The actor may perform the action in general, but not on *this* target —
+	* the resource falls outside the actor's permitted scope (e.g. a different
+	* school or tenant than the one they are bound to).
+	*
+	* @param input - Factory options plus the optional `required` scope that the
+	*   target failed to satisfy.
+	*/
 	static outOfScope(input) {
 		return new AuthorizationError({
 			message: "Action outside the allowed scope",
@@ -182,6 +225,17 @@ var BusinessRuleViolationError = class extends AppError {
 };
 //#endregion
 //#region src/core/errors/conflict-error.ts
+/**
+* Base for errors that signal a state conflict — the request collides with data
+* that already exists. Common at an HTTP 409 boundary.
+*
+* The discriminating {@link kind} lets a handler branch on *why* it conflicted
+* (an already-existing record, a domain duplicate, or a raw storage uniqueness
+* breach) without `instanceof` chains. Abstract: construct one of the concrete
+* subclasses through its `detected(...)` factory, which fills in the right code,
+* message, and metadata. Instances are frozen, so a conflict error can be shared
+* and rethrown without risk of tampering.
+*/
 var ConflictError = class extends AppError {
 	constructor(params) {
 		super(params.message, params.code, {
@@ -195,6 +249,11 @@ var ConflictError = class extends AppError {
 		Object.freeze(this);
 	}
 };
+/**
+* The operation cannot proceed because a matching record already exists —
+* e.g. creating something whose natural key is already taken. Construct via
+* {@link AlreadyExistsError.detected}.
+*/
 var AlreadyExistsError = class AlreadyExistsError extends ConflictError {
 	constructor(input) {
 		super({
@@ -204,6 +263,14 @@ var AlreadyExistsError = class AlreadyExistsError extends ConflictError {
 			...input
 		});
 	}
+	/**
+	* Builds an {@link AlreadyExistsError} for a detected collision. `operation`
+	* defaults to `"create"` and a generic retry `hint` is supplied when none is
+	* given, so the error is actionable even from a minimal call site.
+	*
+	* @param input - The conflicting entity plus optional non-sensitive context
+	*   (operation, field, existing id, value hash/preview, correlation ids).
+	*/
 	static detected(input) {
 		return new AlreadyExistsError({
 			metadata: {
@@ -223,6 +290,13 @@ var AlreadyExistsError = class AlreadyExistsError extends ConflictError {
 		});
 	}
 };
+/**
+* A domain-level duplicate: the data being written would duplicate an existing
+* record under the model's own uniqueness rules. Use this when the duplication
+* is recognized in the domain, as opposed to a raw DB constraint
+* ({@link UniqueConstraintViolationError}). Construct via
+* {@link DuplicateError.detected}.
+*/
 var DuplicateError = class DuplicateError extends ConflictError {
 	constructor(input) {
 		super({
@@ -232,6 +306,13 @@ var DuplicateError = class DuplicateError extends ConflictError {
 			...input
 		});
 	}
+	/**
+	* Builds a {@link DuplicateError} for a detected duplicate, defaulting to a
+	* "adjust the data so it does not duplicate" hint when none is provided.
+	*
+	* @param input - The conflicting entity plus optional non-sensitive context
+	*   (field, constraint name, existing id, value hash/preview, correlation ids).
+	*/
 	static detected(input) {
 		return new DuplicateError({
 			metadata: {
@@ -252,6 +333,14 @@ var DuplicateError = class DuplicateError extends ConflictError {
 		});
 	}
 };
+/**
+* A uniqueness breach surfaced by the storage layer itself (a database unique
+* index), carrying the raw {@link UniqueConstraintViolation} (constraint, table,
+* columns). Keep this distinct from {@link DuplicateError}: this one is the
+* infrastructure signal; translate it into a domain duplicate at the boundary
+* with {@link translateUniqueViolationToDuplicate} when the model should own the
+* message. Construct via {@link UniqueConstraintViolationError.detected}.
+*/
 var UniqueConstraintViolationError = class UniqueConstraintViolationError extends ConflictError {
 	constructor(input) {
 		super({
@@ -261,6 +350,13 @@ var UniqueConstraintViolationError = class UniqueConstraintViolationError extend
 			...input
 		});
 	}
+	/**
+	* Builds a {@link UniqueConstraintViolationError} from the constraint details
+	* a driver reports, packaging them into a nested `violation` payload.
+	*
+	* @param input - The entity plus the offending constraint name, table, and
+	*   columns, and optional correlation ids.
+	*/
 	static detected(input) {
 		return new UniqueConstraintViolationError({
 			metadata: {
@@ -283,6 +379,17 @@ var UniqueConstraintViolationError = class UniqueConstraintViolationError extend
 		});
 	}
 };
+/**
+* Translates a raw storage {@link UniqueConstraintViolation} into a domain-level
+* {@link DuplicateError}. This is the seam where an infrastructure concern (a DB
+* unique index firing) is re-expressed in the language of the model, so callers
+* upstream catch a `DuplicateError` and never have to know a database was
+* involved.
+*
+* @param input - The entity, the driver-reported `violation`, and optional
+*   request context (`ctx`) carrying correlation ids and a clock instant.
+* @returns A {@link DuplicateError} carrying the constraint name as its field hint.
+*/
 function translateUniqueViolationToDuplicate(input) {
 	return DuplicateError.detected({
 		entity: input.entity,
@@ -453,6 +560,18 @@ function resolveKeyIdentity(key, keyHash, keyPreview) {
 }
 //#endregion
 //#region src/core/errors/integration-error.ts
+/**
+* Raised when a call to an external provider fails — a timeout, an unreachable
+* endpoint, or a malformed response. This is the boundary error that separates
+* "our code is fine, the outside world misbehaved" from internal faults, which
+* matters for retry and alerting decisions.
+*
+* Every instance records the `provider`, the `operation`, and timing
+* (`startedAtIso` / `durationMs`) so failures are correlatable across services
+* and a slow dependency is visible in the metadata. The discriminating
+* {@link reason} lets callers decide whether a failure is worth retrying.
+* Instances are frozen; construct through the static factories.
+*/
 var IntegrationError = class IntegrationError extends AppError {
 	constructor(params) {
 		const { message, code, metadata, ...rest } = params;
@@ -463,6 +582,10 @@ var IntegrationError = class IntegrationError extends AppError {
 		this.reason = params.reason;
 		Object.freeze(this);
 	}
+	/**
+	* The provider did not respond within the allotted time. Usually retryable,
+	* since a timeout leaves the outcome unknown rather than known-failed.
+	*/
 	static timeout(options) {
 		return new IntegrationError({
 			message: "Timeout while integrating with external provider",
@@ -475,6 +598,10 @@ var IntegrationError = class IntegrationError extends AppError {
 			...pickAppErrorFields(options)
 		});
 	}
+	/**
+	* The provider could not be reached at all (connection refused, DNS
+	* failure, network partition) — the request never landed.
+	*/
 	static unreachable(options) {
 		return new IntegrationError({
 			message: "Provider unavailable",
@@ -487,6 +614,11 @@ var IntegrationError = class IntegrationError extends AppError {
 			...pickAppErrorFields(options)
 		});
 	}
+	/**
+	* The provider answered, but with something the system cannot use — an
+	* unexpected status, an unparsable body, or a contract mismatch. Unlike a
+	* timeout this is a definite failure, so blind retries rarely help.
+	*/
 	static badResponse(options) {
 		return new IntegrationError({
 			message: "Unexpected response from provider",
@@ -547,7 +679,21 @@ var LegacyIncompatibleError = class extends AppError {
 };
 //#endregion
 //#region src/core/errors/not-found-error.ts
+/**
+* Raised when a requested resource does not exist. Maps naturally onto an HTTP
+* 404 at the edge, but stays transport-agnostic here.
+*
+* The `resource` name builds the message (`"<resource> not found"`) and, with
+* the optional lookup `criteria`, lands in the metadata so logs show *what* was
+* searched for without the caller having to restate it in the message.
+*/
 var NotFoundError = class extends AppError {
+	/**
+	* @param resource - Human-readable name of the missing resource (e.g. `"Order"`).
+	* @param criteria - Optional lookup keys used in the search; recorded in
+	*   metadata to aid debugging. Avoid putting sensitive values here.
+	* @param options - Optional cause, correlation ids, and extra metadata.
+	*/
 	constructor(resource, criteria, options) {
 		const baseMetadata = criteria ? {
 			resource,
@@ -735,7 +881,25 @@ function evaluateTemporalWindow(input) {
 }
 //#endregion
 //#region src/core/errors/validation-error.ts
+/**
+* Raised when a single input fails a validation rule — the canonical
+* "this field is wrong, and here is why" error.
+*
+* It pins the offending `field` and a machine-readable `validationCode` into
+* the metadata (merged ahead of any caller-supplied metadata) so an API layer
+* can map the failure straight onto a form field without parsing the message.
+* The fixed {@link ErrorCodes.validation} code lets callers catch all
+* validation failures uniformly while still distinguishing the specific rule
+* through `validationCode`.
+*/
 var ValidationError = class extends AppError {
+	/**
+	* @param field - The input that failed validation; surfaced as `metadata.field`.
+	* @param code - The specific rule that was violated; surfaced as `metadata.validationCode`.
+	* @param message - The developer-facing description of the failure.
+	* @param options - Optional cause, correlation ids, and extra metadata
+	*   (merged over the field/code metadata, never overwriting it by accident).
+	*/
 	constructor(field, code, message, options) {
 		const baseMetadata = {
 			field: field.value,