@everysk/apps-sdk 0.1.0-beta.0

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

@@ -0,0 +1,38 @@
+import Backdrop from "@mui/material/Backdrop";
+import Box from "@mui/material/Box";
+import CircularProgress from "@mui/material/CircularProgress";
+import Typography from "@mui/material/Typography";
+
+interface GlobalLoadingProps {
+    isLoading: boolean;
+    backdrop?: boolean;
+    message?: string;
+}
+
+export const GlobalLoading = ({ isLoading, backdrop = true, message }: GlobalLoadingProps) => {
+    if (!isLoading) return null;
+
+    const content = (
+        <Box sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 2 }}>
+            <CircularProgress color="primary" />
+            {message && <Typography color="text.secondary">{message}</Typography>}
+        </Box>
+    );
+
+    if (!backdrop) {
+        return (
+            <Box sx={{ display: "flex", justifyContent: "center", alignItems: "center", height: "100%" }}>
+                {content}
+            </Box>
+        );
+    }
+
+    return (
+        <Backdrop
+            open
+            sx={{ zIndex: (theme) => theme.zIndex.modal + 1, backgroundColor: "rgba(0, 0, 0, 0.3)" }}
+        >
+            {content}
+        </Backdrop>
+    );
+}

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

@@ -0,0 +1,14 @@
+import clsx from "clsx";
+import type { PropsWithChildren, ReactNode } from "react";
+
+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)}>
+                {children}
+            </div>
+            {footer}
+        </div>
+    );
+};

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

@@ -0,0 +1,44 @@
+import type { PropsWithChildren } from 'react';
+
+import AppBar from '@mui/material/AppBar';
+import { useTheme, type Theme } from '@mui/material/styles';
+import MuiToolbar from '@mui/material/Toolbar';
+
+import clsx from 'clsx';
+
+import { EveryskIcon } from '@/components/ui/EveryskIcon';
+
+import type { AnyRecord } from '@/types/anyRecord';
+
+export const Toolbar = ({ children, className }: PropsWithChildren<{ className?: string }>) => {
+    const theme: Theme = useTheme();
+
+    const styles: AnyRecord = {
+        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
+        }
+    };
+
+    return (
+        <AppBar position='relative' {...styles?.[theme.palette.mode]}>
+            <MuiToolbar >
+                <div className={clsx("flex items-center gap-4", className)}>
+                    <EveryskIcon />
+                    {children}
+                </div>
+            </MuiToolbar>
+        </AppBar>
+    );
+}

package/src/contexts/agGridLicenseContext/provider.tsx

@@ -0,0 +1,63 @@
+import { type PropsWithChildren } from "react";
+
+import { LicenseManager } from "ag-grid-enterprise";
+
+/**
+ * setAgGridLicense
+ *
+ * Registers the AG Grid Enterprise license. A no-op when the key is missing or empty, so an
+ * app that has not configured one degrades to the watermark instead of throwing.
+ *
+ * The key is a **parameter**, not something this package reads from the environment. The
+ * template read `import.meta.env.VITE_AG_GRID_LICENSE_KEY` at module scope, which works
+ * inside an app and silently breaks inside a published package: Vite replaces
+ * `import.meta.env.VITE_*` with a literal at the build of whoever compiles the file, so the
+ * value would freeze to whatever the SDK's own CI had — nothing — and the consuming app's
+ * environment would never reach it. No build error, no runtime error, just the watermark.
+ *
+ * The app keeps ownership of its own environment:
+ *
+ * ```ts
+ * // src/main.tsx
+ * setAgGridLicense(import.meta.env.VITE_AG_GRID_LICENSE_KEY);
+ * ```
+ *
+ * @param {string} [licenseKey] - The license key, typically from the app's build environment.
+ */
+export const setAgGridLicense = (licenseKey?: string): void => {
+    if (typeof licenseKey === "string" && licenseKey) {
+        LicenseManager.setLicenseKey(licenseKey);
+    }
+};
+
+export type AgGridLicenseProviderProps = PropsWithChildren<{
+    /** The license key. Omitted or empty, the provider only renders its children. */
+    licenseKey?: string;
+}>;
+
+/**
+ * AgGridLicenseProvider
+ *
+ * Provider form of `setAgGridLicense`, for apps that would rather configure the license in
+ * the component tree than at bootstrap. It holds no context — it registers the key and
+ * renders its children.
+ *
+ * The registration happens in the render body rather than in an effect on purpose: AG Grid
+ * reads the license when a grid first renders, and an effect runs *after* that commit, so a
+ * grid mounted in the same commit would flash the watermark. React renders a parent's body
+ * before its children, which is exactly the ordering needed here. `setLicenseKey` is an
+ * idempotent setter on a module global, so StrictMode's double render is harmless.
+ *
+ * ```tsx
+ * <EveryskApp>
+ *   <AgGridLicenseProvider licenseKey={import.meta.env.VITE_AG_GRID_LICENSE_KEY}>
+ *     <Routes />
+ *   </AgGridLicenseProvider>
+ * </EveryskApp>
+ * ```
+ */
+export const AgGridLicenseProvider = ({ children, licenseKey }: AgGridLicenseProviderProps) => {
+    setAgGridLicense(licenseKey);
+
+    return <>{children}</>;
+};

package/src/contexts/appAlertContext/index.tsx

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

package/src/contexts/appAlertContext/provider.tsx

@@ -0,0 +1,92 @@
+import { useCallback, useMemo, useState, type PropsWithChildren } from "react";
+import Alert from "@mui/material/Alert";
+import Snackbar, { type SnackbarCloseReason } from "@mui/material/Snackbar";
+
+import { AppAlertContext } from ".";
+import type { AppAlertContextType, AppAlertState, ShowAlertOptions } from "./types";
+
+/**
+ * AppAlertProvider
+ *
+ * React context provider responsible for exposing a global application alert API and rendering
+ * a Material UI `Snackbar` + `Alert` pair anchored to the viewport.
+ *
+ * What this provider does:
+ * - Maintains an internal `AppAlertState` that controls:
+ *   - visibility (`open`)
+ *   - displayed text (`message`)
+ *   - alert tone (`severity`)
+ *   - auto-dismiss timing (`autoHideDuration`)
+ *   - screen position (`anchorOrigin`)
+ * - Exposes an imperative API via context:
+ *   - `showAlert(options)` to open/update the alert
+ *   - `hideAlert()` to close the alert
+ * - Renders the `Snackbar`/`Alert` components once (at the provider level), so any descendant can
+ *   trigger alerts without needing to manage UI state locally.
+ *
+ * Behavior:
+ * - `showAlert(options)` performs a shallow merge of the provided options into the current state
+ *   and forces `open: true`.
+ * - `hideAlert()` sets `open: false` (preserving the remaining state).
+ * - Snackbar `onClose` ignores the `"clickaway"` reason to prevent accidental dismissals when the user
+ *   clicks outside the toast.
+ *
+ * Performance / stability:
+ * - `showAlert` and `hideAlert` should be stable (e.g., created with `useCallback`) so the context value
+ *   does not change on every render, avoiding unnecessary re-renders in consumers.
+ *
+ * Usage:
+ * ```ts
+ * <AppAlertProvider>
+ *   <App />
+ * </AppAlertProvider>
+ * ```
+ */
+
+export const AppAlertProvider = ({ children }: PropsWithChildren) => {
+    const [state, setState] = useState<AppAlertState>({
+        open: false,
+        message: "",
+        severity: "info",
+        autoHideDuration: 4000,
+        anchorOrigin: { vertical: "bottom", horizontal: "right" },
+    });
+
+    const hideAlert = useCallback(() => {
+        setState((prev) => ({ ...prev, open: false }));
+    }, []);
+
+    const showAlert = useCallback((options: ShowAlertOptions) => {
+        setState((prev) => ({
+            ...prev,
+            ...options,
+            open: true,
+        }));
+    }, []);
+
+    const value: AppAlertContextType = useMemo(
+        () => ({ showAlert, hideAlert }),
+        [showAlert, hideAlert]
+    );
+
+    return (
+        <AppAlertContext.Provider value={value}>
+            {children}
+
+            <Snackbar
+                open={state.open}
+                message={state.message}
+                autoHideDuration={state.autoHideDuration}
+                anchorOrigin={state.anchorOrigin}
+                onClose={(_, reason: SnackbarCloseReason) => {
+                    if (reason === "clickaway") return;
+                    hideAlert();
+                }}
+            >
+                <Alert onClose={hideAlert} severity={state.severity} variant="filled" elevation={6}>
+                    {state.message}
+                </Alert>
+            </Snackbar>
+        </AppAlertContext.Provider>
+    );
+};

package/src/contexts/appAlertContext/types.ts

@@ -0,0 +1,17 @@
+import type { AlertColor } from "@mui/material/Alert";
+import type { SnackbarProps } from "@mui/material/Snackbar";
+
+export type AppAlertState = Omit<SnackbarProps, "open" | "onClose" | "message"> & {
+    open: boolean;
+    message: string;
+    severity: AlertColor;
+};
+
+export type ShowAlertOptions = Partial<Omit<AppAlertState, "open">> & {
+    message: string;
+};
+
+export type AppAlertContextType = {
+  showAlert: (options: ShowAlertOptions) => void;
+  hideAlert: () => void;
+};

package/src/contexts/appAlertContext/useAppAlert.ts

@@ -0,0 +1,39 @@
+import { useContext } from "react";
+import { AppAlertContext } from ".";
+
+/**
+ * useAppAlert
+ *
+ * Convenience hook that reads the alert API from `AppAlertContext`.
+ *
+ * Behavior:
+ * - Returns the functions exposed by `<AppAlertProvider>`, typically:
+ *   - `showAlert(options)` to display an alert
+ *   - `hideAlert()` to close the current alert
+ *
+ * Error handling:
+ * - Throws a descriptive error if called outside of an `<AppAlertProvider>` scope, to fail fast
+ *   and prevent silent no-op alert calls.
+ *
+ * Usage:
+ * ```ts
+ * const { showAlert } = useAppAlert();
+ *
+ * showAlert({
+ *   message: "Saved successfully.",
+ *   severity: "success",
+ *   autoHideDuration: 3000,
+ * });
+ * ```
+ *
+ * @throws {Error}
+ *  Throws if the hook is used outside of `<AppAlertProvider>`.
+ */
+
+export const useAppAlert = () => {
+    const ctx = useContext(AppAlertContext);
+    if (!ctx) {
+        throw new Error("useAppAlert must be used within <AppAlertProvider>.");
+    }
+    return ctx;
+};

package/src/contexts/appConfigContext/index.tsx

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

package/src/contexts/appConfigContext/provider.tsx

@@ -0,0 +1,67 @@
+import { useMemo } from "react";
+
+import { AppConfigContext } from ".";
+import type { AppConfigContextType, AppConfigProviderProps } from "./types";
+
+/**
+ * AppConfigProvider
+ *
+ * React context provider responsible for exposing the application's runtime configuration
+ * (`AppConfigContextType`) to the component tree.
+ *
+ * Configuration sources, in order of precedence:
+ *
+ * 1. The `appId` / `appEnvironmentVar` props.
+ *    Explicit injection, for tests and for hosts that resolve configuration themselves rather
+ *    than through the page globals. A prop wins over the corresponding global; passing
+ *    `appId={null}` forces "no app id" instead of falling through to `window.APP_ID`.
+ *
+ * 2. `window.APP_ID` and `window.APP_CONFIG`.
+ *    Injected into the page by the platform (from the app's `config.json` `env_vars`) before
+ *    the bundle executes.
+ *
+ * In dev there is no platform to inject them, so the app's dev server serves the `env_vars` at
+ * `/app-config.json` and the app merges them into `window.APP_CONFIG` during bootstrap, before
+ * React mounts. That merge is shallow and belongs to the app, not to this provider: nested
+ * objects are replaced whole, not deep-merged.
+ *
+ * Lifecycle notes:
+ * - This provider performs no network request and does not update its value after mount.
+ * - Because configuration is resolved before `createRoot(...).render(...)`, the tree receives a
+ *   consistent configuration from the first render.
+ *
+ * Example:
+ * ```tsx
+ * <AppConfigProvider>
+ *   <App />
+ * </AppConfigProvider>
+ *
+ * // In a test, with no page globals:
+ * <AppConfigProvider appId="app_42" appEnvironmentVar={{ API_URL: "/api" }}>
+ *   <ComponentUnderTest />
+ * </AppConfigProvider>
+ *
+ * // Consumer hook usage
+ * const { appId, appEnvironmentVar } = useAppConfig();
+ * ```
+ */
+export const AppConfigProvider = ({
+    children,
+    appId,
+    appEnvironmentVar,
+}: AppConfigProviderProps) => {
+    const value: AppConfigContextType = useMemo(() => {
+        const globalConfig = (globalThis.window?.APP_CONFIG ?? {}) as Record<string, unknown>;
+
+        return {
+            appId: appId !== undefined ? appId : (globalThis.window?.APP_ID ?? null),
+            appEnvironmentVar: appEnvironmentVar ?? globalConfig,
+        };
+    }, [appId, appEnvironmentVar]);
+
+    return (
+        <AppConfigContext.Provider value={value}>
+            {children}
+        </AppConfigContext.Provider>
+    );
+};

package/src/contexts/appConfigContext/types.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type { AnyRecord } from "@/types/anyRecord";
+
+/**
+ * The platform injects these into the host page before the bundle runs. Both are optional:
+ * this augmentation reaches every consumer of the package, and declaring them as required
+ * would be a lie in dev, where nothing injects them — `AppConfigProvider` itself has always
+ * read `window.APP_ID ?? null`.
+ */
+declare global {
+    interface Window {
+        APP_ID?: string;
+        APP_CONFIG?: { [key: string]: unknown };
+    }
+}
+
+export type AppConfigContextType = {
+    appId: string | null;
+    appEnvironmentVar: AnyRecord;
+};
+
+export type AppConfigProviderProps = {
+    children?: ReactNode;
+    /** Overrides `window.APP_ID`. Pass `null` to force "no app id". */
+    appId?: string | null;
+    /** Overrides `window.APP_CONFIG` wholesale (not merged into it). */
+    appEnvironmentVar?: AnyRecord;
+};

package/src/contexts/appConfigContext/useAppConfig.ts

@@ -0,0 +1,30 @@
+import { useContext } from "react";
+
+import { AppConfigContext } from ".";
+
+/**
+ * useAppConfig
+ *
+ * Convenience hook that reads the current application configuration from `AppConfigContext`.
+ *
+ * Behavior:
+ * - Returns the `AppConfigContextType` value provided by `<AppConfigProvider>`.
+ * - Throws a descriptive error if called outside of an `<AppConfigProvider>` scope, to fail fast and
+ *   avoid undefined configuration usage throughout the app.
+ *
+ * Usage:
+ * ```ts
+ * const { appId, appEnvironmentVar } = useAppConfig();
+ * ```
+ *
+ * @throws {Error}
+ *  Throws if the hook is used outside of `<AppConfigProvider>`.
+ */
+
+export const useAppConfig = () => {
+    const context = useContext(AppConfigContext);
+    if (!context) {
+        throw new Error("useAppConfig must be used within <AppConfigProvider>.");
+    }
+    return context;
+};

package/src/contexts/webSocketContext/constants.ts

@@ -0,0 +1,3 @@
+export const NOTIFICATION_EVENT = "notification";
+export const JOIN_EVENT = "join";
+export const APP_NOTIFICATION_EVENT_TYPE = "USER_APP_NOTIFICATION";

package/src/contexts/webSocketContext/handler.ts

@@ -0,0 +1,108 @@
+import { io, type Socket } from "socket.io-client";
+
+import type { WebSocketNotification, WebSocketStatus, WebsocketsConfig } from "./types";
+
+function isWebSocketNotification(value: unknown): value is WebSocketNotification {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        typeof (value as Record<string, unknown>)["event_type"] === "string"
+    );
+}
+import { JOIN_EVENT, NOTIFICATION_EVENT } from "./constants";
+
+type StatusListener = (status: Exclude<WebSocketStatus, "idle">) => void;
+
+type WebSocketHandlerConfig = WebsocketsConfig & {
+    onStatusChange?: StatusListener;
+};
+
+/**
+ * WebSocketHandler
+ *
+ * Low-level Socket.IO wrapper with a pub/sub layer.
+ *
+ * - Connects to the notification server.
+ * - Joins the per-user channel.
+ * - Forwards notifications to registered listeners.
+ *
+ * API:
+ * - `listen(callback)`: register a notification listener; returns an unsubscribe function.
+ * - `close()`: disconnect the socket and clear all listeners.
+ */
+export class WebSocketHandler {
+    private _socket: Socket;
+    private _everyskUID: string;
+    private _listeners: Set<(msg: WebSocketNotification) => void> = new Set();
+
+    constructor({ appConnectionURL, appChannelID, everyskUID, onStatusChange }: WebSocketHandlerConfig) {
+        this._everyskUID = everyskUID;
+
+        this._socket = io(appConnectionURL, {
+            auth: { appChannelID, everyskUID },
+            transports: ["websocket"],
+        });
+
+        this._socket.on("connect", () => {
+            this._socket.emit(JOIN_EVENT, appChannelID);
+            onStatusChange?.("connected");
+        });
+
+        this._socket.on("connect_error", (error) => {
+            console.error("Socket.IO connection error:", error);
+            onStatusChange?.("error");
+        });
+
+        this._socket.on("disconnect", (reason: string) => {
+            console.error("Socket.IO disconnected:", reason);
+            onStatusChange?.(reason === "io server disconnect" ? "error" : "connecting");
+        });
+
+        this._socket.on(NOTIFICATION_EVENT, (msg: unknown) => {
+            if (!isWebSocketNotification(msg)) return;
+            if (this._isEcho(msg)) return;
+            this._listeners.forEach((callback) => {
+                try {
+                    callback(msg);
+                } catch (error) {
+                    console.error("Socket.IO notification listener threw:", error);
+                }
+            });
+        });
+    }
+
+    private _isEcho(msg: WebSocketNotification): boolean {
+        // Echo-cancellation is disabled by default.
+        // Set ECHO_UID_FIELD to the message field that carries the originating uid
+        // once the server team confirms the field name.
+        const ECHO_UID_FIELD: string | null = null;
+        if (!ECHO_UID_FIELD) return false;
+        const originating = (msg as Record<string, unknown>)[ECHO_UID_FIELD];
+        return originating === this._everyskUID;
+    }
+
+    /**
+     * listen
+     *
+     * Registers a listener that receives every incoming notification.
+     *
+     * @param {(msg: WebSocketNotification) => void} callback - Invoked for each notification.
+     * @returns {() => void} Unsubscribe function.
+     */
+    listen(callback: (msg: WebSocketNotification) => void): () => void {
+        this._listeners.add(callback);
+        return () => this._listeners.delete(callback);
+    }
+
+    /**
+     * close
+     *
+     * Clears all listeners and disconnects the socket.
+     * After calling this, the handler should be considered unusable.
+     */
+    close(): void {
+        this._listeners.clear();
+        this._socket.removeAllListeners();
+        this._socket.disconnect();
+    }
+}

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

@@ -0,0 +1,36 @@
+import { useWebSocketSubscription } from "../useWebSocketSubscription";
+import { APP_NOTIFICATION_EVENT_TYPE } from "../../constants";
+import type { AppNotification, WebSocketNotification } from "../../types";
+
+function isAppNotification(msg: WebSocketNotification): msg is AppNotification {
+    return (
+        msg.event_type === APP_NOTIFICATION_EVENT_TYPE &&
+        typeof msg["user_app_id"] === "string" &&
+        typeof msg["payload"] === "object" &&
+        msg["payload"] !== null
+    );
+}
+
+/**
+ * useAppNotificationSubscription
+ *
+ * Convenience wrapper around `useWebSocketSubscription` that only invokes the handler
+ * for `event_type === "USER_APP_NOTIFICATION"` messages. All other WebSocket events are ignored.
+ *
+ * @param {(msg: AppNotification) => void} handler
+ *  Callback invoked for each app-targeted notification.
+ *
+ * Example:
+ * ```ts
+ * useAppNotificationSubscription((msg) => {
+ *   queryClient.invalidateQueries({ queryKey: ["portfolios"] });
+ * });
+ * ```
+ */
+export const useAppNotificationSubscription = (handler: (msg: AppNotification) => void) => {
+    useWebSocketSubscription((msg: WebSocketNotification) => {
+        if (isAppNotification(msg)) {
+            handler(msg);
+        }
+    });
+};

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

@@ -0,0 +1,18 @@
+import { useContext } from "react";
+
+import { WebSocketContext } from "../..";
+
+/**
+ * useWebSocket
+ *
+ * Convenience hook that reads the WebSocket API from `WebSocketContext`.
+ *
+ * Returns: `{ subscribe, lastMessage, status }` (see `WebSocketContextType`).
+ *
+ * @throws {Error} If used outside of `<WebSocketProvider>`.
+ */
+export const useWebSocket = () => {
+    const context = useContext(WebSocketContext);
+    if (!context) throw new Error("useWebSocket must be used within <WebSocketProvider>.");
+    return context;
+};

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

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from "react";
+
+import { useWebSocket } from "../useWebSocket";
+import type { WebSocketNotification } from "../../types";
+
+/**
+ * useWebSocketSubscription
+ *
+ * High-level helper hook that subscribes to all WebSocket notifications on mount
+ * and unsubscribes on unmount.
+ *
+ * Why this exists:
+ * - Enforces the correct subscription pattern (`useEffect` + cleanup).
+ * - Prevents accidental duplicate subscriptions from re-renders.
+ * - Uses a ref-backed handler so the subscription is not recreated when the callback
+ *   identity changes — the latest handler is always called without re-subscribing.
+ *
+ * Filtering (e.g. by `msg.event_type`) is intentionally left to the consumer.
+ * See `useAppNotificationSubscription` for a typed convenience wrapper.
+ *
+ * @param {(msg: WebSocketNotification) => void} handler
+ *  Callback invoked for every received notification.
+ *
+ * Example:
+ * ```ts
+ * useWebSocketSubscription((msg) => {
+ *   if (msg.event_type === "WORKFLOW_EXECUTION_COMPLETED") {
+ *     queryClient.invalidateQueries({ queryKey: ["workflows"] });
+ *   }
+ * });
+ * ```
+ */
+export const useWebSocketSubscription = (handler: (msg: WebSocketNotification) => void) => {
+    const { subscribe } = useWebSocket();
+    const handlerRef = useRef(handler);
+
+    useEffect(() => {
+        handlerRef.current = handler;
+    });
+
+    useEffect(() => {
+        const unsubscribe = subscribe((msg: WebSocketNotification) => handlerRef.current(msg));
+        return unsubscribe;
+    }, [subscribe]);
+};

package/src/contexts/webSocketContext/index.tsx

@@ -0,0 +1,5 @@
+import { createContext } from "react";
+
+import type { WebSocketContextType } from "./types";
+
+export const WebSocketContext = createContext<WebSocketContextType | null>(null);