@chaosity/location-client 0.2.0 → 0.2.1

package/dist/auth/TokenProvider.js

@@ -1,6 +1,7 @@
 import debug from 'debug';
 import { LocationServiceException } from '../errors/LocationServiceException';
 import { requestJson } from '../transport/http';
+import { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry } from './tokenRefresh';
 const log = debug('location-client:auth');
 /**
  * TokenProvider - SERVER-SIDE ONLY
@@ -110,9 +111,13 @@ export class TokenProvider {
             });
         }
         this.cachedToken = data.access_token;
-        // Prefer the absolute expires_at (ms); fall back to expires_in (seconds).
+        // The token's own `exp` claim first — it is the only value that cannot
+        // disagree with what the API will actually accept. `expires_at` and
+        // `expires_in` are what the response CLAIMS, and are kept as fallbacks.
         this.cachedExpiresAt =
-            data.expires_at ?? Date.now() + (data.expires_in ?? 900) * 1000;
+            readTokenExpiry(data.access_token) ??
+                data.expires_at ??
+                Date.now() + (data.expires_in ?? 900) * 1000;
         log('Token acquired successfully (expires in %ds)', Math.floor((this.cachedExpiresAt - Date.now()) / 1000));
         return {
             success: true,
@@ -120,7 +125,7 @@ export class TokenProvider {
             expiresAt: this.cachedExpiresAt,
         };
     }
-    isExpired(bufferSeconds = 60) {
+    isExpired(bufferSeconds = TOKEN_REFRESH_BUFFER_SECONDS) {
         if (!this.cachedExpiresAt)
             return true;
         return Date.now() >= this.cachedExpiresAt - bufferSeconds * 1000;

package/dist/auth/tokenRefresh.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+export declare const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+export declare function readTokenExpiry(token: string | undefined): number | undefined;

package/dist/auth/tokenRefresh.js

@@ -0,0 +1,54 @@
+/**
+ * How long before expiry a token is treated as needing replacement.
+ *
+ * ONE number, used by both sides: the server-side `TokenProvider` deciding
+ * whether its cached token is still good, and the React provider deciding
+ * whether to ask for a new one. Both apply it to the same `exp` claim, so they
+ * cannot reach different answers about the same token.
+ *
+ * It used to be two separate `60`s — a private literal in `isExpired()` and a
+ * public `refreshBuffer` prop default — with nothing tying them together. On
+ * 2026-08-23 a consumer passed `refreshBuffer={800}` against a 900 s token: the
+ * client judged it stale after 100 s, the server still considered it fresh for
+ * another 840 s and returned the same one, and the client asked again
+ * immediately — roughly 110 requests per second from an idle page.
+ *
+ * Not configurable per consumer, deliberately. A settable client-side buffer is
+ * precisely what allowed that disagreement, and no amount of capping or backing
+ * off fixes it as cleanly as the two sides simply sharing the number.
+ */
+export const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+/**
+ * Read the `exp` claim out of a JWT, in milliseconds.
+ *
+ * The expiry is IN THE TOKEN, so neither side needs to be told it. Both used to
+ * take it on trust from elsewhere — the server from the response body's
+ * `expires_at`, the React provider from whatever `getConfig` returned, falling
+ * back to inventing `Date.now() + 900_000` when that was absent. An invented
+ * expiry is how the two ended up disagreeing about the same token.
+ *
+ * Deliberately NOT verified. This is only used to decide *when to refresh*;
+ * nothing is authorised on the strength of it, and the API verifies the
+ * signature on every request regardless. Trusting `exp` for scheduling is safe
+ * in a way that trusting it for access would not be.
+ *
+ * Returns undefined for anything unparseable, so callers keep their fallback.
+ */
+export function readTokenExpiry(token) {
+    if (!token)
+        return undefined;
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const json = typeof atob === 'function'
+            ? atob(base64)
+            : Buffer.from(base64, 'base64').toString('utf8');
+        const exp = JSON.parse(json)?.exp;
+        return typeof exp === 'number' ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { GeoPlacesClient } from './client/GeoPlacesClient';
 export type { SendOptions } from './client/GeoPlacesClient';
 export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
 export type { RequestOptions } from './transport/http';
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
 export { LocationServiceException } from './errors/LocationServiceException';
 export type { LocationServiceExceptionOptions } from './errors/LocationServiceException';
 export * from '@aws-sdk/client-geo-places';

package/dist/index.js

@@ -2,6 +2,8 @@
 export { GeoPlacesClient } from './client/GeoPlacesClient';
 // Transport options — cancellation, per-attempt timeout, retry policy
 export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport/http';
+// Token refresh policy — shared by the server provider and the React provider
+export { TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from './auth/tokenRefresh';
 // Errors
 export { LocationServiceException } from './errors/LocationServiceException';
 // Re-export AWS SDK commands and types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",