chore: Improve ApiClient class (#12720)

* refactor: Decouple ApiClient from auth store and document its public surface

Move logout policy out of the transport layer: ApiClient now notifies a
registered handler on unauthenticated responses (401 / suspended 403) instead
of calling stores.auth.logout directly, breaking the AuthStore -> client ->
stores import cycle. AuthStore owns the logout flags and registers the handler.

Also add JSDoc across the public surface (setShareId, fetch, get, post, client).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor: Extend request deduplication to PUT via shared helper

Extract the in-flight dedup logic into a private deduplicate() helper and route
both post() and the new put() through it. The dedup key now includes the HTTP
method so a POST and PUT to the same path can't collide. Multipart uploads
continue to bypass deduplication.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Improve types

* refactor: Improve ApiClient type safety and address review feedback

- Add a Method union ("GET" | "POST" | "PUT") for fetch/deduplicate, replacing
  the loose string type. Narrowed to methods whose bodies are actually
  serialized, so callers aren't given false support for PATCH/DELETE.
- Type previously implicit-any locals (modifiedPath, urlToFetch, isJson).
- Extract an ApiErrorResponse interface for the parsed error payload.
- Register the unauthorized handler before fetchAuth() so a 401 on the initial
  auth request triggers the logout policy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom MoorandClaude Opus 4.8 authored and GitHub committed 2026-06-16 22:28:22 -04:00
1 parent 62d5c25bd3
commit 061aee0225
3 files changed
+123 -29

No files matched your search

+7
View File
@@ -92,6 +92,13 @@ export default class AuthStore extends Store<Team> {
const data: PersistedData = Storage.get(this.name) || {};
this.rehydrate(data);
client.setUnauthorizedHandler((reason) =>
reason === "user_suspended"
? this.logout({ savePath: false, revokeToken: false, clearCache: true })
: this.logout({ savePath: true, revokeToken: false, clearCache: false })
);
void this.fetchAuth();
// persists this entire store to localstorage whenever any keys are changed
+115 -29
View File
@@ -6,7 +6,6 @@ import type { JSONObject } from "@shared/types";
import { Scope } from "@shared/types";
import { version } from "../../package.json";
import env from "~/env";
import stores from "~/stores";
import Logger from "./Logger";
import download from "./download";
import {
@@ -31,6 +30,22 @@ type Options = {
baseUrl?: string;
};
/** An HTTP method supported by the API client. */
type Method = "GET" | "POST" | "PUT";
/** Shape of an error payload returned by the API. */
interface ApiErrorResponse {
message?: string;
error?: string;
data?: Record<string, unknown>;
}
/** Reason the server rejected a request as unauthenticated. */
export type UnauthorizedReason = "unauthorized" | "user_suspended";
/** Handler invoked when a request is rejected as unauthenticated. */
type UnauthorizedHandler = (reason: UnauthorizedReason) => void | Promise<void>;
interface FetchOptions {
download?: boolean;
retry?: boolean;
@@ -46,29 +61,60 @@ class ApiClient {
shareId?: string;
/** Map of in-flight POST requests for deduplication, keyed by path + body. */
/** Map of in-flight requests for deduplication, keyed by method + path + body. */
// oxlint-disable-next-line no-explicit-any
private inflightRequests = new Map<string, Promise<any>>();
private onUnauthorized?: UnauthorizedHandler;
constructor(options: Options = {}) {
this.baseUrl = options.baseUrl || "/api";
}
/**
* Sets the share identifier appended to subsequent requests, used to
* authenticate access to publicly shared documents.
*
* @param shareId the share identifier, or undefined to clear it.
*/
setShareId = (shareId: string | undefined) => {
this.shareId = shareId;
};
/**
* Registers a handler invoked when a request is rejected as unauthenticated
* (a 401, or a 403 indicating the user was suspended). Used to keep
* session/logout policy out of the transport layer.
*
* @param handler the handler to invoke.
*/
setUnauthorizedHandler = (handler: UnauthorizedHandler) => {
this.onUnauthorized = handler;
};
/**
* Performs an HTTP request against the API, handling serialization, headers,
* CSRF, retries, and error mapping.
*
* @param path the request path, relative to the base URL or an absolute URL.
* @param method the HTTP method to use.
* @param data the request payload, sent as a query string for GET requests
* and as a JSON or multipart body otherwise.
* @param options additional request options.
* @returns the parsed JSON response, or undefined for downloads and empty responses.
* @throws {RequestError} if the response status indicates failure.
*/
// oxlint-disable-next-line no-explicit-any
fetch = async <T = any>(
path: string,
method: string,
method: Method,
data: JSONObject | FormData | undefined,
options: FetchOptions = {}
): Promise<T> => {
let body: string | FormData | undefined;
let modifiedPath;
let urlToFetch;
let isJson;
let modifiedPath: string | undefined;
let urlToFetch: string;
let isJson = false;
if (this.shareId) {
if (data instanceof FormData) {
@@ -122,9 +168,7 @@ class ApiClient {
};
// Add CSRF token to headers for mutating requests
const isModifyingRequest = ["POST", "PUT", "PATCH", "DELETE"].includes(
method
);
const isModifyingRequest = method === "POST" || method === "PUT";
const canAccessWithReadOnly = AuthenticationHelper.canAccess(path, [
Scope.Read,
]);
@@ -182,14 +226,10 @@ class ApiClient {
return response.json();
}
// Handle 401, log out user
// Handle 401, notify session owner to log out
if (response.status === 401) {
if (!this.shareId) {
await stores.auth.logout({
savePath: true,
clearCache: false,
revokeToken: false,
});
await this.onUnauthorized?.("unauthorized");
}
throw new AuthorizationError();
}
@@ -208,14 +248,10 @@ class ApiClient {
}
// Handle failed responses
const error: {
message?: string;
error?: string;
data?: Record<string, unknown>;
} = {};
const error: ApiErrorResponse = {};
try {
const parsed = await response.json();
const parsed: ApiErrorResponse = await response.json();
error.message = parsed.message || "";
error.error = parsed.error;
error.data = parsed.data;
@@ -238,11 +274,7 @@ class ApiClient {
if (response.status === 403) {
if (error.error === "user_suspended") {
await stores.auth.logout({
savePath: false,
revokeToken: false,
clearCache: true,
});
await this.onUnauthorized?.("user_suspended");
}
if (error.error === "csrf_error") {
@@ -282,6 +314,14 @@ class ApiClient {
throw err;
};
/**
* Performs a GET request against the API.
*
* @param path the request path, relative to the base URL or an absolute URL.
* @param data the data serialized into the query string.
* @param options additional request options.
* @returns the parsed JSON response.
*/
// oxlint-disable-next-line no-explicit-any
get = <T = any>(
path: string,
@@ -289,23 +329,68 @@ class ApiClient {
options?: FetchOptions
) => this.fetch<T>(path, "GET", data, options);
/**
* Performs a POST request against the API. Identical in-flight requests are
* deduplicated and share a single response, except for multipart uploads.
*
* @param path the request path, relative to the base URL or an absolute URL.
* @param data the request payload, sent as a JSON or multipart body.
* @param options additional request options.
* @returns the parsed JSON response.
*/
// oxlint-disable-next-line no-explicit-any
post = <T = any>(
path: string,
data?: JSONObject | FormData,
options?: FetchOptions
): Promise<T> => this.deduplicate<T>(path, "POST", data, options);
/**
* Performs a PUT request against the API. Identical in-flight requests are
* deduplicated and share a single response, except for multipart uploads.
*
* @param path the request path, relative to the base URL or an absolute URL.
* @param data the request payload, sent as a JSON or multipart body.
* @param options additional request options.
* @returns the parsed JSON response.
*/
// oxlint-disable-next-line no-explicit-any
put = <T = any>(
path: string,
data?: JSONObject | FormData,
options?: FetchOptions
): Promise<T> => this.deduplicate<T>(path, "PUT", data, options);
/**
* Sends a request, deduplicating identical in-flight requests so concurrent
* callers share a single response. Multipart uploads are never deduplicated.
*
* @param path the request path, relative to the base URL or an absolute URL.
* @param method the HTTP method to use.
* @param data the request payload.
* @param options additional request options.
* @returns the parsed JSON response.
*/
// oxlint-disable-next-line no-explicit-any
private deduplicate = <T = any>(
path: string,
method: Method,
data?: JSONObject | FormData,
options?: FetchOptions
): Promise<T> => {
if (data instanceof FormData) {
return this.fetch<T>(path, "POST", data, options);
return this.fetch<T>(path, method, data, options);
}
const key = `${path}:${JSON.stringify(data)}:${JSON.stringify(options)}`;
const key = `${method}:${path}:${JSON.stringify(data)}:${JSON.stringify(
options
)}`;
const inflight = this.inflightRequests.get(key);
if (inflight) {
return inflight;
}
const promise = this.fetch<T>(path, "POST", data, options).finally(() => {
const promise = this.fetch<T>(path, method, data, options).finally(() => {
this.inflightRequests.delete(key);
});
this.inflightRequests.set(key, promise);
@@ -313,4 +398,5 @@ class ApiClient {
};
}
/** Shared API client instance configured against the default base URL. */
export const client = new ApiClient();
+1
View File
@@ -2,6 +2,7 @@
import { vi } from "vitest";
export const client = {
setUnauthorizedHandler: vi.fn(),
post: vi.fn(() =>
Promise.resolve({
data: {