@chaosity/location-client-react 0.9.0 → 0.10.0

package/README.md

@@ -28,9 +28,16 @@ in `@chaosity/location-client`'s README has the copy script and the Vite form.
 
 import { getClientConfig } from '@chaosity/location-client/server'
 
-export async function getLocationConfig() {
+export async function getLocationConfig(request?: { refusedToken?: string }) {
   // Auto-reads LOCATION_API_URL, LOCATION_CLIENT_ID, LOCATION_CLIENT_SECRET
-  return await getClientConfig()
+  const config = await getClientConfig()
+  // The API refused this token before its expiry (revoked, or its secret
+  // rotated). getClientConfig() keeps one token per application, so replace
+  // it, but only when it is the one refused: see Token Refresh, step 5.
+  // `request` is optional: it arrives from the browser, and only after a 401.
+  return request?.refusedToken === config.token
+    ? getClientConfig({ forceRefresh: true })
+    : config
 }
 ```
 
@@ -88,6 +95,11 @@ function SearchComponent() {
 }
 ```
 
+With `@chaosity/location-client` 0.13.0 or later, `client.send` resolves with
+the command's own output type, so the `SuggestCommandOutput` annotation above
+is optional. On an older core, `send` answers `unknown` unless the output type
+is named, as it is here.
+
 ## Map Utilities
 
 ### useMapLanguage
@@ -141,7 +153,7 @@ Provides the location client and automatic token refresh to all child components
 
 **Props:**
 
-- `getConfig` — Async function that returns `{ apiUrl: string, token: string, expiresAt?: number }`. Called on mount, whenever the token needs refreshing, and to retry a call that failed (see [Token Refresh](#token-refresh)).
+- `getConfig` — Async function that returns `{ apiUrl: string, token: string, expiresAt?: number }`. Called on mount, whenever the token needs refreshing, and to retry a call that failed (see [Token Refresh](#token-refresh)). After the API refuses a token it is called with `{ refusedToken }`, the token refused; every other call passes nothing. An answer without a non-empty `token` and `apiUrl` is treated as a failure, as a rejection is.
 - `configKey` — Optional. What `getConfig` answers for, such as an organisation or application id. When it changes, the provider drops the old client, token and `apiUrl`, calls `getConfig` again and hands out a new client, without remounting its children.
 - `children` — Child components.
 
@@ -215,8 +227,22 @@ The provider owns the token lifecycle. There is nothing to manage manually.
    until the timer next comes around: for a token with 14 minutes left, 14
    minutes of a broken page. The core added this in 0.7.0, so every core this
    package's peer range admits has it.
+
+   Since 0.10.0 that refresh calls `getConfig({ refusedToken })`. Your server
+   has to act on it: `getClientConfig()` keeps one token per application and,
+   asked again, hands back the one just refused, so nothing is retried until
+   its cache comes round on its own (measured: almost ten minutes). Replace the
+   cached token only when it is the refused one, as the Quick Start does: that
+   mints once per refused token, however many visitors report it, and nothing
+   for a report of any other token. It does not stop a visitor echoing the
+   token it was just handed to make your server mint again; rate-limit the
+   action if that matters.
+
 6. Concurrent refreshes are deduplicated — everything waiting shares one call to
-   `getConfig`.
+   `getConfig`. A 401 that lands while a scheduled refresh is in flight shares
+   that call too, which names no token, so the refused one is named on the
+   next 401: at the next `send()` on a core below 0.12.0, and after the core's
+   30-second hold from 0.12.0.
 7. A failed `getConfig` is retried on the provider's own timer, backing off
    exponentially from 1 to 30 seconds, with jitter. When `getConfig` rejects
    with an error that has `retryAfterMs` (milliseconds), it waits that long
@@ -230,8 +256,13 @@ The provider owns the token lifecycle. There is nothing to manage manually.
    there:
 
    ```ts
-   async function getConfig() {
-     const res = await fetch('/api/location-token')
+   async function getConfig(request?: { refusedToken: string }) {
+     // In the body, not the URL, so the token stays out of access logs.
+     const res = await fetch('/api/location-token', {
+       method: 'POST',
+       headers: { 'content-type': 'application/json' },
+       body: JSON.stringify(request ?? {}),
+     })
      if (!res.ok) {
        const retryAfter = Number(res.headers.get('retry-after'))
        throw Object.assign(new Error(`token route answered ${res.status}`), {
@@ -319,6 +350,8 @@ export default function MapComponent() {
         'top-right',
       )
 
+      // Type-checks with @chaosity/location-client 0.13.0 or later. An older
+      // core types GeoPlaces's client as GeoPlacesClient, and reports TS2345.
       const geoPlaces = new GeoPlaces(client, instance)
       const geocoder = new MaplibreGeocoder(geoPlaces, {
         maplibregl,
@@ -494,6 +527,11 @@ const response: SuggestCommandOutput = await client!.send(
 )
 ```
 
+Every `send` example in this README names the output type, so it compiles on
+every core the peer range admits. From `@chaosity/location-client` 0.13.0 the
+annotation is optional: `send` resolves with the command's own output type,
+and the core's `CommandOutput<C>` names it when you need it.
+
 ## License
 
 MIT

package/dist/cjs/provider/LocationClientProvider.d.ts

@@ -1,5 +1,5 @@
 import type { ClientConfig, VerifyAddressResponse } from '@chaosity/location-client';
-import { type AppConfigClaims } from '@chaosity/location-client';
+import { type AppConfigClaims, GeoPlacesClient } from '@chaosity/location-client';
 import type { ReactNode } from 'react';
 /**
  * Per-request transport options.
@@ -36,7 +36,16 @@ export interface LocationClient {
     readonly config: {
         serviceId: string;
     };
-    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    /**
+     * The core's own `send`, overloads and all, not a copy of it: from core
+     * 0.13.0, `await client.send(new AutocompleteCommand(…))` is an
+     * `AutocompleteCommandOutput` with nothing to annotate (core #68). A copy
+     * of the old `send<TInput, TOutput>` kept answering `unknown`, and nothing
+     * caught it — that one signature and the core's pair of overloads are
+     * assignable to each other both ways. Below 0.13.0 it is the core's old
+     * signature, as before.
+     */
+    send: GeoPlacesClient['send'];
     /**
      * Verify a PlaceId through `POST /address/verify`: the full place record plus
      * `verified`, the one Places result an integrator may store (#26). A
@@ -86,7 +95,32 @@ interface LocationClientContextValue {
 }
 export interface LocationClientProviderProps {
     children: ReactNode;
-    getConfig: () => Promise<ClientConfig & {
+    /**
+     * Where the token and `apiUrl` come from: usually a server action returning
+     * `getClientConfig()`.
+     *
+     * After the API refuses a token before its `exp` (a revoked token, or a
+     * rotated secret), it is asked with `{ refusedToken }`, the token refused
+     * (#43). `getClientConfig()` caches one token per application, so a server
+     * that ignores this hands the refused token back, and the page stays broken
+     * until that cache comes round on its own. Ask for a new one only when the
+     * cached token IS the refused one:
+     *
+     *     return request?.refusedToken === config.token
+     *       ? getClientConfig({ forceRefresh: true })
+     *       : config
+     *
+     * That mints once per refused token, and nothing for a report of any other.
+     * It does not stop a caller echoing the token it was just handed, so a
+     * server worried about that rate-limits the call. Every other call passes
+     * nothing, and a `getConfig` that ignores the argument works as before.
+     *
+     * An answer without a non-empty `token` and `apiUrl` is taken as a failure
+     * (#39), as a rejection is.
+     */
+    getConfig: (request?: {
+        refusedToken: string;
+    }) => Promise<ClientConfig & {
         expiresAt?: number;
     }>;
     /**

package/dist/cjs/provider/LocationClientProvider.js

@@ -48,6 +48,7 @@ function retryAfterOf(err) {
         ?.retryAfterMs;
     return typeof ms === 'number' && ms > 0 ? ms : undefined;
 }
+const isFilled = (value) => typeof value === 'string' && value.length > 0;
 function overrides(trigger, hold) {
     if (trigger === 'scheduled')
         return true;
@@ -204,7 +205,9 @@ function LocationClientProvider({ children, getConfig, configKey, }) {
              *
              * The client awaits this after a 401 and retries the request once with
              * what it returns; the same token, or nothing, means no retry, so a
-             * doomed request is never sent — or billed — twice.
+             * doomed request is never sent — or billed — twice. The `rejected`
+             * trigger names the refused token to `getConfig` (#43): a server that
+             * caches one token returns it again unless told which one was refused.
              *
              * @chaosity/location-client 0.8.0 and later also calls it BEFORE the
              * first send when it holds no token at all. Here that means this client
@@ -232,6 +235,9 @@ function LocationClientProvider({ children, getConfig, configKey, }) {
         // this provider would have been silently discarded.
         const client = {
             config: baseClient.config,
+            // Typed by `LocationClient` above, so callers see the core's overloads
+            // and never this signature: a literal has no overload syntax, and one
+            // generic body with the cast satisfies both (core #68).
             async send(command, options) {
                 await ready();
                 return baseClient.send(command, options);
@@ -284,10 +290,31 @@ function LocationClientProvider({ children, getConfig, configKey, }) {
                 : Promise.reject(hold.error);
         }
         log('Asking getConfig (%s)', trigger);
+        // The token the API refused, so a server that caches one can replace
+        // exactly that one (#43). Named on no other trigger, where the call
+        // stays argument-less. A `rejected` call that finds an attempt in
+        // flight joins it above and names nothing, and the next 401 names it:
+        // at the next send below core 0.12.0, and after that core's 30 s hold
+        // on the refused token from 0.12.0. The core's `refreshToken` takes no
+        // argument, so `state.token` stands for the token it sent.
+        const refused = trigger === 'rejected' ? state.token : undefined;
+        const request = refused
+            ? [{ refusedToken: refused }]
+            : [];
         const attempt = (async () => {
             let cfg;
             try {
-                cfg = await getConfigRef.current();
+                cfg = await getConfigRef.current(...request);
+                // A token route's error body passed through `res.json()` resolves
+                // too (#39). Installing it published a client for no URL, and an
+                // `error` of null, so it fails here as a rejection does.
+                const missing = !isFilled(cfg?.token)
+                    ? 'a token'
+                    : !isFilled(cfg?.apiUrl)
+                        ? 'an apiUrl'
+                        : null;
+                if (missing)
+                    throw new Error(`getConfig resolved without ${missing}`);
             }
             catch (err) {
                 if (configRef.current !== state)

package/dist/provider/LocationClientProvider.d.ts

@@ -1,5 +1,5 @@
 import type { ClientConfig, VerifyAddressResponse } from '@chaosity/location-client';
-import { type AppConfigClaims } from '@chaosity/location-client';
+import { type AppConfigClaims, GeoPlacesClient } from '@chaosity/location-client';
 import type { ReactNode } from 'react';
 /**
  * Per-request transport options.
@@ -36,7 +36,16 @@ export interface LocationClient {
     readonly config: {
         serviceId: string;
     };
-    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    /**
+     * The core's own `send`, overloads and all, not a copy of it: from core
+     * 0.13.0, `await client.send(new AutocompleteCommand(…))` is an
+     * `AutocompleteCommandOutput` with nothing to annotate (core #68). A copy
+     * of the old `send<TInput, TOutput>` kept answering `unknown`, and nothing
+     * caught it — that one signature and the core's pair of overloads are
+     * assignable to each other both ways. Below 0.13.0 it is the core's old
+     * signature, as before.
+     */
+    send: GeoPlacesClient['send'];
     /**
      * Verify a PlaceId through `POST /address/verify`: the full place record plus
      * `verified`, the one Places result an integrator may store (#26). A
@@ -86,7 +95,32 @@ interface LocationClientContextValue {
 }
 export interface LocationClientProviderProps {
     children: ReactNode;
-    getConfig: () => Promise<ClientConfig & {
+    /**
+     * Where the token and `apiUrl` come from: usually a server action returning
+     * `getClientConfig()`.
+     *
+     * After the API refuses a token before its `exp` (a revoked token, or a
+     * rotated secret), it is asked with `{ refusedToken }`, the token refused
+     * (#43). `getClientConfig()` caches one token per application, so a server
+     * that ignores this hands the refused token back, and the page stays broken
+     * until that cache comes round on its own. Ask for a new one only when the
+     * cached token IS the refused one:
+     *
+     *     return request?.refusedToken === config.token
+     *       ? getClientConfig({ forceRefresh: true })
+     *       : config
+     *
+     * That mints once per refused token, and nothing for a report of any other.
+     * It does not stop a caller echoing the token it was just handed, so a
+     * server worried about that rate-limits the call. Every other call passes
+     * nothing, and a `getConfig` that ignores the argument works as before.
+     *
+     * An answer without a non-empty `token` and `apiUrl` is taken as a failure
+     * (#39), as a rejection is.
+     */
+    getConfig: (request?: {
+        refusedToken: string;
+    }) => Promise<ClientConfig & {
         expiresAt?: number;
     }>;
     /**

package/dist/provider/LocationClientProvider.js

@@ -41,6 +41,7 @@ function retryAfterOf(err) {
         ?.retryAfterMs;
     return typeof ms === 'number' && ms > 0 ? ms : undefined;
 }
+const isFilled = (value) => typeof value === 'string' && value.length > 0;
 function overrides(trigger, hold) {
     if (trigger === 'scheduled')
         return true;
@@ -197,7 +198,9 @@ export function LocationClientProvider({ children, getConfig, configKey, }) {
              *
              * The client awaits this after a 401 and retries the request once with
              * what it returns; the same token, or nothing, means no retry, so a
-             * doomed request is never sent — or billed — twice.
+             * doomed request is never sent — or billed — twice. The `rejected`
+             * trigger names the refused token to `getConfig` (#43): a server that
+             * caches one token returns it again unless told which one was refused.
              *
              * @chaosity/location-client 0.8.0 and later also calls it BEFORE the
              * first send when it holds no token at all. Here that means this client
@@ -225,6 +228,9 @@ export function LocationClientProvider({ children, getConfig, configKey, }) {
         // this provider would have been silently discarded.
         const client = {
             config: baseClient.config,
+            // Typed by `LocationClient` above, so callers see the core's overloads
+            // and never this signature: a literal has no overload syntax, and one
+            // generic body with the cast satisfies both (core #68).
             async send(command, options) {
                 await ready();
                 return baseClient.send(command, options);
@@ -277,10 +283,31 @@ export function LocationClientProvider({ children, getConfig, configKey, }) {
                 : Promise.reject(hold.error);
         }
         log('Asking getConfig (%s)', trigger);
+        // The token the API refused, so a server that caches one can replace
+        // exactly that one (#43). Named on no other trigger, where the call
+        // stays argument-less. A `rejected` call that finds an attempt in
+        // flight joins it above and names nothing, and the next 401 names it:
+        // at the next send below core 0.12.0, and after that core's 30 s hold
+        // on the refused token from 0.12.0. The core's `refreshToken` takes no
+        // argument, so `state.token` stands for the token it sent.
+        const refused = trigger === 'rejected' ? state.token : undefined;
+        const request = refused
+            ? [{ refusedToken: refused }]
+            : [];
         const attempt = (async () => {
             let cfg;
             try {
-                cfg = await getConfigRef.current();
+                cfg = await getConfigRef.current(...request);
+                // A token route's error body passed through `res.json()` resolves
+                // too (#39). Installing it published a client for no URL, and an
+                // `error` of null, so it fails here as a rejection does.
+                const missing = !isFilled(cfg?.token)
+                    ? 'a token'
+                    : !isFilled(cfg?.apiUrl)
+                        ? 'an apiUrl'
+                        : null;
+                if (missing)
+                    throw new Error(`getConfig resolved without ${missing}`);
             }
             catch (err) {
                 if (configRef.current !== state)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -48,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@chaosity/location-client": "^0.11.0",
+    "@chaosity/location-client": "^0.13.0",
     "@eslint/js": "^10.0.1",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.0.0",