@ideal-postcodes/core-interface
Advanced tools
Comparing version 1.1.1 to 1.2.0
@@ -0,1 +1,19 @@ | ||
# [1.2.0](https://github.com/ideal-postcodes/core-interface/compare/1.1.1...1.2.0) (2019-06-07) | ||
### Bug Fixes | ||
* **Karma-Typescript:** Explicitly exclude typings module ([b11e9e3](https://github.com/ideal-postcodes/core-interface/commit/b11e9e3)) | ||
### Features | ||
* **Client#checkKeyUsability:** Implement key check ([df6a611](https://github.com/ideal-postcodes/core-interface/commit/df6a611)) | ||
* **Client#lookupAddress:** Implement address lookup ([a53fb67](https://github.com/ideal-postcodes/core-interface/commit/a53fb67)) | ||
* **Client#lookupPostcode:** Implement and document postcode lookup ([21e591e](https://github.com/ideal-postcodes/core-interface/commit/21e591e)) | ||
* **Client#lookupPostcode:** Make results paginateable ([a155f9f](https://github.com/ideal-postcodes/core-interface/commit/a155f9f)) | ||
* **Client#lookupUdprn:** Implement and document udprn search ([e709853](https://github.com/ideal-postcodes/core-interface/commit/e709853)) | ||
* **Client#lookupUmprn:** Implement UMPRN lookup ([14227c3](https://github.com/ideal-postcodes/core-interface/commit/14227c3)) | ||
* **Error:** Export errors on Client ([ff111f0](https://github.com/ideal-postcodes/core-interface/commit/ff111f0)) | ||
## [1.1.1](https://github.com/ideal-postcodes/core-interface/compare/1.1.0...1.1.1) (2019-06-06) | ||
@@ -2,0 +20,0 @@ |
import { Agent, HttpResponse, Header } from "./agent"; | ||
import { Authenticable, Filterable, Taggable, HttpOptions, Paginateable } from "./types"; | ||
import * as errors from "./error"; | ||
import { Address, KeyStatus } from "@ideal-postcodes/api-typings"; | ||
declare type Protocol = "http" | "https"; | ||
@@ -47,2 +50,40 @@ export interface Config { | ||
import { UmprnResource } from "./resources/umprn"; | ||
interface LookupIdOptions extends Authenticable, Filterable, Taggable, HttpOptions { | ||
} | ||
interface LookupAddressOptions extends Authenticable, Filterable, Taggable, Paginateable, HttpOptions { | ||
/** | ||
* Query for address | ||
*/ | ||
query: string; | ||
} | ||
interface LookupPostcodeOptions extends LookupIdOptions { | ||
/** | ||
* Postcode to query for. Space and case insensitive | ||
*/ | ||
postcode: string; | ||
/** | ||
* With multiple residence datasets, a very small number of postcodes will | ||
* yield more than 100 results. In this instance, you would need to paginate | ||
* through them with `page` | ||
*/ | ||
page?: number; | ||
} | ||
interface LookupUdprnOptions extends LookupIdOptions { | ||
/** | ||
* UDPRN to query for | ||
*/ | ||
udprn: number; | ||
} | ||
interface LookupUmprnOptions extends LookupIdOptions { | ||
/** | ||
* UMPRN to query for | ||
*/ | ||
umprn: number; | ||
} | ||
interface CheckKeyUsabilityOptions extends HttpOptions { | ||
/** | ||
* If api_key is supplied, this will overwrite the key defined during client instantiation | ||
*/ | ||
api_key?: string; | ||
} | ||
export declare class Client { | ||
@@ -63,2 +104,3 @@ static defaults: Defaults; | ||
readonly keys: KeyResource; | ||
static errors: typeof errors; | ||
constructor(config: Config); | ||
@@ -78,3 +120,52 @@ /** | ||
ping(): Promise<HttpResponse>; | ||
/** | ||
* lookupPostcode | ||
* | ||
* Search for addresses given a postcode. Postcode queries are case and space insensitive | ||
* | ||
* Invalid postcodes return an empty array address result `[]` | ||
* | ||
* [API Documentation for /postcodes](https://ideal-postcodes.co.uk/documentation/postcodes#postcode) | ||
*/ | ||
lookupPostcode(options: LookupPostcodeOptions): Promise<Address[]>; | ||
/** | ||
* lookupAddress | ||
* | ||
* Search for an address given a query | ||
* | ||
* [API Documentation for /addresses](https://ideal-postcodes.co.uk/documentation/addresses#query) | ||
*/ | ||
lookupAddress(options: LookupAddressOptions): Promise<Address[]>; | ||
/** | ||
* toAddressIdQuery | ||
* | ||
* Generates a request object. Bundles together commonly used header/query extractions: | ||
* - Authorization (api_key, licensee, user_token) | ||
* - Source IP forwarding | ||
* - Result filtering | ||
* - Tagging | ||
*/ | ||
private toAddressIdQuery; | ||
/** | ||
* lookupUdprn | ||
* | ||
* Search for an address given a UDPRN | ||
* | ||
* Invalid UDPRN returns `null` | ||
* | ||
* [API Documentation for /udprn](https://ideal-postcodes.co.uk/documentation/udprn) | ||
*/ | ||
lookupUdprn(options: LookupUdprnOptions): Promise<Address | null>; | ||
/** | ||
* lookupUdprn | ||
* | ||
* Search for an address given a UDPRN | ||
* | ||
* Invalid UDPRN returns `null` | ||
* | ||
* [API Documentation for /udprn](https://ideal-postcodes.co.uk/documentation/udprn) | ||
*/ | ||
lookupUmprn(options: LookupUmprnOptions): Promise<Address | null>; | ||
checkKeyUsability(options: CheckKeyUsabilityOptions): Promise<KeyStatus>; | ||
} | ||
export {}; |
@@ -13,3 +13,13 @@ "use strict"; | ||
}; | ||
var __importStar = (this && this.__importStar) || function (mod) { | ||
if (mod && mod.__esModule) return mod; | ||
var result = {}; | ||
if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k]; | ||
result["default"] = mod; | ||
return result; | ||
}; | ||
Object.defineProperty(exports, "__esModule", { value: true }); | ||
var error_1 = require("./error"); | ||
var errors = __importStar(require("./error")); | ||
var util_1 = require("./util"); | ||
var addresses_1 = require("./resources/addresses"); | ||
@@ -63,2 +73,117 @@ var postcodes_1 = require("./resources/postcodes"); | ||
}; | ||
/** | ||
* lookupPostcode | ||
* | ||
* Search for addresses given a postcode. Postcode queries are case and space insensitive | ||
* | ||
* Invalid postcodes return an empty array address result `[]` | ||
* | ||
* [API Documentation for /postcodes](https://ideal-postcodes.co.uk/documentation/postcodes#postcode) | ||
*/ | ||
Client.prototype.lookupPostcode = function (options) { | ||
var queryOptions = this.toAddressIdQuery(options); | ||
var page = options.page; | ||
if (page !== undefined) | ||
queryOptions.query.page = page.toString(); | ||
return this.postcodes | ||
.retrieve(options.postcode, queryOptions) | ||
.then(function (response) { return response.body.result; }) | ||
.catch(function (error) { | ||
if (error instanceof error_1.IdpcPostcodeNotFoundError) | ||
return []; | ||
throw error; | ||
}); | ||
}; | ||
/** | ||
* lookupAddress | ||
* | ||
* Search for an address given a query | ||
* | ||
* [API Documentation for /addresses](https://ideal-postcodes.co.uk/documentation/addresses#query) | ||
*/ | ||
Client.prototype.lookupAddress = function (options) { | ||
var header = {}; | ||
var query = { query: options.query }; | ||
util_1.appendAuthorization({ client: this, header: header, options: options }); | ||
util_1.appendIp({ header: header, options: options }); | ||
util_1.appendFilter({ query: query, options: options }); | ||
util_1.appendTags({ query: query, options: options }); | ||
util_1.appendPage({ query: query, options: options }); | ||
var queryOptions = { header: header, query: query }; | ||
if (options.timeout !== undefined) | ||
queryOptions.timeout = options.timeout; | ||
return this.addresses | ||
.list(queryOptions) | ||
.then(function (response) { return response.body.result.hits; }); | ||
}; | ||
/** | ||
* toAddressIdQuery | ||
* | ||
* Generates a request object. Bundles together commonly used header/query extractions: | ||
* - Authorization (api_key, licensee, user_token) | ||
* - Source IP forwarding | ||
* - Result filtering | ||
* - Tagging | ||
*/ | ||
Client.prototype.toAddressIdQuery = function (options) { | ||
var header = {}; | ||
var query = {}; | ||
util_1.appendAuthorization({ client: this, header: header, options: options }); | ||
util_1.appendIp({ header: header, options: options }); | ||
util_1.appendFilter({ query: query, options: options }); | ||
util_1.appendTags({ query: query, options: options }); | ||
var request = { header: header, query: query }; | ||
if (options.timeout !== undefined) | ||
request.timeout = options.timeout; | ||
return request; | ||
}; | ||
/** | ||
* lookupUdprn | ||
* | ||
* Search for an address given a UDPRN | ||
* | ||
* Invalid UDPRN returns `null` | ||
* | ||
* [API Documentation for /udprn](https://ideal-postcodes.co.uk/documentation/udprn) | ||
*/ | ||
Client.prototype.lookupUdprn = function (options) { | ||
var queryOptions = this.toAddressIdQuery(options); | ||
return this.udprn | ||
.retrieve(options.udprn.toString(), queryOptions) | ||
.then(function (response) { return response.body.result; }) | ||
.catch(function (error) { | ||
if (error instanceof error_1.IdpcUdprnNotFoundError) | ||
return null; | ||
throw error; | ||
}); | ||
}; | ||
/** | ||
* lookupUdprn | ||
* | ||
* Search for an address given a UDPRN | ||
* | ||
* Invalid UDPRN returns `null` | ||
* | ||
* [API Documentation for /udprn](https://ideal-postcodes.co.uk/documentation/udprn) | ||
*/ | ||
Client.prototype.lookupUmprn = function (options) { | ||
var queryOptions = this.toAddressIdQuery(options); | ||
return this.umprn | ||
.retrieve(options.umprn.toString(), queryOptions) | ||
.then(function (response) { return response.body.result; }) | ||
.catch(function (error) { | ||
if (error instanceof error_1.IdpcUmprnNotFoundError) | ||
return null; | ||
throw error; | ||
}); | ||
}; | ||
Client.prototype.checkKeyUsability = function (options) { | ||
var _a = options.api_key, api_key = _a === void 0 ? this.api_key : _a, timeout = options.timeout; | ||
var queryOptions = { query: {}, header: {} }; | ||
if (timeout !== undefined) | ||
queryOptions.timeout = timeout; | ||
return this.keys | ||
.retrieve(api_key, queryOptions) | ||
.then(function (response) { return response.body.result; }); // Assert that we're retrieving public key information as no user_token provided | ||
}; | ||
Client.defaults = { | ||
@@ -70,2 +195,3 @@ header: { | ||
}; | ||
Client.errors = errors; | ||
return Client; | ||
@@ -72,0 +198,0 @@ }()); |
@@ -23,20 +23,3 @@ /** | ||
export { Agent, HttpRequest, HttpResponse } from "./agent"; | ||
import { Address } from "../node_modules/@ideal-postcodes/api-typings"; | ||
import * as errors from "./error"; | ||
export { errors }; | ||
interface Authenticable { | ||
api_key?: string; | ||
licensee?: string; | ||
} | ||
interface ResponseFilterable { | ||
filter?: keyof Address[]; | ||
} | ||
interface Taggable { | ||
tags?: string[]; | ||
} | ||
interface Paginateable { | ||
page?: number; | ||
} | ||
export interface LookupPostcodeOptions extends Authenticable, ResponseFilterable, Taggable, Paginateable { | ||
postcode: string; | ||
} |
@@ -30,4 +30,4 @@ "use strict"; | ||
if (error) | ||
return Promise.reject(error); | ||
return Promise.resolve(response); | ||
throw error; | ||
return response; | ||
}); | ||
@@ -50,4 +50,4 @@ }; | ||
if (error) | ||
return Promise.reject(error); | ||
return Promise.resolve(response); | ||
throw error; | ||
return response; | ||
}); | ||
@@ -54,0 +54,0 @@ }; |
import { Client } from "./client"; | ||
import { Authenticable, Paginateable, AdminAuthenticable, Taggable, HttpOptions, Filterable } from "./types"; | ||
export interface OptionalStringMap { | ||
@@ -33,2 +34,46 @@ [key: string]: string | undefined; | ||
export declare const toHeader: ({ header }: OptionalHeader, client: Client) => StringMap; | ||
declare type AuthenticationOptions = Partial<Authenticable & AdminAuthenticable>; | ||
/** | ||
* toAuthHeader | ||
* | ||
* Extracts credentials into authorization header format | ||
*/ | ||
export declare const toAuthHeader: (client: Client, options: Partial<Authenticable & AdminAuthenticable>) => string; | ||
interface AppendAuthorizationOptions { | ||
options: AuthenticationOptions; | ||
client: Client; | ||
header: StringMap; | ||
} | ||
interface AppendAuthorization { | ||
(options: AppendAuthorizationOptions): StringMap; | ||
} | ||
/** | ||
* appendAuthorization | ||
* | ||
* Mutates a headers object to include Authorization header. Will insert if found: | ||
* - api_key | ||
* - licensee | ||
* - user_token | ||
*/ | ||
export declare const appendAuthorization: AppendAuthorization; | ||
interface AppendIpOptions { | ||
header: StringMap; | ||
options: HttpOptions; | ||
} | ||
export declare const appendIp: ({ header, options }: AppendIpOptions) => StringMap; | ||
interface AppendFilterOptions { | ||
query: StringMap; | ||
options: Filterable; | ||
} | ||
export declare const appendFilter: ({ query, options, }: AppendFilterOptions) => StringMap; | ||
interface AppendTagsOptions { | ||
query: StringMap; | ||
options: Taggable; | ||
} | ||
export declare const appendTags: ({ query, options, }: AppendTagsOptions) => StringMap; | ||
interface AppendPageOptions { | ||
query: StringMap; | ||
options: Paginateable; | ||
} | ||
export declare const appendPage: ({ query, options, }: AppendPageOptions) => StringMap; | ||
export {}; |
@@ -54,2 +54,72 @@ "use strict"; | ||
}; | ||
/** | ||
* toAuthHeader | ||
* | ||
* Extracts credentials into authorization header format | ||
*/ | ||
exports.toAuthHeader = function (client, options) { | ||
var credentials = []; | ||
var api_key = options.api_key || client.api_key; | ||
credentials.push(["api_key", api_key]); | ||
var licensee = options.licensee; | ||
if (licensee !== undefined) | ||
credentials.push(["licensee", licensee]); | ||
var user_token = options.user_token; | ||
if (user_token !== undefined) | ||
credentials.push(["user_token", user_token]); | ||
return "IDEALPOSTCODES " + toCredentialString(credentials); | ||
}; | ||
/** | ||
* appendAuthorization | ||
* | ||
* Mutates a headers object to include Authorization header. Will insert if found: | ||
* - api_key | ||
* - licensee | ||
* - user_token | ||
*/ | ||
exports.appendAuthorization = function (_a) { | ||
var header = _a.header, options = _a.options, client = _a.client; | ||
header.Authorization = exports.toAuthHeader(client, options); | ||
return header; | ||
}; | ||
var toCredentialString = function (credentials) { | ||
return credentials.map(function (_a) { | ||
var key = _a[0], value = _a[1]; | ||
return key + "=\"" + value + "\""; | ||
}).join(" "); | ||
}; | ||
// Adds source IP to headers | ||
exports.appendIp = function (_a) { | ||
var header = _a.header, options = _a.options; | ||
var sourceIp = options.sourceIp; | ||
if (sourceIp !== undefined) | ||
header["IDPC-Source-IP"] = sourceIp; | ||
return header; | ||
}; | ||
// Adds filters to query | ||
exports.appendFilter = function (_a) { | ||
var query = _a.query, options = _a.options; | ||
var filter = options.filter; | ||
if (filter !== undefined) | ||
query.filter = filter.join(","); | ||
return query; | ||
}; | ||
// Adds tags to query | ||
exports.appendTags = function (_a) { | ||
var query = _a.query, options = _a.options; | ||
var tags = options.tags; | ||
if (tags !== undefined) | ||
query.tags = tags.join(","); | ||
return query; | ||
}; | ||
// Adds pagination attributes to query | ||
exports.appendPage = function (_a) { | ||
var query = _a.query, options = _a.options; | ||
var page = options.page, limit = options.limit; | ||
if (page !== undefined) | ||
query.page = page.toString(); | ||
if (limit !== undefined) | ||
query.limit = limit.toString(); | ||
return query; | ||
}; | ||
//# sourceMappingURL=util.js.map |
{ | ||
"name": "@ideal-postcodes/core-interface", | ||
"version": "1.1.1", | ||
"version": "1.2.0", | ||
"description": "Interface specification for javascript based API Clients to api.ideal-postcodes.co.uk", | ||
@@ -23,2 +23,3 @@ "author": { | ||
"semantic-release": "node_modules/.bin/semantic-release --no-ci", | ||
"test-watch": "NODE_ENV=test node_modules/.bin/mocha --watch", | ||
"test": "npm run lint && NODE_ENV=test node_modules/.bin/nyc node_modules/.bin/mocha", | ||
@@ -25,0 +26,0 @@ "karma": "./node_modules/.bin/karma start", |
190
README.md
@@ -5,6 +5,6 @@ <h1 align="center"> | ||
> Javascript API interface for api.ideal-postcodes.co.uk | ||
> Javascript API for api.ideal-postcodes.co.uk | ||
[![CircleCI](https://circleci.com/gh/ideal-postcodes/core-interface/tree/master.svg?style=svg)](https://circleci.com/gh/ideal-postcodes/core-interface/tree/master) | ||
[![Coverage Status](https://coveralls.io/repos/github/ideal-postcodes/core-interface/badge.svg?branch=master)](https://coveralls.io/github/ideal-postcodes/core-interface?branch=master) | ||
[![Coverage Status](https://coveralls.io/repos/github/ideal-postcodes/core-interface/badge.svg?branch=master&t=nyUaqN)](https://coveralls.io/github/ideal-postcodes/core-interface?branch=master) | ||
![Dependency Status](https://david-dm.org/ideal-postcodes/core-interface.svg) | ||
@@ -15,6 +15,7 @@ [![BrowserStack Status](https://www.browserstack.com/automate/badge.svg?badge_key=RGl2bTU2Z3l4MGZNR1ZZREpyajlNaXZFMElZMkNCNENKRHNCMCtyVTBrbz0tLXdVODl3TlRJejA1MWpiTzYzaTBsZ1E9PQ==--8eb0b38bd782e0145dc4dc01e093c861828dbfa8)](https://www.browserstack.com/automate/public-build/RGl2bTU2Z3l4MGZNR1ZZREpyajlNaXZFMElZMkNCNENKRHNCMCtyVTBrbz0tLXdVODl3TlRJejA1MWpiTzYzaTBsZ1E9PQ==--8eb0b38bd782e0145dc4dc01e093c861828dbfa8) | ||
![npm bundle size (scoped)](https://img.shields.io/bundlephobia/minzip/@ideal-postcodes/core-interface.svg?color=%234c1&style=popout) | ||
[![install size](https://packagephobia.now.sh/badge?p=@ideal-postcodes/core-interface)](https://packagephobia.now.sh/result?p=@ideal-postcodes/core-interface) | ||
`@ideal-postcodes/core-interface` is an environment agnostic implementation of the Ideal Postcodes javascript API client interface. | ||
If you are looking for a browser or node.js client, please check out the downstream clients in the [links](#links) below. | ||
If you are looking for the browser or node.js client which implements this interface, please check out the [downstream clients links](#downstream-clients). | ||
@@ -24,11 +25,20 @@ ## Links | ||
- [API Documentation](https://core-interface.ideal-postcodes.dev/) | ||
- [NPM Module](https://www.npmjs.com/package/@ideal-postcodes/core-interface) | ||
- [npm Module](https://www.npmjs.com/package/@ideal-postcodes/core-interface) | ||
- [Github Repository](https://github.com/ideal-postcodes/core-interface) | ||
- [Browser Client Repository](https://github.com/ideal-postcodes/core-browser) | ||
- [Node.js Client](https://github.com/ideal-postcodes/core-node) | ||
- [Typings Repository](https://github.com/ideal-postcodes/api-typings) | ||
- [Fixtures Repository](https://github.com/ideal-postcodes/api-fixtures) | ||
## Downstream Clients | ||
- [Browser Client Repository](https://github.com/ideal-postcodes/core-browser) | ||
- [Bundled Browser Client Repository](https://github.com/ideal-postcodes/core-browser-bundled) | ||
- [Node.js Client Repository](https://github.com/ideal-postcodes/core-node) | ||
## Documentation | ||
- [Usage & Configuration](#usage) | ||
- [Quick Methods](#quick-methods) | ||
- [Resource Methods](#resource-methods) | ||
- [Error Handling](#error-handling) | ||
### Methods | ||
@@ -54,6 +64,6 @@ | ||
```javascript | ||
const api_key = "iddqd"; | ||
const client = new Client({ | ||
api_key: "iddqd", | ||
}); | ||
const client = new Client({ api_key }); | ||
// Only api_key is required by core-node and core-browser - all others are optional | ||
@@ -63,4 +73,109 @@ // The agentless interface requires explicit configuration | ||
Configuration options [outlined in the docs](https://core-interface.ideal-postcodes.dev/docs/interfaces/config.html) | ||
More configuration options [outlined in the docs](https://core-interface.ideal-postcodes.dev/interfaces/config.html) | ||
--- | ||
#### Quick Methods | ||
The client exposes a number of simple methods to get at the most common tasks when interacting with the API. | ||
- [Lookup a Postcode](#lookup-a-postcode) | ||
- [Search for an Address](#search-for-an-address) | ||
- [Search for an Address by UDPRN](#search-for-an-address-by-udprn) | ||
- [Search for an Address by UMPRN](#search-for-an-address-by-umprn) | ||
- [Check Key Usability](#check-key-usability) | ||
#### Lookup a Postcode | ||
Return addresses associated with a given `postcode` | ||
```javascript | ||
const postcode = "id11qd"; | ||
client.lookupPostcode({ postcode }).then(addresses => { | ||
console.log(addresses); | ||
{ | ||
postcode: "ID1 1QD", | ||
line_1: "2 Barons Court Road", | ||
// ...etc... | ||
} | ||
}); | ||
``` | ||
Method options [outlined in the docs](https://core-interface.ideal-postcodes.dev/interfaces/lookuppostcodeoptions.html) | ||
#### Search for an Address | ||
Return addresses associated with a given `query` | ||
```javascript | ||
const query = "10 downing street sw1a"; | ||
client.lookupAddress({ query }).then(addresses => { | ||
console.log(addresses); | ||
{ | ||
postcode: "SW1A 2AA", | ||
line_1: "Prime Minister & First Lord Of The Treasury", | ||
// ...etc... | ||
} | ||
}); | ||
``` | ||
Method options [outlined in the docs](https://core-interface.ideal-postcodes.dev/interfaces/lookupaddressoptions.html) | ||
#### Search for an Address by UDPRN | ||
Return address for a given `udprn` | ||
Invalid UDPRN will return `null` | ||
```javascript | ||
const udprn = 23747771; | ||
client.lookupUdprn({ udprn }).then(address => { | ||
console.log(address); | ||
{ | ||
postcode: "SW1A 2AA", | ||
line_1: "Prime Minister & First Lord Of The Treasury", | ||
// ...etc... | ||
} | ||
}); | ||
``` | ||
Method options [outlined in the docs](https://core-interface.ideal-postcodes.dev/interfaces/lookupudprnoptions.html) | ||
#### Search for an Address by UMPRN | ||
Return address for a given `umprn` | ||
Invalid UMPRN will return `null` | ||
```javascript | ||
const umprn = 50906066; | ||
client.lookupUmprn({ umprn }).then(address => { | ||
console.log(address); | ||
{ | ||
postcode: "CV4 7AL", | ||
line_1: "Room 1, Block 1 Arthur Vick", | ||
// ...etc... | ||
} | ||
}); | ||
``` | ||
Method options [outlined in the docs](https://core-interface.ideal-postcodes.dev/interfaces/lookupumprnoptions.html) | ||
#### Check Key Usability | ||
Check if a key is currently usable | ||
```javascript | ||
client.checkKeyUsability({}).then(key => { | ||
console.log(key.available); // => true | ||
}); | ||
``` | ||
Method options [outlined in the docs](https://core-interface.ideal-postcodes.dev/interfaces/checkkeyusabilityoptions.html) | ||
--- | ||
#### Resource Methods | ||
@@ -130,4 +245,8 @@ | ||
#### Available Resources | ||
--- | ||
#### Resource Methods | ||
Listed below are the available resources exposed by the client: | ||
- [Postcodes](#postcodes) | ||
@@ -264,8 +383,49 @@ - [Addresses](#addresses) | ||
### Errors | ||
--- | ||
For more advanced use cases, this library also exports: | ||
#### Error Handling | ||
`Client` exports a static variable `errors` which contains custom error constructors that wrap specific API errors. These constructors can be used to test for specific cases using the `instanceof` operator. | ||
For example: | ||
```javascript | ||
const { IdpcInvalidKeyError } = Client.errors; | ||
try { | ||
const addresses = client.lookupPostcode({ postcode: "SW1A2AA" }); | ||
} catch (error) { | ||
if (error instanceof IdpcInvalidKeyError) { | ||
// Handle an invalid key error | ||
} | ||
} | ||
``` | ||
Not all specific API errors will be caught. If a specific API error does not have an error constructor defined, a more generic error (determined by the HTTP status code) will be returned. | ||
For example: | ||
```javascript | ||
const { IdpcRequestFailedError } = Client.errors; | ||
try { | ||
const addresses = client.lookupPostcode({ postcode: "SW1A2AA" }); | ||
} catch (error) { | ||
if (error instanceof IdpcRequestFailedError) { | ||
// IdpcRequestFailedError indicates a 402 response code | ||
// Possibly the key balance has been depleted | ||
} | ||
} | ||
``` | ||
A sketch of the error prototype chain can be found [here](#error-prototype-chain) | ||
--- | ||
### Core Interface Errors | ||
For more advanced use cases, this core-interface library provides: | ||
- Class implementations for Ideal Postcodes API errors that inherit from `Error` | ||
- A parser that converts raw error data into an error instance | ||
- A parser that converts raw error data into one of these error instances | ||
@@ -330,3 +490,3 @@ #### Usage | ||
Errors consume a HTTP API response | ||
The error parser consumes a HTTP API response and returns the correct error instance. | ||
@@ -333,0 +493,0 @@ ```javascript |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
85408
43
1589
509