@chaosity/location-client 0.11.0 → 0.13.0

package/dist/server/getClientConfig.js

@@ -69,6 +69,30 @@ 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. An application
+ * that is not active is a 403 (`ApplicationNotActiveException`) on either
+ * path, whose sentence names its cause, and it is left as the API wrote it,
+ * like every 403.
+ */
+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) {
+    return `Check that LOCATION_CLIENT_ID ("${clientId}") and LOCATION_CLIENT_SECRET match your application in the developer portal.`;
+}
 export function serverTokenSource(config = {}) {
     log('[serverTokenSource] Starting with config:', {
         hasApiUrl: !!config.apiUrl,
@@ -103,28 +127,27 @@ export function serverTokenSource(config = {}) {
     const provider = getTokenProvider(apiUrl, clientId, clientSecret);
     return {
         apiUrl,
-        async getToken(forceRefresh = false) {
+        async getToken(forceRefresh = false, options) {
             log('[serverTokenSource] Fetching token (forceRefresh=%s)', forceRefresh);
             let result;
             try {
-                result = await provider.getToken(forceRefresh);
+                result = await provider.getToken(forceRefresh, options);
             }
             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)}`,
+                        statusCode: error.statusCode,
+                        requestId: error.requestId,
+                        details: error.details,
+                        retryAfterMs: error.retryAfterMs,
+                        cause: error,
+                    });
                 }
                 throw error;
             }
@@ -181,8 +204,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/server/index.d.ts

@@ -1,5 +1,5 @@
 export { TokenProvider } from '../auth/TokenProvider.js';
-export type { TokenProviderConfig, TokenResponse, } from '../auth/TokenProvider.js';
+export type { GetTokenOptions, TokenProviderConfig, TokenResponse, } from '../auth/TokenProvider.js';
 export { getClientConfig } from './getClientConfig.js';
 export type { ServerAuthConfig, ServerClientConfig } from './getClientConfig.js';
 export { LocationServiceConnector } from './LocationServiceConnector.js';

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/dist/transport/http.d.ts

@@ -38,6 +38,24 @@ export interface RequestOptions {
         maxAttempts?: number;
     };
 }
+/**
+ * A call's options once it has begun: `deadline` is when `overallTimeoutMs`
+ * runs out, fixed at the call's entry, so that a wait before the request — a
+ * token — spends the same budget the request then gets the rest of (#62).
+ */
+export interface CallOptions extends RequestOptions {
+    deadline: number;
+}
+/** Fix a call's deadline at its entry (#62). */
+export declare function startCall<T extends RequestOptions>(options?: T): T & CallOptions;
+/**
+ * Wait for `work` within the call: reject with `AbortedException` when the
+ * caller's signal aborts, and with `TimeoutException` when its deadline
+ * passes, whichever comes first (#62). `work` itself is left running, because
+ * it may be shared: one caller's abort must not fail another waiting on the
+ * same token fetch.
+ */
+export declare function withinCall<T>(work: Promise<T>, call: CallOptions): Promise<T>;
 /** Exponential backoff with FULL jitter, so retries never march in lockstep. */
 export declare function backoffMs(attempt: number, random?: () => number): number;
 /**

package/dist/transport/http.js

@@ -25,6 +25,40 @@ export const DEFAULT_OVERALL_TIMEOUT_MS = 30000;
 export const DEFAULT_MAX_ATTEMPTS = 3;
 const BACKOFF_BASE_MS = 250;
 const BACKOFF_CAP_MS = 4000;
+/** Fix a call's deadline at its entry (#62). */
+export function startCall(options = {}) {
+    return {
+        ...options,
+        deadline: Date.now() + (options.overallTimeoutMs ?? DEFAULT_OVERALL_TIMEOUT_MS),
+    };
+}
+/**
+ * Wait for `work` within the call: reject with `AbortedException` when the
+ * caller's signal aborts, and with `TimeoutException` when its deadline
+ * passes, whichever comes first (#62). `work` itself is left running, because
+ * it may be shared: one caller's abort must not fail another waiting on the
+ * same token fetch.
+ */
+export function withinCall(work, call) {
+    const { signal, deadline } = call;
+    const overallTimeoutMs = call.overallTimeoutMs ?? DEFAULT_OVERALL_TIMEOUT_MS;
+    if (signal?.aborted)
+        return Promise.reject(abortedException(signal));
+    const left = deadline - Date.now();
+    if (left <= 0)
+        return Promise.reject(overallTimeoutException(overallTimeoutMs));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => finish(() => reject(overallTimeoutException(overallTimeoutMs))), left);
+        const onAbort = () => finish(() => reject(abortedException(signal)));
+        signal?.addEventListener('abort', onAbort, { once: true });
+        function finish(settle) {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            settle();
+        }
+        work.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
 /**
  * Combine the caller's signal with a per-attempt timeout.
  *
@@ -106,7 +140,9 @@ async function request(url, init, options, read) {
             details: { source: 'client' },
         });
     }
-    const deadline = Date.now() + overallTimeoutMs;
+    // A call that began before this request (#62) brings its own deadline, so
+    // the request has only what the wait before it left.
+    const deadline = options.deadline ?? Date.now() + overallTimeoutMs;
     let lastError;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
         // Checked before every attempt: a signal aborted during backoff must not fire one more.

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+import type { VerifyAddressCommand, VerifyAddressResponse } from '../client/commands.js';
 /**
  * At least one of `token`, `getToken` or `refreshToken` must supply a token, or
  * `send` refuses locally with `InvalidCredentialsException` rather than putting
@@ -52,6 +53,30 @@ export interface ClientConfig {
 export interface GeoPlacesCommand {
     readonly input: object;
 }
+/**
+ * The part of an AWS SDK command that carries its output type: the request
+ * handler its `resolveMiddleware` builds resolves with `{ output }`. The SDK's
+ * own `send` reads the output from the command the same way.
+ */
+interface SdkCommandOutputs<O extends object = object> {
+    resolveMiddleware(...args: never[]): (...args: never[]) => Promise<{
+        output: O;
+    }>;
+}
+/**
+ * A command whose output `send` can name (#68): every SDK command, this
+ * package's narrowed Places commands among them, and `VerifyAddressCommand`.
+ */
+export type CommandWithOutput = SdkCommandOutputs | VerifyAddressCommand;
+/**
+ * What `send` resolves with for a command (#68): an SDK command's own
+ * `…CommandOutput`, and `VerifyAddressResponse` for `VerifyAddressCommand`,
+ * which is this package's and has no handler.
+ *
+ * @example
+ * type Out = CommandOutput<AutocompleteCommand> // AutocompleteCommandOutput
+ */
+export type CommandOutput<C extends CommandWithOutput> = C extends SdkCommandOutputs<infer O> ? O : VerifyAddressResponse;
 /**
  * Minimal interface for a MapLibre Map instance.
  * Using a structural type avoids hard coupling to a specific maplibre-gl version.
@@ -69,3 +94,4 @@ export interface MapLike {
     getLayoutProperty(layerId: string, name: string): unknown;
     setLayoutProperty(layerId: string, name: string, value: unknown): void;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -58,8 +58,8 @@
     "url": "https://github.com/chaosity-io/location-service-client/issues"
   },
   "dependencies": {
-    "@aws-sdk/client-geo-places": "^3.0.0",
-    "@aws/amazon-location-utilities-datatypes": "^1.0.0",
+    "@aws-sdk/client-geo-places": "^3.1116.0",
+    "@aws/amazon-location-utilities-datatypes": "^1.2.4",
     "debug": "^4.4.3"
   },
   "peerDependencies": {