HyperTrack Web SDK

Browser-hosted Web SDK for foreground locate() and addGeotag() calls driven by shared Rust SDK logic.

Docs:

• docs/spike.md - current behavior, target architecture, and spike review.
• docs/todo.md - hardening backlog.

Scope

• Regular mobile browser page.
• URL-provided publishable key; authentication is driven by Rust SDK logic through the Web SDK auth endpoint.
• Foreground current-location requests via navigator.geolocation.getCurrentPosition when Rust emits a Web shell location effect.
• Public locate() and addGeotag() APIs backed by generated Web shell actions/effects.
• Rust SDK state/logic compiled to wasm via rust/runtime_web and rust/web_logic.
• One page-level SDK singleton, matching native static/object SDK semantics.
• JavaScript shell encodes generated Web shell/runtime action bytes, interprets wasm effect bytes, and resumes wasm after browser callbacks or runtime completions.

Out of scope for this Web SDK surface: background tracking, continuous tracking, PWA mode, desktop support, and native WebView bridges.

Install

npm install @hypertrack/sdk-web@beta

The beta package is a browser ESM package. It includes the wasm-bindgen runtime and wasm asset used by the SDK; apps should import the SDK entrypoint and let their bundler serve the package asset.

Run locally

npm install
npm run build:wasm
npm run dev

Open with SDK-managed auth fetch:

http://127.0.0.1:4173/examples/locate/?pk=pk_test_web

API shape

import { createHyperTrackSDK } from "@hypertrack/sdk-web";

const sdk = await createHyperTrackSDK({
    publishableKey,
    workerHandle: "worker-123",
});

const location = await sdk.locate();

const geotag = await sdk.addGeotag({
    metadata: { source: "browser" },
    orderHandle: "order-123",
    orderStatus: "custom_status",
});

const geotagWithDeviation = await sdk.addGeotag({
    expectedLocation: { latitude: 37.785834, longitude: -122.406417 },
    metadata: { source: "browser" },
    orderHandle: "order-123",
    orderStatus: "clockIn",
});

clockIn and clockOut are predefined order statuses. Every other non-empty string is sent as a custom order status.

createHyperTrackSDK(...) returns one page-level singleton. The first successful create owns the instance; later calls return that instance and do not reinitialize Rust state or mutate options. Use sdk.setWorkerHandle(...) to change the worker handle after init.

Pass null or an empty string to setWorkerHandle() to clear the binding, matching native SDK behavior. Initialization treats an omitted, null, or empty worker handle as an explicit unbound state, so a persisted binding is not silently reused while the page reports workerHandle === null.

The SDK uses durable browser storage when available. If browser storage is blocked, unavailable, corrupt, or over quota, the current SDK instance keeps working with an in-memory identity/cache and emits a degraded-persistence diagnostic. Ephemeral identity survives only for that page instance; reload and offline-queue durability are not guaranteed.

addGeotag() is Rust-sequenced: JavaScript dispatches a generated Web shell action and resolves a Promise from the generated completion effect. Rust owns the pending operation and emits the browser current-position effect.

locate() and addGeotag() reject with arrays of SDK error strings when Rust returns SDK errors:

try {
    await sdk.locate();
} catch (errors) {
    if (Array.isArray(errors)
        && errors.includes("permissions.location.denied")) {
        // Show browser location permission UI.
    }
}

SDK errors use the Web-reachable SDK vocabulary: permissions.location.denied, location.signalLost, location.servicesUnavailable, invalidPublishableKey, and blockedFromRunning. Web addGeotag() resolves from a fresh foreground browser fix and does not produce the native tracking-dependent notRunning or starting errors. Invalid JavaScript arguments throw TypeError.

If the WebAssembly bridge fails unexpectedly, pending public Promises reject with a HyperTrackSDKInternalError and that SDK instance stops accepting calls. Expected SDK, browser, and authentication failures remain typed results or Rust-owned retry transitions.

debug and onDebug are internal development hooks for HyperTrack-owned pages.

Package entrypoint

package.json points main at ./src/index.js, exports["."].import at ./src/index.js, and types at ./src/index.d.ts. The package publishes the wasm-bindgen output under pkg/; browser bundlers such as Webpack 5 and Vite should treat the wasm file referenced from import.meta.url as a package asset.

Before publishing a beta package, build release wasm and verify the package contents:

npm run pack:dry-run

The beta publish command is:

npm publish --access public --tag beta

Test

npm test

The test script builds the wasm package, serves the example page with Vite, and runs Playwright checks for geolocation, singleton behavior, SDK-managed auth fetch/WebSocket open, browser WebSocket runtime execution, locate(), addGeotag(), concurrent locate callback keying, and permission denial.

Files

• src/index.js — browser shell and public createHyperTrackSDK API.
• src/generated/protocol.js — generated binary protocol codec for generic action/effect envelopes, Web shell ADTs, browser runtime ADTs, and shared runtime ADTs.
• src/binary.js — browser shell adapter around the generated protocol codec.
• src/runtime.js — zero-dependency browser runtime adapter for generated BrowserRuntimeEffect / BrowserRuntimeAction values.
• examples/locate/index.html — hosted test page.
• tests/web-sdk.spec.js — hermetic Playwright browser checks.
• tests/backend.e2e.spec.js — staging/live browser backend E2E.
• pkg/ — generated wasm-bindgen output from npm run build:wasm; ignored by git but included in npm packages through the files allowlist.