@chaosity/location-client 0.10.0 → 0.12.0

package/dist/errors/LocationServiceException.d.ts

@@ -12,9 +12,36 @@
  * caller hears of it; there is no check to make beforehand.
  */
 export declare const FEATURE_NOT_ENTITLED = "FeatureNotEntitledException";
+/**
+ * Every `code` the API sends (#38): its error contract, published at
+ * https://docs.chaosity.cloud/api/errors, plus the Amazon Location exception
+ * names it passes through from upstream.
+ *
+ * A few are worth knowing apart. `RateLimitExceededException` is the
+ * application's own throttle; `ThrottlingException` is Amazon Location
+ * throttling the service; `IpRateLimitExceededException` is the per-address
+ * limit in front of `/auth/token`. `ApplicationNotActiveException` (403) is an
+ * application that is new, suspended or off its plan.
+ * `TokenExpiredException` is in the contract but never sent: an expired token
+ * arrives as `UnauthorizedException`.
+ */
+export declare const API_ERROR_CODES: readonly ["AccessDeniedException", "ApplicationNotActiveException", "ClientException", "FeatureNotEntitledException", "ForbiddenException", "InternalException", "InternalServerException", "InvalidCredentialsException", "IpRateLimitExceededException", "NotAcceptableException", "NotFoundException", "OriginNotAllowedException", "RateLimitExceededException", "ResourceNotFoundException", "ServiceUnavailableException", "ThrottlingException", "TimeoutException", "TokenExpiredException", "UnauthorizedException", "UpstreamException", "ValidationException"];
+/**
+ * The codes only this package raises, for failures that never reached the
+ * API. It raises some of the API's codes too — `TimeoutException` for its own
+ * timeout, `InvalidCredentialsException` for a missing token — and those are
+ * in the list above.
+ */
+export declare const CLIENT_ERROR_CODES: readonly ["AbortedException", "NetworkException", "ServiceException", "UnknownCommandException"];
+export declare const LOCATION_SERVICE_ERROR_CODES: readonly ["AccessDeniedException", "ApplicationNotActiveException", "ClientException", "FeatureNotEntitledException", "ForbiddenException", "InternalException", "InternalServerException", "InvalidCredentialsException", "IpRateLimitExceededException", "NotAcceptableException", "NotFoundException", "OriginNotAllowedException", "RateLimitExceededException", "ResourceNotFoundException", "ServiceUnavailableException", "ThrottlingException", "TimeoutException", "TokenExpiredException", "UnauthorizedException", "UpstreamException", "ValidationException", "AbortedException", "NetworkException", "ServiceException", "UnknownCommandException"];
+/**
+ * A `LocationServiceException`'s `code`: one of these, or a code the API adds
+ * after this release, which arrives all the same.
+ */
+export type LocationServiceErrorCode = (typeof LOCATION_SERVICE_ERROR_CODES)[number];
 export interface LocationServiceExceptionOptions {
     message: string;
-    code: string;
+    code: LocationServiceErrorCode | (string & {});
     /** Absent for failures that never reached the server: network, timeout, abort. */
     statusCode?: number;
     requestId?: string;
@@ -32,7 +59,8 @@ export interface LocationServiceExceptionOptions {
  * rather than sniffing at `TypeError` vs `DOMException` vs a bare `Error`.
  */
 export declare class LocationServiceException extends Error {
-    readonly code: string;
+    /** See `LocationServiceErrorCode`: typed, and open to a code added later. */
+    readonly code: LocationServiceErrorCode | (string & {});
     readonly statusCode?: number;
     readonly requestId?: string;
     readonly details?: Record<string, unknown>;

package/dist/errors/LocationServiceException.js

@@ -12,6 +12,58 @@
  * caller hears of it; there is no check to make beforehand.
  */
 export const FEATURE_NOT_ENTITLED = 'FeatureNotEntitledException';
+/**
+ * Every `code` the API sends (#38): its error contract, published at
+ * https://docs.chaosity.cloud/api/errors, plus the Amazon Location exception
+ * names it passes through from upstream.
+ *
+ * A few are worth knowing apart. `RateLimitExceededException` is the
+ * application's own throttle; `ThrottlingException` is Amazon Location
+ * throttling the service; `IpRateLimitExceededException` is the per-address
+ * limit in front of `/auth/token`. `ApplicationNotActiveException` (403) is an
+ * application that is new, suspended or off its plan.
+ * `TokenExpiredException` is in the contract but never sent: an expired token
+ * arrives as `UnauthorizedException`.
+ */
+export const API_ERROR_CODES = [
+    'AccessDeniedException',
+    'ApplicationNotActiveException',
+    'ClientException',
+    'FeatureNotEntitledException',
+    'ForbiddenException',
+    'InternalException',
+    'InternalServerException',
+    'InvalidCredentialsException',
+    'IpRateLimitExceededException',
+    'NotAcceptableException',
+    'NotFoundException',
+    'OriginNotAllowedException',
+    'RateLimitExceededException',
+    'ResourceNotFoundException',
+    'ServiceUnavailableException',
+    'ThrottlingException',
+    'TimeoutException',
+    'TokenExpiredException',
+    'UnauthorizedException',
+    'UpstreamException',
+    'ValidationException',
+];
+/**
+ * The codes only this package raises, for failures that never reached the
+ * API. It raises some of the API's codes too — `TimeoutException` for its own
+ * timeout, `InvalidCredentialsException` for a missing token — and those are
+ * in the list above.
+ */
+export const CLIENT_ERROR_CODES = [
+    'AbortedException',
+    'NetworkException',
+    'ServiceException',
+    'UnknownCommandException',
+];
+export const LOCATION_SERVICE_ERROR_CODES = [
+    ...API_ERROR_CODES,
+    ...CLIENT_ERROR_CODES,
+];
 /**
  * The single error type this package throws.
  *

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { DEFAULT_MAX_ATTEMPTS, DEFAULT_OVERALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, }
 export type { RequestOptions } from './transport/http.js';
 export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh.js';
 export { FEATURE_NOT_ENTITLED, LocationServiceException, } from './errors/LocationServiceException.js';
-export type { LocationServiceExceptionOptions } from './errors/LocationServiceException.js';
+export type { LocationServiceErrorCode, LocationServiceExceptionOptions, } from './errors/LocationServiceException.js';
 export * from '@aws-sdk/client-geo-places';
 export { AutocompleteCommand, GeocodeCommand, GetPlaceCommand, ReverseGeocodeCommand, SearchNearbyCommand, SearchTextCommand, SuggestCommand, VerifyAddressCommand, } from './client/commands.js';
 export type { AutocompleteCommandInput, AutocompleteRequest, GeocodeCommandInput, GeocodeRequest, GetPlaceCommandInput, GetPlaceRequest, NeverForwarded, ReverseGeocodeCommandInput, ReverseGeocodeRequest, SearchNearbyCommandInput, SearchNearbyRequest, SearchTextCommandInput, SearchTextRequest, SuggestCommandInput, SuggestRequest, VerifyAddressCommandInput, VerifyAddressResponse, } from './client/commands.js';

package/dist/server/LocationServiceConnector.d.ts

@@ -70,6 +70,8 @@ export declare class LocationServiceConnector {
     private readonly config;
     private tokenSource?;
     private readonly origin?;
+    /** A token the API refused, and why, until the hold lapses (#38). */
+    private readonly refused;
     readonly serviceId: string;
     constructor(config?: ConnectorConfig);
     /**

package/dist/server/LocationServiceConnector.js

@@ -1,4 +1,5 @@
 import debug from 'debug';
+import { TokenHold, holdFor } from '../auth/tokenHold.js';
 import { VerifyAddressCommand } from '../client/commands.js';
 import { LocationServiceException } from '../errors/LocationServiceException.js';
 import { resolveEndpoint } from '../transport/endpoints.js';
@@ -100,6 +101,8 @@ function explainMissingOrigin(err, sentOrigin) {
  */
 export class LocationServiceConnector {
     constructor(config = {}) {
+        /** A token the API refused, and why, until the hold lapses (#38). */
+        this.refused = new TokenHold();
         this.serviceId = 'Geo Places';
         this.config = config;
         // `||`, not `??`, to match the other four env-completed fields: an empty
@@ -213,24 +216,60 @@ export class LocationServiceConnector {
         const token = await source.get();
         if (!token)
             throw noTokenAvailable(NO_TOKEN_ADVICE);
+        // This token was refused a moment ago and nothing has replaced it: answer
+        // with that refusal rather than send it, and force the source, again (#38).
+        // A different token from the source ends the hold. When the refresh that
+        // followed said nothing about when to ask again, it is asked now — but the
+        // refused token is still not sent.
+        const held = this.refused.check(token);
+        if (held && !held.askAgain)
+            throw held.error;
+        let rejected = held?.error;
+        if (!held) {
+            try {
+                return await this.dispatch(url, token, cmd, options);
+            }
+            catch (err) {
+                if (!isTokenRejected(err))
+                    throw err;
+                rejected = err;
+            }
+        }
+        // One retry, and only when the replacement is genuinely a different token.
+        // That single comparison covers every source: a fixed `token` string, a
+        // caller `getToken` that ignores `forceRefresh`, and a cached token the API
+        // has revoked before its `exp` all hand back what we already sent — and
+        // re-sending it would be a second doomed request for the same answer.
+        let fresh;
         try {
-            return await this.dispatch(url, token, cmd, options);
+            fresh = await source.get(true);
         }
-        catch (err) {
-            if (!isTokenRejected(err))
-                throw err;
-            // One retry, and only when the replacement is genuinely a different
-            // token. That single comparison covers every source: a fixed `token`
-            // string, a caller `getToken` that ignores `forceRefresh`, and a cached
-            // token the API has revoked before its `exp` all hand back what we
-            // already sent — and re-sending it would be a second doomed request for
-            // the same answer.
-            const fresh = await source.get(true);
-            if (!fresh || fresh === token)
-                throw err;
-            log('401 on a token the API no longer accepts — retrying once, refreshed');
+        catch (refusal) {
+            // A suspended application's /auth/token refuses it as its data routes
+            // refuse its token. Without this, every send asked for another. A
+            // refusal that says nothing — a network fault — leaves the source to be
+            // asked again, but not the token sent.
+            if (holdFor(refusal) > 0)
+                this.refused.remember(refusal, token);
+            // Only when no hold stands: one already standing keeps its own end, so
+            // the refused token is tried again once per hold rather than never.
+            else if (!held)
+                this.refused.remember(rejected, token, { askAgain: true });
+            throw refusal;
+        }
+        if (!fresh || fresh === token) {
+            this.refused.remember(rejected, token);
+            throw rejected;
+        }
+        log('401 on a token the API no longer accepts — retrying once, refreshed');
+        try {
             return await this.dispatch(url, fresh, cmd, options);
         }
+        catch (again) {
+            if (isTokenRejected(again))
+                this.refused.remember(again, fresh);
+            throw again;
+        }
     }
     dispatch(url, token, cmd, options) {
         // The caller's input goes out as the caller wrote it — nothing in the body

package/dist/server/getClientConfig.d.ts

@@ -104,8 +104,9 @@ export declare function serverTokenSource(config?: ServerAuthConfig): ServerToke
  * // Auto-detect from environment
  * const config = await getClientConfig()
  *
- * // Or override specific values
- * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ * // Or override specific values — the API URL is the one on the
+ * // application's page in the developer portal
+ * const config = await getClientConfig({ apiUrl: 'https://your-api-url.example' })
  *
  * // The API rejected the token before its exp — revoked, or secret rotated
  * const fresh = await getClientConfig({ forceRefresh: true })

package/dist/server/getClientConfig.js

@@ -69,6 +69,33 @@ export function resolveApiUrl(explicit) {
         process.env.LOCATION_API_URL ||
         process.env.LOCATION_SERVICE_API_URL);
 }
+/**
+ * A refusal of the client credentials themselves, as opposed to a refusal
+ * whose sentence already names its cause.
+ *
+ * Two answers qualify. `/auth/token`'s own `Invalid credentials` is a secret
+ * that matched nothing. The gateway's 401 (`UnauthorizedException`) is the
+ * authorizer refusing the Basic pair before `/auth/token` runs, and it gives
+ * the same answer for a wrong secret and for an application that is not
+ * active, so the advice for it names both. `Application is not active`, and
+ * every 403, is left as the API wrote it.
+ */
+function isCredentialsRefusal(error) {
+    if (!(error instanceof LocationServiceException))
+        return false;
+    if (error.statusCode !== 401)
+        return false;
+    return (error.code === 'UnauthorizedException' ||
+        error.message === 'Invalid credentials');
+}
+/** The API's words as a sentence, so the advice can follow them. */
+const sentence = (text) => (/[.!?]$/.test(text) ? text : `${text}.`);
+function credentialsAdvice(clientId, error) {
+    const check = `Check that LOCATION_CLIENT_ID ("${clientId}") and LOCATION_CLIENT_SECRET match your application in the developer portal`;
+    return error.code === 'UnauthorizedException'
+        ? `${check}, and that the application is active there.`
+        : `${check}.`;
+}
 export function serverTokenSource(config = {}) {
     log('[serverTokenSource] Starting with config:', {
         hasApiUrl: !!config.apiUrl,
@@ -110,21 +137,20 @@ export function serverTokenSource(config = {}) {
                 result = await provider.getToken(forceRefresh);
             }
             catch (error) {
-                // The provider now rejects rather than resolving with success:false, and
-                // the rejection is typed — so a store outage (503) can be reported as a
-                // store outage instead of as bad credentials.
-                if (error instanceof LocationServiceException) {
-                    if (error.isAuth) {
-                        throw new LocationServiceException({
-                            code: 'InvalidCredentialsException',
-                            message: `Authentication failed for client ID "${clientId}". ` +
-                                `Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET match your application in the developer portal.`,
-                            statusCode: error.statusCode,
-                            requestId: error.requestId,
-                            cause: error,
-                        });
-                    }
-                    throw error;
+                // The API's code and sentence, passed through (#38). Every 401 and 403
+                // used to become "Verify LOCATION_CLIENT_ID and LOCATION_CLIENT_SECRET",
+                // which sent a suspended application to check a secret that was fine.
+                // The advice is added only where the credentials are what was refused.
+                if (isCredentialsRefusal(error)) {
+                    throw new LocationServiceException({
+                        code: error.code,
+                        message: `${sentence(error.message)} ${credentialsAdvice(clientId, error)}`,
+                        statusCode: error.statusCode,
+                        requestId: error.requestId,
+                        details: error.details,
+                        retryAfterMs: error.retryAfterMs,
+                        cause: error,
+                    });
                 }
                 throw error;
             }
@@ -181,8 +207,9 @@ export function serverTokenSource(config = {}) {
  * // Auto-detect from environment
  * const config = await getClientConfig()
  *
- * // Or override specific values
- * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ * // Or override specific values — the API URL is the one on the
+ * // application's page in the developer portal
+ * const config = await getClientConfig({ apiUrl: 'https://your-api-url.example' })
  *
  * // The API rejected the token before its exp — revoked, or secret rotated
  * const fresh = await getClientConfig({ forceRefresh: true })

package/dist/transport/errors.d.ts

@@ -2,14 +2,20 @@ import { LocationServiceException } from '../errors/LocationServiceException.js'
 /**
  * Turn a non-2xx response into a LocationServiceException.
  *
- * The API does not yet speak one error shape — that is api#29 (T23) — so this
- * tolerates the three it currently emits and synthesises a `code` for each.
- * RFC-0002 calls this legacy tolerance, and it is what lets the client ship
- * before the API contract lands. Delete the fallbacks once T23 is deployed.
- *
- *   { message, code, requestId }         service Lambdas — already correct
- *   { error, error_description }         /auth/token, OAuth shape
- *   { message: "Unauthorized" }          API Gateway's own responses
+ * The API answers every failure with a `code`, in one of three envelopes:
+ *
+ *   { message, code, requestId }                    data routes; the gateway
+ *   { error, error_description, code, requestId }   /auth/token (OAuth 2.0)
+ *   { code, message }                               the per-address limit
+ *
+ * The sentence is in `message`, or on /auth/token in `error_description`, and
+ * both are read whatever else the body carries (#38). The description used to
+ * be read only from a body with no `code`, and /auth/token has sent one since,
+ * so every refusal from it arrived as "Request failed: Unauthorized": a
+ * suspended application read exactly like a wrong secret.
+ *
+ * A body with no `code` — a proxy's, or an older deployment's — still gets
+ * one: from its OAuth `error`, else from the status.
  */
 export declare function parseErrorResponse(status: number, statusText: string, body: string, headers?: Headers): LocationServiceException;
 /**

package/dist/transport/errors.js

@@ -1,15 +1,21 @@
-import { LocationServiceException } from '../errors/LocationServiceException.js';
+import { LocationServiceException, } from '../errors/LocationServiceException.js';
 /**
  * Turn a non-2xx response into a LocationServiceException.
  *
- * The API does not yet speak one error shape — that is api#29 (T23) — so this
- * tolerates the three it currently emits and synthesises a `code` for each.
- * RFC-0002 calls this legacy tolerance, and it is what lets the client ship
- * before the API contract lands. Delete the fallbacks once T23 is deployed.
+ * The API answers every failure with a `code`, in one of three envelopes:
  *
- *   { message, code, requestId }         service Lambdas — already correct
- *   { error, error_description }         /auth/token, OAuth shape
- *   { message: "Unauthorized" }          API Gateway's own responses
+ *   { message, code, requestId }                    data routes; the gateway
+ *   { error, error_description, code, requestId }   /auth/token (OAuth 2.0)
+ *   { code, message }                               the per-address limit
+ *
+ * The sentence is in `message`, or on /auth/token in `error_description`, and
+ * both are read whatever else the body carries (#38). The description used to
+ * be read only from a body with no `code`, and /auth/token has sent one since,
+ * so every refusal from it arrived as "Request failed: Unauthorized": a
+ * suspended application read exactly like a wrong secret.
+ *
+ * A body with no `code` — a proxy's, or an older deployment's — still gets
+ * one: from its OAuth `error`, else from the status.
  */
 export function parseErrorResponse(status, statusText, body, headers) {
     let message = `Request failed: ${statusText || status}`;
@@ -18,17 +24,19 @@ export function parseErrorResponse(status, statusText, body, headers) {
     let details;
     try {
         const data = JSON.parse(body);
-        if (typeof data.message === 'string')
-            message = data.message;
-        if (typeof data.code === 'string')
-            code = data.code;
-        if (typeof data.requestId === 'string')
-            requestId = data.requestId;
-        // OAuth envelope from /auth/token
-        if (!code && typeof data.error === 'string') {
-            message = data.error_description ?? data.error;
-            code = oauthCode(data.error, status);
-            details = { oauthError: data.error };
+        const text = (value) => typeof value === 'string' ? value : undefined;
+        message =
+            text(data.error_description) ??
+                text(data.message) ??
+                text(data.error) ??
+                message;
+        code = text(data.code);
+        requestId = text(data.requestId);
+        // OAuth `error`, from /auth/token and the gateway's 401 on it
+        const oauthError = text(data.error);
+        if (oauthError) {
+            code ?? (code = oauthCode(oauthError, status));
+            details = { oauthError };
         }
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -64,7 +64,7 @@
   },
   "peerDependencies": {
     "@maplibre/maplibre-gl-geocoder": "^1.9.4",
-    "maplibre-gl": "^5.0.0"
+    "maplibre-gl": "^6.4.1"
   },
   "peerDependenciesMeta": {
     "@maplibre/maplibre-gl-geocoder": {
@@ -82,7 +82,7 @@
     "@vitest/coverage-v8": "^3.0.0",
     "eslint": "^10.1.0",
     "husky": "^9.0.0",
-    "maplibre-gl": "^5.0.0",
+    "maplibre-gl": "^6.4.1",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "typescript": "^5.0.0",