@lotics/app-sdk 0.81.0 → 0.82.0

package/dist/src/comments.d.ts

@@ -1,8 +1,6 @@
 /** 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;

package/dist/src/comments.js

@@ -18,22 +18,30 @@
  * 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,
- * so a thread updated by another viewer appears on the next focus / refetch.
+ * 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 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,
-    }));
+/**
+ * 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;
 /**
@@ -116,7 +124,7 @@ export function useComments(args) {
                 record_id,
                 comment_id: id,
                 content,
-                files: toStorageFiles(currentFiles),
+                file_ids: toFileIds(currentFiles),
             });
             return rpc("comments.list", { record_id });
         }, {

package/docs/members_and_options.md

@@ -279,8 +279,9 @@ updateComment, deleteComment, refetch }`.
 - `comments` — newest first on the wire (server order). Pass the array as-is to `@lotics/ui`'s
   `CommentList`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
   table_id, member_id, content, files, workspace_id, created_at, updated_at }`. Attachments
-  (`AppCommentFile`) carry `id` / `filename` / `mime_type` plus `file_storage_key` (needed when
-  re-sending files on edit). The `url` / `thumbnail_url` / `preview_url` fields exist on the type
+  (`AppCommentFile`) carry `id` / `filename` / `mime_type` — a file's identity is its `id`, and
+  the server re-reads every attachment from storage by that id, so nothing else you hold about a
+  file can affect what is stored. The `url` / `thumbnail_url` / `preview_url` fields exist on the type
   but the server does not populate them today — render attachments by name and type (what
   `CommentList`'s default file row does), never by counting on a fetchable URL.
 - `createComment({ content, file_ids? })` — posts as the viewing member. `file_ids` come from
@@ -297,8 +298,11 @@ updateComment, deleteComment, refetch }`.
   member source: the `useMembers` roster (requires the member-access declaration above) or member
   cells in your own data. An unresolvable id should render a fallback (`CommentList` has an
   `unknownMember` label for exactly this).
-- **Freshness:** SWR-cached, revalidates on focus/reconnect; there is **no realtime push** to apps,
-  so another viewer's comment appears on the next focus or explicit `refetch()`.
+- **Freshness:** SWR-cached, revalidates on focus/reconnect, so another viewer's comment appears on
+  the next focus or explicit `refetch()` — not on its own. Comments are the one read that does not
+  keep itself current, and not because apps lack realtime: the channel carries **record** changes,
+  and a comment is its own entity that emits no record event. Your queries DO get pushed
+  ([data_fetching.md](./data_fetching.md)) — don't read this line as "no push" and build a poll.
 
 ### Counts
 

package/package.json

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