@everysk/apps-sdk 0.1.0-beta.0

package/src/agGrid/index.ts

@@ -0,0 +1,15 @@
+// `@everysk/apps-sdk/ag-grid` — the grid layer: license registration and the grid theme.
+//
+// `ag-grid-community` and `ag-grid-enterprise` are OPTIONAL peers: an app that never imports
+// this subpath does not install them, which keeps the grid out of the lockfile, out of CI
+// install time and out of the license perimeter. That is also why the grid theme lives here
+// rather than next to the MUI theme in `/theme` — importing it there would put an AG Grid
+// import in the path every app loads.
+//
+// The license key is a parameter, never read from the environment by this package — see
+// `setAgGridLicense` for why that distinction is load-bearing once the code is published.
+
+export { setAgGridLicense, AgGridLicenseProvider } from "@/contexts/agGridLicenseContext/provider";
+export type { AgGridLicenseProviderProps } from "@/contexts/agGridLicenseContext/provider";
+
+export { getAgGridTheme, useAgGridTheme, agGridThemeParams } from "./agGridTheme";

package/src/api/datastore.ts

@@ -0,0 +1,175 @@
+import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+
+import type { AnyRecord } from "@/types/anyRecord";
+import type { DeleteEntityDefaultResponse, FilterExpression, QueryObject } from "@/types/entityQuery";
+import type { Datastore, DatastoreSingleResponse, DatastoreListResponse, DeleteDatastoreResponse } from "@/types/datastore";
+
+const baseUrl = "datastores";
+
+/**
+ * getDatastore
+ *
+ * Fetches a single datastore by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - Datastore identifier.
+ * @param {string} workspace - Workspace the datastore belongs to.
+ * @returns {Promise<Datastore>} The fetched datastore.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const getDatastore = async (api: AxiosInstance, id: string, workspace: string): Promise<Datastore> => {
+  const params: AnyRecord = { workspace };
+
+  if (!workspace) throw new Error("Workspace filter is required to fetch a datastore");
+
+  try {
+    const response: AxiosResponse<DatastoreSingleResponse> = await api.get(`${baseUrl}/${id}`, { params });
+    return response.data.datastore;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error fetching datastore");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error fetching datastore");
+  }
+};
+
+/**
+ * listDatastores
+ *
+ * Fetches a list of datastores using a query object (filters, order, pagination, etc.).
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {AnyRecord} query - Query object built via `buildQueryObject`.
+ * @returns {Promise<DatastoreListResponse>} Paginated list of datastores.
+ *
+ * @throws {Error} If workspace filter is missing.
+ * @throws {Error} If the request fails.
+ */
+export const listDatastores = async (api: AxiosInstance, query: QueryObject): Promise<DatastoreListResponse> => {
+  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === "workspace");
+  const workspace = workspaceFilter?.[workspaceFilter.length - 1];
+
+  if (!workspace) throw new Error("Workspace filter is required to list datastores");
+
+  const params: AnyRecord = {
+    workspace,
+    ...(query ? { query: JSON.stringify(query) } : {}),
+  };
+
+  try {
+    const response: AxiosResponse<DatastoreListResponse> = await api.get(baseUrl, { params });
+    return response.data;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error listing datastores");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error listing datastores");
+  }
+};
+
+/**
+ * createDatastore
+ *
+ * Creates a new datastore.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {Partial<Datastore>} data - Datastore payload.
+ * @returns {Promise<Datastore>} The created datastore.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const createDatastore = async (api: AxiosInstance, data: Partial<Datastore>): Promise<Datastore> => {
+
+  const { workspace } = data;
+  if (!workspace) throw new Error("Workspace filter is required to create a datastore");
+
+  try {
+    const response: AxiosResponse<DatastoreSingleResponse> = await api.post(baseUrl, data);
+    return response.data.datastore;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error creating datastore");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error creating datastore");
+  }
+};
+
+/**
+ * updateDatastore
+ *
+ * Updates an existing datastore by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - Datastore identifier.
+ * @param {Partial<Datastore>} data - Fields to update.
+ * @returns {Promise<Datastore>} The updated datastore.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const updateDatastore = async (api: AxiosInstance, id: string, data: Partial<Datastore>): Promise<Datastore> => {
+
+  const { workspace } = data;
+  if (!workspace) throw new Error("Workspace filter is required to update a datastore");
+
+  try {
+    const response: AxiosResponse<DatastoreSingleResponse> = await api.put(`${baseUrl}/${id}`, data);
+    return response.data.datastore;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error updating datastore");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error updating datastore");
+  }
+};
+
+/**
+ * deleteDatastore
+ *
+ * Deletes a datastore by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - Datastore identifier.
+ * @param {string} workspace - Workspace the datastore belongs to.
+ * @returns {Promise<DeleteEntityDefaultResponse[]>} List of deleted entity records.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const deleteDatastore = async (api: AxiosInstance, id: string, workspace: string): Promise<DeleteEntityDefaultResponse[]> => {
+  const params: AnyRecord = { workspace };
+
+  try {
+    const response: AxiosResponse<DeleteDatastoreResponse> = await api.delete(`${baseUrl}/${id}`, { params });
+    return response.data.datastores;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error removing datastore");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error removing datastore");
+  }
+};

package/src/api/entityQuery.ts

@@ -0,0 +1,101 @@
+import type { FilterClause, FilterExpression, EntityQueryParams, QueryObject } from "@/types/entityQuery";
+
+/**
+ * toFilterTuple
+ *
+ * Converts a `FilterClause` object into a `FilterExpression` tuple
+ * compatible with the API query format.
+ *
+ * - If no operator is provided or operator is `"="`, returns a 2-tuple `[field, value]`.
+ * - Otherwise, returns a 3-tuple `[field, op, value]`.
+ *
+ * @param {FilterClause} filter - Filter clause to convert.
+ * @returns {FilterExpression} Tuple representation of the filter.
+ *
+ * Examples:
+ * ```ts
+ * toFilterTuple({ field: "workspace", value: "ws-1" })
+ * // -> ["workspace", "ws-1"]
+ *
+ * toFilterTuple({ field: "age", op: ">=", value: 18 })
+ * // -> ["age", ">=", 18]
+ * ```
+ */
+export const toFilterTuple = (filter: FilterClause): FilterExpression => {
+    const { field, op, value } = filter;
+    if (!op || op === '=') {
+        return [field, value];
+    }
+    return [field, op, value];
+};
+
+/**
+ * buildQueryObject
+ *
+ * Builds the query payload object to be sent to the API,
+ * converting filters, ordering, pagination, and projection into the expected format.
+ *
+ * @param {EntityQueryParams} params - Query parameters.
+ * @param {FilterClause[]} params.filters - Filters to apply (converted via `toFilterTuple`).
+ * @param {string[]} params.order - Sorting fields.
+ * @param {number} [params.pageSize] - Number of items per page.
+ * @param {string} [params.pageToken] - Cursor token for the next page.
+ * @param {string} [params.projection] - Single field to project. `"field"` returns only that
+ *   field (every other field comes back null); `"-field"` returns all fields except that one.
+ *   One field only — comma/space lists return a 500. Omitted from payload if empty.
+ * @returns {QueryObject} Query payload ready to be passed to the API.
+ *
+ * Example:
+ * ```ts
+ * buildQueryObject({
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ *   order: ["name"], // plain field name(s) only — no "asc"/"desc" suffix
+ *   pageSize: 10,
+ *   pageToken: "token-abc",
+ *   projection: "name",
+ * });
+ * // -> {
+ * //   filters: [["workspace", "ws-1"]],
+ * //   order: ["name"],
+ * //   projection: "name",
+ * //   page_size: 10,
+ * //   page_token: "token-abc",
+ * // }
+ * ```
+ */
+export const buildQueryObject = (params: EntityQueryParams): QueryObject => {
+    const { filters, pageSize, pageToken, order, projection } = params;
+
+    return {
+        filters: filters.map(toFilterTuple),
+        order,
+        ...(!!projection && { projection }),
+        page_size: pageSize,
+        page_token: pageToken,
+    };
+}
+
+/**
+ * buildQueryKey
+ *
+ * Builds a stable React Query cache key by combining a base key array
+ * with the values of the provided filters.
+ *
+ * This ensures the query is re-executed whenever filter values change.
+ *
+ * @param {(string | number)[]} keys - Base keys (e.g. entity name, id).
+ * @param {FilterClause[]} filters - Filters whose values are appended to the key.
+ * @returns {unknown[]} Cache key array for use in `queryKey`.
+ *
+ * Example:
+ * ```ts
+ * buildQueryKey(["datastores"], [{ field: "workspace", value: "ws-1" }]);
+ * // -> ["datastores", "ws-1"]
+ * ```
+ */
+export const buildQueryKey = (keys: (string | number)[], filters: FilterClause[]): unknown[] => {
+    return [
+        ...keys,
+        ...filters.flatMap((filter) => filter.value)
+    ];
+}

package/src/api/file.ts

@@ -0,0 +1,174 @@
+import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+
+import type { AnyRecord } from "@/types/anyRecord";
+import type { DeleteFileResponse, EveryskFile, FileListResponse, FileSingleResponse } from "@/types/file";
+import type { DeleteEntityDefaultResponse, FilterExpression, QueryObject } from "@/types/entityQuery";
+
+const baseUrl = "files";
+
+/**
+ * getFile
+ *
+ * Fetches a single file by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - EveryskFile identifier.
+ * @param {string} workspace - Workspace the file belongs to.
+ * @returns {Promise<EveryskFile>} The fetched file.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const getFile = async (api: AxiosInstance, id: string, workspace: string): Promise<EveryskFile> => {
+  const params: AnyRecord = { workspace };
+
+  try {
+    const response: AxiosResponse<FileSingleResponse> = await api.get(`${baseUrl}/${id}`, { params });
+    return response.data.file;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+     throw new Error(error.message || "Error while fetching file");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while fetching file");
+  }
+};
+
+/**
+ * listFiles
+ *
+ * Fetches a list of files using a query object (filters, order, pagination, etc.).
+ *
+ * Note: `workspace` is extracted from the query filters and sent as a separate
+ * query param alongside the serialized query object.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {QueryObject} query - Query object built via `buildQueryObject`.
+ * @returns {Promise<EveryskFile[]>} List of files. Returns an empty array if none found.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const listFiles = async (api: AxiosInstance, query: QueryObject): Promise<FileListResponse> => {
+  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === "workspace");
+  const workspace = workspaceFilter?.[workspaceFilter.length - 1];
+  
+  if (!workspace) throw new Error("Workspace filter is required to list files");
+
+  const params: AnyRecord = {
+    workspace,
+    ...(query ? { query: JSON.stringify(query) } : {}),
+  };
+
+  try {
+    const response: AxiosResponse<FileListResponse> = await api.get(baseUrl, { params });
+    return response.data;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error while fetching files");
+    } 
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while fetching files");
+  }
+};
+
+/**
+ * createFile
+ *
+ * Creates a new file.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {Partial<EveryskFile>} data - EveryskFile payload.
+ * @returns {Promise<EveryskFile>} The created file.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const createFile = async (api: AxiosInstance, data: Partial<EveryskFile>): Promise<EveryskFile> => {
+
+  const { workspace } = data;
+  if (!workspace) throw new Error("Workspace filter is required to create a file");
+
+  try {
+    const response: AxiosResponse<FileSingleResponse> = await api.post(baseUrl, data);
+    return response.data.file;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error while creating file");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while creating file");
+  }
+};
+
+/**
+ * updateFile
+ *
+ * Updates an existing file by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - EveryskFile identifier.
+ * @param {Partial<EveryskFile>} data - Fields to update.
+ * @returns {Promise<EveryskFile>} The updated file.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const updateFile = async (api: AxiosInstance, id: string, data: Partial<EveryskFile>): Promise<EveryskFile> => {
+
+    const { workspace } = data;
+    if (!workspace) throw new Error("Workspace filter is required to update a file");
+
+    try {
+        const response: AxiosResponse<FileSingleResponse> = await api.put(`${baseUrl}/${id}`, data);
+        return response.data.file;
+    } catch (error: unknown) {
+        if (isAxiosError<AnyRecord>(error)) {
+            throw new Error(error.message || "Error while updating file");
+        }
+
+        if (error instanceof Error) {
+            throw error;
+        }
+
+        throw new Error("Error while updating file");
+    }
+};
+
+/**
+ * deleteFile
+ *
+ * Deletes a file by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - EveryskFile identifier.
+ * @param {string} workspace - Workspace the file belongs to.
+ * @returns {Promise<DeleteEntityDefaultResponse[]>} List of deleted entity records.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const deleteFile = async (api: AxiosInstance, id: string, workspace: string): Promise<DeleteEntityDefaultResponse[]> => {
+  const params: AnyRecord = { workspace };
+
+  try {
+    const response: AxiosResponse<DeleteFileResponse> = await api.delete(`${baseUrl}/${id}`, { params });
+    return response.data.files;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error while deleting file");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while deleting file");
+  }
+};

package/src/api/portfolio.ts

@@ -0,0 +1,190 @@
+import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+
+import type { QueryObject } from "@/types/entityQuery";
+import type { AnyRecord } from "@/types/anyRecord";
+import type { FilterExpression } from "@/types/entityQuery";
+import type { Portfolio, PortfolioListResponse, PortfolioSingleResponse } from "@/types/portfolio";
+
+const baseUrl = "portfolios";
+
+/**
+ * getPortfolio
+ *
+ * Fetches a single portfolio by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - Portfolio identifier.
+ * @param {string} workspace - Workspace the portfolio belongs to.
+ * @returns {Promise<PortfolioSingleResponse>} The fetched portfolio response.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const getPortfolio = async (api: AxiosInstance, id: string, workspace: string): Promise<PortfolioSingleResponse> => {
+  const params: AnyRecord = { workspace };
+
+  if(!workspace){
+    throw new Error("Workspace is required to fetch a portfolio");
+  }
+
+  try {
+    const response: AxiosResponse<PortfolioSingleResponse> = await api.get(`${baseUrl}/${id}`, { params });
+    return response.data;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+     throw new Error(error.message || "Error while fetching portfolio");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while fetching portfolio");
+  }
+};
+
+/**
+ * listPortfolios
+ *
+ * Fetches a list of portfolios using a query object (filters, order, pagination, etc.).
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {QueryObject} query - Query object built via `buildQueryObject`.
+ * @returns {Promise<PortfolioListResponse>} List of portfolios.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const listPortfolios = async (api: AxiosInstance, query: QueryObject): Promise<PortfolioListResponse> => {
+    const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === "workspace");
+    const workspace = workspaceFilter?.[workspaceFilter.length - 1];
+
+    if (!workspace) {
+      throw new Error("Workspace is required to fetch portfolios");
+    }
+
+    const params: AnyRecord = {
+      workspace,
+      ...(query ? { query: JSON.stringify(query) } : {}),
+    };
+
+    try {
+      const response: AxiosResponse<PortfolioListResponse> = await api.get(baseUrl, { params });
+      return response.data;
+    } catch (error: unknown) {
+      if (isAxiosError<AnyRecord>(error)) {
+        throw new Error(error.message || "Error while fetching portfolios");
+      }
+
+      if (error instanceof Error) {
+        throw error;
+      }
+
+      throw new Error("Error while fetching portfolios");
+    }
+}
+
+/**
+ * createPortfolio
+ *
+ * Creates a new portfolio.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {Partial<Portfolio>} data - Portfolio payload.
+ * @returns {Promise<Portfolio>} The created portfolio.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const createPortfolio = async (api: AxiosInstance, data: Partial<Portfolio>): Promise<Portfolio> => {
+
+  const { workspace } = data;
+
+   if (!workspace) {
+    throw new Error("Workspace is required to post a portfolio");
+  }
+
+  try {
+    const response: AxiosResponse<Portfolio> = await api.post(baseUrl, data);
+    return response.data;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error while creating portfolio");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while creating portfolio");
+  }
+}
+
+/**
+ * updatePortfolio
+ *
+ * Updates an existing portfolio by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - Portfolio identifier.
+ * @param {Partial<Portfolio>} data - Fields to update.
+ * @returns {Promise<Portfolio>} The updated portfolio.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const updatePortfolio = async (api: AxiosInstance, id: string, data: Partial<Portfolio>): Promise<Portfolio> => {
+
+  const { workspace } = data;
+  
+  if(!workspace) {
+    throw new Error("Workspace is required to delete a portfolio");
+  }
+
+  try {
+    const response: AxiosResponse<Portfolio> = await api.put(`${baseUrl}/${id}`, data);
+    return response.data;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error while updating portfolio");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while updating portfolio");
+  }
+}
+
+/**
+ * deletePortfolio
+ *
+ * Deletes a portfolio by ID.
+ *
+ * @param {AxiosInstance} api - Axios instance.
+ * @param {string} id - Portfolio identifier.
+ * @param {string} workspace - Workspace the portfolio belongs to.
+ * @returns {Promise<Portfolio>} The deleted portfolio.
+ *
+ * @throws {Error} If the request fails.
+ */
+export const deletePortfolio = async (api: AxiosInstance, id: string, workspace: string): Promise<Portfolio> => {
+  
+  if(!workspace) {
+    throw new Error("Workspace is required to delete a portfolio");
+  }
+  
+  const params: AnyRecord = { workspace };
+
+  try {
+    const response: AxiosResponse<Portfolio> = await api.delete(`${baseUrl}/${id}`, { params });
+    return response.data;
+  } catch (error: unknown) {
+    if (isAxiosError<AnyRecord>(error)) {
+      throw new Error(error.message || "Error while deleting portfolio");
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+
+    throw new Error("Error while deleting portfolio");
+  }
+}