@lotics/app-sdk 0.100.0 → 0.101.0

package/dist/src/ask_ai.js

@@ -1,35 +0,0 @@
-import { rpc } from "./rpc.js";
-/**
- * Hand off to the Lotics chat agent — opens the messenger on a FRESH chat
- * seeded with the given files, records, and prompt.
- *
- * Use this for dialogue-shaped work: iterating on a document ("edit this
- * invoice"), drafting from record context, open-ended questions. For
- * structured judgment that commits back into the app's own data
- * (extract/check/match/rank), use `useAgentRun` with a review surface
- * instead — the outcome of `askAi` lands in chat, not in your workflows.
- *
- * The user stays in control: the prompt is only prefilled, attachments are
- * visible in the composer, and nothing is sent until they press send.
- *
- * ```tsx
- * import { askAi } from "@lotics/app-sdk";
- * await askAi({
- *   file_ids: [file.id],
- *   record_ids: [row.id],
- *   prompt: "Update the header of this invoice to match our letterhead.",
- * });
- * ```
- *
- * Only available embedded in Lotics — rejects in standalone/dev mode.
- */
-export function askAi(args) {
-    const hasPayload = (args.prompt ?? "") !== "" ||
-        (args.file_ids?.length ?? 0) > 0 ||
-        (args.record_ids?.length ?? 0) > 0 ||
-        (args.context ?? "") !== "";
-    if (!hasPayload) {
-        return Promise.reject(new Error("askAi requires at least one of prompt, file_ids, record_ids, context"));
-    }
-    return rpc("askAi", args);
-}

package/dist/src/attachments.d.ts

@@ -1,68 +0,0 @@
-import type { ImageFidelity } from "./upload/optimize.js";
-/** A file attached to a surface — its local preview is available immediately,
- *  its stored `file_id` once the background upload completes. */
-export interface AttachedFile {
-    /** Stable local id — the React key and the `remove(id)` handle. */
-    id: string;
-    filename: string;
-    mime_type: string;
-    /** Local object-URL preview, available the INSTANT the file is added (before upload). */
-    preview_url: string;
-    status: "uploading" | "ready" | "error";
-    /** The stored file id, set once `status` is `"ready"` — pass to a workflow/agent. */
-    file_id?: string;
-}
-export interface AttachmentsOptions {
-    /**
-     * The stored ids the DESTINATION now holds. Every queued entry among them has
-     * arrived, so it leaves the queue and its preview URL is revoked.
-     *
-     * This is what makes the queue a record's rather than a composer's: pass what
-     * the row came back with and the queue hands over to the pile exactly as the
-     * pile takes it, with no window where neither is on screen. Pass nothing and
-     * the queue accumulates until `clear`.
-     */
-    landed?: readonly string[];
-}
-export interface AttachmentsState {
-    /** The current attachments, in the order added. */
-    files: AttachedFile[];
-    /**
-     * Add picked/pasted/dropped files — each shows its local preview at once and
-     * uploads in the background. Picking is the app's choice: wire a button to
-     * `@lotics/ui` `pickFiles`, or a paste/drop handler, then call this.
-     */
-    add: (files: File[], options?: {
-        fidelity?: ImageFidelity;
-    }) => void;
-    /**
-     * The same add, ANSWERED WHEN EVERY ONE OF THEM IS STORED — the ids, in the
-     * order given. What a write waits on: a record told it holds files whose
-     * bytes are still going up names ids the workspace does not have.
-     *
-     * Rejects with the first refusal instead of answering short, and the queue
-     * keeps every entry with its own status, so the reader sees which one failed
-     * and the ones that succeeded are not silently written without it.
-     */
-    attach: (files: File[], options?: {
-        fidelity?: ImageFidelity;
-    }) => Promise<string[]>;
-    /** Remove one attachment and revoke its preview URL. */
-    remove: (id: string) => void;
-    /** Remove all attachments and revoke their preview URLs. */
-    clear: () => void;
-    /** True while any attachment is still uploading — gate Send on it. */
-    uploading: boolean;
-    /** Stored file ids of the completed uploads — the workflow/agent payload. */
-    fileIds: string[];
-}
-/**
- * The queue itself, over whichever upload the caller runs through. `upload` is
- * typed by what this needs of it — a stored id — so the transport is the
- * caller's to bring.
- */
-export declare function useAttachmentQueue(upload: (file: File, options?: {
-    fidelity?: ImageFidelity;
-}) => Promise<{
-    id: string;
-}>, options?: AttachmentsOptions): AttachmentsState;

package/dist/src/attachments.js

@@ -1,93 +0,0 @@
-/**
- * THE ADD-QUEUE — one owner of the preview → upload → id → revoke lifecycle,
- * apart from the transport that carries the bytes.
- *
- * A surface that takes files has the same four moments wherever it stands: a
- * local preview the instant one is picked, an upload in the background, the
- * stored id when it lands, and the object URL revoked when the entry is done
- * with. What differs is only WHEN an entry is done with — a composer keeps its
- * pile until it sends, a record's section keeps one until the row comes back
- * holding it — so the lifecycle is stated once and the caller says which.
- *
- * Parameterised by the upload rather than reaching for it, so the queue is the
- * same queue wherever the bytes go.
- */
-import { useCallback, useEffect, useState } from "react";
-let attachSeq = 0;
-/**
- * What the landed ids are joined by to make the effect's one dependency, and
- * split back on. A stored id is an opaque token with no punctuation in it; one
- * that carried this would simply not match, leaving its own tile standing —
- * never taking a different one away.
- */
-const LANDED_SEPARATOR = ",";
-/**
- * The queue itself, over whichever upload the caller runs through. `upload` is
- * typed by what this needs of it — a stored id — so the transport is the
- * caller's to bring.
- */
-export function useAttachmentQueue(upload, options) {
-    const [files, setFiles] = useState([]);
-    const start = useCallback((file, uploadOptions) => {
-        const id = `att_${(attachSeq += 1)}`;
-        const previewUrl = URL.createObjectURL(file);
-        setFiles((prev) => [
-            ...prev,
-            { id, filename: file.name, mime_type: file.type, preview_url: previewUrl, status: "uploading" },
-        ]);
-        // SETTLES, NEVER REJECTS: the queue entry is where a failure is recorded,
-        // so a caller that only wanted the preview holds no rejected promise.
-        return upload(file, uploadOptions).then((uploaded) => {
-            setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "ready", file_id: uploaded.id } : f)));
-            return { kind: "stored", id: uploaded.id };
-        }, (cause) => {
-            setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "error" } : f)));
-            return { kind: "failed", reason: cause instanceof Error ? cause : new Error(String(cause)) };
-        });
-    }, [upload]);
-    const add = useCallback((incoming, uploadOptions) => {
-        for (const file of incoming)
-            void start(file, uploadOptions);
-    }, [start]);
-    const attach = useCallback(async (incoming, uploadOptions) => {
-        const settled = await Promise.all(incoming.map((file) => start(file, uploadOptions)));
-        const refused = settled.find((one) => one.kind === "failed");
-        if (refused?.kind === "failed")
-            throw refused.reason;
-        return settled.flatMap((one) => (one.kind === "stored" ? [one.id] : []));
-    }, [start]);
-    const remove = useCallback((id) => {
-        setFiles((prev) => {
-            const target = prev.find((f) => f.id === id);
-            if (target)
-                URL.revokeObjectURL(target.preview_url);
-            return prev.filter((f) => f.id !== id);
-        });
-    }, []);
-    const clear = useCallback(() => {
-        setFiles((prev) => {
-            for (const f of prev)
-                URL.revokeObjectURL(f.preview_url);
-            return [];
-        });
-    }, []);
-    // The IDS are the dependency, not the array holding them: a caller reading
-    // them off a row builds a fresh array every render.
-    const landedKey = options?.landed === undefined ? null : options.landed.join(LANDED_SEPARATOR);
-    useEffect(() => {
-        if (landedKey === null)
-            return;
-        const taken = new Set(landedKey === "" ? [] : landedKey.split(LANDED_SEPARATOR));
-        setFiles((prev) => {
-            const arrived = prev.filter((f) => f.file_id !== undefined && taken.has(f.file_id));
-            if (arrived.length === 0)
-                return prev;
-            for (const f of arrived)
-                URL.revokeObjectURL(f.preview_url);
-            return prev.filter((f) => !arrived.includes(f));
-        });
-    }, [landedKey]);
-    const uploading = files.some((f) => f.status === "uploading");
-    const fileIds = files.flatMap((f) => (f.status === "ready" && f.file_id ? [f.file_id] : []));
-    return { files, add, attach, remove, clear, uploading, fileIds };
-}

package/dist/src/comments.d.ts

@@ -1,127 +0,0 @@
-/** A file attached to a comment, in the resolved (serving) shape the list returns. */
-export interface AppCommentFile {
-    id: string;
-    filename: string;
-    mime_type: string;
-    url?: string;
-    thumbnail_url?: string;
-    preview_url?: string;
-}
-/** A comment author's display identity, resolved server-side. */
-export interface AppCommentAuthor {
-    /** The member's display name. Null when the id no longer resolves in the org
-     *  (a removed member) — fall back explicitly, as with `readMembers`. */
-    name: string | null;
-    /** Presigned avatar URL, when the member has one. */
-    image?: string | null;
-}
-/** One record comment, as returned by the list op. */
-export interface AppComment {
-    id: string;
-    record_id: string;
-    table_id: string;
-    /** The author's member id. */
-    member_id: string;
-    /**
-     * The author's display identity, resolved server-side on EVERY comment the
-     * server returns — list, create and update alike — including one written from
-     * another app by someone the record references nowhere. A thread crossing a
-     * role boundary is legible without the app declaring member access it does not
-     * otherwise need.
-     *
-     * Optional for one reason only: the optimistic row `createComment` renders is
-     * built HERE, from a context that carries the viewer's id and not their name,
-     * and inventing a display identity for it would render as somebody. It is
-     * replaced by the server's row when the refetch lands.
-     */
-    author?: AppCommentAuthor;
-    content: string;
-    files: AppCommentFile[] | null;
-    workspace_id: string;
-    created_at: string;
-    updated_at: string;
-}
-export interface CommentsState {
-    /** Comments on the record, oldest first. Empty while loading or unavailable. */
-    comments: AppComment[];
-    /** True on the initial load only — false during background revalidation. */
-    loading: boolean;
-    error: string | null;
-    /**
-     * True only when a member is signed in AND the app declared the `comments`
-     * capability in its manifest. False in a standalone / public (anonymous) app,
-     * and for any app that didn't opt in. Gate the composer on this; mutations
-     * reject (and the backend re-checks the capability) when false.
-     */
-    available: boolean;
-    /**
-     * Post a new comment as the viewing member. `file_ids` are ids from
-     * `useFileUpload().upload()`. No-op for empty content with no files.
-     */
-    createComment: (input: {
-        content: string;
-        file_ids?: string[];
-    }) => Promise<void>;
-    /**
-     * Edit a comment (author-only, enforced server-side). Pass `files` to replace
-     * the attachment set; omit it to keep the comment's current files — a
-     * text-only edit never silently drops attachments.
-     */
-    updateComment: (id: string, input: {
-        content: string;
-        files?: AppCommentFile[];
-    }) => Promise<void>;
-    /** Delete a comment (author-only, enforced server-side). */
-    deleteComment: (id: string) => Promise<void>;
-    /** Re-pull the thread from the server (e.g. after an external change). */
-    refetch: () => void;
-}
-export interface UseCommentsArgs {
-    /** The record whose comments to read and write. */
-    record_id: string;
-}
-/**
- * `record_id` must be a REAL id. The fetch keys on `available` alone, so an
- * empty string is not skipped — it fetches comments for nothing. When the id
- * comes off a row's `__source_record_id` addressing column, narrow it first: a
- * grouped query carries none, and a hook cannot be called conditionally, so the
- * guard belongs at the component that renders the panel.
- *
- * ```tsx
- * // In a record screen, where an id definitionally exists:
- * const { comments, available, createComment } = useComments({ record_id: recordId });
- *
- * // From a row, gate the whole panel rather than passing a placeholder:
- * {row.__source_record_id && <CommentsPanel recordId={row.__source_record_id} />}
- * ```
- */
-export declare function useComments(args: UseCommentsArgs): CommentsState;
-export interface CommentCountsState {
-    /** `{ record_id: count }`. Empty while loading or unavailable. */
-    counts: Record<string, number>;
-    /** True on the initial load only — false during background revalidation. */
-    loading: boolean;
-    error: string | null;
-    /** Same gate as `useComments` — member signed in AND the app declared `comments`. */
-    available: boolean;
-    /** Re-pull the counts (e.g. after posting a comment). */
-    refetch: () => void;
-}
-export interface UseCommentCountsArgs {
-    /** The table whose per-record comment counts to read. Read it off a row
-     *  (`__source_table_id`) rather than pasting a `tbl_` id — a copy of the app
-     *  runs over other tables. `undefined` (no row on screen yet) sends no
-     *  request and answers `{}`. */
-    table_id: string | undefined;
-}
-/**
- * Per-record comment counts for a whole table, as `{ record_id: count }` — for
- * row badges (a count beside each row) without loading any comment content. One
- * server-side `GROUP BY`. App-authority like {@link useComments}.
- *
- * ```tsx
- * const { counts } = useCommentCounts({ table_id: rows[0]?.__source_table_id });
- * // counts[row.__source_record_id] ?? 0
- * ```
- */
-export declare function useCommentCounts(args: UseCommentCountsArgs): CommentCountsState;

package/dist/src/comments.js

@@ -1,192 +0,0 @@
-/**
- * `useComments` — read and write the comments on a record from a custom-code app.
- *
- * Comments are a *members-only* surface but, like `useQuery` / `useWorkflow`,
- * run under the app's authority — NOT the member's table IAM. An app user with
- * the app open (and the app declaring `comments`) may read/write comments on any
- * record the app reaches, regardless of their own table access:
- *
- *   - read / write gated by `app:use` + the `comments` capability (no table grant)
- *   - the comment's author is still the real viewing member (correct attribution)
- *   - edit / delete are author-only, checked against the viewer
- *
- * `useCommentCounts` returns per-record counts for a table (row badges) — a
- * single server-side `GROUP BY`, no comment content shipped.
- *
- * The bridged host (`app_iframe_host`) proxies each op to the app-scoped
- * `/v1/apps/{id}/…/comments` endpoints. A standalone (public) app has no
- * signed-in member: `available` is false, lists stay empty, and a mutation
- * rejects. Check `available` before rendering a composer.
- *
- * Freshness: SWR-cached, revalidate on focus / reconnect, and an explicit
- * refetch after every mutation — so another viewer's comment appears on the
- * next focus or `refetch()`, not on its own.
- *
- * This is the one read hook that does NOT keep itself current, and the reason
- * is worth knowing rather than guessing: the realtime channel carries **record**
- * changes, and a comment is its own entity that emits no record event. Your
- * QUERIES do get pushed (`docs/data_fetching.md`) — do not read this as "apps
- * have no realtime" and go build a poll.
- */
-import { useCallback } from "react";
-import useSWR from "swr";
-import { rpc } from "./rpc.js";
-import { useAppContext } from "./viewer.js";
-/**
- * The attachment set as ids — what the update endpoint wants.
- *
- * Sending whole file objects instead would be a full-snapshot write of metadata
- * this client does not own: a filename or a storage key echoed back from a read
- * lands in the row verbatim, so a stale copy overwrites what is stored. An id
- * the server resolves for itself cannot do that.
- */
-function toFileIds(files) {
-    return (files ?? []).map((f) => f.id);
-}
-let optimisticCounter = 0;
-/**
- * `record_id` must be a REAL id. The fetch keys on `available` alone, so an
- * empty string is not skipped — it fetches comments for nothing. When the id
- * comes off a row's `__source_record_id` addressing column, narrow it first: a
- * grouped query carries none, and a hook cannot be called conditionally, so the
- * guard belongs at the component that renders the panel.
- *
- * ```tsx
- * // In a record screen, where an id definitionally exists:
- * const { comments, available, createComment } = useComments({ record_id: recordId });
- *
- * // From a row, gate the whole panel rather than passing a placeholder:
- * {row.__source_record_id && <CommentsPanel recordId={row.__source_record_id} />}
- * ```
- */
-export function useComments(args) {
-    const { record_id } = args;
-    const { memberId, commentsEnabled, resolved } = useAppContext();
-    const available = memberId != null && commentsEnabled;
-    const swr = useSWR(available ? ["app-comments", record_id] : null, () => rpc("comments.list", { record_id }), {
-        shouldRetryOnError: false,
-    });
-    const comments = swr.data?.comments ?? [];
-    const refetch = useCallback(() => {
-        void swr.mutate();
-    }, [swr]);
-    const createComment = useCallback(async (input) => {
-        if (!available || memberId == null) {
-            throw new Error("Comments are not available in this app.");
-        }
-        const content = input.content.trim();
-        const fileIds = input.file_ids ?? [];
-        if (!content && fileIds.length === 0)
-            return;
-        const now = new Date().toISOString();
-        const optimistic = {
-            id: `cmt_optimistic_${Date.now()}_${optimisticCounter++}`,
-            record_id,
-            // table_id / workspace_id resolve on the refetch (server-owned); the
-            // optimistic row only needs to render until then.
-            table_id: "",
-            member_id: memberId,
-            content,
-            // The real attachments resolve on the refetch; show none meanwhile.
-            files: null,
-            workspace_id: "",
-            created_at: now,
-            updated_at: now,
-        };
-        await swr.mutate(async () => {
-            await rpc("comments.create", {
-                record_id,
-                content,
-                file_ids: fileIds.length > 0 ? fileIds : undefined,
-            });
-            return rpc("comments.list", { record_id });
-        }, {
-            optimisticData: (current) => ({
-                comments: [...(current?.comments ?? []), optimistic],
-            }),
-            rollbackOnError: true,
-            revalidate: false,
-            populateCache: true,
-        });
-    }, [available, memberId, record_id, swr]);
-    const updateComment = useCallback(async (id, input) => {
-        if (!available)
-            throw new Error("Comments are not available in this app.");
-        const content = input.content.trim();
-        // Omitted files → keep the comment's current attachments (never drop them
-        // on a text-only edit). The update endpoint replaces the whole set.
-        const currentFiles = input.files !== undefined
-            ? input.files
-            : (swr.data?.comments.find((c) => c.id === id)?.files ?? null);
-        const now = new Date().toISOString();
-        await swr.mutate(async () => {
-            await rpc("comments.update", {
-                record_id,
-                comment_id: id,
-                content,
-                file_ids: toFileIds(currentFiles),
-            });
-            return rpc("comments.list", { record_id });
-        }, {
-            optimisticData: (current) => ({
-                comments: (current?.comments ?? []).map((c) => c.id === id ? { ...c, content, files: currentFiles, updated_at: now } : c),
-            }),
-            rollbackOnError: true,
-            revalidate: false,
-            populateCache: true,
-        });
-    }, [available, record_id, swr]);
-    const deleteComment = useCallback(async (id) => {
-        if (!available)
-            throw new Error("Comments are not available in this app.");
-        await swr.mutate(async () => {
-            await rpc("comments.delete", { record_id, comment_id: id });
-            return rpc("comments.list", { record_id });
-        }, {
-            optimisticData: (current) => ({
-                comments: (current?.comments ?? []).filter((c) => c.id !== id),
-            }),
-            rollbackOnError: true,
-            revalidate: false,
-            populateCache: true,
-        });
-    }, [available, record_id, swr]);
-    return {
-        comments,
-        // Unavailable resolves instantly (no fetch); available shows the initial
-        // load until the list lands. Waiting on context counts as loading.
-        loading: available ? swr.isLoading : !resolved,
-        error: swr.error ? swr.error.message : null,
-        available,
-        createComment,
-        updateComment,
-        deleteComment,
-        refetch,
-    };
-}
-/**
- * Per-record comment counts for a whole table, as `{ record_id: count }` — for
- * row badges (a count beside each row) without loading any comment content. One
- * server-side `GROUP BY`. App-authority like {@link useComments}.
- *
- * ```tsx
- * const { counts } = useCommentCounts({ table_id: rows[0]?.__source_table_id });
- * // counts[row.__source_record_id] ?? 0
- * ```
- */
-export function useCommentCounts(args) {
-    const { table_id } = args;
-    const { memberId, commentsEnabled, resolved } = useAppContext();
-    const available = memberId != null && commentsEnabled;
-    const swr = useSWR(available && table_id !== undefined ? ["app-comment-counts", table_id] : null, () => rpc("comments.counts", { table_id }), { shouldRetryOnError: false });
-    const refetch = useCallback(() => {
-        void swr.mutate();
-    }, [swr]);
-    return {
-        counts: swr.data ?? {},
-        loading: available ? swr.isLoading : !resolved,
-        error: swr.error ? swr.error.message : null,
-        available,
-        refetch,
-    };
-}

package/dist/src/download.js

@@ -1,54 +0,0 @@
-/**
- * Save bytes the app generated in the browser to the visitor's device.
- *
- * This is the client-side counterpart to `openExternal`. The platform's other
- * download path is server-side: a workflow generates a file, it comes back in
- * `WorkflowResult.files[]` with a `.url`, and the app opens that URL with
- * `openExternal`. But data an app builds *in the browser* (an .xlsx exported
- * from a query result, a CSV, a generated PDF) never gets a server URL — there
- * was no primitive to save it. This is that primitive.
- *
- * It is pure DOM, not an RPC: the embed iframe is sandboxed with
- * `allow-downloads` (see `app_iframe_host`), so a same-origin blob download
- * triggered from a user gesture is permitted without host mediation. In
- * standalone (public) mode the app is a normal top-level page, where downloads
- * always work. Call it synchronously from the click handler that produced the
- * bytes so the browser attributes the download to the user gesture.
- *
- * ```tsx
- * import { downloadFile } from "@lotics/app-sdk";
- * import { buildDataWorkbook, exportWorkbook } from "@lotics/xlsx";
- *
- * const wb = buildDataWorkbook({ columns, rows });
- * downloadFile("report.xlsx", exportWorkbook(wb), XLSX_MIME);
- * ```
- */
-const DEFAULT_MIME = "application/octet-stream";
-function toBlob(data, mimeType) {
-    if (data instanceof Blob)
-        return data;
-    if (typeof data === "string")
-        return new Blob([data], { type: mimeType });
-    // Re-wrap the bytes: the DOM lib types a generic `Uint8Array<ArrayBufferLike>`
-    // as incompatible with `BlobPart`, and `new Uint8Array(data)` narrows it to a
-    // fresh `ArrayBuffer`-backed view (the pattern `save_workbook_version` uses).
-    return new Blob([new Uint8Array(data)], { type: mimeType });
-}
-export function downloadFile(filename, data, mimeType) {
-    const url = URL.createObjectURL(toBlob(data, mimeType ?? DEFAULT_MIME));
-    try {
-        const a = document.createElement("a");
-        a.href = url;
-        a.download = filename;
-        a.rel = "noopener";
-        a.style.display = "none";
-        document.body.appendChild(a);
-        a.click();
-        a.remove();
-    }
-    finally {
-        // Revoke after the current task so the navigation to the blob URL has
-        // started — revoking synchronously can cancel the download in some browsers.
-        setTimeout(() => URL.revokeObjectURL(url), 0);
-    }
-}

package/dist/src/geolocation.d.ts

@@ -1,64 +0,0 @@
-/**
- * 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>;