@tileflow/static 0.1.0-alpha.0 → 0.1.0-alpha.10

package/README.md

@@ -3,13 +3,17 @@
 Static map schemas, overlay helpers, and request utilities for Tileflow static map rendering.
 
 ```ts
-import { marker, validateStaticScene } from "@tileflow/static";
+import {marker, precacheStaticMap, validateStaticScene} from '@tileflow/static';
 
 const scene = validateStaticScene({
-  map: "madrid",
-  camera: { type: "center", center: [-3.7038, 40.4168], zoom: 12 },
-  size: { width: 1200, height: 800 },
-  overlays: [marker({ coordinate: [-3.7038, 40.4168] })],
+  map: 'madrid',
+  camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+  size: {width: 1200, height: 800},
+  overlays: [marker({coordinate: [-3.7038, 40.4168]})],
+});
+
+await precacheStaticMap(scene.scene, {
+  apiKey: process.env.TILEFLOW_API_KEY,
 });
 ```
 

package/dist/index.d.ts

@@ -202,17 +202,17 @@ type StaticMapResult = {
     cached: boolean;
     hash: string;
     imageUrl: string;
-    status: "ready";
+    status: 'ready';
 };
 type StaticMapCreateOptions = {
     apiKey?: string;
     apiUrl?: string;
     fetch?: typeof fetch;
 };
-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;
-declare function polygon(input: Omit<z.input<typeof polygonOverlaySchema>, "type">): StaticOverlay;
+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;
+declare function polygon(input: Omit<z.input<typeof polygonOverlaySchema>, 'type'>): StaticOverlay;
 declare function validateStaticScene(input: unknown): {
     ok: true;
     scene: StaticScene;
@@ -242,6 +242,7 @@ declare function compileStaticOverlays(overlays: StaticOverlay[]): {
     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 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, 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, hashRenderManifest, line, marker, normalizeStaticScene, polygon, precacheStaticMap, stableStringify, staticOverlaySchema, staticRenderManifestSchema, staticRendererSchemaVersion, staticSceneLimits, staticSceneSchema, staticSceneSchemaVersion, validateStaticRenderManifest, validateStaticScene };

package/dist/index.js

@@ -10,12 +10,9 @@ var staticSceneLimits = {
   maxPhysicalPixels: 1280 * 1280,
   minDimension: 64
 };
-var coordinateSchema = z.tuple([z.number().finite(), z.number().finite()]).refine(
-  ([lng, lat]) => lng >= -180 && lng <= 180 && lat >= -90 && lat <= 90,
-  {
-    message: "Expected [lng, lat] within world bounds"
-  }
-);
+var coordinateSchema = z.tuple([z.number().finite(), z.number().finite()]).refine(([lng, lat]) => lng >= -180 && lng <= 180 && lat >= -90 && lat <= 90, {
+  message: "Expected [lng, lat] within world bounds"
+});
 var colorSchema = z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, {
   message: "Expected a hex color like #C6A15B"
 });
@@ -37,12 +34,7 @@ var centerCameraSchema = z.object({
 });
 var boundsCameraSchema = z.object({
   bearing: z.number().finite().min(-180).max(180).optional(),
-  bounds: z.tuple([
-    z.number().finite(),
-    z.number().finite(),
-    z.number().finite(),
-    z.number().finite()
-  ]).refine(
+  bounds: z.tuple([z.number().finite(), z.number().finite(), z.number().finite(), z.number().finite()]).refine(
     ([west, south, east, north]) => west >= -180 && west <= 180 && east >= -180 && east <= 180 && south >= -90 && south <= 90 && north >= -90 && north <= 90 && west !== east && south !== north,
     { message: "Expected bounds as [west, south, east, north]" }
   ),
@@ -78,10 +70,16 @@ var markerOverlaySchema = z.object({
   strokeWidth: z.number().finite().min(0).max(16).default(2),
   type: z.literal("marker")
 });
+var polygonRingSchema = z.array(coordinateSchema).min(4).max(staticSceneLimits.maxPathCoordinates).refine(
+  (ring) => {
+    const first = ring[0];
+    const last = ring[ring.length - 1];
+    return Boolean(first && last && first[0] === last[0] && first[1] === last[1]);
+  },
+  { message: "Polygon rings must end at their starting coordinate" }
+);
 var polygonOverlaySchema = z.object({
-  coordinates: z.array(
-    z.array(coordinateSchema).min(4).max(staticSceneLimits.maxPathCoordinates)
-  ).min(1).max(16),
+  coordinates: z.array(polygonRingSchema).min(1).max(16),
   fill: colorSchema.default("#C6A15B"),
   id: z.string().trim().min(1).max(64).optional(),
   opacity: z.number().finite().min(0).max(1).default(0.28),
@@ -96,10 +94,7 @@ var staticOverlaySchema = z.discriminatedUnion("type", [
   polygonOverlaySchema
 ]);
 var staticSceneSchema = z.object({
-  camera: z.discriminatedUnion("type", [
-    centerCameraSchema,
-    boundsCameraSchema
-  ]),
+  camera: z.discriminatedUnion("type", [centerCameraSchema, boundsCameraSchema]),
   map: z.string().trim().min(1).max(128),
   overlays: z.array(staticOverlaySchema).max(staticSceneLimits.maxOverlays).default([]),
   size: sizeSchema
@@ -147,9 +142,7 @@ function validateStaticRenderManifest(input) {
   const parsed = staticRenderManifestSchema.safeParse(input);
   if (!parsed.success) {
     return {
-      error: parsed.error.issues.map(
-        (issue) => `${issue.path.join(".") || "manifest"}: ${issue.message}`
-      ).join("; "),
+      error: parsed.error.issues.map((issue) => `${issue.path.join(".") || "manifest"}: ${issue.message}`).join("; "),
       ok: false
     };
   }
@@ -222,9 +215,7 @@ function compileStaticOverlays(overlays) {
   const sources = {};
   const layers = [];
   for (const [index, overlay] of overlays.entries()) {
-    const id = safeLayerId(
-      `overlay-${index + 1}-${overlay.id ?? overlay.type}`
-    );
+    const id = safeLayerId(`overlay-${index + 1}-${overlay.id ?? overlay.type}`);
     const sourceId = `${id}-source`;
     if (overlay.type === "line") {
       sources[sourceId] = {
@@ -292,6 +283,12 @@ function compileStaticOverlays(overlays) {
   return { layers, sources };
 }
 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 validation = validateStaticScene(scene);
   if (!validation.ok) {
     throw new Error(`Invalid Tileflow static scene: ${validation.error}`);
@@ -304,7 +301,7 @@ async function createStaticMap(scene, options = {}) {
   if (options.apiKey) {
     headers.Authorization = `Bearer ${options.apiKey}`;
   }
-  const response = await fetcher(`${apiUrl}/v1/static/maps`, {
+  const response = await fetcher(`${apiUrl}${path}`, {
     body: JSON.stringify(validation.scene),
     headers,
     method: "POST"
@@ -322,9 +319,7 @@ function normalizeOverlay(overlay) {
   const parsed = staticOverlaySchema.parse(overlay);
   const normalized = stripUndefined({ ...parsed });
   if ("coordinate" in normalized) {
-    normalized.coordinate = normalizeCoordinate(
-      normalized.coordinate
-    );
+    normalized.coordinate = normalizeCoordinate(normalized.coordinate);
   }
   if ("coordinates" in normalized) {
     normalized.coordinates = normalizeCoordinates(normalized.coordinates);
@@ -350,9 +345,7 @@ function stripUndefined(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return value;
   }
-  return Object.fromEntries(
-    Object.entries(value).filter(([, entry]) => entry !== void 0)
-  );
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
 }
 function sortJson(value) {
   if (Array.isArray(value)) {
@@ -398,6 +391,7 @@ export {
   marker,
   normalizeStaticScene,
   polygon,
+  precacheStaticMap,
   stableStringify,
   staticOverlaySchema,
   staticRenderManifestSchema,

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@tileflow/static",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.10",
   "description": "Static map request schemas and helpers for Tileflow.",
   "type": "module",
+  "sideEffects": false,
   "homepage": "https://tileflow.dev",
   "repository": {
     "type": "git",
@@ -39,6 +40,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
+    "verify": "tsx --test test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit"
   }