npm package: @symmetrichs/sdk
Description: ## Overview Symmetric Health Solutions is a software company for healthcare supply chain data. Hundreds of hospitals — from large IDNs to community hospitals — use Symmetric's item and vendor data solutions to enable improvements in supply chain operation
Latest version: 1.0.24

# Symmetric Health Solutions SDK

## Overview
Symmetric Health Solutions is a software company for healthcare 
supply chain data. Hundreds of hospitals — from large IDNs to 
community hospitals — use Symmetric's item and vendor data 
solutions to enable improvements in supply chain operations,
business integration, and public health.

With Symmetric Health Solutions, the right information is 
delivered in the right interface, at the right time.

This SDK provides access to Symmetric APIs for searching and collecting
data for medical supplies. The API (and by association the SDK) are split
into four main categories:

1. Medical devices (e.g. gloves, MRI machines, screws)
1. Pharmaceuticals
1. Substitute devices (i.e. what products could be used as replacements for 
   another)
1. Vendors

Generally each category provides SDK functions for:

1. Searching
1. Downloading
1. Counting

There are a few additional specialized functionalities:

1. For devices, there is a specialized search (referred to as "matching")
   that provides search results based on several mapped data fields
   in a way that a much larger variety of fuzzy matching is performed
   as compared to the more generalized search
1. For devices, there is the ability to get data for specific devices 
   via UDI-DI
1. For pharmaceuticals, there is the ability to search for specific
   pharmaceuticals via NDC
   
## Examples

### Configuration
Before calling any SDK functions, the SDK must be configured:
```javascript
import {configure} from "@symmetrichs/sdk";

configure({
    apiKey: process.env.YOUR_API_KEY,
    apiSecret: process.env.YOUR_SECRET_KEY,
    appKey: process.env.YOUR_APP_KEY
});
```

### Devices
#### Search for a device by keyword
Notes: 
1. The full list of available columns is available at the end 
   of this document. Devices, pharmaceuticals, and vendors have different columns
   available.
1. This function will return a limited number of results (<1000). 
   To retrieve a larger number of results (up to 10,000) use the \
   `download` function below. To get a count of the number of results
   available for your search, use the `count` function below.
```javascript
import {device} from "@symmetrichs/sdk";

const results = await device.search({
    query: 'needle',
    columns: ['Primary DI', 'GMDN By Name']
});

// Search with additional filters
const results = await device.search({
   query: 'needle',
   columns: ['Primary DI', 'GMDN By Name'],
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['RE', 'TAC'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['RE', 'TAC'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['RE', 'TAC'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC' 
   filters: [{column: 'Noun', values: ['CONTAINER', 'RECEPTACLE'], type: 'ANY'}]
});
```

#### Download search results
```javascript
import {device} from "@symmetrichs/sdk";

const download = await device.download({
   // Most options are the same as for `search`, including filters
   query: 'needle',
   columns: ['Primary DI', 'GMDN By Name'],
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());
```

#### Count search results
```javascript
import {device} from "@symmetrichs/sdk";

const results = await device.count({
   // Options are the same as for `search`, including filters
   query: 'needle',
   column: 'Primary DI'
});
```

#### Match
Notes:
1. The `match` function only returns the UDI-DI's that best match
   the provided information, based on Symmetric's matching algorithms. 
   With the UDI-DI's, you can call the `device` function below to 
   collect additional information.
1. All possible fields are enumerated below. The more fields specified,
   the better the match results will be. At least one of 
   [`mnfCtlg`, `vendorCtlg`, `udiDi`] must be specified.
1. The catalogs, UDI-DI, manufacturer, vendor, and description options 
   need not be exact (that's the point of this API!) but the cleaner the 
   options, the better the results (e.g. including or excluding leading
   `0`'s)

```javascript
import {device} from "@symmetrichs/sdk";

const results = await device.match({
   mnfCtlg: '210295',
   mnfName: 'arkray'
});

const results = await device.match({
   mnfCtlg: '210295',
   mnfName: 'arkray',
   vendorCtlg: undefined,
   vendorName: undefined,
   udiDi: undefined,
   description: 'your item description'
});
```

#### Get information by UDI-DI
```javascript
import {device} from "@symmetrichs/sdk";

const results = await device.get({
   ids: ['00366975005090', '00606959054202'],  // Up to 20 items can be specified, must be an array
   columns: ['Primary DI', 'GMDN By Name']
});
```

### Pharmaceuticals
#### Search for a pharmaceutical by keyword
Notes:
1. The full list of available columns is available at the end
   of this document. Devices, pharmaceuticals, and vendors have different columns
   available.
1. This function will return a limited number of results (<1000).
   To retrieve a larger number of results use the `download` function
   below. To get a count of the number of results available for your
   search, use the `count` function below.
```javascript
import {pharmacy} from "@symmetrichs/sdk";

const results = await pharmacy.search({
   query: 'ibuprofen',
   columns: ['Generic Name', 'Labeler Name']
});

// Search with additional filters
const results = await pharmacy.search({
   query: 'ibuprofen',
   columns: ['Generic Name', 'Labeler Name'],
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['O', 'TC'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['O', 'TC'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['O', 'TC'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC' 
   filters: [{column: 'OTC', values: ['OTC', 'RX'], type: 'ANY'}]
});
```

#### Download search results
```javascript
import {pharmacy} from "@symmetrichs/sdk";

const download = await pharmacy.download({
   // Most options are the same as for `search`, including filters
   query: 'ibuprofen',
   columns: ['Product Packaging NDC', 'Generic Name', 'Labeler Name'],
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());
```

#### Count search results
```javascript
import {pharmacy} from "@symmetrichs/sdk";

const results = await pharmacy.count({
   // Options are the same as for `search`, including filters
   query: 'ibuprofen',
   column: 'Generic Name'
});
```

#### Get information by NDC
Notes:
1. This function only accepts the NDC-11 format with dashes 
   (e.g. `24385-0546-62`)
```javascript
import {pharmacy} from "@symmetrichs/sdk";

const results = await pharmacy.get({
   ids: ['24385-0546-62', '00573-0164-40'],
   columns: ['Generic Name', 'Labeler Name']
});
```

### Device Substitutes
#### Search for substitutes by UDI-DI
Notes:
1. The full list of available columns is available at the end
   of this document. Devices, pharmaceuticals, and vendors have different columns
   available.
1. This function will return a limited number of results (<1000).
   To retrieve a larger number of results use the `download` function
   below. To get a count of the number of results available for your
   search, use the `count` function below.
```javascript
import {substitutes} from "@symmetrichs/sdk";

const results = await substitutes.search({
   query: '00008712000028',
   columns: ['Primary DI', 'Manufacturer Name Cleansed'],
   manufacturer: 'DIFFERENT'  // One of: 'ALL', 'DIFFERENT', or 'SAME'
});

// Search with additional filters
const results = await substitutes.search({
   query: '00008712000028',
   columns: ['Primary DI', 'Manufacturer Name Cleansed'],
   manufacturer: 'DIFFERENT',
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['CON', 'NER'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['CON', 'NER'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['CON', 'NER'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC' 
   filters: [{column: 'Noun', values: ['CONTAINER'], type: 'ANY'}]
});
```

#### Download search results
```javascript
import {substitutes} from "@symmetrichs/sdk";

const download = await substitutes.download({
   // Most options are the same as for `search`, including filters
   query: '00008712000028',
   columns: ['Primary DI', 'Manufacturer Name Cleansed'],
   manufacturer: 'DIFFERENT',
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());
```

#### Count search results
```javascript
import {substitutes} from "@symmetrichs/sdk";

const results = await substitutes.count({
   // Most options are the same as for `search`, including filters
   query: '00008712000028',
   column: 'Manufacturer Name Cleansed',
   manufacturer: 'DIFFERENT'
});
```

### Vendors
#### Search for vendors by keyword
Notes:
1. The full list of available columns is available at the end
   of this document. Devices, pharmaceuticals, and vendors have 
   different columns available.
1. This function will return a limited number of results (<1000).
   To retrieve a larger number of results use the `download` function
   below. To get a count of the number of results available for your
   search, use the `count` function below.
```javascript
import {vendor} from "@symmetrichs/sdk";

const results = await vendor.search({
   query: 'seattle',
   columns: ['Name', 'City']
});

// Search with additional filters
const results = await vendor.search({
   query: 'seattle',
   columns: ['Name', 'City'],
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['98', '121'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['98', '121'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['98', '121'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC'
   filters: [{column: 'Zip', values: ['98121', '98208'], type: 'ANY'}]
});
```

#### Download search results
```javascript
import {vendor} from "@symmetrichs/sdk";

const download = await vendor.download({
   // Most options are the same as for `search`, including filters
   query: 'seattle',
   columns: ['Name', 'City'],
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());
```

#### Count search results
```javascript
import {vendor} from "@symmetrichs/sdk";

const results = await vendor.count({
   // Most options are the same as for `search`, including filters
   query: 'seattle',
   column: 'City'
});
```

### Full Node.js Example
```javascript
const {configure, device} = require("@symmetrichs/sdk");

configure({
   apiKey: process.env.YOUR_API_KEY,
   apiSecret: process.env.YOUR_SECRET_KEY,
   appKey: process.env.YOUR_APP_KEY
});

(async () => {
  const results = await device.search({
    query: 'needle',
    columns: ['Primary DI', 'GMDN By Name']
  });
  console.log(JSON.stringify(results, null, 2));
})();
```

## Documentation
### Available Columns
A full list of columns is available at https://www.symmetrichealthsolutions.com/data.
The column names as seen in the `field_name_app` of the download are the
columns used by the SDK, and can be filtered on the `database_name` to view
columns available for each of the sections above (device, pharmaceuticals,
and vendors). Note that the substitute columns are the same columns as device.

Some example columns are as follows:
1. Device
   1. `Primary DI`
   1. `Brand Name`
   1. `Noun`
   1. `UNSPSC`
   1. `HCPCS`
   1. `Parent Company Name`
   1. `Manufacturer Name Cleansed`
   1. `GMDN Preferred Term`
1. Pharmaceuticals
   1. `Product Packaging NDC`
   1. `Generic Name`
   1. `Labeler Name`
   1. `Package Description`
   1. `Established Pharmacologic Class`
   1. `Proprietary Name`
   1. `Substance Name`
   1. `Product NDC`
1. Vendors
   1. `Name`
   1. `City`
   1. `Minority Classification`
   1. `Vendor Description`