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 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 mesh-service/map-osrm/map-service
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
- /** e.g. "http://map-service:4120/api/v1/maps" */
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
- /** This service's own key (map-service: npm run clients -- create <name>). */
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.0.0",
4
- "description": "Client for Mummy's Dabba map-service: routing, ETA, trip optimization, geocoding and India PIN codes \u2014 provider-independent",
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/mummys-dabba-map-service.git",
21
+ "url": "git+https://github.com/satyamsonker1010/hoogaaa-map-service.git",
22
22
  "directory": "sdk"
23
23
  },
24
- "homepage": "https://github.com/satyamsonker1010/mummys-dabba-map-service/tree/development/sdk#readme",
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 (this service's own key: npm run clients -- create <name>)");
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
- "X-Map-Service-Api-Key": this.apiKey,
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 …) plus two of the SDK's own:
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" ||