@cullet/erp-core 1.0.10 → 1.1.0

package/dist/validation-error.js

@@ -1,4 +1,4 @@
-import { c as ErrorCodes, l as serializationErrorCode, o as AppError } from "./validation-code.js";
+import { a as ErrorCodes, o as serializationErrorCode, r as AppError } from "./validation-code.js";
 //#region src/core/errors/authentication-error.ts
 var AuthenticationError = class AuthenticationError extends AppError {
 	constructor(params) {
@@ -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",
@@ -163,25 +206,18 @@ function extractMetadataOnly(input) {
 	return metadata;
 }
 //#endregion
-//#region src/core/errors/business-rule-violation-error.ts
-var BusinessRuleViolationError = class extends AppError {
-	constructor(rule, message, detail, options) {
-		const baseMetadata = detail ? {
-			rule,
-			detail
-		} : { rule };
-		const mergedMetadata = options?.metadata ? {
-			...baseMetadata,
-			...options.metadata
-		} : baseMetadata;
-		super(message, ErrorCodes.businessRuleViolation, {
-			...options,
-			metadata: mergedMetadata
-		});
-	}
-};
-//#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 +231,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 +245,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 +272,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 +288,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 +315,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 +332,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 +361,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 +542,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 +564,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 +580,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 +596,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",
@@ -546,24 +660,6 @@ var LegacyIncompatibleError = class extends AppError {
 	}
 };
 //#endregion
-//#region src/core/errors/not-found-error.ts
-var NotFoundError = class extends AppError {
-	constructor(resource, criteria, options) {
-		const baseMetadata = criteria ? {
-			resource,
-			criteria
-		} : { resource };
-		const mergedMetadata = options?.metadata ? {
-			...baseMetadata,
-			...options.metadata
-		} : baseMetadata;
-		super(`${resource} not found`, ErrorCodes.notFound, {
-			...options,
-			metadata: mergedMetadata
-		});
-	}
-};
-//#endregion
 //#region src/core/errors/serialization-error.ts
 var SerializationError = class extends AppError {
 	constructor(input) {
@@ -735,7 +831,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,
@@ -752,6 +866,6 @@ var ValidationError = class extends AppError {
 	}
 };
 //#endregion
-export { UniqueConstraintViolationError as C, AuthenticationError as D, AuthorizationError as E, DuplicateError as S, BusinessRuleViolationError as T, IdempotencyKeyMissingError as _, evaluateTemporalWindow as a, AlreadyExistsError as b, SerializationInError as c, safePreview as d, NotFoundError as f, IdempotencyInProgressError as g, IdempotencyError as h, TemporalError as i, SerializationMessages as l, IntegrationError as m, ExpiredError as n, SerializationCodes as o, LegacyIncompatibleError as p, NotYetValidError as r, SerializationError as s, ValidationError as t, SerializationOutError as u, IdempotencyPayloadMismatchError as v, translateUniqueViolationToDuplicate as w, ConflictError as x, IdempotencyReplayNotSupportedError as y };
+export { translateUniqueViolationToDuplicate as C, UniqueConstraintViolationError as S, AuthenticationError as T, IdempotencyPayloadMismatchError as _, evaluateTemporalWindow as a, ConflictError as b, SerializationInError as c, safePreview as d, LegacyIncompatibleError as f, IdempotencyKeyMissingError as g, IdempotencyInProgressError as h, TemporalError as i, SerializationMessages as l, IdempotencyError as m, ExpiredError as n, SerializationCodes as o, IntegrationError as p, NotYetValidError as r, SerializationError as s, ValidationError as t, SerializationOutError as u, IdempotencyReplayNotSupportedError as v, AuthorizationError as w, DuplicateError as x, AlreadyExistsError as y };
 
 //# sourceMappingURL=validation-error.js.map