@lotics/app-sdk 0.27.0 → 0.29.0

package/dist/src/comments.js

@@ -24,6 +24,7 @@ import { useCallback } from "react";
 import useSWR from "swr";
 import { rpc } from "./rpc.js";
 import { captureAppEvent } from "./analytics.js";
+import { useAppContext } from "./viewer.js";
 /** The reduced storage shape the update endpoint accepts for `files`. */
 function toStorageFiles(files) {
     return (files ?? []).map((f) => ({
@@ -33,24 +34,6 @@ function toStorageFiles(files) {
         mime_type: f.mime_type,
     }));
 }
-/**
- * Read the app's context once, shared across every hook via a stable SWR key.
- * Comments need a signed-in member (members-only) AND the app's declared
- * `comments` capability — both come from here.
- */
-function useAppContext() {
-    const { data } = useSWR("app-context", () => rpc("context", {}), {
-        revalidateOnFocus: false,
-        revalidateIfStale: false,
-        revalidateOnReconnect: false,
-        shouldRetryOnError: false,
-    });
-    return {
-        memberId: data?.member_id ?? null,
-        commentsEnabled: data?.comments_enabled ?? false,
-        resolved: data !== undefined,
-    };
-}
 let optimisticCounter = 0;
 /**
  * ```tsx

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

@@ -20,6 +20,9 @@ export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUplo
 export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
 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

@@ -17,6 +17,8 @@
 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/dist/src/viewer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read the app's context once, shared across every hook via a stable SWR key.
+ * The host (the product iframe, or `lotics app dev`) supplies the signed-in
+ * member and the app's declared capabilities.
+ */
+export declare function useAppContext(): {
+    memberId: string | null;
+    commentsEnabled: boolean;
+    resolved: boolean;
+};
+/**
+ * The signed-in member currently viewing the app — the **view-as target** under
+ * an admin's "View as" (product UI or `lotics app dev --view-as`), the
+ * authenticated member otherwise, and `null` for a public/standalone visitor or
+ * until the context resolves (gate viewer-dependent UI on `loading`).
+ *
+ * Use it to personalize (greet the member, default an assignment to them) or to
+ * pass the viewer into a workflow that must attribute to them. **Per-row data
+ * scoping does NOT need this** — put an `is_current_member` filter in the query
+ * template and the server resolves it to the same member (honoring view-as).
+ */
+export declare function useViewer(): {
+    memberId: string | null;
+    loading: boolean;
+};

package/dist/src/viewer.js

@@ -0,0 +1,35 @@
+import useSWR from "swr";
+import { rpc } from "./rpc.js";
+/**
+ * Read the app's context once, shared across every hook via a stable SWR key.
+ * The host (the product iframe, or `lotics app dev`) supplies the signed-in
+ * member and the app's declared capabilities.
+ */
+export function useAppContext() {
+    const { data } = useSWR("app-context", () => rpc("context", {}), {
+        revalidateOnFocus: false,
+        revalidateIfStale: false,
+        revalidateOnReconnect: false,
+        shouldRetryOnError: false,
+    });
+    return {
+        memberId: data?.member_id ?? null,
+        commentsEnabled: data?.comments_enabled ?? false,
+        resolved: data !== undefined,
+    };
+}
+/**
+ * The signed-in member currently viewing the app — the **view-as target** under
+ * an admin's "View as" (product UI or `lotics app dev --view-as`), the
+ * authenticated member otherwise, and `null` for a public/standalone visitor or
+ * until the context resolves (gate viewer-dependent UI on `loading`).
+ *
+ * Use it to personalize (greet the member, default an assignment to them) or to
+ * pass the viewer into a workflow that must attribute to them. **Per-row data
+ * scoping does NOT need this** — put an `is_current_member` filter in the query
+ * template and the server resolves it to the same member (honoring view-as).
+ */
+export function useViewer() {
+    const ctx = useAppContext();
+    return { memberId: ctx.memberId, loading: !ctx.resolved };
+}

package/package.json

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