Update JavaScript SDK request handling and Arabic support for 3.0.2

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 3.0.2
+
+- Hide API keys when printing client settings and request errors, including errors in typed bulk results.
+- Stop redirects from sending lookup data or custom headers to another server.
+- Keep the HTTP status when an error response is too large or interrupted. Check that typed bulk results match the number of IPs requested.
+- Add Arabic (`ar`) for single and bulk lookups.
+- Include CDN, proxy, bot and corporate gateway details in typed results.
+- Report the installed package version and preserve special property names in headers and JSON output.
+
 ## 3.0.0
 
 - Initial JavaScript SDK release for `/v3/ipgeo` and `/v3/ipgeo-bulk`

README.md

@@ -191,6 +191,8 @@ Paid plans still need `include` for optional modules. `fields` and `excludes` on
 
 You can also pass a custom `HttpTransport` as the second constructor argument.
 
+If you set `baseUrl`, use the final API address. In Node.js, the built-in client follows redirects only within the same protocol, host and port. Browsers hide the redirect address, so the client stops at a redirect.
+
 ## Available Methods
 
 | Method | Returns | Notes |
@@ -210,7 +212,7 @@ You can also pass a custom `HttpTransport` as the second constructor argument.
 |--------|------------|-------|
 | `ip` | Single lookup | IPv4, IPv6, or domain. Omit it for caller IP lookup. Domain lookup requires a paid plan. |
 | `ips` | Bulk lookup | Iterable of 1 to 50,000 IPs or domains. |
-| `lang` | Single and bulk | One of `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`. |
+| `lang` | Single and bulk | One of `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar` (Arabic). |
 | `include` | Single and bulk | Iterable of module names such as `security`, `abuse`, `user_agent`, `hostname`, `liveHostname`, `hostnameFallbackLive`, `geo_accuracy`, `dma_code`, or `*`. |
 | `fields` | Single and bulk | Iterable of field paths to keep, for example `["location.country_name", "security.threat_score"]`. |
 | `excludes` | Single and bulk | Iterable of field paths to remove from the response. |
@@ -401,7 +403,7 @@ for (const result of response.data) {
 
 ### Mixed Success and Error Results
 
-Each bulk result is either a success with `data` or an error with `error.message`.
+Each bulk result is either a success with `data` or an error with `error.message`. If the API sends a different number of results than you requested, the typed lookup throws `SerializationError`. The raw lookup returns the response as received.
 
 ```js
 const response = await client.bulkLookupIpGeolocation({
@@ -453,7 +455,7 @@ console.log(response.metadata.firstHeaderValue("x-credits-charged")); // the sam
 
 ## JSON Helpers
 
-Use `toJson()` or `toPrettyJson()` when you want a stable JSON view of SDK objects.
+Use `toJson()` or `toPrettyJson()` to print SDK objects as JSON. When you print a client or its settings as JSON, the SDK shows `[REDACTED]` in place of your API key. `config.apiKey` still gives you the key.
 
 ```js
 import { toPrettyJson } from "ip-geolocation-api-javascript-sdk";
@@ -467,7 +469,7 @@ console.log(toPrettyJson(response.data));
 
 ## Error Handling
 
-All SDK errors extend `IpGeolocationError`.
+All SDK errors extend `IpGeolocationError`. If an API error includes your key, the SDK hides it. This also applies to error messages in typed bulk results. If the SDK receives an HTTP status but can’t read the error body, you still get the status code.
 
 Runtime and validation errors:
 

package.json

@@ -1,7 +1,7 @@
 {
   "author": "IPGeolocation.io",
   "name": "ip-geolocation-api-javascript-sdk",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Official JavaScript SDK for the IPGeolocation IP Location API with single and bulk lookup, typed JSON, and raw JSON/XML support.",
   "license": "MIT",
   "type": "module",

scripts/check-package.cjs

@@ -7,14 +7,19 @@ async function main() {
   const esm = await import(pkg.name);
   const cjs = require(pkg.name);
   assert.deepEqual(Object.keys(esm).sort(), Object.keys(cjs).sort());
-  assert.equal(esm.getVersion(), cjs.getVersion());
   await access(path.resolve(__dirname, '..', pkg.types));
   await access(path.resolve(__dirname, '..', 'dist/index.d.cts'));
 
   for (const sdk of [esm, cjs]) {
+    assert.equal(sdk.getVersion(), pkg.version);
+    assert.equal(sdk.SDK_VERSION, pkg.version);
+    assert.equal(sdk.IpGeolocationClient.defaultUserAgent(), `ipgeolocation-javascript-sdk/${pkg.version}`);
     const config = new sdk.IpGeolocationClientConfig({ apiKey: 'package-test' });
     assert.equal(config.baseUrl, 'https://api.ipgeolocation.io');
     assert.equal(Object.isFrozen(config), true);
+    for (const formatter of [esm, cjs]) {
+      assert.equal(JSON.parse(formatter.toJson(config)).apiKey, '[REDACTED]');
+    }
     const request = new sdk.LookupIpGeolocationRequest({ ip: '2001:db8::1' });
     assert.equal(request.ip, '2001:db8::1');
     assert.equal(request.output, sdk.ResponseFormat.JSON);

src/client.ts

@@ -15,6 +15,7 @@ import {
   buildQuery,
   mergeHeaders,
   resolveUserAgentHeader,
+  safeTransportError,
   toApiError,
   toMetadata,
   validateJsonOutput,
@@ -31,7 +32,7 @@ import { getVersion } from "./version";
 
 export class IpGeolocationClient {
   private readonly config: IpGeolocationClientConfig;
-  private readonly transport: HttpTransport;
+  readonly #transport: HttpTransport;
   private readonly ownsTransport: boolean;
   private closed = false;
 
@@ -47,7 +48,7 @@ export class IpGeolocationClient {
       config instanceof IpGeolocationClientConfig
         ? config
         : new IpGeolocationClientConfig(config);
-    this.transport = transport ?? new FetchHttpTransport();
+    this.#transport = transport ?? new FetchHttpTransport();
     this.ownsTransport = transport == null;
   }
 
@@ -66,12 +67,8 @@ export class IpGeolocationClient {
     const httpRequest = this.buildLookupHttpRequest(normalizedRequest);
     const { response, durationMs } = await this.executeWithMetrics(httpRequest);
 
-    if (Math.floor(response.statusCode / 100) !== 2) {
-      throw toApiError(response.statusCode, response.body);
-    }
-
     return {
-      data: parseSingleLookup(response.body),
+      data: parseSingleLookup(response.body, this.config.apiKey),
       metadata: toMetadata(response.statusCode, durationMs, response.headers),
     };
   }
@@ -86,10 +83,6 @@ export class IpGeolocationClient {
     const httpRequest = this.buildLookupHttpRequest(normalizedRequest);
     const { response, durationMs } = await this.executeWithMetrics(httpRequest);
 
-    if (Math.floor(response.statusCode / 100) !== 2) {
-      throw toApiError(response.statusCode, response.body);
-    }
-
     return {
       data: response.body,
       metadata: toMetadata(response.statusCode, durationMs, response.headers),
@@ -109,12 +102,8 @@ export class IpGeolocationClient {
     const httpRequest = this.buildBulkHttpRequest(normalizedRequest);
     const { response, durationMs } = await this.executeWithMetrics(httpRequest);
 
-    if (Math.floor(response.statusCode / 100) !== 2) {
-      throw toApiError(response.statusCode, response.body);
-    }
-
     return {
-      data: parseBulkLookup(response.body),
+      data: parseBulkLookup(response.body, normalizedRequest.ips.length, this.config.apiKey),
       metadata: toMetadata(response.statusCode, durationMs, response.headers),
     };
   }
@@ -131,10 +120,6 @@ export class IpGeolocationClient {
     const httpRequest = this.buildBulkHttpRequest(normalizedRequest);
     const { response, durationMs } = await this.executeWithMetrics(httpRequest);
 
-    if (Math.floor(response.statusCode / 100) !== 2) {
-      throw toApiError(response.statusCode, response.body);
-    }
-
     return {
       data: response.body,
       metadata: toMetadata(response.statusCode, durationMs, response.headers),
@@ -148,7 +133,7 @@ export class IpGeolocationClient {
 
     this.closed = true;
     if (this.ownsTransport) {
-      await this.transport.close();
+      await this.#transport.close();
     }
   }
 
@@ -269,7 +254,15 @@ export class IpGeolocationClient {
     request: HttpRequestData,
   ): Promise<{ response: HttpResponseData; durationMs: number }> {
     const started = Date.now();
-    const response = await this.transport.send(request);
+    let response: HttpResponseData;
+    try {
+      response = await this.#transport.send(request);
+    } catch (error) {
+      throw safeTransportError(error, this.config.apiKey);
+    }
+    if (Math.floor(response.statusCode / 100) !== 2) {
+      throw toApiError(response.statusCode, response.body, this.config.apiKey);
+    }
     return {
       response,
       durationMs: Math.max(0, Date.now() - started),

src/config.ts

@@ -1,4 +1,5 @@
 import { ValidationError } from "./errors";
+import { configForOutput, configJson } from "./internal/redaction";
 import { containsCrOrLf, isPlainObjectRecord } from "./internal/shared";
 
 const DEFAULT_BASE_URL = "https://api.ipgeolocation.io";
@@ -15,7 +16,7 @@ export interface IpGeolocationClientConfigInit {
 }
 
 export class IpGeolocationClientConfig {
-  public readonly apiKey: string | undefined;
+  declare public readonly apiKey: string | undefined;
   public readonly requestOrigin: string | undefined;
   public readonly baseUrl: string;
   public readonly connectTimeoutMs: number;
@@ -41,7 +42,13 @@ export class IpGeolocationClientConfig {
       DEFAULT_READ_TIMEOUT_MS,
     );
 
-    this.apiKey = apiKey;
+    const forOutput = () => configForOutput(this);
+    Object.defineProperties(this, {
+      apiKey: { enumerable: true, get: () => apiKey },
+      toJSON: { value: forOutput },
+      [configJson]: { value: forOutput },
+      [Symbol.for("nodejs.util.inspect.custom")]: { value: forOutput },
+    });
     this.requestOrigin = requestOrigin;
     this.baseUrl = baseUrl;
     this.connectTimeoutMs = connectTimeoutMs;

src/enums.ts

@@ -11,6 +11,7 @@ export const Language = Object.freeze({
   KO: "ko",
   FA: "fa",
   PT: "pt",
+  AR: "ar",
 } as const);
 
 export type Language = (typeof Language)[keyof typeof Language];

src/internal/redaction.ts

@@ -0,0 +1,125 @@
+import type { IpGeolocationClientConfig } from "../config";
+
+const MASK = "[REDACTED]";
+export const configJson = Symbol.for("ipgeolocation.clientConfig.toJSON");
+
+export function redactApiKey(text: string, key?: string): string {
+  if (!key) return text;
+  if (/^[A-Za-z0-9._-]+$/.test(key)) return text.split(key).join(MASK);
+
+  const form = new URLSearchParams({ k: key });
+  const encoded = encodeURIComponent(form.get("k")!);
+  let result = text;
+  for (const token of new Set([
+    encoded.replace(/'/g, "%27"),
+    encoded,
+    form.toString().slice(2),
+  ])) {
+    if (token === key || token.length > result.length) continue;
+    const upperEscapes = (s: string) =>
+      s.replace(/%[a-f\d]{2}/gi, (escape) => escape.toUpperCase());
+    const haystack = upperEscapes(result);
+    const needle = upperEscapes(token);
+    let start = 0;
+    const parts: string[] = [];
+    for (
+      let at = haystack.indexOf(needle);
+      at >= 0;
+      at = haystack.indexOf(needle, start)
+    ) {
+      parts.push(result.slice(start, at), MASK);
+      start = at + token.length;
+    }
+    if (parts.length) result = parts.join("") + result.slice(start);
+  }
+  const escaped = JSON.stringify(key).slice(1, -1);
+  if (escaped !== key) result = result.split(escaped).join(MASK);
+  return result.split(key).join(MASK);
+}
+
+const nativeStackGetter = Object.getOwnPropertyDescriptor(
+  new Error(),
+  "stack",
+)?.get;
+const inspectSymbol = Symbol.for("nodejs.util.inspect.custom");
+
+export function hasSafeErrorDetails(
+  value: unknown,
+  key: string,
+  seen = new Set<object>(),
+): boolean {
+  if (typeof value === "string") return redactApiKey(value, key) === value;
+  if (value === null || typeof value !== "object") {
+    return typeof value !== "function" && typeof value !== "symbol";
+  }
+  if (seen.has(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  if (
+    seen.size >= 32 ||
+    "toJSON" in value ||
+    Symbol.toPrimitive in value ||
+    inspectSymbol in value ||
+    (!(value instanceof Error) &&
+      !Array.isArray(value) &&
+      proto !== null &&
+      proto !== Object.prototype)
+  ) {
+    return false;
+  }
+  seen.add(value);
+  if (value instanceof Error) {
+    for (
+      let p = proto;
+      p && p !== Error.prototype;
+      p = Object.getPrototypeOf(p)
+    ) {
+      for (const name of Reflect.ownKeys(p)) {
+        if (name === "constructor") continue;
+        const field = Object.getOwnPropertyDescriptor(p, name)!;
+        if (
+          typeof name !== "string" ||
+          name === "toString" ||
+          name === "valueOf" ||
+          !("value" in field) ||
+          redactApiKey(name, key) !== name
+        )
+          return false;
+        if (
+          typeof field.value !== "function" &&
+          !hasSafeErrorDetails(field.value, key, seen)
+        )
+          return false;
+      }
+    }
+  }
+  for (const name of Reflect.ownKeys(value)) {
+    if (typeof name !== "string" || redactApiKey(name, key) !== name)
+      return false;
+    const property = Object.getOwnPropertyDescriptor(value, name)!;
+    let detail = property.value;
+    if (!("value" in property)) {
+      if (
+        name !== "stack" ||
+        !(value instanceof Error) ||
+        !nativeStackGetter ||
+        property.get !== nativeStackGetter
+      )
+        return false;
+      detail = nativeStackGetter.call(value);
+    }
+    if (!hasSafeErrorDetails(detail, key, seen)) return false;
+  }
+  return true;
+}
+
+export function configForOutput(config: IpGeolocationClientConfig) {
+  const key = config.apiKey;
+  return {
+    apiKey: key === undefined ? undefined : MASK,
+    requestOrigin:
+      config.requestOrigin && redactApiKey(config.requestOrigin, key),
+    baseUrl: redactApiKey(config.baseUrl, key),
+    connectTimeoutMs: config.connectTimeoutMs,
+    readTimeoutMs: config.readTimeoutMs,
+  };
+}