{"id":24678321,"url":"https://github.com/firstclasspostcodes/firstclasspostcodes-js","last_synced_at":"2025-10-10T14:35:15.477Z","repository":{"id":54416700,"uuid":"228634267","full_name":"firstclasspostcodes/firstclasspostcodes-js","owner":"firstclasspostcodes","description":"Browser and Node.JS library for the Firstclasspostcodes API. Install it or require it directly in the browser.","archived":false,"fork":false,"pushed_at":"2021-02-19T07:39:14.000Z","size":3326,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T22:56:25.465Z","etag":null,"topics":["api","firstclasspostcodes"],"latest_commit_sha":null,"homepage":"https://firstclasspostcodes.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firstclasspostcodes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-17T14:28:15.000Z","updated_at":"2020-11-13T08:21:31.000Z","dependencies_parsed_at":"2022-08-13T15:00:49.069Z","dependency_job_id":null,"html_url":"https://github.com/firstclasspostcodes/firstclasspostcodes-js","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstclasspostcodes%2Ffirstclasspostcodes-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firstclasspostcodes","download_url":"https://codeload.github.com/firstclasspostcodes/firstclasspostcodes-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244845429,"owners_count":20519959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","firstclasspostcodes"],"created_at":"2025-01-26T13:16:39.927Z","updated_at":"2025-10-10T14:35:10.444Z","avatar_url":"https://github.com/firstclasspostcodes.png","language":"JavaScript","readme":"[//]: # \"NOTE: The URL for the JS library is automatically updated by semantic-release.\"\n\n# Firstclasspostcodes\n![Build, test and release](https://github.com/firstclasspostcodes/firstclasspostcodes-js/workflows/Build,%20test%20and%20release/badge.svg)\n\nThe Firstclasspostcodes Javascript library is compatible with both Node.JS and Browsers. \n\nThe library will work in all modern browsers and IE9+.\n\nAn identical API is provided for both the client and server side.\n\n## Documentation\nSee [@firstclasspostcodes/js API docs](https://docs.firstclasspostcodes.com/js/getting-started) for detailed usage and examples.\n\n## Installation\nInstall the package with:\n\n```\nnpm install @firstclasspostcodes/js\n```\n\nor directly in HTML with:\n\n```html\n\u003cscript src=\"https://js.firstclasspostcodes.com/v1.6.2.js\"\u003e\u003c/script\u003e\n```\n\n**Note on older browsers:** We recommend using a polyfill service, the following example covers all of the required language features:\n\n```html\n\u003cscript src=\"https://polyfill.io/v3/polyfill.min.js?features=Promise%2Cfetch%2CObject.assign\"\u003e\u003c/script\u003e\n```\n\n### Security\nWhere the libary is loaded on pages including sensitive information, we recommend using the [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) security feature. \n\nEvery version of the library is accompanied by an SRI hash file, the hash can be accessed directly using:\n\n```sh\n$ curl https://js.firstclasspostcodes.com/v1.6.2.sri.txt # =\u003e \"sha256-45tfd... sha384-43567ytr...\"\n```\n\nYou can then update the above `\u003cscript\u003e` tag, adding the integrity attribute:\n\n```html\n\u003cscript src=\"https://js.firstclasspostcodes.com/v1.6.2.js\"\n        integrity=\"sha256-45tfd... sha384-43567ytr...\"\n        crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n```\n\n## Usage\nYou need to configure the library to use your API Key which is available on your [dashboard](https://dashboard.firstclasspostcodes.com/key). Require the library using the key:\n\n```js\nconst client = require('@firstclasspostcodes/js')('fg3rfgy3345tgfAt3r');\n\nconst postcodeData = await client.getPostcode('sw13 8gh');\n```\n\nUsing ES modules looks a little different:\n\n```js\nimport Firstclasspostcodes from '@firstclasspostcodes/js';\n\nconst client = Firstclasspostcodes('fg3rfgy3345tgfAt3r');\n\n// ...\n```\n\n## Configuration\nThe library can be initialized with several options:\n\n```js\nconst client = Firstclasspostcodes('fg3r...', {\n  endpoint: 'https://api.firstclasspostcodes.com/data',\n  content: 'json',\n});\n```\n\n| Property | Default | Description |\n|:-----|:-----|:-----|\n| `endpoint` | `https://api.firstclasspostcodes.com/data` | The endpoint to be used. This can be overridden to use a private endpoint, or for testing purposes. |\n| `content` | `'json'` | The content key controls the type of response being received. `geo+json` can be used to receives responses in [GeoJSON](https://geojson.org/).\n\n## Events\nEvent handlers can be attached to the library using the Node.JS [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) pattern. \n\nThe library does not currently support wildcards or regular expressions.\n\n```js\nconst client = Firstclasspostcodes('....');\n\nconst handler = (requestObj) =\u003e {\n  console.log(requestObj);\n};\n\nclient.on('request', handler);\n\nclient.once('response', (responseObj) =\u003e {\n  sendSignal(responseObj);\n});\n\nclient.off('request', handler);\n```\n\n| Event name | Description |\n|:-----|:-----|\n| `request` | Triggered before a request is sent. The request object to be sent is passed to the event handler. |\n| `response` | Triggered with the parsed JSON response body upon a successful reques. |\n| `error` | Triggered with a client error when the request fails. |\n| `operation:{name}` | Triggered by an operation with the parameter object. |\n\n**Note:** `{name}` is replaced with the operation name of the method, as defined inside the OpenAPI specification.\n\n## Debug\nOnce the library has been initialized, various debug statements are logged as requests are sent and responses received.\n\nEnabling debug mode:\n\n```js\nconst client = Firstclasspostcodes('....');\n\nclient.debugging = true;\n```\n\n## Integration / Testing\nWe provide a mock service of our API as a docker container [available here](https://github.com/firstclasspostcodes/firstclasspostcodes-mock). Once the container is running, the library can be easily configured to use it:\n\n```js\nconst Firstclasspostcodes = require('@firstclasspostcodes/js')\n\nconst MOCK_API_URL = 'http://localhost:3000';\n\n// The mock API key is always 111111111111 (\"12x1\")\nconst MOCK_API_KEY = '111111111111'\n\nconst client = Firstclasspostcodes(MOCK_API_KEY, {\n  endpoint: MOCK_API_URL,\n});\n```\n\n## Development\nRun all linting and tests:\n\n```\n$ npm ci\n$ npm run lint\n$ npm test\n```\n\nWe use [Cypress](https://www.cypress.io/) to ensure that our library is working correctly inside the browser, this can be executed locally using:\n\n```\n$ npm run cypress\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstclasspostcodes%2Ffirstclasspostcodes-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirstclasspostcodes%2Ffirstclasspostcodes-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstclasspostcodes%2Ffirstclasspostcodes-js/lists"}