@lotics/app-sdk 0.28.0 → 0.30.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/hooks.d.ts

@@ -1,4 +1,4 @@
-import type { AppWorkflows, AppQueries } from "./types.js";
+import type { AppWorkflows, AppWorkflowResults, AppQueries } from "./types.js";
 import type { ResolvedMember } from "./members.js";
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
@@ -151,17 +151,21 @@ export interface PaginatedQueryOptions extends BaseQueryOptions {
  */
 export declare function useWorkflow<K extends keyof AppWorkflows & string>(alias: K): UseWorkflowFn<K>;
 export declare function useWorkflow(alias: string): (inputs?: Record<string, unknown>) => Promise<WorkflowResult>;
-type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? AppWorkflows[K] extends Record<string, never> ? (inputs?: Record<string, never>) => Promise<WorkflowResult> : (inputs: AppWorkflows[K]) => Promise<WorkflowResult> : (inputs?: Record<string, unknown>) => Promise<WorkflowResult>;
+type ResultDataOf<K extends string> = K extends keyof AppWorkflowResults ? AppWorkflowResults[K] : unknown;
+type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? AppWorkflows[K] extends Record<string, never> ? (inputs?: Record<string, never>) => Promise<WorkflowResult<ResultDataOf<K>>> : (inputs: AppWorkflows[K]) => Promise<WorkflowResult<ResultDataOf<K>>> : (inputs?: Record<string, unknown>) => Promise<WorkflowResult<ResultDataOf<K>>>;
 /**
  * Result of an app-workflow run — the execute endpoint's response. `files` holds
  * any document a workflow step generated (e.g. via a `generate_*_from_template`
  * tool), resolved for download: read `files[0].url` and pass it to `openExternal`.
- * A workflow that generates no file resolves with `files` absent.
+ * A workflow that generates no file resolves with `files` absent. `data` is the
+ * structured value the workflow returned via `return({ data })`, typed per the
+ * alias's declared `outputs` schema (`unknown` when none was declared).
  */
-export interface WorkflowResult {
+export interface WorkflowResult<TData = unknown> {
     status: "success" | "error";
     message?: string;
     files?: UploadedFile[];
+    data?: TData;
 }
 type QueryArgs<K extends keyof AppQueries & string, O> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: O] : [params: AppQueries[K], opts?: O];
 /**

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/dist/src/types.d.ts

@@ -23,6 +23,27 @@
  */
 export interface AppWorkflows {
 }
+/**
+ * App-specific workflow-RESULT augmentation point. Same pattern as AppWorkflows,
+ * but maps each alias to the type of the `data` its workflow returns via
+ * `return({ data })` — derived from the alias's declared `outputs` schema.
+ *
+ * The base SDK ships it empty, so `useWorkflow(alias)` resolves `result.data` as
+ * `unknown`. Per-app codegen augments it for aliases that declare `outputs`:
+ *
+ * ```ts
+ * // .lotics/app_workflows.d.ts (generated)
+ * declare module "@lotics/app-sdk" {
+ *   interface AppWorkflowResults {
+ *     "computeQuote": { total: number; lines: ReadonlyArray<{ name: string; amount: number }> };
+ *   }
+ * }
+ * ```
+ *
+ * An alias absent from this map (no declared `outputs`) gets `result.data: unknown`.
+ */
+export interface AppWorkflowResults {
+}
 /**
  * App-specific named-query augmentation point. Same pattern as AppWorkflows.
  *

package/package.json

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