@everysk/apps-sdk 0.2.0 → 0.3.0-beta-20261019175049

package/src/test/msw/store.ts

@@ -0,0 +1,182 @@
+import { DEV_PROFILE } from "@/api/profile";
+import type { WebsocketsConfig } from "@/api/websocketsConfig";
+import type { Datastore } from "@/types/datastore";
+import type { EveryskFile } from "@/types/file";
+import type { Portfolio } from "@/types/portfolio";
+import type { Profile } from "@/types/profile";
+import type { Workflow, WorkflowExecution, WorkerExecution } from "@/types/workflow";
+import type { Workspace } from "@/types/workspace";
+
+/** What the fake API holds. A test seeds it and reads it back after a write. */
+export type FakeApiStore = {
+    datastores: Datastore[];
+    files: EveryskFile[];
+    portfolios: Portfolio[];
+    workflows: Workflow[];
+    workflowExecutions: WorkflowExecution[];
+    workerExecutions: WorkerExecution[];
+    workspaces: Workspace[];
+    profile: Profile;
+    websocketsConfig: WebsocketsConfig;
+};
+
+/** What a test seeds: partial records, each completed with what its type requires. */
+export type FakeApiSeed = {
+    datastores?: Partial<Datastore>[];
+    files?: Partial<EveryskFile>[];
+    portfolios?: Partial<Portfolio>[];
+    workflows?: Partial<Workflow>[];
+    workflowExecutions?: Partial<WorkflowExecution>[];
+    workerExecutions?: Partial<WorkerExecution>[];
+    workspaces?: (Partial<Workspace> & { name: string })[];
+    profile?: Profile;
+    websocketsConfig?: WebsocketsConfig;
+};
+
+export const newId = (prefix: string) =>
+    `${prefix}_${Array.from({ length: 25 }, () => Math.floor(Math.random() * 36).toString(36)).join("")}`;
+
+/** The hex of a version-4 UUID, as a file's stored `url` is (`RE_FILE_URL`). */
+export const newFileHash = () => crypto.randomUUID().replaceAll("-", "");
+
+export const nowSeconds = () => Math.floor(Date.now() / 1000);
+
+/**
+ * The fields each type requires and a test left out. `workspace` is `main`, as the API's create
+ * defaults it; the rest are blank, empty or zero rather than invented values.
+ */
+export const complete = {
+    datastore: (d: Partial<Datastore>): Datastore => ({
+        name: "",
+        workspace: "main",
+        data: [],
+        date_time: "",
+        ...d,
+        id: d.id ?? newId("dats"),
+    }),
+    file: (f: Partial<EveryskFile>): EveryskFile => {
+        const hash = f.hash ?? newFileHash();
+        return {
+            name: "",
+            workspace: "main",
+            content_type: "",
+            version: "",
+            link_uid: null,
+            data: null,
+            ...f,
+            hash,
+            url: f.url ?? `/file/${hash}`,
+            id: f.id ?? newId("file"),
+        };
+    },
+    portfolio: (p: Partial<Portfolio>): Portfolio => ({
+        workspace: "main",
+        base_currency: "",
+        securities: [],
+        date: "",
+        ...p,
+        id: p.id ?? newId("port"),
+    }),
+    workflow: (w: Partial<Workflow>): Workflow => ({
+        name: "",
+        workspace: "main",
+        description: "",
+        tags: [],
+        status: "",
+        created: 0,
+        updated: 0,
+        version: "",
+        trigger_enabled: false,
+        trigger_type: "",
+        trigger_config: {},
+        starter_worker_id: "",
+        ender_worker_id: "",
+        ...w,
+        id: w.id ?? newId("wrkf"),
+    }),
+    workflowExecution: (e: Partial<WorkflowExecution>): WorkflowExecution => ({
+        workflow_id: "",
+        workflow_name: "",
+        workspace: "main",
+        status: "",
+        run_status: "",
+        duration: 0,
+        real_execution_time: 0,
+        total_execution_time: 0,
+        started: 0,
+        created: 0,
+        updated: 0,
+        trigger: "",
+        started_worker_id: "",
+        ender_worker_id: "",
+        ender_worker_execution_id: "",
+        resume: null,
+        version: "",
+        ...e,
+        id: e.id ?? newId("wfex"),
+    }),
+    workerExecution: (e: Partial<WorkerExecution>): WorkerExecution =>
+        ({
+            status: "",
+            worker_id: "",
+            worker_name: "",
+            worker_type: "",
+            workflow_execution_id: "",
+            workflow_id: "",
+            workflow_name: "",
+            trigger: "",
+            created: 0,
+            updated: 0,
+            started: 0,
+            duration: 0,
+            cpu_time: 0,
+            result: {},
+            input_params: {},
+            ...e,
+            id: e.id ?? newId("wkex"),
+        }) as WorkerExecution,
+    workspace: (w: Partial<Workspace> & { name: string }): Workspace => ({
+        group: null,
+        description: "",
+        version: "",
+        created: 0,
+        updated: 0,
+        ...w,
+    }),
+};
+
+const EMPTY_WEBSOCKETS_CONFIG: WebsocketsConfig = {
+    appConnectionURL: "",
+    appChannelID: "",
+    everyskUID: "",
+};
+
+/** An empty store: no records, the SDK's dev profile, a blank websocket config. */
+export const emptyStore = (): FakeApiStore => ({
+    datastores: [],
+    files: [],
+    portfolios: [],
+    workflows: [],
+    workflowExecutions: [],
+    workerExecutions: [],
+    workspaces: [],
+    profile: structuredClone(DEV_PROFILE),
+    websocketsConfig: { ...EMPTY_WEBSOCKETS_CONFIG },
+});
+
+/** The store a seed describes: each record completed, everything not seeded empty. */
+export const storeFrom = (seed: FakeApiSeed): FakeApiStore => {
+    const data = structuredClone(seed);
+    const empty = emptyStore();
+    return {
+        datastores: (data.datastores ?? []).map(complete.datastore),
+        files: (data.files ?? []).map(complete.file),
+        portfolios: (data.portfolios ?? []).map(complete.portfolio),
+        workflows: (data.workflows ?? []).map(complete.workflow),
+        workflowExecutions: (data.workflowExecutions ?? []).map(complete.workflowExecution),
+        workerExecutions: (data.workerExecutions ?? []).map(complete.workerExecution),
+        workspaces: (data.workspaces ?? []).map(complete.workspace),
+        profile: data.profile ?? empty.profile,
+        websocketsConfig: data.websocketsConfig ?? empty.websocketsConfig,
+    };
+};

package/src/test/renderWithProviders.tsx

@@ -9,7 +9,7 @@ import {
 import userEvent from "@testing-library/user-event";
 import { QueryClient } from "@tanstack/react-query";
 
-import { EveryskApp, type ProviderComponent } from "@/EveryskApp";
+import { EveryskApp, type ProviderEntry } from "@/EveryskApp";
 import type { AnyRecord } from "@/types/anyRecord";
 
 /**
@@ -39,14 +39,19 @@ export function createTestQueryClient(): QueryClient {
 type ProviderOptions = {
     queryClient?: QueryClient;
     /** Extra providers, mounted inside the core tree and around the subject. */
-    providers?: ProviderComponent[];
+    providers?: ProviderEntry[];
     /** Injected instead of `window.APP_ID`, so a test needs no page globals. */
     appId?: string | null;
     /** Injected instead of `window.APP_CONFIG`. */
     appEnvironmentVar?: AnyRecord;
 };
 
-const buildWrapper = ({ queryClient, providers, appId, appEnvironmentVar }: ProviderOptions & {
+const buildWrapper = ({
+    queryClient,
+    providers,
+    appId,
+    appEnvironmentVar,
+}: ProviderOptions & {
     queryClient: QueryClient;
 }) =>
     function Wrapper({ children }: { children?: React.ReactNode }) {

package/src/test/setup.ts

@@ -5,31 +5,31 @@ import "@testing-library/jest-dom/vitest";
 
 // Unmount React trees and clear the jsdom document between tests so they stay isolated.
 afterEach(() => {
-  cleanup();
+    cleanup();
 });
 
 // jsdom does not implement matchMedia; MUI's `useMediaQuery` needs it. The theme no longer
 // reads it — it is pinned to the brand dark theme — but responsive components still do.
 if (!window.matchMedia) {
-  window.matchMedia = vi.fn().mockImplementation((query: string) => ({
-    matches: false,
-    media: query,
-    onchange: null,
-    addListener: vi.fn(),
-    removeListener: vi.fn(),
-    addEventListener: vi.fn(),
-    removeEventListener: vi.fn(),
-    dispatchEvent: vi.fn(),
-  }));
+    window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+    }));
 }
 
 // jsdom does not implement ResizeObserver; several MUI components observe their container.
 if (!globalThis.ResizeObserver) {
-  globalThis.ResizeObserver = class {
-    observe(): void {}
-    unobserve(): void {}
-    disconnect(): void {}
-  };
+    globalThis.ResizeObserver = class {
+        observe(): void {}
+        unobserve(): void {}
+        disconnect(): void {}
+    };
 }
 
 // The template stubbed `BroadcastChannel` here, which jsdom does not implement. Nothing in

package/src/theme/index.ts

@@ -12,4 +12,4 @@ export { EveryskDarkTheme } from "./themes/EveryskDark";
 export { DefaultLightTheme } from "./themes/DefaultLight";
 export { DefaultDarkTheme } from "./themes/DefaultDark";
 export { MidnightEmberTheme } from "./themes/MidnightEmber";
-export { components } from "./overrides";
+export { componentOverrides } from "./overrides";

package/src/theme/overrides/index.ts

@@ -1,6 +1,6 @@
 import type { Components, Theme } from "@mui/material/styles";
 
-import type { } from '@mui/x-date-pickers/themeAugmentation';
+import type {} from "@mui/x-date-pickers/themeAugmentation";
 
 import { MuiCssBaseline } from "./muiCssBaseline";
 import { MuiDatePicker } from "./muiDatePicker";
@@ -15,9 +15,11 @@ import { MuiButton } from "./muiButton";
 
 /**
  * Shared MUI component overrides applied by every theme (light, dark and branded).
- * They read `theme.palette.mode`, so the same set works for any palette.
+ * They read `theme.palette.mode`, so the same set works for any palette. Public as
+ * `componentOverrides` for an app that builds its own theme; `components` alone, at the root of
+ * the package, did not say whose components.
  */
-export const components: Components<Omit<Theme, "components">> = {
+export const componentOverrides: Components<Omit<Theme, "components">> = {
     MuiCssBaseline,
     MuiDatePicker,
     MuiTextField,

package/src/theme/overrides/muiButton.ts

@@ -1,7 +1,7 @@
-import type { Components, Theme } from '@mui/material/styles';
+import type { Components, Theme } from "@mui/material/styles";
 
-export const MuiButton: Components<Theme>['MuiButton'] = {
+export const MuiButton: Components<Theme>["MuiButton"] = {
     defaultProps: {
-        size: 'small',
+        size: "small",
     },
 };

package/src/theme/overrides/muiCssBaseline.ts

@@ -9,27 +9,26 @@ export const MuiCssBaseline = {
         },
         "*::-webkit-scrollbar-thumb": {
             borderRadius: 10,
-            backgroundColor: '#959595'
-
+            backgroundColor: "#959595",
         },
         "*::-webkit-scrollbar-thumb:hover ": {
-            backgroundColor: '#959595'
+            backgroundColor: "#959595",
         },
         "*:hover::-webkit-scrollbar-thumb": {
-            backgroundColor: '#959595'
+            backgroundColor: "#959595",
         },
 
         "*::-webkit-scrollbar-thumb:active": {
-            backgroundColor: theme.palette.primary.main
+            backgroundColor: theme.palette.primary.main,
         },
 
         "*::-moz-selection": {
-            color: (theme.palette.mode === "dark" ? colors.common.black : colors.common.white),
-            backgroundColor: theme.palette.primary.main
+            color: theme.palette.mode === "dark" ? colors.common.black : colors.common.white,
+            backgroundColor: theme.palette.primary.main,
         },
         "*::selection": {
-            color: (theme.palette.mode === "dark") ? colors.common.black : colors.common.white,
-            backgroundColor: theme.palette.primary.main
-        }
-    })
-}
+            color: theme.palette.mode === "dark" ? colors.common.black : colors.common.white,
+            backgroundColor: theme.palette.primary.main,
+        },
+    }),
+};

package/src/theme/overrides/muiDatePicker.ts

@@ -1,5 +1,5 @@
 export const MuiDatePicker = {
     defaultProps: {
-        slotProps: { textField: { size: 'small' as const } },
+        slotProps: { textField: { size: "small" as const } },
     },
-};
+};

package/src/theme/overrides/muiFormControl.ts

@@ -2,6 +2,6 @@ import type { Components, Theme } from "@mui/material/styles";
 
 export const MuiFormControl: Components<Theme>["MuiFormControl"] = {
     defaultProps: {
-        size: 'small',
+        size: "small",
     },
-};
+};

package/src/theme/overrides/muiIconButton.ts

@@ -1,7 +1,7 @@
-import type { Components, Theme } from '@mui/material/styles';
+import type { Components, Theme } from "@mui/material/styles";
 
-export const MuiIconButton: Components<Theme>['MuiIconButton'] = {
+export const MuiIconButton: Components<Theme>["MuiIconButton"] = {
     defaultProps: {
-        size: 'small',
+        size: "small",
     },
 };

package/src/theme/overrides/muiSelect.ts

@@ -2,6 +2,6 @@ import type { Components, Theme } from "@mui/material/styles";
 
 export const MuiSelect: Components<Theme>["MuiSelect"] = {
     defaultProps: {
-        size: 'small',
+        size: "small",
     },
-}
+};

package/src/theme/overrides/muiSvgIcon.ts

@@ -2,6 +2,6 @@ import type { Components, Theme } from "@mui/material/styles";
 
 export const MuiSvgIcon: Components<Theme>["MuiSvgIcon"] = {
     defaultProps: {
-        fontSize: 'small',
+        fontSize: "small",
     },
-}
+};

package/src/theme/overrides/muiTextField.ts

@@ -4,4 +4,4 @@ export const MuiTextField: Components<Theme>["MuiTextField"] = {
     defaultProps: {
         size: "small",
     },
-};
+};

package/src/theme/overrides/muiToggleButton.ts

@@ -1,7 +1,7 @@
-import type { Components, Theme } from '@mui/material/styles';
+import type { Components, Theme } from "@mui/material/styles";
 
-export const MuiToggleButton: Components<Theme>['MuiToggleButton'] = {
+export const MuiToggleButton: Components<Theme>["MuiToggleButton"] = {
     defaultProps: {
-        size: 'small',
+        size: "small",
     },
-};
+};

package/src/theme/overrides/muiToggleButtonGroup.ts

@@ -1,7 +1,7 @@
-import type { Components, Theme } from '@mui/material/styles';
+import type { Components, Theme } from "@mui/material/styles";
 
-export const MuiToggleButtonGroup: Components<Theme>['MuiToggleButtonGroup'] = {
+export const MuiToggleButtonGroup: Components<Theme>["MuiToggleButtonGroup"] = {
     defaultProps: {
-        size: 'small',
+        size: "small",
     },
-};
+};

package/src/theme/themes/DefaultDark.ts

@@ -1,6 +1,6 @@
 import { createTheme, type Theme } from "@mui/material/styles";
 
-import { components } from "@/theme/overrides";
+import { componentOverrides } from "@/theme/overrides";
 
 /**
  * Neutral dark theme. Uses MUI's default palette (no brand color) plus the
@@ -10,5 +10,5 @@ export const DefaultDarkTheme: Theme = createTheme({
     palette: {
         mode: "dark",
     },
-    components,
+    components: componentOverrides,
 });

package/src/theme/themes/DefaultLight.ts

@@ -1,6 +1,6 @@
 import { createTheme, type Theme } from "@mui/material/styles";
 
-import { components } from "@/theme/overrides";
+import { componentOverrides } from "@/theme/overrides";
 
 /**
  * Neutral light theme. Uses MUI's default palette (no brand color) plus the
@@ -10,5 +10,5 @@ export const DefaultLightTheme: Theme = createTheme({
     palette: {
         mode: "light",
     },
-    components,
+    components: componentOverrides,
 });

package/src/theme/themes/EveryskDark.ts

@@ -1,6 +1,6 @@
 import { createTheme, type Theme } from "@mui/material/styles";
 
-import { components } from "@/theme/overrides";
+import { componentOverrides } from "@/theme/overrides";
 
 /**
  * Everysk Dark — the theme every Everysk app runs with.
@@ -58,5 +58,5 @@ export const EveryskDarkTheme: Theme = createTheme({
     shape: {
         borderRadius: 8,
     },
-    components,
+    components: componentOverrides,
 });

package/src/theme/themes/EveryskLight.ts

@@ -1,6 +1,6 @@
 import { createTheme, type Theme } from "@mui/material/styles";
 
-import { components } from "@/theme/overrides";
+import { componentOverrides } from "@/theme/overrides";
 
 /**
  * Everysk Light — the light twin of {@link EveryskDarkTheme}.
@@ -64,5 +64,5 @@ export const EveryskLightTheme: Theme = createTheme({
     shape: {
         borderRadius: 8,
     },
-    components,
+    components: componentOverrides,
 });

package/src/theme/themes/MidnightEmber.ts

@@ -1,30 +1,30 @@
 import { createTheme, type Theme } from "@mui/material/styles";
 
-import { components } from "@/theme/overrides";
+import { componentOverrides } from "@/theme/overrides";
 
 export const MidnightEmberTheme: Theme = createTheme({
     palette: {
-        mode: 'dark',
+        mode: "dark",
         primary: {
-            main: '#F97316',
-            dark: '#EA580C',
-            light: '#FDBA74',
-            contrastText: '#020617',
+            main: "#F97316",
+            dark: "#EA580C",
+            light: "#FDBA74",
+            contrastText: "#020617",
         },
         secondary: {
-            main: '#94A3B8',
-            dark: '#64748B',
-            light: '#CBD5F5',
-            contrastText: '#020617',
+            main: "#94A3B8",
+            dark: "#64748B",
+            light: "#CBD5F5",
+            contrastText: "#020617",
         },
         background: {
-            default: '#020617',
-            paper: '#0B1120',
+            default: "#020617",
+            paper: "#0B1120",
         },
         text: {
-            primary: '#F9FAFB',
+            primary: "#F9FAFB",
         },
-        divider: 'rgba(148, 163, 184, 0.25)'
+        divider: "rgba(148, 163, 184, 0.25)",
     },
-    components,
+    components: componentOverrides,
 });

package/src/types/anyRecord.ts

@@ -1,4 +1,4 @@
 export type AnyRecord = {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: any
-}
+    [key: string]: any;
+};

package/src/types/datastore.ts

@@ -1,33 +1,67 @@
 import type { AnyRecord } from "./anyRecord";
-import type { EntitySingleResponse, EntityListResponse, DeleteEntityResponse } from "./entityQuery";
+import type { EntityListResponse } from "./entityQuery";
+import type { DatastoreDataFormat } from "./datastoreDataFormat";
 
 export type DatastoreRow = string | number | null;
+
+/** A tabular datastore's content: a matrix whose first row names the columns. */
 export type DatastoreData = DatastoreRow[][];
 
 export type Datastore = {
-    updated?: number,
-    created?: number,
-
-    id: string,
-    name: string,
-    date?: string,
-    version?: string,
-    description?: string,
-
-    tags?: string[],
-    link_uid?: string,
-    workspace: string,
-    data: DatastoreData,
-    date_time: string,
-    level?: string,
-}
-
-export type DatastoreWithRows = Omit<Datastore, "data"> & {
+    updated?: number;
+    created?: number;
+
+    id: string;
+    name: string;
+    date?: string;
+    version?: string;
+    description?: string;
+
+    tags?: string[];
+    link_uid?: string;
+    workspace: string;
+    /**
+     * A matrix for a tabular datastore; an object or an array of objects for a JSON one. The API
+     * does not say which, so the shape is the only signal: an array whose every element is an
+     * array is a table. The API has returned `[{ … }]` for a JSON one, an array without being a
+     * table.
+     */
+    data: DatastoreData | AnyRecord | AnyRecord[];
+    date_time: string;
+    level?: string;
+};
+
+/** A tabular datastore as the hooks return it: the matrix converted to row objects. */
+export type TableDatastore = Omit<Datastore, "data"> & {
+    format: "table";
     data: AnyRecord[];
+    /**
+     * The column names in the datastore's own order, from the header row the conversion to
+     * objects drops. Saving back needs it — `toDatastoreMatrix(datastore)` uses it — rather
+     * than rebuilding the order from object keys and leaving out the `datastoreId` the SDK adds.
+     * Empty when the read projects `data` away.
+     */
+    fields: string[];
+};
+
+/** A JSON datastore as the hooks return it: its object or array of objects, untouched. */
+export type JsonDatastore = Omit<Datastore, "data"> & {
+    format: "json";
+    data: AnyRecord | AnyRecord[];
 };
 
-export type DatastoreSingleResponse = EntitySingleResponse<"datastore", Datastore>;
+/**
+ * A datastore as the hooks return it: its `data` read and classified by `parseDatastore`. Narrow
+ * on `format` (or with `isTableDatastore`) before reading `data` as rows: a list can mix both
+ * kinds. `F` is the `dataFormat` the hook read with. It was `DatastoreWithRows`, a name from
+ * before JSON datastores, which carry no rows.
+ */
+export type ParsedDatastore<F extends DatastoreDataFormat = "object"> =
+    | (F extends "matrix"
+          ? // A tabular datastore read with `dataFormat: "matrix"`: its matrix unconverted, header row included,
+            // so it can be written back unchanged. Written in place: nothing refers to it by name.
+            Omit<TableDatastore, "data"> & { data: DatastoreData }
+          : TableDatastore)
+    | JsonDatastore;
 
 export type DatastoreListResponse = EntityListResponse<"datastores", Datastore>;
-
-export type DeleteDatastoreResponse = DeleteEntityResponse<"datastores">;

package/src/types/datastoreDataFormat.ts

@@ -0,0 +1,12 @@
+/**
+ * How the datastore hooks hand over a **tabular** datastore's `data`; a JSON datastore's is never
+ * converted. `"object"` (the default) is each row as an object — a list of them, not one
+ * object — which lets an app patch a row as `{ ...row, ...patch }`. `"matrix"` leaves the table's
+ * matrix unconverted, header row included. A value rather than a conversion function, so it can
+ * be part of the cache key.
+ *
+ * Internal: no barrel re-exports this file. An app never writes the name — `dataFormat` is
+ * inferred from the value it passes — so it stays out of the public types, and exists only so
+ * the SDK does not repeat the union in every generic.
+ */
+export type DatastoreDataFormat = "object" | "matrix";