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

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";

package/src/types/entityQuery.ts

@@ -1,64 +1,148 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
+import type {
+    InfiniteData,
+    QueryKey,
+    UseInfiniteQueryOptions,
+    UseQueryOptions,
+} from "@tanstack/react-query";
 import type { AnyRecord } from "./anyRecord";
 
-export type FilterOperator = "=" | ">" | ">=" | "<" | "<=" | "!=";
+/** `IN` and `NOT_IN` take a list as the value: `{ field: "tags", op: "IN", value: ["a", "b"] }`. */
+export type FilterOperator = "=" | ">" | ">=" | "<" | "<=" | "!=" | "IN" | "NOT_IN";
 
 export type FilterExpression =
-  | [field: string, value: unknown]
-  | [field: string, op: FilterOperator, value: unknown];
+    [field: string, value: unknown] | [field: string, op: FilterOperator, value: unknown];
 
 export type FilterClause = {
-  field: string;
-  value: unknown;
-  op?: FilterOperator;
-}
+    field: string;
+    value: unknown;
+    op?: FilterOperator;
+};
+
+/**
+ * The fields a read returns. `"field"` or `["a", "b"]` returns only those (every other field
+ * comes back null); `"-field"` or `["-a", "-b"]` returns everything but those.
+ *
+ * The backend rejects, as a 500, a projection that mixes the two, or that names a field the
+ * entity does not have. That is also why `"a,b"` fails: it is read as one field named `a,b`.
+ * Source: everysk-lib 1.13.4, `_normalize_projection`, which the API's JSON query goes through.
+ */
+export type Projection = string | string[];
 
 export type BaseQueryParams = {
-  order: string[];
-  projection?: string;
-}
+    order: string[];
+    projection?: Projection;
+};
 
 export type EntityQueryParams = BaseQueryParams & {
-  filters: FilterClause[];
-  pageSize?: number;
-  pageToken?: string;
-}
+    filters: FilterClause[];
+    pageSize?: number;
+    pageToken?: string;
+};
 
 export type QueryObject = BaseQueryParams & {
-  filters: FilterExpression[];
-  page_size?: number;
-  page_token?: string;
+    filters: FilterExpression[];
+    page_size?: number;
+    page_token?: string;
 };
 
-export type EntityQueryOptions<TQueryFnData, TData = TQueryFnData> = Omit<UseQueryOptions<TQueryFnData, Error, TData>,"queryKey" | "queryFn">;
+/**
+ * TanStack options a single-entity hook passes through, merged over its defaults. `select` is
+ * not one of them: it is a prop of the hook, which is what types `data` as its result.
+ */
+export type EntityQueryOptions<TQueryFnData, TData = TQueryFnData> = Omit<
+    UseQueryOptions<TQueryFnData, Error, TData>,
+    "queryKey" | "queryFn" | "select"
+>;
+
+/** The props every single-entity hook shares. */
+export type FetchEntityProps<TEntity, TSelected> = {
+    /** Shapes the entity for this caller: `data` is what it returns. Keep its reference stable. */
+    select?: (entity: TEntity) => TSelected;
+    queryOptions?: EntityQueryOptions<TEntity, TSelected>;
+};
 
-export type FetchEntityParams<TData = AnyRecord, TSelected = TData> = {
-  id: string;
-  workspace: string;
-  queryOptions?: EntityQueryOptions<TData, TSelected>;
+export type FetchEntityByIdProps<TData = AnyRecord, TSelected = TData> = FetchEntityProps<
+    TData,
+    TSelected
+> & {
+    id: string;
+    workspace: string;
 };
 
-export type FetchEntitiesParams<TData = AnyRecord, QO = EntityQueryOptions<TData>> = {
+/**
+ * The JSON query a list hook sends, for the lists that take one (datastores, files, portfolios).
+ * The workspace filter is added from the app config. The workflow and workspace lists take only
+ * a text search, so they take `search` instead.
+ */
+export type ListQueryProps = {
     filters?: FilterClause[];
     order?: string[];
-    projection?: string;
-    queryOptions?: QO;
+    projection?: Projection;
 };
 
+/** The cursor a list endpoint pages with. `null` asks for the first page. */
+export type PageToken = string | null;
 
-export type EntityDefaultResponse = {
-    next_page_token: string | null;
-}
+/** What every page of a list carries beside its items: the cursor to the next page, `null` on the last. */
+export type PagedResponse = {
+    next_page_token: PageToken;
+};
+
+/**
+ * What a list hook keeps in the query cache: the pages as the API returned them (after any
+ * per-page conversion), not the flat list `query.data` shows. Type `setQueryData` with it.
+ *
+ * ```ts
+ * queryClient.setQueryData<DatastoresCache>(queryKey, (cache) => …);
+ * ```
+ */
+export type ListCache<TPage> = InfiniteData<TPage, PageToken>;
+
+/**
+ * TanStack options a list hook passes through. `select` is not one of them: it is a prop of
+ * the hook, applied after the pages are merged. Spread in from here it used to replace the
+ * merging itself, handing the caller `{ pages, pageParams }` under a type that said otherwise.
+ */
+export type EntityInfiniteQueryOptions<TPage, TData> = Omit<
+    UseInfiniteQueryOptions<TPage, Error, TData, QueryKey, PageToken>,
+    "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam" | "select"
+>;
 
-export type EntitySingleResponse<K extends string, T> = EntityDefaultResponse & Record<K, T>;
+/** The props every list hook shares. */
+export type FetchEntitiesProps<TItem, TData, TPage> = {
+    /** Items per request. */
+    pageSize?: number;
+    /**
+     * Shapes the merged list for this caller: `query.data` is what it returns. It runs on the
+     * observer, not in the cache, so writing to the cache (`setQueryData`) still works on the
+     * pages. Keep it stable (module scope or `useCallback`): TanStack reruns it whenever its
+     * reference changes.
+     */
+    select?: (items: TItem[]) => TData;
+    /**
+     * Follows the cursor to the end before reporting success, for a view that consolidates
+     * the whole set — where a partial read is a wrong answer rather than a shorter one. Raise
+     * `pageSize` with it: the read fails rather than stop short after a fixed number of pages.
+     */
+    fetchAllPages?: boolean;
+    queryOptions?: EntityInfiniteQueryOptions<TPage, TData>;
+};
+
+/** A get by id: the entity under its singular key, with no cursor. */
+export type EntitySingleResponse<K extends string, T> = Record<K, T>;
 
-export type EntityListResponse<K extends string, T> = EntityDefaultResponse & Record<K, T[]>;
+export type EntityListResponse<K extends string, T> = PagedResponse & Record<K, T[]>;
 
-export type DeleteEntityDefaultResponse = {
-  id:string,
-  name:string,
-  deleted:boolean
-}
+export type DeletedEntity = {
+    id: string;
+    name: string;
+    deleted: boolean;
+};
 
-export type DeleteEntityResponse<K extends string, T = DeleteEntityDefaultResponse> = Record<K, T[]>;
-  
+/**
+ * What a delete by id answers: one record under the entity's singular key, such as
+ * `{ datastore: { id, name, deleted } }`. Only the batch form (`?ids=a,b`), which the SDK does
+ * not use, answers a list under the plural key. This type used to describe that list, and the
+ * datastore and file deletes read `body.datastores` and `body.files`, which were undefined.
+ */
+export type DeleteEntityResponse<K extends string, T = DeletedEntity> = Record<K, T>;

package/src/types/file.ts

@@ -1,4 +1,4 @@
-import type { EntitySingleResponse, EntityListResponse, DeleteEntityResponse } from "./entityQuery";
+import type { EntityListResponse } from "./entityQuery";
 
 /**
  * A file stored in a workspace.
@@ -21,12 +21,14 @@ export type EveryskFile = {
     updated?: number;
     version: string;
     link_uid: string | null;
+    /**
+     * The content as raw base64, without a `data:<type>;base64,` prefix: `fileToBase64` turns a
+     * `File` into it, and `createFile` / `updateFile` refuse a data URL. `null` when the read
+     * left it out, as `useFetchFile` and `useFetchFiles` do unless `withData` asks for it; show
+     * or download a file through its `url` instead.
+     */
     data: string | null;
     tags?: string[];
-}
-
-export type FileSingleResponse = EntitySingleResponse<"file", EveryskFile>;
+};
 
 export type FileListResponse = EntityListResponse<"files", EveryskFile>;
-
-export type DeleteFileResponse = DeleteEntityResponse<"files">;

package/src/types/portfolio.ts

@@ -1,81 +1,77 @@
-import type { DeleteEntityResponse, EntityListResponse, EntitySingleResponse } from "./entityQuery";
+import type { EntityListResponse } from "./entityQuery";
 
 export type Security = {
-  instrument_type: string | null;
-  coupon: unknown | null;
-  issue_price: unknown | null;
-  display: string | null;
-  asset_subclass: string | null;
-  market_value: number | null;
-  rate: unknown | null;
-  book: unknown | null;
-  symbol: string | null;
-  percent_index: unknown | null;
-  settlement: unknown | null;
-  issuer_type: unknown | null;
-  label: string | null;
-  accounting: unknown | null;
-  market_price: number | null;
-  hash: string | null;
-  extra_data: unknown | null;
-  multiplier: number | null;
-  option_type: unknown | null;
-  error_type: string | null;
-  exchange: string | null;
-  premium: unknown | null;
-  fx_rate: number | null;
-  ticker: string | null;
-  status: string | null;
-  currency: string | null;
-  operation: unknown | null;
-  comparable: string | null;
-  market_value_in_base: number | null;
-  issuer: unknown | null;
-  unrealized_pl_in_base: number | null;
-  unrealized_pl: number | null;
-  instrument_class: string | null;
-  issue_date: unknown | null;
-  series: unknown | null;
-  quantity: number | null;
-  id: string | null;
-  cost_price: number | null;
-  isin: string | null;
-  strike: unknown | null;
-  asset_class: string | null;
-  look_through_reference: unknown | null;
-  return_date: unknown | null;
-  underlying: unknown | null;
-  maturity_date: unknown | null;
-  previous_quantity: number | null;
-  warranty: unknown | null;
-  name: string | null;
-  error_message: string | null;
-  indexer: unknown | null;
-  trader: unknown | null;
-  trade_id: unknown | null;
+    instrument_type: string | null;
+    coupon: unknown | null;
+    issue_price: unknown | null;
+    display: string | null;
+    asset_subclass: string | null;
+    market_value: number | null;
+    rate: unknown | null;
+    book: unknown | null;
+    symbol: string | null;
+    percent_index: unknown | null;
+    settlement: unknown | null;
+    issuer_type: unknown | null;
+    label: string | null;
+    accounting: unknown | null;
+    market_price: number | null;
+    hash: string | null;
+    extra_data: unknown | null;
+    multiplier: number | null;
+    option_type: unknown | null;
+    error_type: string | null;
+    exchange: string | null;
+    premium: unknown | null;
+    fx_rate: number | null;
+    ticker: string | null;
+    status: string | null;
+    currency: string | null;
+    operation: unknown | null;
+    comparable: string | null;
+    market_value_in_base: number | null;
+    issuer: unknown | null;
+    unrealized_pl_in_base: number | null;
+    unrealized_pl: number | null;
+    instrument_class: string | null;
+    issue_date: unknown | null;
+    series: unknown | null;
+    quantity: number | null;
+    id: string | null;
+    cost_price: number | null;
+    isin: string | null;
+    strike: unknown | null;
+    asset_class: string | null;
+    look_through_reference: unknown | null;
+    return_date: unknown | null;
+    underlying: unknown | null;
+    maturity_date: unknown | null;
+    previous_quantity: number | null;
+    warranty: unknown | null;
+    name: string | null;
+    error_message: string | null;
+    indexer: unknown | null;
+    trader: unknown | null;
+    trade_id: unknown | null;
 };
 
 export type Portfolio = {
-    id:string;
-    name?:string;
-    description?:string;
-    base_currency:string;
-    securities:Security[];
-    nlv?:number;
-    date:string;
-    date_time?:string;
-    tags?:string[];
-    workspace:string;
-    created?:number;
-    updated?:number;
-    version?:string;
-    link_uid?:string|null;
-    level?:string|null;
-    check_securities?:boolean;
-}
-
-export type PortfolioSingleResponse = EntitySingleResponse<"portfolio", Portfolio>;
+    id: string;
+    name?: string;
+    description?: string;
+    base_currency: string;
+    securities: Security[];
+    nlv?: number;
+    date: string;
+    date_time?: string;
+    tags?: string[];
+    workspace: string;
+    created?: number;
+    updated?: number;
+    version?: string;
+    link_uid?: string | null;
+    level?: string | null;
+    check_securities?: boolean;
+};
 
 export type PortfolioListResponse = EntityListResponse<"portfolios", Portfolio>;
-
-export type DeletePortfolioResponse = DeleteEntityResponse<"portfolios">;

package/src/types/profile.ts

@@ -26,14 +26,3 @@ export interface Profile {
     auto_refresh: unknown;
     [key: string]: unknown;
 }
-
-/**
- * ProfileResponse — the endpoint's envelope.
- *
- * It does not follow `EntitySingleResponse`: `/api/profile` is not a queryable entity, so the
- * payload carries a `status` and no `next_page_token`.
- */
-export type ProfileResponse = {
-    status: string;
-    profile: Profile;
-};

package/src/types/workflow.ts

@@ -1,4 +1,4 @@
-import type { DeleteEntityResponse, EntityListResponse, EntitySingleResponse } from "./entityQuery";
+import type { EntityListResponse } from "./entityQuery";
 
 export interface Workflow {
     id: string;
@@ -60,17 +60,46 @@ export type WorkerExecution = {
     version: string;
 };
 
-
-export type WorkflowSingleResponse = EntitySingleResponse<"workflow", Workflow>;
-
 export type WorkflowListResponse = EntityListResponse<"workflows", Workflow>;
 
-export type DeleteWorkflowResponse = DeleteEntityResponse<"workflows">;
+export type WorkflowExecutionListResponse = EntityListResponse<
+    "workflow_executions",
+    WorkflowExecution
+>;
 
-export type WorkflowExecutionSingleResponse = EntitySingleResponse<"workflow_execution", WorkflowExecution>;
+/** What `useRunWorkflow` resolves with: the ended run and its output. */
+export type WorkflowResult = {
+    /** The execution, ended `SUCCEEDED`. */
+    execution: WorkflowExecution;
+    /** The Ender's worker execution, or `null` when the run did not reference one. */
+    workerExecution: WorkerExecution | null;
+    /** What the Ender produced (`workerExecution.result`), or `null`. */
+    result: Record<string, unknown> | null;
+};
 
-export type WorkflowExecutionListResponse = EntityListResponse<"workflow_executions", WorkflowExecution>;
+/** The fields every group of `WorkerExecutionListResponse` carries. */
+type WorkerExecutionGroupBase = {
+    worker_id: string;
+    worker_name: string;
+};
 
-export type WorkerExecutionSingleResponse = EntitySingleResponse<"worker_execution", WorkerExecution>;
+/**
+ * One worker's runs within a workflow execution, as the list endpoint groups them: a single
+ * `execution`, or, for a worker that ran in parallel, every run under `executions`, ordered by
+ * parallel index. Narrow on `is_parallel_execution`.
+ */
+export type WorkerExecutionGroup = WorkerExecutionGroupBase &
+    (
+        | { is_parallel_execution: false; execution: WorkerExecution }
+        | { is_parallel_execution: true; executions: WorkerExecution[] }
+    );
 
-export type WorkerExecutionListResponse = {parallel_index_max:number} & EntityListResponse<"worker_executions", WorkerExecution>;
+/**
+ * What `GET /workflows/:id/worker_executions` returns for one workflow execution: every worker
+ * at once, grouped. Not paginated — there is no `next_page_token` — and `parallel_index_max` is
+ * the highest parallel index among them, `-1` when no worker ran in parallel.
+ */
+export type WorkerExecutionListResponse = {
+    worker_executions: WorkerExecutionGroup[];
+    parallel_index_max: number;
+};

package/src/types/workspace.ts

@@ -1,4 +1,4 @@
-import type { EntityListResponse, EntitySingleResponse } from "./entityQuery";
+import type { EntityListResponse } from "./entityQuery";
 
 export interface Workspace {
     name: string;
@@ -10,6 +10,4 @@ export interface Workspace {
     [key: string]: unknown;
 }
 
-export type WorkspaceSingleResponse = EntitySingleResponse<"workspace", Workspace>;
-
-export type WorkspaceListResponse = EntityListResponse<"workspaces", Workspace>;
+export type WorkspaceListResponse = EntityListResponse<"workspaces", Workspace>;

package/src/ui/index.ts

@@ -11,4 +11,4 @@ export { EveryskIcon } from "@/components/ui/EveryskIcon";
 export { Footer } from "@/components/ui/Footer";
 export { GlobalLoading } from "@/components/ui/GlobalLoading";
 export { PageContainer } from "@/components/ui/PageContainer";
-export { Toolbar } from "@/components/ui/Toolbar";
+export { Toolbar, type ToolbarContent, type ToolbarProps } from "@/components/ui/Toolbar";