npm package: @ideal-postcodes/api-typings
Description: Typings and other useful javascript abstractions for interacting with the Ideal-Postcodes.co.uk API
Author: Ideal Postcodes
Latest version: 2.1.0

<h1 align="center">
  <img src="https://img.ideal-postcodes.co.uk/API%20Typings%20Logo@3x.png" alt="Ideal Postcodes API Typings">
</h1>

> Typings for the Ideal Postcodes API (api.ideal-postcodes.co.uk)

![CI](https://github.com/ideal-postcodes/api-typings/workflows/CI/badge.svg)
![Release](https://github.com/ideal-postcodes/api-typings/workflows/Release/badge.svg)
[![npm version](https://badge.fury.io/js/%40ideal-postcodes%2Fapi-typings.svg)](https://badge.fury.io/js/%40ideal-postcodes%2Fapi-typings)

TypeScript typings which define:

- The basic JSON objects returned by our APIs (e.g. addresses `Address`, autocomplete suggestions `AddressSuggestion`, API key status `KeyStatus`)
- The overall shape of JSON responses returned by the API (e.g. postcode lookups `PostcodesResponse`, address autocomplete queries `AddressSuggestionResponse`, address search queries `AddressQueryResponse`)

Typings are exported to `index.d.ts` when published to [npm](https://www.npmjs.com/package/@ideal-postcodes/api-typings). The typings in this repository are defined in `lib/index.ts`.

### Usage

Install package

```bash
npm install --save-dev @ideal-postcodes/api-typings
```

Import interfaces and other definitions

```typescript
// Import Address type
import { Address } from "@ideal-postcodes/api-typings";

let address: Address;
```

### Links

- [Project Repository](https://github.com/ideal-postcodes/api-typings)
- [Project Documentation](https://api-typings.ideal-postcodes.dev)
- [npm module](https://www.npmjs.com/package/@ideal-postcodes/api-typings)

## Benefits of Typings

### Code Completion

Typings allow IDEs to provide a richer, more productive environment to develop integrations. This includes providing code completions and suggestions.

### Inline Documentation

Our typings also bear documentation which can be rendered in your IDE as you work.

### Type Checking

Compile time checks that your library or application appropriately consumes objects and data types returned by our APIs and client libraries

### Non-TypeScript Projects

Your integration does not have to be exclusively TypeScript driven to benefit from this typings repository.

Some IDEs (e.g. Visual Studio, Visual Studio Code, Sublime Text) use TypeScript typings to provide inline code completion and documentation for plain JavaScript files.

It is also possible to develop a partial, robust TypeScript integration against our services and subsequently incorporate it in a larger JavaScript project. TypeScript compiles down to plain JavaScript which can conform to ES3 and later. That output can be exported to other JavaScript projects.

## Testing

The testing process involves attempting to compile a test file which assigns [API fixtures](https://github.com/ideal-postcodes/api-fixtures) generated by the API to the interfaces exported by this typings library. The tests will fail to compile if the API fixtures fail to conform to types.

```bash
npm test
```

## Licence

MIT