@tileflow/react 0.1.0-alpha.17 → 0.1.0-alpha.18

package/README.md

@@ -38,7 +38,7 @@ manifest:
 Or bypass the manifest and load a hosted style directly:
 
 ```tsx
-<Map styleUrl="https://api.tileflow.dev/v1/styles/acme/madrid.json" />
+<Map styleUrl="https://api.tileflow.dev/maps/map_1234567890abcdef/style.json" />
 ```
 
 For simple hosted static images, use image mode:
@@ -55,6 +55,35 @@ the production image behavior locally.
 For full static scenes with bounds, overlays, and server-side precache, use
 `StaticMap` from `@tileflow/react/static` or helpers from `@tileflow/static`.
 
+```tsx
+import {StaticMap} from '@tileflow/react/static';
+import {useState} from 'react';
+import {createStaticMapIdempotencyKey} from '@tileflow/static';
+
+export function Preview() {
+  const [idempotencyKey] = useState(createStaticMapIdempotencyKey);
+
+  return (
+    <StaticMap
+      map="madrid"
+      camera={{type: 'center', center: [-3.7038, 40.4168], zoom: 12}}
+      size={{width: 1200, height: 800}}
+      createUrl="/api/static-maps"
+      idempotencyKey={idempotencyKey}
+    />
+  );
+}
+```
+
+`idempotencyKey` is required in create mode. Keep one key for one intentional create action and
+reuse it across retries and remounts. Concurrent React consumers share work only when URL,
+normalized scene, and idempotency key all identify the same operation; unmounting the final
+consumer aborts its in-flight request.
+
+Hosted interactive maps automatically preflight a short-lived commercial session grant before
+eligible resources. Setting `analytics={{enabled: false}}` disables the optional beacon only; it
+does not remove hosted authorization or override a user `mapOptions.transformRequest` callback.
+
 ## Headless capture readiness
 
 Use `captureId` to disambiguate multiple maps with the same configured name:

package/dist/index.js

@@ -10,7 +10,7 @@ import {
 } from "react";
 import maplibregl from "maplibre-gl";
 import {
-  createTileflowSessionId,
+  createTileflowSessionController,
   defaultTileflowManifestUrl,
   loadTileflowManifest,
   mergeTileflowAnalytics,
@@ -72,11 +72,6 @@ function Map({
   const mapNameRef = useRef(mapName);
   const resolvedAnalyticsRef = useRef(void 0);
   const readinessRunRef = useRef(0);
-  const sessionId = useMemo(() => createTileflowSessionId(), []);
-  const sessionStarter = useMemo(
-    () => createTileflowSessionStarter({ sessionId, source: "react" }),
-    [sessionId]
-  );
   const markerController = useMemo(
     () => createTileflowMarkerController({
       attach(markerInstance, map, marker) {
@@ -188,16 +183,6 @@ function Map({
     }) : void 0),
     [imageSize, imageUrl, isImageMode, manifestMap, resolvedZoom, staticImageCenter]
   );
-  const transformRequest = useMemo(
-    () => createTileflowTransformRequest({
-      always: true,
-      asyncAnalyticsTiming: "resolution",
-      getAnalytics: () => resolvedAnalyticsRef.current,
-      sessionId,
-      transformRequest: stableMapOptions?.transformRequest ?? void 0
-    }),
-    [sessionId, stableMapOptions?.transformRequest]
-  );
   useEffect(() => {
     if (!isImageMode || imageUrl || !containerRef.current) {
       setImageSize(null);
@@ -226,6 +211,20 @@ function Map({
     }
     readinessRunRef.current += 1;
     setCaptureState("loading");
+    const session = createTileflowSessionController({ source: "react" });
+    const sessionStarter = createTileflowSessionStarter({
+      getSessionId: () => session.sessionId,
+      sessionId: session.sessionId,
+      source: "react"
+    });
+    const transformRequest = createTileflowTransformRequest({
+      always: true,
+      asyncAnalyticsTiming: "resolution",
+      getAnalytics: () => resolvedAnalyticsRef.current,
+      sessionController: session,
+      sessionId: session.sessionId,
+      transformRequest: stableMapOptions?.transformRequest ?? void 0
+    });
     const map = new maplibregl.Map({
       ...stableMapOptions,
       container: containerRef.current,
@@ -288,14 +287,7 @@ function Map({
         }
       }
     };
-  }, [
-    markerController,
-    resolvedInteractive,
-    runtimeStyle,
-    sessionStarter,
-    stableMapOptions,
-    transformRequest
-  ]);
+  }, [markerController, resolvedInteractive, runtimeStyle, stableMapOptions]);
   useLayoutEffect(() => {
     if (!isImageMode) return;
     readinessRunRef.current += 1;

package/dist/static.d.ts

@@ -16,13 +16,15 @@ type StaticMapBaseProps = StaticSceneInput & {
 };
 type StaticMapImageProps = {
     createUrl?: never;
+    idempotencyKey?: never;
     imageUrl: string;
 };
 type StaticMapCreateProps = {
     createUrl: string;
+    idempotencyKey: string;
     imageUrl?: never;
 };
 type StaticMapProps = StaticMapBaseProps & (StaticMapCreateProps | StaticMapImageProps);
-declare function StaticMap({ alt, camera, className, captureId, createUrl, imageStyle, imageUrl, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, }: StaticMapProps): react.JSX.Element;
+declare function StaticMap({ alt, camera, className, captureId, createUrl, imageStyle, imageUrl, idempotencyKey, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, }: StaticMapProps): react.JSX.Element;
 
 export { StaticMap, type StaticMapProps };

package/dist/static.js

@@ -9,8 +9,181 @@ import {
   useState
 } from "react";
 import { normalizeTileflowCaptureId } from "@tileflow/core";
-import { jsx } from "react/jsx-runtime";
+import {
+  validateStaticMapIdempotencyKey
+} from "@tileflow/static";
+
+// src/static-map-request.ts
+import {
+  staticMapProcessingResultSchema,
+  staticMapReadyResultSchema
+} from "@tileflow/static";
 var inFlightRequests = /* @__PURE__ */ new Map();
+function createStaticMapRequestKey(input) {
+  return stableStringify(input);
+}
+async function resolveStaticMap(input) {
+  throwIfAborted(input.signal);
+  let entry = inFlightRequests.get(input.requestKey);
+  if (!entry) {
+    const controller = new AbortController();
+    const promise = requestStaticMapUntilReady({ ...input, signal: controller.signal });
+    const created = {
+      controller,
+      consumers: 0,
+      promise,
+      settled: false
+    };
+    const settle = () => {
+      created.settled = true;
+      if (inFlightRequests.get(input.requestKey) === created) {
+        inFlightRequests.delete(input.requestKey);
+      }
+    };
+    void promise.then(settle, settle);
+    inFlightRequests.set(input.requestKey, created);
+    entry = created;
+  }
+  entry.consumers += 1;
+  try {
+    return await raceWithAbort(entry.promise, input.signal);
+  } finally {
+    entry.consumers -= 1;
+    if (entry.consumers === 0 && !entry.settled) {
+      if (inFlightRequests.get(input.requestKey) === entry) {
+        inFlightRequests.delete(input.requestKey);
+      }
+      entry.controller.abort();
+    }
+  }
+}
+async function requestStaticMapUntilReady(input) {
+  const maxWaitMs = input.maxWaitMs ?? 3e4;
+  if (!Number.isSafeInteger(maxWaitMs) || maxWaitMs < 1 || maxWaitMs > 12e4) {
+    throw new Error("Static map maxWaitMs must be an integer from 1 to 120000");
+  }
+  return runWithinBudget(maxWaitMs, input.signal, async (signal) => {
+    const body = JSON.stringify(input.scene);
+    const fetcher = input.fetch ?? fetch;
+    let operationId = null;
+    while (true) {
+      const response = await fetcher(input.createUrl, {
+        body,
+        headers: {
+          "Content-Type": "application/json",
+          "Idempotency-Key": input.idempotencyKey
+        },
+        method: "POST",
+        signal
+      });
+      throwIfAborted(signal);
+      if (!response.ok) throw new Error(`Static map endpoint failed: ${response.status}`);
+      let value;
+      try {
+        value = await response.json();
+      } catch {
+        throw new Error("Static map endpoint returned invalid JSON");
+      }
+      throwIfAborted(signal);
+      if (response.status !== 202) {
+        const ready = staticMapReadyResultSchema.safeParse(value);
+        if (!ready.success) throw new Error("Static map endpoint returned an invalid response");
+        assertStaticMapOperationIdentity(operationId, ready.data.operationId);
+        return ready.data;
+      }
+      const pending = staticMapProcessingResultSchema.safeParse(value);
+      if (!pending.success) throw new Error("Static map endpoint returned an invalid response");
+      assertStaticMapOperationIdentity(operationId, pending.data.operationId);
+      operationId ??= pending.data.operationId;
+      await delay(pending.data.retryAfterMs, signal);
+    }
+  });
+}
+function stableStringify(value) {
+  return JSON.stringify(sortJson(value));
+}
+function assertStaticMapOperationIdentity(expected, actual) {
+  if (expected !== null && actual !== expected) {
+    throw new Error("Static map endpoint changed operation identity while polling");
+  }
+}
+async function runWithinBudget(maxWaitMs, externalSignal, operation) {
+  const controller = new AbortController();
+  const timeoutError = new Error(`Static map request timed out after ${maxWaitMs}ms`);
+  const abortFromConsumer = () => controller.abort(externalSignal?.reason);
+  if (externalSignal?.aborted) abortFromConsumer();
+  else externalSignal?.addEventListener("abort", abortFromConsumer, { once: true });
+  const timeout = setTimeout(() => controller.abort(timeoutError), maxWaitMs);
+  try {
+    throwIfAborted(controller.signal);
+    const pending = operation(controller.signal);
+    return await raceWithAbort(pending, controller.signal);
+  } finally {
+    clearTimeout(timeout);
+    externalSignal?.removeEventListener("abort", abortFromConsumer);
+  }
+}
+function delay(milliseconds, signal) {
+  if (milliseconds === 0) {
+    throwIfAborted(signal);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, milliseconds);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(abortReason(signal));
+    };
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function raceWithAbort(operation, signal) {
+  if (!signal) return operation;
+  if (signal.aborted) return Promise.reject(abortReason(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(abortReason(signal));
+    };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      }
+    );
+  });
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortReason(signal);
+}
+function abortReason(signal) {
+  if (signal.reason instanceof Error) return signal.reason;
+  const error = new Error("Static map request was aborted");
+  error.name = "AbortError";
+  return error;
+}
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, sortJson(entry)])
+    );
+  }
+  return value;
+}
+
+// src/static-map.tsx
+import { jsx } from "react/jsx-runtime";
 function StaticMap({
   alt = "",
   camera,
@@ -19,6 +192,7 @@ function StaticMap({
   createUrl,
   imageStyle,
   imageUrl,
+  idempotencyKey,
   keepPreviousImage = false,
   loading = "lazy",
   map,
@@ -43,7 +217,7 @@ function StaticMap({
     () => stableStringify({ camera, map, overlays, size }),
     [camera, map, overlays, size]
   );
-  const requestKey = imageUrl ? `image:${imageUrl}` : `create:${createUrl}:${sceneKey}`;
+  const intentKey = imageUrl ? `image:${imageUrl}` : `create:${createUrl}:${idempotencyKey ?? ""}:${sceneKey}`;
   useLayoutEffect(() => {
     imageLoadRunRef.current += 1;
     setCaptureState("loading");
@@ -52,7 +226,7 @@ function StaticMap({
       if (image.naturalWidth === 0) setCaptureState("error");
       else void markImageReady(image);
     }
-  }, [requestKey]);
+  }, [intentKey]);
   async function markImageReady(image) {
     const runId = ++imageLoadRunRef.current;
     try {
@@ -81,14 +255,31 @@ function StaticMap({
     if (!createUrl) {
       return;
     }
+    const validation = validateStaticMapIdempotencyKey(idempotencyKey ?? "");
+    if (!validation.ok) {
+      const keyError = new Error(`Invalid Static Maps idempotency key: ${validation.error}`);
+      if (!keepPreviousImage) setResult(null);
+      setError(keyError);
+      imageLoadRunRef.current += 1;
+      setCaptureState("error");
+      onErrorRef.current?.(keyError);
+      return;
+    }
     if (!keepPreviousImage) {
       setResult(null);
     }
     setError(null);
+    const requestController = new AbortController();
     resolveStaticMap({
       createUrl,
-      requestKey,
-      scene: JSON.parse(sceneKey)
+      idempotencyKey: validation.key,
+      requestKey: createStaticMapRequestKey({
+        createUrl,
+        idempotencyKey: validation.key,
+        sceneKey
+      }),
+      scene: JSON.parse(sceneKey),
+      signal: requestController.signal
     }).then((nextResult) => {
       if (cancelled) {
         return;
@@ -111,8 +302,9 @@ function StaticMap({
     });
     return () => {
       cancelled = true;
+      requestController.abort();
     };
-  }, [createUrl, imageUrl, keepPreviousImage, requestKey, sceneKey]);
+  }, [createUrl, idempotencyKey, imageUrl, intentKey, keepPreviousImage, sceneKey]);
   return /* @__PURE__ */ jsx(
     "div",
     {
@@ -159,50 +351,17 @@ function StaticMap({
     }
   );
 }
-async function resolveStaticMap(input) {
-  const existing = inFlightRequests.get(input.requestKey);
-  if (existing) {
-    return existing;
-  }
-  const promise = fetch(input.createUrl, {
-    body: JSON.stringify(input.scene),
-    headers: {
-      "Content-Type": "application/json"
-    },
-    method: "POST"
-  }).then(async (response) => {
-    if (!response.ok) {
-      throw new Error(`Static map endpoint failed: ${response.status}`);
-    }
-    return await response.json();
-  }).finally(() => {
-    inFlightRequests.delete(input.requestKey);
-  });
-  inFlightRequests.set(input.requestKey, promise);
-  return promise;
-}
 function imageResult(imageUrl) {
   return {
     cached: true,
     hash: "",
     imageUrl,
-    status: "ready"
+    operationId: null,
+    remainingUnits: null,
+    status: "ready",
+    unitCost: 0
   };
 }
-function stableStringify(value) {
-  return JSON.stringify(sortJson(value));
-}
-function sortJson(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJson);
-  }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, sortJson(entry)])
-    );
-  }
-  return value;
-}
 export {
   StaticMap
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "description": "React components for rendering Tileflow maps with MapLibre.",
   "type": "module",
   "sideEffects": false,
@@ -41,8 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.17 <0.1.0-beta.0",
-    "@tileflow/static": ">=0.1.0-alpha.16 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.18 <0.1.0-beta.0",
+    "@tileflow/static": ">=0.1.0-alpha.17 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5",