npm package: @quandis/qbo4.permutator
Description: ASP.NET Core class library that exposes name permutation and parsing as a REST API and ships a Lit-based web component (`<qbo-permutator>`) for interactive use.
Author: Quandis, Inc.
Latest version: 4.0.1-CI-20260406-162619

# qbo4.Permutator.Web

ASP.NET Core class library that exposes name permutation and parsing as a REST API and ships a Lit-based web component (`<qbo-permutator>`) for interactive use.

## What it does

Contact and company name data is often entered inconsistently — nicknames, hyphenated last names, middle initials, entity suffixes like "LLC", and so on. The Permutator solves this by taking a raw name, parsing it into structured parts, and generating every reasonable variation so that downstream search and matching operations can work against a complete alias set rather than just what was typed.

This project is the hosting layer. It wires the parsing and permutation engines to HTTP endpoints and provides a browser UI for testing and inspection.

## REST API

All endpoints are under the `/permutator` route prefix.

### `POST /permutator/parse-permutate`

Parses a contact name into structured parts and then generates all permutations in one call.

**Request**
```json
{
  "contact": {
    "firstName": "John",
    "middleName": "Allen",
    "lastName": "Smith-Jones",
    "suffix": "Jr"
  },
  "options": {
    "transpose": true,
    "toggleMiddleName": true,
    "forceHyphen": false
  }
}
```

**Response** — flat array of `Contact` objects. Each item includes a `source` field indicating which option produced it (e.g. `"Transpose"`, `"ToggleMiddleName"`, `"ForceHyphen"`, `"MixedCaseSplit"`, `"IncludeSuffix"`, or `null` for base variations). Multi-source items are comma-separated (e.g. `"Transpose,ToggleMiddleName"`).

---

### `POST /permutator/permutate`

Generates permutations from an already-parsed contact (skips the parse step).

Same request/response shape as `parse-permutate`.

---

### `POST /permutator/parse-company`

Parses a raw company name string into distinct variations, splitting on common delimiters (`dba`, `aka`, `fka`, `/`) and recognising entity types (`LLC`, `Inc`, `Corp`, `LLP`, etc.).

**Request**
```json
{
  "company": "Acme Corp dba The Rocket Company, LLC",
  "options": {
    "includeEntity": "OriginalOnly"
  }
}
```

**Response** — array of `CompanyVariation` objects (`name`, `entity`, `contactTemplate`).

---

## Parse options (`ParsePermutateOptions`)

| Option | Type | Default | Effect |
|---|---|---|---|
| `parseModel` | enum | `NameSegmentParse` | Selects the parser/permutator implementation (`NameSegmentParse`, `None`, `AI`) |
| `keepOriginal` | bool | `true` | Include the original unparsed name in results |
| `parsePrefix` | bool | `true` | Extract titles (Mr, Dr, etc.) from the first-name field |
| `parseSuffix` | bool | `true` | Extract suffixes (Jr, Sr, Esq, etc.) from the last-name field |
| `middleNameParse` | enum | `None` | How to handle middle names: `None`, `Share`, `ShareMerge`, `AppendMiddleInitial`, `AppendMiddleInitialAll` |
| `toggleMiddleName` | bool | `false` | Generate variations both with and without the middle name |
| `togglePrimaryName` | bool | `false` | Generate variations with only the last name (no first/middle) |
| `transpose` | bool | `false` | Swap the order of compound last-name parts (e.g. "Smith Jones" → "Jones Smith") |
| `mergeNameParts` | bool | `false` | Generate merged forms of compound names (e.g. "Smith Jones" → "SmithJones") |
| `forceHyphen` | bool | `false` | For two-part space-separated last names, also generate a hyphenated form |
| `suppressHyphenParse` | enum | `Never` | Control whether existing hyphens in a last name are split: `Never`, `MultipleOnly`, `Always` |
| `mixedCaseSplit` | bool | `false` | Split camelCase last names into separate parts |
| `includeSuffix` | enum | `None` | Append the name suffix to variations: `None`, `OriginalOnly`, `All` |
| `removeNobiliaryParticiple` | bool | `false` | Strip nobiliary particles (von, de, van, etc.) when splitting compound names |
| `maxPermutationCount` | int | `50` | Hard limit on the number of permutations returned |

## Web component

The project ships a Lit custom element for browser-based testing and inspection. Register the script and use the element:

```html
<script type="module" src="/permutator/js/Program.js"></script>

<qbo-permutator base-url="/"></qbo-permutator>
```

### Features

- **Contact / Company mode toggle** — switch between person name and company name workflows
- **Options panel** — collapsible panel exposing every `ParsePermutateOptions` and `ParseCompanyOptions` field
- **Results table** — displays parsed and permutated variations with columns for Full Name, Prefix, First, Middle, Last, Suffix, Template, Type, and Source
- **Source filter chips** — after a result is returned, clickable chips appear for each distinct `source` value (e.g. `Transpose`, `ToggleMiddleName`). Selecting a chip filters the table to show only variations produced by that option. Multiple chips can be active at once; a Clear button resets the filter
- **Export Results** — downloads the currently displayed (filtered) results as a JSON file named `permutator-results-{lastName}.json`
- **Export Settings** — downloads the full request payload (contact/company input + options) as `permutator-settings.json`, ready to replay directly against the API

## Dependency injection

Register via `AddPermutatorUI` along with the parser and permutator implementations:

```csharp
services.AddNameSegmentParser(configuration);   // registers IParser + ICompanyParser
services.AddAdvancedPermutator(configuration);  // registers IPermutator
services.AddPermutatorUI(configuration.GetSection(PermutatorWebOptions.SectionName));
```

The convention-based `ConfigureProject()` host builder extension will discover and call these automatically when the assemblies are referenced.

## Project structure

```
Controllers/
  PermutatorController.cs     REST endpoints
Extensions/
  ServiceCollectionExtensions.cs   AddPermutatorUI registration
src/
  qbo-permutator.ts           Lit web component
  styles.ts                   Component CSS (generated — edit scss/qbo-permutator.scss)
scss/
  qbo-permutator.scss         Source styles
wwwroot/
  js/                         Compiled TypeScript output
  css/                        Compiled and purged CSS output
```

> **Note:** `src/styles.ts` is generated by the build pipeline (`npm run sass`). Always edit `scss/qbo-permutator.scss` — do not edit `styles.ts` directly.