@tileflow/static 0.1.0-alpha.14 → 0.1.0-alpha.17

package/README.md

@@ -3,7 +3,12 @@
 Static map schemas, overlay helpers, and request utilities for Tileflow static map rendering.
 
 ```ts
-import {marker, precacheStaticMap, validateStaticScene} from '@tileflow/static';
+import {
+  createStaticMapIdempotencyKey,
+  marker,
+  precacheStaticMap,
+  validateStaticScene,
+} from '@tileflow/static';
 
 const scene = validateStaticScene({
   map: 'madrid',
@@ -14,7 +19,22 @@ const scene = validateStaticScene({
 
 await precacheStaticMap(scene.scene, {
   apiKey: process.env.TILEFLOW_API_KEY,
+  idempotencyKey: createStaticMapIdempotencyKey(),
 });
 ```
 
+Create one idempotency key per intentional create/precache action and retain it across network
+retries. Reusing the key with the same normalized scene returns the stored result; reusing it with a
+different scene returns 409. A successful paid operation reports `unitCost: 15`, shared
+`remainingUnits`, its durable `operationId`, cache reuse, hash, and immutable image URL. A live
+equal-hash render may return `202`; the helper polls with the same body/key within its bounded wait.
+`maxWaitMs` is the total client completion budget, including network, response parsing, and polling
+delays; `signal` cancels the same complete operation. The helper aborts in-flight work when either
+boundary is reached. It rejects malformed responses, non-HTTP(S) image URLs, and any change of
+durable operation ID while polling.
+
+Free cannot initiate Static Maps work. Starter consumes 15 shared API units for each successful
+logical operation, including a distinct-key cache reuse. Downloading the immutable PNG consumes
+zero units.
+
 Docs: https://tileflow.dev/docs

package/dist/index.d.ts

@@ -202,13 +202,42 @@ type StaticMapResult = {
     cached: boolean;
     hash: string;
     imageUrl: string;
+    operationId: string | null;
+    remainingUnits: number | null;
     status: 'ready';
+    unitCost: 0 | 15;
 };
 type StaticMapCreateOptions = {
     apiKey?: string;
     apiUrl?: string;
     fetch?: typeof fetch;
+    idempotencyKey: string;
+    maxWaitMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
 };
+declare const staticMapReadyResultSchema: z.ZodObject<{
+    cached: z.ZodBoolean;
+    hash: z.ZodString;
+    imageUrl: z.ZodString;
+    operationId: z.ZodString;
+    remainingUnits: z.ZodNumber;
+    status: z.ZodLiteral<"ready">;
+    unitCost: z.ZodLiteral<15>;
+}, z.core.$strict>;
+declare const staticMapProcessingResultSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    retryAfterMs: z.ZodNumber;
+    status: z.ZodLiteral<"processing">;
+}, z.core.$strict>;
+declare function validateStaticMapIdempotencyKey(value: unknown): {
+    key: string;
+    ok: true;
+} | {
+    error: string;
+    ok: false;
+};
+declare function createStaticMapIdempotencyKey(): string;
 declare function line(input: Omit<z.input<typeof lineOverlaySchema>, 'type'>): StaticOverlay;
 declare function circle(input: Omit<z.input<typeof circleOverlaySchema>, 'type'>): StaticOverlay;
 declare function marker(input: Omit<z.input<typeof markerOverlaySchema>, 'type'>): StaticOverlay;
@@ -237,12 +266,13 @@ declare function createRenderManifest(input: {
     styleUrl: string;
 }): StaticRenderManifest;
 declare function hashRenderManifest(manifest: StaticRenderManifest): Promise<string>;
+declare function hashStaticSceneRequest(scene: StaticSceneInput): Promise<string>;
 declare function compileStaticOverlays(overlays: StaticOverlay[]): {
     layers: Record<string, unknown>[];
     sources: Record<string, Record<string, unknown>>;
 };
-declare function createStaticMap(scene: StaticSceneInput, options?: StaticMapCreateOptions): Promise<StaticMapResult>;
-declare function precacheStaticMap(scene: StaticSceneInput, options?: StaticMapCreateOptions): Promise<StaticMapResult>;
+declare function createStaticMap(scene: StaticSceneInput, options: StaticMapCreateOptions): Promise<StaticMapResult>;
+declare function precacheStaticMap(scene: StaticSceneInput, options: StaticMapCreateOptions): Promise<StaticMapResult>;
 declare function stableStringify(value: unknown): string;
 
-export { type StaticCoordinate, type StaticMapCreateOptions, type StaticMapResult, type StaticOverlay, type StaticOverlayInput, type StaticRenderManifest, type StaticScene, type StaticSceneInput, circle, compileStaticOverlays, createRenderManifest, createStaticMap, hashRenderManifest, line, marker, normalizeStaticScene, polygon, precacheStaticMap, stableStringify, staticOverlaySchema, staticRenderManifestSchema, staticRendererSchemaVersion, staticSceneLimits, staticSceneSchema, staticSceneSchemaVersion, validateStaticRenderManifest, validateStaticScene };
+export { type StaticCoordinate, type StaticMapCreateOptions, type StaticMapResult, type StaticOverlay, type StaticOverlayInput, type StaticRenderManifest, type StaticScene, type StaticSceneInput, circle, compileStaticOverlays, createRenderManifest, createStaticMap, createStaticMapIdempotencyKey, hashRenderManifest, hashStaticSceneRequest, line, marker, normalizeStaticScene, polygon, precacheStaticMap, stableStringify, staticMapProcessingResultSchema, staticMapReadyResultSchema, staticOverlaySchema, staticRenderManifestSchema, staticRendererSchemaVersion, staticSceneLimits, staticSceneSchema, staticSceneSchemaVersion, validateStaticMapIdempotencyKey, validateStaticRenderManifest, validateStaticScene };

package/dist/index.js

@@ -110,6 +110,37 @@ var staticRenderManifestSchema = z.object({
     message: "Expected an http(s) style URL"
   })
 });
+var staticMapIdempotencyKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
+var staticMapReadyResultSchema = z.object({
+  cached: z.boolean(),
+  hash: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+  imageUrl: z.string().trim().url().max(2048).refine(isSafeHttpUrl, { message: "Expected an http(s) URL without credentials" }),
+  operationId: z.string().min(20).max(68),
+  remainingUnits: z.number().int().nonnegative(),
+  status: z.literal("ready"),
+  unitCost: z.literal(15)
+}).strict();
+var staticMapProcessingResultSchema = z.object({
+  operationId: z.string().min(20).max(68),
+  retryAfterMs: z.number().int().min(0).max(5e3),
+  status: z.literal("processing")
+}).strict();
+function validateStaticMapIdempotencyKey(value) {
+  if (typeof value !== "string" || !staticMapIdempotencyKeyPattern.test(value)) {
+    return {
+      error: "Idempotency key must contain 8-128 ASCII letters, digits, dot, underscore, colon, or hyphen and start with a letter or digit",
+      ok: false
+    };
+  }
+  return { key: value, ok: true };
+}
+function createStaticMapIdempotencyKey() {
+  const key = `static_${crypto.randomUUID()}`;
+  if (!validateStaticMapIdempotencyKey(key).ok) {
+    throw new Error("Unable to create a valid Tileflow Static Maps idempotency key");
+  }
+  return key;
+}
 function line(input) {
   return normalizeOverlay({ ...input, type: "line" });
 }
@@ -211,6 +242,11 @@ async function hashRenderManifest(manifest) {
   const digest = await crypto.subtle.digest("SHA-256", bytes);
   return base64Url(new Uint8Array(digest));
 }
+async function hashStaticSceneRequest(scene) {
+  const validation = validateStaticScene(scene);
+  if (!validation.ok) throw new Error(`Invalid Tileflow static scene: ${validation.error}`);
+  return hashStableValue(validation.scene);
+}
 function compileStaticOverlays(overlays) {
   const sources = {};
   const layers = [];
@@ -282,10 +318,10 @@ function compileStaticOverlays(overlays) {
   }
   return { layers, sources };
 }
-async function createStaticMap(scene, options = {}) {
+async function createStaticMap(scene, options) {
   return requestStaticMap(scene, options, "/v1/static/maps");
 }
-async function precacheStaticMap(scene, options = {}) {
+async function precacheStaticMap(scene, options) {
   return requestStaticMap(scene, options, "/v1/static/maps/precache");
 }
 async function requestStaticMap(scene, options, path) {
@@ -293,24 +329,66 @@ async function requestStaticMap(scene, options, path) {
   if (!validation.ok) {
     throw new Error(`Invalid Tileflow static scene: ${validation.error}`);
   }
+  const idempotency = validateStaticMapIdempotencyKey(options.idempotencyKey);
+  if (!idempotency.ok) {
+    throw new Error(`Invalid Tileflow Static Maps idempotency key: ${idempotency.error}`);
+  }
+  const maxWaitMs = boundedClientDuration(options.maxWaitMs, 3e4, 100, 12e4, "maxWaitMs");
+  const pollIntervalMs = boundedClientDuration(
+    options.pollIntervalMs,
+    500,
+    0,
+    5e3,
+    "pollIntervalMs"
+  );
   const fetcher = options.fetch ?? fetch;
   const apiUrl = normalizeUrl(options.apiUrl ?? "https://api.tileflow.dev");
   const headers = {
-    "Content-Type": "application/json"
+    "Content-Type": "application/json",
+    "Idempotency-Key": idempotency.key
   };
   if (options.apiKey) {
     headers.Authorization = `Bearer ${options.apiKey}`;
   }
-  const response = await fetcher(`${apiUrl}${path}`, {
-    body: JSON.stringify(validation.scene),
-    headers,
-    method: "POST"
+  return runWithinStaticMapBudget(maxWaitMs, options.signal, async (signal) => {
+    const body = JSON.stringify(validation.scene);
+    let operationId = null;
+    while (true) {
+      const response = await fetcher(`${apiUrl}${path}`, {
+        body,
+        headers,
+        method: "POST",
+        signal
+      });
+      throwIfAborted(signal);
+      if (!response.ok) {
+        const error = await response.text();
+        throwIfAborted(signal);
+        throw new Error(`Tileflow static map failed: ${response.status} ${error}`);
+      }
+      const json = await readJsonResponse(response);
+      throwIfAborted(signal);
+      if (response.status !== 202) {
+        const parsed = staticMapReadyResultSchema.safeParse(json);
+        if (!parsed.success) {
+          throw new Error(
+            `Tileflow static map returned an invalid response: ${parsed.error.message}`
+          );
+        }
+        assertStaticMapOperationIdentity(operationId, parsed.data.operationId);
+        return parsed.data;
+      }
+      const pending = staticMapProcessingResultSchema.safeParse(json);
+      if (!pending.success) {
+        throw new Error(
+          `Tileflow static map returned an invalid response: ${pending.error.message}`
+        );
+      }
+      assertStaticMapOperationIdentity(operationId, pending.data.operationId);
+      operationId ??= pending.data.operationId;
+      await delay(Math.max(pollIntervalMs, pending.data.retryAfterMs), signal);
+    }
   });
-  if (!response.ok) {
-    const error = await response.text();
-    throw new Error(`Tileflow static map failed: ${response.status} ${error}`);
-  }
-  return await response.json();
 }
 function stableStringify(value) {
   return JSON.stringify(sortJson(value));
@@ -378,6 +456,110 @@ function base64Url(bytes) {
   }
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
+async function hashStableValue(value) {
+  const bytes = new TextEncoder().encode(stableStringify(value));
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return base64Url(new Uint8Array(digest));
+}
+function boundedClientDuration(value, fallback, minimum, maximum, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new Error(
+      `Tileflow Static Maps ${name} must be an integer from ${minimum} to ${maximum}`
+    );
+  }
+  return resolved;
+}
+async function readJsonResponse(response) {
+  try {
+    return await response.json();
+  } catch {
+    throw new Error("Tileflow static map returned an invalid response: expected JSON");
+  }
+}
+async function runWithinStaticMapBudget(maxWaitMs, externalSignal, operation) {
+  const controller = new AbortController();
+  const timeoutError = new Error(`Tileflow static map timed out after ${maxWaitMs}ms`);
+  const abortFromCaller = () => controller.abort(externalSignal?.reason);
+  if (externalSignal?.aborted) {
+    abortFromCaller();
+  } else {
+    externalSignal?.addEventListener("abort", abortFromCaller, { 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", abortFromCaller);
+  }
+}
+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.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("Tileflow static map request was aborted");
+  error.name = "AbortError";
+  return error;
+}
+function assertStaticMapOperationIdentity(expected, actual) {
+  if (expected !== null && actual !== expected) {
+    throw new Error("Tileflow static map changed operation identity while polling");
+  }
+}
+function isSafeHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}
 function normalizeUrl(value) {
   return value.replace(/\/+$/, "");
 }
@@ -386,19 +568,24 @@ export {
   compileStaticOverlays,
   createRenderManifest,
   createStaticMap,
+  createStaticMapIdempotencyKey,
   hashRenderManifest,
+  hashStaticSceneRequest,
   line,
   marker,
   normalizeStaticScene,
   polygon,
   precacheStaticMap,
   stableStringify,
+  staticMapProcessingResultSchema,
+  staticMapReadyResultSchema,
   staticOverlaySchema,
   staticRenderManifestSchema,
   staticRendererSchemaVersion,
   staticSceneLimits,
   staticSceneSchema,
   staticSceneSchemaVersion,
+  validateStaticMapIdempotencyKey,
   validateStaticRenderManifest,
   validateStaticScene
 };

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@tileflow/static",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.17",
   "description": "Static map request schemas and helpers for Tileflow.",
   "type": "module",
   "sideEffects": false,
   "homepage": "https://tileflow.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tileflow/tileflow.git",
+    "url": "git+https://github.com/tileflow/tileflow-sdk.git",
     "directory": "packages/static"
   },
   "bugs": {
-    "url": "https://github.com/tileflow/tileflow/issues"
+    "url": "https://github.com/tileflow/tileflow-sdk/issues"
   },
   "keywords": [
     "tileflow",