@tileflow/static 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/client.d.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+export { S as StaticMapError, a as StaticMapErrorResponse, s as staticMapErrorResponseSchema } from './errors-CSz1xaDx.js';
+import { S as StaticAttributionPosition, a as StaticSceneInput } from './scene-contract-NFnIcQtt.js';
+
+declare function stableStringify(value: unknown): string;
+
+declare const STATIC_MAP_RESULT_MEDIA_TYPE = "application/vnd.tileflow.static-map-result+json;version=1";
+
+type StaticMapAttributionEntry = Readonly<{
+    authority: 'platform-notice' | 'team-declared';
+    links: readonly Readonly<{
+        label: string;
+        url: string;
+    }>[];
+    text: string;
+}>;
+type StaticMapAttributionResult = Readonly<{
+    entries: readonly StaticMapAttributionEntry[];
+    mode: 'embedded' | 'external';
+    position: Exclude<StaticAttributionPosition, 'auto'> | null;
+}>;
+type StaticMapResultBase = Readonly<{
+    cached: boolean;
+    hash: string;
+    imageUrl: string;
+    remainingUnits: number | null;
+    status: 'ready';
+}>;
+type StaticMapImageResult = StaticMapResultBase & Readonly<{
+    operationId: null;
+    unitCost: 0;
+}>;
+type StaticMapHostedResult = StaticMapResultBase & Readonly<{
+    attribution: StaticMapAttributionResult;
+    operationId: string;
+    resultVersion: 1;
+    unitCost: 15;
+}>;
+type StaticMapResult = StaticMapImageResult | StaticMapHostedResult;
+type StaticMapCreateOptions = {
+    apiKey?: string;
+    mapId?: string;
+    apiUrl?: string;
+    fetch?: typeof fetch;
+    idempotencyKey: string;
+    maxWaitMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+};
+type StaticMapEndpointRequestOptions = Omit<StaticMapCreateOptions, 'apiUrl'> & {
+    createUrl: string;
+};
+type PreparedStaticMapRequest = Readonly<{
+    sceneKey: string;
+}>;
+declare const staticMapAttributionEntrySchema: z.ZodObject<{
+    authority: z.ZodEnum<{
+        "platform-notice": "platform-notice";
+        "team-declared": "team-declared";
+    }>;
+    links: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strict>>;
+    text: z.ZodString;
+}, z.core.$strict>;
+declare const staticMapAttributionResultSchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        authority: z.ZodEnum<{
+            "platform-notice": "platform-notice";
+            "team-declared": "team-declared";
+        }>;
+        links: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strict>>;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    mode: z.ZodEnum<{
+        embedded: "embedded";
+        external: "external";
+    }>;
+    position: z.ZodNullable<z.ZodEnum<{
+        "bottom-left": "bottom-left";
+        "bottom-right": "bottom-right";
+        "top-left": "top-left";
+        "top-right": "top-right";
+    }>>;
+}, z.core.$strict>;
+declare const staticMapHostedResultSchema: z.ZodObject<{
+    cached: z.ZodBoolean;
+    hash: z.ZodString;
+    imageUrl: z.ZodString;
+    operationId: z.ZodString;
+    remainingUnits: z.ZodNullable<z.ZodNumber>;
+    status: z.ZodLiteral<"ready">;
+    unitCost: z.ZodLiteral<15>;
+    attribution: z.ZodObject<{
+        entries: z.ZodArray<z.ZodObject<{
+            authority: z.ZodEnum<{
+                "platform-notice": "platform-notice";
+                "team-declared": "team-declared";
+            }>;
+            links: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                url: z.ZodString;
+            }, z.core.$strict>>;
+            text: z.ZodString;
+        }, z.core.$strict>>;
+        mode: z.ZodEnum<{
+            embedded: "embedded";
+            external: "external";
+        }>;
+        position: z.ZodNullable<z.ZodEnum<{
+            "bottom-left": "bottom-left";
+            "bottom-right": "bottom-right";
+            "top-left": "top-left";
+            "top-right": "top-right";
+        }>>;
+    }, z.core.$strict>;
+    resultVersion: z.ZodLiteral<1>;
+}, 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 prepareStaticMapRequest(scene: StaticSceneInput): PreparedStaticMapRequest;
+declare function createStaticMap(scene: StaticSceneInput, options: StaticMapCreateOptions): Promise<StaticMapHostedResult>;
+declare function precacheStaticMap(scene: StaticSceneInput, options: StaticMapCreateOptions): Promise<StaticMapHostedResult>;
+declare function requestStaticMapUntilReady(request: PreparedStaticMapRequest, options: StaticMapEndpointRequestOptions): Promise<StaticMapHostedResult>;
+
+export { type PreparedStaticMapRequest, STATIC_MAP_RESULT_MEDIA_TYPE, type StaticMapAttributionEntry, type StaticMapAttributionResult, type StaticMapCreateOptions, type StaticMapEndpointRequestOptions, type StaticMapHostedResult, type StaticMapImageResult, type StaticMapResult, createStaticMap, createStaticMapIdempotencyKey, precacheStaticMap, prepareStaticMapRequest, requestStaticMapUntilReady, stableStringify, staticMapAttributionEntrySchema, staticMapAttributionResultSchema, staticMapHostedResultSchema, staticMapProcessingResultSchema, validateStaticMapIdempotencyKey };

package/dist/client.js

@@ -0,0 +1,382 @@
+import {
+  StaticMapError,
+  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,
+  createStaticMap,
+  createStaticMapIdempotencyKey,
+  precacheStaticMap,
+  prepareStaticMapRequest,
+  requestStaticMapUntilReady,
+  stableStringify,
+  staticMapAttributionEntrySchema,
+  staticMapAttributionResultSchema,
+  staticMapErrorResponseSchema,
+  staticMapHostedResultSchema,
+  staticMapProcessingResultSchema,
+  validateStaticMapIdempotencyKey
+};

package/dist/errors-CSz1xaDx.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+declare const staticMapErrorResponseSchema: z.ZodObject<{
+    code: z.ZodOptional<z.ZodString>;
+    error: z.ZodString;
+    remainingUnits: z.ZodOptional<z.ZodNumber>;
+    requestId: z.ZodOptional<z.ZodString>;
+    requiredPlan: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type StaticMapErrorResponse = z.infer<typeof staticMapErrorResponseSchema>;
+declare class StaticMapError extends Error {
+    readonly code: string | null;
+    readonly remainingUnits: number | null;
+    readonly requestId: string | null;
+    readonly requiredPlan: string | null;
+    readonly response: StaticMapErrorResponse;
+    readonly retryable: boolean | null;
+    readonly status: number;
+    constructor(response: StaticMapErrorResponse, status: number);
+}
+
+export { StaticMapError as S, type StaticMapErrorResponse as a, staticMapErrorResponseSchema as s };