hg-map-sdk 1.0.0 → 1.1.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 +30 -2
- package/index.d.ts +17 -2
- package/package.json +1 -1
- package/src/client.js +7 -3
- package/src/errors.js +2 -1
package/README.md
CHANGED
|
@@ -14,6 +14,22 @@ Node 18+, no dependencies, TypeScript types included.
|
|
|
14
14
|
|
|
15
15
|
## Setup
|
|
16
16
|
|
|
17
|
+
### With a Hoogaaa Cloud key (recommended)
|
|
18
|
+
|
|
19
|
+
1. In the Hoogaaa Cloud console, open your project, switch **Maps** on and create a key that may use Maps
|
|
20
|
+
(Test mode: `hk_test_…`, Live mode: `hk_live_…`).
|
|
21
|
+
2. Put the gateway URL and the key in your service's env, under any names you like:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
MAP_SERVICE_URL=https://apidev.hoogaaa.com/api/v1/maps # hk_test_ keys; live keys: https://api.hoogaaa.com/api/v1/maps
|
|
25
|
+
MAP_SERVICE_API_KEY=hk_test_…
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
3. Create the client as below. A key starting with `hk_` is sent as `X-Hoogaaa-Api-Key`: the gateway checks it,
|
|
29
|
+
counts the call in the console's Usage and strips it before map-service. Nothing else changes.
|
|
30
|
+
|
|
31
|
+
### With a map-service key (inside the cluster)
|
|
32
|
+
|
|
17
33
|
1. Give your service its own key on map-service:
|
|
18
34
|
|
|
19
35
|
```bash
|
|
@@ -28,7 +44,7 @@ Node 18+, no dependencies, TypeScript types included.
|
|
|
28
44
|
MAP_SERVICE_API_KEY=mk_…
|
|
29
45
|
```
|
|
30
46
|
|
|
31
|
-
3. Create one client per process and reuse it:
|
|
47
|
+
3. Create one client per process and reuse it (same code for both kinds of key):
|
|
32
48
|
|
|
33
49
|
```js
|
|
34
50
|
const { createMapClient, MapServiceError } = require("hg-map-sdk");
|
|
@@ -83,7 +99,7 @@ const mostlyInside = pincodes.filter((p) => p.share_inside >= 0.5).map((p) => p.
|
|
|
83
99
|
## Errors
|
|
84
100
|
|
|
85
101
|
Every failure is a `MapServiceError` with:
|
|
86
|
-
- `code`: map-service's own code, or `NETWORK_ERROR` / `TIMEOUT`
|
|
102
|
+
- `code`: map-service's own code, the gateway's code (with a `hk_` key), or `NETWORK_ERROR` / `TIMEOUT`
|
|
87
103
|
- `status`: the HTTP status, or `null` if map-service wasn't reached
|
|
88
104
|
- `details`
|
|
89
105
|
- `retryAfterS`
|
|
@@ -110,6 +126,18 @@ try {
|
|
|
110
126
|
| `PROVIDER_UNAVAILABLE` / `GEOCODING_UNAVAILABLE` (503) | Engine down / no geocoder configured |
|
|
111
127
|
| `NETWORK_ERROR`, `TIMEOUT` | map-service not reachable or too slow |
|
|
112
128
|
|
|
129
|
+
With a Hoogaaa Cloud key the gateway may answer first:
|
|
130
|
+
|
|
131
|
+
| `code` | Meaning |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `API_KEY_MISSING` / `API_KEY_INVALID` (401) | No key, or unknown, switched off, expired or deleted |
|
|
134
|
+
| `KEY_WRONG_ENV` (403) | A live key on apidev or a test key on api |
|
|
135
|
+
| `API_NOT_ENABLED` / `API_NOT_ALLOWED_FOR_KEY` (403) | Maps is off for the project, or this key may not use it |
|
|
136
|
+
| `KEY_RESTRICTED` (403) | The key's IP / Android restriction does not match |
|
|
137
|
+
| `PROJECT_DISABLED` (403) | The project is switched off |
|
|
138
|
+
| `RATE_LIMITED` (429) | The project's per-minute or daily Maps limit (with `Retry-After`) |
|
|
139
|
+
| `SERVICE_DISABLED` (503) | Maps is switched off in Hoogaaa Cloud |
|
|
140
|
+
|
|
113
141
|
**Retries:** network errors, timeouts and 5xx are retried `retries` times (default 1), with
|
|
114
142
|
backoff. This is safe because every map-service endpoint only reads. A `429` is retried only when
|
|
115
143
|
`Retry-After` is at most `maxRetryAfterS` (2 s); otherwise it is thrown at once. 4xx errors are
|
package/index.d.ts
CHANGED
|
@@ -7,9 +7,15 @@ export interface LatLng {
|
|
|
7
7
|
}
|
|
8
8
|
|
|
9
9
|
export interface MapClientOptions {
|
|
10
|
-
/**
|
|
10
|
+
/**
|
|
11
|
+
* Hoogaaa Cloud gateway: "https://apidev.hoogaaa.com/api/v1/maps" (hk_test_ keys) or
|
|
12
|
+
* "https://api.hoogaaa.com/api/v1/maps" (hk_live_ keys). Inside the cluster: "http://map-service:4120/api/v1/maps".
|
|
13
|
+
*/
|
|
11
14
|
baseUrl: string;
|
|
12
|
-
/**
|
|
15
|
+
/**
|
|
16
|
+
* A Hoogaaa Cloud key from the console (hk_test_… / hk_live_…, sent as X-Hoogaaa-Api-Key), or this service's own
|
|
17
|
+
* map-service key (mk_…, sent as X-Map-Service-Api-Key).
|
|
18
|
+
*/
|
|
13
19
|
apiKey: string;
|
|
14
20
|
/** Per attempt. Default 8000. */
|
|
15
21
|
timeoutMs?: number;
|
|
@@ -29,6 +35,15 @@ export type ErrorCode =
|
|
|
29
35
|
| "TIMEOUT"
|
|
30
36
|
| "INVALID_API_KEY"
|
|
31
37
|
| "RATE_LIMITED"
|
|
38
|
+
// Hoogaaa Cloud gateway (hk_ keys)
|
|
39
|
+
| "API_KEY_MISSING"
|
|
40
|
+
| "API_KEY_INVALID"
|
|
41
|
+
| "KEY_WRONG_ENV"
|
|
42
|
+
| "KEY_RESTRICTED"
|
|
43
|
+
| "API_NOT_ENABLED"
|
|
44
|
+
| "API_NOT_ALLOWED_FOR_KEY"
|
|
45
|
+
| "PROJECT_DISABLED"
|
|
46
|
+
| "SERVICE_DISABLED"
|
|
32
47
|
| "INVALID_POINT"
|
|
33
48
|
| "INVALID_POINTS"
|
|
34
49
|
| "INVALID_STOPS"
|
package/package.json
CHANGED
package/src/client.js
CHANGED
|
@@ -17,6 +17,7 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
|
17
17
|
*/
|
|
18
18
|
class HttpClient {
|
|
19
19
|
/**
|
|
20
|
+
* apiKey: a Hoogaaa Cloud key (hk_…, through the gateway) or this service's map-service key (mk_…).
|
|
20
21
|
* @param {{ baseUrl: string, apiKey: string, timeoutMs?: number, retries?: number,
|
|
21
22
|
* retryDelayMs?: number, maxRetryAfterS?: number, fetch?: typeof fetch, userAgent?: string }} options
|
|
22
23
|
*/
|
|
@@ -25,10 +26,13 @@ class HttpClient {
|
|
|
25
26
|
throw new TypeError("hg-map-sdk: baseUrl is required, e.g. http://map-service:4120/api/v1/maps");
|
|
26
27
|
}
|
|
27
28
|
if (typeof options.apiKey !== "string" || !options.apiKey) {
|
|
28
|
-
throw new TypeError("hg-map-sdk: apiKey is required (
|
|
29
|
+
throw new TypeError("hg-map-sdk: apiKey is required (a Hoogaaa Cloud key hk_test_… / hk_live_…, or a map-service key mk_…)");
|
|
29
30
|
}
|
|
30
31
|
this.baseUrl = options.baseUrl.replace(/\/+$/, "");
|
|
31
|
-
this.apiKey = options.apiKey;
|
|
32
|
+
this.apiKey = options.apiKey.trim();
|
|
33
|
+
// A Hoogaaa Cloud key (from the console) goes to the gateway in its own header; the gateway checks it, counts the
|
|
34
|
+
// call in the console's Usage and strips it before map-service. A map-service key (mk_…) goes as before.
|
|
35
|
+
this.keyHeader = this.apiKey.startsWith("hk_") ? "X-Hoogaaa-Api-Key" : "X-Map-Service-Api-Key";
|
|
32
36
|
this.timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs;
|
|
33
37
|
this.retries = Math.max(0, options.retries ?? DEFAULTS.retries);
|
|
34
38
|
this.retryDelayMs = options.retryDelayMs ?? DEFAULTS.retryDelayMs;
|
|
@@ -49,7 +53,7 @@ class HttpClient {
|
|
|
49
53
|
res = await this.fetch(`${this.baseUrl}${path}`, {
|
|
50
54
|
method,
|
|
51
55
|
headers: {
|
|
52
|
-
|
|
56
|
+
[this.keyHeader]: this.apiKey,
|
|
53
57
|
"User-Agent": this.userAgent,
|
|
54
58
|
...(body !== undefined ? { "Content-Type": "application/json" } : {}),
|
|
55
59
|
},
|
package/src/errors.js
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Every failure from map-service (or reaching it) is a MapServiceError, so callers branch on
|
|
3
3
|
* `code` — the same codes map-service documents (NO_ROUTE, POINT_OUTSIDE_COVERAGE,
|
|
4
|
-
* INVALID_API_KEY, RATE_LIMITED, PINCODE_NOT_FOUND …)
|
|
4
|
+
* INVALID_API_KEY, RATE_LIMITED, PINCODE_NOT_FOUND …), the Hoogaaa Cloud gateway's codes when called with a
|
|
5
|
+
* hk_ key (API_KEY_INVALID, KEY_WRONG_ENV, API_NOT_ENABLED, RATE_LIMITED …) plus two of the SDK's own:
|
|
5
6
|
* NETWORK_ERROR — map-service not reachable
|
|
6
7
|
* TIMEOUT — no answer within timeoutMs
|
|
7
8
|
*/
|