@cullet/erp-core 1.0.0

package/src/core/errors/index.ts

@@ -0,0 +1,99 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type {
+  AppErrorOptions,
+  ErrorSeverity,
+  JsonSafePrimitive,
+  JsonSafeRecord,
+  JsonSafeValue,
+} from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { ErrorCodes, serializationErrorCode } from "./error-codes";
+export { assertJsonSafeMetadata } from "./utils";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error classes
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { AppError } from "./app-error";
+export type {
+  AuthenticationErrorMetadata,
+  AuthenticationErrorReason,
+} from "./authentication-error";
+export { AuthenticationError } from "./authentication-error";
+export type {
+  AuthorizationErrorMetadata,
+  AuthorizationErrorReason,
+  AuthorizationRequirement,
+} from "./authorization-error";
+export { AuthorizationError } from "./authorization-error";
+export { BusinessRuleViolationError } from "./business-rule-violation-error";
+export type {
+  ConflictErrorMetadata,
+  ConflictKind,
+  UniqueConstraintViolation,
+} from "./conflict-error";
+export {
+  AlreadyExistsError,
+  ConflictError,
+  DuplicateError,
+  translateUniqueViolationToDuplicate,
+  UniqueConstraintViolationError,
+} from "./conflict-error";
+export type {
+  IdempotencyErrorMetadata,
+  IdempotencyFailureKind,
+} from "./idempotency-error";
+export {
+  IdempotencyError,
+  IdempotencyInProgressError,
+  IdempotencyKeyMissingError,
+  IdempotencyPayloadMismatchError,
+  IdempotencyReplayNotSupportedError,
+  payloadHash,
+  sha256Hex,
+  stableStringify,
+} from "./idempotency-error";
+export type {
+  IntegrationErrorMetadata,
+  IntegrationErrorReason,
+} from "./integration-error";
+export { IntegrationError } from "./integration-error";
+export { LegacyIncompatibleError } from "./legacy-incompatible-error";
+export { NotFoundError } from "./not-found-error";
+export type {
+  SerializationBoundary,
+  SerializationDirection,
+  SerializationErrorMetadata,
+  SerializationFailureCategory,
+} from "./serialization-error";
+export {
+  SerializationInError as DeserializationError,
+  safePreview,
+  SerializationCodes,
+  SerializationError,
+  SerializationInError,
+  SerializationMessages,
+  SerializationOutError,
+} from "./serialization-error";
+export type {
+  TemporalErrorMetadata as ExpiredErrorMetadata,
+  TemporalPrecision as ExpiredErrorPrecision,
+  TemporalErrorMetadata,
+  TemporalKind,
+  TemporalPrecision,
+} from "./temporal-error";
+export {
+  evaluateTemporalWindow,
+  ExpiredError,
+  NotYetValidError,
+  TemporalError,
+} from "./temporal-error";
+export { UnexpectedError } from "./unexpected-error";
+export { ValidationError } from "./validation-error";

package/src/core/errors/integration-error.ts

@@ -0,0 +1,157 @@
+import type { AppErrorOptions, ErrorSeverity } from "./types";
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+
+type IntegrationErrorReason =
+  | "timeout"
+  | "unreachable"
+  | "bad_response"
+  | "unknown";
+
+type IntegrationErrorMetadata = {
+  reason: IntegrationErrorReason;
+  provider: string;
+  operation: string;
+  startedAtIso: string;
+  durationMs: number;
+  detectedAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  details?: string;
+  statusCode?: number;
+  responseCode?: string;
+};
+
+type IntegrationErrorAppOptions = Pick<
+  AppErrorOptions,
+  | "cause"
+  | "type"
+  | "severity"
+  | "correlationId"
+  | "requestId"
+  | "commandId"
+  | "createdAtIso"
+  | "publicMessage"
+>;
+
+type IntegrationErrorConstructorParams = {
+  message: string;
+  code: string;
+  reason: IntegrationErrorReason;
+  metadata: IntegrationErrorMetadata;
+} & IntegrationErrorAppOptions;
+
+class IntegrationError extends AppError {
+  public readonly reason: IntegrationErrorReason;
+
+  private constructor(params: IntegrationErrorConstructorParams) {
+    const { message, code, metadata, ...rest } = params;
+    super(message, code, {
+      ...rest,
+      metadata,
+    });
+
+    this.reason = params.reason;
+    Object.freeze(this);
+  }
+
+  static timeout(options: IntegrationErrorTimeoutOptions): IntegrationError {
+    return new IntegrationError({
+      message: "Timeout while integrating with external provider",
+      code: ErrorCodes.integration.timeout,
+      reason: "timeout",
+      metadata: buildMetadata({ reason: "timeout", ...options }),
+      ...pickAppErrorFields(options),
+    });
+  }
+
+  static unreachable(
+    options: IntegrationErrorEndpointOptions,
+  ): IntegrationError {
+    return new IntegrationError({
+      message: "Provider unavailable",
+      code: ErrorCodes.integration.unreachable,
+      reason: "unreachable",
+      metadata: buildMetadata({ reason: "unreachable", ...options }),
+      ...pickAppErrorFields(options),
+    });
+  }
+
+  static badResponse(
+    options: IntegrationErrorEndpointOptions,
+  ): IntegrationError {
+    return new IntegrationError({
+      message: "Unexpected response from provider",
+      code: ErrorCodes.integration.badResponse,
+      reason: "bad_response",
+      metadata: buildMetadata({ reason: "bad_response", ...options }),
+      ...pickAppErrorFields(options),
+    });
+  }
+}
+
+type IntegrationErrorBaseOptions = {
+  provider: string;
+  operation: string;
+  startedAtIso: string;
+  durationMs: number;
+  detectedAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  details?: string;
+  statusCode?: number;
+  responseCode?: string;
+  cause?: unknown;
+  type?: string;
+  severity?: ErrorSeverity;
+  createdAtIso?: string;
+  publicMessage?: string;
+};
+
+type IntegrationErrorTimeoutOptions = IntegrationErrorBaseOptions;
+type IntegrationErrorEndpointOptions = IntegrationErrorBaseOptions;
+
+function buildMetadata(
+  input: IntegrationErrorBaseOptions & { reason: IntegrationErrorReason },
+): IntegrationErrorMetadata {
+  return compactMetadata({
+    reason: input.reason,
+    provider: input.provider,
+    operation: input.operation,
+    startedAtIso: input.startedAtIso,
+    durationMs: input.durationMs,
+    detectedAtIso: input.detectedAtIso,
+    correlationId: input.correlationId,
+    requestId: input.requestId,
+    commandId: input.commandId,
+    details: input.details,
+    statusCode: input.statusCode,
+    responseCode: input.responseCode,
+  }) as IntegrationErrorMetadata;
+}
+
+function pickAppErrorFields(
+  options: IntegrationErrorBaseOptions,
+): IntegrationErrorAppOptions {
+  return {
+    cause: options.cause,
+    type: options.type,
+    severity: options.severity,
+    correlationId: options.correlationId,
+    requestId: options.requestId,
+    commandId: options.commandId,
+    createdAtIso: options.createdAtIso,
+    publicMessage: options.publicMessage,
+  };
+}
+
+function compactMetadata<T extends Record<string, unknown>>(input: T): T {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, value]) => value !== undefined),
+  ) as T;
+}
+
+export { IntegrationError };
+export type { IntegrationErrorReason, IntegrationErrorMetadata };

package/src/core/errors/legacy-incompatible-error.ts

@@ -0,0 +1,26 @@
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// LegacyIncompatibleError
+// ─────────────────────────────────────────────────────────────────────────────
+
+class LegacyIncompatibleError extends AppError {
+  constructor(
+    message: string,
+    context?: Record<string, unknown>,
+    options?: AppErrorOptions,
+  ) {
+    const mergedMetadata = options?.metadata
+      ? { ...(context ?? {}), ...options.metadata }
+      : context;
+
+    super(message, ErrorCodes.legacyIncompatible, {
+      ...options,
+      metadata: mergedMetadata,
+    });
+  }
+}
+
+export { LegacyIncompatibleError };

package/src/core/errors/not-found-error.ts

@@ -0,0 +1,27 @@
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NotFoundError
+// ─────────────────────────────────────────────────────────────────────────────
+
+class NotFoundError extends AppError {
+  constructor(
+    resource: string,
+    criteria?: Record<string, unknown>,
+    options?: AppErrorOptions,
+  ) {
+    const baseMetadata = criteria ? { resource, criteria } : { resource };
+    const mergedMetadata = options?.metadata
+      ? { ...baseMetadata, ...options.metadata }
+      : baseMetadata;
+
+    super(`${resource} not found`, ErrorCodes.notFound, {
+      ...options,
+      metadata: mergedMetadata,
+    });
+  }
+}
+
+export { NotFoundError };

package/src/core/errors/serialization-error.ts

@@ -0,0 +1,233 @@
+import { AppError } from "./app-error";
+import { serializationErrorCode } from "./error-codes";
+import type { AppErrorOptions } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+type SerializationDirection = "serialize" | "deserialize";
+
+type SerializationFailureCategory =
+  | "invalid_json"
+  | "invalid_shape"
+  | "missing_field"
+  | "unexpected_field"
+  | "invalid_type"
+  | "schema_version_missing"
+  | "schema_version_unsupported"
+  | "mapping_not_implemented"
+  | "contract_mismatch"
+  | "parse_failed"
+  | "stringify_failed"
+  | "unknown";
+
+type SerializationBoundary =
+  | "http_in"
+  | "http_out"
+  | "graphql_in"
+  | "graphql_out"
+  | "dto_to_domain"
+  | "domain_to_dto"
+  | "persistence_to_domain"
+  | "domain_to_persistence"
+  | "event_in"
+  | "event_out"
+  | "projection"
+  | "unknown";
+
+/**
+ * Metadata shared by serialization/deserialization failures. Payload previews must be sanitized.
+ */
+type SerializationErrorMetadata = {
+  direction: SerializationDirection;
+  category: SerializationFailureCategory;
+  boundary: SerializationBoundary;
+  contract: string;
+  schemaVersion?: number | string;
+  path?: string;
+  payloadPreview?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  hint?: string;
+  details?: string;
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Base error
+// ─────────────────────────────────────────────────────────────────────────────
+
+type SerializationErrorOptions = Omit<AppErrorOptions, "metadata"> & {
+  message: string;
+  code: string;
+  metadata: Omit<SerializationErrorMetadata, "direction" | "category">;
+  direction: SerializationDirection;
+  category: SerializationFailureCategory;
+};
+
+abstract class SerializationError extends AppError {
+  public readonly direction: SerializationDirection;
+  public readonly category: SerializationFailureCategory;
+  public readonly boundary: SerializationBoundary;
+  public readonly contract: string;
+
+  protected constructor(input: SerializationErrorOptions) {
+    super(input.message ?? "Serialization failure", input.code, {
+      cause: input.cause,
+      metadata: {
+        direction: input.direction,
+        category: input.category,
+        ...input.metadata,
+      },
+      type: input.type,
+      severity: input.severity,
+      correlationId: input.correlationId,
+      requestId: input.requestId,
+      commandId: input.commandId,
+      createdAtIso: input.createdAtIso,
+      publicMessage: input.publicMessage,
+    });
+
+    this.direction = input.direction;
+    this.category = input.category;
+    this.boundary = input.metadata.boundary;
+    this.contract = input.metadata.contract;
+
+    Object.freeze(this);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Serialization In
+// ─────────────────────────────────────────────────────────────────────────────
+
+class SerializationInError extends SerializationError {
+  private constructor(input: SerializationErrorOptions) {
+    super(input);
+  }
+
+  static failure(
+    category: SerializationFailureCategory,
+    metadata: Omit<SerializationErrorMetadata, "direction" | "category"> & {
+      cause?: unknown;
+    },
+  ): SerializationInError {
+    return new SerializationInError({
+      message: SerializationMessages.message("deserialize", category),
+      code: SerializationCodes.code("deserialize", category),
+      category,
+      direction: "deserialize",
+      metadata,
+      cause: metadata.cause,
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Serialization
+// ─────────────────────────────────────────────────────────────────────────────
+
+class SerializationOutError extends SerializationError {
+  private constructor(input: SerializationErrorOptions) {
+    super(input);
+  }
+
+  static failure(
+    category: SerializationFailureCategory,
+    metadata: Omit<SerializationErrorMetadata, "direction" | "category"> & {
+      cause?: unknown;
+    },
+  ): SerializationOutError {
+    return new SerializationOutError({
+      message: SerializationMessages.message("serialize", category),
+      code: SerializationCodes.code("serialize", category),
+      category,
+      direction: "serialize",
+      metadata,
+      cause: metadata.cause,
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Codes + Messages helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+class SerializationCodes {
+  static code(
+    direction: SerializationDirection,
+    category: SerializationFailureCategory,
+  ): string {
+    return serializationErrorCode(direction, category);
+  }
+}
+
+class SerializationMessages {
+  static message(
+    direction: SerializationDirection,
+    category: SerializationFailureCategory,
+  ): string {
+    if (direction === "deserialize") {
+      if (category === "invalid_json") {
+        return "Invalid payload: malformed JSON";
+      }
+      if (category === "schema_version_missing") {
+        return "Invalid payload: schemaVersion is missing";
+      }
+      if (category === "schema_version_unsupported") {
+        return "Invalid payload: schemaVersion is not supported";
+      }
+      if (category === "invalid_shape") {
+        return "Invalid payload: incompatible shape";
+      }
+      if (category === "mapping_not_implemented") {
+        return "Unsupported payload: mapping not implemented";
+      }
+      if (category === "contract_mismatch") {
+        return "Payload does not match the expected contract";
+      }
+      return "Failed to parse incoming payload";
+    }
+
+    if (category === "stringify_failed") {
+      return "Failed to serialize the response";
+    }
+    if (category === "contract_mismatch") {
+      return "Response does not match the expected contract";
+    }
+    return "Failed to build the response";
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+function safePreview(value: unknown, limit = 240): string | undefined {
+  try {
+    const serialized =
+      typeof value === "string" ? value : JSON.stringify(value);
+    return serialized.length > limit
+      ? `${serialized.slice(0, limit)}…`
+      : serialized;
+  } catch {
+    return undefined;
+  }
+}
+
+export {
+  safePreview,
+  SerializationCodes,
+  SerializationError,
+  SerializationInError as DeserializationError,
+  SerializationInError,
+  SerializationMessages,
+  SerializationOutError,
+};
+export type {
+  SerializationBoundary,
+  SerializationDirection,
+  SerializationErrorMetadata,
+  SerializationFailureCategory,
+};

package/src/core/errors/temporal-error.ts

@@ -0,0 +1,145 @@
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions } from "./types";
+
+type TemporalKind = "expired" | "not_yet_valid";
+
+type TemporalPrecision = "EXACT" | "ESTIMATED" | "UNKNOWN" | "APPROXIMATE";
+
+type TemporalErrorMetadata = {
+  resourceType: string;
+  resourceId?: string;
+  operation?: string;
+  validFromIso?: string | null;
+  validUntilIso?: string | null;
+  evaluatedAtIso: string;
+  policyId?: string;
+  precision?: TemporalPrecision;
+  hint?: string;
+  details?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+};
+
+type TemporalErrorOptions = {
+  message: string;
+  code: string;
+  kind: TemporalKind;
+  metadata: TemporalErrorMetadata;
+} & AppErrorOptions;
+
+abstract class TemporalError extends AppError {
+  public readonly kind: TemporalKind;
+  public readonly resourceType: string;
+  public readonly evaluatedAtIso: string;
+
+  protected constructor(input: TemporalErrorOptions) {
+    super(input.message, input.code, {
+      ...input,
+      metadata: {
+        kind: input.kind,
+        ...input.metadata,
+      },
+    });
+
+    this.kind = input.kind;
+    this.resourceType = input.metadata.resourceType;
+    this.evaluatedAtIso = input.metadata.evaluatedAtIso;
+    Object.freeze(this);
+  }
+}
+
+type TemporalCreationInput = TemporalErrorMetadata &
+  Partial<Omit<AppErrorOptions, "metadata">> & {
+    cause?: unknown;
+  };
+
+class ExpiredError extends TemporalError {
+  private constructor(input: TemporalErrorOptions) {
+    super(input);
+  }
+
+  static detected(input: TemporalCreationInput): ExpiredError {
+    return new ExpiredError({
+      message: "The validity of the resource/action has expired",
+      code: ErrorCodes.temporal.expired,
+      kind: "expired",
+      metadata: {
+        ...input,
+        hint:
+          input.hint ??
+          "The window has expired. Request a new link or try again within the valid period.",
+      },
+      cause: input.cause,
+      type: input.type,
+      severity: input.severity,
+      correlationId: input.correlationId,
+      requestId: input.requestId,
+      commandId: input.commandId,
+      createdAtIso: input.createdAtIso,
+      publicMessage: input.publicMessage,
+    });
+  }
+}
+
+class NotYetValidError extends TemporalError {
+  private constructor(input: TemporalErrorOptions) {
+    super(input);
+  }
+
+  static detected(input: TemporalCreationInput): NotYetValidError {
+    return new NotYetValidError({
+      message: "The resource/action is not yet valid",
+      code: ErrorCodes.temporal.notYetValid,
+      kind: "not_yet_valid",
+      metadata: {
+        ...input,
+        hint: input.hint ?? "Not yet within the valid period. Try again later.",
+      },
+      cause: input.cause,
+      type: input.type,
+      severity: input.severity,
+      correlationId: input.correlationId,
+      requestId: input.requestId,
+      commandId: input.commandId,
+      createdAtIso: input.createdAtIso,
+      publicMessage: input.publicMessage,
+    });
+  }
+}
+
+function evaluateTemporalWindow(input: {
+  validFromIso?: string | null;
+  validUntilIso?: string | null;
+  evaluatedAtIso: string;
+}): { expired: boolean; notYetValid: boolean } | null {
+  const evaluatedMs = Date.parse(input.evaluatedAtIso);
+  if (Number.isNaN(evaluatedMs)) return null;
+
+  let notYetValid = false;
+
+  if (input.validFromIso) {
+    const fromMs = Date.parse(input.validFromIso);
+    if (!Number.isNaN(fromMs) && evaluatedMs < fromMs) {
+      notYetValid = true;
+    }
+  }
+
+  if (input.validUntilIso) {
+    const untilMs = Date.parse(input.validUntilIso);
+    if (!Number.isNaN(untilMs) && evaluatedMs > untilMs) {
+      return { expired: true, notYetValid: false };
+    }
+  }
+
+  return { expired: false, notYetValid };
+}
+
+export {
+  evaluateTemporalWindow,
+  ExpiredError,
+  NotYetValidError,
+  TemporalError,
+};
+export type { TemporalErrorMetadata, TemporalKind, TemporalPrecision };