npm package: @infoxchange/iss4
Description: ISS v4 REST API client for Node.js
Latest version: 1.0.3

# ISS v4 REST API Node.js Client

This package provides a Node.js client for interacting with the ISS v4 REST API.
This client has been transpiled from the python client https://github.com/InfoxchangeTS/iss-v4-rest-python-client

## Installation

```bash
npm install iss-v4-rest-nodejs-client
```

## Usage

### Basic Usage

```typescript
import { ISSV4APIClient } from 'iss-v4-rest-nodejs-client';

// Initialize the client with JWT authentication
const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  {},
  'client_id',
  'client_secret'
);

// Or with Basic token authentication
import { BasicTokenSession } from 'iss-v4-rest-nodejs-client';

const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  { session: BasicTokenSession },
  'your_token'
);

// Directory search provides a simple yet powerfull parameter based method for a simpler search experience
async function simpleSearch() {
  try {
    const results = await client.directorySearch({
      name: 'health services',
      lga: 'city of yarra',
      fields: '*'
    });
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
}

// Advanced search is provided via the search endpoint and takes Appsearch based filters and boosts 
async function advancedSearch() {
  try {
    const results = await client.search(
      'search term', 
      { filter_key: 'filter_value' }
    );
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
}

// Entity operations example
async function createOrganisation() {
  try {
    const response = await client.createOrganisation({
      name: 'Test Organisation',
      // Other fields...
    });
    console.log('Organisation created:', response.data);
  } catch (error) {
    console.error('Failed to create organisation:', error);
  }
}
```

### Authentication

The client supports two authentication methods:

1. JWT authentication (default)
2. Basic token authentication

#### JWT Authentication

```typescript
const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  {},
  'client_id',
  'client_secret'
);
```

#### Basic Token Authentication

```typescript
import { BasicTokenSession } from 'iss-v4-rest-nodejs-client';

const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  { session: BasicTokenSession },
  'your_token'
);
```

### Query Parameters

When working with list operations, you can provide query parameters to filter and paginate results:

```typescript
// Get organisations with pagination
const organisations = await client.organisations(undefined, { limit: '50', offset: '10' });

// Get services with a search term and filters
const services = await client.services(
  { name: 'Health' },  // search term
  { active: 'true' }   // query parameters
);
```

The client automatically handles various parameter formats, including:
- String values (e.g., `{ limit: '50' }`)
- Array values (e.g., `{ limit: ['50'] }`)
- Mixed values (e.g., `{ limit: '50', tags: ['tag1', 'tag2'] }`)

> **Note**: For array parameters, the client uses the first value in the array when making API requests.

## API Reference

The client provides methods for interacting with all the endpoints of the ISS v4 API.

### Search Operations

- `search(term, filters, boosts, serialiser, options)` - Search ISS v4
- `directorySearch(queryParams)` - Directory search with GET parameters
- `searchExplain(term, filters, boosts, serialiser, options)` - Explain search query
- `searchElasticsearch(query, params, analyticsQuery, analyticsTags)` - Submit an Elasticsearch query
- `multiSearch(queries)` - Perform a multi-search
- `querySuggestion(query, options)` - Get search suggestions

### Organisation Operations

- `organisations(searchTerm, params)` - Get a list of organisations
- `organisationExists(entityId)` - Check if an organisation exists
- `fetchOrganisation(entityId)` - Fetch an organisation
- `createOrganisation(data)` - Create an organisation
- `updateOrganisation(entityId, data)` - Update an organisation
- `deleteOrganisation(entityId)` - Delete an organisation
- `createOrUpdateOrganisation(entityId, data)` - Create or update an organisation

### Site Operations

- `sites(searchTerm, params)` - Get a list of sites
- `siteExists(entityId)` - Check if a site exists
- `fetchSite(entityId)` - Fetch a site
- `createSite(data)` - Create a site
- `updateSite(entityId, data)` - Update a site
- `deleteSite(entityId)` - Delete a site
- `createOrUpdateSite(entityId, data)` - Create or update a site

### Service Operations

- `services(searchTerm, params)` - Get a list of services
- `serviceExists(entityId)` - Check if a service exists
- `fetchService(entityId)` - Fetch a service
- `createService(data)` - Create a service
- `updateService(entityId, data)` - Update a service
- `deleteService(entityId)` - Delete a service
- `createOrUpdateService(entityId, data)` - Create or update a service
- `fetchServiceType(entityId)` - Fetch a service type
- `listServiceTypes(params)` - List service types

### Event Operations

- `listEvents(queryParams)` - List events
- `eventExists(entityId)` - Check if an event exists
- `fetchEvent(entityId)` - Fetch an event
- `createEvent(data)` - Create an event
- `updateEvent(entityId, data)` - Update an event
- `deleteEvent(entityId)` - Delete an event
- `createOrUpdateEvent(entityId, data)` - Create or update an event

### Other Operations

- `listAgeGroups(queryParams)` - List age groups
- `fetchAgeGroup(entityId)` - Fetch an age group
- `listDatasets(queryParams)` - List datasets
- `fetchDataset(entityId)` - Fetch a dataset
- `listCrisisKeywords(queryParams)` - List crisis keywords
- `listRelatedCrisisKeywords(terms)` - List related crisis keywords
- `fetchCrisisKeyword(entityId)` - Fetch a crisis keyword
- `createCrisisKeyword(data)` - Create a crisis keyword
- `deleteCrisisKeyword(entityId)` - Delete a crisis keyword
- `listLanguages(queryParams)` - List languages
- `fetchLanguage(entityId)` - Fetch a language
- `analyticsQueries(options)` - Fetch query analytics
- `fetchByExternalId(externalId, organisation)` - Fetch by external ID
- `suggest(suggestionType, start)` - Get suggestions

## Development

### Setup

```bash
# Install dependencies
yarn install

# Build
yarn run build

# Run tests
yarn test
```

### Testing

The package includes a comprehensive test suite:

```bash
# Run all tests
yarn test

# Run with coverage
yarn test -- --coverage
```