Socket
Socket
Sign inDemoInstall

@ideal-postcodes/core-interface

Package Overview
Dependencies
Maintainers
1
Versions
21
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@ideal-postcodes/core-interface - npm Package Compare versions

Comparing version 1.9.0 to 2.0.0

dist/helpers.d.ts
dist/helpers.js
esm/helpers.d.ts
esm/helpers.js

27

CHANGELOG.md

@@ -0,1 +1,28 @@

# [2.0.0](https://github.com/ideal-postcodes/core-interface/compare/1.9.0...2.0.0) (2021-06-04)
### Code Refactoring
* **Defaults:** Export `defaults` object ([6b9b698](https://github.com/ideal-postcodes/core-interface/commit/6b9b6981abd517061621436a2afef0f4f62cddb7))
### Features
* **Version 2:** Reduce package size ([cfcae8a](https://github.com/ideal-postcodes/core-interface/commit/cfcae8a7087708820ec0ca1b2d97df3dabd056f5))
### BREAKING CHANGES
* **Version 2:** - Package now exports a `defaults` object
- Client.defaults has been removed
- All client config is now stored in `client.config`
- All resources have been removed from the client. Instead retrieve
these from the library and inject the client. E.g.
`client.postcodes.retrieve` becomes `postcodes.retrieve(client, ...)`
- Helper methods (like lookupPostcode, ping) have been removed from the client.
Instead retrieve these from teh library and inject the client. E.g.
`client.lookupPostcode` becomes `lookupPostcode(client, ...)`
* **Defaults:** Uppercased default variables no longer exported.
Instead `defaults` object is supplied
# [1.9.0](https://github.com/ideal-postcodes/core-interface/compare/1.8.1...1.9.0) (2021-01-15)

@@ -2,0 +29,0 @@

4

dist/agent.d.ts

@@ -52,5 +52,3 @@ /**

}
export interface StringMap {
[key: string]: string;
}
export declare type StringMap = Record<string, string>;
/**

@@ -57,0 +55,0 @@ * Header

179

dist/client.d.ts

@@ -1,9 +0,11 @@

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";
import { Agent, Header } from "./agent";
declare type Protocol = "http" | "https";
/**
* Client Configuration Object
*/
export interface Config {
/**
* Use TLS. Defaults to `true`
* Use TLS
*
* @default true
*/

@@ -13,20 +15,30 @@ tls: boolean;

* API Key. Used in API helper methods
*
* @default ""
*/
api_key: string;
/**
* Target API hostname. Defaults to `'api.ideal-postcodes.co.uk'`
* Target API domain
*
* @default "api.ideal-postcodes.co.uk"
*/
baseUrl: string;
/**
* API version. Defaults to `'v1'`
* API version
*
* @default "v1"
*/
version: string;
/**
* Force autocomplete authorisation via HTTP headers only. Defaults to `false`
* Force autocomplete authorisation via HTTP headers only
*
* @default false
*/
strictAuthorisation: boolean;
strictAuthorisation?: boolean;
/**
* Default time in ms before HTTP request timeout. Defaults to 10s (`10000`)
*
* @default 10000
*/
timeout: number;
timeout?: number;
/**

@@ -37,7 +49,9 @@ * HTTP Agent

*/
agent: Agent;
agent?: Agent;
/**
* String map specifying default headers
*
* @default {}
*/
header: Header;
header?: Header;
/**

@@ -47,75 +61,16 @@ * Append tags to helper requests like `lookupPostcode` and `lookupUDPRN`

* Tags attached to the client are overwritten on an request if it is also specified in the helper request options
*
* @default []
*/
tags: string[];
tags?: string[];
}
interface Defaults {
header: Header;
}
import { AddressResource } from "./resources/addresses";
import { PostcodeResource } from "./resources/postcodes";
import { KeyResource } from "./resources/keys";
import { UdprnResource } from "./resources/udprn";
import { UmprnResource } from "./resources/umprn";
import { AutocompleteResource } from "./resources/autocomplete";
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;
/**
* Checks API Key and licensee combination. This checks whether a particular
* licensee can use the API
*/
licensee?: string;
}
/**
* Default configuration
*/
export declare const defaults: Required<Config>;
/**
* Client Class
*/
export declare class Client {
static defaults: Defaults;
readonly tls: boolean;
readonly api_key: string;
readonly baseUrl: string;
readonly version: string;
readonly strictAuthorisation: boolean;
readonly timeout: number;
readonly agent: Agent;
readonly header: Header;
readonly tags: string[];
readonly postcodes: PostcodeResource;
readonly addresses: AddressResource;
readonly udprn: UdprnResource;
readonly umprn: UmprnResource;
readonly keys: KeyResource;
readonly autocomplete: AutocompleteResource;
static errors: typeof errors;
config: Required<Config>;
constructor(config: Config);

@@ -127,63 +82,3 @@ /**

protocol(): Protocol;
/**
* Ping API base (`/`)
*
* Dispatches HTTP request to root endpoint "`/`"
*/
ping(): Promise<HttpResponse>;
/**
* Lookup Postcode
*
* 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[]>;
/**
* Lookup Address
*
* Search for an address given a query
*
* [API Documentation for /addresses](https://ideal-postcodes.co.uk/documentation/addresses#query)
*/
lookupAddress(options: LookupAddressOptions): Promise<Address[]>;
/**
* 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;
/**
* Lookup UDPRN
*
* 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>;
/**
* Lookup UMPRN
*
* 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>;
/**
* Check Key Availability
*
* Checks if a key can bey used
*
* [API Documentation for /keys]()https://ideal-postcodes.co.uk/documentation/keys#key)
*/
checkKeyUsability(options: CheckKeyUsabilityOptions): Promise<KeyStatus>;
}
export {};

223

dist/client.js

@@ -13,49 +13,28 @@ "use strict";

};
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
__setModuleDefault(result, mod);
return result;
Object.defineProperty(exports, "__esModule", { value: true });
exports.Client = exports.defaults = void 0;
/**
* Default configuration
*/
exports.defaults = {
tls: true,
api_key: "",
baseUrl: "api.ideal-postcodes.co.uk",
version: "v1",
strictAuthorisation: false,
timeout: 10000,
header: {
Accept: "application/json",
"Content-Type": "application/json",
},
tags: [],
agent: {},
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.Client = void 0;
var error_1 = require("./error");
var errors = __importStar(require("./error"));
var util_1 = require("./util");
var addresses_1 = require("./resources/addresses");
var postcodes_1 = require("./resources/postcodes");
var keys_1 = require("./resources/keys");
var udprn_1 = require("./resources/udprn");
var umprn_1 = require("./resources/umprn");
var autocomplete_1 = require("./resources/autocomplete");
/**
* Client Class
*/
var Client = /** @class */ (function () {
function Client(config) {
this.tls = config.tls;
this.api_key = config.api_key;
this.baseUrl = config.baseUrl;
this.version = config.version;
this.strictAuthorisation = config.strictAuthorisation;
this.timeout = config.timeout;
this.agent = config.agent;
this.tags = config.tags;
this.header = __assign(__assign({}, Client.defaults.header), config.header);
this.postcodes = postcodes_1.create(this);
this.addresses = addresses_1.create(this);
this.udprn = udprn_1.create(this);
this.umprn = umprn_1.create(this);
this.keys = keys_1.create(this);
this.autocomplete = autocomplete_1.create(this);
this.config = __assign(__assign({}, exports.defaults), config);
this.config.header = __assign(__assign({}, exports.defaults.header), (config.header && config.header));
}

@@ -66,160 +45,10 @@ /**

Client.prototype.url = function () {
return this.protocol() + "://" + this.baseUrl + "/" + this.version;
var _a = this.config, baseUrl = _a.baseUrl, version = _a.version;
return this.protocol() + "://" + baseUrl + "/" + version;
};
Client.prototype.protocol = function () {
return this.tls ? "https" : "http";
return this.config.tls ? "https" : "http";
};
/**
* Ping API base (`/`)
*
* Dispatches HTTP request to root endpoint "`/`"
*/
Client.prototype.ping = function () {
var method = "GET";
var url = this.protocol() + "://" + this.baseUrl + "/";
return this.agent.http({
method: method,
url: url,
header: {},
query: {},
timeout: this.timeout,
});
};
/**
* Lookup Postcode
*
* 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;
});
};
/**
* Lookup Address
*
* 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({ client: this, 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; });
};
/**
* 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({ client: this, query: query, options: options });
var request = { header: header, query: query };
if (options.timeout !== undefined)
request.timeout = options.timeout;
return request;
};
/**
* Lookup UDPRN
*
* 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;
});
};
/**
* Lookup UMPRN
*
* 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;
});
};
/**
* Check Key Availability
*
* Checks if a key can bey used
*
* [API Documentation for /keys]()https://ideal-postcodes.co.uk/documentation/keys#key)
*/
Client.prototype.checkKeyUsability = function (options) {
var _a = options.api_key, api_key = _a === void 0 ? this.api_key : _a, timeout = options.timeout;
var licensee = options.licensee;
var query;
if (licensee === undefined) {
query = {};
}
else {
query = { licensee: licensee };
}
var queryOptions = { query: 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 = {
header: {
Accept: "application/json",
"Content-Type": "application/json",
},
};
Client.errors = errors;
return Client;
}());
exports.Client = Client;

5

dist/error.js

@@ -10,2 +10,4 @@ "use strict";

return function (d, b) {
if (typeof b !== "function" && b !== null)
throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
extendStatics(d, b);

@@ -301,3 +303,3 @@ function __() { this.constructor = d; }

*/
exports.parse = function (response) {
var parse = function (response) {
var httpStatus = response.httpStatus, body = response.body;

@@ -338,1 +340,2 @@ if (isSuccess(httpStatus))

};
exports.parse = parse;

30

dist/index.d.ts
/**
* Constants
*/
/**
* Default API endpoint
*/
export declare const API_URL = "api.ideal-postcodes.co.uk";
/**
* Use TLS by default. Set to `true`
*/
export declare const TLS = true;
/**
* Default API Version number. Defaults to "v1"
*/
export declare const VERSION = "v1";
/**
* Default HTTP timeout in milliseconds. Defaults to 10s
*/
export declare const TIMEOUT = 10000;
export declare const STRICT_AUTHORISATION = false;
export { Client, Config } from "./client";
export { Client, Config, defaults } from "./client";
export { Agent, HttpRequest, HttpResponse } from "./agent";
import * as errors from "./error";
export { errors };
export * as addresses from "./resources/addresses";
export * as autocomplete from "./resources/autocomplete";
export * as keys from "./resources/keys";
export * as postcodes from "./resources/postcodes";
export * as udprn from "./resources/udprn";
export * as umprn from "./resources/umprn";
export * from "./helpers";
export * from "./types";
export * as errors from "./error";

41

dist/index.js
"use strict";
/**
* Constants
*/
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {

@@ -24,29 +21,21 @@ if (k2 === undefined) k2 = k;

};
var __exportStar = (this && this.__exportStar) || function(m, exports) {
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.errors = exports.Client = exports.STRICT_AUTHORISATION = exports.TIMEOUT = exports.VERSION = exports.TLS = exports.API_URL = void 0;
exports.errors = exports.umprn = exports.udprn = exports.postcodes = exports.keys = exports.autocomplete = exports.addresses = exports.defaults = exports.Client = void 0;
/**
* Default API endpoint
* Constants
*/
exports.API_URL = "api.ideal-postcodes.co.uk";
/**
* Use TLS by default. Set to `true`
*/
exports.TLS = true;
/**
* Default API Version number. Defaults to "v1"
*/
exports.VERSION = "v1";
/**
* Default HTTP timeout in milliseconds. Defaults to 10s
*/
exports.TIMEOUT = 10000;
/*
* STRICT_AUTHORISATION forces authorization header usage on
* autocomplete API which increases latency due to overhead
* OPTIONS request
*/
exports.STRICT_AUTHORISATION = false;
var client_1 = require("./client");
Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
var errors = __importStar(require("./error"));
exports.errors = errors;
Object.defineProperty(exports, "defaults", { enumerable: true, get: function () { return client_1.defaults; } });
exports.addresses = __importStar(require("./resources/addresses"));
exports.autocomplete = __importStar(require("./resources/autocomplete"));
exports.keys = __importStar(require("./resources/keys"));
exports.postcodes = __importStar(require("./resources/postcodes"));
exports.udprn = __importStar(require("./resources/udprn"));
exports.umprn = __importStar(require("./resources/umprn"));
__exportStar(require("./helpers"), exports);
__exportStar(require("./types"), exports);
exports.errors = __importStar(require("./error"));

6

dist/resources/addresses.d.ts

@@ -44,6 +44,6 @@ import { AddressQueryResponse } from "@ideal-postcodes/api-typings";

}
export interface AddressResource {
list(request: Request): Promise<Response>;
export interface List {
(client: Client, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => AddressResource;
export declare const list: List;
export {};

8

dist/resources/addresses.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.create = void 0;
exports.list = void 0;
var resource_1 = require("./resource");
var resource = "addresses";
exports.create = function (client) {
var list = resource_1.listMethod({ resource: resource, client: client });
return { list: list };
var list = function (client, request) {
return resource_1.listMethod({ resource: resource, client: client })(request);
};
exports.list = list;

5

dist/resources/autocomplete.d.ts

@@ -43,3 +43,6 @@ import { AddressSuggestionResponse } from "@ideal-postcodes/api-typings";

}
export declare const create: (client: Client) => AutocompleteResource;
export interface List {
(client: Client, request: Request): Promise<Response>;
}
export declare const list: List;
export {};

11

dist/resources/autocomplete.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.create = void 0;
exports.list = void 0;
var resource_1 = require("./resource");
var resource = "autocomplete/addresses";
exports.create = function (client) {
var list = resource_1.listMethod({
resource: resource,
client: client,
});
return { list: list };
var list = function (client, request) {
return resource_1.listMethod({ resource: resource, client: client })(request);
};
exports.list = list;

11

dist/resources/keys.d.ts

@@ -32,7 +32,10 @@ import { PublicKeyResponse, PrivateKeyResponse, KeyUsageResponse } from "@ideal-postcodes/api-typings";

}
export interface KeyResource {
retrieve(key: string, request: Request): Promise<Response>;
usage(postcode: string, request: UsageRequest): Promise<UsageResponse>;
export interface Retrieve {
(client: Client, apiKey: string, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => KeyResource;
export declare const retrieve: Retrieve;
export interface Usage {
(client: Client, apiKey: string, request: UsageRequest): Promise<UsageResponse>;
}
export declare const usage: Usage;
export {};

17

dist/resources/keys.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.create = void 0;
exports.usage = exports.retrieve = void 0;
var resource_1 = require("./resource");
var resource = "keys";
exports.create = function (client) {
var retrieve = resource_1.retrieveMethod({
var retrieve = function (client, apiKey, request) {
return resource_1.retrieveMethod({
resource: resource,
client: client,
});
var usage = resource_1.retrieveMethod({
})(apiKey, request);
};
exports.retrieve = retrieve;
var usage = function (client, apiKey, request) {
return resource_1.retrieveMethod({
resource: resource,
client: client,
action: "usage",
});
return { retrieve: retrieve, usage: usage };
})(apiKey, request);
};
exports.usage = usage;

5

dist/resources/postcodes.d.ts

@@ -27,3 +27,6 @@ import { PostcodesResponse } from "@ideal-postcodes/api-typings";

}
export declare const create: (client: Client) => PostcodeResource;
export interface Retrieve {
(client: Client, postcode: string, request: Request): Promise<Response>;
}
export declare const retrieve: Retrieve;
export {};

10

dist/resources/postcodes.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.create = void 0;
exports.retrieve = void 0;
var resource_1 = require("./resource");
var resource = "postcodes";
exports.create = function (client) {
var retrieve = resource_1.retrieveMethod({
var retrieve = function (client, postcode, request) {
return resource_1.retrieveMethod({
resource: resource,
client: client,
});
return { retrieve: retrieve };
})(postcode, request);
};
exports.retrieve = retrieve;

10

dist/resources/resource.js

@@ -17,6 +17,6 @@ "use strict";

};
exports.retrieveMethod = function (options) {
var retrieveMethod = function (options) {
var client = options.client;
return function (id, request) {
return client.agent
return client.config.agent
.http({

@@ -37,6 +37,7 @@ method: "GET",

};
exports.listMethod = function (options) {
exports.retrieveMethod = retrieveMethod;
var listMethod = function (options) {
var client = options.client, resource = options.resource;
return function (request) {
return client.agent
return client.config.agent
.http({

@@ -57,1 +58,2 @@ method: "GET",

};
exports.listMethod = listMethod;

6

dist/resources/udprn.d.ts

@@ -23,6 +23,6 @@ import { UdprnResponse } from "@ideal-postcodes/api-typings";

}
export interface UdprnResource {
retrieve(udprn: string, request: Request): Promise<Response>;
export interface Retrieve {
(client: Client, udprn: string, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => UdprnResource;
export declare const retrieve: Retrieve;
export {};

8

dist/resources/udprn.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.create = void 0;
exports.retrieve = void 0;
var resource_1 = require("./resource");
var resource = "udprn";
exports.create = function (client) {
var retrieve = resource_1.retrieveMethod({ resource: resource, client: client });
return { retrieve: retrieve };
var retrieve = function (client, udprn, request) {
return resource_1.retrieveMethod({ resource: resource, client: client })(udprn, request);
};
exports.retrieve = retrieve;

6

dist/resources/umprn.d.ts

@@ -23,6 +23,6 @@ import { UmprnResponse } from "@ideal-postcodes/api-typings";

}
export interface UmprnResource {
retrieve(umprn: string, request: Request): Promise<Response>;
export interface Retrieve {
(client: Client, umprn: string, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => UmprnResource;
export declare const retrieve: Retrieve;
export {};

8

dist/resources/umprn.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.create = void 0;
exports.retrieve = void 0;
var resource_1 = require("./resource");
var resource = "umprn";
exports.create = function (client) {
var retrieve = resource_1.retrieveMethod({ resource: resource, client: client });
return { retrieve: retrieve };
var retrieve = function (client, umprn, request) {
return resource_1.retrieveMethod({ resource: resource, client: client })(umprn, request);
};
exports.retrieve = retrieve;

37

dist/util.js

@@ -20,3 +20,3 @@ "use strict";

*/
exports.toStringMap = function (optional) {
var toStringMap = function (optional) {
if (optional === undefined)

@@ -32,2 +32,3 @@ return {};

};
exports.toStringMap = toStringMap;
var isString = function (i) { return typeof i === "string"; };

@@ -59,8 +60,9 @@ var isArray = function (i) { return Array.isArray(i); };

*/
exports.toTimeout = function (_a, client) {
var toTimeout = function (_a, client) {
var timeout = _a.timeout;
if (isNumber(timeout))
return timeout;
return client.timeout;
return client.config.timeout;
};
exports.toTimeout = toTimeout;
/**

@@ -73,6 +75,7 @@ * toHeader

*/
exports.toHeader = function (_a, client) {
var toHeader = function (_a, client) {
var _b = _a.header, header = _b === void 0 ? {} : _b;
return __assign(__assign({}, client.header), exports.toStringMap(header));
return __assign(__assign({}, client.config.header), exports.toStringMap(header));
};
exports.toHeader = toHeader;
/**

@@ -83,5 +86,5 @@ * toAuthHeader

*/
exports.toAuthHeader = function (client, options) {
var toAuthHeader = function (client, options) {
var credentials = [];
var api_key = options.api_key || client.api_key;
var api_key = options.api_key || client.config.api_key;
credentials.push(["api_key", api_key]);

@@ -96,2 +99,3 @@ var licensee = options.licensee;

};
exports.toAuthHeader = toAuthHeader;
/**

@@ -105,3 +109,3 @@ * appendAuthorization

*/
exports.appendAuthorization = function (_a) {
var appendAuthorization = function (_a) {
var header = _a.header, options = _a.options, client = _a.client;

@@ -111,2 +115,3 @@ header.Authorization = exports.toAuthHeader(client, options);

};
exports.appendAuthorization = appendAuthorization;
var toCredentialString = function (credentials) {

@@ -119,3 +124,3 @@ return credentials.map(function (_a) {

// Adds source IP to headers
exports.appendIp = function (_a) {
var appendIp = function (_a) {
var header = _a.header, options = _a.options;

@@ -127,4 +132,5 @@ var sourceIp = options.sourceIp;

};
exports.appendIp = appendIp;
// Adds filters to query
exports.appendFilter = function (_a) {
var appendFilter = function (_a) {
var query = _a.query, options = _a.options;

@@ -136,8 +142,9 @@ var filter = options.filter;

};
exports.appendFilter = appendFilter;
// Adds tags to query
exports.appendTags = function (_a) {
var appendTags = function (_a) {
var client = _a.client, query = _a.query, options = _a.options;
var tags;
if (client.tags.length)
tags = client.tags;
if (client.config.tags.length)
tags = client.config.tags;
if (options.tags)

@@ -149,4 +156,5 @@ tags = options.tags;

};
exports.appendTags = appendTags;
// Adds pagination attributes to query
exports.appendPage = function (_a) {
var appendPage = function (_a) {
var query = _a.query, options = _a.options;

@@ -160,1 +168,2 @@ var page = options.page, limit = options.limit;

};
exports.appendPage = appendPage;

4

esm/agent.d.ts

@@ -52,5 +52,3 @@ /**

}
export interface StringMap {
[key: string]: string;
}
export declare type StringMap = Record<string, string>;
/**

@@ -57,0 +55,0 @@ * Header

179

esm/client.d.ts

@@ -1,9 +0,11 @@

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";
import { Agent, Header } from "./agent";
declare type Protocol = "http" | "https";
/**
* Client Configuration Object
*/
export interface Config {
/**
* Use TLS. Defaults to `true`
* Use TLS
*
* @default true
*/

@@ -13,20 +15,30 @@ tls: boolean;

* API Key. Used in API helper methods
*
* @default ""
*/
api_key: string;
/**
* Target API hostname. Defaults to `'api.ideal-postcodes.co.uk'`
* Target API domain
*
* @default "api.ideal-postcodes.co.uk"
*/
baseUrl: string;
/**
* API version. Defaults to `'v1'`
* API version
*
* @default "v1"
*/
version: string;
/**
* Force autocomplete authorisation via HTTP headers only. Defaults to `false`
* Force autocomplete authorisation via HTTP headers only
*
* @default false
*/
strictAuthorisation: boolean;
strictAuthorisation?: boolean;
/**
* Default time in ms before HTTP request timeout. Defaults to 10s (`10000`)
*
* @default 10000
*/
timeout: number;
timeout?: number;
/**

@@ -37,7 +49,9 @@ * HTTP Agent

*/
agent: Agent;
agent?: Agent;
/**
* String map specifying default headers
*
* @default {}
*/
header: Header;
header?: Header;
/**

@@ -47,75 +61,16 @@ * Append tags to helper requests like `lookupPostcode` and `lookupUDPRN`

* Tags attached to the client are overwritten on an request if it is also specified in the helper request options
*
* @default []
*/
tags: string[];
tags?: string[];
}
interface Defaults {
header: Header;
}
import { AddressResource } from "./resources/addresses";
import { PostcodeResource } from "./resources/postcodes";
import { KeyResource } from "./resources/keys";
import { UdprnResource } from "./resources/udprn";
import { UmprnResource } from "./resources/umprn";
import { AutocompleteResource } from "./resources/autocomplete";
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;
/**
* Checks API Key and licensee combination. This checks whether a particular
* licensee can use the API
*/
licensee?: string;
}
/**
* Default configuration
*/
export declare const defaults: Required<Config>;
/**
* Client Class
*/
export declare class Client {
static defaults: Defaults;
readonly tls: boolean;
readonly api_key: string;
readonly baseUrl: string;
readonly version: string;
readonly strictAuthorisation: boolean;
readonly timeout: number;
readonly agent: Agent;
readonly header: Header;
readonly tags: string[];
readonly postcodes: PostcodeResource;
readonly addresses: AddressResource;
readonly udprn: UdprnResource;
readonly umprn: UmprnResource;
readonly keys: KeyResource;
readonly autocomplete: AutocompleteResource;
static errors: typeof errors;
config: Required<Config>;
constructor(config: Config);

@@ -127,63 +82,3 @@ /**

protocol(): Protocol;
/**
* Ping API base (`/`)
*
* Dispatches HTTP request to root endpoint "`/`"
*/
ping(): Promise<HttpResponse>;
/**
* Lookup Postcode
*
* 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[]>;
/**
* Lookup Address
*
* Search for an address given a query
*
* [API Documentation for /addresses](https://ideal-postcodes.co.uk/documentation/addresses#query)
*/
lookupAddress(options: LookupAddressOptions): Promise<Address[]>;
/**
* 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;
/**
* Lookup UDPRN
*
* 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>;
/**
* Lookup UMPRN
*
* 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>;
/**
* Check Key Availability
*
* Checks if a key can bey used
*
* [API Documentation for /keys]()https://ideal-postcodes.co.uk/documentation/keys#key)
*/
checkKeyUsability(options: CheckKeyUsabilityOptions): Promise<KeyStatus>;
}
export {};

205

esm/client.js

@@ -1,27 +0,28 @@

import { IdpcPostcodeNotFoundError, IdpcUmprnNotFoundError, IdpcUdprnNotFoundError, } from "./error";
import * as errors from "./error";
import { appendAuthorization, appendPage, appendIp, appendFilter, appendTags, } from "./util";
import { create as createAddressResource, } from "./resources/addresses";
import { create as createPostcodeResource, } from "./resources/postcodes";
import { create as createKeyResource } from "./resources/keys";
import { create as createUdprnResource, } from "./resources/udprn";
import { create as createUmprnResource, } from "./resources/umprn";
import { create as createAutocompleteResource, } from "./resources/autocomplete";
/**
* Default configuration
*/
export const defaults = {
tls: true,
api_key: "",
baseUrl: "api.ideal-postcodes.co.uk",
version: "v1",
strictAuthorisation: false,
timeout: 10000,
header: {
Accept: "application/json",
"Content-Type": "application/json",
},
tags: [],
agent: {},
};
/**
* Client Class
*/
export class Client {
constructor(config) {
this.tls = config.tls;
this.api_key = config.api_key;
this.baseUrl = config.baseUrl;
this.version = config.version;
this.strictAuthorisation = config.strictAuthorisation;
this.timeout = config.timeout;
this.agent = config.agent;
this.tags = config.tags;
this.header = { ...Client.defaults.header, ...config.header };
this.postcodes = createPostcodeResource(this);
this.addresses = createAddressResource(this);
this.udprn = createUdprnResource(this);
this.umprn = createUmprnResource(this);
this.keys = createKeyResource(this);
this.autocomplete = createAutocompleteResource(this);
this.config = { ...defaults, ...config };
this.config.header = {
...defaults.header,
...(config.header && config.header),
};
}

@@ -32,158 +33,8 @@ /**

url() {
return `${this.protocol()}://${this.baseUrl}/${this.version}`;
const { baseUrl, version } = this.config;
return `${this.protocol()}://${baseUrl}/${version}`;
}
protocol() {
return this.tls ? "https" : "http";
return this.config.tls ? "https" : "http";
}
/**
* Ping API base (`/`)
*
* Dispatches HTTP request to root endpoint "`/`"
*/
ping() {
const method = "GET";
const url = `${this.protocol()}://${this.baseUrl}/`;
return this.agent.http({
method,
url,
header: {},
query: {},
timeout: this.timeout,
});
}
/**
* Lookup Postcode
*
* 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) {
const queryOptions = this.toAddressIdQuery(options);
const { page } = options;
if (page !== undefined)
queryOptions.query.page = page.toString();
return this.postcodes
.retrieve(options.postcode, queryOptions)
.then((response) => response.body.result)
.catch((error) => {
if (error instanceof IdpcPostcodeNotFoundError)
return [];
throw error;
});
}
/**
* Lookup Address
*
* Search for an address given a query
*
* [API Documentation for /addresses](https://ideal-postcodes.co.uk/documentation/addresses#query)
*/
lookupAddress(options) {
const header = {};
const query = { query: options.query };
appendAuthorization({ client: this, header, options });
appendIp({ header, options });
appendFilter({ query, options });
appendTags({ client: this, query, options });
appendPage({ query, options });
const queryOptions = { header, query };
if (options.timeout !== undefined)
queryOptions.timeout = options.timeout;
return this.addresses
.list(queryOptions)
.then((response) => response.body.result.hits);
}
/**
* Generates a request object. Bundles together commonly used header/query extractions:
* - Authorization (api_key, licensee, user_token)
* - Source IP forwarding
* - Result filtering
* - Tagging
*/
toAddressIdQuery(options) {
const header = {};
const query = {};
appendAuthorization({ client: this, header, options });
appendIp({ header, options });
appendFilter({ query, options });
appendTags({ client: this, query, options });
const request = { header, query };
if (options.timeout !== undefined)
request.timeout = options.timeout;
return request;
}
/**
* Lookup UDPRN
*
* Search for an address given a UDPRN
*
* Invalid UDPRN returns `null`
*
* [API Documentation for /udprn](https://ideal-postcodes.co.uk/documentation/udprn)
*/
lookupUdprn(options) {
const queryOptions = this.toAddressIdQuery(options);
return this.udprn
.retrieve(options.udprn.toString(), queryOptions)
.then((response) => response.body.result)
.catch((error) => {
if (error instanceof IdpcUdprnNotFoundError)
return null;
throw error;
});
}
/**
* Lookup UMPRN
*
* Search for an address given a UDPRN
*
* Invalid UDPRN returns `null`
*
* [API Documentation for /udprn](https://ideal-postcodes.co.uk/documentation/udprn)
*/
lookupUmprn(options) {
const queryOptions = this.toAddressIdQuery(options);
return this.umprn
.retrieve(options.umprn.toString(), queryOptions)
.then((response) => response.body.result)
.catch((error) => {
if (error instanceof IdpcUmprnNotFoundError)
return null;
throw error;
});
}
/**
* Check Key Availability
*
* Checks if a key can bey used
*
* [API Documentation for /keys]()https://ideal-postcodes.co.uk/documentation/keys#key)
*/
checkKeyUsability(options) {
const { api_key = this.api_key, timeout } = options;
const { licensee } = options;
let query;
if (licensee === undefined) {
query = {};
}
else {
query = { licensee };
}
const queryOptions = { query, header: {} };
if (timeout !== undefined)
queryOptions.timeout = timeout;
return this.keys
.retrieve(api_key, queryOptions)
.then((response) => response.body.result); // Assert that we're retrieving public key information as no user_token provided
}
}
Client.defaults = {
header: {
Accept: "application/json",
"Content-Type": "application/json",
},
};
Client.errors = errors;

30

esm/index.d.ts
/**
* Constants
*/
/**
* Default API endpoint
*/
export declare const API_URL = "api.ideal-postcodes.co.uk";
/**
* Use TLS by default. Set to `true`
*/
export declare const TLS = true;
/**
* Default API Version number. Defaults to "v1"
*/
export declare const VERSION = "v1";
/**
* Default HTTP timeout in milliseconds. Defaults to 10s
*/
export declare const TIMEOUT = 10000;
export declare const STRICT_AUTHORISATION = false;
export { Client, Config } from "./client";
export { Client, Config, defaults } from "./client";
export { Agent, HttpRequest, HttpResponse } from "./agent";
import * as errors from "./error";
export { errors };
export * as addresses from "./resources/addresses";
export * as autocomplete from "./resources/autocomplete";
export * as keys from "./resources/keys";
export * as postcodes from "./resources/postcodes";
export * as udprn from "./resources/udprn";
export * as umprn from "./resources/umprn";
export * from "./helpers";
export * from "./types";
export * as errors from "./error";

35

esm/index.js
/**
* Constants
*/
/**
* Default API endpoint
*/
export const API_URL = "api.ideal-postcodes.co.uk";
/**
* Use TLS by default. Set to `true`
*/
export const TLS = true;
/**
* Default API Version number. Defaults to "v1"
*/
export const VERSION = "v1";
/**
* Default HTTP timeout in milliseconds. Defaults to 10s
*/
export const TIMEOUT = 10000;
/*
* STRICT_AUTHORISATION forces authorization header usage on
* autocomplete API which increases latency due to overhead
* OPTIONS request
*/
export const STRICT_AUTHORISATION = false;
export { Client } from "./client";
import * as errors from "./error";
export { errors };
export { Client, defaults } from "./client";
export * as addresses from "./resources/addresses";
export * as autocomplete from "./resources/autocomplete";
export * as keys from "./resources/keys";
export * as postcodes from "./resources/postcodes";
export * as udprn from "./resources/udprn";
export * as umprn from "./resources/umprn";
export * from "./helpers";
export * from "./types";
export * as errors from "./error";

6

esm/resources/addresses.d.ts

@@ -44,6 +44,6 @@ import { AddressQueryResponse } from "@ideal-postcodes/api-typings";

}
export interface AddressResource {
list(request: Request): Promise<Response>;
export interface List {
(client: Client, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => AddressResource;
export declare const list: List;
export {};

5

esm/resources/addresses.js
import { listMethod } from "./resource";
const resource = "addresses";
export const create = (client) => {
const list = listMethod({ resource, client });
return { list };
};
export const list = (client, request) => listMethod({ resource, client })(request);

5

esm/resources/autocomplete.d.ts

@@ -43,3 +43,6 @@ import { AddressSuggestionResponse } from "@ideal-postcodes/api-typings";

}
export declare const create: (client: Client) => AutocompleteResource;
export interface List {
(client: Client, request: Request): Promise<Response>;
}
export declare const list: List;
export {};

8

esm/resources/autocomplete.js
import { listMethod } from "./resource";
const resource = "autocomplete/addresses";
export const create = (client) => {
const list = listMethod({
resource,
client,
});
return { list };
};
export const list = (client, request) => listMethod({ resource, client })(request);

11

esm/resources/keys.d.ts

@@ -32,7 +32,10 @@ import { PublicKeyResponse, PrivateKeyResponse, KeyUsageResponse } from "@ideal-postcodes/api-typings";

}
export interface KeyResource {
retrieve(key: string, request: Request): Promise<Response>;
usage(postcode: string, request: UsageRequest): Promise<UsageResponse>;
export interface Retrieve {
(client: Client, apiKey: string, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => KeyResource;
export declare const retrieve: Retrieve;
export interface Usage {
(client: Client, apiKey: string, request: UsageRequest): Promise<UsageResponse>;
}
export declare const usage: Usage;
export {};

21

esm/resources/keys.js
import { retrieveMethod } from "./resource";
const resource = "keys";
export const create = (client) => {
const retrieve = retrieveMethod({
resource,
client,
});
const usage = retrieveMethod({
resource,
client,
action: "usage",
});
return { retrieve, usage };
};
export const retrieve = (client, apiKey, request) => retrieveMethod({
resource,
client,
})(apiKey, request);
export const usage = (client, apiKey, request) => retrieveMethod({
resource,
client,
action: "usage",
})(apiKey, request);

5

esm/resources/postcodes.d.ts

@@ -27,3 +27,6 @@ import { PostcodesResponse } from "@ideal-postcodes/api-typings";

}
export declare const create: (client: Client) => PostcodeResource;
export interface Retrieve {
(client: Client, postcode: string, request: Request): Promise<Response>;
}
export declare const retrieve: Retrieve;
export {};

11

esm/resources/postcodes.js
import { retrieveMethod } from "./resource";
const resource = "postcodes";
export const create = (client) => {
const retrieve = retrieveMethod({
resource,
client,
});
return { retrieve };
};
export const retrieve = (client, postcode, request) => retrieveMethod({
resource,
client,
})(postcode, request);

4

esm/resources/resource.js

@@ -14,3 +14,3 @@ import { toStringMap, toTimeout, toHeader } from "../util";

const { client } = options;
return (id, request) => client.agent
return (id, request) => client.config.agent
.http({

@@ -32,3 +32,3 @@ method: "GET",

const { client, resource } = options;
return (request) => client.agent
return (request) => client.config.agent
.http({

@@ -35,0 +35,0 @@ method: "GET",

6

esm/resources/udprn.d.ts

@@ -23,6 +23,6 @@ import { UdprnResponse } from "@ideal-postcodes/api-typings";

}
export interface UdprnResource {
retrieve(udprn: string, request: Request): Promise<Response>;
export interface Retrieve {
(client: Client, udprn: string, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => UdprnResource;
export declare const retrieve: Retrieve;
export {};

5

esm/resources/udprn.js
import { retrieveMethod } from "./resource";
const resource = "udprn";
export const create = (client) => {
const retrieve = retrieveMethod({ resource, client });
return { retrieve };
};
export const retrieve = (client, udprn, request) => retrieveMethod({ resource, client })(udprn, request);

6

esm/resources/umprn.d.ts

@@ -23,6 +23,6 @@ import { UmprnResponse } from "@ideal-postcodes/api-typings";

}
export interface UmprnResource {
retrieve(umprn: string, request: Request): Promise<Response>;
export interface Retrieve {
(client: Client, umprn: string, request: Request): Promise<Response>;
}
export declare const create: (client: Client) => UmprnResource;
export declare const retrieve: Retrieve;
export {};

5

esm/resources/umprn.js
import { retrieveMethod } from "./resource";
const resource = "umprn";
export const create = (client) => {
const retrieve = retrieveMethod({ resource, client });
return { retrieve };
};
export const retrieve = (client, umprn, request) => retrieveMethod({ resource, client })(umprn, request);

10

esm/util.js

@@ -46,3 +46,3 @@ /**

return timeout;
return client.timeout;
return client.config.timeout;
};

@@ -57,3 +57,3 @@ /**

export const toHeader = ({ header = {} }, client) => {
return { ...client.header, ...toStringMap(header) };
return { ...client.config.header, ...toStringMap(header) };
};

@@ -67,3 +67,3 @@ /**

const credentials = [];
const api_key = options.api_key || client.api_key;
const api_key = options.api_key || client.config.api_key;
credentials.push(["api_key", api_key]);

@@ -110,4 +110,4 @@ const licensee = options.licensee;

let tags;
if (client.tags.length)
tags = client.tags;
if (client.config.tags.length)
tags = client.config.tags;
if (options.tags)

@@ -114,0 +114,0 @@ tags = options.tags;

47

package.json
{
"name": "@ideal-postcodes/core-interface",
"version": "1.9.0",
"version": "2.0.0",
"description": "Interface specification for javascript based API Clients to api.ideal-postcodes.co.uk",

@@ -33,3 +33,3 @@ "author": {

"coverage": "nyc report --reporter=text-lcov > coverage.lcov && codecov",
"docs": "typedoc --mode file --out docs/ --name 'Ideal Postcodes JS Client Interface' --theme minimal --excludePrivate --hideGenerator lib/",
"docs": "typedoc",
"prepublishOnly": "npm run test && npm run build"

@@ -41,2 +41,6 @@ },

],
"browserslist": [
"ie 11",
"last 2 versions"
],
"prettier": {

@@ -95,26 +99,27 @@ "trailingComma": "es5"

"license": "MIT",
"dependencies": {},
"devDependencies": {
"@babel/polyfill": "~7.12.1",
"@cablanchard/eslint-config": "~2.0.1",
"@cablanchard/eslint-config": "~2.1.1",
"@cablanchard/semantic-release": "~1.3.1",
"@cablanchard/tsconfig": "2.0.0",
"@cablanchard/tslint": "0.0.1",
"@ideal-postcodes/api-fixtures": "~1.2.0",
"@ideal-postcodes/api-typings": "~2.0.0",
"@ideal-postcodes/api-fixtures": "~1.3.0",
"@ideal-postcodes/api-typings": "~2.1.0",
"@ideal-postcodes/doc-assets": "~1.0.3",
"@ideal-postcodes/supported-browsers": "~2.5.0",
"@types/chai": "~4.2.0",
"@types/dotenv": "~8.2.0",
"@types/karma": "~5.0.0",
"@types/karma": "~6.3.0",
"@types/mocha": "~8.2.0",
"@types/node": "~14.14.3",
"@types/prettier": "~2.1.0",
"@types/puppeteer": "~5.4.0",
"@types/sinon": "~9.0.1",
"chai": "~4.2.0",
"@types/prettier": "~2.2.0",
"@types/sinon": "~10.0.0",
"@typescript-eslint/eslint-plugin": "~3.0.2",
"chai": "~4.3.0",
"codecov": "~3.8.0",
"core-js": "~3.8.1",
"core-js": "~3.11.0",
"dotenv": "~8.2.0",
"eslint": "~7.17.0",
"karma": "~5.2.1",
"eslint": "~7.25.0",
"eslint-plugin-compat": "~3.9.0",
"karma": "~6.1.1",
"karma-chrome-launcher": "~3.1.0",

@@ -125,11 +130,11 @@ "karma-cli": "~2.0.0",

"karma-sauce-launcher": "~4.3.3",
"karma-typescript": "~5.2.0",
"karma-typescript": "~5.5.1",
"karma-typescript-es6-transform": "~5.2.0",
"mocha": "~8.2.0",
"mocha": "~8.3.0",
"nyc": "~15.1.0",
"prettier": "~2.2.1",
"puppeteer": "~5.4.0",
"puppeteer": "~9.0.0",
"regenerator-runtime": "~0.13.3",
"semantic-release": "~17.3.0",
"sinon": "~9.2.0",
"semantic-release": "~17.4.1",
"sinon": "~10.0.0",
"source-map-support": "~0.5.10",

@@ -139,5 +144,5 @@ "ts-node": "~9.1.1",

"type-zoo": "~3.4.0",
"typedoc": "~0.19.1",
"typescript": "~4.0.3"
"typedoc": "^0.20.35",
"typescript": "~4.2.3"
}
}

219

README.md

@@ -7,3 +7,3 @@ <h1 align="center">

[![CircleCI](https://circleci.com/gh/ideal-postcodes/core-interface/tree/master.svg?style=svg)](https://circleci.com/gh/ideal-postcodes/core-interface/tree/master)
[![CI](https://github.com/ideal-postcodes/core-interface/actions/workflows/ci.yml/badge.svg)](https://github.com/ideal-postcodes/core-interface/actions/workflows/ci.yml)
![Cross Browser Testing](https://github.com/ideal-postcodes/core-interface/workflows/Cross%20Browser%20Testing/badge.svg?branch=saucelabs)

@@ -98,3 +98,3 @@ [![Release](https://github.com/ideal-postcodes/core-interface/workflows/Release/badge.svg)](https://github.com/ideal-postcodes/core-interface/actions)

client.lookupPostcode({ postcode }).then(addresses => {
lookupPostcode({ client, postcode }).then(addresses => {
console.log(addresses);

@@ -109,5 +109,5 @@ {

[`client.lookupPostcode` docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookuppostcode)
`lookupPostcode` [docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookuppostcode)
[`client.lookupPostcode` options](https://core-interface.ideal-postcodes.dev/interfaces/lookuppostcodeoptions.html)
`lookupPostcode` [options](https://core-interface.ideal-postcodes.dev/interfaces/lookuppostcodeoptions.html)

@@ -121,3 +121,3 @@ #### Search for an Address

client.lookupAddress({ query }).then(addresses => {
lookupAddress({ client, query }).then(addresses => {
console.log(addresses);

@@ -132,5 +132,5 @@ {

[`client.lookupAddress` docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookupaddress)
`lookupAddress` [docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookupaddress)
[`client.lookupAddress` options](https://core-interface.ideal-postcodes.dev/interfaces/lookupaddressoptions.html)
`lookupAddress` [options](https://core-interface.ideal-postcodes.dev/interfaces/lookupaddressoptions.html)

@@ -146,3 +146,3 @@ #### Search for an Address by UDPRN

client.lookupUdprn({ udprn }).then(address => {
lookupUdprn({ client, udprn }).then(address => {
console.log(address);

@@ -157,5 +157,5 @@ {

[`client.lookupUdprn` docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookupudprn)
`lookupUdprn` [docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookupudprn)
[`client.lookupUdprn` options](https://core-interface.ideal-postcodes.dev/interfaces/lookupudprnoptions.html)
`lookupUdprn` [options](https://core-interface.ideal-postcodes.dev/interfaces/lookupudprnoptions.html)

@@ -171,3 +171,3 @@ #### Search for an Address by UMPRN

client.lookupUmprn({ umprn }).then(address => {
lookupUmprn({ client, umprn }).then(address => {
console.log(address);

@@ -182,5 +182,5 @@ {

[`client.lookupUmprn` docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookupumprn)
`lookupUmprn` [docs](https://core-interface.ideal-postcodes.dev/classes/client.html#lookupumprn)
[`client.lookupUmprn` options](https://core-interface.ideal-postcodes.dev/interfaces/lookupumprnoptions.html)
`lookupUmprn` [options](https://core-interface.ideal-postcodes.dev/interfaces/lookupumprnoptions.html)

@@ -192,3 +192,3 @@ #### Check Key Usability

```javascript
client.checkKeyUsability({}).then(key => {
checkKeyUsability({ client }).then((key) => {
console.log(key.available); // => true

@@ -198,5 +198,5 @@ });

[`client.checkKeyUsability` docs](https://core-interface.ideal-postcodes.dev/classes/client.html#checkkeyusability)
`checkKeyUsability` [docs](https://core-interface.ideal-postcodes.dev/classes/client.html#checkkeyusability)
[`client.checkKeyUsability` options](https://core-interface.ideal-postcodes.dev/interfaces/checkkeyusabilityoptions.html)
`checkKeyUsability` [options](https://core-interface.ideal-postcodes.dev/interfaces/checkkeyusabilityoptions.html)

@@ -207,3 +207,3 @@ ---

Resources defined in [the API documentation](https://ideal-postcodes.co.uk/documentation) are exposed on the client. Each resource exposes a method (`#retrieve`, `#list`, etc) which maps to a resource action.
Resources defined in [the API documentation](https://ideal-postcodes.co.uk/documentation) are exported by the library. Each resource exposes a method (`#retrieve`, `#list`, etc) which maps to a resource action.

@@ -221,3 +221,3 @@ These methods expose a low level interface to execute HTTP requests and observe HTTP responses. They are ideal if you have a more complex query or usecase where low level access would be useful.

```javascript
client.resourceName.retrieve("id", {
resourceName.retrieve("id", {
query: {

@@ -240,6 +240,6 @@ api_key: "foo",

```javascript
client.resourceName.list({
resourceName.list({
query: {
api_key: "foo",
query: "10 downing street"
query: "10 downing street",
},

@@ -262,5 +262,5 @@ header: {

```javascript
client.keys.usage(api_key, {
keys.usage(api_key, {
query: {
tags: "checkout,production"
tags: "checkout,production",
},

@@ -292,9 +292,13 @@ header: {

```javascript
client.postcodes.retrieve("SW1A2AA", {
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const addresses = response.body.result;
}).catch(error => logger(error));
import { postcodes } from "@ideal-postcodes/core-browser";
postcodes
.retrieve("SW1A2AA", {
header: {
Authorization: 'IDEALPOSTCODES api_key="iddqd"',
},
})
.then((response) => {
const addresses = response.body.result;
})
.catch((error) => logger(error));
```

@@ -311,12 +315,17 @@

```javascript
client.addresses.list({
query: {
query: "10 Downing street",
},
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const addresses = response.body.result.hits;
}).catch(error => logger(error));
import { addresses } from "@ideal-postcodes/core-browser";
addresses
.list({
query: {
query: "10 Downing street",
},
header: {
Authorization: 'IDEALPOSTCODES api_key="iddqd"',
},
})
.then((response) => {
const addresses = response.body.result.hits;
})
.catch((error) => logger(error));
```

@@ -333,12 +342,17 @@

```javascript
client.autocomplete.list({
query: {
query: "10 Downing stre",
},
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const suggestions = response.body.result.hits;
}).catch(error => logger(error));
import { autocomplete } from "@ideal-postcodes/core-browser";
autocomplete
.list({
query: {
query: "10 Downing stre",
},
header: {
Authorization: 'IDEALPOSTCODES api_key="iddqd"',
},
})
.then((response) => {
const suggestions = response.body.result.hits;
})
.catch((error) => logger(error));
```

@@ -355,9 +369,14 @@

```javascript
client.udprn.retrieve("12345678", {
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const address = response.body.result;
}).catch(error => logger(error));
import { udprn } from "@ideal-postcodes/core-browser";
udprn
.retrieve("12345678", {
header: {
Authorization: 'IDEALPOSTCODES api_key="iddqd"',
},
})
.then((response) => {
const address = response.body.result;
})
.catch((error) => logger(error));
```

@@ -374,9 +393,14 @@

```javascript
client.umprn.retrieve("87654321", {
header: {
"Authorization": 'IDEALPOSTCODES api_key="iddqd"',
},
}).then(response => {
const address = response.body.result;
}).catch(error => logger(error));
import { umprn } from "@ideal-postcodes/core-browser";
umprn
.retrieve("87654321", {
header: {
Authorization: 'IDEALPOSTCODES api_key="iddqd"',
},
})
.then((response) => {
const address = response.body.result;
})
.catch((error) => logger(error));
```

@@ -393,6 +417,10 @@

```javascript
client.keys.retrieve("iddqd", {})
.then(response => {
import { keys } from "@ideal-postcodes/core-browser";
keys
.retrieve("iddqd", {})
.then((response) => {
const { available } = response.body.result;
}).catch(error => logger(error));
})
.catch((error) => logger(error));
```

@@ -405,9 +433,14 @@

```javascript
client.keys.retrieve("iddqd", {
header: {
"Authorization": 'IDEALPOSTCODES user_token="secret-token"',
},
}).then(response => {
const key = response.body.result;
}).catch(error => logger(error));
import { keys } from "@ideal-postcodes/core-browser";
keys
.retrieve("iddqd", {
header: {
Authorization: 'IDEALPOSTCODES user_token="secret-token"',
},
})
.then((response) => {
const key = response.body.result;
})
.catch((error) => logger(error));
```

@@ -420,9 +453,14 @@

```javascript
client.keys.usage("iddqd", {
header: {
"Authorization": 'IDEALPOSTCODES user_token="secret-token"',
},
}).then(response => {
const key = response.body.result;
}).catch(error => logger(error));
import { keys } from "@ideal-postcodes/core-browser";
keys
.usage("iddqd", {
header: {
Authorization: 'IDEALPOSTCODES user_token="secret-token"',
},
})
.then((response) => {
const key = response.body.result;
})
.catch((error) => logger(error));
```

@@ -440,3 +478,3 @@

`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.
This library 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.

@@ -462,6 +500,9 @@ For example:

```javascript
const { IdpcRequestFailedError } = Client.errors;
import {
IdpcRequestFailedError,
lookupPostcode,
} from "@ideal-postcodes/core-browser";
try {
const addresses = client.lookupPostcode({ postcode: "SW1A2AA" });
const addresses = lookupPostcode({ client, postcode: "SW1A2AA" });
} catch (error) {

@@ -475,3 +516,3 @@ if (error instanceof IdpcRequestFailedError) {

A sketch of the error prototype chain can be found [here](#error-prototype-chain)
You may view a [sketch of the error prototype chain](#error-prototype-chain).

@@ -487,3 +528,3 @@ ---

#### Usage
#### Error Usage

@@ -495,3 +536,3 @@ Aside from inspecting the HTTP request status code and/or JSON body response codes, you may also test for specific error instances.

```javascript
import { errors } from "@ideal-postcodes/core-interface";
import { errors } from "@ideal-postcodes/core-browser";
const { IdpcPostcodeNotFoundError } = errors;

@@ -507,5 +548,5 @@

case error instanceof IdpcPostcodeNotFoundError:
// You got yourself an invalid API Key
// You got yourself an invalid API Key
default:
// Default error handling path
// Default error handling path
}

@@ -553,3 +594,3 @@ ```

```javascript
import { errors } from "@ideal-postcodes/core-interface";
import { errors } from "@ideal-postcodes/core-browser";
const { parse, IdpcPostcodeNotFoundError } = errors;

@@ -556,0 +597,0 @@

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc