@lotics/app-sdk 0.24.0 → 0.26.0

package/dist/src/comments.d.ts

@@ -0,0 +1,71 @@
+/** A file attached to a comment, in the resolved (serving) shape the list returns. */
+export interface AppCommentFile {
+    id: string;
+    /** Storage key — needed to re-send the file when editing a comment. */
+    file_storage_key: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+    preview_url?: string;
+}
+/** 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;
+    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;
+}
+/**
+ * ```tsx
+ * const { comments, available, createComment } = useComments({
+ *   record_id: row.__source_record_id,
+ * });
+ * ```
+ */
+export declare function useComments(args: UseCommentsArgs): CommentsState;

package/dist/src/comments.js

@@ -0,0 +1,169 @@
+/**
+ * `useComments` — read and write the comments on a record from a custom-code app.
+ *
+ * Comments are a *members-only* surface and behave differently from `useQuery`
+ * / `useWorkflow`. Those run under the app OWNER's authority (the app is the
+ * capability), which is what lets a public app expose owner-curated data to an
+ * anonymous visitor. Comments are member-to-member discussion tied to a real
+ * author identity, so they run under the VIEWING MEMBER's own authority instead:
+ *
+ *   - read / write authorized against the viewer's own table access + row-scope
+ *   - the comment's author is the viewer (correct attribution)
+ *   - edit / delete are author-only, checked against the viewer
+ *
+ * The bridged host (`app_iframe_host`) holds the member session and proxies each
+ * op to the member's `/v1/records/.../comments` endpoints. A standalone (public)
+ * app has no signed-in member: `available` is false, the list stays empty, and a
+ * mutation rejects. Check `available` before rendering a composer.
+ *
+ * Freshness mirrors `useQuery`: SWR-cached, revalidate on focus / reconnect, and
+ * an explicit refetch after every mutation. There is no realtime push to apps,
+ * so a thread updated by another viewer appears on the next focus / refetch.
+ */
+import { useCallback } from "react";
+import useSWR from "swr";
+import { rpc } from "./rpc.js";
+import { captureAppEvent } from "./analytics.js";
+/** The reduced storage shape the update endpoint accepts for `files`. */
+function toStorageFiles(files) {
+    return (files ?? []).map((f) => ({
+        id: f.id,
+        file_storage_key: f.file_storage_key,
+        filename: f.filename,
+        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
+ * const { comments, available, createComment } = useComments({
+ *   record_id: 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,
+        });
+        captureAppEvent("app_comment_created", { has_files: fileIds.length > 0 });
+    }, [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,
+                files: toStorageFiles(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,
+        });
+        captureAppEvent("app_comment_updated", {});
+    }, [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,
+        });
+        captureAppEvent("app_comment_deleted", {});
+    }, [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,
+    };
+}

package/dist/src/hooks.d.ts

@@ -28,6 +28,36 @@ interface QueryState<R> {
     /** True while a `loadMore` request is in flight. */
     loadingMore: boolean;
 }
+/**
+ * One sort key — the wire shape of the query RPC's `sort`. The server applies
+ * these AFTER the named query, bounded to the query's output columns (an
+ * un-projected `field_key` is rejected), so an app can sort by any column it
+ * actually selects without the query template declaring it.
+ */
+export interface QuerySortKey {
+    field_key: string;
+    order: "asc" | "desc";
+}
+/** A filter condition over one output column (wire shape of a filter node). */
+export interface QueryFilterCondition {
+    node_type: "condition";
+    field_key: string;
+    type?: string;
+    operator: string;
+    value?: unknown;
+}
+/** A boolean group of filter nodes (wire shape — recursive). */
+export interface QueryFilterGroup {
+    node_type: "group";
+    logic: "and" | "or";
+    children: Array<QueryFilterCondition | QueryFilterGroup>;
+}
+/**
+ * Runtime filter applied AFTER the named query, bounded to its output columns
+ * (same exposure invariant as `sort`). Build a group from per-column filters
+ * with `columnFilterToConditions` (`@lotics/ui/grid/column_filter`).
+ */
+export type QueryFilter = QueryFilterCondition | QueryFilterGroup;
 /** Options for `useQuery`. */
 export interface QueryOptions {
     /**
@@ -53,6 +83,16 @@ export interface QueryOptions {
      * re-run is wasted work and a visible reload.
      */
     revalidateOnFocus?: boolean;
+    /**
+     * Sort the result by output columns at runtime. Changing it re-queries (it is
+     * part of the cache key). Empty/omitted leaves the query's own order intact.
+     */
+    sort?: QuerySortKey[];
+    /**
+     * Filter the result by output columns at runtime. Changing it re-queries.
+     * Compose from per-column UI filters via `columnFilterToConditions`.
+     */
+    filter?: QueryFilter;
 }
 /**
  * Trigger a workflow by alias from the app's manifest.

package/dist/src/hooks.js

@@ -36,6 +36,8 @@ export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
     const enabled = opts?.enabled ?? true;
     const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
+    const filter = opts?.filter;
     // A registered fixture short-circuits the network in mock / dev mode.
     const mockRows = getMockRows(alias);
     // The cache key is (alias, params, pageSize, pageIndex), built HERE so an app
@@ -52,15 +54,19 @@ export function useQuery(alias, params, opts) {
         if (index > 0 && (pageSize == null || prev == null || prev.rows.length < pageSize)) {
             return null;
         }
-        return ["app-query", alias, params ?? {}, pageSize ?? null, index];
+        // sort/filter join the key so a re-sort or re-filter is a distinct cache
+        // entry — SWR refetches instead of serving the previous order/subset.
+        return ["app-query", alias, params ?? {}, pageSize ?? null, sort ?? null, filter ?? null, index];
     };
     const swr = useSWRInfinite(getKey, (key) => {
-        const index = Number(key[4]);
+        const index = Number(key[6]);
         return rpc("query", {
             alias,
             params: params ?? {},
             limit: pageSize,
             offset: pageSize != null ? index * pageSize : 0,
+            sort,
+            filter,
         });
     }, {
         // loadMore appends pages — don't re-fetch earlier pages when `size` grows.

package/dist/src/index.d.ts

@@ -17,7 +17,9 @@
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
-export type { UploadedFile, QueryOptions, WorkflowResult, MembersOptions } from "./hooks.js";
+export type { UploadedFile, QueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
+export { useComments } from "./comments.js";
+export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs } from "./comments.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";

package/dist/src/index.js

@@ -16,6 +16,7 @@
  */
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
+export { useComments } from "./comments.js";
 export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";

package/dist/src/rpc.d.ts

@@ -18,7 +18,7 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal";
+export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete";
 /**
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:
@@ -38,5 +38,11 @@ export interface AppContext {
     workspace_id: string;
     organization_id: string;
     member_id: string | null;
+    /**
+     * Whether the app declared the `comments` capability. `useComments` is
+     * available only when this is true AND a member is signed in. False for any
+     * app that didn't opt in, and (vacuously) for standalone visitors.
+     */
+    comments_enabled: boolean;
 }
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

package/dist/src/rpc.js

@@ -223,8 +223,24 @@ function rpcStandalone(op, payload) {
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
+        case "comments.list":
+        case "comments.create":
+        case "comments.update":
+        case "comments.delete":
+            return rejectCommentsStandalone();
     }
 }
+/**
+ * Comments are a members-only collaboration surface. A comment must have an
+ * authenticated member as its author, and a thread can carry member-to-member
+ * discussion — so a standalone (public, anonymous) app has no member to author
+ * as and no business reading other members' threads. `useComments` detects this
+ * up front via the null context `member_id` and never sends a comment op; this
+ * rejection is the belt-and-braces backstop for any direct `rpc()` caller.
+ */
+function rejectCommentsStandalone() {
+    return Promise.reject(new Error("Comments are available only in embedded apps — a signed-in member is required."));
+}
 async function standaloneMembers(p) {
     const { app_id } = await boot();
     const qs = p.group ? `?group_id=${encodeURIComponent(p.group)}` : "";
@@ -261,8 +277,10 @@ async function standaloneContext() {
         app_name: info.app_name,
         workspace_id: info.workspace_id,
         organization_id: info.organization_id,
-        // No host session in standalone mode — the visitor is anonymous.
+        // No host session in standalone mode — the visitor is anonymous, so
+        // comments are unavailable regardless of the capability flag.
         member_id: null,
+        comments_enabled: info.comments_enabled,
     };
 }
 async function standaloneQuery(p) {

package/package.json

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