@fdot/arculus-staff-service/README.md

Simplifies usage of the Arculus Staff Service

# FDOT Arculus Staff Service

NPM package to assist accessing FDOT Staff information through the Arculus Staff Service v4 API
in both test and production.

## Benefits of Using this Package

### Full Typescript Support

This package was created in TypeScript and thus has full type support.

### Caching

Caching is not enabled by default but can be enabled via the options during initialization.
When caching is enabled, a cache duration setting controls when cached entries will be purged
from the cache. A sliding cache option can also be used to slide the expiration forward every
time that cached element is accessed. All exposed functions in this package use caching if
caching is enabled. The caching options provided during initialization can be overridden via
a cache option parameter available on each exposed function.

### Automatic Throttle Retry

The Arculus Staff Service is hosted on Azure API Management and can return a HTTP Status Code: 429 when
throttle thresholds are met. When this happens a retry-after header will be returned along with the 429
with the number of seconds that should elapse before another attempt to call the api operation. This package
will automatically wait the specified time and then issue another attempt.

### Automatic Support for Custom Mapping

If you wish to transform the IStaffMember returned from functions in this
package, every available function has a corollary method that accepts a custom
map function and will perform that mapping before returning staff data.

### Runtime Engine Agnostic

This package has no browser specific or [Node.js](https://nodejs.org/en/) specific dependencies
so you can use it on the server side and client side of your application.

## Getting Started

Install the package

> npm install @fdot/arculus-staff-service

Import necessary types and methods:

```typescript
import {
  Environment,
  IStaffMember,
  IStaffServiceOptions,
  ICacheOptions,
  staffService,
} from "@fdot/arculus-staff-service";
```

Create a IStaffServiceOptions object with the necessary information:

```typescript
const cacheOptions: ICacheOptions = {
  cacheDurationInMinutes: 60,
  cachingEnabled: true,
  slidingExpirationEnabled: true,
};

const options: IStaffServiceOptions = {
  arculusApiKey: "InsertYourKeyHere",
  cacheOptions,
  environment: Environment.Test,
};
```

JavaScript example for those less privileged: 😁

```javascript
const cacheOptions = {
  cacheDurationInMinutes: 60,
  cachingEnabled: true,
  slidingExpirationEnabled: true,
};

const testOptions = {
  arculusApiKey: "InsertYourKeyHere",
  cacheOptions,
  environment: "Test",
};

const productionOptions = {
  arculusApiKey: "InsertYourKeyHere",
  cacheOptions,
  environment: "Production",
};
```

Initialize the service:

```typescript
staffService.initialize(options);
```

Use the service:

```typescript
const staffMember: IStaffMember = await staffService.getStaffByEmailAddress(
  "cody.raffensperger@dot.state.fl.us"
);
```

JavaScript example for those less privileged: 😁

```javascript
const staffMember = await staffService.getStaffByEmailAddress(
  "cody.raffensperger@dot.state.fl.us"
);
```

Use the service with a custom map function if you only care about a subset of properties or wish
to transform anything:

```typescript
interface IStaff = {
    srsId: number;
    email: string;
}

const mapFunction = (staff: IStaffMember) : IStaff => {
    return {
        srsId: staff.id,
        email: staff.emailAddress
    };
}

const staff : IStaff = await staffService.getMappedStaffByEmailAddress<IStaff>(
    "cody.raffensperger@dot.state.fl.us",
    mapFunction);
```

JavaScript example for those less privileged: 😁

```javascript
const mapFunction = (staff) => {
  return {
    srsId: staff.id,
    email: staff.emailAddress,
  };
};

const staff = await staffService.getMappedStaffByEmailAddress(
  "cody.raffensperger@dot.state.fl.us",
  mapFunction
);
```

### Prerequisites

A subscription key with access to call the FDOT Arculus Staff Service API in the environment specified is
required to use this package. To request a key for the Test environment visit the FDOT Arculus Azure API
Management [Developer Portal](https://portal.test.arc.fdot.gov/). The Arculus API Product Group is the product
you will want to request a subscription to gain access to FDOT staff information.

## Available Staff Service Methods

```typescript
export declare const initialize: (options: IStaffServiceOptions) => void;

export declare const getStaffByAzureOid: (
  oid: string,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember | null>;
export declare const getMappedStaffByAzureOid: <T>(
  oid: string,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T | null>;

export declare const getStaffByAzureOids: (
  oids: string[],
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember[]>;
export declare const getMappedStaffByAzureOids: <T>(
  oids: string[],
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T[]>;

export declare const getStaffByEmailAddress: (
  emailAddress: string,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember | null>;
export declare const getMappedStaffByEmailAddress: <T>(
  emailAddress: string,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T | null>;

export declare const getStaffBySrsId: (
  srsId: number,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember | null>;
export declare const getMappedStaffBySrsId: <T>(
  srsId: number,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T | null>;

export declare const getStaffBySrsIds: (
  srsIds: number[],
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember[]>;
export declare const getMappedStaffBySrsIds: <T>(
  srsIds: number[],
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T[]>;

export declare const getActiveStaffByPartialName: (
  partialName: string,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember[]>;
export declare const getMappedActiveStaffByPartialName: <T>(
  partialName: string,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T[]>;

export declare const getActiveAndInactiveStaffByPartialName: (
  partialName: string,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember[]>;
export declare const getMappedActiveAndInactiveStaffByPartialName: <T>(
  partialName: string,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T[]>;

export declare const getStaffByFilterCriteria: (
  filterCriteria: IStaffFilterCriteria,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember[]>;
export declare const getMappedStaffByFilterCriteria: <T>(
  filterCriteria: IStaffFilterCriteria,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T[]>;

export declare const getAllStaffMembers: (
  statusFilter: StatusFilter = StatusFilter.ActiveOnly,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember[]>;
export declare const getAllMappedStaffMembers: <T>(
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T[]>;

export declare const getDirectReports: (
  srsId: number,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember[]>;
export declare const getMappedDirectReports: <T>(
  srsId: number,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T[]>;

export declare const getManager: (
  srsId: number,
  cacheOptions?: ICacheOptions | undefined
) => Promise<IStaffMember>;
export declare const getMappedManager: <T>(
  srsId: number,
  mapFunction: (staff: IStaffMember) => T,
  cacheOptions?: ICacheOptions | undefined
) => Promise<T>;

export declare const clearCache: () => void;
```

## Tests

The tests for this package were developed using [Jest](https://jestjs.io/) with the help of the
TypeScript pre processor [ts-jest](https://kulshekhar.github.io/ts-jest/).

The tests require a key to the arculus API for the test environment. Create an .env file in the root of this
package with the following:

```json
ARCULUS_API_KEY=[Enter Your Key Here]
```

Once the .env file is in place the tests can be executed by simply running the following command:

> npm run test

To debug the tests set your breakpoints in VSCode and then launch the 'Jest All' debug configuration.

After executing the Jest tests a code coverage reports can be found at:
.\coverage\lcov-report\index.html.

## Contributing

Any user with the appropriate rights within FDOT Azure Dev Ops can contribute to this package.

## Authors

- **Cody Raffensperger** - _Initial work_ - [NPM Page](https://www.npmjs.com/~cody.raffy.fdot)

## License

This project is licensed under the MIT License.