@jskit-ai/users-web 0.1.105 → 0.1.107

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.105",
+  version: "0.1.107",
   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.89",
-        "@jskit-ai/realtime": "0.1.89",
-        "@jskit-ai/kernel": "0.1.90",
-        "@jskit-ai/shell-web": "0.1.89",
-        "@jskit-ai/uploads-image-web": "0.1.68",
-        "@jskit-ai/users-core": "0.1.100"
+        "@jskit-ai/http-runtime": "0.1.91",
+        "@jskit-ai/realtime": "0.1.91",
+        "@jskit-ai/kernel": "0.1.92",
+        "@jskit-ai/shell-web": "0.1.91",
+        "@jskit-ai/uploads-image-web": "0.1.70",
+        "@jskit-ai/users-core": "0.1.102"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.105",
+  "version": "0.1.107",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -44,12 +44,12 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.89",
-    "@jskit-ai/kernel": "0.1.90",
-    "@jskit-ai/realtime": "0.1.89",
-    "@jskit-ai/shell-web": "0.1.89",
-    "@jskit-ai/uploads-image-web": "0.1.68",
-    "@jskit-ai/users-core": "0.1.100"
+    "@jskit-ai/http-runtime": "0.1.91",
+    "@jskit-ai/kernel": "0.1.92",
+    "@jskit-ai/realtime": "0.1.91",
+    "@jskit-ai/shell-web": "0.1.91",
+    "@jskit-ai/uploads-image-web": "0.1.70",
+    "@jskit-ai/users-core": "0.1.102"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",

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

@@ -29,7 +29,10 @@ function useAddEdit({
   readMethod = "GET",
   readEnabled = true,
   writeMethod = "PATCH",
+  client = null,
   transport = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Resource",
   placementSource = "users-web.add-edit",
   fallbackLoadError = "Unable to load resource.",
   fallbackSaveError = "Unable to save resource.",
@@ -117,10 +120,13 @@ function useAddEdit({
     queryKey: requestQueryRuntime.queryKey,
     path: operationScope.apiPath,
     enabled: queryCanRun,
+    client,
     readMethod,
     writeMethod,
     readQuery: requestQueryRuntime.requestQuery,
     transport,
+    requestRecovery,
+    requestRecoveryLabel,
     fallbackLoadError,
     fallbackSaveError: String(fallbackSaveError || effectiveMessages.saveError || "Unable to save resource.")
   });

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

@@ -43,9 +43,12 @@ function useList({
   initialPageParam = null,
   getNextPageParam,
   selectItems,
+  client = null,
   transport = null,
   requestOptions,
   queryOptions,
+  requestRecovery,
+  requestRecoveryLabel = "List",
   realtime = null,
   adapter = null,
   recordIdParam = "recordId",
@@ -222,12 +225,15 @@ function useList({
     queryKey: listQueryKey,
     path: listPath,
     enabled: operationScope.queryCanRun(canView),
+    client,
     transport,
     initialPageParam,
     getNextPageParam,
     selectItems,
     requestOptions: listRequestOptions,
     queryOptions,
+    requestRecovery,
+    requestRecoveryLabel,
     fallbackLoadError
   });
   const routeSyncHydrated = ref(routeSyncConfig.enabled !== true);

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

@@ -20,7 +20,10 @@ function useView({
   viewPermissions = [],
   readMethod = "GET",
   readEnabled = true,
+  client = null,
   transport = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Resource",
   placementSource = "users-web.view",
   fallbackLoadError = "Unable to load resource.",
   notFoundStatuses = [404],
@@ -101,9 +104,12 @@ function useView({
     queryKey: requestQueryRuntime.queryKey,
     path: operationScope.apiPath,
     enabled: operationScope.queryCanRun(canView),
+    client,
     readMethod,
     readQuery: requestQueryRuntime.requestQuery,
     transport,
+    requestRecovery,
+    requestRecoveryLabel,
     refreshOnPull: true,
     fallbackLoadError
   });

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

@@ -1,13 +1,14 @@
 import { computed, unref } from "vue";
 import { useMutation, useQuery } from "@tanstack/vue-query";
-import { usersWebHttpClient } from "../../lib/httpClient.js";
+import { getUsersWebHttpClient } 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
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
 } from "../support/resourceLoadStateHelpers.js";
 
 function buildEndpointReadRequestOptions({
@@ -66,7 +67,7 @@ function useEndpointResource({
   queryKey,
   path = "",
   enabled = true,
-  client = usersWebHttpClient,
+  client = null,
   readMethod = "GET",
   writeMethod = "PATCH",
   readQuery = null,
@@ -75,10 +76,13 @@ function useEndpointResource({
   realtime = null,
   queryOptions = null,
   mutationOptions = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Request",
   fallbackLoadError = "Unable to load resource.",
   fallbackSaveError = "Unable to save resource."
 } = {}) {
-  if (!client || typeof client.request !== "function") {
+  const activeClient = client || getUsersWebHttpClient();
+  if (!activeClient || typeof activeClient.request !== "function") {
     throw new TypeError("useEndpointResource requires a client with request().");
   }
 
@@ -93,7 +97,7 @@ function useEndpointResource({
         throw new Error("Resource path is required.");
       }
 
-      return client.request(requestPath, {
+      return activeClient.request(requestPath, {
         ...buildEndpointReadRequestOptions({
           method: readMethod,
           query: readQuery,
@@ -102,13 +106,20 @@ function useEndpointResource({
       });
     },
     enabled: queryEnabled,
-    ...(refreshOnPull
-      ? mergeQueryMeta(asPlainObject(queryOptions), {
-        jskit: {
-          refreshOnPull: true
-        }
-      })
-      : asPlainObject(queryOptions))
+    ...mergeRequestRecoveryQueryMeta(
+      refreshOnPull
+        ? mergeQueryMeta(asPlainObject(queryOptions), {
+          jskit: {
+            refreshOnPull: true
+          }
+        })
+        : asPlainObject(queryOptions),
+      requestRecovery,
+      {
+        label: requestRecoveryLabel,
+        method: readMethod
+      }
+    )
   });
   const realtimeBinding = useOperationRealtime({
     realtime,
@@ -127,7 +138,7 @@ function useEndpointResource({
       const method = String(options.method || writeMethod || "PATCH").toUpperCase();
       const hasBody = Object.hasOwn(options, "body");
       const body = hasBody ? options.body : options.payload;
-      return client.request(
+      return activeClient.request(
         requestPath,
         buildEndpointWriteRequestOptions({
           method,

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

@@ -1,8 +1,9 @@
 import { computed, unref } from "vue";
-import { usersWebHttpClient } from "../../lib/httpClient.js";
+import { getUsersWebHttpClient } from "../../lib/httpClient.js";
 import { asPlainObject } from "../support/scopeHelpers.js";
 import { resolveEnabledRef, resolveTextRef } from "../support/refValueHelpers.js";
 import { usePagedCollection } from "../usePagedCollection.js";
+import { mergeRequestRecoveryQueryMeta } from "../support/resourceLoadStateHelpers.js";
 
 const DEFAULT_LIST_LIMIT = 20;
 
@@ -47,20 +48,27 @@ function resolveRequestOptionsObject(value = null) {
   return asPlainObject(source);
 }
 
+function resolveListRequestMethod(requestOptions = null) {
+  return String(resolveRequestOptionsObject(requestOptions).method || "GET").toUpperCase();
+}
+
 function useListCore({
   queryKey,
   path = "",
   enabled = true,
-  client = usersWebHttpClient,
+  client = null,
   transport = null,
   initialPageParam = null,
   getNextPageParam,
   selectItems,
   requestOptions = null,
   queryOptions = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "List",
   fallbackLoadError = "Unable to load list."
 } = {}) {
-  if (!client || typeof client.request !== "function") {
+  const activeClient = client || getUsersWebHttpClient();
+  if (!activeClient || typeof activeClient.request !== "function") {
     throw new TypeError("useListCore requires a client with request().");
   }
 
@@ -77,7 +85,7 @@ function useListCore({
         throw new Error("List path is required.");
       }
 
-      return client.request(
+      return activeClient.request(
         requestPath,
         buildListRequestOptions({
           requestOptions,
@@ -88,7 +96,10 @@ function useListCore({
     },
     getNextPageParam,
     selectItems,
-    queryOptions,
+    queryOptions: mergeRequestRecoveryQueryMeta(queryOptions, requestRecovery, {
+      label: requestRecoveryLabel,
+      method: resolveListRequestMethod(requestOptions)
+    }),
     fallbackLoadError
   });
 

package/src/client/composables/support/resourceLoadStateHelpers.js

@@ -36,7 +36,194 @@ function mergeQueryMeta(queryOptions = null, meta = {}) {
   };
 }
 
+function normalizeText(value = "") {
+  return String(value || "").trim();
+}
+
+function firstNormalizedText(...values) {
+  for (const value of values) {
+    const normalized = normalizeText(value);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return "";
+}
+
+function firstNonNegativeFiniteNumber(...values) {
+  for (const value of values) {
+    const numberValue = Number(value);
+    if (Number.isFinite(numberValue)) {
+      return Math.max(0, numberValue);
+    }
+  }
+  return null;
+}
+
+function normalizePlainObject(value = null) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function normalizeRequestRecoveryInput(requestRecovery = null) {
+  if (typeof requestRecovery === "string") {
+    return {
+      label: requestRecovery
+    };
+  }
+  return normalizePlainObject(requestRecovery);
+}
+
+function normalizeRequestRecoveryMethod(value = "") {
+  return normalizeText(value).toUpperCase();
+}
+
+function isRequestRecoveryMetaDisabled(sourceJskitMeta = {}, sourceMeta = {}) {
+  return Boolean(
+    sourceJskitMeta.requestRecovery === false ||
+      sourceMeta.jskitRequestRecovery === false ||
+      sourceMeta.requestRecovery === false
+  );
+}
+
+function hasUsableMetaValue(source = {}, key = "") {
+  return Object.hasOwn(source, key) && source[key] !== undefined && source[key] !== null && source[key] !== "";
+}
+
+function buildRequestRecoveryMeta(requestRecovery = null, defaults = {}) {
+  if (requestRecovery === false) {
+    return {
+      jskit: {
+        requestRecovery: false
+      }
+    };
+  }
+
+  const fallback = normalizePlainObject(defaults);
+  const source = normalizeRequestRecoveryInput(requestRecovery);
+  if (source.requestRecovery === false || source.enabled === false) {
+    return {
+      jskit: {
+        requestRecovery: false
+      }
+    };
+  }
+
+  const label = firstNormalizedText(
+    source.requestRecoveryLabel,
+    source.label,
+    fallback.requestRecoveryLabel,
+    fallback.label
+  );
+  const recoverySource = firstNormalizedText(
+    source.requestRecoverySource,
+    source.source,
+    fallback.requestRecoverySource,
+    fallback.source
+  );
+  const dedupeKey = firstNormalizedText(
+    source.requestRecoveryDedupeKey,
+    source.dedupeKey,
+    fallback.requestRecoveryDedupeKey,
+    fallback.dedupeKey
+  );
+  const method = normalizeRequestRecoveryMethod(
+    firstNormalizedText(
+      source.requestRecoveryMethod,
+      source.method,
+      fallback.requestRecoveryMethod,
+      fallback.method
+    )
+  );
+  const dedupeWindowMs = firstNonNegativeFiniteNumber(
+    source.requestRecoveryDedupeWindowMs,
+    source.dedupeWindowMs,
+    fallback.requestRecoveryDedupeWindowMs,
+    fallback.dedupeWindowMs
+  );
+
+  const jskit = {};
+  if (label) {
+    jskit.requestRecoveryLabel = label;
+  }
+  if (recoverySource) {
+    jskit.requestRecoverySource = recoverySource;
+  }
+  if (dedupeKey) {
+    jskit.requestRecoveryDedupeKey = dedupeKey;
+  }
+  if (method) {
+    jskit.requestRecoveryMethod = method;
+  }
+  if (dedupeWindowMs !== null) {
+    jskit.requestRecoveryDedupeWindowMs = dedupeWindowMs;
+  }
+
+  return Object.keys(jskit).length > 0 ? { jskit } : {};
+}
+
+function hasRequestRecoveryMetaValue(sourceJskitMeta = {}, sourceMeta = {}, key = "") {
+  const suffix = String(key || "").trim();
+  if (!suffix) {
+    return false;
+  }
+
+  const jskitKey = `requestRecovery${suffix}`;
+  const legacyJskitKey = `jskitRequestRecovery${suffix}`;
+  const legacyKey = `requestRecovery${suffix}`;
+
+  return Boolean(
+    hasUsableMetaValue(sourceJskitMeta, jskitKey) ||
+      hasUsableMetaValue(sourceMeta, legacyJskitKey) ||
+      hasUsableMetaValue(sourceMeta, legacyKey)
+  );
+}
+
+function resolveRequestRecoveryDefaults(queryOptions = null, defaults = {}) {
+  const sourceOptions = normalizePlainObject(queryOptions);
+  const sourceMeta = normalizePlainObject(sourceOptions.meta);
+  const sourceJskitMeta = normalizePlainObject(sourceMeta.jskit);
+  const fallback = normalizePlainObject(defaults);
+  if (isRequestRecoveryMetaDisabled(sourceJskitMeta, sourceMeta)) {
+    return {};
+  }
+
+  const hasExplicitLabel = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "Label");
+  const hasExplicitSource = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "Source");
+  const hasExplicitDedupeKey = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "DedupeKey");
+  const hasExplicitDedupeWindowMs = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "DedupeWindowMs");
+  const hasExplicitMethod = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "Method");
+
+  return {
+    ...fallback,
+    requestRecoveryLabel: hasExplicitLabel ? "" : fallback.requestRecoveryLabel,
+    label: hasExplicitLabel ? "" : fallback.label,
+    requestRecoverySource: hasExplicitSource ? "" : fallback.requestRecoverySource,
+    source: hasExplicitSource ? "" : fallback.source,
+    requestRecoveryDedupeKey: hasExplicitDedupeKey ? "" : fallback.requestRecoveryDedupeKey,
+    dedupeKey: hasExplicitDedupeKey ? "" : fallback.dedupeKey,
+    requestRecoveryDedupeWindowMs: hasExplicitDedupeWindowMs ? "" : fallback.requestRecoveryDedupeWindowMs,
+    dedupeWindowMs: hasExplicitDedupeWindowMs ? "" : fallback.dedupeWindowMs,
+    requestRecoveryMethod: hasExplicitMethod ? "" : fallback.requestRecoveryMethod,
+    method: hasExplicitMethod ? "" : fallback.method
+  };
+}
+
+function mergeRequestRecoveryQueryMeta(queryOptions = null, requestRecovery = null, defaults = {}) {
+  const sourceOptions = normalizePlainObject(queryOptions);
+  const effectiveDefaults =
+    requestRecovery == null
+      ? resolveRequestRecoveryDefaults(sourceOptions, defaults)
+      : normalizePlainObject(defaults);
+  const meta = buildRequestRecoveryMeta(requestRecovery, effectiveDefaults);
+  if (Object.keys(meta).length < 1) {
+    return sourceOptions;
+  }
+  return mergeQueryMeta(sourceOptions, meta);
+}
+
 export {
+  buildRequestRecoveryMeta,
   hasResolvedQueryData,
-  mergeQueryMeta
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
 };

package/src/client/composables/useCommand.js

@@ -17,6 +17,7 @@ function useCommand({
   apiSuffix = "",
   runPermissions = [],
   writeMethod = "POST",
+  client = null,
   transport = null,
   placementSource = "users-web.command",
   fallbackRunError = "Unable to complete action.",
@@ -52,6 +53,7 @@ function useCommand({
   const resource = useEndpointResource({
     path: operationScope.apiPath,
     enabled: false,
+    client,
     writeMethod,
     transport,
     fallbackSaveError: fallbackRunError

package/src/client/composables/useCrudListScreen.js

@@ -31,6 +31,7 @@ function useCrudListScreen({
   listFilters = {},
   listBulkActions = [],
   routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]),
+  requestRecoveryLabel = "Records",
   fallbackLoadError = "Unable to load records."
 } = {}) {
   const filterRuntime = useCrudListFilters(listFilters);
@@ -62,6 +63,7 @@ function useCrudListScreen({
       queryParamBlacklist: routeQueryBlacklist
     },
     placementSource: `ui-generator.${normalizedResourceNamespace}.list`,
+    requestRecoveryLabel,
     fallbackLoadError,
     recordIdParam,
     recordIdSelector,

package/src/client/composables/useCrudViewScreen.js

@@ -12,6 +12,7 @@ function useCrudViewScreen({
   listUrlTemplate = "",
   editUrlTemplate = "",
   recordChangedEvent = "",
+  requestRecoveryLabel = "Record",
   fallbackLoadError = "Unable to load record.",
   notFoundMessage = "Record not found."
 } = {}) {
@@ -31,6 +32,7 @@ function useCrudViewScreen({
       String(workspaceSlug || "")
     ],
     placementSource: `ui-generator.${normalizedResourceNamespace}.view`,
+    requestRecoveryLabel,
     fallbackLoadError,
     notFoundMessage,
     listUrlTemplate,

package/src/client/lib/httpClient.js

@@ -1,10 +1,47 @@
 import { createTransientRetryHttpClient } from "@jskit-ai/http-runtime/client";
 
-const usersWebHttpClient = createTransientRetryHttpClient({
-  credentials: "include",
-  csrf: {
-    sessionPath: "/api/session"
-  }
-});
-
-export { usersWebHttpClient };
+function normalizeOptions(value = null) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function createUsersWebHttpClient(options = {}) {
+  const source = normalizeOptions(options);
+  const sourceCsrf = normalizeOptions(source.csrf);
+
+  return createTransientRetryHttpClient({
+    ...source,
+    credentials: source.credentials ?? "include",
+    csrf: {
+      sessionPath: "/api/session",
+      ...sourceCsrf
+    }
+  });
+}
+
+let usersWebHttpClient = createUsersWebHttpClient();
+
+function configureUsersWebHttpClient(optionsOrClient = {}) {
+  const source = normalizeOptions(optionsOrClient);
+  usersWebHttpClient =
+    typeof source.request === "function"
+      ? source
+      : createUsersWebHttpClient(source);
+  return usersWebHttpClient;
+}
+
+function getUsersWebHttpClient() {
+  return usersWebHttpClient;
+}
+
+function resetUsersWebHttpClientForTests() {
+  usersWebHttpClient = createUsersWebHttpClient();
+  return usersWebHttpClient;
+}
+
+export {
+  configureUsersWebHttpClient,
+  createUsersWebHttpClient,
+  getUsersWebHttpClient,
+  resetUsersWebHttpClientForTests,
+  usersWebHttpClient
+};

package/test/requestTransportOptions.test.js

@@ -9,6 +9,11 @@ import {
   buildEndpointWriteRequestOptions,
   useEndpointResource
 } from "../src/client/composables/runtime/useEndpointResource.js";
+import { useCommand } from "../src/client/composables/useCommand.js";
+import {
+  configureUsersWebHttpClient,
+  resetUsersWebHttpClientForTests
+} from "../src/client/lib/httpClient.js";
 import { buildListRequestOptions } from "../src/client/composables/runtime/useListCore.js";
 import {
   resolveOperationRealtimeOptions
@@ -249,3 +254,152 @@ test("endpoint resources invalidate their query key from configured realtime eve
     }
   ]);
 });
+
+test("endpoint resource reads attach request recovery metadata to query options", async () => {
+  const queryClient = new QueryClient();
+  const queryKey = ["project-access", "beepollen"];
+  const app = createSSRApp({
+    setup() {
+      useEndpointResource({
+        queryKey,
+        path: "/api/project-access",
+        client: {
+          async request() {
+            return {};
+          }
+        },
+        requestRecovery: {
+          label: "Project access",
+          source: "project-access.panel",
+          dedupeKey: "project-access"
+        }
+      });
+      return () => h("div");
+    }
+  });
+  app.use(VueQueryPlugin, {
+    queryClient
+  });
+  await renderToString(app);
+
+  const query = queryClient.getQueryCache().find({
+    queryKey
+  });
+  assert.deepEqual(query?.meta?.jskit, {
+    requestRecoveryLabel: "Project access",
+    requestRecoverySource: "project-access.panel",
+    requestRecoveryDedupeKey: "project-access",
+    requestRecoveryMethod: "GET"
+  });
+});
+
+test("endpoint resources use the configured users-web HTTP client by default", async () => {
+  const queryClient = new QueryClient();
+  const calls = [];
+  let resource = null;
+  configureUsersWebHttpClient({
+    csrf: {
+      enabled: false
+    },
+    resolveRequestUrl(url) {
+      return url.replace(/^\/api\//u, "/api/app/beepollen/");
+    },
+    fetchImpl: async (url, options) => {
+      calls.push([url, options]);
+      return {
+        ok: true,
+        status: 200,
+        headers: {
+          get(name) {
+            return String(name || "").toLowerCase() === "content-type"
+              ? "application/json; charset=utf-8"
+              : "";
+          }
+        },
+        async json() {
+          return {
+            ok: true
+          };
+        }
+      };
+    }
+  });
+
+  try {
+    const app = createSSRApp({
+      setup() {
+        resource = useEndpointResource({
+          queryKey: ["vibe64-sessions"],
+          path: "/api/vibe64/sessions"
+        });
+        return () => h("div");
+      }
+    });
+    app.use(VueQueryPlugin, {
+      queryClient
+    });
+    await renderToString(app);
+
+    await resource.reload();
+
+    assert.equal(calls.at(-1)?.[0], "/api/app/beepollen/vibe64/sessions");
+  } finally {
+    resetUsersWebHttpClientForTests();
+  }
+});
+
+test("commands use the configured users-web HTTP client by default", async () => {
+  const queryClient = new QueryClient();
+  const calls = [];
+  let command = null;
+  configureUsersWebHttpClient({
+    csrf: {
+      enabled: false
+    },
+    resolveRequestUrl(url) {
+      return url.replace(/^\/api\//u, "/api/app/beepollen/");
+    },
+    fetchImpl: async (url, options) => {
+      calls.push([url, options]);
+      return {
+        ok: true,
+        status: 200,
+        headers: {
+          get(name) {
+            return String(name || "").toLowerCase() === "content-type"
+              ? "application/json; charset=utf-8"
+              : "";
+          }
+        },
+        async json() {
+          return {
+            ok: true
+          };
+        }
+      };
+    }
+  });
+
+  try {
+    const app = createSSRApp({
+      setup() {
+        command = useCommand({
+          access: "always",
+          apiSuffix: "/vibe64/sessions"
+        });
+        return () => h("div");
+      }
+    });
+    app.use(VueQueryPlugin, {
+      queryClient
+    });
+    await renderToString(app);
+
+    await command.run();
+
+    assert.equal(calls.at(-1)?.[0], "/api/app/beepollen/vibe64/sessions");
+    assert.equal(calls.at(-1)?.[1]?.method, "POST");
+  } finally {
+    resetUsersWebHttpClientForTests();
+  }
+});

package/test/resourceLoadStateHelpers.test.js

@@ -2,8 +2,10 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { ref } from "vue";
 import {
+  buildRequestRecoveryMeta,
   hasResolvedQueryData,
-  mergeQueryMeta
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
 } from "../src/client/composables/support/resourceLoadStateHelpers.js";
 
 test("hasResolvedQueryData returns true when the query succeeded", () => {
@@ -71,3 +73,117 @@ test("mergeQueryMeta preserves caller metadata while adding JSKIT refresh policy
     }
   );
 });
+
+test("request recovery query metadata supports labels and disabling recovery", () => {
+  assert.deepEqual(
+    buildRequestRecoveryMeta("Project access"),
+    {
+      jskit: {
+        requestRecoveryLabel: "Project access"
+      }
+    }
+  );
+
+  assert.deepEqual(
+    buildRequestRecoveryMeta(false),
+    {
+      jskit: {
+        requestRecovery: false
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta preserves caller metadata while adding recovery hints", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        staleTime: 5000,
+        meta: {
+          owner: "project-access",
+          jskit: {
+            refreshOnPull: true
+          }
+        }
+      },
+      {
+        label: "Project access",
+        source: "app.project-access",
+        dedupeKey: "project-access",
+        method: "get",
+        dedupeWindowMs: 100
+      }
+    ),
+    {
+      staleTime: 5000,
+      meta: {
+        owner: "project-access",
+        jskit: {
+          refreshOnPull: true,
+          requestRecoveryLabel: "Project access",
+          requestRecoverySource: "app.project-access",
+          requestRecoveryDedupeKey: "project-access",
+          requestRecoveryMethod: "GET",
+          requestRecoveryDedupeWindowMs: 100
+        }
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta does not overwrite explicit query recovery labels with defaults", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        meta: {
+          jskit: {
+            requestRecoveryLabel: "Explicit label",
+            requestRecoveryMethod: "HEAD",
+            requestRecoveryDedupeWindowMs: 0
+          }
+        }
+      },
+      null,
+      {
+        label: "Default label",
+        method: "GET",
+        dedupeWindowMs: 5000
+      }
+    ),
+    {
+      meta: {
+        jskit: {
+          requestRecoveryLabel: "Explicit label",
+          requestRecoveryMethod: "HEAD",
+          requestRecoveryDedupeWindowMs: 0
+        }
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta preserves disabled recovery metadata", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        meta: {
+          jskit: {
+            requestRecovery: false
+          }
+        }
+      },
+      null,
+      {
+        label: "Default label",
+        method: "GET"
+      }
+    ),
+    {
+      meta: {
+        jskit: {
+          requestRecovery: false
+        }
+      }
+    }
+  );
+});