@cullet/erp-core 1.0.0

package/src/core/domain/temporal/transaction-time.ts

@@ -0,0 +1,60 @@
+import { InvariantViolationException } from "../../exceptions/invariant-violation-exception";
+import { makeImmutable } from "../../shared/immutable";
+import { assertValidDate } from "../../shared/temporal-guards";
+
+/**
+ * Represents transaction time (Transaction Time).
+ * Defines when the system learned about or recorded a piece of information.
+ * Useful for auditing and reconstructing system state at a specific past moment.
+ */
+interface TransactionTime {
+  /** When the information was first recorded in the system. */
+  readonly recordedAt: Date;
+  /** When this information was superseded or invalidated by a newer version. */
+  readonly supersededAt?: Date;
+}
+
+type CreateTransactionTimeInput = TransactionTime;
+
+function assertTransactionTime(
+  txTime: TransactionTime,
+  fieldName: string = "txTime",
+): void {
+  assertValidDate(`${fieldName}.recordedAt`, txTime.recordedAt);
+
+  if (txTime.supersededAt === undefined) {
+    return;
+  }
+
+  assertValidDate(`${fieldName}.supersededAt`, txTime.supersededAt);
+
+  if (txTime.supersededAt.getTime() <= txTime.recordedAt.getTime()) {
+    throw new InvariantViolationException(
+      `${fieldName}.supersededAt must be later than ${fieldName}.recordedAt`,
+    );
+  }
+}
+
+function createTransactionTime(
+  input: CreateTransactionTimeInput,
+): TransactionTime {
+  assertTransactionTime(input, "txTime");
+
+  if (input.supersededAt === undefined) {
+    return makeImmutable({
+      recordedAt: input.recordedAt,
+    });
+  }
+
+  return makeImmutable({
+    recordedAt: input.recordedAt,
+    supersededAt: input.supersededAt,
+  });
+}
+
+export {
+  assertTransactionTime,
+  createTransactionTime,
+  type CreateTransactionTimeInput,
+  type TransactionTime,
+};

package/src/core/domain/temporal/valid-time.ts

@@ -0,0 +1,57 @@
+import { InvariantViolationException } from "../../exceptions/invariant-violation-exception";
+import { makeImmutable } from "../../shared/immutable";
+import { assertValidDate } from "../../shared/temporal-guards";
+
+/**
+ * Represents business time (Valid Time).
+ * Defines when a piece of information is considered true or in effect in the real world.
+ */
+interface ValidTime {
+  /** Start of the validity window (inclusive). */
+  readonly from: Date;
+  /** End of the validity window (exclusive). When absent, the information is still in effect. */
+  readonly to?: Date;
+}
+
+type CreateValidTimeInput = ValidTime;
+
+function assertValidTime(
+  validTime: ValidTime,
+  fieldName: string = "validTime",
+): void {
+  assertValidDate(`${fieldName}.from`, validTime.from);
+
+  if (validTime.to === undefined) {
+    return;
+  }
+
+  assertValidDate(`${fieldName}.to`, validTime.to);
+
+  if (validTime.to.getTime() <= validTime.from.getTime()) {
+    throw new InvariantViolationException(
+      `${fieldName}.to must be later than ${fieldName}.from`,
+    );
+  }
+}
+
+function createValidTime(input: CreateValidTimeInput): ValidTime {
+  assertValidTime(input, "validTime");
+
+  if (input.to === undefined) {
+    return makeImmutable({
+      from: input.from,
+    });
+  }
+
+  return makeImmutable({
+    from: input.from,
+    to: input.to,
+  });
+}
+
+export {
+  assertValidTime,
+  createValidTime,
+  type CreateValidTimeInput,
+  type ValidTime,
+};

package/src/core/domain/value-object.ts

@@ -0,0 +1,30 @@
+import { type DeepReadonly, makeImmutable } from "../shared/immutable";
+import { type ContractVersion, version } from "../versioning/version";
+
+@version("1.0")
+abstract class ValueObject<T, P> {
+  public static readonly CONTRACT_VERSION: ContractVersion;
+  public readonly value: DeepReadonly<T>;
+
+  protected constructor(value: T) {
+    this.value = makeImmutable(value);
+  }
+
+  public get contractVersion(): ContractVersion {
+    return ValueObject.CONTRACT_VERSION;
+  }
+
+  protected finalize(): void {
+    Object.freeze(this);
+  }
+
+  public toJSON(): P {
+    return this.toPrimitive();
+  }
+
+  public abstract equals(other: this): boolean;
+
+  public abstract toPrimitive(): P;
+}
+
+export { type DeepReadonly, ValueObject };

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

@@ -0,0 +1,85 @@
+// Base application error for the domain/application layer.
+// Encapsulates a code, optional cause, and JSON-safe metadata.
+
+import type { AppErrorOptions, ErrorSeverity, JsonSafeRecord } from "./types";
+import { assertJsonSafeMetadata } from "./utils";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AppError (abstract base class)
+// ─────────────────────────────────────────────────────────────────────────────
+
+abstract class AppError extends Error {
+  public readonly code: string;
+  public readonly cause?: unknown;
+  public readonly metadata?: JsonSafeRecord;
+  public readonly type?: string;
+  public readonly severity?: ErrorSeverity;
+  public readonly createdAtIso: string;
+  public readonly publicMessage?: string;
+  /**
+   * Identifies a single execution "story" in the system. All operations
+   * related to the same logical flow must share the same correlationId.
+   */
+  public readonly correlationId?: string;
+  /**
+   * Identifies a specific technical request attempt (each retry may produce
+   * a new requestId), even when the correlationId stays the same.
+   */
+  public readonly requestId?: string;
+  /**
+   * Marks the business intent / idempotency key; stays the same across
+   * technical retries and multiple requests that represent the same intent.
+   */
+  public readonly commandId?: string;
+
+  protected constructor(
+    message: string,
+    code: string,
+    options?: AppErrorOptions,
+  ) {
+    super(message);
+
+    this.name = new.target.name;
+    this.code = code;
+    this.cause = options?.cause;
+    this.type = options?.type;
+    this.severity = options?.severity;
+    this.correlationId = options?.correlationId;
+    this.requestId = options?.requestId;
+    this.commandId = options?.commandId;
+    this.createdAtIso = options?.createdAtIso ?? new Date().toISOString();
+    this.publicMessage = options?.publicMessage;
+
+    this.metadata = options?.metadata
+      ? assertJsonSafeMetadata(options.metadata)
+      : undefined;
+
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  /**
+   * Returns a JSON-safe representation of the error.
+   * Does NOT include `cause` by default (to avoid leaking internal details).
+   */
+  public toJSON(): Record<string, unknown> {
+    const payload: Record<string, unknown> = {
+      name: this.name,
+      code: this.code,
+      type: this.type,
+      severity: this.severity,
+      message: this.message,
+      publicMessage: this.publicMessage,
+      createdAtIso: this.createdAtIso,
+      metadata: this.metadata,
+    };
+
+    if (this.correlationId !== undefined)
+      payload.correlationId = this.correlationId;
+    if (this.requestId !== undefined) payload.requestId = this.requestId;
+    if (this.commandId !== undefined) payload.commandId = this.commandId;
+
+    return payload;
+  }
+}
+
+export { AppError };

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

@@ -0,0 +1,171 @@
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions, ErrorSeverity } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+type AuthenticationErrorReason =
+  | "missing_token"
+  | "malformed_token"
+  | "invalid_token"
+  | "expired_token"
+  | "revoked_token"
+  | "invalid_credentials"
+  | "session_not_found"
+  | "session_expired"
+  | "unknown";
+
+type AuthenticationErrorMetadata = {
+  reason: AuthenticationErrorReason;
+  authScheme?: "bearer" | "cookie" | "basic" | "unknown";
+  tokenLocation?: "header" | "cookie" | "query" | "unknown";
+  expiresAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  details?: string;
+};
+
+type AuthenticationErrorFactoryOptions = Omit<
+  AuthenticationErrorMetadata,
+  "reason"
+> &
+  Omit<AppErrorOptions, "metadata">;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AuthenticationError
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AuthenticationError extends AppError {
+  public readonly reason: AuthenticationErrorReason;
+
+  private constructor(params: {
+    message: string;
+    code: string;
+    reason: AuthenticationErrorReason;
+    metadata?: Omit<AuthenticationErrorMetadata, "reason">;
+    cause?: unknown;
+    type?: string;
+    severity?: ErrorSeverity;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    createdAtIso?: string;
+    publicMessage?: string;
+  }) {
+    super(params.message, params.code, {
+      cause: params.cause,
+      metadata: {
+        reason: params.reason,
+        ...(params.metadata ?? {}),
+      },
+      type: params.type,
+      severity: params.severity,
+      correlationId: params.correlationId,
+      requestId: params.requestId,
+      commandId: params.commandId,
+      createdAtIso: params.createdAtIso,
+      publicMessage: params.publicMessage,
+    });
+
+    this.reason = params.reason;
+    Object.freeze(this);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Factory methods
+  // ─────────────────────────────────────────────────────────────────────────
+
+  static missingToken(
+    options?: AuthenticationErrorFactoryOptions,
+  ): AuthenticationError {
+    return new AuthenticationError({
+      message: "Missing credentials",
+      code: ErrorCodes.authentication.missingToken,
+      reason: "missing_token",
+      metadata: compactMetadata(options),
+      ...extractAppErrorOptions(options),
+    });
+  }
+
+  static invalidToken(
+    options?: AuthenticationErrorFactoryOptions & { cause?: unknown },
+  ): AuthenticationError {
+    return new AuthenticationError({
+      message: "Invalid credentials",
+      code: ErrorCodes.authentication.invalidToken,
+      reason: "invalid_token",
+      metadata: compactMetadata({
+        authScheme: options?.authScheme,
+        tokenLocation: options?.tokenLocation,
+        details: options?.details,
+        correlationId: options?.correlationId,
+        requestId: options?.requestId,
+      }),
+      ...extractAppErrorOptions(options),
+    });
+  }
+
+  static expiredToken(
+    options?: AuthenticationErrorFactoryOptions & { sessionId?: string },
+  ): AuthenticationError {
+    return new AuthenticationError({
+      message: "Expired credentials",
+      code: ErrorCodes.authentication.expiredToken,
+      reason: "expired_token",
+      metadata: compactMetadata(options),
+      ...extractAppErrorOptions(options),
+    });
+  }
+
+  static invalidCredentials(
+    options?: Pick<
+      AuthenticationErrorFactoryOptions,
+      | "correlationId"
+      | "requestId"
+      | "type"
+      | "severity"
+      | "createdAtIso"
+      | "publicMessage"
+    >,
+  ): AuthenticationError {
+    return new AuthenticationError({
+      message: "Invalid username or password",
+      code: ErrorCodes.authentication.invalidCredentials,
+      reason: "invalid_credentials",
+      metadata: compactMetadata(options),
+      ...extractAppErrorOptions(options),
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function extractAppErrorOptions(options?: Partial<AppErrorOptions>) {
+  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 | undefined {
+  if (!input) return undefined;
+
+  return Object.fromEntries(
+    Object.entries(input).filter(([, value]) => value !== undefined),
+  ) as T;
+}
+
+export { AuthenticationError };
+export type { AuthenticationErrorMetadata, AuthenticationErrorReason };

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

@@ -0,0 +1,204 @@
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions, ErrorSeverity } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+type AuthorizationErrorReason =
+  | "forbidden"
+  | "missing_role"
+  | "missing_capability"
+  | "out_of_scope"
+  | "outside_time_window"
+  | "policy_denied"
+  | "unknown";
+
+type AuthorizationRequirement = {
+  role?: string;
+  capability?: string;
+  scope?: string; // e.g.: "school:{id}" or "class:{id}"
+};
+
+type AuthorizationErrorMetadata = {
+  reason: AuthorizationErrorReason;
+
+  /** Stable action you evaluated (not an HTTP route — a "business action") */
+  action: string;
+
+  /** Resource identification (without leaking the full payload) */
+  resource?: { type: string; id?: string };
+
+  /** Optional: actor (do not include sensitive data) */
+  actor?: { userId: string; role?: string };
+
+  /** Optional: expected requirement */
+  required?: AuthorizationRequirement;
+
+  /** Optional: policy (when you already have PolicyEvaluation or similar) */
+  policyId?: string;
+  policyVersion?: number;
+  evaluatedAtIso?: string;
+  decision?: "allow" | "deny";
+  reasonCode?: string;
+
+  /** Optional: additional non-sensitive info */
+  details?: string;
+};
+
+/**
+ * Options for AuthorizationError factory methods.
+ * Combines metadata fields (except 'reason') with common AppError options.
+ */
+type AuthorizationErrorFactoryOptions = Omit<
+  AuthorizationErrorMetadata,
+  "reason"
+> &
+  Omit<AppErrorOptions, "metadata">;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AuthorizationError
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AuthorizationError extends AppError {
+  public readonly reason: AuthorizationErrorReason;
+
+  private constructor(params: {
+    message: string;
+    code: string;
+    reason: AuthorizationErrorReason;
+    metadata: AuthorizationErrorMetadata;
+    cause?: unknown;
+    type?: string;
+    severity?: ErrorSeverity;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    createdAtIso?: string;
+    publicMessage?: string;
+  }) {
+    super(params.message, params.code, {
+      cause: params.cause,
+      metadata: params.metadata,
+      type: params.type,
+      severity: params.severity,
+      correlationId: params.correlationId,
+      requestId: params.requestId,
+      commandId: params.commandId,
+      createdAtIso: params.createdAtIso,
+      publicMessage: params.publicMessage,
+    });
+
+    this.reason = params.reason;
+    Object.freeze(this);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Factories
+  // ─────────────────────────────────────────────────────────────────────────
+
+  static forbidden(
+    input: AuthorizationErrorFactoryOptions,
+  ): AuthorizationError {
+    return new AuthorizationError({
+      message: "Action not allowed",
+      code: ErrorCodes.authorization.forbidden,
+      reason: "forbidden",
+      metadata: { reason: "forbidden", ...extractMetadataOnly(input) },
+      ...extractAppErrorOptions(input),
+    });
+  }
+
+  static policyDenied(
+    input: AuthorizationErrorFactoryOptions & {
+      policyId: string;
+      policyVersion: number;
+      evaluatedAtIso: string;
+    },
+  ): AuthorizationError {
+    return new AuthorizationError({
+      message: "Action denied by policy",
+      code: ErrorCodes.authorization.policyDenied,
+      reason: "policy_denied",
+      metadata: {
+        reason: "policy_denied",
+        ...extractMetadataOnly(input),
+        decision: "deny",
+      },
+      ...extractAppErrorOptions(input),
+    });
+  }
+
+  static missingCapability(
+    input: AuthorizationErrorFactoryOptions & {
+      required: AuthorizationRequirement;
+    },
+  ): AuthorizationError {
+    return new AuthorizationError({
+      message: "Insufficient capability to perform the action",
+      code: ErrorCodes.authorization.missingCapability,
+      reason: "missing_capability",
+      metadata: {
+        reason: "missing_capability",
+        ...extractMetadataOnly(input),
+      },
+      ...extractAppErrorOptions(input),
+    });
+  }
+
+  static outOfScope(
+    input: AuthorizationErrorFactoryOptions & {
+      required?: AuthorizationRequirement;
+    },
+  ): AuthorizationError {
+    return new AuthorizationError({
+      message: "Action outside the allowed scope",
+      code: ErrorCodes.authorization.outOfScope,
+      reason: "out_of_scope",
+      metadata: { reason: "out_of_scope", ...extractMetadataOnly(input) },
+      ...extractAppErrorOptions(input),
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function extractAppErrorOptions(options?: Partial<AppErrorOptions>) {
+  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 extractMetadataOnly(
+  input: AuthorizationErrorFactoryOptions,
+): Omit<AuthorizationErrorMetadata, "reason"> {
+  const {
+    cause,
+    type,
+    severity,
+    correlationId,
+    requestId,
+    commandId,
+    createdAtIso,
+    publicMessage,
+    ...metadata
+  } = input;
+  return metadata;
+}
+
+export { AuthorizationError };
+export type {
+  AuthorizationErrorMetadata,
+  AuthorizationErrorReason,
+  AuthorizationRequirement,
+};

package/src/core/errors/business-rule-violation-error.ts

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