@servora/client 0.0.2

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Kratos 错误解析工具
+ *
+ * Kratos 统一错误格式：{ code, reason, message, metadata? }
+ * 所有使用 protoc-gen-go-errors 生成的服务均输出此格式。
+ */
+import type { ApiError } from './request.js';
+export interface KratosErrorBody {
+    code: number;
+    reason: string;
+    message: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * 从 ApiError 中提取 Kratos 结构化错误体。
+ * 非 HTTP 错误、或响应体不符合格式时返回 null。
+ */
+export declare function parseKratosError(err: ApiError): KratosErrorBody | null;
+/**
+ * 判断 ApiError 是否为指定的 Kratos reason。
+ *
+ * @example
+ * if (isKratosReason(err, 'EMAIL_NOT_VERIFIED')) { ... }
+ */
+export declare function isKratosReason(err: ApiError, reason: string): boolean;
+/**
+ * 提取用户可读的错误消息，含 network / timeout 降级处理。
+ *
+ * @param fallback 当无法提取有效消息时的兜底文案，默认 '操作失败'
+ */
+export declare function kratosMessage(err: ApiError, fallback?: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAE5C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,eAAe,GAAG,IAAI,CAKtE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,SAAS,GAAG,MAAM,CAOtE"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/**
+ * 从 ApiError 中提取 Kratos 结构化错误体。
+ * 非 HTTP 错误、或响应体不符合格式时返回 null。
+ */
+export function parseKratosError(err) {
+    if (err.kind !== 'http' || !err.responseBody)
+        return null;
+    const body = err.responseBody;
+    if (typeof body['reason'] !== 'string')
+        return null;
+    return body;
+}
+/**
+ * 判断 ApiError 是否为指定的 Kratos reason。
+ *
+ * @example
+ * if (isKratosReason(err, 'EMAIL_NOT_VERIFIED')) { ... }
+ */
+export function isKratosReason(err, reason) {
+    return parseKratosError(err)?.reason === reason;
+}
+/**
+ * 提取用户可读的错误消息，含 network / timeout 降级处理。
+ *
+ * @param fallback 当无法提取有效消息时的兜底文案，默认 '操作失败'
+ */
+export function kratosMessage(err, fallback = '操作失败') {
+    if (err.kind === 'network')
+        return '网络连接失败，请检查网络设置';
+    if (err.kind === 'timeout')
+        return '请求超时，请稍后重试';
+    return (parseKratosError(err)?.message ??
+        (err.httpStatus ? `请求失败（HTTP ${err.httpStatus}）` : fallback));
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAa;IAC5C,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY;QAAE,OAAO,IAAI,CAAA;IACzD,MAAM,IAAI,GAAG,GAAG,CAAC,YAAuC,CAAA;IACxD,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACnD,OAAO,IAAkC,CAAA;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAa,EAAE,MAAc;IAC1D,OAAO,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAa,EAAE,QAAQ,GAAG,MAAM;IAC5D,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAA;IACnD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,YAAY,CAAA;IAC/C,OAAO,CACL,gBAAgB,CAAC,GAAG,CAAC,EAAE,OAAO;QAC9B,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAC7D,CAAA;AACH,CAAC"}

package/dist/request.d.ts

@@ -0,0 +1,43 @@
+export type RequestType = {
+    path: string;
+    method: string;
+    body: string | null;
+};
+export type RequestMeta = {
+    service: string;
+    method: string;
+};
+export type RequestHandler = (request: RequestType, meta: RequestMeta) => Promise<unknown>;
+export interface TokenStore {
+    getAccessToken: () => string | null;
+    getRefreshToken: () => string | null;
+    setTokens: (accessToken: string, refreshToken: string) => void;
+    clear: () => void;
+}
+export interface RequestHandlerOptions {
+    baseUrl?: string;
+    tokenStore?: TokenStore;
+    contextHeaders?: (meta: RequestMeta) => Record<string, string>;
+    timeoutMs?: number;
+    onError?: (error: ApiError, meta: RequestMeta) => void;
+    autoRefreshToken?: boolean;
+}
+export type ApiErrorKind = 'http' | 'network' | 'timeout';
+export declare class ApiError extends Error {
+    readonly kind: ApiErrorKind;
+    readonly httpStatus?: number;
+    readonly responseBody?: unknown;
+    readonly service: string;
+    readonly method: string;
+    constructor(opts: {
+        kind: ApiErrorKind;
+        message: string;
+        httpStatus?: number;
+        responseBody?: unknown;
+        service: string;
+        method: string;
+        cause?: unknown;
+    });
+}
+export declare function createRequestHandler(options?: RequestHandlerOptions): RequestHandler;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,WAAW,KACd,OAAO,CAAC,OAAO,CAAC,CAAA;AAErB,MAAM,WAAW,UAAU;IACzB,cAAc,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACnC,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACpC,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9D,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;IACtD,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;AAEzD,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;gBAEX,IAAI,EAAE;QAChB,IAAI,EAAE,YAAY,CAAA;QAClB,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CASF;AASD,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,qBAA0B,GAClC,cAAc,CA+IhB"}

package/dist/request.js

@@ -0,0 +1,146 @@
+/**
+ * @servora/client — 通用 HTTP 请求处理器
+ *
+ * 为 proto 生成的 TypeScript client 提供标准 RequestHandler 实现，包含：
+ * - Bearer token 自动注入
+ * - Token 自动刷新（单例防重复）
+ * - 结构化 ApiError（区分 http / network / timeout）
+ * - 全局 onError 回调（延迟到宏任务，避免与 toast.promise 竞态）
+ *
+ * 消费方需自行安装 peer dependency: ofetch
+ */
+import { ofetch } from 'ofetch';
+export class ApiError extends Error {
+    kind;
+    httpStatus;
+    responseBody;
+    service;
+    method;
+    constructor(opts) {
+        super(opts.message, { cause: opts.cause });
+        this.name = 'ApiError';
+        this.kind = opts.kind;
+        this.httpStatus = opts.httpStatus;
+        this.responseBody = opts.responseBody;
+        this.service = opts.service;
+        this.method = opts.method;
+    }
+}
+function ensureLeadingSlash(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
+const REFRESH_PATH = '/v1/auth/refresh-token';
+const AUTH_PATH_PREFIX = '/v1/auth/';
+export function createRequestHandler(options = {}) {
+    const { baseUrl = '', tokenStore, contextHeaders, timeoutMs = 30_000, onError, autoRefreshToken = false, } = options;
+    let refreshPromise = null;
+    async function tryRefreshToken() {
+        if (!tokenStore)
+            return false;
+        const refreshToken = tokenStore.getRefreshToken();
+        if (!refreshToken)
+            return false;
+        if (refreshPromise)
+            return refreshPromise;
+        refreshPromise = (async () => {
+            try {
+                const data = await ofetch(REFRESH_PATH, {
+                    baseURL: baseUrl,
+                    method: 'POST',
+                    body: { refreshToken },
+                    timeout: timeoutMs,
+                });
+                tokenStore.setTokens(data.accessToken, data.refreshToken);
+                return true;
+            }
+            catch {
+                tokenStore.clear();
+                return false;
+            }
+            finally {
+                refreshPromise = null;
+            }
+        })();
+        return refreshPromise;
+    }
+    async function doRequest(request, meta, isRetry = false) {
+        const headers = {
+            Accept: 'application/json',
+        };
+        if (request.body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (tokenStore) {
+            const token = tokenStore.getAccessToken();
+            if (token) {
+                headers['Authorization'] = `Bearer ${token}`;
+            }
+        }
+        if (contextHeaders) {
+            Object.assign(headers, contextHeaders(meta));
+        }
+        const fetchOptions = {
+            baseURL: baseUrl,
+            method: request.method,
+            headers,
+            timeout: timeoutMs,
+        };
+        if (request.body) {
+            fetchOptions.body = request.body;
+        }
+        try {
+            return await ofetch(ensureLeadingSlash(request.path), fetchOptions);
+        }
+        catch (err) {
+            const fetchError = err;
+            if (fetchError.response) {
+                const status = fetchError.response.status;
+                const body = fetchError.response._data;
+                const apiErr = new ApiError({
+                    kind: 'http',
+                    message: `HTTP ${status} on ${meta.service}.${meta.method}`,
+                    httpStatus: status,
+                    responseBody: body,
+                    service: meta.service,
+                    method: meta.method,
+                    cause: err,
+                });
+                const normalizedPath = ensureLeadingSlash(request.path);
+                if (autoRefreshToken &&
+                    status === 401 &&
+                    !isRetry &&
+                    !normalizedPath.startsWith(AUTH_PATH_PREFIX)) {
+                    const refreshed = await tryRefreshToken();
+                    if (refreshed) {
+                        return doRequest(request, meta, true);
+                    }
+                }
+                // 延迟到宏任务再调 onError，让 promise 链先跑完（含 toast.promise 的 _mark），
+                // 避免全局 handler 与 sonner.promise error callback 同时弹出双重 toast。
+                if (onError) {
+                    const _err = apiErr;
+                    setTimeout(() => onError(_err, meta), 0);
+                }
+                throw apiErr;
+            }
+            const message = (fetchError.message ?? '').toLowerCase();
+            const kind = message.includes('timeout')
+                ? 'timeout'
+                : 'network';
+            const apiErr = new ApiError({
+                kind,
+                message: `${kind} error on ${meta.service}.${meta.method}: ${fetchError.message}`,
+                service: meta.service,
+                method: meta.method,
+                cause: err,
+            });
+            if (onError) {
+                const _err = apiErr;
+                setTimeout(() => onError(_err, meta), 0);
+            }
+            throw apiErr;
+        }
+    }
+    return doRequest;
+}
+//# sourceMappingURL=request.js.map

package/dist/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@servora/client",
+  "version": "0.0.2",
+  "description": "Shared frontend utilities for Servora web apps (request handler, token management, Kratos error parsing)",
+  "type": "module",
+  "exports": {
+    "./request": {
+      "types": "./dist/request.d.ts",
+      "import": "./dist/request.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*_test.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Servora-Kit/servora-web.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/Servora-Kit/servora-web/tree/main/packages/client",
+  "bugs": {
+    "url": "https://github.com/Servora-Kit/servora-web/issues"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "dependencies": {
+    "ofetch": "^1.5.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+/**
+ * Kratos 错误解析工具
+ *
+ * Kratos 统一错误格式：{ code, reason, message, metadata? }
+ * 所有使用 protoc-gen-go-errors 生成的服务均输出此格式。
+ */
+import type { ApiError } from './request.js'
+
+export interface KratosErrorBody {
+  code: number
+  reason: string
+  message: string
+  metadata?: Record<string, string>
+}
+
+/**
+ * 从 ApiError 中提取 Kratos 结构化错误体。
+ * 非 HTTP 错误、或响应体不符合格式时返回 null。
+ */
+export function parseKratosError(err: ApiError): KratosErrorBody | null {
+  if (err.kind !== 'http' || !err.responseBody) return null
+  const body = err.responseBody as Record<string, unknown>
+  if (typeof body['reason'] !== 'string') return null
+  return body as unknown as KratosErrorBody
+}
+
+/**
+ * 判断 ApiError 是否为指定的 Kratos reason。
+ *
+ * @example
+ * if (isKratosReason(err, 'EMAIL_NOT_VERIFIED')) { ... }
+ */
+export function isKratosReason(err: ApiError, reason: string): boolean {
+  return parseKratosError(err)?.reason === reason
+}
+
+/**
+ * 提取用户可读的错误消息，含 network / timeout 降级处理。
+ *
+ * @param fallback 当无法提取有效消息时的兜底文案，默认 '操作失败'
+ */
+export function kratosMessage(err: ApiError, fallback = '操作失败'): string {
+  if (err.kind === 'network') return '网络连接失败，请检查网络设置'
+  if (err.kind === 'timeout') return '请求超时，请稍后重试'
+  return (
+    parseKratosError(err)?.message ??
+    (err.httpStatus ? `请求失败（HTTP ${err.httpStatus}）` : fallback)
+  )
+}

package/src/request.ts

@@ -0,0 +1,227 @@
+/**
+ * @servora/client — 通用 HTTP 请求处理器
+ *
+ * 为 proto 生成的 TypeScript client 提供标准 RequestHandler 实现，包含：
+ * - Bearer token 自动注入
+ * - Token 自动刷新（单例防重复）
+ * - 结构化 ApiError（区分 http / network / timeout）
+ * - 全局 onError 回调（延迟到宏任务，避免与 toast.promise 竞态）
+ *
+ * 消费方需自行安装 peer dependency: ofetch
+ */
+import { ofetch } from 'ofetch'
+import type { FetchOptions } from 'ofetch'
+
+export type RequestType = {
+  path: string
+  method: string
+  body: string | null
+}
+
+export type RequestMeta = {
+  service: string
+  method: string
+}
+
+export type RequestHandler = (
+  request: RequestType,
+  meta: RequestMeta,
+) => Promise<unknown>
+
+export interface TokenStore {
+  getAccessToken: () => string | null
+  getRefreshToken: () => string | null
+  setTokens: (accessToken: string, refreshToken: string) => void
+  clear: () => void
+}
+
+export interface RequestHandlerOptions {
+  baseUrl?: string
+  tokenStore?: TokenStore
+  contextHeaders?: (meta: RequestMeta) => Record<string, string>
+  timeoutMs?: number
+  onError?: (error: ApiError, meta: RequestMeta) => void
+  autoRefreshToken?: boolean
+}
+
+export type ApiErrorKind = 'http' | 'network' | 'timeout'
+
+export class ApiError extends Error {
+  readonly kind: ApiErrorKind
+  readonly httpStatus?: number
+  readonly responseBody?: unknown
+  readonly service: string
+  readonly method: string
+
+  constructor(opts: {
+    kind: ApiErrorKind
+    message: string
+    httpStatus?: number
+    responseBody?: unknown
+    service: string
+    method: string
+    cause?: unknown
+  }) {
+    super(opts.message, { cause: opts.cause })
+    this.name = 'ApiError'
+    this.kind = opts.kind
+    this.httpStatus = opts.httpStatus
+    this.responseBody = opts.responseBody
+    this.service = opts.service
+    this.method = opts.method
+  }
+}
+
+function ensureLeadingSlash(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`
+}
+
+const REFRESH_PATH = '/v1/auth/refresh-token'
+const AUTH_PATH_PREFIX = '/v1/auth/'
+
+export function createRequestHandler(
+  options: RequestHandlerOptions = {},
+): RequestHandler {
+  const {
+    baseUrl = '',
+    tokenStore,
+    contextHeaders,
+    timeoutMs = 30_000,
+    onError,
+    autoRefreshToken = false,
+  } = options
+
+  let refreshPromise: Promise<boolean> | null = null
+
+  async function tryRefreshToken(): Promise<boolean> {
+    if (!tokenStore) return false
+    const refreshToken = tokenStore.getRefreshToken()
+    if (!refreshToken) return false
+
+    if (refreshPromise) return refreshPromise
+
+    refreshPromise = (async () => {
+      try {
+        const data = await ofetch<{
+          accessToken: string
+          refreshToken: string
+        }>(REFRESH_PATH, {
+          baseURL: baseUrl,
+          method: 'POST',
+          body: { refreshToken },
+          timeout: timeoutMs,
+        })
+        tokenStore.setTokens(data.accessToken, data.refreshToken)
+        return true
+      } catch {
+        tokenStore.clear()
+        return false
+      } finally {
+        refreshPromise = null
+      }
+    })()
+
+    return refreshPromise
+  }
+
+  async function doRequest(
+    request: RequestType,
+    meta: RequestMeta,
+    isRetry = false,
+  ): Promise<unknown> {
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+    }
+
+    if (request.body) {
+      headers['Content-Type'] = 'application/json'
+    }
+
+    if (tokenStore) {
+      const token = tokenStore.getAccessToken()
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`
+      }
+    }
+
+    if (contextHeaders) {
+      Object.assign(headers, contextHeaders(meta))
+    }
+
+    const fetchOptions: FetchOptions = {
+      baseURL: baseUrl,
+      method: request.method as FetchOptions['method'],
+      headers,
+      timeout: timeoutMs,
+    }
+
+    if (request.body) {
+      fetchOptions.body = request.body
+    }
+
+    try {
+      return await ofetch(ensureLeadingSlash(request.path), fetchOptions)
+    } catch (err: unknown) {
+      const fetchError = err as {
+        response?: { status: number; _data?: unknown }
+        message?: string
+      }
+
+      if (fetchError.response) {
+        const status = fetchError.response.status
+        const body = fetchError.response._data
+
+        const apiErr = new ApiError({
+          kind: 'http',
+          message: `HTTP ${status} on ${meta.service}.${meta.method}`,
+          httpStatus: status,
+          responseBody: body,
+          service: meta.service,
+          method: meta.method,
+          cause: err,
+        })
+
+        const normalizedPath = ensureLeadingSlash(request.path)
+        if (
+          autoRefreshToken &&
+          status === 401 &&
+          !isRetry &&
+          !normalizedPath.startsWith(AUTH_PATH_PREFIX)
+        ) {
+          const refreshed = await tryRefreshToken()
+          if (refreshed) {
+            return doRequest(request, meta, true)
+          }
+        }
+
+        // 延迟到宏任务再调 onError，让 promise 链先跑完（含 toast.promise 的 _mark），
+        // 避免全局 handler 与 sonner.promise error callback 同时弹出双重 toast。
+        if (onError) {
+          const _err = apiErr
+          setTimeout(() => onError(_err, meta), 0)
+        }
+        throw apiErr
+      }
+
+      const message = (fetchError.message ?? '').toLowerCase()
+      const kind: ApiErrorKind = message.includes('timeout')
+        ? 'timeout'
+        : 'network'
+
+      const apiErr = new ApiError({
+        kind,
+        message: `${kind} error on ${meta.service}.${meta.method}: ${fetchError.message}`,
+        service: meta.service,
+        method: meta.method,
+        cause: err,
+      })
+      if (onError) {
+        const _err = apiErr
+        setTimeout(() => onError(_err, meta), 0)
+      }
+      throw apiErr
+    }
+  }
+
+  return doRequest
+}