Package Exports

@lanitamarihuanera/suspicious-companies
@lanitamarihuanera/suspicious-companies/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@lanitamarihuanera/suspicious-companies) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@neko-arc/suspicious-companies

NestJS library for tracking suspicious companies with red flags, threat scoring, and fraud detection

Features

🚩 Red Flag Tracking - 15+ categories of suspicious activities
📊 Automatic Threat Scoring - 0-100 scale with algorithmic calculation
⚖️ Risk Classification - LOW/MEDIUM/HIGH/CRITICAL levels
🔍 Evidence Management - Track sources, documents, and testimony
📝 Investigation Workflow - INITIAL → ACTIVE → VERIFIED → RESOLVED
💾 MongoDB Integration - Persistent storage with full TypeScript support
🎯 Worker Protection - Identify fake job postings and employment scams
🇨🇱 Labor Law Support - Chilean labor law integration ready

Installation

npm install @neko-arc/suspicious-companies

Peer Dependencies

npm install @nestjs/common@^10.0.0 @nestjs/core@^10.0.0 mongodb@^6.0.0

Quick Start

1. Import the Module

import { Module } from '@nestjs/common';
import { SuspiciousCompanyModule } from '@neko-arc/suspicious-companies';

@Module({
  imports: [
    SuspiciousCompanyModule.forRoot({
      mongodbUri: process.env.MONGODB_URI,
      database: 'hannibal-forensic-archives',     // optional
      collection: 'suspicious-companies',         // optional
    }),
  ],
})
export class AppModule {}

2. Inject the Service

import { Injectable } from '@nestjs/common';
import {
  SuspiciousCompanyService,
  CreateSuspiciousCompanyDto,
  RedFlagCategory,
  RedFlagSeverity,
} from '@neko-arc/suspicious-companies';

@Injectable()
export class FraudDetectionService {
  constructor(
    private readonly suspiciousCompanyService: SuspiciousCompanyService,
  ) {}

  async investigateCompany(name: string) {
    const company = await this.suspiciousCompanyService.create({
      legalName: name,
      country: 'Chile',
      industry: 'Tourism',
      companyType: 'SPA',
      investigatedBy: ['Neko-Arc', 'Hannibal'],
      redFlags: [
        {
          category: RedFlagCategory.NO_DIGITAL_PRESENCE,
          severity: RedFlagSeverity.CRITICAL,
          title: 'No online presence',
          description: 'Company has zero digital footprint in 2025',
          discoveredBy: 'Neko-Arc',
        },
      ],
      digitalFootprint: {
        hasWebsite: false,
        hasSocialMedia: false,
        hasReviews: false,
        searchResultCount: 0,
      },
    });

    console.log(`Threat Score: ${company.overallThreatScore}/100`);
    console.log(`Risk Level: ${company.riskLevel}`);

    return company;
  }
}

API Reference

SuspiciousCompanyService

create(dto: CreateSuspiciousCompanyDto): Promise

Create a new suspicious company record with automatic threat scoring.

const company = await service.create({
  legalName: 'ACME Corporation SPA',
  country: 'Chile',
  industry: 'Technology',
  companyType: 'SPA',
  investigatedBy: ['Investigator 1'],
  redFlags: [...],
});

findById(companyId: string): Promise<ISuspiciousCompany | null>

Find a company by its unique ID.

const company = await service.findById('company-1731276000000');

findByName(legalName: string): Promise<ISuspiciousCompany[]>

Search companies by legal name (case-insensitive partial match).

const companies = await service.findByName('ACME');

findByRiskLevel(riskLevel: RiskLevel): Promise<ISuspiciousCompany[]>

Find all companies with a specific risk level.

import { RiskLevel } from '@neko-arc/suspicious-companies';

const critical = await service.findByRiskLevel(RiskLevel.CRITICAL);

update(companyId: string, dto: UpdateSuspiciousCompanyDto): Promise<ISuspiciousCompany | null>

Update a company record. Scores are automatically recalculated if relevant fields change.

const updated = await service.update('company-1731276000000', {
  rut: '12.345.678-9',
  legalStatus: {
    registrationVerified: true,
  },
});

getStatistics(): Promise

Get database statistics including total count and risk level breakdown.

const stats = await service.getStatistics();
// { total: 100, byRiskLevel: { critical: 10, high: 20, medium: 30, low: 40 } }

ThreatScoringService

calculateThreatScore(company: ISuspiciousCompany): number

Calculate threat score (0-100) based on red flags and company attributes.

getRiskLevel(score: number): RiskLevel

Determine risk level classification from threat score.

updateScores(company: ISuspiciousCompany): ISuspiciousCompany

Update company with calculated threat score and risk level.

Red Flag Categories

enum RedFlagCategory {
  NO_DIGITAL_PRESENCE = 'NO_DIGITAL_PRESENCE',
  FAKE_CREDENTIALS = 'FAKE_CREDENTIALS',
  LABOR_VIOLATIONS = 'LABOR_VIOLATIONS',
  UNPAID_WAGES = 'UNPAID_WAGES',
  FRAUDULENT_ACTIVITY = 'FRAUDULENT_ACTIVITY',
  TAX_EVASION = 'TAX_EVASION',
  HARASSMENT = 'HARASSMENT',
  WRONGFUL_TERMINATION = 'WRONGFUL_TERMINATION',
  SHELL_COMPANY = 'SHELL_COMPANY',
  DEFUNCT_BUSINESS = 'DEFUNCT_BUSINESS',
  SUSPICIOUS_REGISTRATION = 'SUSPICIOUS_REGISTRATION',
  NO_PHYSICAL_ADDRESS = 'NO_PHYSICAL_ADDRESS',
  UNREACHABLE = 'UNREACHABLE',
  FAKE_JOB_POSTINGS = 'FAKE_JOB_POSTINGS',
  INVESTMENT_SCAM = 'INVESTMENT_SCAM',
  OTHER = 'OTHER',
}

Threat Scoring Algorithm

The threat score (0-100) is calculated based on multiple factors:

Red Flag Severity

CRITICAL: +25 points per flag
WARNING: +15 points per flag
INFO: +5 points per flag

Digital Presence Penalties

No website: +20 points
No social media: +15 points
No reviews: +10 points
Low search results (<5): +15 points

Legal Status Penalties

Unverified registration: +20 points
Dormant status: +10 points
Labor violations: +25 points
Pending litigation: +15 points

Risk Levels

0-25: LOW - Minor concerns
26-50: MEDIUM - Suspicious patterns
51-75: HIGH - Significant red flags
76-100: CRITICAL - Severe threats

TypeScript Support

Full TypeScript support with complete type definitions included:

import {
  ISuspiciousCompany,
  IRedFlag,
  CreateSuspiciousCompanyDto,
  RiskLevel,
} from '@neko-arc/suspicious-companies';

const company: ISuspiciousCompany = await service.findById('company-123');

Use Cases

1. Worker Protection

Identify fraudulent job postings and protect job seekers:

const company = await service.create({
  legalName: 'Fake Recruitment Inc',
  country: 'Chile',
  industry: 'Recruitment',
  companyType: 'LTDA',
  investigatedBy: ['HR Security Team'],
  redFlags: [
    {
      category: RedFlagCategory.FAKE_JOB_POSTINGS,
      severity: RedFlagSeverity.CRITICAL,
      title: 'Fraudulent job ads',
      description: 'Company posting fake jobs to collect personal data',
      discoveredBy: 'Security Team',
    },
  ],
});

2. Investment Due Diligence

Verify companies before investment:

const companies = await service.findByName('Investment Opportunity LLC');

for (const company of companies) {
  if (company.riskLevel === RiskLevel.CRITICAL) {
    console.warn(`⚠️ HIGH RISK: ${company.legalName}`);
    console.warn(`Threat Score: ${company.overallThreatScore}/100`);
    console.warn(`Red Flags: ${company.redFlags.length}`);
  }
}

3. Labor Law Compliance

Track companies with labor violations:

const company = await service.create({
  legalName: 'Labor Violator SA',
  country: 'Chile',
  industry: 'Construction',
  companyType: 'SA',
  investigatedBy: ['Labor Inspector'],
  legalStatus: {
    hasLaborViolations: true,
    laborViolationDetails: ['Unpaid wages', 'Workplace harassment'],
  },
  redFlags: [
    {
      category: RedFlagCategory.UNPAID_WAGES,
      severity: RedFlagSeverity.CRITICAL,
      title: 'Systematic wage theft',
      description: '20 employees unpaid for 3 months',
      discoveredBy: 'Labor Inspector',
    },
  ],
});

Security

✅ No hardcoded credentials - All configuration via environment variables
✅ MongoDB connection string - Provided at runtime
✅ Private repository - Source code is private
✅ Public package - NPM distribution for easy installation
✅ Security audited - Pre-publishing security scan

Configuration Options

interface ISuspiciousCompanyModuleOptions {
  mongodbUri: string;      // Required: MongoDB Atlas connection string
  database?: string;       // Optional: Database name (default: 'hannibal-forensic-archives')
  collection?: string;     // Optional: Collection name (default: 'suspicious-companies')
}

Environment Variables

# .env file
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/?retryWrites=true&w=majority

// app.module.ts
SuspiciousCompanyModule.forRoot({
  mongodbUri: process.env.MONGODB_URI,
})

Examples

Complete Investigation Workflow

// 1. Create initial investigation
const company = await service.create({
  legalName: 'Suspicious Company SPA',
  country: 'Chile',
  industry: 'Tourism',
  companyType: 'SPA',
  investigatedBy: ['Neko-Arc', 'Hannibal'],
  digitalFootprint: {
    hasWebsite: false,
    searchResultCount: 0,
  },
  suspiciousPatterns: [
    'No digital presence despite being in tourism',
    'Formal legal structure without operations',
  ],
  tags: ['ghost-company', 'patagonia', 'tourism-fraud'],
});

// 2. Add verification after registry check
await service.update(company.companyId, {
  rut: '12.345.678-9',
  legalStatus: {
    registrationVerified: true,
    isActive: true,
    isDormant: false,
  },
});

// 3. Add new red flag after discovery
const updated = await service.findById(company.companyId);
updated.redFlags.push({
  flagId: `flag-${Date.now()}`,
  category: RedFlagCategory.SHELL_COMPANY,
  severity: RedFlagSeverity.CRITICAL,
  title: 'Active registration without operations',
  description: 'Registered and active but no commercial activity',
  discoveredDate: new Date(),
  discoveredBy: 'Hannibal',
  verified: true,
});

await service.update(company.companyId, {
  redFlags: updated.redFlags,
  investigationStatus: InvestigationStatus.VERIFIED,
});

License

MIT

Author

Javier Collipal

Repository

Source Code: Private (GitHub)
NPM Package: Public (npmjs.com)

Support

For issues and questions:

GitHub Issues: https://github.com/JavierCollipal/neko-suspicious-companies/issues

Part of the Neko-Arc Six-Personality System 🐾

Developed with forensic precision by:

🐾 Neko-Arc - Technical Coordination
🎭 Mario - Procedural Orchestration
🗡️ Noel - Precision Analysis
🎸 Glam - Worker Advocacy
🧠 Hannibal - Forensic Dissection
🧠 Tetora - Multi-Perspective Analysis