googlemaps-kit 0.4.0 → 0.5.0

package/dist/types/transit.d.ts

@@ -1,8 +1,22 @@
 /** Transit station departure board embedded in place preview placeData[62]. */
+import type { Coordinates } from './common.js';
+import type { TransitMode } from './directions.js';
+/**
+ * Raw vehicle label from the transit feed.
+ * Known canonical values are suggested, but Google also emits locale display
+ * labels ("Tube", "Metro"), so any string is assignable.
+ */
+export type TransitVehicleType = 'SUBWAY' | 'BUS' | 'TRAM' | 'RAIL' | 'FERRY' | 'CABLE_CAR' | 'GONDOLA' | (string & {});
 export interface TransitDeparture {
     headsign: string;
+    /** Human-readable departure time, e.g. "2 min" or "10:32". */
     scheduledTime?: string;
+    /** Unix timestamp in seconds (UTC). */
     scheduledUnix?: number;
+    /** ISO 8601 formatted departure time derived from scheduledUnix when timezone is present. */
+    scheduledAt?: string;
+    /** Minutes until departure (derived from scheduledUnix and current time). */
+    minutesUntil?: number;
     timezone?: string;
     platform?: string;
     tripId?: string;
@@ -10,12 +24,23 @@ export interface TransitDeparture {
     lineName?: string;
     lineColor?: string;
     lineTextColor?: string;
-    vehicleType?: string;
+    /**
+     * Vehicle type string from the transit feed.
+     * Known values: `"SUBWAY"`, `"BUS"`, `"TRAM"`, `"RAIL"`, `"FERRY"`, `"CABLE_CAR"`, `"GONDOLA"`.
+     * May also be a display label like `"Tube"` or `"Metro"` depending on locale.
+     */
+    vehicleType?: TransitVehicleType;
     vehicleIconUrl?: string;
+    /** Short route identifier (e.g. "N1", "Jubilee") extracted from headsign or line name. */
+    routeShortName?: string;
+    raw?: unknown;
 }
 export interface TransitModeBoard {
     mode: string;
+    /** Human-readable mode label (e.g. "Tube", "Bus") when present. */
+    modeLabel?: string;
     departures: TransitDeparture[];
+    raw?: unknown;
 }
 export interface TransitStationBoard {
     stationName?: string;
@@ -24,6 +49,7 @@ export interface TransitStationBoard {
     lng?: number;
     timezone?: string;
     modes: TransitModeBoard[];
+    raw?: unknown;
 }
 export interface GetStationDeparturesOptions {
     hexId: string;
@@ -43,4 +69,137 @@ export interface ListTransitLinesOptions {
     lng?: number;
     psi?: string;
 }
+export interface TransitRouteOptions {
+    origin: Coordinates | string;
+    destination: Coordinates | string;
+    /** Desired departure (local timezone of the origin). */
+    departureTime?: Date;
+    /** Desired arrival. Mutually exclusive with `departureTime`. */
+    arrivalTime?: Date;
+    preferences?: TransitPreference[];
+    /** Restrict to these vehicle types. */
+    modes?: TransitVehicleFilter[];
+    language?: string;
+}
+/**
+ * Vehicle types accepted by the transit filter.
+ * Same value set as {@link TransitMode} — kept as an alias so both option
+ * spellings (`RouteOptions.transitModes`, `TransitRouteOptions.modes`) stay valid.
+ */
+export type TransitVehicleFilter = TransitMode;
+export type TransitPreference = 'avoidSurface' | 'preferRail' | 'fewerTransfers';
+/** A point in space and time on a transit trip. */
+export interface TransitStation {
+    name: string;
+    /** Feed stop id (GTFS stop code) when Google publishes one. */
+    code?: string;
+    lat: number;
+    lng: number;
+    /** Maps feature id (`0x…:0x…`) for the stop, when present. */
+    hexId?: string;
+    /** Scheduled departure from this stop. */
+    departureTime?: Date;
+    /** Scheduled arrival at this stop. */
+    arrivalTime?: Date;
+}
+/** Operator running a transit leg. */
+export interface TransitAgency {
+    name: string;
+    id?: string;
+    url?: string;
+    phone?: string;
+}
+export interface TransitLine {
+    /** Short name riders use — `"176"`, `"A Line"`, `"Northern"`. */
+    number?: string;
+    /** Long display name when it differs from {@link number}. */
+    name?: string;
+    /** Line colour as `#rrggbb`. */
+    color?: string;
+    /** Contrasting text colour for {@link color}. */
+    textColor?: string;
+    agency?: string;
+    /** Full operator record. */
+    agencyDetails?: TransitAgency;
+    /** Terminus shown on the vehicle, e.g. `"Far Rockaway-Mott Av"`. */
+    headsign?: string;
+    /** Vehicle label from the feed — `"Bus"`, `"Subway"`, `"Tram"`. */
+    vehicleType?: TransitVehicleType;
+    /** Line/vehicle icon served by maps.gstatic.com. */
+    iconUrl?: string;
+}
+/** Service advisory attached to a route or leg. */
+export interface TransitAlert {
+    /** Short label, e.g. `"Modified schedule"`. */
+    headline?: string;
+    /** Severity label Google renders, e.g. `"Information"`. */
+    severity?: string;
+    /** Full advisory text. */
+    description?: string;
+}
+/** Fare for a route or leg, as published by the operator. */
+export interface TransitFare {
+    /** Numeric amount in {@link currency}. */
+    amount: number;
+    /** Localised amount, e.g. `"£1.75"`. */
+    text: string;
+    /** ISO 4217 code. */
+    currency: string;
+}
+export interface TransitLeg {
+    /** `walking` for the connecting legs, `transit` when riding a vehicle. */
+    mode: 'walking' | 'transit';
+    /**
+     * Boarding stop. Omitted when Google does not publish a station block
+     * (common on walking legs) — never a placeholder.
+     */
+    startStation?: TransitStation;
+    /** Alighting stop. Omitted when Google does not publish a station block. */
+    endStation?: TransitStation;
+    departureTime?: Date;
+    arrivalTime?: Date;
+    /** Leg duration in seconds. Omitted when the feed carries no duration node. */
+    durationSeconds?: number;
+    /** Human-readable duration, e.g. `"14 min"`. */
+    durationText?: string;
+    /** Distance in metres — present on walking legs. */
+    distanceMeters?: number;
+    distanceText?: string;
+    line?: TransitLine;
+    /** Turn-by-turn text for walking legs. */
+    instructions?: string[];
+    /** Stops between {@link startStation} and {@link endStation}. */
+    stops?: TransitStation[];
+    /** Number of stops ridden, as Google counts them. */
+    stopCount?: number;
+    /** Advisories scoped to this leg. */
+    alerts?: TransitAlert[];
+    fare?: TransitFare;
+}
+export interface TransitRoute {
+    legs: TransitLeg[];
+    /** Total trip duration in seconds. Omitted when the feed carries no duration node. */
+    durationSeconds?: number;
+    durationText?: string;
+    distanceMeters?: number;
+    distanceText?: string;
+    arrivalTime?: Date;
+    departureTime?: Date;
+    /** IANA timezone the times are expressed in. */
+    timezone?: string;
+    /** Vehicle boardings on this route (walking legs excluded). */
+    transfers: number;
+    /** Service frequency blurb, e.g. `"every 10 min"`. */
+    frequency?: string;
+    /** Total walking time across the route. */
+    walkingSeconds?: number;
+    fare?: TransitFare;
+    agencies?: TransitAgency[];
+    alerts?: TransitAlert[];
+    summary?: string;
+}
+export interface TransitRouteResult {
+    routes: TransitRoute[];
+    timingMs: number;
+}
 //# sourceMappingURL=transit.d.ts.map

package/dist/types/transit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transit.d.ts","sourceRoot":"","sources":["../../src/types/transit.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"transit.d.ts","sourceRoot":"","sources":["../../src/types/transit.ts"],"names":[],"mappings":"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"}

package/dist/types/transit.js

@@ -1,3 +1,2 @@
-/** Transit station departure board embedded in place preview placeData[62]. */
 export {};
 //# sourceMappingURL=transit.js.map

package/dist/types/transit.js.map

@@ -1 +1 @@
-{"version":3,"file":"transit.js","sourceRoot":"","sources":["../../src/types/transit.ts"],"names":[],"mappings":"AAAA,+EAA+E"}
+{"version":3,"file":"transit.js","sourceRoot":"","sources":["../../src/types/transit.ts"],"names":[],"mappings":""}

package/dist/types/viewport.d.ts

@@ -0,0 +1,159 @@
+/** Viewport-surface types: passive-assist chips, neighbourhood context, click reveal. */
+export interface PassiveAssistChip {
+    name: string;
+    cacheKey?: string;
+    token?: string;
+    weatherIconUrl?: string;
+    weatherLabel?: string;
+    weatherTemp?: string;
+    /** Latitude of the associated place when present in the chip payload. */
+    lat?: number;
+    /** Longitude of the associated place when present in the chip payload. */
+    lng?: number;
+    /** Hex feature id of the associated place when present. */
+    hexId?: string;
+    /** ChIJ place id when present. */
+    placeId?: string;
+    raw?: unknown;
+}
+/** What a psi provider returns; `url` lets a provider hand back the verbatim captured request. */
+export interface MintedViewportPsi {
+    psi: string;
+    passiveAssistUrl?: string;
+}
+export interface PassiveAssistPsiContext {
+    lat: number;
+    lng: number;
+    zoom?: number;
+    hl: string;
+    gl: string;
+}
+export interface PassiveAssistOptions {
+    lat: number;
+    lng: number;
+    /** Viewport zoom used to derive camera altitude (default 14). */
+    zoom?: number;
+    /**
+     * In-page viewport psi. REQUIRED unless `psiProvider` is supplied: bootstrap
+     * kEI / fetchSessionPsi tokens only ever return the cache-metadata stub.
+     */
+    psi?: string;
+    /**
+     * Supplies an in-page psi on demand. Only a live Maps viewport session produces
+     * a usable token, so obtaining one needs a browser — this SDK deliberately will
+     * not launch one for you. Use `mintViewportPsi` from `scripts/lib/mint-viewport-psi.ts`
+     * to build a provider when a browser is acceptable in your environment.
+     */
+    psiProvider?: (context: PassiveAssistPsiContext) => Promise<string | MintedViewportPsi>;
+    width?: number;
+    height?: number;
+    /** Chip density hint (default 50). Browser also requests a 20-chip variant. */
+    chipLimit?: number;
+    hl?: string;
+    gl?: string;
+}
+export interface PassiveAssistResult {
+    chips: PassiveAssistChip[];
+    /** True when the response is the ~212 B cache-metadata stub with no POI rows. */
+    isStub: boolean;
+    raw?: unknown;
+}
+export type AreaType = 'city' | 'district' | 'neighborhood' | 'park' | 'water' | 'region';
+export type AdminLevel = 'country' | 'state' | 'county' | 'city' | 'neighborhood';
+export interface NearbyAreasOptions {
+    location: {
+        lat: number;
+        lng: number;
+    };
+    radiusMeters?: number;
+    types?: AreaType[];
+}
+export interface GeoArea {
+    id: string;
+    name: string;
+    type: AreaType;
+    lat: number;
+    lng: number;
+    distanceMeters: number;
+    bounds?: {
+        ne: {
+            lat: number;
+            lng: number;
+        };
+        sw: {
+            lat: number;
+            lng: number;
+        };
+    };
+    population?: number;
+}
+export interface AdminRegion {
+    name: string;
+    type: AdminLevel;
+    code?: string;
+    /**
+     * Region extent, when the source surface reports one.
+     *
+     * Reverse geocode names the administrative hierarchy but does not carry
+     * polygons, so this is usually absent.
+     */
+    bounds?: {
+        ne: {
+            lat: number;
+            lng: number;
+        };
+        sw: {
+            lat: number;
+            lng: number;
+        };
+    };
+    parent?: AdminRegion;
+}
+/** Options for GET /maps/preview/reveal (hidden POI at map click). */
+export interface RevealPlaceOptions {
+    /** Map viewport center latitude. */
+    camLat: number;
+    /** Map viewport center longitude. */
+    camLng: number;
+    /** Map zoom level used to derive camera altitude (default 14). */
+    camZoom?: number;
+    /** Click / hit-test latitude. */
+    hitLat: number;
+    /** Click / hit-test longitude. */
+    hitLng: number;
+    /**
+     * Feature id at the hit location (`!4m2!1s{ftid}!7e81`).
+     * From search/suggest `featureId` or place preview; omit to try hex-only flows.
+     */
+    ftid?: string;
+    /** Viewport width in pixels (default 1440). */
+    width?: number;
+    /** Viewport height in pixels (default 900). */
+    height?: number;
+    /** Tile pixel X for the hit (default 96). */
+    tileX?: number;
+    /** Tile pixel Y for the hit (default 64). */
+    tileY?: number;
+}
+/** POI revealed at a map click — often hidden from default map tiles. */
+export interface RevealedPlace {
+    name?: string;
+    formattedAddress?: string;
+    hexId?: string;
+    placeId?: string;
+    featureId?: string;
+    lat?: number;
+    lng?: number;
+    timezone?: string;
+    categoryHint?: string;
+    streetViewThumbnailUrl?: string;
+    plusCode?: string;
+    raw?: unknown;
+}
+export interface RevealPlaceResult {
+    place?: RevealedPlace;
+    /** Raw address line pair when present at response root. */
+    addressLines?: string[];
+    raw?: unknown;
+}
+//# sourceMappingURL=viewport.d.ts.map

package/dist/types/viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../../src/types/viewport.ts"],"names":[],"mappings":"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"}

package/dist/types/viewport.js

@@ -0,0 +1,3 @@
+/** Viewport-surface types: passive-assist chips, neighbourhood context, click reveal. */
+export {};
+//# sourceMappingURL=viewport.js.map

package/dist/types/viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../../src/types/viewport.ts"],"names":[],"mappings":"AAAA,yFAAyF"}

package/dist/utils/async.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Async plumbing: abortable sleep, bounded-concurrency pools, TTL cache and
+ * per-call request context (AbortSignal via AsyncLocalStorage).
+ */
+export declare function throwIfAborted(signal?: AbortSignal): void;
+/** Sleep that rejects when the signal aborts. */
+export declare function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function pooled<T>(items: T[], limit: number, worker: (item: T, index: number) => Promise<void>): Promise<void>;
+/** Like {@link pooled} but collects return values in input order. */
+export declare function pooledMap<T, R>(items: T[], limit: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function sleep(ms: number): Promise<void>;
+export declare class TtlCache<V> {
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly map;
+    constructor(options?: {
+        ttlMs?: number;
+        maxEntries?: number;
+    });
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    clear(): void;
+    get size(): number;
+}
+export interface RequestContext {
+    signal?: AbortSignal;
+}
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => Promise<T>): Promise<T>;
+export declare function getRequestSignal(): AbortSignal | undefined;
+/**
+ * Run any kit calls inside an abortable scope.
+ *
+ * Intent methods (`discover`, `profile`, …) take `signal` directly. Service
+ * calls (`maps.travel.directions.get(…)`, `maps.map.tiles.getTile(…)`) do not —
+ * wrap them in this to make their HTTP requests abortable.
+ *
+ * @example
+ * const ac = new AbortController();
+ * const tile = await withAbortSignal(ac.signal, () =>
+ *   maps.map.tiles.getTile({ zoom: 14, x: 11871, y: 7576 }),
+ * );
+ */
+export declare function withAbortSignal<T>(signal: AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=async.d.ts.map

package/dist/utils/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/utils/async.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAOzD;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB9E;AAQD,wBAAsB,MAAM,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,qEAAqE;AACrE,wBAAsB,SAAS,CAAC,CAAC,EAAE,CAAC,EAClC,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CAMd;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsD;gBAE9D,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAKjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAa/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAUhC,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAID,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,GAAG,EAAE,cAAc,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,wBAAgB,gBAAgB,IAAI,WAAW,GAAG,SAAS,CAE1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ"}

package/dist/utils/async.js

@@ -0,0 +1,132 @@
+/**
+ * Async plumbing: abortable sleep, bounded-concurrency pools, TTL cache and
+ * per-call request context (AbortSignal via AsyncLocalStorage).
+ */
+import { GMapsError } from '../types/common.js';
+export function throwIfAborted(signal) {
+    if (!signal)
+        return;
+    if (signal.aborted) {
+        const reason = signal.reason;
+        if (reason instanceof Error)
+            throw reason;
+        throw new GMapsError(typeof reason === 'string' ? reason : 'Aborted', undefined, reason);
+    }
+}
+/** Sleep that rejects when the signal aborts. */
+export function sleepAbortable(ms, signal) {
+    if (ms <= 0) {
+        throwIfAborted(signal);
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError(signal));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function abortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error)
+        return reason;
+    return new GMapsError(typeof reason === 'string' ? reason : 'Aborted', undefined, reason);
+}
+export async function pooled(items, limit, worker) {
+    if (items.length === 0)
+        return;
+    let cursor = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            await worker(items[index], index);
+        }
+    });
+    await Promise.all(runners);
+}
+/** Like {@link pooled} but collects return values in input order. */
+export async function pooledMap(items, limit, worker) {
+    const results = new Array(items.length);
+    await pooled(items, limit, async (item, index) => {
+        results[index] = await worker(item, index);
+    });
+    return results;
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class TtlCache {
+    ttlMs;
+    maxEntries;
+    map = new Map();
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? 60_000;
+        this.maxEntries = Math.max(1, options.maxEntries ?? 256);
+    }
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.map.delete(key);
+            return undefined;
+        }
+        // refresh LRU order
+        this.map.delete(key);
+        this.map.set(key, entry);
+        return entry.value;
+    }
+    set(key, value) {
+        if (this.map.has(key))
+            this.map.delete(key);
+        while (this.map.size >= this.maxEntries) {
+            const oldest = this.map.keys().next().value;
+            if (oldest == null)
+                break;
+            this.map.delete(oldest);
+        }
+        this.map.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    clear() {
+        this.map.clear();
+    }
+    get size() {
+        return this.map.size;
+    }
+}
+import { AsyncLocalStorage } from 'node:async_hooks';
+const store = new AsyncLocalStorage();
+export function runWithRequestContext(ctx, fn) {
+    return store.run(ctx, fn);
+}
+export function getRequestSignal() {
+    return store.getStore()?.signal;
+}
+/**
+ * Run any kit calls inside an abortable scope.
+ *
+ * Intent methods (`discover`, `profile`, …) take `signal` directly. Service
+ * calls (`maps.travel.directions.get(…)`, `maps.map.tiles.getTile(…)`) do not —
+ * wrap them in this to make their HTTP requests abortable.
+ *
+ * @example
+ * const ac = new AbortController();
+ * const tile = await withAbortSignal(ac.signal, () =>
+ *   maps.map.tiles.getTile({ zoom: 14, x: 11871, y: 7576 }),
+ * );
+ */
+export function withAbortSignal(signal, fn) {
+    if (!signal)
+        return fn();
+    return runWithRequestContext({ signal }, fn);
+}
+//# sourceMappingURL=async.js.map

package/dist/utils/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/utils/async.ts"],"names":[],"mappings":"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"}

package/dist/utils/encoded-polyline.d.ts

@@ -6,4 +6,47 @@ import type { Coordinates } from '../types/common.js';
 export declare function decodeEncodedPolyline(encoded: string, precision?: number): Coordinates[];
 /** Encode coordinates to Google's standard encoded polyline (precision 5). */
 export declare function encodePolyline(points: Coordinates[], precision?: number): string;
+/**
+ * Decode an encoded polyline string to an array of `{ lat, lng }` objects.
+ * Alias of `decodeEncodedPolyline` with a friendlier name.
+ *
+ * @example
+ * const path = decodePolyline('_p~iF~ps|U_ulLnnqC_mqNvxq`@');
+ * // [{ lat: 38.5, lng: -120.2 }, { lat: 40.7, lng: -120.95 }, { lat: 43.252, lng: -126.453 }]
+ */
+export declare function decodePolyline(encoded: string): Coordinates[];
+/**
+ * Decode an encoded polyline and return an array of human-readable strings.
+ * Each element is "lat, lng" rounded to 5 decimal places.
+ *
+ * @example
+ * polylineToHumanPath('_p~iF~ps|U_ulLnnqC');
+ * // ["38.50000, -120.20000", "40.70000, -120.95000"]
+ */
+export declare function polylineToHumanPath(encoded: string): string[];
+/**
+ * Convert an encoded polyline (or a raw `Coordinates[]` path) to a GeoJSON LineString Feature.
+ * The result is safe to stringify and pass to any GeoJSON consumer (Mapbox, Leaflet, turf, etc.).
+ *
+ * @example
+ * const geojson = polylineToGeoJSON(route.polyline!);
+ * // { type: 'Feature', geometry: { type: 'LineString', coordinates: [[lng, lat], ...] }, properties: {} }
+ */
+export declare function polylineToGeoJSON(encoded: string | Coordinates[]): {
+    type: 'Feature';
+    geometry: {
+        type: 'LineString';
+        coordinates: [number, number][];
+    };
+    properties: Record<string, never>;
+};
+/**
+ * Summarize a polyline as a compact human-readable string showing the first point,
+ * a middle sample, and the last point, plus total point count.
+ *
+ * @example
+ * summarizePolyline(route.polyline!);
+ * // "4 pts: (38.50000, -120.20000) → … → (43.25200, -126.45300)"
+ */
+export declare function summarizePolyline(encoded: string | Coordinates[]): string;
 //# sourceMappingURL=encoded-polyline.d.ts.map

package/dist/utils/encoded-polyline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoded-polyline.d.ts","sourceRoot":"","sources":["../../src/utils/encoded-polyline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAI,GAAG,WAAW,EAAE,CAqCnF;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,SAAS,SAAI,GAAG,MAAM,CAgB3E"}
+{"version":3,"file":"encoded-polyline.d.ts","sourceRoot":"","sources":["../../src/utils/encoded-polyline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAI,GAAG,WAAW,EAAE,CAqCnF;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,SAAS,SAAI,GAAG,MAAM,CAgB3E;AAqBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAE7D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAI7D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,GAC9B;IACD,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;KAAE,CAAC;IAClE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACnC,CAcA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,MAAM,CAsBzE"}