Documentation

Class

InvestigationService

InvestigationService()

Investigation Service (facade)

Constructor

# new InvestigationService()

Constructor

View Source services/investigation.service.js, line 16

Classes

InvestigationService

Methods

# addContradictionInPlace(investigation, contradiction) → {Partial.<IInvestigation>}

Adds contradiction metadata to a field on the investigation object (mutates in place).

Parameters:
Name Type Description
investigation Partial.<IInvestigation>

Investigation (partial) to mutate.
contradiction IContradictionInput

Contradiction descriptor.

View Source services/investigation.service.js, line 105

The same investigation object, mutated in place.

Partial.<IInvestigation>

# async checkAndUnlockStaleLocks() → {Promise.<number>}

Unlocks stale locks (older than configured threshold).

View Source services/investigation.service.js, line 291

Count of unlocked investigations.

Promise.<number>

# async cloneInvestigation(investigationId, userIdopt) → {Promise.<IInvestigation>}

Creates a clone of an investigation.

Parameters:
Name Type Attributes Description
investigationId string

Investigation id.
userId string <optional>

The ID of the user cloning the investigation (will be set as the new author).

View Source services/investigation.service.js, line 172

The cloned investigation.

Promise.<IInvestigation>

# async createInvestigation(createDto) → {Promise.<IInvestigation>}

Creates a new investigation.

Parameters:
Name Type Description
createDto ICreateInvestigationDto

DTO used to create the investigation.

View Source services/investigation.service.js, line 30

The created investigation.

Promise.<IInvestigation>

# async deleteInvestigationById(investigationId) → {Promise.<IDeleteInvestigationByIdResponse>}

Permanently deletes an investigation and related chat history.

Parameters:
Name Type Description
investigationId string

Investigation id.

View Source services/investigation.service.js, line 188

Delete result.

Promise.<IDeleteInvestigationByIdResponse>

# deleteInvestigationData(investigation) → {IInvestigation}

Clears investigation content and marks it as empty (mutates in place).

Parameters:
Name Type Description
investigation IInvestigation

Investigation to clear.

View Source services/investigation.service.js, line 180

The same investigation instance after mutation.

IInvestigation

# async ensureInvestigationAuthor(investigationId, authorId) → {Promise.<(IInvestigation|null)>}

Ensures author is set for an investigation.

Parameters:
Name Type Description
investigationId string

Investigation id.
authorId Types.ObjectId

Author id to set when missing.

View Source services/investigation.service.js, line 96

Updated investigation or null if no change.

Promise.<(IInvestigation|null)>

# async generateInvestigation(message, history, investigationMetadata) → {Promise.<(IAssistantInvestigationFormat|null)>}

AI: Generates a full investigation (text + objects + steps).

Parameters:
Name Type Description
message string

User message.
history FormattedHistory

Structured chat history.
investigationMetadata IMetadataDocument

Metadata document used as guide.

View Source services/investigation.service.js, line 163

AI response.

Promise.<(IAssistantInvestigationFormat|null)>

# async generateInvestigationObjects(message, history, investigationMetadata, investigation) → {Promise.<(IAssistantInvestigationFormat|null)>}

AI: Generates objects for an investigation.

Parameters:
Name Type Description
message string

User message.
history string

Chat history.
investigationMetadata string

Guide/metadata YAML.
investigation string

Investigation YAML.

View Source services/investigation.service.js, line 142

AI response.

Promise.<(IAssistantInvestigationFormat|null)>

# async generateInvestigationSteps(message, history, investigationMetadata, investigation) → {Promise.<(IAssistantInvestigationFormat|null)>}

AI: Generates steps for an investigation.

Parameters:
Name Type Description
message string

User message.
history string

Chat history.
investigationMetadata string

Guide/metadata YAML.
investigation string

Investigation YAML.

View Source services/investigation.service.js, line 153

AI response.

Promise.<(IAssistantInvestigationFormat|null)>

# async generateInvestigationWithoutStepsAndObjects(message, history, investigationMetadata) → {Promise.<(IAssistantInvestigationFormat|null)>}

AI: Generates investigation text fields without steps/objects.

Parameters:
Name Type Description
message string

User message.
history string

Chat history.
investigationMetadata string

Guide/metadata YAML.

View Source services/investigation.service.js, line 131

AI response.

Promise.<(IAssistantInvestigationFormat|null)>

# async getFieldHistory(investigationId, fieldPath, limitopt) → {Promise.<{fieldPath: string, history: Array.<*>, totalCount: number}>}

Gets history entries for a specific field.

Parameters:
Name Type Attributes Default Description
investigationId string

Investigation id.
fieldPath string

Field path (e.g. "title", "steps.0.title").
limit number <optional>
 50

Max number of entries (defaults to 50).

View Source services/investigation.service.js, line 62

Field history data.

Promise.<{fieldPath: string, history: Array.<*>, totalCount: number}>

# async getFilterMetadata() → {Promise.<IInvestigationFilterMetadataDto>}

Retrieves available filter metadata for investigations list.

View Source services/investigation.service.js, line 121

Filter metadata response.

Promise.<IInvestigationFilterMetadataDto>

# async getInvestigationById(investigationId) → {Promise.<IInvestigation>}

Retrieves a single investigation by id (version-aware).

Parameters:
Name Type Description
investigationId string

Investigation id.

View Source services/investigation.service.js, line 38

The investigation document.

Promise.<IInvestigation>

# async getInvestigationVersions(investigationId, limitopt) → {Promise.<IInvestigationVersionListResponse>}

Lists versions for an investigation.

Parameters:
Name Type Attributes Default Description
investigationId string

Investigation id.
limit number <optional>
 20

Max number of versions (defaults to 20).

View Source services/investigation.service.js, line 71

Versions list response.

Promise.<IInvestigationVersionListResponse>

# async getInvestigations(searchDto, grpcClientopt) → {Promise.<IInvestigationListResponseDto>}

Retrieves investigations with filtering/sorting/sectioning.

Parameters:
Name Type Attributes Description
searchDto IInvestigationSearchDto

Search and pagination parameters.
grpcClient AuthGrpcService <optional>

Optional gRPC client for profile enrichment.

View Source services/investigation.service.js, line 114

Investigation list response.

Promise.<IInvestigationListResponseDto>

# async lockInvestigation(investigationId, userId) → {Promise.<IInvestigation>}

Locks investigation for editing.

Parameters:
Name Type Description
investigationId string

Investigation id.
userId string

User id acquiring the lock.

View Source services/investigation.service.js, line 275

Updated investigation.

Promise.<IInvestigation>

# async redoInvestigation(investigationId) → {Promise.<IInvestigation>}

Moves currentVersionIndex forward (redo).

Parameters:
Name Type Description
investigationId string

Investigation id.

View Source services/investigation.service.js, line 87

Investigation restored to the next version.

Promise.<IInvestigation>

# async regenerateOtherFields(investigationId, fieldName, updatedByopt, historyopt) → {Promise.<IInvestigation>}

Orchestrates 3-step regeneration and writes results back to DB.

Parameters:
Name Type Attributes Default Description
investigationId string

Investigation id.
fieldName string

Field name used as regeneration source.
updatedBy Types.ObjectId | null <optional>
 null

User id who triggered regeneration.
history string <optional>
 -

Chat history YAML (defaults to "-").

View Source services/investigation.service.js, line 258

Updated investigation.

Promise.<IInvestigation>

# async regenerateOtherFieldsObjects(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

AI regeneration step 2: objects.

Parameters:
Name Type Attributes Default Description
fieldName string

Field name used as regeneration source.
fieldValue string

Source field value.
investigation string

Current investigation YAML.
investigationMetadata string

Guide/metadata YAML.
history string <optional>
 -

Chat history YAML (defaults to "-").
contradictionInfo object <optional>

Optional contradiction info.
contradictionReason string | null <optional>

Contradiction reason (if any).
targetFieldName string | null <optional>

Target field name related to contradiction.
isContradicting boolean <optional>

Whether the source field is contradicting.

View Source services/investigation.service.js, line 231

AI response.

Promise.<(IAssistantInvestigationFormat|null)>

# async regenerateOtherFieldsSteps(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

AI regeneration step 3: steps.

Parameters:
Name Type Attributes Default Description
fieldName string

Field name used as regeneration source.
fieldValue string

Source field value.
investigation string

Current investigation YAML.
investigationMetadata string

Guide/metadata YAML.
history string <optional>
 -

Chat history YAML (defaults to "-").
contradictionInfo object <optional>

Optional contradiction info.
contradictionReason string | null <optional>

Contradiction reason (if any).
targetFieldName string | null <optional>

Target field name related to contradiction.
isContradicting boolean <optional>

Whether the source field is contradicting.

View Source services/investigation.service.js, line 247

AI response.

Promise.<(IAssistantInvestigationFormat|null)>

# async regenerateOtherFieldsWithoutStepsAndObjects(fieldName, fieldValue, investigation, investigationMetadata, historyopt, contradictionInfoopt) → {Promise.<(IAssistantInvestigationFormat|null)>}

AI regeneration step 1: text fields (no steps/objects).

Parameters:
Name Type Attributes Default Description
fieldName string

Field name used as regeneration source.
fieldValue string

Source field value.
investigation string

Current investigation YAML.
investigationMetadata string

Guide/metadata YAML.
history string <optional>
 -

Chat history YAML (defaults to "-").
contradictionInfo object <optional>

Optional contradiction info.
contradictionReason string | null <optional>

Contradiction reason (if any).
targetFieldName string | null <optional>

Target field name related to contradiction.
isContradicting boolean <optional>

Whether the source field is contradicting.

View Source services/investigation.service.js, line 215

AI response.

Promise.<(IAssistantInvestigationFormat|null)>

# async toggleInvestigationDevelopment(investigationId) → {Promise.<IInvestigation>}

Toggles investigation status to/from IN_DEVELOPMENT.

Parameters:
Name Type Description
investigationId string

Investigation id.

View Source services/investigation.service.js, line 266

Updated investigation.

Promise.<IInvestigation>

# async undoInvestigation(investigationId) → {Promise.<IInvestigation>}

Moves currentVersionIndex back (undo).

Parameters:
Name Type Description
investigationId string

Investigation id.

View Source services/investigation.service.js, line 79

Investigation restored to the previous version.

Promise.<IInvestigation>

# async unlockInvestigation(investigationId, userId) → {Promise.<IInvestigation>}

Unlocks investigation.

Parameters:
Name Type Description
investigationId string

Investigation id.
userId string

User id releasing the lock.

View Source services/investigation.service.js, line 284

Updated investigation.

Promise.<IInvestigation>

# async updateInvestigation(investigationId, updateData, objopt) → {Promise.<IUpdateInvestigationResponse>}

Updates an investigation with the new API format.

Parameters:
Name Type Attributes Description
investigationId string

Investigation id.
updateData IUpdateInvestigationDto

Update payload.
obj object <optional>

Optional update options.
needsBuildUpdate boolean <optional>

Whether to rebuild update fields with the builder.
updatedBy Types.ObjectId | null <optional>

User id performing the update.
isAiGenerated boolean <optional>

Whether the update is AI-generated.
skipVersioning boolean <optional>

Whether to skip versioning for this update.

View Source services/investigation.service.js, line 52

Update result.

Promise.<IUpdateInvestigationResponse>

# async updateInvestigationByVersion(oldInvestigation, investigation, userIdopt, isUserChangeExistopt) → {Promise.<IInvestigation>}

Adds a new version entry and updates currentVersionIndex (legacy flow).

Parameters:
Name Type Attributes Default Description
oldInvestigation IInvestigation

Previous investigation state.
investigation IInvestigation

Current investigation document to update.
userId ObjectId | null <optional>

User id who made the change.
isUserChangeExist boolean <optional>
 false

Whether the change was made by user (defaults to false).

View Source services/investigation.service.js, line 199

Updated investigation document.

Promise.<IInvestigation>