@everysk/apps-sdk 0.1.0 → 0.3.0-beta-20261016180126

package/src/api/workspace.ts

@@ -1,10 +1,14 @@
-import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+import type { AxiosInstance } from "axios";
 
-import type { AnyRecord } from "@/types/anyRecord";
-import type { Workspace, WorkspaceListResponse, WorkspaceSingleResponse } from "@/types/workspace";
+import type { EntitySingleResponse } from "@/types/entityQuery";
+import type { Workspace, WorkspaceListResponse } from "@/types/workspace";
+import { pageParams, request } from "./request";
 
 const baseUrl = "workspaces";
 
+/** The endpoint's envelope, private: `getWorkspace` returns the workspace itself. */
+type WorkspaceSingleResponse = EntitySingleResponse<"workspace", Workspace>;
+
 /**
  * getWorkspace
  *
@@ -12,61 +16,57 @@ const baseUrl = "workspaces";
  *
  * @param {AxiosInstance} api - Axios instance.
  * @param {string} name - Workspace name.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @returns {Promise<Workspace>} The fetched workspace.
  *
  * @throws {Error} If the request fails.
  */
-export const getWorkspace = async (api: AxiosInstance, name: string): Promise<Workspace> => {
-  if (!name) throw new Error("Workspace name is required to fetch a workspace");
-
-  try {
-    const response: AxiosResponse<WorkspaceSingleResponse> = await api.get(`${baseUrl}/${name}`);
-    return response.data.workspace;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error while fetching workspace");
-    }
+export const getWorkspace = async (
+    api: AxiosInstance,
+    name: string,
+    signal?: AbortSignal,
+): Promise<Workspace> => {
+    if (!name) throw new Error("Workspace name is required to fetch a workspace");
 
-    if (error instanceof Error) {
-      throw error;
-    }
+    const body = await request(
+        () => api.get<WorkspaceSingleResponse>(`${baseUrl}/${name}`, { signal }),
+        "Error fetching workspace",
+    );
+    return body.workspace;
+};
 
-    throw new Error("Error while fetching workspace");
-  }
+/** What `listWorkspaces` sends. */
+export type WorkspaceListParams = {
+    /** A name prefix. Sent as `query`. */
+    search?: string;
+    pageSize?: number;
+    pageToken?: string;
 };
 
 /**
  * listWorkspaces
  *
- * Fetches a list of workspaces with optional cursor-based pagination.
+ * Lists the account's workspaces, a page at a time.
+ *
+ * The one list that takes no workspace: the docs exempt it, and the endpoint ignores one. This
+ * function used to send it anyway, documented as "required by some API configurations".
  *
  * @param {AxiosInstance} api - Axios instance.
- * @param {string} [workspace] - Current workspace name. Sent as a query param via the legacy method, required by some API configurations.
- * @param {number} [pageSize] - Number of items per page.
- * @param {string} [pageToken] - Cursor token for the next page.
- * @returns {Promise<WorkspaceListResponse>} List of workspaces.
+ * @param {WorkspaceListParams} [params] - Search and paging.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
+ * @returns {Promise<WorkspaceListResponse>} A page of workspaces, with the cursor to the next one.
  *
  * @throws {Error} If the request fails.
  */
-export const listWorkspaces = async (api: AxiosInstance, workspace?: string, pageSize?: number, pageToken?: string): Promise<WorkspaceListResponse> => {
-  const params: AnyRecord = {};
-
-  if (workspace) params.workspace = workspace;
-  if (pageSize) params.page_size = pageSize;
-  if (pageToken) params.page_token = pageToken;
-
-  try {
-    const response: AxiosResponse<WorkspaceListResponse> = await api.get(baseUrl, { params });
-    return response.data;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error while fetching workspaces");
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
+export const listWorkspaces = async (
+    api: AxiosInstance,
+    { search, pageSize, pageToken }: WorkspaceListParams = {},
+    signal?: AbortSignal,
+): Promise<WorkspaceListResponse> => {
+    const params = pageParams({ search, pageSize, pageToken });
 
-    throw new Error("Error while fetching workspaces");
-  }
+    return request(
+        () => api.get<WorkspaceListResponse>(baseUrl, { params, signal }),
+        "Error listing workspaces",
+    );
 };

package/src/components/ui/Footer/index.tsx

@@ -1,6 +1,6 @@
-import type { PropsWithChildren } from "react"
+import type { PropsWithChildren } from "react";
 
-import { clsx } from 'clsx';
+import { clsx } from "clsx";
 import Paper from "@mui/material/Paper";
 import { useTheme, type Theme } from "@mui/material/styles";
 
@@ -10,11 +10,11 @@ export const Footer = ({ className, children }: PropsWithChildren<{ className?:
     const theme: Theme = useTheme();
     const paperProps: AnyRecord = {
         light: {
-            variant: 'outlined',
+            variant: "outlined",
         },
         dark: {
-            variant: 'elevation'
-        }
+            variant: "elevation",
+        },
     };
 
     return (
@@ -23,8 +23,9 @@ export const Footer = ({ className, children }: PropsWithChildren<{ className?:
             elevation={1}
             component="footer"
             className={clsx("flex shrink-0 grow-0 basis-auto h-16 pl-6 pr-6", className)}
-            {...paperProps?.[theme.palette.mode]} >
+            {...paperProps?.[theme.palette.mode]}
+        >
             {children}
         </Paper>
     );
-}
+};

package/src/components/ui/GlobalLoading/index.tsx

@@ -21,7 +21,14 @@ export const GlobalLoading = ({ isLoading, backdrop = true, message }: GlobalLoa
 
     if (!backdrop) {
         return (
-            <Box sx={{ display: "flex", justifyContent: "center", alignItems: "center", height: "100%" }}>
+            <Box
+                sx={{
+                    display: "flex",
+                    justifyContent: "center",
+                    alignItems: "center",
+                    height: "100%",
+                }}
+            >
                 {content}
             </Box>
         );
@@ -30,9 +37,12 @@ export const GlobalLoading = ({ isLoading, backdrop = true, message }: GlobalLoa
     return (
         <Backdrop
             open
-            sx={{ zIndex: (theme) => theme.zIndex.modal + 1, backgroundColor: "rgba(0, 0, 0, 0.3)" }}
+            sx={{
+                zIndex: (theme) => theme.zIndex.modal + 1,
+                backgroundColor: "rgba(0, 0, 0, 0.3)",
+            }}
         >
             {content}
         </Backdrop>
     );
-}
+};

package/src/components/ui/PageContainer/index.tsx

@@ -1,11 +1,18 @@
 import clsx from "clsx";
 import type { PropsWithChildren, ReactNode } from "react";
 
-export const PageContainer = ({ header, footer, contentClassName, children }: PropsWithChildren<{ header?: ReactNode, footer?: ReactNode, contentClassName?: string }>) => {
+export const PageContainer = ({
+    header,
+    footer,
+    contentClassName,
+    children,
+}: PropsWithChildren<{ header?: ReactNode; footer?: ReactNode; contentClassName?: string }>) => {
     return (
         <div className="flex flex-col w-full h-full overflow-hidden">
             {header}
-            <div className={clsx("flex shrink-1 grow-1 basis-auto overflow-auto", contentClassName)}>
+            <div
+                className={clsx("flex shrink-1 grow-1 basis-auto overflow-auto", contentClassName)}
+            >
                 {children}
             </div>
             {footer}

package/src/components/ui/Toolbar/index.tsx

@@ -1,44 +1,119 @@
-import type { PropsWithChildren } from 'react';
+import type { PropsWithChildren, ReactNode } from "react";
 
-import AppBar from '@mui/material/AppBar';
-import { useTheme, type Theme } from '@mui/material/styles';
-import MuiToolbar from '@mui/material/Toolbar';
+import AppBar, { type AppBarProps } from "@mui/material/AppBar";
+import { useTheme, type PaletteMode, type Theme } from "@mui/material/styles";
+import MuiToolbar from "@mui/material/Toolbar";
+import Typography from "@mui/material/Typography";
 
-import clsx from 'clsx';
+import clsx from "clsx";
 
-import { EveryskIcon } from '@/components/ui/EveryskIcon';
+import { EveryskIcon } from "@/components/ui/EveryskIcon";
 
-import type { AnyRecord } from '@/types/anyRecord';
+/**
+ * The names follow MUI's own header components: `title`, `subheader` and `action` are
+ * `CardHeader`'s, `logo` is Toolpad's `branding.logo`, and the boolean reads as what turning
+ * it *on* does (`hideLogo`), because an MUI boolean defaults to `false`.
+ */
+export type ToolbarProps = PropsWithChildren<{
+    /**
+     * Rendered before the logo. It is a slot rather than `onToggleMenu`/`onBack` props because
+     * the buttons that go here belong to whatever shell hosts the bar (a drawer toggle, a back
+     * button), and a prop per button would make the bar grow with every shell.
+     */
+    startAction?: ReactNode;
+    /** Replaces the Everysk mark, for an app that carries its client's. */
+    logo?: ReactNode;
+    /**
+     * A flag rather than `logo={null}` or `logo={false}` (MUI's `Alert.icon` spelling), so
+     * that no single prop means default, replace and remove at once. It wins over `logo`.
+     */
+    hideLogo?: boolean;
+    /** The page heading. An `h1`: the bar is where the page says what it is. */
+    title?: ReactNode;
+    subheader?: ReactNode;
+    /** Pushed to the far end of the bar, so no page has to align it with `justify-between`. */
+    action?: ReactNode;
+    /**
+     * `relative` by default: in `PageContainer` only the content scrolls, so the bar stays put
+     * by layout. `sticky` is for a page that scrolls as a whole.
+     */
+    position?: AppBarProps["position"];
+    /** Applied to the content row. */
+    className?: string;
+}>;
 
-export const Toolbar = ({ children, className }: PropsWithChildren<{ className?: string }>) => {
-    const theme: Theme = useTheme();
+/**
+ * What a page supplies, as opposed to what the chrome around it decides (`startAction`, the
+ * logo, `position`). A shell that renders the bar for its pages holds this, and a page
+ * publishes it without ever rendering the bar itself.
+ */
+export type ToolbarContent = Pick<ToolbarProps, "title" | "subheader" | "action" | "children">;
 
-    const styles: AnyRecord = {
-        light: {
-            color: 'transparent',
-            elevation: 0,
-            sx: {
-                border: "1px solid rgba(0, 0, 0, 0.12)"
-            }
+// Typed as AppBar props, not `AnyRecord`: a loose map here is what let an invalid `color: ''`
+// through for as long as it did.
+const MODE_PROPS: Record<PaletteMode, AppBarProps> = {
+    light: {
+        color: "transparent",
+        elevation: 0,
+        sx: {
+            border: "1px solid rgba(0, 0, 0, 0.12)",
         },
-        dark: {
-            // 'default', not ''. An empty string is not a value the AppBar API takes — it
-            // produced the class `MuiAppBar-color` with no variant suffix, which rendered the
-            // same only because the brand theme overrides AppBar anyway. This is the explicit
-            // spelling of what already happens, and it survives a theme that does not.
-            color: 'default',
-            elevation: 1
-        }
-    };
+    },
+    dark: {
+        // 'default', not ''. An empty string is not a value the AppBar API takes — it
+        // produced the class `MuiAppBar-color` with no variant suffix, which rendered the
+        // same only because the brand theme overrides AppBar anyway. This is the explicit
+        // spelling of what already happens, and it survives a theme that does not.
+        color: "default",
+        elevation: 1,
+    },
+};
+
+export const Toolbar = ({
+    startAction,
+    logo,
+    hideLogo = false,
+    title,
+    subheader,
+    action,
+    position = "relative",
+    className,
+    children,
+}: ToolbarProps) => {
+    const theme: Theme = useTheme();
 
     return (
-        <AppBar position='relative' {...styles?.[theme.palette.mode]}>
-            <MuiToolbar >
-                <div className={clsx("flex items-center gap-4", className)}>
-                    <EveryskIcon />
+        <AppBar position={position} {...MODE_PROPS[theme.palette.mode]}>
+            <MuiToolbar>
+                <div className={clsx("flex items-center gap-4 w-full min-w-0", className)}>
+                    {startAction && <div className="flex items-center shrink-0">{startAction}</div>}
+
+                    {!hideLogo && (logo ?? <EveryskIcon titleAccess="Everysk" />)}
+
+                    {(title || subheader) && (
+                        // `min-w-0` is what lets the title truncate instead of pushing the
+                        // action out of the bar.
+                        <div className="flex flex-col min-w-0">
+                            {title && (
+                                <Typography variant="h6" component="h1" noWrap>
+                                    {title}
+                                </Typography>
+                            )}
+                            {subheader && (
+                                <Typography variant="body2" color="text.secondary" noWrap>
+                                    {subheader}
+                                </Typography>
+                            )}
+                        </div>
+                    )}
+
                     {children}
+
+                    {action && (
+                        <div className="flex items-center gap-3 ml-auto shrink-0">{action}</div>
+                    )}
                 </div>
             </MuiToolbar>
         </AppBar>
     );
-}
+};

package/src/contexts/appAlertContext/provider.tsx

@@ -66,7 +66,7 @@ export const AppAlertProvider = ({ children }: PropsWithChildren) => {
 
     const value: AppAlertContextType = useMemo(
         () => ({ showAlert, hideAlert }),
-        [showAlert, hideAlert]
+        [showAlert, hideAlert],
     );
 
     return (

package/src/contexts/appAlertContext/types.ts

@@ -12,6 +12,6 @@ export type ShowAlertOptions = Partial<Omit<AppAlertState, "open">> & {
 };
 
 export type AppAlertContextType = {
-  showAlert: (options: ShowAlertOptions) => void;
-  hideAlert: () => void;
-};
+    showAlert: (options: ShowAlertOptions) => void;
+    hideAlert: () => void;
+};

package/src/contexts/appConfigContext/index.tsx

@@ -1,4 +1,4 @@
 import { createContext } from "react";
 import type { AppConfigContextType } from "./types";
 
-export const AppConfigContext = createContext<AppConfigContextType | null>(null)
+export const AppConfigContext = createContext<AppConfigContextType | null>(null);

package/src/contexts/appConfigContext/provider.tsx

@@ -59,9 +59,5 @@ export const AppConfigProvider = ({
         };
     }, [appId, appEnvironmentVar]);
 
-    return (
-        <AppConfigContext.Provider value={value}>
-            {children}
-        </AppConfigContext.Provider>
-    );
+    return <AppConfigContext.Provider value={value}>{children}</AppConfigContext.Provider>;
 };

package/src/contexts/webSocketContext/handler.ts

@@ -1,6 +1,7 @@
 import { io, type Socket } from "socket.io-client";
 
-import type { WebSocketNotification, WebSocketStatus, WebsocketsConfig } from "./types";
+import type { WebsocketsConfig } from "@/api/websocketsConfig";
+import type { WebSocketNotification, WebSocketStatus } from "./types";
 
 function isWebSocketNotification(value: unknown): value is WebSocketNotification {
     return (
@@ -35,7 +36,12 @@ export class WebSocketHandler {
     private _everyskUID: string;
     private _listeners: Set<(msg: WebSocketNotification) => void> = new Set();
 
-    constructor({ appConnectionURL, appChannelID, everyskUID, onStatusChange }: WebSocketHandlerConfig) {
+    constructor({
+        appConnectionURL,
+        appChannelID,
+        everyskUID,
+        onStatusChange,
+    }: WebSocketHandlerConfig) {
         this._everyskUID = everyskUID;
 
         this._socket = io(appConnectionURL, {

package/src/contexts/webSocketContext/hooks/useWebSocket/index.ts

@@ -7,7 +7,7 @@ import { WebSocketContext } from "../..";
  *
  * Convenience hook that reads the WebSocket API from `WebSocketContext`.
  *
- * Returns: `{ subscribe, lastMessage, status }` (see `WebSocketContextType`).
+ * Returns: `{ subscribe, subscribeStatus, lastMessage, status }` (see `WebSocketContextType`).
  *
  * @throws {Error} If used outside of `<WebSocketProvider>`.
  */

package/src/contexts/webSocketContext/provider.tsx

@@ -5,7 +5,24 @@ import { useAxios } from "@/hooks/useAxios";
 import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
 import { WebSocketContext } from ".";
 import { WebSocketHandler } from "./handler";
-import type { WebSocketContextType, WebSocketNotification, WebSocketProviderProps, WebSocketStatus } from "./types";
+import type {
+    WebSocketContextType,
+    WebSocketNotification,
+    WebSocketProviderProps,
+    WebSocketStatus,
+} from "./types";
+
+/**
+ * Calls a status listener, logging and skipping one that throws, as notification listeners are,
+ * so it cannot keep the others from hearing the change.
+ */
+const tellStatus = (listener: (status: WebSocketStatus) => void, status: WebSocketStatus) => {
+    try {
+        listener(status);
+    } catch (error) {
+        console.error("WebSocket status listener threw:", error);
+    }
+};
 
 /**
  * WebSocketProvider
@@ -14,9 +31,10 @@ import type { WebSocketContextType, WebSocketNotification, WebSocketProviderProp
  *
  * What this provider does:
  * - Fetches `/api/websockets_config` once on mount to get the connection URL, channel id,
- *   and session uid. Socket.IO handles reconnection internally — the config is not re-fetched.
+ *   and session uid. Socket.IO handles reconnection internally — the config is not re-fetched,
+ *   and the effect that does it runs once (`changeStatus`, its only dependency, is stable).
  * - Opens a `WebSocketHandler` instance that connects and joins the per-user channel.
- * - Exposes `subscribe`, `lastMessage`, and `status` via `WebSocketContext`.
+ * - Exposes `subscribe`, `subscribeStatus`, `lastMessage`, and `status` via `WebSocketContext`.
  *
  * Why the pending buffer exists (`pendingRef`):
  * - The handler is created asynchronously (after the config fetch resolves).
@@ -40,8 +58,10 @@ import type { WebSocketContextType, WebSocketNotification, WebSocketProviderProp
  * Context value (WebSocketContextType):
  * @returns {object}
  *  - `subscribe(fn)`: register a listener; returns an unsubscribe function.
+ *  - `subscribeStatus(fn)`: hear the current status at once, then every status the socket
+ *    reports, repeats included; returns an unsubscribe function.
  *  - `lastMessage`: the most recently received notification (or null).
- *  - `status`: current connection status ("connecting" | "connected" | "error").
+ *  - `status`: current connection status ("idle" | "connecting" | "connected" | "error").
  */
 export const WebSocketProvider = ({ children }: WebSocketProviderProps) => {
     const { api } = useAxios();
@@ -51,13 +71,30 @@ export const WebSocketProvider = ({ children }: WebSocketProviderProps) => {
     // making it re-run when api or showAlert change.
     const apiRef = useRef(api);
     const showAlertRef = useRef(showAlert);
-    useEffect(() => { apiRef.current = api; });
-    useEffect(() => { showAlertRef.current = showAlert; });
+    useEffect(() => {
+        apiRef.current = api;
+    });
+    useEffect(() => {
+        showAlertRef.current = showAlert;
+    });
 
     const handlerRef = useRef<WebSocketHandler | null>(null);
     const unsubscribeProviderRef = useRef<(() => void) | null>(null);
     const [lastMessage, setLastMessage] = useState<WebSocketNotification | null>(null);
     const [status, setStatus] = useState<WebSocketStatus>("idle");
+    const statusListenersRef = useRef(new Set<(status: WebSocketStatus) => void>());
+    const currentStatusRef = useRef<WebSocketStatus>("idle");
+
+    /**
+     * Sets `status` and tells the status listeners, so both see the same sequence. The current
+     * status is also kept in a ref, so a new listener is told it at once rather than from React
+     * state, which lags a change until the next render.
+     */
+    const changeStatus = useCallback((next: WebSocketStatus) => {
+        currentStatusRef.current = next;
+        setStatus(next);
+        statusListenersRef.current.forEach((listener) => tellStatus(listener, next));
+    }, []);
 
     const pendingRef = useRef(new Map<(m: WebSocketNotification) => void, (() => void) | null>());
 
@@ -69,14 +106,16 @@ export const WebSocketProvider = ({ children }: WebSocketProviderProps) => {
             .then((config) => {
                 if (cancelled) return;
 
-                setStatus("connecting");
+                changeStatus("connecting");
                 const handler = new WebSocketHandler({
                     ...config,
-                    onStatusChange: (s) => setStatus(s),
+                    onStatusChange: changeStatus,
                 });
                 handlerRef.current = handler;
 
-                unsubscribeProviderRef.current = handler.listen((message) => setLastMessage(message));
+                unsubscribeProviderRef.current = handler.listen((message) =>
+                    setLastMessage(message),
+                );
 
                 for (const [fn, unsub] of pending.entries()) {
                     if (!unsub) {
@@ -88,8 +127,11 @@ export const WebSocketProvider = ({ children }: WebSocketProviderProps) => {
             .catch((error) => {
                 if (cancelled) return;
                 console.error("Failed to initialize WebSocket connection:", error);
-                setStatus("error");
-                showAlertRef.current({ message: "Real-time notifications are unavailable. Please refresh the page.", severity: "error" });
+                changeStatus("error");
+                showAlertRef.current({
+                    message: "Real-time notifications are unavailable. Please refresh the page.",
+                    severity: "error",
+                });
             });
 
         return () => {
@@ -100,7 +142,7 @@ export const WebSocketProvider = ({ children }: WebSocketProviderProps) => {
             handlerRef.current = null;
             pending.clear();
         };
-    }, []); // mount-only — Socket.IO handles reconnection; no re-init needed when api changes
+    }, [changeStatus]);
 
     const subscribe = useCallback((fn: (m: WebSocketNotification) => void) => {
         if (handlerRef.current) {
@@ -116,9 +158,17 @@ export const WebSocketProvider = ({ children }: WebSocketProviderProps) => {
         };
     }, []);
 
+    const subscribeStatus = useCallback((listener: (status: WebSocketStatus) => void) => {
+        statusListenersRef.current.add(listener);
+        tellStatus(listener, currentStatusRef.current);
+        return () => {
+            statusListenersRef.current.delete(listener);
+        };
+    }, []);
+
     const value: WebSocketContextType = useMemo(
-        () => ({ subscribe, lastMessage, status }),
-        [subscribe, lastMessage, status]
+        () => ({ subscribe, subscribeStatus, lastMessage, status }),
+        [subscribe, subscribeStatus, lastMessage, status],
     );
 
     return <WebSocketContext.Provider value={value}>{children}</WebSocketContext.Provider>;

package/src/contexts/webSocketContext/types.ts

@@ -1,11 +1,5 @@
 import type { ReactNode } from "react";
 
-export type WebsocketsConfig = {
-    appConnectionURL: string;
-    appChannelID: string;
-    everyskUID: string;
-};
-
 export type WebSocketStatus = "idle" | "connecting" | "connected" | "error";
 
 export type AppNotificationPayload = {
@@ -38,6 +32,13 @@ export type AppNotification = WebSocketNotification & {
 
 export type WebSocketContextType = {
     subscribe: (listener: (msg: WebSocketNotification) => void) => () => void;
+    /**
+     * Calls `listener` with the current status at once, then on every status the socket reports,
+     * repeats included; returns the unsubscribe. For code that waits on the socket outside React,
+     * where `status` cannot be watched: a reconnect is when it must catch up on what was
+     * published in between, which the server does not replay.
+     */
+    subscribeStatus: (listener: (status: WebSocketStatus) => void) => () => void;
     lastMessage: WebSocketNotification | null;
     status: WebSocketStatus;
 };

package/src/file/index.ts

@@ -11,3 +11,5 @@ export * from "@/types/file";
 export * from "@/hooks/file/useFetchFile";
 export * from "@/hooks/file/useFetchFiles";
 export * from "@/hooks/file/useFileMutations";
+export * from "@/lib/file";
+export type { FileDataProps } from "@/hooks/file/fileData";