@lotics/app-sdk 0.30.0 → 0.32.0

package/dist/src/comments.d.ts

@@ -69,3 +69,29 @@ export interface UseCommentsArgs {
  * ```
  */
 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. */
+    table_id: string;
+}
+/**
+ * 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 });
+ * // counts[row.__source_record_id] ?? 0
+ * ```
+ */
+export declare function useCommentCounts(args: UseCommentCountsArgs): CommentCountsState;

package/dist/src/comments.js

@@ -1,20 +1,22 @@
 /**
  * `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:
+ * 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 authorized against the viewer's own table access + row-scope
- *   - the comment's author is the viewer (correct attribution)
+ *   - 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
  *
- * 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.
+ * `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 mirrors `useQuery`: SWR-cached, revalidate on focus / reconnect, and
  * an explicit refetch after every mutation. There is no realtime push to apps,
@@ -150,3 +152,29 @@ export function useComments(args) {
         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 });
+ * // 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 ? ["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/hooks.d.ts

@@ -157,9 +157,10 @@ type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] exte
  * 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. `data` is the
- * structured value the workflow returned via `return({ data })`, typed per the
- * alias's declared `outputs` schema (`unknown` when none was declared).
+ * 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<TData = unknown> {
     status: "success" | "error";

package/dist/src/index.d.ts

@@ -18,8 +18,8 @@ export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
 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 { useComments, useCommentCounts } from "./comments.js";
+export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";
@@ -32,7 +32,7 @@ export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";
-export { row, readLinks, readFiles } from "./row.js";
+export { row, readLinks, readFiles, readLocked } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";

package/dist/src/index.js

@@ -16,13 +16,13 @@
  */
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
-export { useComments } from "./comments.js";
+export { useComments, useCommentCounts } 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";
 export { readSelect } from "./select.js";
-export { row, readLinks, readFiles } from "./row.js";
+export { row, readLinks, readFiles, readLocked } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export { useRecents } from "./use_recents.js";

package/dist/src/row.d.ts

@@ -65,6 +65,15 @@ export interface AppFile {
  * an unservable file. Map to `@lotics/ui` `DisplayFile` for FileThumbnail/Gallery.
  */
 export declare function readFiles(v: unknown): AppFile[];
+/**
+ * Record lock state for a `useQuery` row. The query layer emits a row-level
+ * `__source_locked` addressing column (alongside `__source_record_id`). A locked
+ * record rejects direct writes, so an app reads this to show a locked state and
+ * route edits through a `request_locked_field_change` workflow instead of an
+ * `update_records` save. Pass the whole row (not a cell). False for any
+ * non-object / absent flag.
+ */
+export declare function readLocked(rowValue: unknown): boolean;
 export declare const row: {
     opt: typeof opt;
     text: typeof text;

package/dist/src/row.js

@@ -118,4 +118,17 @@ export function readFiles(v) {
     }
     return out;
 }
+/**
+ * Record lock state for a `useQuery` row. The query layer emits a row-level
+ * `__source_locked` addressing column (alongside `__source_record_id`). A locked
+ * record rejects direct writes, so an app reads this to show a locked state and
+ * route edits through a `request_locked_field_change` workflow instead of an
+ * `update_records` save. Pass the whole row (not a cell). False for any
+ * non-object / absent flag.
+ */
+export function readLocked(rowValue) {
+    if (!rowValue || typeof rowValue !== "object")
+        return false;
+    return bool(rowValue["__source_locked"]);
+}
 export const row = { opt, text, num, bool, date, link };

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" | "comments.list" | "comments.create" | "comments.update" | "comments.delete";
+export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /**
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:

package/dist/src/rpc.js

@@ -227,6 +227,7 @@ function rpcStandalone(op, payload) {
         case "comments.create":
         case "comments.update":
         case "comments.delete":
+        case "comments.counts":
             return rejectCommentsStandalone();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -46,4 +46,4 @@
     "url": "https://github.com/lotics/lotics.git",
     "directory": "packages/app-sdk"
   }
-}
+}