@tileflow/static 0.1.0-alpha.27 → 0.1.0-alpha.29

package/README.md

@@ -31,12 +31,9 @@ silently share another scene's identity.
 <!-- docs:check -->
 
 ```ts
-import {
-  createStaticMap,
-  createStaticMapIdempotencyKey,
-  marker,
-  validateStaticScene,
-} from '@tileflow/static';
+import {createStaticMap, createStaticMapIdempotencyKey} from '@tileflow/static/client';
+import {marker} from '@tileflow/static/overlays';
+import {validateStaticScene} from '@tileflow/static/scene';
 
 const apiKey = process.env.TILEFLOW_API_KEY;
 if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
@@ -99,7 +96,7 @@ preserved within each placement; later overlays paint above earlier overlays in
 Use `symbol` for a deployed sprite icon, renderer-owned text, or both:
 
 ```ts
-import {symbol} from '@tileflow/static';
+import {symbol} from '@tileflow/static/overlays';
 
 symbol({
   coordinate: [-3.7038, 40.4168],
@@ -155,7 +152,7 @@ Choose a corner when composition requires it:
 <!-- docs:check -->
 
 ```ts
-import type {StaticAttributionRequest} from '@tileflow/static';
+import type {StaticAttributionRequest} from '@tileflow/static/scene';
 
 const attribution = {
   mode: 'embedded',
@@ -168,7 +165,7 @@ Or request structured external attribution:
 <!-- docs:check -->
 
 ```ts
-import {createStaticMap, createStaticMapIdempotencyKey} from '@tileflow/static';
+import {createStaticMap, createStaticMapIdempotencyKey} from '@tileflow/static/client';
 
 const apiKey = process.env.TILEFLOW_API_KEY;
 if (!apiKey) throw new Error('Set TILEFLOW_API_KEY on the server.');
@@ -251,19 +248,18 @@ operation or API-unit charge. A different `403` is a credential or Map-coverage
 
 ## API entry points
 
-The package has four deliberately separate surfaces, all available from the root for compatibility:
+The package has four deliberately separate entry points:
 
-- scene validation and normalization: `staticSceneSchema`, `validateStaticScene`, and
-  `normalizeStaticScene`;
-- overlay authoring and MapLibre compilation: `line`, `circle`, `marker`, `polygon`, `symbol`, and
-  `compileStaticOverlays`;
-- renderer identity: `createRenderManifest`,
+- `@tileflow/static/scene`, scene validation and normalization: `staticSceneSchema`,
+  `validateStaticScene`, and `normalizeStaticScene`;
+- `@tileflow/static/overlays`, overlay authoring and MapLibre compilation: `line`, `circle`,
+  `marker`, `polygon`, `symbol`, and `compileStaticOverlays`;
+- `@tileflow/static/manifest`, renderer identity: `createRenderManifest`,
   `validateStaticRenderManifest`, `hashRenderManifest`, and `hashStaticSceneRequest`;
-- bounded Hosted transport: `prepareStaticMapRequest`, `createStaticMap`, `precacheStaticMap`, and
-  `requestStaticMapUntilReady`.
+- `@tileflow/static/client`, bounded Hosted transport: `prepareStaticMapRequest`,
+  `createStaticMap`, `precacheStaticMap`, and `requestStaticMapUntilReady`.
 
-Applications that need only one surface can use `@tileflow/static/scene`, `/overlays`, `/manifest`,
-or `/client`. The root remains a compatibility entry point.
+The package has no root entry point.
 
 `StaticRenderManifest` is the single strict immutable input contract between a resolved Hosted style
 and a Static Maps renderer. It binds safe attribution, exact source identity, semantic placement

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 export { S as StaticMapError, a as StaticMapErrorResponse, s as staticMapErrorResponseSchema } from './errors-CSz1xaDx.js';
-import { a as StaticAttributionPosition, j as StaticSceneInput } from './scene-contract-Cr6BNLz0.js';
+import { S as StaticAttributionPosition, a as StaticSceneInput } from './scene-contract-NFnIcQtt.js';
 
 declare function stableStringify(value: unknown): string;
 

package/dist/client.js

@@ -1,23 +1,369 @@
-import {
-  STATIC_MAP_RESULT_MEDIA_TYPE,
-  createStaticMap,
-  createStaticMapIdempotencyKey,
-  precacheStaticMap,
-  prepareStaticMapRequest,
-  requestStaticMapUntilReady,
-  staticMapAttributionEntrySchema,
-  staticMapAttributionResultSchema,
-  staticMapHostedResultSchema,
-  staticMapProcessingResultSchema,
-  validateStaticMapIdempotencyKey
-} from "./chunk-4GPRPR33.js";
 import {
   StaticMapError,
-  staticMapErrorResponseSchema
+  StaticMapRequestError,
+  staticMapErrorResponseSchema,
+  staticMapRequestErrorResponseSchema,
+  validateStaticScene
 } from "./chunk-ALFVZ3PC.js";
 import {
+  isSafeHttpUrl,
+  jsonByteLength,
   stableStringify
 } from "./chunk-6DWVCK64.js";
+
+// src/client.ts
+import { z } from "zod";
+var maxStaticMapResponseBytes = 64 * 1024;
+var staticMapIdempotencyKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
+var STATIC_MAP_RESULT_MEDIA_TYPE = "application/vnd.tileflow.static-map-result+json;version=1";
+var preparedStaticMapRequestBodies = /* @__PURE__ */ new WeakMap();
+var staticMapReadyResultBaseSchema = 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().nullable(),
+  status: z.literal("ready"),
+  unitCost: z.literal(15)
+}).strict();
+var safeAttributionTextSchema = z.string().min(1).max(16384).refine(hasNoControlCharacters, { message: "Attribution text contains control characters" });
+var staticMapAttributionEntrySchema = z.object({
+  authority: z.enum(["platform-notice", "team-declared"]),
+  links: z.array(
+    z.object({
+      label: safeAttributionTextSchema,
+      url: z.string().trim().url().max(2048).refine(isSafeHttpUrl, {
+        message: "Expected an http(s) URL without credentials or a fragment"
+      })
+    }).strict()
+  ).max(8),
+  text: safeAttributionTextSchema
+}).strict();
+var staticMapAttributionResultSchema = z.object({
+  entries: z.array(staticMapAttributionEntrySchema).max(18),
+  mode: z.enum(["embedded", "external"]),
+  position: z.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).nullable()
+}).strict().superRefine((result, context) => {
+  if (result.mode === "external" && result.position !== null || result.mode === "embedded" && result.position === null) {
+    context.addIssue({
+      code: "custom",
+      message: "Attribution position must match its mode",
+      path: ["position"]
+    });
+  }
+  if (jsonByteLength(result) > 32 * 1024) {
+    context.addIssue({ code: "custom", message: "Attribution result exceeds 32 KiB" });
+  }
+});
+var staticMapHostedResultSchema = staticMapReadyResultBaseSchema.extend({
+  attribution: staticMapAttributionResultSchema,
+  resultVersion: z.literal(1)
+}).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 prepareStaticMapRequest(scene) {
+  const validation = validateStaticScene(scene);
+  if (!validation.ok) {
+    if (isStaticMapRequestFailure(validation)) {
+      const { ok: _ok, ...response } = validation;
+      throw new StaticMapRequestError(response);
+    }
+    throw new Error(`Invalid Tileflow static scene: ${validation.error}`);
+  }
+  const prepared = Object.freeze({
+    sceneKey: stableStringify(validation.scene)
+  });
+  preparedStaticMapRequestBodies.set(prepared, JSON.stringify(validation.scene));
+  return prepared;
+}
+async function createStaticMap(scene, options) {
+  return requestStaticMap(scene, options, "/v1/static/maps");
+}
+async function precacheStaticMap(scene, options) {
+  return requestStaticMap(scene, options, "/v1/static/maps/precache");
+}
+async function requestStaticMap(scene, options, path) {
+  const preparedRequest = prepareStaticMapRequest(scene);
+  const { apiUrl = "https://api.tileflow.dev", ...requestOptions } = options;
+  return requestStaticMapUntilReady(preparedRequest, {
+    ...requestOptions,
+    createUrl: `${normalizeUrl(apiUrl)}${path}`
+  });
+}
+async function requestStaticMapUntilReady(request, options) {
+  const body = preparedStaticMapRequestBodies.get(request);
+  if (body === void 0) {
+    throw new Error("Tileflow static map request must be created with prepareStaticMapRequest");
+  }
+  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 createUrl = normalizeStaticMapEndpointUrl(options.createUrl);
+  const headers = {
+    Accept: STATIC_MAP_RESULT_MEDIA_TYPE,
+    "Content-Type": "application/json",
+    "Idempotency-Key": idempotency.key
+  };
+  if (options.apiKey) {
+    headers.Authorization = `Bearer ${options.apiKey}`;
+  }
+  if (options.mapId !== void 0) {
+    if (!/^map_[A-Za-z0-9_-]{16}$/u.test(options.mapId)) {
+      throw new Error("Invalid Tileflow Map ID.");
+    }
+    headers["X-Tileflow-Map-Id"] = options.mapId;
+  }
+  return runWithinStaticMapBudget(maxWaitMs, options.signal, async (signal) => {
+    let operationId = null;
+    while (true) {
+      const response = await fetcher(createUrl, {
+        body,
+        headers,
+        method: "POST",
+        signal
+      });
+      throwIfAborted(signal);
+      if (!response.ok) {
+        const errorBody = await readStaticMapErrorBody(response, 8 * 1024);
+        throwIfAborted(signal);
+        if (response.status === 422) {
+          const requestError = staticMapRequestErrorResponseSchema.safeParse(errorBody);
+          if (requestError.success) {
+            throw new StaticMapRequestError(requestError.data, response.status);
+          }
+        }
+        const structured = staticMapErrorResponseSchema.safeParse(errorBody);
+        if (structured.success) {
+          throw new StaticMapError(structured.data, response.status);
+        }
+        throw new Error(`Tileflow static map failed (${response.status}).`);
+      }
+      const json = await readJsonResponse(response);
+      throwIfAborted(signal);
+      if (response.status !== 202) {
+        const parsed = staticMapHostedResultSchema.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);
+    }
+  });
+}
+function hasNoControlCharacters(value) {
+  return !Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint === 127;
+  });
+}
+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) {
+  const source = await readBoundedResponseText(response, maxStaticMapResponseBytes, "64 KiB");
+  try {
+    return JSON.parse(source);
+  } catch {
+    throw new Error("Tileflow static map returned an invalid response: expected JSON");
+  }
+}
+async function readStaticMapErrorBody(response, maximumBytes) {
+  try {
+    const source = await readBoundedResponseText(response, maximumBytes, `${maximumBytes} bytes`);
+    return JSON.parse(source);
+  } catch {
+    return null;
+  }
+}
+function isStaticMapRequestFailure(value) {
+  if (!("code" in value)) return false;
+  const { ok: _ok, ...response } = value;
+  return staticMapRequestErrorResponseSchema.safeParse(response).success;
+}
+async function readBoundedResponseText(response, maximumBytes, displayLimit) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks = [];
+  let byteLength = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    byteLength += value.byteLength;
+    if (byteLength > maximumBytes) {
+      await reader.cancel();
+      throw new Error(
+        `Tileflow static map returned an invalid response: response exceeded ${displayLimit}`
+      );
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error("Tileflow static map returned an invalid response: expected UTF-8 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 normalizeUrl(value) {
+  const url = new URL(value);
+  if (!isSafeHttpUrl(value) || url.search) {
+    throw new TypeError(
+      "Tileflow Static Maps apiUrl must be HTTP(S) without credentials, query, or fragment"
+    );
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+function normalizeStaticMapEndpointUrl(value) {
+  if (value.startsWith("/")) {
+    if (value.startsWith("//") || value.length > 2048 || /[\\?#]/u.test(value) || hasControlCharacter(value)) {
+      throw new TypeError(
+        "Tileflow Static Maps createUrl must be HTTP(S) without credentials, query, or fragment or a safe root-relative path"
+      );
+    }
+    return value;
+  }
+  const url = new URL(value);
+  if (!isSafeHttpUrl(value) || url.search) {
+    throw new TypeError(
+      "Tileflow Static Maps createUrl must be HTTP(S) without credentials, query, or fragment or a safe root-relative path"
+    );
+  }
+  return url.toString();
+}
+function hasControlCharacter(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const codePoint = value.charCodeAt(index);
+    if (codePoint <= 31 || codePoint === 127) return true;
+  }
+  return false;
+}
 export {
   STATIC_MAP_RESULT_MEDIA_TYPE,
   StaticMapError,

package/dist/manifest.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { j as StaticSceneInput } from './scene-contract-Cr6BNLz0.js';
+import { a as StaticSceneInput } from './scene-contract-NFnIcQtt.js';
 
 declare const staticRendererSchemaVersion = 1;
 declare const staticAttributionPlanSchemaVersion = 1;
@@ -452,8 +452,8 @@ declare const staticRenderManifestSchema: z.ZodObject<{
                 haloColor: string;
                 haloWidth: number;
                 language: "ja" | "ko" | "zh-Hans" | "zh-Hant";
-                text: string;
                 position?: "above" | "above-left" | "above-right" | "below" | "below-left" | "below-right" | "center" | "left" | "right" | undefined;
+                text: string;
             } | {
                 appearance: "badge";
                 backgroundColor: string;
@@ -468,8 +468,8 @@ declare const staticRenderManifestSchema: z.ZodObject<{
                     x: number;
                     y: number;
                 };
-                text: string;
                 position?: "above" | "above-left" | "above-right" | "below" | "below-left" | "below-right" | "center" | "left" | "right" | undefined;
+                text: string;
             }, string | {
                 appearance: "plain";
                 color: string;
@@ -478,8 +478,8 @@ declare const staticRenderManifestSchema: z.ZodObject<{
                 haloColor: string;
                 haloWidth: number;
                 language: "ja" | "ko" | "zh-Hans" | "zh-Hant";
-                text: string;
                 position?: "above" | "above-left" | "above-right" | "below" | "below-left" | "below-right" | "center" | "left" | "right" | undefined;
+                text: string;
             } | {
                 appearance: "badge";
                 backgroundColor: string;
@@ -494,8 +494,8 @@ declare const staticRenderManifestSchema: z.ZodObject<{
                     x: number;
                     y: number;
                 };
-                text: string;
                 position?: "above" | "above-left" | "above-right" | "below" | "below-left" | "below-right" | "center" | "left" | "right" | undefined;
+                text: string;
             }>>>;
             offset: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
             opacity: z.ZodDefault<z.ZodNumber>;