@lotics/app-sdk 0.28.0 → 0.29.0

package/dist/src/geolocation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Device location for geofenced app actions.
+ *
+ * The host grants the app iframe the `geolocation` Permissions-Policy, so app
+ * code reads the device position directly through the browser — no RPC bridge.
+ * This module wraps that with permission handling, a timeout, and a geofence
+ * check, and returns a STRUCTURED outcome (`denied` / `unavailable` / `outside`)
+ * so the app renders its own guidance. A terse, untranslated "permission denied"
+ * dead-end is the single biggest reason a geofenced check-in fails in the field,
+ * so the messaging belongs to the app, not buried in here.
+ *
+ * Self-contained on purpose: `@lotics/app-sdk` is published to npm with a minimal
+ * dependency set and cannot pull in the private `@lotics/shared`, so the haversine
+ * lives here rather than being imported.
+ */
+/** One allowed circular zone: center `[latitude, longitude]` and a radius in meters. */
+export interface GeofenceZone {
+    coordinates: [number, number];
+    radius: number;
+}
+/** The resolved device position handed back on a successful check. */
+export interface GeoCoords {
+    latitude: number;
+    longitude: number;
+    /** Accuracy radius of the fix, in meters (browser-reported). */
+    accuracy: number;
+}
+/**
+ * Result of `requestGeofencedLocation`. On failure, `reason` is a stable code the
+ * app maps to its own (localized) message and recovery UI:
+ * - `denied` — the user/browser has not granted location permission.
+ * - `unavailable` — no fix: location services off, no GPS, or the request timed out.
+ * - `outside` — a fix was obtained but it is not within any allowed zone.
+ */
+export type GeofenceOutcome = {
+    ok: true;
+    coords: GeoCoords;
+} | {
+    ok: false;
+    reason: "denied" | "unavailable" | "outside";
+};
+/** Options for `requestGeofencedLocation`. */
+export interface GeofenceOptions {
+    /** Max wait for a position fix before resolving `unavailable`. Default 15000ms. */
+    timeoutMs?: number;
+}
+/** True when `[latitude, longitude]` falls within `zone`'s radius of its center. */
+export declare function isWithinZone(latitude: number, longitude: number, zone: GeofenceZone): boolean;
+/**
+ * Get the device position and check it against the allowed zones.
+ *
+ * Returns `{ ok: true, coords }` when a fix lands inside any zone — the app can
+ * forward `coords` to a workflow to record where the action happened. Otherwise
+ * `{ ok: false, reason }`; render guidance per `reason`. An empty `zones` array
+ * means "no geofence" and resolves `ok` with the raw position (use it for a
+ * plain location read).
+ *
+ * ```tsx
+ * const r = await requestGeofencedLocation(DEPOTS);
+ * if (!r.ok) return showGeofenceError(r.reason);
+ * await chamCong();
+ * ```
+ */
+export declare function requestGeofencedLocation(zones: GeofenceZone[], opts?: GeofenceOptions): Promise<GeofenceOutcome>;

package/dist/src/geolocation.js

@@ -0,0 +1,96 @@
+/**
+ * Device location for geofenced app actions.
+ *
+ * The host grants the app iframe the `geolocation` Permissions-Policy, so app
+ * code reads the device position directly through the browser — no RPC bridge.
+ * This module wraps that with permission handling, a timeout, and a geofence
+ * check, and returns a STRUCTURED outcome (`denied` / `unavailable` / `outside`)
+ * so the app renders its own guidance. A terse, untranslated "permission denied"
+ * dead-end is the single biggest reason a geofenced check-in fails in the field,
+ * so the messaging belongs to the app, not buried in here.
+ *
+ * Self-contained on purpose: `@lotics/app-sdk` is published to npm with a minimal
+ * dependency set and cannot pull in the private `@lotics/shared`, so the haversine
+ * lives here rather than being imported.
+ */
+const EARTH_RADIUS_M = 6_371_000;
+function toRadians(degrees) {
+    return (degrees * Math.PI) / 180;
+}
+/** Great-circle distance between two coordinates, in meters (haversine). */
+function distanceMeters(lat1, lon1, lat2, lon2) {
+    const dLat = toRadians(lat2 - lat1);
+    const dLon = toRadians(lon2 - lon1);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2)) * Math.sin(dLon / 2) * Math.sin(dLon / 2);
+    return EARTH_RADIUS_M * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+/** True when `[latitude, longitude]` falls within `zone`'s radius of its center. */
+export function isWithinZone(latitude, longitude, zone) {
+    const [centerLat, centerLon] = zone.coordinates;
+    return distanceMeters(latitude, longitude, centerLat, centerLon) <= zone.radius;
+}
+async function readPermissionState() {
+    // The Permissions API is unavailable on some browsers (notably older Safari);
+    // fall back to `null` and let `getCurrentPosition` surface the real state.
+    if (typeof navigator === "undefined" || !navigator.permissions?.query)
+        return null;
+    try {
+        const status = await navigator.permissions.query({ name: "geolocation" });
+        return status.state;
+    }
+    catch {
+        return null;
+    }
+}
+function getPosition(timeoutMs) {
+    return new Promise((resolve, reject) => {
+        navigator.geolocation.getCurrentPosition(resolve, reject, {
+            enableHighAccuracy: false,
+            timeout: timeoutMs,
+            maximumAge: 0,
+        });
+    });
+}
+/**
+ * Get the device position and check it against the allowed zones.
+ *
+ * Returns `{ ok: true, coords }` when a fix lands inside any zone — the app can
+ * forward `coords` to a workflow to record where the action happened. Otherwise
+ * `{ ok: false, reason }`; render guidance per `reason`. An empty `zones` array
+ * means "no geofence" and resolves `ok` with the raw position (use it for a
+ * plain location read).
+ *
+ * ```tsx
+ * const r = await requestGeofencedLocation(DEPOTS);
+ * if (!r.ok) return showGeofenceError(r.reason);
+ * await chamCong();
+ * ```
+ */
+export async function requestGeofencedLocation(zones, opts) {
+    const timeoutMs = opts?.timeoutMs ?? 15_000;
+    if (typeof navigator === "undefined" || !navigator.geolocation) {
+        return { ok: false, reason: "unavailable" };
+    }
+    // Fast-path a hard denial: once blocked, the browser will not re-prompt, so
+    // calling getCurrentPosition would just hang until the timeout.
+    if ((await readPermissionState()) === "denied") {
+        return { ok: false, reason: "denied" };
+    }
+    let position;
+    try {
+        position = await getPosition(timeoutMs);
+    }
+    catch (err) {
+        const code = err?.code;
+        // 1 = PERMISSION_DENIED; 2 = POSITION_UNAVAILABLE; 3 = TIMEOUT.
+        return { ok: false, reason: code === 1 ? "denied" : "unavailable" };
+    }
+    const coords = {
+        latitude: position.coords.latitude,
+        longitude: position.coords.longitude,
+        accuracy: position.coords.accuracy,
+    };
+    const inside = zones.length === 0 || zones.some((z) => isWithinZone(coords.latitude, coords.longitude, z));
+    return inside ? { ok: true, coords } : { ok: false, reason: "outside" };
+}

package/dist/src/index.d.ts

@@ -21,6 +21,8 @@ export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions
 export { useComments } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs } from "./comments.js";
 export { useViewer } from "./viewer.js";
+export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
+export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";

package/dist/src/index.js

@@ -18,6 +18,7 @@ export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
 export { useComments } from "./comments.js";
 export { useViewer } from "./viewer.js";
+export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {