@openutility/experian-angular-services

Experian Angular Service

This serviuce will generate a Linked Effect tided to an Experian Search and Format request.

BASIC SETUP

install the library

npm install @openUtility/experian-angular-services

inject the token

import { OPEN_UTILITY_EXPERIAN_SERVICE_CONFIG_TK } from '@openutility/experian-services';

export const config: ApplicationConfig = {
  providers: [
    { provide: OPEN_UTILITY_EXPERIAN_SERVICE_CONFIG_TK, useValue: {token: '{EXPERIAN_TOKEN_HERE}' } },
  ],
};

the configuration can also accept a signal; NOTE: updating the configuration signal will NOT trigger a refresh event on the Linked Effect (IE a new search will not be triggered).

import { OPEN_UTILITY_EXPERIAN_SERVICE_CONFIG_TK, ExperianServiceConfig } from '@openutility/experian-services';

function ExperianLookupConfigFactory() {
    const _http = inject(HttpClient);
    const rply = signal<ExperianServiceConfig>({token: ''});
    lastValueFrom(_http.get('API_URL')).then(d => rply.update(f => ({...f, token: d.token})));
    return rply.asReadonly();
}

export const config: ApplicationConfig = {
  providers: [
    { provide: OPEN_UTILITY_EXPERIAN_SERVICE_CONFIG_TK, useFactory: ExperianLookupConfigFactory, deps: [HttpClient] },
  ],
};

You can then consume the content with some code like the following

import { ExperianService } from '@openutility/experian-services';
import { JsonPipe } from '@angular/common';
import { Component, ChangeDetectionStrategy, inject, signal, OnDestroy, computed } from '@angular/core';
import { MatInputModule } from '@angular/material/input';
import { MatAutocompleteModule, MatAutocompleteSelectedEvent } from '@angular/material/autocomplete';
import { MatFormFieldModule } from '@angular/material/form-field';

@Component({
    selector: 'field-address',
    standalone: true,
    imports: [
        JsonPipe,
        MatInputModule,
        MatAutocompleteModule,
        MatFormFieldModule,
    ],
    template: `
        <mat-form-field
        [color]="'primary'"
        >
        <input type='text' matInput #input [value]="source()" (input)="source.set(input.value)"
        [matAutocomplete]="autoGroup">
        <mat-autocomplete #autoGroup="matAutocomplete" [displayWith]="displayFn" (optionSelected)="optionSelected($event)">
            @for (item of suggestions(); track item.global_address_key) {
                <mat-option [value]="item">{{item.text}}</mat-option>
            }
        
        </mat-autocomplete>
        <mat-label>Lookup</mat-label>
        </mat-form-field>
        
        <code><pre>
        {{expLookUp.result() | json}}
        </pre></code>
        <code><pre>
        {{this.frm.result() | json}}
        </pre></code>
  `,
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SearchAddressComponent implements OnDestroy {
    private readonly expSrv = inject(ExperianService);

    source = signal<string>('');
    selected = signal<string | null>(null);
    
    public readonly expLookUp = this.expSrv.generateLookupService(this.source);
    public readonly expformat = this.expSrv.generateFormatService(this.selected);
    
    suggestions = computed(() => this.expLookUp.result().object?.suggestions ?? []);

    ngOnDestroy(): void {
        this.expLookUp.destroy();
        this.expformat.destroy();
    }

    displayFn(itemValue: any): string {
        return itemValue.text.split(',')[0];
    }

    optionSelected(ev: MatAutocompleteSelectedEvent) {
        this.selected.set(ev.option.value.global_address_key)
    }
}

CONFIGRUATION

The Experian Service config will allow you to set various settings

Name	Type	Default	Description
baseUrl	string	'https://api.experianaperture.io/'	The base URL for the Experian API.
searchUrl	string	'address/search/v1'	The endpoint URL for address search.
formatUrl	string	'address/format/v1'	The endpoint URL for address formatting.
useCurrentLocation	boolean	false	Determines whether to use the current location for searches.
maxResults	number	10	The maximum number of results to return from a search.
dataSets	string[]	["us-address"]	Specifies the datasets to use for the search.
country	string	'USA'	The default country for the address search.
formatLayouts	string[]	[]	Layouts used for address formatting.
debounce	number	700	The debounce time in milliseconds to wait for additional input before triggering a search.
searchOptions	ExperianServiceSearchOptions[]	[ { name: "search_type", value: "singleline" }, { name: "prompt_set", value: "default" }, { name: "flatten", value: "true" }, { name: "intensity", value: "close" } ]	Additional options for configuring the search behavior.

FORMAT parser

Note: I don't suspect many systems will need this feature, but if for some reason the descision was made to utalize Experian Layouts and through no lack of trying you end up with an address model that looks like the JSON below, this feature will allow you to clean that up before it's output by the LinkedEffect

{
    "LINE_1": "{ADDR LINE 1}",
    "LINE_2": "{ADDR LINE 2}",
    "City name": "{CITY}",
    "State code": "{STATE}",
    "LINE_5": "{ZIP CODE}",
    "Three character ISO country code": "USA"
}

import { OPEN_UTILITY_EXPERIAN_SERVICE_CONFIG_TK, ExperianServiceAddressFormatParser, DefaultAddressFormat, ExperianFormatedAddress } from '@openutility/experian-services';

const expAddressParser: ExperianServiceAddressFormatParser = {
    layout: '{LAYOUT NAME}',
    parse<DefaultAddressFormat>(source: ExperianFormatedAddress) {
      return {
        address_line_1: source.address["LINE_1"],
        address_line_2: source.address["LINE_2"],
        locality: source.address["City name"],
        region: source.address["State code"],
        postal_code: source.address["LINE_5"],
        country: source.address["Three character ISO country code"],
      } as DefaultAddressFormat;
    }
};

export const config: ApplicationConfig = {
  providers: [
    { provide: OPEN_UTILITY_EXPERIAN_SERVICE_CONFIG_TK, useValue: {
        token: '{EXPERIAN_TOKEN_HERE}',
        formatLayouts: ['{LAYOUT NAME}'], 
        } 
    },
  ],
};