@cullet/erp-core 1.0.0

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

@@ -0,0 +1,246 @@
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+import type { AppErrorOptions } from "./types";
+
+/**
+ * Conflict kinds we want to distinguish semantically.
+ */
+type ConflictKind = "already_exists" | "duplicate" | "unique_violation";
+
+/**
+ * Metadata attached to conflicts without exposing sensitive values.
+ */
+type ConflictErrorMetadata = {
+  kind: ConflictKind;
+  entity: string;
+  operation?: string;
+  field?: string;
+  constraintName?: string;
+  existingId?: string;
+  valueHash?: string;
+  valuePreview?: string;
+  detectedAtIso?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  hint?: string;
+};
+
+type UniqueConstraintViolation = {
+  kind: "unique_violation";
+  constraintName?: string;
+  table?: string;
+  columns?: string[];
+};
+
+abstract class ConflictError extends AppError {
+  public readonly kind: ConflictKind;
+
+  protected constructor(
+    params: {
+      message: string;
+      code: string;
+      kind: ConflictKind;
+      metadata: Omit<ConflictErrorMetadata, "kind">;
+      cause?: unknown;
+    } & AppErrorOptions,
+  ) {
+    super(params.message, params.code, {
+      ...params,
+      metadata: {
+        kind: params.kind,
+        ...params.metadata,
+      },
+    });
+
+    this.kind = params.kind;
+    Object.freeze(this);
+  }
+}
+
+class AlreadyExistsError extends ConflictError {
+  private constructor(
+    input: {
+      metadata: Omit<ConflictErrorMetadata, "kind">;
+      cause?: unknown;
+    } & AppErrorOptions,
+  ) {
+    super({
+      message: "A matching record already exists for the requested operation",
+      code: ErrorCodes.conflict.alreadyExists,
+      kind: "already_exists",
+      ...input,
+    });
+  }
+
+  static detected(input: {
+    entity: string;
+    operation?: string;
+    field?: string;
+    existingId?: string;
+    valueHash?: string;
+    valuePreview?: string;
+    detectedAtIso?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    hint?: string;
+    cause?: unknown;
+  }): AlreadyExistsError {
+    return new AlreadyExistsError({
+      metadata: {
+        entity: input.entity,
+        operation: input.operation ?? "create",
+        field: input.field,
+        existingId: input.existingId,
+        valueHash: input.valueHash,
+        valuePreview: input.valuePreview,
+        detectedAtIso: input.detectedAtIso,
+        correlationId: input.correlationId,
+        requestId: input.requestId,
+        commandId: input.commandId,
+        hint: input.hint ?? "Verify existing records before retrying.",
+      },
+      cause: input.cause,
+    });
+  }
+}
+
+class DuplicateError extends ConflictError {
+  private constructor(
+    input: {
+      metadata: Omit<ConflictErrorMetadata, "kind">;
+      cause?: unknown;
+    } & AppErrorOptions,
+  ) {
+    super({
+      message: "Conflict: an existing record violates uniqueness",
+      code: ErrorCodes.conflict.duplicate,
+      kind: "duplicate",
+      ...input,
+    });
+  }
+
+  static detected(input: {
+    entity: string;
+    operation?: string;
+    field?: string;
+    constraintName?: string;
+    existingId?: string;
+    valueHash?: string;
+    valuePreview?: string;
+    detectedAtIso?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    hint?: string;
+    cause?: unknown;
+  }): DuplicateError {
+    return new DuplicateError({
+      metadata: {
+        entity: input.entity,
+        operation: input.operation,
+        field: input.field,
+        constraintName: input.constraintName,
+        existingId: input.existingId,
+        valueHash: input.valueHash,
+        valuePreview: input.valuePreview,
+        detectedAtIso: input.detectedAtIso,
+        correlationId: input.correlationId,
+        requestId: input.requestId,
+        commandId: input.commandId,
+        hint:
+          input.hint ??
+          "Adjust the data so it does not duplicate existing records.",
+      },
+      cause: input.cause,
+    });
+  }
+}
+
+class UniqueConstraintViolationError extends ConflictError {
+  private constructor(
+    input: {
+      metadata: Omit<ConflictErrorMetadata, "kind"> & {
+        violation: UniqueConstraintViolation;
+      };
+      cause?: unknown;
+    } & AppErrorOptions,
+  ) {
+    super({
+      message: "Uniqueness violation in storage",
+      code: ErrorCodes.conflict.uniqueViolation,
+      kind: "unique_violation",
+      ...input,
+    });
+  }
+
+  static detected(input: {
+    entity: string;
+    operation?: string;
+    constraintName?: string;
+    table?: string;
+    columns?: string[];
+    detectedAtIso?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    cause?: unknown;
+  }): UniqueConstraintViolationError {
+    return new UniqueConstraintViolationError({
+      metadata: {
+        entity: input.entity,
+        operation: input.operation,
+        constraintName: input.constraintName,
+        detectedAtIso: input.detectedAtIso,
+        correlationId: input.correlationId,
+        requestId: input.requestId,
+        commandId: input.commandId,
+        violation: {
+          kind: "unique_violation",
+          constraintName: input.constraintName,
+          table: input.table,
+          columns: input.columns,
+        },
+        hint: "Uniqueness conflict detected in the database.",
+      },
+      cause: input.cause,
+    });
+  }
+}
+
+function translateUniqueViolationToDuplicate(input: {
+  entity: string;
+  operation?: string;
+  violation: UniqueConstraintViolation;
+  field?: string;
+  ctx?: {
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    nowIso?: string;
+  };
+  cause?: unknown;
+}): DuplicateError {
+  return DuplicateError.detected({
+    entity: input.entity,
+    operation: input.operation,
+    field: input.field,
+    constraintName: input.violation.constraintName,
+    detectedAtIso: input.ctx?.nowIso,
+    correlationId: input.ctx?.correlationId,
+    requestId: input.ctx?.requestId,
+    commandId: input.ctx?.commandId,
+    cause: input.cause,
+  });
+}
+
+export {
+  AlreadyExistsError,
+  ConflictError,
+  DuplicateError,
+  translateUniqueViolationToDuplicate,
+  UniqueConstraintViolationError,
+};
+
+export type { ConflictErrorMetadata, ConflictKind, UniqueConstraintViolation };

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

@@ -0,0 +1,60 @@
+const ErrorCodes = {
+  authentication: {
+    missingToken: "sec.authn.missing_token",
+    invalidToken: "sec.authn.invalid_token",
+    expiredToken: "sec.authn.expired_token",
+    invalidCredentials: "sec.authn.invalid_credentials",
+  },
+  authorization: {
+    forbidden: "sec.authz.forbidden",
+    policyDenied: "sec.authz.policy_denied",
+    missingCapability: "sec.authz.missing_capability",
+    outOfScope: "sec.authz.out_of_scope",
+  },
+  businessRuleViolation: "business_rule_violation",
+  conflict: {
+    alreadyExists: "conf.already_exists",
+    duplicate: "conf.duplicate",
+    uniqueViolation: "conf.unique_violation",
+  },
+  idempotency: {
+    keyMissing: "idemp.key_missing",
+    inProgress: "idemp.in_progress",
+    payloadMismatch: "idemp.payload_mismatch",
+    replayNotSupported: "idemp.replay_not_supported",
+  },
+  integration: {
+    timeout: "int.timeout",
+    unreachable: "int.unreachable",
+    badResponse: "int.bad_response",
+  },
+  legacyIncompatible: "legacy_incompatible",
+  notFound: "not_found",
+  serialization: {
+    deserializePrefix: "ser.des",
+    serializePrefix: "ser.ser",
+  },
+  temporal: {
+    expired: "tmp.expired",
+    notYetValid: "tmp.not_yet_valid",
+  },
+  unexpected: "unexpected",
+  validation: "validation_error",
+} as const;
+
+type SerializationCodeDirection = "deserialize" | "serialize";
+
+function serializationErrorCode(
+  direction: SerializationCodeDirection,
+  category: string,
+): string {
+  const prefix =
+    direction === "deserialize"
+      ? ErrorCodes.serialization.deserializePrefix
+      : ErrorCodes.serialization.serializePrefix;
+
+  return `${prefix}.${category}`;
+}
+
+export { ErrorCodes, serializationErrorCode };
+export type { SerializationCodeDirection };

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

@@ -0,0 +1,372 @@
+import { payloadHash, sha256Hex, stableStringify } from "../shared/hashing";
+
+import { AppError } from "./app-error";
+import { ErrorCodes } from "./error-codes";
+
+export type IdempotencyFailureKind =
+  | "key_missing"
+  | "in_progress"
+  | "payload_mismatch"
+  | "replay_not_supported"
+  | "unknown";
+
+export type IdempotencyErrorMetadata = {
+  kind: IdempotencyFailureKind;
+  operation: string;
+  scope?: string;
+  entity?: string;
+  keyHash?: string;
+  keyPreview?: string;
+  incomingPayloadHash?: string;
+  existingPayloadHash?: string;
+  idempotencyRecordId?: string;
+  correlationId?: string;
+  requestId?: string;
+  commandId?: string;
+  detectedAtIso?: string;
+  hint?: string;
+  details?: string;
+};
+
+type IdempotencyErrorConstructorInput = {
+  message: string;
+  code: string;
+  kind: IdempotencyFailureKind;
+  metadata: Omit<IdempotencyErrorMetadata, "kind">;
+  cause?: unknown;
+};
+
+abstract class IdempotencyError extends AppError {
+  public readonly kind: IdempotencyFailureKind;
+
+  protected constructor(input: IdempotencyErrorConstructorInput) {
+    super(input.message, input.code, {
+      cause: input.cause,
+      metadata: { kind: input.kind, ...input.metadata },
+    });
+
+    this.kind = input.kind;
+    Object.freeze(this);
+  }
+
+  static keyMissing(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyKeyMissingError {
+    return IdempotencyKeyMissingError.detected(input);
+  }
+
+  static inProgress(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyInProgressError {
+    return IdempotencyInProgressError.detected(input);
+  }
+
+  static payloadMismatch(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    incomingPayloadHash?: string;
+    existingPayloadHash?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyPayloadMismatchError {
+    return IdempotencyPayloadMismatchError.detected(input);
+  }
+
+  static replayNotSupported(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyReplayNotSupportedError {
+    return IdempotencyReplayNotSupportedError.detected(input);
+  }
+}
+
+class IdempotencyKeyMissingError extends IdempotencyError {
+  private constructor(input: {
+    metadata: Omit<IdempotencyErrorMetadata, "kind">;
+    cause?: unknown;
+  }) {
+    super({
+      message: "Idempotency key/commandId missing for the requested operation",
+      code: ErrorCodes.idempotency.keyMissing,
+      kind: "key_missing",
+      metadata: input.metadata,
+      cause: input.cause,
+    });
+  }
+
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyKeyMissingError {
+    return new IdempotencyKeyMissingError({
+      cause: input.cause,
+      metadata: {
+        operation: input.operation,
+        scope: input.scope,
+        entity: input.entity,
+        correlationId: input.correlationId,
+        requestId: input.requestId,
+        commandId: input.commandId,
+        detectedAtIso: input.detectedAtIso,
+        hint:
+          input.hint ??
+          "Send a commandId/idempotency key to prevent duplicate processing.",
+        details: input.details,
+      },
+    });
+  }
+}
+
+class IdempotencyInProgressError extends IdempotencyError {
+  private constructor(input: {
+    metadata: Omit<IdempotencyErrorMetadata, "kind">;
+    cause?: unknown;
+  }) {
+    super({
+      message: "The same business intent is already being processed",
+      code: ErrorCodes.idempotency.inProgress,
+      kind: "in_progress",
+      metadata: input.metadata,
+      cause: input.cause,
+    });
+  }
+
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyInProgressError {
+    const resolved = resolveKeyIdentity(
+      input.key,
+      input.keyHash,
+      input.keyPreview,
+    );
+
+    return new IdempotencyInProgressError({
+      cause: input.cause,
+      metadata: {
+        operation: input.operation,
+        scope: input.scope,
+        entity: input.entity,
+        keyHash: resolved.keyHash,
+        keyPreview: resolved.keyPreview,
+        idempotencyRecordId: input.idempotencyRecordId,
+        correlationId: input.correlationId,
+        requestId: input.requestId,
+        commandId: input.commandId,
+        detectedAtIso: input.detectedAtIso,
+        hint: input.hint ?? "Wait for completion and retry using the same key.",
+        details: input.details,
+      },
+    });
+  }
+}
+
+class IdempotencyPayloadMismatchError extends IdempotencyError {
+  private constructor(input: {
+    metadata: Omit<IdempotencyErrorMetadata, "kind">;
+    cause?: unknown;
+  }) {
+    super({
+      message: "The idempotency key was reused with a different payload",
+      code: ErrorCodes.idempotency.payloadMismatch,
+      kind: "payload_mismatch",
+      metadata: input.metadata,
+      cause: input.cause,
+    });
+  }
+
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    incomingPayloadHash?: string;
+    existingPayloadHash?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyPayloadMismatchError {
+    const resolved = resolveKeyIdentity(
+      input.key,
+      input.keyHash,
+      input.keyPreview,
+    );
+
+    return new IdempotencyPayloadMismatchError({
+      cause: input.cause,
+      metadata: {
+        operation: input.operation,
+        scope: input.scope,
+        entity: input.entity,
+        keyHash: resolved.keyHash,
+        keyPreview: resolved.keyPreview,
+        incomingPayloadHash: input.incomingPayloadHash,
+        existingPayloadHash: input.existingPayloadHash,
+        idempotencyRecordId: input.idempotencyRecordId,
+        correlationId: input.correlationId,
+        requestId: input.requestId,
+        commandId: input.commandId,
+        detectedAtIso: input.detectedAtIso,
+        hint:
+          input.hint ??
+          "Use a new idempotency key for a new intent. The same key should only be reused for retries of the same payload.",
+        details: input.details,
+      },
+    });
+  }
+}
+
+class IdempotencyReplayNotSupportedError extends IdempotencyError {
+  private constructor(input: {
+    metadata: Omit<IdempotencyErrorMetadata, "kind">;
+    cause?: unknown;
+  }) {
+    super({
+      message:
+        "Re-execution detected, but replay of the previous result is not implemented",
+      code: ErrorCodes.idempotency.replayNotSupported,
+      kind: "replay_not_supported",
+      metadata: input.metadata,
+      cause: input.cause,
+    });
+  }
+
+  static detected(input: {
+    operation: string;
+    scope?: string;
+    entity?: string;
+    key?: string;
+    keyHash?: string;
+    keyPreview?: string;
+    idempotencyRecordId?: string;
+    correlationId?: string;
+    requestId?: string;
+    commandId?: string;
+    detectedAtIso?: string;
+    hint?: string;
+    details?: string;
+    cause?: unknown;
+  }): IdempotencyReplayNotSupportedError {
+    const resolved = resolveKeyIdentity(
+      input.key,
+      input.keyHash,
+      input.keyPreview,
+    );
+
+    return new IdempotencyReplayNotSupportedError({
+      cause: input.cause,
+      metadata: {
+        operation: input.operation,
+        scope: input.scope,
+        entity: input.entity,
+        keyHash: resolved.keyHash,
+        keyPreview: resolved.keyPreview,
+        idempotencyRecordId: input.idempotencyRecordId,
+        correlationId: input.correlationId,
+        requestId: input.requestId,
+        commandId: input.commandId,
+        detectedAtIso: input.detectedAtIso,
+        hint:
+          input.hint ??
+          "Try again later, or enable result replay for full idempotency.",
+        details: input.details,
+      },
+    });
+  }
+}
+
+function resolveKeyIdentity(
+  key?: string,
+  keyHash?: string,
+  keyPreview?: string,
+): { keyHash?: string; keyPreview?: string } {
+  const preview =
+    keyPreview ?? (key ? (key.length <= 8 ? key : key.slice(0, 8)) : undefined);
+
+  return {
+    keyHash: keyHash,
+    keyPreview: preview,
+  };
+}
+
+export {
+  IdempotencyError,
+  IdempotencyKeyMissingError,
+  IdempotencyInProgressError,
+  IdempotencyPayloadMismatchError,
+  IdempotencyReplayNotSupportedError,
+  sha256Hex,
+  stableStringify,
+  payloadHash,
+};