@jskit-ai/users-web 0.1.4

package/src/client/composables/useView.js

@@ -0,0 +1,89 @@
+import { computed } from "vue";
+import { USERS_ROUTE_VISIBILITY_WORKSPACE } from "@jskit-ai/users-core/shared/support/usersVisibility";
+import { useViewCore } from "./useViewCore.js";
+import { useEndpointResource } from "./useEndpointResource.js";
+import { useOperationScope } from "./internal/useOperationScope.js";
+import { setupOperationErrorReporting } from "./operationUiHelpers.js";
+
+function useView({
+  ownershipFilter = USERS_ROUTE_VISIBILITY_WORKSPACE,
+  surfaceId = "",
+  access = "auto",
+  apiSuffix = "",
+  queryKeyFactory = null,
+  viewPermissions = [],
+  readMethod = "GET",
+  readEnabled = true,
+  placementSource = "users-web.view",
+  fallbackLoadError = "Unable to load resource.",
+  notFoundStatuses = [404],
+  notFoundMessage = "Record not found.",
+  model,
+  mapLoadedToModel,
+  realtime = null
+} = {}) {
+  const operationScope = useOperationScope({
+    ownershipFilter,
+    surfaceId,
+    access,
+    placementSource,
+    apiSuffix,
+    readEnabled,
+    queryKeyFactory,
+    permissionSets: {
+      view: viewPermissions
+    },
+    realtime
+  });
+  const canView = operationScope.permissionGate("view");
+
+  const resource = useEndpointResource({
+    queryKey: operationScope.queryKey,
+    path: operationScope.apiPath,
+    enabled: operationScope.queryCanRun(canView),
+    readMethod,
+    fallbackLoadError
+  });
+
+  const view = useViewCore({
+    resource,
+    model,
+    canView,
+    mapLoadedToModel,
+    notFoundStatuses,
+    notFoundMessage
+  });
+
+  const loadError = operationScope.loadError(view.loadError);
+  const isLoading = operationScope.isLoading(view.isLoading);
+  const isFetching = operationScope.isLoading(view.isFetching);
+  const isRefetching = computed(() => Boolean(isFetching.value && !isLoading.value));
+  setupOperationErrorReporting({
+    source: `${placementSource}.load`,
+    loadError,
+    notFoundError: view.notFoundError,
+    dedupeWindowMs: 0,
+    loadActionFactory: () => ({
+      label: "Retry",
+      dismissOnRun: true,
+      handler() {
+        void view.refresh();
+      }
+    })
+  });
+
+  return Object.freeze({
+    record: view.record,
+    canView,
+    isLoading,
+    isFetching,
+    isRefetching,
+    isNotFound: view.isNotFound,
+    notFoundError: view.notFoundError,
+    loadError,
+    refresh: view.refresh,
+    resource
+  });
+}
+
+export { useView };

package/src/client/composables/useViewCore.js

@@ -0,0 +1,104 @@
+import { computed, watch } from "vue";
+import { captureModelSnapshot, restoreModelSnapshot } from "./modelStateHelpers.js";
+
+function normalizeStatusList(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => Number(entry)).filter((entry) => Number.isInteger(entry) && entry > 0);
+  }
+
+  return [404];
+}
+
+function useViewCore({
+  resource,
+  model,
+  canView,
+  mapLoadedToModel,
+  notFoundStatuses = [404],
+  notFoundMessage = "Record not found."
+} = {}) {
+  const statusList = normalizeStatusList(notFoundStatuses);
+  const modelSnapshot = captureModelSnapshot(model);
+
+  watch(
+    () => resource?.query?.isPending?.value,
+    (isPending) => {
+      if (!isPending || !modelSnapshot) {
+        return;
+      }
+
+      restoreModelSnapshot(model, modelSnapshot);
+    },
+    {
+      immediate: true
+    }
+  );
+
+  watch(
+    () => resource?.data?.value,
+    (payload) => {
+      if (!payload || typeof mapLoadedToModel !== "function") {
+        return;
+      }
+
+      mapLoadedToModel(model, payload, {
+        resource
+      });
+    },
+    {
+      immediate: true
+    }
+  );
+
+  const data = resource?.data;
+  const record = computed(() => (model !== undefined ? model : data?.value));
+  const isLoading = computed(() => Boolean(resource?.query?.isPending?.value));
+  const isFetching = computed(() => Boolean(resource?.query?.isFetching?.value));
+  const error = computed(() => resource?.query?.error?.value || null);
+
+  const isNotFound = computed(() => {
+    const status = Number(error.value?.status || 0);
+    return statusList.includes(status);
+  });
+
+  const notFoundError = computed(() => {
+    if (!isNotFound.value) {
+      return "";
+    }
+
+    return String(notFoundMessage || "Record not found.");
+  });
+
+  const loadError = computed(() => {
+    if (isNotFound.value) {
+      return "";
+    }
+
+    return String(resource?.loadError?.value || "").trim();
+  });
+
+  const resolvedCanView = computed(() => {
+    if (canView === undefined) {
+      return true;
+    }
+
+    return Boolean(canView?.value);
+  });
+
+  async function refresh() {
+    return resource?.reload?.();
+  }
+
+  return Object.freeze({
+    record,
+    isLoading,
+    isFetching,
+    isNotFound,
+    notFoundError,
+    loadError,
+    canView: resolvedCanView,
+    refresh
+  });
+}
+
+export { useViewCore };

package/src/client/composables/useWorkspaceRouteContext.js

@@ -0,0 +1,28 @@
+import { computed } from "vue";
+import {
+  extractWorkspaceSlugFromSurfacePathname
+} from "../lib/workspaceSurfacePaths.js";
+import { useSurfaceRouteContext } from "./useSurfaceRouteContext.js";
+
+function useWorkspaceRouteContext() {
+  const { route, routePath, placementContext, mergePlacementContext, currentSurfaceId } = useSurfaceRouteContext();
+  const workspaceSlugFromRoute = computed(() => {
+    const workspaceSlug = extractWorkspaceSlugFromSurfacePathname(
+      placementContext.value,
+      currentSurfaceId.value,
+      routePath.value
+    );
+    return String(workspaceSlug || "").trim();
+  });
+
+  return Object.freeze({
+    route,
+    routePath,
+    placementContext,
+    mergePlacementContext,
+    currentSurfaceId,
+    workspaceSlugFromRoute
+  });
+}
+
+export { useWorkspaceRouteContext };

package/src/client/composables/useWorkspaceSurfaceId.js

@@ -0,0 +1,43 @@
+import { computed, unref } from "vue";
+import { resolveSurfaceIdFromPlacementPathname } from "@jskit-ai/shell-web/client/placement";
+import {
+  resolveSurfaceSwitchTargetsFromPlacementContext,
+  surfaceRequiresWorkspaceFromPlacementContext
+} from "../lib/workspaceSurfaceContext.js";
+
+function resolveCurrentPathname(route = null) {
+  const routePath = String(route?.path || "").trim();
+  if (routePath) {
+    return routePath;
+  }
+
+  if (typeof window === "object" && window?.location?.pathname) {
+    return String(window.location.pathname);
+  }
+
+  return "/";
+}
+
+function useWorkspaceSurfaceId({ route = null, placementContext = null } = {}) {
+  const currentSurfaceId = computed(() =>
+    resolveSurfaceIdFromPlacementPathname(unref(placementContext), resolveCurrentPathname(route))
+  );
+
+  const workspaceSurfaceId = computed(() => {
+    const contextValue = unref(placementContext);
+    const surfaceId = String(currentSurfaceId.value || "").trim().toLowerCase();
+    if (surfaceId && surfaceRequiresWorkspaceFromPlacementContext(contextValue, surfaceId)) {
+      return surfaceId;
+    }
+
+    const targets = resolveSurfaceSwitchTargetsFromPlacementContext(contextValue, surfaceId);
+    return String(targets.workspaceSurfaceId || "").trim().toLowerCase();
+  });
+
+  return Object.freeze({
+    currentSurfaceId,
+    workspaceSurfaceId
+  });
+}
+
+export { useWorkspaceSurfaceId };

package/src/client/index.js

@@ -0,0 +1,7 @@
+import { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
+
+export { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
+
+const clientProviders = Object.freeze([UsersWebClientProvider]);
+
+export { clientProviders };

package/src/client/lib/bootstrap.js

@@ -0,0 +1,95 @@
+function buildBootstrapApiPath(workspaceSlug = "") {
+  const normalizedWorkspaceSlug = String(workspaceSlug || "").trim();
+  if (!normalizedWorkspaceSlug) {
+    return "/api/bootstrap";
+  }
+
+  const query = new URLSearchParams({
+    workspaceSlug: normalizedWorkspaceSlug
+  });
+  return `/api/bootstrap?${query.toString()}`;
+}
+
+function normalizeWorkspaceEntry(entry) {
+  if (!entry || typeof entry !== "object") {
+    return null;
+  }
+
+  const id = Number(entry.id);
+  const slug = String(entry.slug || "").trim();
+  if (!Number.isInteger(id) || id < 1 || !slug) {
+    return null;
+  }
+
+  return Object.freeze({
+    id,
+    slug,
+    name: String(entry.name || slug).trim() || slug,
+    color: String(entry.color || "").trim(),
+    avatarUrl: String(entry.avatarUrl || "").trim(),
+    roleId: String(entry.roleId || "member").trim().toLowerCase() || "member",
+    isAccessible: entry.isAccessible !== false
+  });
+}
+
+function normalizeWorkspaceList(list) {
+  const source = Array.isArray(list) ? list : [];
+  return source.map(normalizeWorkspaceEntry).filter(Boolean);
+}
+
+function findWorkspaceBySlug(list, workspaceSlug) {
+  const normalizedWorkspaceSlug = String(workspaceSlug || "").trim();
+  if (!normalizedWorkspaceSlug) {
+    return null;
+  }
+
+  const source = Array.isArray(list) ? list : [];
+  for (const entry of source) {
+    const normalizedEntry = normalizeWorkspaceEntry(entry);
+    if (normalizedEntry && normalizedEntry.slug === normalizedWorkspaceSlug) {
+      return normalizedEntry;
+    }
+  }
+
+  return null;
+}
+
+function resolvePlacementUserFromBootstrapPayload(payload = {}, currentUser = null) {
+  const source = payload && typeof payload === "object" ? payload : {};
+  const session = source.session && typeof source.session === "object" ? source.session : {};
+  if (session.authenticated !== true) {
+    return null;
+  }
+
+  const profile = source.profile && typeof source.profile === "object" ? source.profile : {};
+  const profileAvatar = profile.avatar && typeof profile.avatar === "object" ? profile.avatar : {};
+  const fallbackUser = currentUser && typeof currentUser === "object" ? currentUser : {};
+  const nextUser = {};
+
+  const userId = Number(session.userId || fallbackUser.id || 0);
+  if (Number.isInteger(userId) && userId > 0) {
+    nextUser.id = userId;
+  }
+
+  const displayName = String(profile.displayName || fallbackUser.displayName || fallbackUser.name || "").trim();
+  if (displayName) {
+    nextUser.displayName = displayName;
+    nextUser.name = displayName;
+  }
+
+  const email = String(profile.email || fallbackUser.email || "").trim().toLowerCase();
+  if (email) {
+    nextUser.email = email;
+  }
+
+  nextUser.avatarUrl = String(profileAvatar.effectiveUrl || fallbackUser.avatarUrl || "").trim();
+  return Object.freeze(nextUser);
+}
+
+export {
+  buildBootstrapApiPath,
+  normalizeWorkspaceEntry,
+  normalizeWorkspaceList,
+  findWorkspaceBySlug,
+  resolvePlacementUserFromBootstrapPayload
+};

package/src/client/lib/httpClient.js

@@ -0,0 +1,67 @@
+import { createHttpClient } from "@jskit-ai/http-runtime/client";
+import {
+  isTransientQueryError,
+  transientQueryRetryDelay
+} from "@jskit-ai/kernel/shared/support";
+
+const SAFE_RETRY_METHODS = Object.freeze(new Set(["GET", "HEAD"]));
+const MAX_TRANSIENT_HTTP_RETRIES = 2;
+
+const baseUsersWebHttpClient = createHttpClient({
+  credentials: "include",
+  csrf: {
+    sessionPath: "/api/session"
+  }
+});
+
+function sleep(delayMs) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+}
+
+function shouldRetryTransientHttpFailure(error, method, attemptIndex) {
+  if (!SAFE_RETRY_METHODS.has(String(method || "GET").toUpperCase())) {
+    return false;
+  }
+  if (!isTransientQueryError(error)) {
+    return false;
+  }
+  return Number(attemptIndex) < MAX_TRANSIENT_HTTP_RETRIES;
+}
+
+async function requestWithTransientRetry(executor, method) {
+  let attemptIndex = 0;
+
+  while (true) {
+    try {
+      return await executor();
+    } catch (error) {
+      if (!shouldRetryTransientHttpFailure(error, method, attemptIndex)) {
+        throw error;
+      }
+      attemptIndex += 1;
+      await sleep(transientQueryRetryDelay(attemptIndex));
+    }
+  }
+}
+
+const usersWebHttpClient = Object.freeze({
+  ...baseUsersWebHttpClient,
+  request(url, requestOptions = {}, state = null) {
+    const method = String(requestOptions?.method || "GET").toUpperCase();
+    return requestWithTransientRetry(
+      () => baseUsersWebHttpClient.request(url, requestOptions, state),
+      method
+    );
+  },
+  requestStream(url, requestOptions = {}, handlers = {}, state = null) {
+    const method = String(requestOptions?.method || "GET").toUpperCase();
+    return requestWithTransientRetry(
+      () => baseUsersWebHttpClient.requestStream(url, requestOptions, handlers, state),
+      method
+    );
+  }
+});
+
+export { usersWebHttpClient };

package/src/client/lib/menuIcons.js

@@ -0,0 +1,192 @@
+import {
+  mdiAccountCircleOutline,
+  mdiAccountCogOutline,
+  mdiAccountGroupOutline,
+  mdiArrowRightCircleOutline,
+  mdiClipboardListOutline,
+  mdiCogOutline,
+  mdiConsoleNetworkOutline,
+  mdiFolderOutline,
+  mdiHomeVariantOutline,
+  mdiLogin,
+  mdiLogout,
+  mdiRobotOutline,
+  mdiShieldCrownOutline,
+  mdiViewDashboardOutline,
+  mdiViewListOutline
+} from "@mdi/js";
+import { isExternalLinkTarget, splitPathQueryHash } from "@jskit-ai/kernel/shared/support/linkPath";
+import { normalizePathname as normalizeKernelPathname } from "@jskit-ai/kernel/shared/surface/paths";
+
+const SURFACE_SWITCH_ICON_BY_ID = Object.freeze({
+  home: mdiHomeVariantOutline,
+  app: mdiViewDashboardOutline,
+  admin: mdiShieldCrownOutline,
+  console: mdiConsoleNetworkOutline
+});
+
+function normalizeText(value) {
+  return String(value || "").trim();
+}
+
+function normalizePathname(value) {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    return "";
+  }
+
+  if (isExternalLinkTarget(normalizedValue)) {
+    const isHttpTarget = normalizedValue.startsWith("http://") || normalizedValue.startsWith("https://");
+    if (!isHttpTarget) {
+      return "";
+    }
+
+    let parsedPathname = "";
+    try {
+      parsedPathname = String(new URL(normalizedValue).pathname || "");
+    } catch {
+      return "";
+    }
+
+    const normalizedPathname = normalizeText(parsedPathname);
+    if (!normalizedPathname) {
+      return "";
+    }
+    return normalizeKernelPathname(normalizedPathname).toLowerCase();
+  }
+
+  const { pathname } = splitPathQueryHash(normalizedValue);
+  const normalizedPathname = normalizeText(pathname);
+  if (!normalizedPathname) {
+    return "";
+  }
+
+  return normalizeKernelPathname(normalizedPathname).toLowerCase();
+}
+
+function resolveSurfaceSwitchIdFromLabel(label = "") {
+  const normalizedLabel = normalizeText(label).toLowerCase();
+  if (!normalizedLabel.startsWith("go to ")) {
+    return "";
+  }
+  return normalizeText(normalizedLabel.slice("go to ".length));
+}
+
+function resolveSurfaceSwitchIcon(surfaceId = "", explicitIcon = "") {
+  const normalizedExplicitIcon = normalizeText(explicitIcon);
+  if (normalizedExplicitIcon) {
+    return normalizedExplicitIcon;
+  }
+
+  const normalizedSurfaceId = normalizeText(surfaceId).toLowerCase();
+  return SURFACE_SWITCH_ICON_BY_ID[normalizedSurfaceId] || mdiArrowRightCircleOutline;
+}
+
+function resolveMenuLinkIcon({ icon = "", label = "", to = "" } = {}) {
+  const normalizedIcon = normalizeText(icon);
+  if (normalizedIcon) {
+    return normalizedIcon;
+  }
+
+  const normalizedLabel = normalizeText(label).toLowerCase();
+  const normalizedPathname = normalizePathname(to);
+  if (!normalizedLabel && !normalizedPathname) {
+    return "";
+  }
+
+  const surfaceSwitchSurfaceId = resolveSurfaceSwitchIdFromLabel(normalizedLabel);
+  if (surfaceSwitchSurfaceId) {
+    return resolveSurfaceSwitchIcon(surfaceSwitchSurfaceId);
+  }
+
+  if (
+    normalizedLabel.includes("sign in") ||
+    normalizedPathname.includes("/auth/login")
+  ) {
+    return mdiLogin;
+  }
+
+  if (
+    normalizedLabel.includes("sign out") ||
+    normalizedPathname.includes("/auth/signout")
+  ) {
+    return mdiLogout;
+  }
+
+  if (
+    normalizedLabel.includes("account") ||
+    normalizedPathname.includes("/account")
+  ) {
+    if (
+      normalizedLabel.includes("settings") ||
+      normalizedPathname.includes("/settings") ||
+      normalizedPathname === "/account"
+    ) {
+      return mdiAccountCogOutline;
+    }
+    return mdiAccountCircleOutline;
+  }
+
+  if (
+    normalizedLabel.includes("members") ||
+    normalizedLabel.includes("team") ||
+    normalizedPathname.includes("/members")
+  ) {
+    return mdiAccountGroupOutline;
+  }
+
+  if (normalizedLabel.includes("assistant") || normalizedPathname.includes("/assistant")) {
+    return mdiRobotOutline;
+  }
+
+  if (
+    normalizedLabel.includes("console") ||
+    normalizedPathname.startsWith("/console")
+  ) {
+    return mdiConsoleNetworkOutline;
+  }
+
+  if (
+    normalizedLabel.includes("admin") ||
+    normalizedPathname.includes("/admin")
+  ) {
+    return mdiShieldCrownOutline;
+  }
+
+  if (normalizedLabel.includes("settings") || normalizedPathname.includes("/settings")) {
+    return mdiCogOutline;
+  }
+
+  if (
+    normalizedLabel.includes("home") ||
+    normalizedPathname === "/"
+  ) {
+    return mdiHomeVariantOutline;
+  }
+
+  if (
+    normalizedLabel.includes("workspace") ||
+    normalizedLabel.includes("dashboard") ||
+    normalizedPathname.includes("/w/")
+  ) {
+    return mdiViewDashboardOutline;
+  }
+
+  if (normalizedPathname) {
+    const segments = normalizedPathname.split("/").filter(Boolean);
+    if (segments.length === 1) {
+      return mdiFolderOutline;
+    }
+  }
+
+  if (normalizedLabel.includes("list")) {
+    return mdiClipboardListOutline;
+  }
+
+  return mdiViewListOutline;
+}
+
+export {
+  resolveMenuLinkIcon,
+  resolveSurfaceSwitchIcon
+};

package/src/client/lib/permissions.js

@@ -0,0 +1,34 @@
+import {
+  hasPermission,
+  normalizePermissionList
+} from "@jskit-ai/kernel/shared/support";
+
+function toPermissionSet(values) {
+  const normalized = normalizePermissionList(values);
+  if (normalized.length < 1) {
+    return new Set();
+  }
+  return new Set(normalized);
+}
+
+function arePermissionListsEqual(left, right) {
+  const leftSet = toPermissionSet(left);
+  const rightSet = toPermissionSet(right);
+  if (leftSet.size !== rightSet.size) {
+    return false;
+  }
+
+  for (const permission of leftSet) {
+    if (!rightSet.has(permission)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export {
+  normalizePermissionList,
+  arePermissionListsEqual,
+  hasPermission
+};