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

package/src/hooks/workspace/useFetchWorkspaces.ts

@@ -1,86 +1,55 @@
-import { useMemo } from "react";
-import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
+import { useEntityInfiniteQuery } from "@/hooks/useEntityInfiniteQuery";
 import { listWorkspaces } from "@/api/workspace";
+import { buildQueryKey } from "@/api/entityQuery";
 import type { Workspace, WorkspaceListResponse } from "@/types/workspace";
-
-type PageToken = string | null;
-
-type InfiniteOptions<TData> = Omit<
-    UseInfiniteQueryOptions<WorkspaceListResponse, Error, TData, QueryKey, PageToken>,
-    "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"
->;
-
-export type FetchInfiniteWorkspaceProps = {
-    workspace?: string;
-    pageSize?: number;
-    queryOptions?: InfiniteOptions<Workspace[]>;
-};
-
-const defaultQueryOptions: InfiniteOptions<Workspace[]> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
+import type { FetchEntitiesProps, ListCache } from "@/types/entityQuery";
+
+/** The query cache of `useFetchWorkspaces`, for typing `setQueryData`. */
+export type WorkspacesCache = ListCache<WorkspaceListResponse>;
+
+export type FetchWorkspacesProps<TData = Workspace[]> = FetchEntitiesProps<
+    Workspace,
+    TData,
+    WorkspaceListResponse
+> & {
+    /** A name prefix. */
+    search?: string;
 };
 
 /**
  * useFetchWorkspaces
  *
- * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
- * workspaces with cursor-based pagination.
- *
- * It also:
- * - flattens all pages into a single `Workspace[]` via `select`
- *
- * Important notes:
- * - `query.data` returns a flat `Workspace[]` (all pages merged).
- * - `workspace` is required by some API configurations to avoid being blocked.
+ * Lists workspaces with cursor pagination; `query.data` is every loaded page merged, or
+ * whatever `select` makes of it. `select` and `fetchAllPages` behave as in
+ * `useFetchDatastores`. This endpoint lists the account's workspaces: it takes a name `search`,
+ * and no workspace — the docs exempt it, and the endpoint ignores one, which this hook used to
+ * send.
  *
- * @param props - FetchInfiniteWorkspaceProps
- *   - `workspace`: Current workspace name sent as a query param.
- *   - `pageSize`: Number of workspaces to fetch per page.
- *   - `queryOptions`: TanStack Query options passed through to `useInfiniteQuery`.
- *
- * Returns:
- * @returns {object}
- *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
- *   - `queryKey`: the cache key used by React Query
- *
- * Example:
- * ```ts
- * const { query } = useFetchWorkspaces({ workspace: "main", pageSize: 20 });
- *
- * // Flat list of all fetched workspaces
- * const workspaces = query.data ?? [];
- * ```
+ * @param {FetchWorkspacesProps} props - Search, page size, `select`, `fetchAllPages` and
+ *   TanStack `queryOptions`.
+ * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
  */
-export function useFetchWorkspaces({ workspace, pageSize = 10, queryOptions }: FetchInfiniteWorkspaceProps) {
+export function useFetchWorkspaces<TData = Workspace[]>({
+    search,
+    pageSize = 10,
+    select,
+    fetchAllPages = false,
+    queryOptions,
+}: FetchWorkspacesProps<TData>) {
     const { api } = useAxios();
 
-    const queryKey: QueryKey = ["workspaces", workspace ?? null];
-
-    const mergedQueryOptions = useMemo<InfiniteOptions<Workspace[]>>(() => ({
-        ...defaultQueryOptions,
-        ...(queryOptions ?? {}),
-    }), [queryOptions]);
+    const queryKey = buildQueryKey(["workspaces", search ?? null], [], { pageSize, fetchAllPages });
 
-    const query = useInfiniteQuery<WorkspaceListResponse, Error, Workspace[], QueryKey, PageToken>({
+    const query = useEntityInfiniteQuery<WorkspaceListResponse, "workspaces", TData>({
         queryKey,
-        initialPageParam: null,
-        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
-
-        queryFn: async ({ pageParam }) => {
-            return await listWorkspaces(api, workspace, pageSize, pageParam ?? undefined);
-        },
-
-        select: (data) => data.pages.flatMap((p) => p.workspaces),
-
-        ...mergedQueryOptions,
+        itemsKey: "workspaces",
+        fetchPage: (pageToken, signal) =>
+            listWorkspaces(api, { search, pageSize, pageToken: pageToken ?? undefined }, signal),
+        select,
+        fetchAllPages,
+        queryOptions,
     });
 
-    return {
-        query,
-        queryKey,
-    };
+    return { query, queryKey };
 }

package/src/index.ts

@@ -10,21 +10,19 @@
 // before it can tree-shake it, so re-exporting the AG Grid layer from here would fail to build
 // in an app that never installed ag-grid — even one importing nothing but createQueryClient.
 
-export { EveryskApp } from "./EveryskApp";
-export type { EveryskAppProps, ProviderComponent } from "./EveryskApp";
+export { EveryskApp, withProps } from "./EveryskApp";
+export type {
+    ConfiguredProvider,
+    EveryskAppProps,
+    ProviderComponent,
+    ProviderEntry,
+} from "./EveryskApp";
 
-// Contexts — app configuration
-export { AppConfigContext } from "./contexts/appConfigContext";
-export { AppConfigProvider } from "./contexts/appConfigContext/provider";
+// Contexts. `EveryskApp` mounts both providers, so only the hooks and the types are public: a
+// second provider would give part of the tree a context of its own.
 export { useAppConfig } from "./contexts/appConfigContext/useAppConfig";
-export type {
-    AppConfigContextType,
-    AppConfigProviderProps,
-} from "./contexts/appConfigContext/types";
+export type { AppConfigContextType } from "./contexts/appConfigContext/types";
 
-// Contexts — alerts
-export { AppAlertContext } from "./contexts/appAlertContext";
-export { AppAlertProvider } from "./contexts/appAlertContext/provider";
 export { useAppAlert } from "./contexts/appAlertContext/useAppAlert";
 export type {
     AppAlertContextType,
@@ -34,29 +32,46 @@ export type {
 
 // Hooks
 export { useAxios } from "./hooks/useAxios";
+// The hooks the entity slices are built on, public for an endpoint the SDK does not cover.
+export { useEntityQuery } from "./hooks/useEntityQuery";
+export type { EntityQueryProps } from "./hooks/useEntityQuery";
+export { useEntityMutation } from "./hooks/useEntityMutation";
+export type { EntityMutationProps } from "./hooks/useEntityMutation";
+export { useEntityInfiniteQuery, FETCH_ALL_PAGES_LIMIT } from "./hooks/useEntityInfiniteQuery";
+export type { EntityInfiniteQueryProps, ItemOf } from "./hooks/useEntityInfiniteQuery";
 
 // API helpers
-export { toFilterTuple, buildQueryObject, buildQueryKey } from "./api/entityQuery";
+export {
+    buildQueryObject,
+    buildQueryKey,
+    hasWorkspaceFilter,
+    missingWorkspaceError,
+} from "./api/entityQuery";
+export type { QueryKeyParams } from "./api/entityQuery";
 
 // Query client
-export { createQueryClient, getQueryFn } from "./lib/queryClient";
+export { createQueryClient } from "./lib/queryClient";
 
 // Types
 export type { AnyRecord } from "./types/anyRecord";
 export type {
-    BaseQueryParams,
-    DeleteEntityDefaultResponse,
+    DeletedEntity,
     DeleteEntityResponse,
-    EntityDefaultResponse,
+    EntityInfiniteQueryOptions,
     EntityListResponse,
     EntityQueryOptions,
     EntityQueryParams,
     EntitySingleResponse,
-    FetchEntitiesParams,
-    FetchEntityParams,
+    FetchEntitiesProps,
+    FetchEntityByIdProps,
+    FetchEntityProps,
     FilterClause,
     FilterExpression,
     FilterOperator,
+    ListCache,
+    ListQueryProps,
+    PagedResponse,
+    PageToken,
     QueryObject,
 } from "./types/entityQuery";
 

package/src/lib/abort.ts

@@ -0,0 +1,131 @@
+/**
+ * abortable
+ *
+ * The one shape every abortable wait here takes: a promise that `start` settles, or that rejects
+ * with the signal's reason as soon as it aborts. `start` returns its cleanup, which runs either
+ * way, so a timer or a listener never outlives the promise.
+ *
+ * @param signal - Aborts the wait.
+ * @param start - Begins the work and returns what undoes it.
+ * @returns The work's result, unless the signal aborts first.
+ */
+export const abortable = <T>(
+    signal: AbortSignal,
+    start: (resolve: (value: T) => void, reject: (error: unknown) => void) => () => void,
+): Promise<T> =>
+    new Promise<T>((resolve, reject) => {
+        if (signal.aborted) return reject(signal.reason);
+
+        let cleanup = () => {};
+        const finish = () => {
+            cleanup();
+            signal.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            finish();
+            reject(signal.reason);
+        };
+
+        signal.addEventListener("abort", onAbort, { once: true });
+        cleanup = start(
+            (value) => {
+                finish();
+                resolve(value);
+            },
+            (error) => {
+                finish();
+                reject(error);
+            },
+        );
+    });
+
+/**
+ * Settles as `promise` does, or rejects with the signal's reason once it aborts first — for work
+ * that may not honour the signal itself.
+ */
+export const unlessAborted = <T>(promise: Promise<T>, signal: AbortSignal): Promise<T> =>
+    abortable(signal, (resolve, reject) => {
+        promise.then(resolve, reject);
+        return () => {};
+    });
+
+/**
+ * createDeadline
+ *
+ * A signal that aborts after `timeoutMs`, or as soon as `signal` does, each with its own error.
+ * `dispose` stops the timer and the listener once the work is done.
+ *
+ * @param options - The timeout, the outer signal, and the error each abort carries. The errors
+ *   are built when the abort happens, so they can describe the state at that moment.
+ * @returns The signal, and `dispose`.
+ */
+export const createDeadline = ({
+    timeoutMs,
+    signal,
+    timeoutError,
+    abortError,
+}: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    timeoutError: () => Error;
+    abortError: () => Error;
+}) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(timeoutError()), timeoutMs);
+    const abort = () => controller.abort(abortError());
+
+    if (signal?.aborted) abort();
+    else signal?.addEventListener("abort", abort, { once: true });
+
+    return {
+        signal: controller.signal,
+        dispose() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        },
+    };
+};
+
+/**
+ * anySignal
+ *
+ * A signal that aborts as soon as any of `signals` does, with that one's reason. It is
+ * `AbortSignal.any`, written out because that arrived in Chrome 116, Firefox 124 and Safari 17.4,
+ * after the browsers a Vite 8 app targets by default (Chrome 111, Firefox 114, Safari 16.4).
+ * What it uses instead — `abort(reason)`, `signal.reason` and `addEventListener`'s `once` —
+ * predates them all. Source: MDN browser-compat-data, `api/AbortSignal.json` and
+ * `api/AbortController.json` (2026-10-14).
+ *
+ * Missing signals are skipped, so an optional one can be passed as is. It stops listening to the
+ * others once one aborts, or when `dispose` is called: a run that ends normally aborts nothing,
+ * and a long-lived signal would otherwise keep one listener per run.
+ *
+ * @param signals - The signals to follow; `undefined` entries are ignored.
+ * @returns The signal that aborts with the first of them, and `dispose`.
+ */
+export const anySignal = (
+    signals: (AbortSignal | undefined)[],
+): { signal: AbortSignal; dispose: () => void } => {
+    const controller = new AbortController();
+    const present = signals.filter((signal): signal is AbortSignal => signal !== undefined);
+
+    const already = present.find((signal) => signal.aborted);
+    if (already) {
+        controller.abort(already.reason);
+        return { signal: controller.signal, dispose: () => {} };
+    }
+
+    const dispose = () => {
+        for (const [signal, listener] of listeners) signal.removeEventListener("abort", listener);
+    };
+    const listeners = present.map((signal) => {
+        const listener = () => {
+            dispose();
+            controller.abort(signal.reason);
+        };
+        signal.addEventListener("abort", listener, { once: true });
+        return [signal, listener] as const;
+    });
+
+    return { signal: controller.signal, dispose };
+};

package/src/lib/datastoreTable.ts

@@ -1,4 +1,5 @@
-import type { Datastore } from "@/types/datastore";
+import type { Datastore, ParsedDatastore, JsonDatastore } from "@/types/datastore";
+import type { DatastoreDataFormat } from "@/types/datastoreDataFormat";
 import type { AnyRecord } from "@/types/anyRecord";
 
 type Cell = string | number | null;
@@ -34,30 +35,103 @@ type DatastoreData = Cell[][];
  *   ["Alice", 30],
  *   ["Bob", null],
  * ];
- * const rows = tableToObjects("ds_123", headers, data);
+ * const rows = matrixToObjects("ds_123", headers, data);
  * // [
  * //   { datastoreId: "ds_123", name: "Alice", age: 30 },
  * //   { datastoreId: "ds_123", name: "Bob", age: null }
  * // ]
  */
-export const tableToObjects = <T extends Record<string, Cell>>(datastoreId: string, headers: string[], data: DatastoreData): T[] => {
-  const result: T[] = [];
+export const matrixToObjects = <T extends Record<string, Cell>>(
+    datastoreId: string,
+    headers: string[],
+    data: DatastoreData,
+): T[] => {
+    const result: T[] = [];
 
-  for (let i = 1; i < data?.length; i++) {
-    const item: Record<string, Cell> = {};
+    for (let i = 1; i < data?.length; i++) {
+        const item: Record<string, Cell> = {};
 
-    item.datastoreId = datastoreId;
+        item.datastoreId = datastoreId;
 
-    headers.forEach((header: string, index: number) => {
-      item[header] = data[i][index];
-    });
+        headers.forEach((header: string, index: number) => {
+            item[header] = data[i][index];
+        });
 
-    result.push(item as T);
-  }
+        result.push(item as T);
+    }
 
-  return result;
+    return result;
 };
 
+/** A tabular datastore's `data`: an array of rows. An empty array counts, as an empty table. */
+const isMatrix = (data: unknown): data is DatastoreData =>
+    Array.isArray(data) && data.every(Array.isArray);
+
+/**
+ * Converts a datastore as the API returns it into the shape the datastore hooks return.
+ *
+ * A datastore is tabular or JSON, and the API does not say which. `data` is a matrix, an object,
+ * or an array of objects, so only an array whose every element is an array is read as a table.
+ * "Any array" is not enough: the API has returned `[{ … }]` for a JSON datastore, which read as a
+ * matrix lost its content with one element and threw with two. A table's matrix becomes row
+ * objects, with the header row kept as `fields` so that saving back can restore the column
+ * order. JSON passes through untouched.
+ *
+ * A read without its data (`projection: "-data"`) carries nothing to tell the kinds apart and
+ * comes back as an empty table.
+ *
+ * The hooks convert in the request rather than in `select`, so the cache holds objects and an
+ * app patches a row as `{ ...row, ...patch }` rather than by column index. It is exported for an
+ * app that seeds that cache itself.
+ *
+ * With `dataFormat: "matrix"` a table keeps its matrix unconverted, header row included, and still
+ * gets `fields`. JSON is untouched either way.
+ *
+ * @param datastore The datastore as the API returned it.
+ * @param dataFormat `"object"` (default) or `"matrix"`.
+ * @returns A tabular or a `JsonDatastore`, told apart by `format`.
+ */
+export function parseDatastore(datastore: Datastore): ParsedDatastore;
+export function parseDatastore<F extends DatastoreDataFormat>(
+    datastore: Datastore,
+    dataFormat: F,
+): ParsedDatastore<F>;
+export function parseDatastore(
+    datastore: Datastore,
+    dataFormat: DatastoreDataFormat = "object",
+): ParsedDatastore<DatastoreDataFormat> {
+    const { data } = datastore;
+
+    if (data && !isMatrix(data)) {
+        return { ...datastore, format: "json", data: data as JsonDatastore["data"] };
+    }
+
+    const matrix = (data ?? []) as DatastoreData;
+    const fields = (matrix[0] ?? []) as string[];
+
+    if (dataFormat === "matrix") {
+        return { ...datastore, format: "table", fields, data: matrix };
+    }
+
+    return {
+        ...datastore,
+        format: "table",
+        fields,
+        data: matrixToObjects(datastore.id, fields, matrix),
+    };
+}
+
+/**
+ * Narrows a datastore to a tabular one, whose `data` is rows. For a `select` over a list that
+ * may mix kinds: `datastores.filter(isTableDatastore).flatMap((d) => d.data)`.
+ *
+ * @param datastore A datastore as the hooks return it.
+ * @returns True for a tabular datastore.
+ */
+export const isTableDatastore = <D extends ParsedDatastore<DatastoreDataFormat>>(
+    datastore: D,
+): datastore is Extract<D, { format: "table" }> => datastore.format === "table";
+
 /**
  * Converts an array of objects into a datastore table (2D array).
  *
@@ -66,7 +140,8 @@ export const tableToObjects = <T extends Record<string, Cell>>(datastoreId: stri
  * - For each object in `data`, creates a row by mapping `headers` to values in the object.
  * - If a header is missing in an object, the corresponding cell is set to `null`.
  *
- * @template T A record type whose values are compatible with `Cell` (string | number | null).
+ * Takes rows as the datastore hooks hand them over (`AnyRecord`): a value that is not a cell is
+ * written as it is, since the row came from a matrix in the first place.
  *
  * @param headers Column names (and output table header row).
  * @param data Array of objects to convert into rows.
@@ -77,7 +152,7 @@ export const tableToObjects = <T extends Record<string, Cell>>(datastoreId: stri
  *
  * @example
  * const headers = ["name", "age"];
- * const rows = objectsToTable(headers, [
+ * const rows = objectsToMatrix(headers, [
  *   { name: "Alice", age: 30 },
  *   { name: "Bob" }, // age missing -> null
  * ]);
@@ -87,73 +162,51 @@ export const tableToObjects = <T extends Record<string, Cell>>(datastoreId: stri
  * //   ["Bob", null]
  * // ]
  */
-export const objectsToTable = <T extends Record<string, Cell>>(headers: string[] ,data: T[]): DatastoreData => {
-  const rows: DatastoreData = data.map((d) => headers.map<Cell>((h) => d[h as string] ?? null));
+export const objectsToMatrix = <T extends AnyRecord = AnyRecord>(
+    headers: string[],
+    data: T[],
+): DatastoreData => {
+    // Built into one array: mapping the rows and then spreading them after the header copied the
+    // whole list a second time. The header is copied: a caller's `headers` is often a datastore's
+    // `fields`, held in the query cache, and renaming a column in the matrix renamed it there too.
+    const matrix: DatastoreData = [headers.slice()];
 
-  return [headers, ...rows];
+    for (const row of data)
+        matrix.push(headers.map<Cell>((header) => (row[header] ?? null) as Cell));
+
+    return matrix;
 };
 
 /**
- * Flattens multiple datastore row arrays into a single array.
- *
- * This is typically used after fetching multiple datastores, where each datastore is
- * represented as `AnyRecord[]` (i.e., an array of row objects).
+ * The matrix of a tabular datastore, however the hook read it. Code that saves or exports a
+ * datastore calls this without knowing the `dataFormat` it was read with: a matrix read is
+ * copied, an object read is rebuilt in the datastore's own column order (`fields`), without the
+ * `datastoreId` the SDK adds to each row, and with any patch applied to the rows.
  *
- * @param datastores A list of datastores, each represented as an array of row objects.
+ * Either way the result is a new matrix the caller owns and may edit before saving. A matrix
+ * read's `data` is the matrix in the query cache, and handing that back made an edit change what
+ * every screen reading the entry sees.
  *
- * @returns A single array containing all rows from all datastores, in the same order.
+ * Do not save the result of a read that projected `data` away (`projection: "-data"`): it comes
+ * back as an empty table, indistinguishable from a real one, and saving it would empty the
+ * datastore.
  *
- * @example
- * const merged = mergeDatastores([
- *   [{ datastoreId: "a", x: 1 }],
- *   [{ datastoreId: "b", x: 2 }, { datastoreId: "b", x: 3 }],
- * ]);
- * // [{...}, {...}, {...}]
+ * @param datastore A tabular datastore as the hooks return it (narrow with `isTableDatastore`).
+ * @returns The matrix, header row first.
  */
-export const mergeDatastores = (datastores: AnyRecord[][]): AnyRecord[] => {
-  const result: AnyRecord[] = [];
+export const toDatastoreMatrix = (
+    datastore: Extract<ParsedDatastore<DatastoreDataFormat>, { format: "table" }>,
+): DatastoreData => {
+    const { data, fields } = datastore;
 
-  datastores.forEach((datastore: AnyRecord[]) => {
-    result.push(...datastore);
-  });
+    if (data.length === 0) return fields.length > 0 ? [fields.slice()] : [];
 
-  return result;
+    // The first row is enough: the SDK built this `data`, so it is all rows or all objects. The
+    // full `isMatrix` scan guards the API's data, and here it would only walk every row for nothing.
+    // A row-by-row copy is a full copy: a matrix is two levels deep and its cells are primitives.
+    // `structuredClone` would do the same about 8 times slower (147 ms against 18 ms for 100,000
+    // rows of 10 cells), paying for cycles and special types a datastore matrix never holds.
+    return Array.isArray(data[0])
+        ? (data as DatastoreData).map((row) => row.slice())
+        : objectsToMatrix(fields, data as AnyRecord[]);
 };
-
-/**
- * buildDatastoreProps
- *
- * Extracts and maps the metadata properties of a `Datastore` into a plain object
- * for UI usage, discarding raw data rows.
- *
- * - `header` is derived from `datastore.data?.[0]` (the first row of the data matrix),
- *   which is expected to contain the column names. Falls back to `[]` if not present.
- *
- * @param {Datastore} datastore - The source datastore object.
- * @returns Metadata object with the datastore's descriptive properties and header.
- *
- * @example
- * const meta = buildDatastoreProps(datastore);
- * // {
- * //   name: "my-datastore",
- * //   workspace: "ws-1",
- * //   header: ["col1", "col2"],
- * //   ...
- * // }
- */
-export const buildDatastoreProps = (datastore: Datastore) => {
-    return {
-        name: datastore.name,
-        date: datastore.date,
-        version: datastore.version,
-        description: datastore.description,
-        tags: datastore.tags,
-        link_uid: datastore.link_uid,
-        workspace: datastore.workspace,
-        date_time: datastore.date_time,
-        created: datastore.created,
-        updated: datastore.updated,
-        level: datastore.level,
-        header: datastore.data?.[0] || [],
-    };
-};

package/src/lib/file.ts

@@ -0,0 +1,67 @@
+/**
+ * fileToBase64
+ *
+ * The raw base64 `createFile` and `updateFile` take as `data`, from a `File` an `<input
+ * type="file">` gives or any `Blob`. The API stores `data` as given, so the `data:<type>;base64,`
+ * prefix `FileReader` puts in front would be stored as part of the content.
+ *
+ * Read through `FileReader` rather than by encoding the bytes in a loop: the browser encodes
+ * natively, with no binary string built byte by byte for `btoa`. An empty file reads as `data:`
+ * with no comma in Chromium, so a missing comma is empty content — for an empty file only, as
+ * a file with content read that way would otherwise be uploaded empty.
+ *
+ * @param blob - The file.
+ * @returns The content as base64, without a prefix.
+ */
+export const fileToBase64 = (blob: Blob): Promise<string> =>
+    new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => {
+            const dataUrl = String(reader.result);
+            const comma = dataUrl.indexOf(",");
+            if (comma !== -1) {
+                resolve(dataUrl.slice(comma + 1));
+            } else if (blob.size === 0) {
+                resolve("");
+            } else {
+                reject(new Error("Unable to read the file: it read as a data URL with no content"));
+            }
+        };
+        reader.onerror = () => reject(reader.error ?? new Error("Unable to read the file"));
+        reader.readAsDataURL(blob);
+    });
+
+/**
+ * base64ToBlob
+ *
+ * A file's content, as the API returns it in `data`, decoded into a `Blob` byte for byte: to work
+ * on the bytes in code, such as parsing a CSV or unzipping. Not to show the file — the app page's
+ * CSP blocks a `blob:` frame, image or media; use the file's own `url` — and it decodes
+ * synchronously, a byte at a time, so a file of several megabytes is better read through it.
+ *
+ * Without content — a file read without `withData: true` — it warns and gives an empty blob:
+ * `atob(null)` decodes the text "null", three bytes of garbage that would pass for the file.
+ *
+ * @param data - The content as base64, as the hooks return it with `withData: true`.
+ * @param contentType - The file's `content_type`, which becomes the blob's `type`.
+ * @returns The content.
+ * @throws {Error} If `data` is not raw base64.
+ */
+export const base64ToBlob = (data: string | null | undefined, contentType: string): Blob => {
+    if (data == null) {
+        console.warn(
+            "[apps-sdk] base64ToBlob: the file came without its content; read it with withData: true.",
+        );
+        return new Blob([], { type: contentType });
+    }
+
+    let binary: string;
+    try {
+        binary = atob(data);
+    } catch (error) {
+        throw new Error("The file's data is not raw base64", { cause: error });
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+    return new Blob([bytes], { type: contentType });
+};