@jskit-ai/users-web 0.1.82 → 0.1.83

package/package.descriptor.mjs

@@ -3,7 +3,7 @@ import { HOME_COG_OUTLET } from "./src/shared/toolsOutletContracts.js";
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/users-web",
-  version: "0.1.82",
+  version: "0.1.83",
   kind: "runtime",
   description: "Users web module: account/profile UI plus shared users web widgets.",
   dependsOn: [
@@ -278,12 +278,12 @@ export default Object.freeze({
     dependencies: {
       runtime: {
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/http-runtime": "0.1.66",
-        "@jskit-ai/realtime": "0.1.66",
-        "@jskit-ai/kernel": "0.1.67",
-        "@jskit-ai/shell-web": "0.1.66",
-        "@jskit-ai/uploads-image-web": "0.1.45",
-        "@jskit-ai/users-core": "0.1.77"
+        "@jskit-ai/http-runtime": "0.1.67",
+        "@jskit-ai/realtime": "0.1.67",
+        "@jskit-ai/kernel": "0.1.68",
+        "@jskit-ai/shell-web": "0.1.67",
+        "@jskit-ai/uploads-image-web": "0.1.46",
+        "@jskit-ai/users-core": "0.1.78"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -44,12 +44,12 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.66",
-    "@jskit-ai/kernel": "0.1.67",
-    "@jskit-ai/realtime": "0.1.66",
-    "@jskit-ai/shell-web": "0.1.66",
-    "@jskit-ai/uploads-image-web": "0.1.45",
-    "@jskit-ai/users-core": "0.1.77"
+    "@jskit-ai/http-runtime": "0.1.67",
+    "@jskit-ai/kernel": "0.1.68",
+    "@jskit-ai/realtime": "0.1.67",
+    "@jskit-ai/shell-web": "0.1.67",
+    "@jskit-ai/uploads-image-web": "0.1.46",
+    "@jskit-ai/users-core": "0.1.78"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",

package/src/client/composables/records/useCrudAddEdit.js

@@ -6,6 +6,7 @@ import { useAddEdit } from "./useAddEdit.js";
 import {
   resolveCrudBoundValues,
 } from "../crud/crudBindingSupport.js";
+import { resolveOperationRealtimeOptions } from "../useRealtimeQueryInvalidation.js";
 import {
   normalizeCrudFormFields,
   createCrudFormModel,
@@ -64,6 +65,12 @@ function useCrudAddEdit({
       operationName
     }
   );
+  const resolvedRealtime = resolveOperationRealtimeOptions({
+    realtime: normalizedAddEditOptions.realtime,
+    fallbackRealtime: resolvedResource?.operations?.[operationName]?.realtime ||
+      resolvedResource?.operations?.list?.realtime ||
+      null
+  });
   const saveSuccessOptions = normalizeSaveSuccessOptions(saveSuccess);
   const defaultFieldErrorKeys = normalizedFields.map((field) => field.key);
   const providedFieldErrorKeys = normalizeFieldErrorKeys(normalizedAddEditOptions.fieldErrorKeys);
@@ -185,6 +192,7 @@ function useCrudAddEdit({
     input: resolvedInput,
     buildRawPayload: resolveBuildRawPayload,
     mapLoadedToModel: effectiveMapLoadedToModel,
+    realtime: resolvedRealtime,
     onSaveSuccess: handleSaveSuccess
   });
   addEditRuntime = addEdit;

package/src/client/composables/records/useCrudList.js

@@ -12,6 +12,7 @@ import {
   toRouteParamValue
 } from "../support/routeTemplateHelpers.js";
 import { asPlainObject } from "../support/scopeHelpers.js";
+import { resolveOperationRealtimeOptions } from "../useRealtimeQueryInvalidation.js";
 import { useList } from "./useList.js";
 
 function resolveRequestQueryParamsInput(requestQueryParams, context = {}) {
@@ -49,6 +50,7 @@ function useCrudList({
   parentBinding = null,
   recordIdParam = "recordId",
   route = null,
+  realtime = undefined,
   ...listOptions
 } = {}) {
   const sourceRoute = route && typeof route === "object" ? route : useRoute();
@@ -72,6 +74,10 @@ function useCrudList({
     transport: resolveCrudJsonApiTransport(listOptions.transport, resource, {
       mode: "list"
     }),
+    realtime: resolveOperationRealtimeOptions({
+      realtime,
+      fallbackRealtime: resource?.operations?.list?.realtime || null
+    }),
     recordIdParam,
     requestQueryParams(context = {}) {
       const baseRequestQueryParams = resolveRequestQueryParamsInput(requestQueryParams, context);

package/src/client/composables/records/useCrudView.js

@@ -29,6 +29,7 @@ function useCrudView({
   });
   const view = useView({
     ...viewOptions,
+    resource,
     transport: resolveCrudJsonApiTransport(viewOptions.transport, resource, {
       mode: "view"
     }),

package/src/client/composables/records/useView.js

@@ -8,6 +8,7 @@ import { setupOperationErrorReporting } from "../runtime/operationUiHelpers.js";
 import { createViewUiRuntime } from "../runtime/viewUiRuntime.js";
 import { createRequestQueryRuntime } from "../support/requestQueryRuntimeSupport.js";
 import { resolveRouteParamNamesInOrder } from "../support/routeTemplateHelpers.js";
+import { resolveOperationRealtimeOptions } from "../useRealtimeQueryInvalidation.js";
 
 function useView({
   ownershipFilter = ROUTE_VISIBILITY_WORKSPACE,
@@ -33,7 +34,7 @@ function useView({
   listUrlTemplate = "",
   editUrlTemplate = "",
   includeRecordIdInQueryKey = false,
-  realtime = null,
+  realtime = undefined,
   adapter = null
 } = {}) {
   const route = useRoute();
@@ -63,7 +64,12 @@ function useView({
     permissionSets: {
       view: viewPermissions
     },
-    realtime
+    realtime: resolveOperationRealtimeOptions({
+      realtime,
+      fallbackRealtime: resource?.operations?.view?.realtime ||
+        resource?.operations?.list?.realtime ||
+        null
+    })
   });
   const queryParamsContext = computed(() => {
     return Object.freeze({

package/src/client/composables/runtime/useEndpointResource.js

@@ -4,6 +4,7 @@ import { usersWebHttpClient } from "../../lib/httpClient.js";
 import { asPlainObject } from "../support/scopeHelpers.js";
 import { resolveEnabledRef, resolveTextRef } from "../support/refValueHelpers.js";
 import { toQueryErrorMessage } from "../support/errorMessageHelpers.js";
+import { useOperationRealtime } from "../useRealtimeQueryInvalidation.js";
 import {
   hasResolvedQueryData,
   mergeQueryMeta
@@ -71,6 +72,7 @@ function useEndpointResource({
   readQuery = null,
   transport = null,
   refreshOnPull = false,
+  realtime = null,
   queryOptions = null,
   mutationOptions = null,
   fallbackLoadError = "Unable to load resource.",
@@ -108,6 +110,11 @@ function useEndpointResource({
       })
       : asPlainObject(queryOptions))
   });
+  const realtimeBinding = useOperationRealtime({
+    realtime,
+    queryKey,
+    enabled: queryEnabled
+  });
 
   const mutation = useMutation({
     mutationFn: async (request = {}) => {
@@ -168,6 +175,7 @@ function useEndpointResource({
     isSaving,
     loadError,
     saveError,
+    realtime: realtimeBinding,
     reload,
     save
   });

package/src/client/composables/useRealtimeQueryInvalidation.js

@@ -14,6 +14,31 @@ function normalizeRealtimeOptions(value = {}) {
   return value;
 }
 
+function hasRealtimeEventConfig(value = {}) {
+  const source = normalizeRealtimeOptions(value);
+  return Object.hasOwn(source, "event") || Object.hasOwn(source, "events");
+}
+
+function resolveOperationRealtimeOptions({
+  realtime = undefined,
+  fallbackRealtime = null
+} = {}) {
+  if (realtime === false) {
+    return null;
+  }
+
+  const fallback = normalizeRealtimeOptions(fallbackRealtime);
+  const explicit = realtime == null ? {} : normalizeRealtimeOptions(realtime);
+  if (hasRealtimeEventConfig(explicit) || !hasRealtimeEventConfig(fallback)) {
+    return Object.keys(explicit).length > 0 ? explicit : null;
+  }
+
+  return Object.freeze({
+    ...fallback,
+    ...explicit
+  });
+}
+
 function resolveEnabled(value) {
   if (typeof value === "undefined") {
     return true;
@@ -125,6 +150,7 @@ function useOperationRealtime({
 }
 
 export {
+  resolveOperationRealtimeOptions,
   useRealtimeQueryInvalidation,
   useOperationRealtime
 };

package/test/requestTransportOptions.test.js

@@ -1,11 +1,18 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import { createSSRApp, h } from "vue";
+import { renderToString } from "vue/server-renderer";
 
 import {
   buildEndpointReadRequestOptions,
-  buildEndpointWriteRequestOptions
+  buildEndpointWriteRequestOptions,
+  useEndpointResource
 } from "../src/client/composables/runtime/useEndpointResource.js";
 import { buildListRequestOptions } from "../src/client/composables/runtime/useListCore.js";
+import {
+  resolveOperationRealtimeOptions
+} from "../src/client/composables/useRealtimeQueryInvalidation.js";
 
 test("endpoint read request options include transport only when provided", () => {
   assert.deepEqual(
@@ -140,3 +147,105 @@ test("list request options preserve explicit limit values", () => {
     }
   );
 });
+
+test("operation realtime options use fallback events unless explicitly overridden", () => {
+  const fallbackRealtime = {
+    events: ["contacts.record.changed"]
+  };
+
+  assert.deepEqual(
+    resolveOperationRealtimeOptions({
+      fallbackRealtime
+    }),
+    {
+      events: ["contacts.record.changed"]
+    }
+  );
+
+  assert.deepEqual(
+    resolveOperationRealtimeOptions({
+      realtime: {
+        enabled: false
+      },
+      fallbackRealtime
+    }),
+    {
+      events: ["contacts.record.changed"],
+      enabled: false
+    }
+  );
+
+  assert.deepEqual(
+    resolveOperationRealtimeOptions({
+      realtime: {
+        event: "contacts.custom.changed"
+      },
+      fallbackRealtime
+    }),
+    {
+      event: "contacts.custom.changed"
+    }
+  );
+
+  assert.equal(
+    resolveOperationRealtimeOptions({
+      realtime: false,
+      fallbackRealtime
+    }),
+    null
+  );
+});
+
+test("endpoint resources invalidate their query key from configured realtime events", async () => {
+  const queryClient = new QueryClient();
+  const invalidations = [];
+  const socketHandlers = new Map();
+  const socket = {
+    on(eventName, handler) {
+      socketHandlers.set(eventName, handler);
+    },
+    off(eventName, handler) {
+      if (socketHandlers.get(eventName) === handler) {
+        socketHandlers.delete(eventName);
+      }
+    }
+  };
+  queryClient.invalidateQueries = async (options = {}) => {
+    invalidations.push(options);
+  };
+  const app = createSSRApp({
+    setup() {
+      useEndpointResource({
+        queryKey: ["today-workout-detail", "/api/today/workouts/2026-05-06"],
+        path: "/api/today/workouts/2026-05-06",
+        client: {
+          async request() {
+            return {};
+          }
+        },
+        realtime: {
+          event: "workout_set_logs.record.changed"
+        }
+      });
+      return () => h("div");
+    }
+  });
+  app.use(VueQueryPlugin, {
+    queryClient
+  });
+  app.provide("jskit.realtime.runtime.client.socket", socket);
+  await renderToString(app);
+
+  const handler = socketHandlers.get("workout_set_logs.record.changed");
+  assert.equal(typeof handler, "function");
+  handler({
+    entityId: "42"
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.deepEqual(invalidations, [
+    {
+      queryKey: ["today-workout-detail", "/api/today/workouts/2026-05-06"]
+    }
+  ]);
+});