@lotics/app-sdk 0.100.1 → 0.101.0

package/dist/comments.d.ts

@@ -0,0 +1,89 @@
+export interface AppCommentFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+    preview_url?: string;
+}
+export interface AppCommentAuthor {
+    /** Null for a removed member — fall back explicitly, as with `readMembers`. */
+    name: string | null;
+    image?: string | null;
+}
+export interface AppComment {
+    id: string;
+    record_id: string;
+    table_id: string;
+    member_id: string;
+    /**
+     * Resolved server-side on every comment, so a cross-role thread is legible
+     * without member access. Absent only on the optimistic row, until the refetch.
+     */
+    author?: AppCommentAuthor;
+    content: string;
+    files: AppCommentFile[] | null;
+    workspace_id: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CommentsState {
+    /** Oldest first. */
+    comments: AppComment[];
+    loading: boolean;
+    error: string | null;
+    /** A signed-in member and the `comments` capability; gate the composer on it — mutations reject otherwise. */
+    available: boolean;
+    /** `file_ids` from `useFileUpload().upload()`; no-op when empty. */
+    createComment: (input: {
+        content: string;
+        file_ids?: string[];
+    }) => Promise<void>;
+    /** Author-only. `files` replaces the set; omitted, the current files are kept. */
+    updateComment: (id: string, input: {
+        content: string;
+        files?: AppCommentFile[];
+    }) => Promise<void>;
+    /** Author-only. */
+    deleteComment: (id: string) => Promise<void>;
+    refetch: () => void;
+}
+export interface UseCommentsArgs {
+    record_id: string;
+}
+/**
+ * `record_id` must be a real id — an empty string still fetches. Gate the
+ * panel on a row's `__source_record_id`, which a grouped query lacks.
+ *
+ * ```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 }`. */
+    counts: Record<string, number>;
+    loading: boolean;
+    error: string | null;
+    /** As `useComments`. */
+    available: boolean;
+    refetch: () => void;
+}
+export interface UseCommentCountsArgs {
+    /** Read off a row's `__source_table_id`, never a pasted `tbl_` (a copy runs over other tables); `undefined` answers `{}`. */
+    table_id: string | undefined;
+}
+/**
+ * Per-record comment counts for row badges, one server-side `GROUP BY` with no
+ * content. 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/error_report.d.ts

@@ -0,0 +1,9 @@
+import { type AppErrorReport } from "./rpc.js";
+/** Where an error surfaced: `mount()`'s `error` / `unhandledrejection` listeners, or a JSON app's spec refused at load. */
+export type AppErrorKind = AppErrorReport["kind"];
+/**
+ * Tells the host an error the app did not handle, so it reaches Lotics's error tracking. Fire-and-forget,
+ * the first five per page load, and inert standalone. Every origin is cut from what leaves: the app's own
+ * is its bearer slug.
+ */
+export declare function reportAppError(kind: AppErrorKind, error: unknown): void;

package/dist/folder_pick.d.ts

@@ -0,0 +1,8 @@
+export interface FolderPick {
+    /** The folder's record id; `null` where the viewer has picked none, `undefined` while it is read. */
+    picked: string | null | undefined;
+    /** Keep this folder for the viewer, or (`null`) none. */
+    pick: (id: string | null) => void;
+}
+/** The folder the viewer works inside for one folder table, and a way to change it. */
+export declare function useFolderPick(table: string): FolderPick;

package/dist/geolocation.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Geofenced device location, read directly (the host grants the iframe the
+ * `geolocation` Permissions-Policy). Failure is a structured `reason`, so the
+ * app words its own guidance.
+ */
+/** Center `[latitude, longitude]`, radius in meters. */
+export interface GeofenceZone {
+    coordinates: [number, number];
+    radius: number;
+}
+export interface GeoCoords {
+    latitude: number;
+    longitude: number;
+    /** Meters. */
+    accuracy: number;
+}
+/**
+ * `denied`: no permission. `unavailable`: no fix (services off, no GPS,
+ * timeout). `outside`: a fix, in no zone.
+ */
+export type GeofenceOutcome = {
+    ok: true;
+    coords: GeoCoords;
+} | {
+    ok: false;
+    reason: "denied" | "unavailable" | "outside";
+};
+export interface GeofenceOptions {
+    /** Default 15000. */
+    timeoutMs?: number;
+}
+export declare function isWithinZone(latitude: number, longitude: number, zone: GeofenceZone): boolean;
+/**
+ * The position checked against the zones; empty `zones` is a plain 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/hooks.d.ts

@@ -0,0 +1,251 @@
+import { type ImageFidelity } from "./upload/optimize.js";
+import { type AttachmentPiles, type AttachmentPilesOptions, type AttachmentsOptions, type AttachmentsState } from "./attachments.js";
+import { type AiContextValue } from "./rpc.js";
+import { type AgentUIPart, type PendingChoice, type AgentRunLanding } from "./agent_stream.js";
+import type { AppWorkflows, AppWorkflowResults, AppAgents, AppAgentResults } from "./types.js";
+import type { ResolvedMember } from "./members.js";
+export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, AgentRunLanding } from "./agent_stream.js";
+export { buildChoiceOutput } from "./agent_stream.js";
+/**
+ * Trigger a workflow by alias. Codegen types the inputs per the declaration;
+ * an undeclared alias is a compile error.
+ *
+ * ```tsx
+ * const issue = useWorkflow("issueInvoiceStorageDrop");
+ * // Guard the addressing column: a grouped query's rows carry none, and the
+ * // workflow would be handed `undefined` where it declares a record.
+ * if (row.__source_record_id) await issue({ record_id: row.__source_record_id });
+ * ```
+ */
+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>;
+/**
+ * A runner per workflow alias, for a surface whose workflows are data (a spec's acts and saves) rather
+ * than a fixed call per component. Each runs exactly as `useWorkflow`'s does.
+ */
+export declare function useWorkflows(aliases: readonly string[]): Readonly<Record<string, (inputs?: Record<string, unknown>) => Promise<WorkflowResult>>>;
+/**
+ * Once every record write of this app already sent has answered — a workflow's or an agent's — for a press
+ * that reads stored state (an act, a document) after a value typed just before it, so the read never
+ * overtakes the write. A write sent after the call is not waited for.
+ */
+export declare function writesSettled(): Promise<void>;
+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>>>;
+/**
+ * An app-workflow run's result. It never rejects: a gateway failure (524, any
+ * 5xx, a non-JSON page) resolves `{ status: "error", message }`. `files` holds
+ * any generated document; `data` is the `return({ data })` value.
+ */
+export interface WorkflowResult<TData = unknown> {
+    status: "success" | "error";
+    message?: string;
+    files?: UploadedFile[];
+    data?: TData;
+    /**
+     * Per-input refusals keyed by the declared INPUT name, from the server's
+     * payload check or the workflow's `return({ field_errors })`; a table's own
+     * refusal keys by `fld_…`. Absent when nothing named a field.
+     */
+    field_errors?: Record<string, string>;
+}
+/** A file the host has stored and resolved serving URLs for. */
+export interface UploadedFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+}
+interface FileUploadState {
+    /**
+     * Resolves to the stored file (pass its `id` to a workflow to attach it);
+     * rejects on failure. `fidelity` affects photographs only and defaults to
+     * `"high"`, which keeps a photographed document legible; `"standard"` suits
+     * bulk capture, `"original"` keeps the pixels as evidence.
+     */
+    upload: (file: File, options?: {
+        fidelity?: ImageFidelity;
+    }) => Promise<UploadedFile>;
+    uploading: boolean;
+    /** Cleared when a new upload starts. */
+    error: string | null;
+}
+/**
+ * Upload files through a host-mediated presigned upload; works in public and
+ * member apps alike.
+ *
+ * ```tsx
+ * const { upload, uploading } = useFileUpload();
+ * const submit = useWorkflow("submitApplication");
+ * const cccd = await upload(file);
+ * await submit({ ...fields, cccd_file_id: cccd.id });
+ * ```
+ */
+export declare function useFileUpload(): FileUploadState;
+/**
+ * An add-queue with instant local previews and background uploads. A composer
+ * clears when it sends; a record passes its stored files as `landed` and each
+ * entry leaves as the pile takes it over.
+ *
+ * ```tsx
+ * const { files, add, remove, clear, uploading, fileIds } = useAttachments();
+ * const design = useWorkflow("design");
+ * // attach:  <Button icon="paperclip" onPress={() => pickFiles({ accept: "image/*" }).then(add)} />
+ * // preview: map each AttachedFile to a @lotics/ui DisplayFile (snake_case → camelCase) — the
+ * //          app owns this data→UI adapter; the SDK never imports @lotics/ui:
+ * //   files.map((f) => (
+ * //     <FileThumbnail
+ * //       file={{ id: f.id, filename: f.filename, mimeType: f.mime_type, url: f.preview_url }}
+ * //       uploading={f.status === "uploading"} onRemove={() => remove(f.id)} />
+ * //   ))
+ * // send:    design({ photo: fileIds[0] }); clear();
+ * ```
+ */
+export declare function useAttachments(options?: AttachmentsOptions): AttachmentsState;
+/**
+ * {@link useAttachments} for a list of piles in one hook: a hook called once
+ * per pile shifts every later hook when the list changes.
+ *
+ * ```tsx
+ * const piles = useAttachmentPiles({ landed: { photos: held.photos, receipts: held.receipts } });
+ * const photos = piles.of("photos"); // an AttachmentsState
+ * ```
+ */
+export declare function useAttachmentPiles(options?: AttachmentPilesOptions): AttachmentPiles;
+/**
+ * Push the current screen's view state to the member's ambient chat agent.
+ * Mounting or changing `context` posts it; unmount, a new `slot` or `null`
+ * clears it; the newest value per slot wins. Push-only: `records` are raw refs
+ * the agent acts on only under the member's own IAM, and `description`/`data`
+ * reach its prompt as data.
+ *
+ * Host caps truncate or drop, never error: `slot` ≤ 50 chars; `description` ≤
+ * 1000 chars; `records` ≤ 20; `data` ≤ 2000 JSON chars or dropped; ≤ 8 slots
+ * per app, the least recently updated evicted.
+ *
+ * ```tsx
+ * useAiContext("orders_list", {
+ *   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
+ *   // A grouped query's rows carry no addressing columns.
+ *   records: rows.flatMap((r) =>
+ *     r.__source_table_id && r.__source_record_id
+ *       ? [{ table_id: r.__source_table_id, record_id: r.__source_record_id }]
+ *       : [],
+ *   ),
+ *   data: { filter: "status=open", sort: "due_date desc" },
+ * });
+ * ```
+ *
+ * No-ops with no embedding host and in mock mode.
+ */
+export declare function useAiContext(slot: string, context: AiContextValue | null): void;
+interface MembersState {
+    members: ResolvedMember[];
+    loading: boolean;
+    error: string | null;
+}
+export interface MembersOptions {
+    /**
+     * One member group, by the `grp_…` id a `member` workflow input's `group`
+     * declares. Omit for the whole roster.
+     */
+    group?: string;
+}
+/**
+ * The organization's members, for an assign picker. Member-only, and gated on
+ * the app declaring a `member`-typed workflow input. `name` may be empty —
+ * fall back to `email`.
+ *
+ * ```tsx
+ * const { members } = useMembers({ group: GRP.sale });
+ * // <Select variant="native" options={members.map((m) => ({
+ * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
+ * // }))} />
+ * ```
+ */
+export declare function useMembers(opts?: MembersOptions): MembersState;
+type AgentOutputOf<K extends string> = K extends keyof AppAgentResults ? AppAgentResults[K] : unknown;
+export interface AgentRunOptions {
+    /** Groups this run with the session's prior runs as context; a new id clears it. */
+    sessionId: string;
+    /** Abort the run in flight and start this one. Without it `run()` is
+     *  single-flight, so a double-press never bills a second run. The replaced
+     *  run still executes and bills server-side. */
+    replace?: boolean;
+}
+export interface UseAgentRun<TInput, TOutput> {
+    /** Resolves with how the leg ended — read its `kind`, since the hook's state
+     *  has not committed yet when it resolves. Single-flight (see `replace`). */
+    run: (input: TInput, opts: AgentRunOptions) => Promise<AgentRunLanding<TOutput>>;
+    /** Stop listening locally; the run finishes server-side into the session history. */
+    abort: () => void;
+    /** Stop the run server-side too — what a "Stop" button calls. */
+    cancel: () => void;
+    /** `awaiting_input`: parked on the agent's question (`pendingChoice`). */
+    status: "idle" | "streaming" | "awaiting_input" | "completed" | "error";
+    /** The ordered transcript, for `@lotics/ui` `AgentRun` as is. */
+    parts: AgentUIPart[];
+    /** Non-null exactly while `awaiting_input`; `questions` map onto `ClarifyWizard`. */
+    pendingChoice: PendingChoice | null;
+    /** Answer the pending ask (one `{value, custom}` per question, by index) and
+     *  continue the run; resolves like `run`. Rejects when nothing is pending or
+     *  the server refuses the answer — the run then stays parked. */
+    answerChoice: (answers: {
+        value: string;
+        custom: boolean;
+    }[]) => Promise<AgentRunLanding<TOutput>>;
+    /** Every `text` part concatenated, live — a free-text agent's result. */
+    text: string;
+    /** A structured agent's `submit_result` output; `undefined` when none was
+     *  submitted. The model authored it, so validate inner fields. */
+    output?: TOutput;
+    error?: string;
+}
+/**
+ * Run a streaming agent by alias. A structured agent's result lands in
+ * `output`, a free-text agent's in `text`; `useAgentRuns` reads the session.
+ *
+ * ```tsx
+ * const recognize = useAgentRun("recognize");
+ * await recognize.run({ image_file_id }, { sessionId });
+ * // <AgentRun parts={recognize.parts} state={recognize.status === "streaming" ? "streaming" : "done"} />
+ * // then read recognize.output (structured) or recognize.text (free-text)
+ * ```
+ */
+export declare function useAgentRun<K extends keyof AppAgents & string>(alias: K): UseAgentRun<AppAgents[K], AgentOutputOf<K>>;
+export declare function useAgentRun(alias: string): UseAgentRun<Record<string, unknown>, unknown>;
+export interface AgentRunRecord {
+    id: string;
+    agent_alias: string;
+    session_id: string;
+    status: string;
+    input: Record<string, unknown> | null;
+    output: unknown;
+    error_message: string | null;
+    started_at: string;
+    completed_at: string | null;
+    /** Single-run GET while `awaiting_input`: rebuilds the ask without the stream. */
+    pending_interactive?: {
+        tool_call_id: string;
+        tool_name: string;
+        input: unknown;
+    } | null;
+}
+interface AgentRunsState {
+    runs: AgentRunRecord[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+/**
+ * A session's runs, oldest first. Refetch after a `run(...)` completes.
+ *
+ * ```tsx
+ * const { runs } = useAgentRuns(sessionId);
+ * ```
+ */
+export declare function useAgentRuns(sessionId: string, opts?: {
+    enabled?: boolean;
+    revalidateOnFocus?: boolean;
+}): AgentRunsState;

package/dist/{src/index.d.ts → index.d.ts}

@@ -1,26 +1,16 @@
-/**
- * Lotics App SDK — the runtime + typed hooks bundled into every custom-code
- * app at build time. Apps `import { mount, useQuery, useWorkflow } from
- * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
- *
- * This SDK is data + RPC only — it deliberately does NOT re-export any
- * `@lotics/ui` component, so an app's dependency on the kit is its own and one
- * version answers for it. That is a packaging choice, NOT a limitation: apps
- * import `@lotics/ui` directly as an ordinary dependency. The starter scaffold
- * (`packages/sdk/src/starter_template.ts`) wires it — the kit as a dependency,
- * `@lotics/ui/styles.css` + `fonts.css` in the entry, and `loticsResolve()` as
- * the whole `resolve` block. Build screens by composing kit components (Card,
- * Metric, charts, Table, …), not raw HTML/CSS. See `docs/apps.md` → "Styling
- * & components".
- */
+/** `@lotics/app-sdk`: hooks, cell readers and `mount()`. Data and RPC only — no kit component. */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
-export type { QueryRow, RowOf, UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, CountOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
-export type { AttachedFile, AttachmentsOptions, AttachmentsState } from "./attachments.js";
+export { reportAppError } from "./error_report.js";
+export type { AppErrorKind } from "./error_report.js";
+export { useWorkflow, useWorkflows, writesSettled, useFileUpload, useAttachments, useAttachmentPiles, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
+export type { UploadedFile, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, } from "./hooks.js";
+export { useQuery, useQueries, queryAll, useFieldOptions } from "./queries.js";
+export type { QueryRow, QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, } from "./queries.js";
+export type { AttachedFile, AttachmentPiles, AttachmentPilesOptions, AttachmentsOptions, AttachmentsState } from "./attachments.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
-export { useViewer } from "./viewer.js";
+export { useAppContext, useViewer, useWorkspaceCurrency, useWorkspaceTimezone } from "./viewer.js";
 export { useRecording } from "./recording.js";
 export type { UseRecording } from "./recording.js";
 export type { RecordingState, RecordingInputs } from "./recording_state.js";
@@ -32,21 +22,22 @@ export { openExternal } from "./open_external.js";
 export { openApp } from "./open_app.js";
 export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
+export { renameFile } from "./rename_file.js";
 export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
 export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
 export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
-export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt } from "./row.js";
+export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt, PENDING } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";
-export { useOptimistic } from "./use_optimistic.js";
-export type { OptimisticApi } from "./use_optimistic.js";
 export { useNewRecord, newRecordId } from "./new_record.js";
 export type { NewRecordApi } from "./new_record.js";
 export { useRecents } from "./use_recents.js";
 export type { RecentsApi, RecentsOptions } from "./use_recents.js";
 export { useUrlState } from "./use_url_state.js";
+export { useFolderPick } from "./folder_pick.js";
+export type { FolderPick } from "./folder_pick.js";
 export type { UrlStateShape, UrlStateValues } from "./use_url_state.js";
 export { urlParam } from "./url_params.js";
 export type { UrlParamCodec, OptionalUrlParamCodec, UrlParams, UrlParamValue, } from "./url_params.js";