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 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
- /** 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"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hg-map-sdk",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Client for Mummy's Dabba 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",
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 (this service's own key: npm run clients -- create <name>)");
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
- "X-Map-Service-Api-Key": this.apiKey,
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 …) 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
  */