@chaosity/location-client 0.5.1 → 0.7.0

package/dist/cjs/maps/staticMap.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staticMapAccept = staticMapAccept;
+exports.buildStaticMapUrl = buildStaticMapUrl;
+exports.fetchStaticMap = fetchStaticMap;
+const errors_js_1 = require("../transport/errors.js");
+/**
+ * The Accept header this request must send.
+ *
+ * Exported because it is the one rule a caller cannot guess, and anyone doing
+ * their own fetch — a server-side render, a proxy — needs it too. Satellite is
+ * the default, so an absent style means JPEG.
+ */
+function staticMapAccept(style) {
+    return style === 'Standard' ? 'image/png' : 'image/jpeg';
+}
+/** A coordinate as the API accepts it: at most six decimals, no float noise. */
+const coord = (n) => String(Number(n.toFixed(6)));
+/** Build the request URL without fetching it. */
+function buildStaticMapUrl(apiUrl, options) {
+    const { width, height, center, boundingBox, boundedPositions, fileName = 'map', ...rest } = options;
+    const params = new URLSearchParams({
+        width: String(width),
+        height: String(height),
+    });
+    // Positions go over the wire as comma-separated numbers. api#35 records that
+    // passing arrays straight through worked only by accidental stringification;
+    // doing it explicitly here means the shape is ours, not JavaScript's default.
+    //
+    // Each number is rounded to six decimals (#29). The API caps a coordinate at
+    // fourteen decimals, and a value straight from `map.getCenter()` routinely
+    // has fifteen or sixteen — so the obvious "render what the user is looking
+    // at" was a 400 blaming the FORMAT. Six decimals is ~10 cm, more than a
+    // raster render can show.
+    if (center)
+        params.set('center', center.map(coord).join(','));
+    if (boundingBox)
+        params.set('bounding-box', boundingBox.map(coord).join(','));
+    if (boundedPositions) {
+        params.set('bounded-positions', boundedPositions.flat().map(coord).join(','));
+    }
+    // The API accepts kebab-case on the wire and camelCase for older callers;
+    // kebab is the documented form, so emit that.
+    const KEBAB = { cropLabels: 'crop-labels' };
+    for (const [key, value] of Object.entries(rest)) {
+        if (value === undefined)
+            continue;
+        params.set(KEBAB[key] ?? key, String(value));
+    }
+    return `${apiUrl}/maps/static/${fileName}?${params}`;
+}
+/**
+ * Fetch a static map as a Blob.
+ *
+ * @param apiUrl   Base URL of the Location Service API
+ * @param options  Render options; exactly one of center / boundingBox / boundedPositions
+ * @param getToken Callback returning the current auth token
+ *
+ * @example
+ * const blob = await fetchStaticMap(API_URL, {
+ *   width: 640, height: 400, center: [151.2093, -33.8688], zoom: 14,
+ *   style: 'Standard',
+ * }, getToken)
+ * const url = URL.createObjectURL(blob)   // remember to revokeObjectURL
+ */
+async function fetchStaticMap(apiUrl, options, getToken) {
+    const response = await fetch(buildStaticMapUrl(apiUrl, options), {
+        headers: {
+            Authorization: `Bearer ${getToken()}`,
+            Accept: staticMapAccept(options.style),
+        },
+    });
+    if (!response.ok) {
+        // Same treatment as fetchMapStyle: the API's {message, code, requestId} is
+        // the useful part, and a bare "failed: 400" throws it away. The messages
+        // here are specific and actionable -- "'width' and 'height' are required",
+        // "Only one of center, bounding-box or bounded-positions may be set".
+        throw (0, errors_js_1.parseErrorResponse)(response.status, response.statusText, await response.text());
+    }
+    return response.blob();
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/server/LocationServiceConnector.d.ts

@@ -0,0 +1,104 @@
+import type { RequestOptions } from '../transport/http.js';
+import type { AppConfigClaims } from '../utils/tokenClaims.js';
+export interface ConnectorConfig {
+    /** Falls back to `LOCATION_API_URL` / `LOCATION_SERVICE_API_URL`. */
+    apiUrl?: string;
+    /**
+     * A fixed token. Nothing can refresh it, so it dies at its own `exp` — pass
+     * `getToken` instead, or nothing at all, for a connector that keeps working.
+     */
+    token?: string;
+    /**
+     * Where a token comes from. Called for every request, so this is what makes
+     * a long-lived connector survive expiry.
+     *
+     * `forceRefresh` is passed as `true` when the API has just rejected the token
+     * this returned — the signature is `TokenProvider.getToken`'s exactly, so
+     * `getToken: (f) => provider.getToken(f)` is a complete implementation.
+     */
+    getToken?: (forceRefresh?: boolean) => Promise<string | {
+        token?: string;
+    } | undefined>;
+    /** Falls back to `LOCATION_CLIENT_ID` / `LOCATION_SERVICE_CLIENT_ID`. */
+    clientId?: string;
+    /** Falls back to `LOCATION_CLIENT_SECRET` / `LOCATION_SERVICE_CLIENT_SECRET`. */
+    clientSecret?: string;
+    /**
+     * Sent as the `Origin` header on every request. The API requires an Origin it
+     * recognises on every data request and answers 403 without one, so every
+     * caller was setting it by hand on each `send`; this does it once.
+     *
+     * Falls back to `LOCATION_ORIGIN` / `LOCATION_SERVICE_ORIGIN`, so the
+     * zero-argument connector can be made to work from the environment alone.
+     */
+    origin?: string;
+}
+export interface SendOptions extends RequestOptions {
+    headers?: Record<string, string>;
+}
+/**
+ * LocationServiceConnector — server-side connector for the Location Service API.
+ *
+ * Backend-to-backend: automatic configuration from the environment, server-side
+ * token management, and the same transport (timeout, cancellation, retry) as the
+ * browser client.
+ *
+ * Configuration is COMPLETED from the environment rather than replaced by it.
+ * The constructor used to be all-or-nothing — any argument at all took the
+ * "caller supplies everything" branch — so `new LocationServiceConnector()` had
+ * credentials but could never send an Origin (403 on every data request) and
+ * `new LocationServiceConnector({ origin })` had an Origin but no credentials
+ * (#45). Now an explicit `token`/`getToken` still wins outright, and anything
+ * short of that is filled in from `LOCATION_API_URL` / `LOCATION_CLIENT_ID` /
+ * `LOCATION_CLIENT_SECRET` / `LOCATION_ORIGIN`.
+ *
+ * @example
+ * ```typescript
+ * // Credentials and apiUrl from the environment, Origin supplied here
+ * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
+ * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
+ * ```
+ */
+export declare class LocationServiceConnector {
+    private readonly config;
+    private tokenSource?;
+    private readonly origin?;
+    readonly serviceId: string;
+    constructor(config?: ConnectorConfig);
+    /**
+     * One place that knows how a token is obtained, so nothing can drift.
+     *
+     * Built on first use rather than in the constructor: resolving the
+     * environment path used to start a `/auth/token` round trip from `new`, whose
+     * rejection nothing was awaiting yet — an unhandled rejection for a
+     * misconfigured process, before it had made a single request.
+     */
+    private source;
+    private buildSource;
+    /**
+     * This application's own configuration, as carried on the access token
+     * (api#65) — bias precision, and the countries it is scoped to.
+     *
+     * Provided so an application can SHOW its own settings: populate a country
+     * selector with the markets it actually serves, label a settings screen, and
+     * so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    getAppConfig(): Promise<AppConfigClaims>;
+    /**
+     * The Origin this request will actually carry.
+     *
+     * ONE definition, for the two readers that must never disagree about it: the
+     * header merge in `dispatch`, and the 403 explanation in `send`. A per-call
+     * header beats the connector default, whatever the caller capitalised.
+     */
+    private effectiveOrigin;
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+    private dispatchWithRetry;
+    private dispatch;
+}

package/dist/cjs/server/LocationServiceConnector.js

@@ -0,0 +1,270 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocationServiceConnector = void 0;
+const debug_1 = __importDefault(require("debug"));
+const LocationServiceException_js_1 = require("../errors/LocationServiceException.js");
+const endpoints_js_1 = require("../transport/endpoints.js");
+const errors_js_1 = require("../transport/errors.js");
+const http_js_1 = require("../transport/http.js");
+const roundPosition_js_1 = require("../utils/roundPosition.js");
+const tokenClaims_js_1 = require("../utils/tokenClaims.js");
+const getClientConfig_js_1 = require("./getClientConfig.js");
+const log = (0, debug_1.default)('location-client:connector');
+/** Header lookup that does not care how the caller capitalised the name. */
+function headerValue(headers, name) {
+    if (!headers)
+        return undefined;
+    const wanted = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === wanted)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * The headers `dispatch` sets itself, and which a caller therefore cannot
+ * supply. Lower-case, because that is how they are compared.
+ *
+ * Kept beside `withoutHeaders` so the list and the record in `dispatch` cannot
+ * drift apart: a header added there must be added here too, or the caller's own
+ * spelling of it survives the merge.
+ */
+const SYSTEM_HEADERS = ['origin', 'content-type', 'authorization'];
+/** The caller's headers minus `names`, however they capitalised them. */
+function withoutHeaders(headers, names) {
+    if (!headers)
+        return {};
+    const wanted = new Set(names);
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => !wanted.has(key.toLowerCase())));
+}
+/**
+ * Say why the 403 happened, when we know.
+ *
+ * `Origin not allowed` with no Origin sent is not an ambiguous failure — it is
+ * the documented backend path missing one piece of configuration (#45), and the
+ * API's own message cannot say so because from its side the header is simply
+ * absent. A new integrator following the README hit a bare "Origin not allowed"
+ * that named neither the cause nor the fix.
+ */
+function explainMissingOrigin(err, sentOrigin) {
+    if (sentOrigin)
+        return err;
+    if (!(err instanceof LocationServiceException_js_1.LocationServiceException))
+        return err;
+    if (err.code !== 'OriginNotAllowedException')
+        return err;
+    return new LocationServiceException_js_1.LocationServiceException({
+        code: err.code,
+        message: `${err.message} — this request carried no Origin header, and the API requires ` +
+            `one it recognises on every data request. Set \`origin\` on the ` +
+            `LocationServiceConnector, set LOCATION_ORIGIN, or pass an Origin in the ` +
+            `per-call headers; if the application has no allowed domain configured in ` +
+            `the developer portal yet, set that first.`,
+        statusCode: err.statusCode,
+        requestId: err.requestId,
+        details: err.details,
+        cause: err,
+    });
+}
+/**
+ * LocationServiceConnector — server-side connector for the Location Service API.
+ *
+ * Backend-to-backend: automatic configuration from the environment, server-side
+ * token management, and the same transport (timeout, cancellation, retry) as the
+ * browser client.
+ *
+ * Configuration is COMPLETED from the environment rather than replaced by it.
+ * The constructor used to be all-or-nothing — any argument at all took the
+ * "caller supplies everything" branch — so `new LocationServiceConnector()` had
+ * credentials but could never send an Origin (403 on every data request) and
+ * `new LocationServiceConnector({ origin })` had an Origin but no credentials
+ * (#45). Now an explicit `token`/`getToken` still wins outright, and anything
+ * short of that is filled in from `LOCATION_API_URL` / `LOCATION_CLIENT_ID` /
+ * `LOCATION_CLIENT_SECRET` / `LOCATION_ORIGIN`.
+ *
+ * @example
+ * ```typescript
+ * // Credentials and apiUrl from the environment, Origin supplied here
+ * const connector = new LocationServiceConnector({ origin: 'https://app.example.com' })
+ * const result = await connector.send(new SearchTextCommand({ QueryText: 'Space Needle' }))
+ * ```
+ */
+class LocationServiceConnector {
+    constructor(config = {}) {
+        this.serviceId = 'Geo Places';
+        this.config = config;
+        // `||`, not `??`, to match the other four env-completed fields: an empty
+        // string is not a choice to send no Origin, it is a missing value, and the
+        // asymmetry meant `origin: ''` suppressed the environment and then produced
+        // an error telling the caller to set a variable they may already have set.
+        this.origin =
+            config.origin ||
+                process.env.LOCATION_ORIGIN ||
+                process.env.LOCATION_SERVICE_ORIGIN;
+    }
+    /**
+     * One place that knows how a token is obtained, so nothing can drift.
+     *
+     * Built on first use rather than in the constructor: resolving the
+     * environment path used to start a `/auth/token` round trip from `new`, whose
+     * rejection nothing was awaiting yet — an unhandled rejection for a
+     * misconfigured process, before it had made a single request.
+     */
+    source() {
+        return (this.tokenSource ?? (this.tokenSource = this.buildSource()));
+    }
+    buildSource() {
+        const { apiUrl, token, getToken, clientId, clientSecret } = this.config;
+        // An explicit token source wins outright. A caller that supplied one is
+        // managing credentials itself, and quietly reading the environment
+        // underneath it could send another application's token.
+        if (getToken) {
+            return {
+                apiUrl: () => requireApiUrl(apiUrl),
+                get: async (forceRefresh) => {
+                    const result = await getToken(forceRefresh);
+                    if (!result)
+                        return undefined;
+                    return typeof result === 'string' ? result : result.token;
+                },
+            };
+        }
+        if (token) {
+            return {
+                apiUrl: () => requireApiUrl(apiUrl),
+                // A fixed string. Asking again returns the same one, which is how the
+                // retry guard knows there is nothing to retry with.
+                get: async () => token,
+            };
+        }
+        // Nothing but (at most) an apiUrl and an origin — complete it from the
+        // environment. This is the branch every sample and doc actually takes.
+        const env = (0, getClientConfig_js_1.serverTokenSource)({ apiUrl, clientId, clientSecret });
+        return {
+            // Already validated by serverTokenSource, which cannot resolve
+            // credentials without it.
+            apiUrl: () => env.apiUrl,
+            get: async (forceRefresh) => (await env.getToken(forceRefresh)).token,
+        };
+    }
+    /**
+     * This application's own configuration, as carried on the access token
+     * (api#65) — bias precision, and the countries it is scoped to.
+     *
+     * Provided so an application can SHOW its own settings: populate a country
+     * selector with the markets it actually serves, label a settings screen, and
+     * so on. Being a few minutes stale is cosmetic for that.
+     *
+     * It is not an entitlement check. See AppConfigClaims for why acting on
+     * `countries` client-side makes requests fail that would otherwise succeed.
+     *
+     * Returns `{}` when the token carries no application config, which is the
+     * case until one is configured in the portal.
+     */
+    async getAppConfig() {
+        return (0, tokenClaims_js_1.readAppConfigClaims)(await this.source().get());
+    }
+    /**
+     * The Origin this request will actually carry.
+     *
+     * ONE definition, for the two readers that must never disagree about it: the
+     * header merge in `dispatch`, and the 403 explanation in `send`. A per-call
+     * header beats the connector default, whatever the caller capitalised.
+     */
+    effectiveOrigin(options) {
+        // `||` for the same reason as the constructor: an empty per-call header is
+        // a missing value, not a decision to send no Origin.
+        return headerValue(options?.headers, 'origin') || this.origin;
+    }
+    async send(command, options) {
+        const source = this.source();
+        const cmd = command;
+        const url = `${source.apiUrl()}${(0, endpoints_js_1.resolveEndpoint)(cmd)}`;
+        try {
+            return await this.dispatchWithRetry(source, url, cmd, options);
+        }
+        catch (err) {
+            throw explainMissingOrigin(err, this.effectiveOrigin(options));
+        }
+    }
+    async dispatchWithRetry(source, url, cmd, options) {
+        const token = await source.get();
+        if (!token)
+            throw noTokenAvailable();
+        try {
+            return await this.dispatch(url, token, cmd, options);
+        }
+        catch (err) {
+            if (!(0, errors_js_1.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, and
+            // a second billed one.
+            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');
+            return await this.dispatch(url, fresh, cmd, options);
+        }
+    }
+    dispatch(url, token, cmd, options) {
+        // The token is resolved before the request is shaped, so the precision this
+        // application is entitled to is available (api#65). Absent claim -> the
+        // 3 dp floor, which is what every application gets until one is configured
+        // otherwise. Recomputed per attempt because a refreshed token may carry
+        // different claims.
+        const { biasDecimals } = (0, tokenClaims_js_1.readAppConfigClaims)(token);
+        const input = (0, roundPosition_js_1.roundPositionFields)(cmd.input, biasDecimals);
+        // Every system header is set exactly ONCE, and the caller's own spelling of
+        // each is dropped first.
+        //
+        // Spreading them over the caller's record is not enough, because fetch's
+        // Headers fill APPENDS rather than replaces: a caller's lowercase key
+        // survives beside the canonical one and both go on the wire. For Origin
+        // that produced `Origin: default, per-call`, which the API's exact-match
+        // domain check rejects (observed: 403 OriginNotAllowedException) — and two
+        // keys with the SAME value fared no better, `Origin: x, x`. For
+        // Authorization it is worse than a failed override: `{ authorization:
+        // 'Bearer not-yours' }` went out as `Bearer not-yours, Bearer <real>`,
+        // corrupting the token rather than being ignored by it.
+        //
+        // Origin's value comes from `effectiveOrigin`, so a per-call header still
+        // beats the connector default — it is the DUPLICATE that is removed, not
+        // the caller's intent.
+        const origin = this.effectiveOrigin(options);
+        const headers = {
+            ...withoutHeaders(options?.headers, SYSTEM_HEADERS),
+            ...(origin ? { Origin: origin } : {}),
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        };
+        log('Sending %s request to %s', cmd.constructor?.name, url);
+        return (0, http_js_1.requestJson)(url, { method: 'POST', headers, body: JSON.stringify(input) }, options);
+    }
+}
+exports.LocationServiceConnector = LocationServiceConnector;
+function requireApiUrl(explicit) {
+    const apiUrl = (0, getClientConfig_js_1.resolveApiUrl)(explicit);
+    if (!apiUrl) {
+        throw new LocationServiceException_js_1.LocationServiceException({
+            code: 'ValidationException',
+            message: 'No API URL. Pass `apiUrl` to the LocationServiceConnector constructor ' +
+                'or set LOCATION_API_URL.',
+            details: { source: 'client' },
+        });
+    }
+    return apiUrl;
+}
+function noTokenAvailable() {
+    return new LocationServiceException_js_1.LocationServiceException({
+        code: 'InvalidCredentialsException',
+        message: 'No token available — check clientId/clientSecret configuration',
+        details: { source: 'client' },
+    });
+}

package/dist/cjs/server/getClientConfig.d.ts

@@ -0,0 +1,94 @@
+import type { TokenResponse } from '../auth/TokenProvider.js';
+import type { ClientConfig } from '../types/index.js';
+export interface ServerAuthConfig {
+    apiUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+    /**
+     * Mint a new token instead of returning the cached one.
+     *
+     * For the case the cache cannot see: a token the API has stopped accepting
+     * before its `exp` — revoked in the portal, or issued against a secret that
+     * has since been rotated. `TokenProvider` judges freshness from `exp` alone,
+     * so without this a caller holding a dead token waits out its whole lifetime.
+     */
+    forceRefresh?: boolean;
+}
+export interface ServerClientConfig extends ClientConfig {
+    expiresAt?: number;
+}
+/**
+ * Where the API lives, from the argument or the environment.
+ *
+ * Separate from the credentials because the two are independently overridable:
+ * a caller can hand `LocationServiceConnector` its own `token` and still expect
+ * `LOCATION_API_URL` to say where to send it.
+ */
+export declare function resolveApiUrl(explicit?: string): string | undefined;
+/**
+ * A LIVE token source: resolved credentials plus a `getToken` that re-mints
+ * when the cached token is spent.
+ *
+ * This is the seam `getClientConfig` and `LocationServiceConnector` share, and
+ * it exists because the two need different SHAPES of the same thing.
+ * `getClientConfig` has to return plain data — see the warning on its return
+ * value — so it can only ever hand back a snapshot. The connector is long-lived
+ * and needs the source itself, or it dies at the first `exp` (#36).
+ *
+ * Deliberately not exported from `./server`: it hands out a callable bound to
+ * the process-wide provider, and the public surface stays the two functions
+ * that were already there.
+ */
+export interface ServerTokenSource {
+    apiUrl: string;
+    /** Resolves with a token or rejects; it never resolves tokenless. */
+    getToken(forceRefresh?: boolean): Promise<TokenResponse & {
+        token: string;
+    }>;
+}
+export declare function serverTokenSource(config?: ServerAuthConfig): ServerTokenSource;
+/**
+ * Get client configuration with OAuth2 authentication.
+ *
+ * Automatically reads from environment variables:
+ * - LOCATION_API_URL or LOCATION_SERVICE_API_URL
+ * - LOCATION_CLIENT_ID or LOCATION_SERVICE_CLIENT_ID
+ * - LOCATION_CLIENT_SECRET or LOCATION_SERVICE_CLIENT_SECRET
+ *
+ * You can override any value by passing it explicitly.
+ *
+ * WARNING: This function uses client credentials (clientId/clientSecret).
+ * Only call this from:
+ * - Next.js Server Components/Actions
+ * - Node.js backend servers
+ * - API routes
+ *
+ * NEVER call from browser/client code as it exposes credentials.
+ * For SPA projects, create your own backend endpoint that calls this.
+ *
+ * ## The return value is PLAIN DATA, and has to stay that way
+ *
+ * `{ apiUrl, token, expiresAt }` — no methods, no closures. The reason is not
+ * style: the shape every sample uses is a Next.js Server Action that returns
+ * this straight to a Client Component (every `src/lib/actions/location.ts`
+ * under `location-service-samples/web`), and the RSC boundary
+ * serialises it. A function on this object is not serialisable and throws at
+ * the boundary, so "make getClientConfig return getToken" — which #36 proposed
+ * and this JSDoc used to promise two lines below — would break every Next.js
+ * consumer of the library.
+ *
+ * A caller that needs a token which REFRESHES wants one of:
+ * - `LocationServiceConnector`, which holds a live source internally (#36), or
+ * - `TokenProvider` directly, if it is managing its own lifecycle.
+ *
+ * @example
+ * // Auto-detect from environment
+ * const config = await getClientConfig()
+ *
+ * // Or override specific values
+ * const config = await getClientConfig({ apiUrl: 'https://custom.api.com' })
+ *
+ * // The API rejected the token before its exp — revoked, or secret rotated
+ * const fresh = await getClientConfig({ forceRefresh: true })
+ */
+export declare function getClientConfig(config?: ServerAuthConfig): Promise<ServerClientConfig>;