@lotics/app-sdk 0.29.0 → 0.31.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

@@ -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,22 @@ 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.
+ *
+ * `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

@@ -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";

package/dist/src/index.js

@@ -16,7 +16,7 @@
  */
 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";

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/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.29.0",
+  "version": "0.31.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {