hg-map-sdk 1.0.0 → 1.2.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 +40 -3
- package/index.d.ts +19 -2
- package/package.json +4 -4
- package/src/client.js +19 -3
- package/src/errors.js +4 -1
package/README.md
CHANGED
|
@@ -14,10 +14,29 @@ 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) — stops on 30 Nov 2026
|
|
32
|
+
|
|
33
|
+
> **`mk_` keys stop working on 30 Nov 2026 00:00 IST.** Move to a Hoogaaa Cloud key (above) before then. From
|
|
34
|
+
> 1.2.0 the SDK prints a `DeprecationWarning` (`HG_MAP_SDK_OLD_KEY`) once per process when it gets an `mk_` key.
|
|
35
|
+
|
|
17
36
|
1. Give your service its own key on map-service:
|
|
18
37
|
|
|
19
38
|
```bash
|
|
20
|
-
cd
|
|
39
|
+
cd map/map-osrm/map-service
|
|
21
40
|
npm run clients -- create user-backend # prints the key once
|
|
22
41
|
```
|
|
23
42
|
|
|
@@ -28,7 +47,7 @@ Node 18+, no dependencies, TypeScript types included.
|
|
|
28
47
|
MAP_SERVICE_API_KEY=mk_…
|
|
29
48
|
```
|
|
30
49
|
|
|
31
|
-
3. Create one client per process and reuse it:
|
|
50
|
+
3. Create one client per process and reuse it (same code for both kinds of key):
|
|
32
51
|
|
|
33
52
|
```js
|
|
34
53
|
const { createMapClient, MapServiceError } = require("hg-map-sdk");
|
|
@@ -83,7 +102,7 @@ const mostlyInside = pincodes.filter((p) => p.share_inside >= 0.5).map((p) => p.
|
|
|
83
102
|
## Errors
|
|
84
103
|
|
|
85
104
|
Every failure is a `MapServiceError` with:
|
|
86
|
-
- `code`: map-service's own code, or `NETWORK_ERROR` / `TIMEOUT`
|
|
105
|
+
- `code`: map-service's own code, the gateway's code (with a `hk_` key), or `NETWORK_ERROR` / `TIMEOUT`
|
|
87
106
|
- `status`: the HTTP status, or `null` if map-service wasn't reached
|
|
88
107
|
- `details`
|
|
89
108
|
- `retryAfterS`
|
|
@@ -109,6 +128,24 @@ try {
|
|
|
109
128
|
| `INVALID_*` (400) | Bad input; `details` says which field |
|
|
110
129
|
| `PROVIDER_UNAVAILABLE` / `GEOCODING_UNAVAILABLE` (503) | Engine down / no geocoder configured |
|
|
111
130
|
| `NETWORK_ERROR`, `TIMEOUT` | map-service not reachable or too slow |
|
|
131
|
+
| `PAID_PROVIDERS_OFF` (503) | A **test** key, and this server has only paid providers (Ola, Mappls, Google) for that call. Not retried |
|
|
132
|
+
|
|
133
|
+
**Test keys use only free providers.** With a `hk_test_` key map-service answers from its own engines (OSRM,
|
|
134
|
+
Photon, Nominatim) and never from Ola, Mappls or Google, so testing never costs money. Live keys use the full
|
|
135
|
+
provider list. The Maps admin can let a project's next few test calls (default 10) use the paid ones too, to check
|
|
136
|
+
them; the response header `X-Map-Paid-Providers` says `off`, `on` or `test 3/10`.
|
|
137
|
+
|
|
138
|
+
With a Hoogaaa Cloud key the gateway may answer first:
|
|
139
|
+
|
|
140
|
+
| `code` | Meaning |
|
|
141
|
+
|---|---|
|
|
142
|
+
| `API_KEY_MISSING` / `API_KEY_INVALID` (401) | No key, or unknown, switched off, expired or deleted |
|
|
143
|
+
| `KEY_WRONG_ENV` (403) | A live key on apidev or a test key on api |
|
|
144
|
+
| `API_NOT_ENABLED` / `API_NOT_ALLOWED_FOR_KEY` (403) | Maps is off for the project, or this key may not use it |
|
|
145
|
+
| `KEY_RESTRICTED` (403) | The key's IP / Android restriction does not match |
|
|
146
|
+
| `PROJECT_DISABLED` (403) | The project is switched off |
|
|
147
|
+
| `RATE_LIMITED` (429) | The project's per-minute or daily Maps limit (with `Retry-After`) |
|
|
148
|
+
| `SERVICE_DISABLED` (503) | Maps is switched off in Hoogaaa Cloud |
|
|
112
149
|
|
|
113
150
|
**Retries:** network errors, timeouts and 5xx are retried `retries` times (default 1), with
|
|
114
151
|
backoff. This is safe because every map-service endpoint only reads. A `429` is retried only when
|
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"
|
|
@@ -46,6 +61,8 @@ export type ErrorCode =
|
|
|
46
61
|
| "PINCODE_NOT_FOUND"
|
|
47
62
|
| "PINCODES_UNAVAILABLE"
|
|
48
63
|
| "GEOCODING_UNAVAILABLE"
|
|
64
|
+
// A Hoogaaa test key on a server whose providers are all paid ones (test keys use only free providers)
|
|
65
|
+
| "PAID_PROVIDERS_OFF"
|
|
49
66
|
| "PROVIDER_UNAVAILABLE"
|
|
50
67
|
| "PROVIDER_REJECTED"
|
|
51
68
|
| (string & {});
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hg-map-sdk",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Client for
|
|
3
|
+
"version": "1.2.0",
|
|
4
|
+
"description": "Client for Hoogaaa Maps (map-service): routing, ETA, trip optimization, geocoding and India PIN codes \u2014 provider-independent",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"types": "index.d.ts",
|
|
7
7
|
"files": [
|
|
@@ -18,10 +18,10 @@
|
|
|
18
18
|
},
|
|
19
19
|
"repository": {
|
|
20
20
|
"type": "git",
|
|
21
|
-
"url": "git+https://github.com/satyamsonker1010/
|
|
21
|
+
"url": "git+https://github.com/satyamsonker1010/hoogaaa-map-service.git",
|
|
22
22
|
"directory": "sdk"
|
|
23
23
|
},
|
|
24
|
-
"homepage": "https://github.com/satyamsonker1010/
|
|
24
|
+
"homepage": "https://github.com/satyamsonker1010/hoogaaa-map-service/tree/development/sdk#readme",
|
|
25
25
|
"keywords": [
|
|
26
26
|
"maps",
|
|
27
27
|
"routing",
|
package/src/client.js
CHANGED
|
@@ -11,12 +11,24 @@ const DEFAULTS = {
|
|
|
11
11
|
|
|
12
12
|
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
13
13
|
|
|
14
|
+
// map-service keys (mk_…) stop on 30 Nov 2026 00:00 IST (owner, 19 Nov 2026). Said once per process.
|
|
15
|
+
let warnedOldKey = false;
|
|
16
|
+
const warnOldKey = () => {
|
|
17
|
+
if (warnedOldKey) return;
|
|
18
|
+
warnedOldKey = true;
|
|
19
|
+
process.emitWarning(
|
|
20
|
+
"map-service keys (mk_…) stop working on 30 Nov 2026 00:00 IST. Create a Hoogaaa Cloud key (hk_test_… / hk_live_…) at https://console.hoogaaa.com and call the gateway (https://apidev.hoogaaa.com/api/v1/maps or https://api.hoogaaa.com/api/v1/maps).",
|
|
21
|
+
{ type: "DeprecationWarning", code: "HG_MAP_SDK_OLD_KEY" },
|
|
22
|
+
);
|
|
23
|
+
};
|
|
24
|
+
|
|
14
25
|
/**
|
|
15
26
|
* Low-level HTTP: base URL + key, timeout, retries, and turning map-service's
|
|
16
27
|
* `{ success, message, data, code, errors }` envelope into data or a MapServiceError.
|
|
17
28
|
*/
|
|
18
29
|
class HttpClient {
|
|
19
30
|
/**
|
|
31
|
+
* apiKey: a Hoogaaa Cloud key (hk_…, through the gateway) or this service's map-service key (mk_…).
|
|
20
32
|
* @param {{ baseUrl: string, apiKey: string, timeoutMs?: number, retries?: number,
|
|
21
33
|
* retryDelayMs?: number, maxRetryAfterS?: number, fetch?: typeof fetch, userAgent?: string }} options
|
|
22
34
|
*/
|
|
@@ -25,10 +37,14 @@ class HttpClient {
|
|
|
25
37
|
throw new TypeError("hg-map-sdk: baseUrl is required, e.g. http://map-service:4120/api/v1/maps");
|
|
26
38
|
}
|
|
27
39
|
if (typeof options.apiKey !== "string" || !options.apiKey) {
|
|
28
|
-
throw new TypeError("hg-map-sdk: apiKey is required (
|
|
40
|
+
throw new TypeError("hg-map-sdk: apiKey is required (a Hoogaaa Cloud key hk_test_… / hk_live_…, or a map-service key mk_…)");
|
|
29
41
|
}
|
|
30
42
|
this.baseUrl = options.baseUrl.replace(/\/+$/, "");
|
|
31
|
-
this.apiKey = options.apiKey;
|
|
43
|
+
this.apiKey = options.apiKey.trim();
|
|
44
|
+
// A Hoogaaa Cloud key (from the console) goes to the gateway in its own header; the gateway checks it, counts the
|
|
45
|
+
// call in the console's Usage and strips it before map-service. A map-service key (mk_…) goes as before.
|
|
46
|
+
this.keyHeader = this.apiKey.startsWith("hk_") ? "X-Hoogaaa-Api-Key" : "X-Map-Service-Api-Key";
|
|
47
|
+
if (!this.apiKey.startsWith("hk_")) warnOldKey();
|
|
32
48
|
this.timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs;
|
|
33
49
|
this.retries = Math.max(0, options.retries ?? DEFAULTS.retries);
|
|
34
50
|
this.retryDelayMs = options.retryDelayMs ?? DEFAULTS.retryDelayMs;
|
|
@@ -49,7 +65,7 @@ class HttpClient {
|
|
|
49
65
|
res = await this.fetch(`${this.baseUrl}${path}`, {
|
|
50
66
|
method,
|
|
51
67
|
headers: {
|
|
52
|
-
|
|
68
|
+
[this.keyHeader]: this.apiKey,
|
|
53
69
|
"User-Agent": this.userAgent,
|
|
54
70
|
...(body !== undefined ? { "Content-Type": "application/json" } : {}),
|
|
55
71
|
},
|
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
|
*/
|
|
@@ -21,6 +22,8 @@ class MapServiceError extends Error {
|
|
|
21
22
|
|
|
22
23
|
/** True for failures worth retrying later (map-service down/slow, or rate-limited). */
|
|
23
24
|
get retryable() {
|
|
25
|
+
// A test key on a server with only paid providers: asking again never helps.
|
|
26
|
+
if (this.code === "PAID_PROVIDERS_OFF") return false;
|
|
24
27
|
return (
|
|
25
28
|
this.code === "NETWORK_ERROR" ||
|
|
26
29
|
this.code === "TIMEOUT" ||
|