@chaosity/location-client-react 0.6.0 → 0.8.0

package/dist/provider/LocationClientProvider.d.ts

@@ -1,15 +1,22 @@
-import type { ClientConfig } from '@chaosity/location-client';
+import type { ClientConfig, VerifyAddressResponse } from '@chaosity/location-client';
 import { type AppConfigClaims } from '@chaosity/location-client';
 import type { ReactNode } from 'react';
 /**
  * Per-request transport options.
  *
- * Declared structurally rather than imported so this package builds against the
- * currently published client; it matches `SendOptions` there exactly.
+ * Declared structurally rather than imported, like `LocationClient` below. A
+ * hand copy does not move when the core does — `overallTimeoutMs` reached the
+ * core in 0.8.0 and not this copy (#26) — so `test/core-surface.test.ts` fails
+ * while the core's `SendOptions` has a key this one lacks.
  */
 export interface SendOptions {
+    /** Caller cancellation. Aborting rejects with code `AbortedException`. */
     signal?: AbortSignal;
+    /** Per ATTEMPT, not for the whole call. */
     timeoutMs?: number;
+    /** The whole call: attempts and the waits between them. Core 0.8.0+. */
+    overallTimeoutMs?: number;
+    /** `false` disables retries entirely. */
     retry?: false | {
         maxAttempts?: number;
     };
@@ -21,6 +28,9 @@ export interface SendOptions {
  * real client to refresh tokens first, and a class with private fields is not
  * structurally assignable — which is why this used to be an `Object.create`
  * prototype hack.
+ *
+ * It must carry every public member of the core client this package builds
+ * with: `test/core-surface.test.ts` fails when the core gains one (#26).
  */
 export interface LocationClient {
     readonly config: {
@@ -28,27 +38,49 @@ export interface LocationClient {
     };
     send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
     /**
-     * This application's own configuration, read from the access token —
-     * bias precision, and the countries it is scoped to (api#65).
+     * Verify a PlaceId through `POST /address/verify`: the full place record plus
+     * `verified`, the one Places result an integrator may store (#26). A
+     * `verified: false` resolves; it is not an error. Refreshes a stale token
+     * first, as `send` does.
+     *
+     * Needs @chaosity/location-client 0.10.0 or later, the peer range's floor.
+     * `send(new VerifyAddressCommand({ PlaceId }))` is the same request.
+     *
+     * Billed per call, whether or not the address verifies: call it once per
+     * chosen PlaceId, at submit.
+     */
+    verifyAddress(placeId: string, options?: SendOptions): Promise<VerifyAddressResponse>;
+    /**
+     * This application's own configuration, read from the access token
+     * (api#65). The fields are whatever the installed @chaosity/location-client
+     * reads — its `AppConfigClaims` is the list, and this passes that client's
+     * answer through unchanged. So a field the core adds appears here with no
+     * change to this package, and is absent under a core too old to read it;
+     * the peer range cannot say which.
      *
      * Here so a React app can SHOW its own settings: populate a country
      * selector with the markets it serves, label a settings screen. Being a
      * few minutes stale is cosmetic for that.
      *
-     * It is not an entitlement check, and the `countries` value must not be
-     * used to shape requests. The token is a snapshot; the API reads the scope
-     * fresh from the application row on every call. Injecting a stale scope
-     * turns a request that would have succeeded into a 400. See
+     * It is not an entitlement check, and none of it may be used to shape or
+     * refuse requests. The token is a snapshot; the API reads every setting
+     * fresh from the application on every call. Injecting a stale country
+     * scope turns a request that would have succeeded into a 400. See
      * `AppConfigClaims` in @chaosity/location-client for the measurement.
-     *
-     * Returns `{}` when the token carries no application config, which is the
-     * case until one is set in the portal.
      */
     getAppConfig(): AppConfigClaims;
 }
 interface LocationClientContextValue {
     client: LocationClient | null;
     getToken: () => string | undefined;
+    /**
+     * The API `client` talks to, from the same `getConfig` answer as the token
+     * `getToken` returns (#14). Build a map's style and tile URLs from this
+     * rather than restating the URL, so a map and its token cannot come from two
+     * different configurations. `null` until a configuration has loaded, and
+     * again while a new `configKey` loads.
+     */
+    apiUrl: string | null;
     loading: boolean;
     error: string | null;
 }
@@ -57,7 +89,20 @@ export interface LocationClientProviderProps {
     getConfig: () => Promise<ClientConfig & {
         expiresAt?: number;
     }>;
+    /**
+     * What `getConfig` answers for: an organisation or application id.
+     *
+     * Changing it drops the old configuration's token, client and `apiUrl` in
+     * the same render, and asks `getConfig` again, without remounting the
+     * children (#14). A client or a `getToken` kept from before the change
+     * refuses from then on, rather than pairing one configuration's token with
+     * the other's URL.
+     *
+     * `getConfig`'s own identity is deliberately not such a signal: it is
+     * usually an inline function, new on every render.
+     */
+    configKey?: string | number;
 }
-export declare function LocationClientProvider({ children, getConfig, }: LocationClientProviderProps): import("react").JSX.Element;
+export declare function LocationClientProvider({ children, getConfig, configKey, }: LocationClientProviderProps): import("react").JSX.Element;
 export declare function useLocationClient(): LocationClientContextValue;
 export {};