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

package/src/api/file.ts

@@ -1,11 +1,30 @@
-import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+import type { AxiosInstance } 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";
+import type { EveryskFile, FileListResponse } from "@/types/file";
+import type {
+    DeletedEntity,
+    DeleteEntityResponse,
+    EntitySingleResponse,
+    QueryObject,
+} from "@/types/entityQuery";
+import { listParams, request, requireWorkspace } from "./request";
 
 const baseUrl = "files";
 
+/** The endpoint's envelopes, private: every function here returns the entity itself. */
+type FileSingleResponse = EntitySingleResponse<"file", EveryskFile>;
+type DeleteFileResponse = DeleteEntityResponse<"file">;
+
+export type GetFileParams = {
+    /**
+     * `false` leaves `data` out (`null`): sent as `with_data=false`, which the API reads as the
+     * projection `-data` (everysk/client `EveryskAPIEngine_V2._get_entity_by_id`). The content
+     * comes as base64, a third larger than the file. The file hooks leave it out by default;
+     * this function, which mirrors the API, includes it.
+     */
+    withData?: boolean;
+};
+
 /**
  * getFile
  *
@@ -14,27 +33,27 @@ const baseUrl = "files";
  * @param {AxiosInstance} api - Axios instance.
  * @param {string} id - EveryskFile identifier.
  * @param {string} workspace - Workspace the file belongs to.
+ * @param {GetFileParams} [options] - Whether to include the content.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @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", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while fetching file", { cause: error });
-  }
+export const getFile = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+    { withData }: GetFileParams = {},
+    signal?: AbortSignal,
+): Promise<EveryskFile> => {
+    requireWorkspace(workspace, "fetch a file");
+
+    const params = { workspace, ...(withData === false && { with_data: false }) };
+    const body = await request(
+        () => api.get<FileSingleResponse>(`${baseUrl}/${id}`, { params, signal }),
+        "Error fetching file",
+    );
+    return body.file;
 };
 
 /**
@@ -47,34 +66,36 @@ export const getFile = async (api: AxiosInstance, id: string, workspace: string)
  *
  * @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.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
+ * @returns {Promise<FileListResponse>} Paginated list of files.
  *
+ * @throws {Error} If the query has no workspace filter.
  * @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) } : {}),
-  };
+export const listFiles = async (
+    api: AxiosInstance,
+    query: QueryObject,
+    signal?: AbortSignal,
+): Promise<FileListResponse> => {
+    const params = listParams(query, "list files");
+
+    return request(
+        () => api.get<FileListResponse>(baseUrl, { params, signal }),
+        "Error listing files",
+    );
+};
 
-  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", { cause: error });
-    } 
-    if (error instanceof Error) {
-      throw error;
+/**
+ * Refuses content sent as a data URL. The API stores `data` as given, so the
+ * `data:<type>;base64,` prefix `FileReader` puts in front would become part of the file, which
+ * then comes out corrupt with no error anywhere.
+ */
+const requireRawBase64 = ({ data }: Partial<EveryskFile>) => {
+    if (data?.startsWith("data:")) {
+        throw new Error(
+            "A file's data must be raw base64, without the data: prefix: read it with fileToBase64",
+        );
     }
-
-    throw new Error("Error while fetching files", { cause: error });
-  }
 };
 
 /**
@@ -83,30 +104,25 @@ export const listFiles = async (api: AxiosInstance, query: QueryObject): Promise
  * Creates a new file.
  *
  * @param {AxiosInstance} api - Axios instance.
- * @param {Partial<EveryskFile>} data - EveryskFile payload.
+ * @param {Partial<EveryskFile>} data - EveryskFile payload. Its `data` is the content as raw
+ *   base64, as `fileToBase64` returns it from a `File`.
  * @returns {Promise<EveryskFile>} The created file.
  *
+ * @throws {Error} If `workspace` is missing, or `data` is a data URL rather than raw base64.
  * @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", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while creating file", { cause: error });
-  }
+export const createFile = async (
+    api: AxiosInstance,
+    data: Partial<EveryskFile>,
+): Promise<EveryskFile> => {
+    requireWorkspace(data.workspace, "create a file");
+    requireRawBase64(data);
+
+    const body = await request(
+        () => api.post<FileSingleResponse>(baseUrl, data),
+        "Error creating file",
+    );
+    return body.file;
 };
 
 /**
@@ -116,30 +132,26 @@ export const createFile = async (api: AxiosInstance, data: Partial<EveryskFile>)
  *
  * @param {AxiosInstance} api - Axios instance.
  * @param {string} id - EveryskFile identifier.
- * @param {Partial<EveryskFile>} data - Fields to update.
+ * @param {Partial<EveryskFile>} data - Fields to update. A new `data` is the content as raw
+ *   base64, as `fileToBase64` returns it from a `File`.
  * @returns {Promise<EveryskFile>} The updated file.
  *
+ * @throws {Error} If `workspace` is missing, or `data` is a data URL rather than raw base64.
  * @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", { cause: error });
-        }
-
-        if (error instanceof Error) {
-            throw error;
-        }
-
-        throw new Error("Error while updating file", { cause: error });
-    }
+export const updateFile = async (
+    api: AxiosInstance,
+    id: string,
+    data: Partial<EveryskFile>,
+): Promise<EveryskFile> => {
+    requireWorkspace(data.workspace, "update a file");
+    requireRawBase64(data);
+
+    const body = await request(
+        () => api.put<FileSingleResponse>(`${baseUrl}/${id}`, data),
+        "Error updating file",
+    );
+    return body.file;
 };
 
 /**
@@ -150,25 +162,20 @@ export const updateFile = async (api: AxiosInstance, id: string, data: Partial<E
  * @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.
+ * @returns {Promise<DeletedEntity>} The deletion record: id, name and `deleted`.
  *
  * @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", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while deleting file", { cause: error });
-  }
-};
+export const deleteFile = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+): Promise<DeletedEntity> => {
+    requireWorkspace(workspace, "delete a file");
+
+    const body = await request(
+        () => api.delete<DeleteFileResponse>(`${baseUrl}/${id}`, { params: { workspace } }),
+        "Error deleting file",
+    );
+    return body.file;
+};

package/src/api/portfolio.ts

@@ -1,12 +1,20 @@
-import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+import type { AxiosInstance } 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";
+import type {
+    DeletedEntity,
+    DeleteEntityResponse,
+    EntitySingleResponse,
+    QueryObject,
+} from "@/types/entityQuery";
+import type { Portfolio, PortfolioListResponse } from "@/types/portfolio";
+import { listParams, request, requireWorkspace } from "./request";
 
 const baseUrl = "portfolios";
 
+/** The endpoint's envelopes, private: every function here returns the entity itself. */
+type PortfolioSingleResponse = EntitySingleResponse<"portfolio", Portfolio>;
+type DeletePortfolioResponse = DeleteEntityResponse<"portfolio">;
+
 /**
  * getPortfolio
  *
@@ -15,31 +23,25 @@ const baseUrl = "portfolios";
  * @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.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
+ * @returns {Promise<Portfolio>} The fetched portfolio.
  *
  * @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", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while fetching portfolio", { cause: error });
-  }
+export const getPortfolio = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+    signal?: AbortSignal,
+): Promise<Portfolio> => {
+    requireWorkspace(workspace, "fetch a portfolio");
+
+    const body = await request(
+        () =>
+            api.get<PortfolioSingleResponse>(`${baseUrl}/${id}`, { params: { workspace }, signal }),
+        "Error fetching portfolio",
+    );
+    return body.portfolio;
 };
 
 /**
@@ -49,38 +51,24 @@ export const getPortfolio = async (api: AxiosInstance, id: string, workspace: st
  *
  * @param {AxiosInstance} api - Axios instance.
  * @param {QueryObject} query - Query object built via `buildQueryObject`.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
  * @returns {Promise<PortfolioListResponse>} List of portfolios.
  *
+ * @throws {Error} If the query has no workspace filter.
  * @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", { cause: error });
-      }
-
-      if (error instanceof Error) {
-        throw error;
-      }
-
-      throw new Error("Error while fetching portfolios", { cause: error });
-    }
-}
+export const listPortfolios = async (
+    api: AxiosInstance,
+    query: QueryObject,
+    signal?: AbortSignal,
+): Promise<PortfolioListResponse> => {
+    const params = listParams(query, "list portfolios");
+
+    return request(
+        () => api.get<PortfolioListResponse>(baseUrl, { params, signal }),
+        "Error listing portfolios",
+    );
+};
 
 /**
  * createPortfolio
@@ -93,29 +81,18 @@ export const listPortfolios = async (api: AxiosInstance, query: QueryObject): Pr
  *
  * @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", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while creating portfolio", { cause: error });
-  }
-}
+export const createPortfolio = async (
+    api: AxiosInstance,
+    data: Partial<Portfolio>,
+): Promise<Portfolio> => {
+    requireWorkspace(data.workspace, "create a portfolio");
+
+    const body = await request(
+        () => api.post<PortfolioSingleResponse>(baseUrl, data),
+        "Error creating portfolio",
+    );
+    return body.portfolio;
+};
 
 /**
  * updatePortfolio
@@ -129,29 +106,19 @@ export const createPortfolio = async (api: AxiosInstance, data: Partial<Portfoli
  *
  * @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", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while updating portfolio", { cause: error });
-  }
-}
+export const updatePortfolio = async (
+    api: AxiosInstance,
+    id: string,
+    data: Partial<Portfolio>,
+): Promise<Portfolio> => {
+    requireWorkspace(data.workspace, "update a portfolio");
+
+    const body = await request(
+        () => api.put<PortfolioSingleResponse>(`${baseUrl}/${id}`, data),
+        "Error updating portfolio",
+    );
+    return body.portfolio;
+};
 
 /**
  * deletePortfolio
@@ -161,30 +128,20 @@ export const updatePortfolio = async (api: AxiosInstance, id: string, data: Part
  * @param {AxiosInstance} api - Axios instance.
  * @param {string} id - Portfolio identifier.
  * @param {string} workspace - Workspace the portfolio belongs to.
- * @returns {Promise<Portfolio>} The deleted portfolio.
+ * @returns {Promise<DeletedEntity>} The deletion record: id, name and `deleted`.
  *
  * @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", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while deleting portfolio", { cause: error });
-  }
-}
+export const deletePortfolio = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+): Promise<DeletedEntity> => {
+    requireWorkspace(workspace, "delete a portfolio");
+
+    const body = await request(
+        () => api.delete<DeletePortfolioResponse>(`${baseUrl}/${id}`, { params: { workspace } }),
+        "Error deleting portfolio",
+    );
+    return body.portfolio;
+};

package/src/api/profile.ts

@@ -1,10 +1,21 @@
-import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+import type { AxiosInstance } from "axios";
 
-import type { AnyRecord } from "@/types/anyRecord";
-import type { Profile, ProfileResponse } from "@/types/profile";
+import type { Profile } from "@/types/profile";
+import { request } from "./request";
 
 const baseUrl = "profile";
 
+/**
+ * The endpoint's envelope, private: `getProfile` returns the profile itself.
+ *
+ * It does not follow `EntitySingleResponse`: `/api/profile` is an app-only route rather than an
+ * entity, and carries a `status` beside the profile.
+ */
+type ProfileResponse = {
+    status: string;
+    profile: Profile;
+};
+
 /**
  * DEV_PROFILE — the profile served while running the dev server.
  *
@@ -56,25 +67,21 @@ export const DEV_PROFILE: Profile = {
  *
  * @param {AxiosInstance} api - Axios instance.
  * @param {Profile} [fallback] - Returned instead of calling the API, when present.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @returns {Promise<Profile>} The logged user's profile.
  *
  * @throws {Error} If the request fails.
  */
-export const getProfile = async (api: AxiosInstance, fallback?: Profile): Promise<Profile> => {
+export const getProfile = async (
+    api: AxiosInstance,
+    fallback?: Profile,
+    signal?: AbortSignal,
+): Promise<Profile> => {
     if (fallback) return fallback;
 
-    try {
-        const response: AxiosResponse<ProfileResponse> = await api.get(baseUrl);
-        return response.data.profile;
-    } catch (error: unknown) {
-        if (isAxiosError<AnyRecord>(error)) {
-            throw new Error(error.message || "Error while fetching profile", { cause: error });
-        }
-
-        if (error instanceof Error) {
-            throw error;
-        }
-
-        throw new Error("Error while fetching profile", { cause: error });
-    }
+    const body = await request(
+        () => api.get<ProfileResponse>(baseUrl, { signal }),
+        "Error fetching profile",
+    );
+    return body.profile;
 };