@bindimaps/hyperlocal-web-sdk 0.0.3 → 0.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@bindimaps/landseer is a devDependency because tsup bundles it into dist — it must NOT be a runtime dependency in the published package",
   "name": "@bindimaps/hyperlocal-web-sdk",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "description": "BindiMaps Hyperlocal Web SDK for indoor localisation",
   "main": "dist/index.js",
@@ -9,13 +9,12 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "development": "./src/index.ts",
+      "source": "./src/index.ts",
       "import": "./dist/index.js"
     }
   },
   "files": [
     "dist",
-    "src",
     "README.md"
   ],
   "scripts": {

package/src/image-selection.ts

@@ -1,75 +0,0 @@
-import type { CapturedFrame } from "./index"
-
-/**
- * Downsamples an image to a small grayscale thumbnail for diversity comparison.
- */
-const getImageThumbnail = async (blob: Blob, size = 16): Promise<Uint8Array> => {
-    const bitmap = await createImageBitmap(blob, { resizeWidth: size, resizeHeight: size, resizeQuality: "low" })
-    const canvas = document.createElement("canvas")
-    canvas.width = size
-    canvas.height = size
-    const ctx = canvas.getContext("2d")
-    if (!ctx) throw new Error("Could not get canvas context")
-    ctx.drawImage(bitmap, 0, 0)
-    bitmap.close()
-    const imageData = ctx.getImageData(0, 0, size, size).data
-    const grayscale = new Uint8Array(size * size)
-    for (let i = 0; i < imageData.length; i += 4) {
-        grayscale[i / 4] = (imageData[i] + imageData[i + 1] + imageData[i + 2]) / 3
-    }
-    return grayscale
-}
-
-/**
- * Calculates the Euclidean distance between two thumbnails.
- */
-const calculateDistance = (a: Uint8Array, b: Uint8Array): number => {
-    let sum = 0
-    for (let i = 0; i < a.length; i++) {
-        const diff = a[i] - b[i]
-        sum += diff * diff
-    }
-    return Math.sqrt(sum)
-}
-
-/**
- * Selects the most diverse frames from a set of candidates.
- * Uses a greedy "max-min" distance algorithm.
- * O(n·k) greedy, suitable for <100 candidates. For larger inputs consider a spatial index.
- */
-export const selectDiverseFrames = async (
-    frames: CapturedFrame[],
-    count: number
-): Promise<CapturedFrame[]> => {
-    if (frames.length <= count) return frames
-
-    const thumbnails = await Promise.all(frames.map(f => getImageThumbnail(f.imageData)))
-    const selectedIndices = new Set<number>([0])
-
-    while (selectedIndices.size < count) {
-        let maxMinDist = -1
-        let bestCandidateIdx = -1
-
-        for (let i = 0; i < frames.length; i++) {
-            if (selectedIndices.has(i)) continue
-
-            let minDist = Infinity
-            for (const selectedIdx of selectedIndices) {
-                const dist = calculateDistance(thumbnails[i], thumbnails[selectedIdx])
-                if (dist < minDist) minDist = dist
-            }
-
-            if (minDist > maxMinDist) {
-                maxMinDist = minDist
-                bestCandidateIdx = i
-            }
-        }
-
-        if (bestCandidateIdx === -1) break
-        selectedIndices.add(bestCandidateIdx)
-    }
-
-    return [...selectedIndices]
-        .sort((a, b) => a - b)
-        .map(idx => frames[idx])
-}

package/src/index.ts

@@ -1,299 +0,0 @@
-/**
- * @bindimaps/hyperlocal-web-sdk
- *
- * SDK for image-based indoor localisation using the Landseer API.
- */
-
-import type {
-    GpsLogEntry,
-    LocationEstimateImage,
-    LocationEstimateRequest,
-    LocationEstimateResponse,
-} from "@bindimaps/landseer/bmproto/landseer/landseer_pb"
-import {
-    LandseerAPIService,
-    Environment as LandseerEnvironment,
-    LocaliseType,
-} from "@bindimaps/landseer/bmproto/landseer/landseer_pb"
-import { createClient } from "@connectrpc/connect"
-import { createGrpcWebTransport } from "@connectrpc/connect-web"
-import { selectDiverseFrames } from "./image-selection"
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export type GeoCoordinate = {
-    latitude: number
-    longitude: number
-}
-
-export type CapturedFrame = {
-    timestamp: Date
-    imageData: Blob
-}
-
-export type PositionEstimate = {
-    type: "success"
-    position: GeoCoordinate
-    floorId: string
-    headingDegrees: number
-}
-
-export type PositionErrorCode =
-    | "invalid_input"
-    | "insufficient_frames"
-    | "no_match"
-    | "location_mismatch"
-    | "api_error"
-
-export type PositionError = {
-    type: "error"
-    code: PositionErrorCode
-    message: string
-    details?: string
-}
-
-export type PositionResult = PositionEstimate | PositionError
-
-export type MockPositionConfig =
-    | true
-    | {
-        position?: GeoCoordinate
-        floorId?: string
-        headingDegrees?: number
-    }
-
-export type EstimatePositionOptions = {
-    environment?: HyperlocalEnvironment
-    mock?: MockPositionConfig
-}
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-export const MIN_LOCALISATION_IMAGE_COUNT = 6
-const USE_DIVERSE_FRAME_SELECTION = false
-
-// Prefixed to avoid clashing with other `Environment` enums of the same name
-export enum HyperlocalEnvironment {
-    UNSPECIFIED = 0,
-    DEV_PREVIEW = 1,
-    DEV_PUBLIC = 2,
-    PROD_PREVIEW = 3,
-    PROD_PUBLIC = 4,
-}
-
-// ============================================================================
-// Internal Helpers
-// ============================================================================
-
-const toLandseerEnv = (env: HyperlocalEnvironment): LandseerEnvironment => {
-    const map: Record<HyperlocalEnvironment, LandseerEnvironment> = {
-        [HyperlocalEnvironment.UNSPECIFIED]: LandseerEnvironment.UNSPECIFIED,
-        [HyperlocalEnvironment.DEV_PREVIEW]: LandseerEnvironment.DEV_PREVIEW,
-        [HyperlocalEnvironment.DEV_PUBLIC]: LandseerEnvironment.DEV_PUBLIC,
-        [HyperlocalEnvironment.PROD_PREVIEW]: LandseerEnvironment.PROD_PREVIEW,
-        [HyperlocalEnvironment.PROD_PUBLIC]: LandseerEnvironment.PROD_PUBLIC,
-    }
-    return map[env]
-}
-
-const blobToUint8Array = async (blob: Blob): Promise<Uint8Array> => {
-    const arrayBuffer = await blob.arrayBuffer()
-    return new Uint8Array(arrayBuffer)
-}
-
-const getBaseUrl = (environment: HyperlocalEnvironment): string =>
-    (environment === HyperlocalEnvironment.PROD_PUBLIC || environment === HyperlocalEnvironment.PROD_PREVIEW)
-        ? "https://landseer.bindimaps.app"
-        : "https://landseer.bindi.dev"
-
-const isValidGpsPosition = (gpsPosition: unknown): gpsPosition is GeoCoordinate => {
-    if (!gpsPosition || typeof gpsPosition !== "object") return false
-    const maybeGps = gpsPosition as { latitude?: unknown, longitude?: unknown }
-
-    return (
-        Number.isFinite(maybeGps.latitude) &&
-        Number.isFinite(maybeGps.longitude) &&
-        Number(maybeGps.latitude) >= -90 && Number(maybeGps.latitude) <= 90 &&
-        Number(maybeGps.longitude) >= -180 && Number(maybeGps.longitude) <= 180
-    )
-}
-
-const normalizeHeadingDegrees = (headingDegrees: unknown): number =>
-    Number.isFinite(headingDegrees) ? Number(headingDegrees) : 0
-
-const validateInputs = (
-    frames: CapturedFrame[],
-    locationId: string,
-    gpsPosition: GeoCoordinate,
-): PositionError | null => {
-    if (typeof locationId !== "string" || locationId.trim().length === 0) {
-        return {
-            type: "error",
-            code: "invalid_input",
-            message: "locationId must be a non-empty string.",
-        }
-    }
-
-    if (!isValidGpsPosition(gpsPosition)) {
-        return {
-            type: "error",
-            code: "invalid_input",
-            message: "gpsPosition coordinates are out of range (lat: -90..90, lng: -180..180).",
-        }
-    }
-
-    if (!Array.isArray(frames)) {
-        return {
-            type: "error",
-            code: "invalid_input",
-            message: "frames must be an array.",
-        }
-    }
-
-    if (frames.length < MIN_LOCALISATION_IMAGE_COUNT) {
-        return {
-            type: "error",
-            code: "insufficient_frames",
-            message: `At least ${MIN_LOCALISATION_IMAGE_COUNT} frames are required for localisation.`,
-            details: `Received ${frames.length} frames, required ${MIN_LOCALISATION_IMAGE_COUNT}.`,
-        }
-    }
-
-    return null
-}
-
-const buildRequest = async (
-    frames: CapturedFrame[],
-    gpsPosition: GeoCoordinate,
-    environment: HyperlocalEnvironment,
-): Promise<LocationEstimateRequest> => {
-    const selectedFrames = USE_DIVERSE_FRAME_SELECTION
-        ? await selectDiverseFrames(frames, MIN_LOCALISATION_IMAGE_COUNT)
-        : frames
-
-    const now = new Date()
-    const ts = BigInt(now.getTime())
-
-    const gps: GpsLogEntry = {
-        gpsLocation: {
-            lat: gpsPosition.latitude,
-            lon: gpsPosition.longitude,
-            horizontalAccuracyMeters: 0,
-            mslAltitudeMeters: 0,
-            verticalAccuracyMeters: 0,
-            $typeName: "bmproto.landseer.LatLon",
-        },
-        ts,
-        $typeName: "bmproto.landseer.GpsLogEntry",
-    }
-
-    const images: LocationEstimateImage[] = await Promise.all(
-        selectedFrames.map(async (img) => ({
-            ts: BigInt(img.timestamp.getTime()),
-            imageData: await blobToUint8Array(img.imageData),
-            $typeName: "bmproto.landseer.LocationEstimateImage",
-        }))
-    )
-
-    return {
-        ts,
-        gps,
-        images,
-        env: toLandseerEnv(environment),
-        $typeName: "bmproto.landseer.LocationEstimateRequest",
-    }
-}
-
-const interpretResponse = (response: LocationEstimateResponse, locationId: string): PositionResult => {
-    if (
-        response.errors.length > 0 ||
-        response.localiseType === LocaliseType.FAILED ||
-        !response.locationEstimate ||
-        !response.locationEstimate.floorId ||
-        !Number.isFinite(response.locationEstimate.latitude) ||
-        !Number.isFinite(response.locationEstimate.longitude)
-    ) {
-        return {
-            type: "error",
-            code: "no_match",
-            message: response.errors.length > 0 ? response.errors.join(", ") : "Localisation failed — no match found.",
-            details: response.errors.length > 0 ? response.errors.join("; ") : `localiseType=${response.localiseType}`,
-        }
-    }
-
-    if (!response.locationEstimate.locationId || response.locationEstimate.locationId !== locationId) {
-        return {
-            type: "error",
-            code: "location_mismatch",
-            message: "Matched a different location than requested.",
-            details: `expected=${locationId}, got=${response.locationEstimate.locationId ?? "undefined"}`,
-        }
-    }
-
-    return {
-        type: "success",
-        position: {
-            latitude: response.locationEstimate.latitude,
-            longitude: response.locationEstimate.longitude,
-        },
-        floorId: response.locationEstimate.floorId,
-        headingDegrees: normalizeHeadingDegrees(response.locationEstimate.headingDegrees),
-    }
-}
-
-// ============================================================================
-// API
-// ============================================================================
-
-/**
- * Estimate a user's indoor position from captured camera frames and GPS.
- *
- * @param frames - Captured camera frames (minimum 6)
- * @param locationId - The Bindi location ID to localise within
- * @param gpsPosition - Approximate GPS coordinates
- * @param options - Optional configuration (environment, mock mode)
- */
-export const estimatePosition = async (
-    frames: CapturedFrame[],
-    locationId: string,
-    gpsPosition: GeoCoordinate,
-    options?: EstimatePositionOptions,
-): Promise<PositionResult> => {
-    // Mock mode — early return before any validation/protobuf/gRPC
-    if (options?.mock) {
-        await new Promise(resolve => setTimeout(resolve, 500))
-        const config = options.mock === true ? {} : options.mock
-        return {
-            type: "success",
-            position: config.position ?? gpsPosition,
-            floorId: config.floorId ?? "mock-floor-1",
-            headingDegrees: config.headingDegrees ?? 45,
-        }
-    }
-
-    const validationError = validateInputs(frames, locationId, gpsPosition)
-    if (validationError) return validationError
-
-    const environment = options?.environment ?? HyperlocalEnvironment.PROD_PUBLIC
-
-    try {
-        const req = await buildRequest(frames, gpsPosition, environment)
-        const transport = createGrpcWebTransport({ baseUrl: getBaseUrl(environment) })
-        const client = createClient(LandseerAPIService, transport)
-        const response = await client.locationEstimate(req, {
-            signal: AbortSignal.timeout(30_000),
-        })
-        return interpretResponse(response, locationId)
-    } catch (err) {
-        return {
-            type: "error",
-            code: "api_error",
-            message: "Network or transport error during localisation.",
-            details: err instanceof Error ? err.message : String(err),
-        }
-    }
-}