@mountainpass/addressr-core 0.1.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# @mountainpass/addressr-core
|
|
2
|
+
|
|
3
|
+
Framework-agnostic HATEOAS client for the [Addressr](https://addressr.io) Australian address API. Use this to build your own address search UI in any framework, or pair it with a framework package:
|
|
4
|
+
|
|
5
|
+
- React: [`@mountainpass/addressr-react`](../react)
|
|
6
|
+
- Svelte: [`@mountainpass/addressr-svelte`](../svelte)
|
|
7
|
+
- Vue: [`@mountainpass/addressr-vue`](../vue)
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @mountainpass/addressr-core
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { createAddressrClient, parseHighlight } from '@mountainpass/addressr-core';
|
|
19
|
+
|
|
20
|
+
const client = createAddressrClient({
|
|
21
|
+
apiUrl: 'https://api.addressr.io/',
|
|
22
|
+
// Or use RapidAPI:
|
|
23
|
+
// apiKey: 'your-rapidapi-key',
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
// Search
|
|
27
|
+
const page = await client.searchAddresses('1 george st');
|
|
28
|
+
console.log(page.results); // AddressSearchResult[]
|
|
29
|
+
console.log(page.nextLink); // Link | null
|
|
30
|
+
|
|
31
|
+
// Paginate
|
|
32
|
+
if (page.nextLink) {
|
|
33
|
+
const page2 = await client.fetchNextPage(page.nextLink);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// Get full detail
|
|
37
|
+
const detail = await client.getAddressDetail('GANSW123');
|
|
38
|
+
console.log(detail.structured); // { street, locality, state, postcode, ... }
|
|
39
|
+
console.log(detail.geocoding); // { latitude, longitude, ... }
|
|
40
|
+
|
|
41
|
+
// Safe highlight rendering
|
|
42
|
+
const segments = parseHighlight('<em>1</em> <em>GEORGE</em> ST');
|
|
43
|
+
// [{ text: '1', highlighted: true }, { text: ' ', highlighted: false }, ...]
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## API
|
|
47
|
+
|
|
48
|
+
### `createAddressrClient(options)`
|
|
49
|
+
|
|
50
|
+
| Option | Type | Default | Description |
|
|
51
|
+
|--------|------|---------|-------------|
|
|
52
|
+
| `apiKey` | `string` | -- | RapidAPI key. Omit for direct API access. |
|
|
53
|
+
| `apiUrl` | `string` | `"https://addressr.p.rapidapi.com/"` | API root URL |
|
|
54
|
+
| `apiHost` | `string` | `"addressr.p.rapidapi.com"` | RapidAPI host header |
|
|
55
|
+
| `fetchImpl` | `typeof fetch` | `globalThis.fetch` | Custom fetch (for testing) |
|
|
56
|
+
|
|
57
|
+
Returns an `AddressrClient` with:
|
|
58
|
+
|
|
59
|
+
| Method | Returns | Description |
|
|
60
|
+
|--------|---------|-------------|
|
|
61
|
+
| `searchAddresses(query, signal?)` | `Promise<SearchPage>` | Search addresses. Returns results + HATEOAS next link. |
|
|
62
|
+
| `fetchNextPage(nextLink, signal?)` | `Promise<SearchPage>` | Follow a next-page link relation. |
|
|
63
|
+
| `getAddressDetail(pid, signal?, searchPage?, index?)` | `Promise<AddressDetail>` | Get full address detail. Follows canonical link when search context provided. |
|
|
64
|
+
|
|
65
|
+
### `SearchPage`
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
{
|
|
69
|
+
results: AddressSearchResult[]; // Array of search results
|
|
70
|
+
nextLink: Link | null; // HATEOAS link to next page, or null
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### `parseHighlight(html)`
|
|
75
|
+
|
|
76
|
+
Safely parses Elasticsearch `<em>` highlight tags into segments. No innerHTML, no XSS.
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
parseHighlight(html: string): HighlightSegment[]
|
|
80
|
+
// HighlightSegment = { text: string; highlighted: boolean }
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Architecture
|
|
84
|
+
|
|
85
|
+
- **HATEOAS** -- API root discovery via RFC 8288 Link headers, no hardcoded paths
|
|
86
|
+
- **Pagination** -- follows `next` link relations, accumulates results across pages
|
|
87
|
+
- **Canonical links** -- `getAddressDetail` follows canonical link from search results when available, falls back to URL construction
|
|
88
|
+
- **Root caching** -- API root fetched once per client instance
|
|
89
|
+
- **Abort support** -- all methods accept `AbortSignal` for cancellation
|
|
90
|
+
|
|
91
|
+
## License
|
|
92
|
+
|
|
93
|
+
Apache-2.0
|