feat: manually mirror opencoze's code from bytedance

Change-Id: I09a73aadda978ad9511264a756b2ce51f5761adf

frontend/packages/arch/bot-http/README.md

@@ -0,0 +1,270 @@
+# @coze-arch/bot-http
+
+> Global HTTP client and error handling utilities for Bot Studio web applications
+
+## Project Overview
+
+This package provides a centralized HTTP client solution for the entire Bot Studio web application ecosystem. It offers a pre-configured axios instance with global interceptors, comprehensive error handling, event-driven API error management, and standardized response processing. This package ensures consistent HTTP behavior across all Bot Studio services while providing robust error reporting and handling capabilities.
+
+## Features
+
+- **Pre-configured Axios Instance**: Ready-to-use HTTP client with Bot Studio optimizations
+- **Global Interceptors**: Request/response interceptors for authentication, logging, and error handling
+- **Event-driven Error Management**: Centralized API error event system with custom handlers
+- **Structured Error Types**: Type-safe API error definitions with detailed error information
+- **Authentication Integration**: Built-in support for unauthorized request handling and redirects
+- **Error Reporting**: Automatic error reporting with categorized event tracking
+- **Response Processing**: Standardized response data extraction and error transformation
+
+## Get Started
+
+### Installation
+
+Add this package to your `package.json` dependencies and set it to `workspace:*` version:
+
+```json
+{
+  "dependencies": {
+    "@coze-arch/bot-http": "workspace:*"
+  }
+}
+```
+
+Then run:
+```bash
+rush update
+```
+
+### Basic Usage
+
+#### Using the Axios Instance
+
+```typescript
+import { axiosInstance } from '@coze-arch/bot-http';
+
+// Make HTTP requests
+const response = await axiosInstance.get('/api/users');
+const userData = await axiosInstance.post('/api/users', { name: 'John' });
+
+// The instance is pre-configured with interceptors and error handling
+```
+
+#### Error Handling
+
+```typescript
+import {
+  APIErrorEvent,
+  handleAPIErrorEvent,
+  isApiError,
+  ApiError
+} from '@coze-arch/bot-http';
+
+// Register global error handler
+handleAPIErrorEvent((error: APIErrorEvent) => {
+  console.error('API Error occurred:', error);
+  // Handle error globally (show toast, redirect, etc.)
+});
+
+// Check if error is an API error
+try {
+  await axiosInstance.get('/api/data');
+} catch (error) {
+  if (isApiError(error)) {
+    console.log('API Error Code:', error.code);
+    console.log('API Error Message:', error.msg);
+  }
+}
+```
+
+#### Global Interceptors
+
+```typescript
+import {
+  addGlobalRequestInterceptor,
+  addGlobalResponseInterceptor,
+  removeGlobalRequestInterceptor
+} from '@coze-arch/bot-http';
+
+// Add request interceptor for authentication
+const requestInterceptor = addGlobalRequestInterceptor((config) => {
+  config.headers.Authorization = `Bearer ${getToken()}`;
+  return config;
+});
+
+// Add response interceptor for data processing
+addGlobalResponseInterceptor((response) => {
+  // Process response data
+  return response;
+});
+
+// Remove interceptor when no longer needed
+removeGlobalRequestInterceptor(requestInterceptor);
+```
+
+#### Error Event Management
+
+```typescript
+import {
+  emitAPIErrorEvent,
+  startAPIErrorEvent,
+  stopAPIErrorEvent,
+  clearAPIErrorEvent
+} from '@coze-arch/bot-http';
+
+// Manually emit API error event
+emitAPIErrorEvent({
+  code: '500',
+  msg: 'Internal server error',
+  type: 'custom'
+});
+
+// Control error event handling
+stopAPIErrorEvent();  // Temporarily disable error events
+startAPIErrorEvent(); // Re-enable error events
+clearAPIErrorEvent(); // Clear all error handlers
+```
+
+## API Reference
+
+### Core Components
+
+#### `axiosInstance`
+Pre-configured axios instance with global interceptors and error handling.
+
+```typescript
+import { axiosInstance } from '@coze-arch/bot-http';
+// Use like regular axios instance
+```
+
+#### `ApiError`
+Extended error class for API-specific errors.
+
+```typescript
+class ApiError extends AxiosError {
+  code: string;           // Error code
+  msg: string;           // Error message
+  hasShowedError: boolean; // Whether error has been displayed
+  type: string;          // Error type
+  raw?: any;            // Raw error data
+}
+```
+
+### Error Management
+
+#### Error Event Functions
+```typescript
+// Register error handler
+handleAPIErrorEvent(handler: (error: APIErrorEvent) => void): void
+
+// Remove error handler
+removeAPIErrorEvent(handler: (error: APIErrorEvent) => void): void
+
+// Control error events
+startAPIErrorEvent(): void
+stopAPIErrorEvent(): void
+clearAPIErrorEvent(): void
+
+// Emit custom error
+emitAPIErrorEvent(error: APIErrorEvent): void
+```
+
+#### Error Checking
+```typescript
+// Check if error is API error
+isApiError(error: any): error is ApiError
+```
+
+### Interceptor Management
+
+#### Request Interceptors
+```typescript
+// Add request interceptor
+addGlobalRequestInterceptor(
+  interceptor: (config: AxiosRequestConfig) => AxiosRequestConfig
+): number
+
+// Remove request interceptor
+removeGlobalRequestInterceptor(interceptorId: number): void
+```
+
+#### Response Interceptors
+```typescript
+// Add response interceptor
+addGlobalResponseInterceptor(
+  interceptor: (response: AxiosResponse) => AxiosResponse
+): void
+```
+
+### Error Codes
+
+Built-in error code constants:
+
+```typescript
+enum ErrorCodes {
+  NOT_LOGIN = 700012006,
+  COUNTRY_RESTRICTED = 700012015,
+  COZE_TOKEN_INSUFFICIENT = 702082020,
+  COZE_TOKEN_INSUFFICIENT_WORKFLOW = 702095072,
+}
+```
+
+## Advanced Usage
+
+### Custom Error Handling
+
+```typescript
+import { axiosInstance, ApiError } from '@coze-arch/bot-http';
+
+axiosInstance.interceptors.response.use(
+  response => response,
+  error => {
+    if (error instanceof ApiError) {
+      // Handle specific API errors
+      switch (error.code) {
+        case '401':
+          // Redirect to login
+          break;
+        case '403':
+          // Show permission error
+          break;
+        default:
+          // Generic error handling
+      }
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+### Integration with Web Context
+
+The package automatically integrates with `@coze-arch/web-context` for handling redirects and navigation in unauthorized scenarios.
+
+## Development
+
+### Available Scripts
+
+- `npm run build` - Build the package (no-op, source-only package)
+- `npm run lint` - Run ESLint
+- `npm run test` - Run tests with Vitest
+- `npm run test:cov` - Run tests with coverage
+
+### Project Structure
+
+```
+src/
+├── axios.ts           # Axios instance configuration and interceptors
+├── api-error.ts       # API error classes and utilities
+├── eventbus.ts        # Error event management system
+└── index.ts          # Main exports
+```
+
+## Dependencies
+
+This package depends on:
+- `@coze-arch/logger` - Logging utilities for error reporting
+- `axios` - HTTP client library
+
+## License
+
+Apache-2.0

frontend/packages/arch/bot-http/__tests__/api-error.test.ts

@@ -0,0 +1,160 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import { type AxiosError, AxiosHeaders } from 'axios';
+import { logger } from '@coze-arch/logger';
+
+import {
+  reportHttpError,
+  ReportEventNames,
+  ApiError,
+  isApiError,
+} from '../src/api-error';
+
+vi.mock('@coze-arch/logger', () => ({
+  logger: {
+    info: vi.fn(),
+    persist: {
+      error: vi.fn(),
+    },
+  },
+}));
+describe('reportHttpError', () => {
+  const error: AxiosError = {
+    response: {
+      data: {
+        code: '500',
+        msg: 'Internal Server Error',
+      },
+      status: 500,
+      statusText: '',
+      config: {
+        headers: new AxiosHeaders(),
+      },
+      headers: {
+        'x-tt-logid': '1234567890',
+      },
+    },
+    config: {
+      method: 'GET',
+      headers: new AxiosHeaders(),
+      url: '/users',
+    },
+    message: 'Request failed with status code 500',
+    name: 'AxiosError',
+    isAxiosError: true,
+    toJSON: () => ({}),
+  };
+  it('if no response data, should report http error', () => {
+    const eventName = ReportEventNames.ApiError;
+    const noResponseError: AxiosError = {
+      response: {
+        data: {
+          code: '',
+        },
+        status: 500,
+        statusText: '',
+        config: {
+          headers: new AxiosHeaders(),
+        },
+        headers: {
+          'x-tt-logid': '1234567890',
+        },
+      },
+      config: {
+        method: 'GET',
+        headers: new AxiosHeaders(),
+        url: '/users',
+      },
+      message: 'Request failed with status code 500',
+      name: 'AxiosError',
+      isAxiosError: true,
+      toJSON: () => ({}),
+    };
+
+    reportHttpError(eventName, noResponseError);
+
+    expect(logger.persist.error).toBeCalledWith({
+      eventName,
+      error: noResponseError,
+      meta: {
+        message: error.message,
+        name: error.name,
+        httpStatusCode: '500',
+        httpMethod: 'GET',
+        urlPath: '/users',
+        logId: '1234567890',
+        customErrorCode: '',
+        customErrorMsg: '',
+      },
+    });
+  });
+
+  it('should report http error', () => {
+    const eventName = ReportEventNames.ApiError;
+
+    reportHttpError(eventName, error);
+
+    expect(logger.persist.error).toHaveBeenCalledWith({
+      eventName,
+      error,
+      meta: {
+        message: error.message,
+        name: error.name,
+        httpStatusCode: '500',
+        httpMethod: 'GET',
+        urlPath: '/users',
+        logId: '1234567890',
+        customErrorCode: '500',
+        customErrorMsg: 'Internal Server Error',
+      },
+    });
+  });
+
+  it('should handle error when reporting http catch', () => {
+    const eventName = ReportEventNames.ApiError;
+
+    (logger.persist.error as any).mockImplementation(() => {
+      throw new Error('Failed to persist error');
+    });
+
+    expect(() => {
+      reportHttpError(eventName, error);
+    }).toThrowError('Failed to persist error');
+  });
+});
+
+describe('isApiError', () => {
+  it('should return true if error is an instance of ApiError', () => {
+    const error = new ApiError('500', 'Internal Server Error', {
+      data: {},
+      status: 500,
+      statusText: 'Internal Server Error',
+      headers: new AxiosHeaders(),
+      config: {
+        headers: new AxiosHeaders(),
+      },
+    });
+    const result = isApiError(error);
+    expect(result).toBe(true);
+  });
+
+  it('should return false if error is not an instance of ApiError', () => {
+    const error = new Error('OtherError');
+    const result = isApiError(error);
+    expect(result).toBe(false);
+  });
+});

frontend/packages/arch/bot-http/__tests__/axios.test.ts

@@ -0,0 +1,249 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import MockAdapter from 'axios-mock-adapter';
+import { AxiosError, isAxiosError } from 'axios';
+import { redirect } from '@coze-arch/web-context';
+
+import { emitAPIErrorEvent } from '../src/eventbus';
+import { axiosInstance } from '../src/axios'; // your import path
+import { ApiError, reportHttpError, ReportEventNames } from '../src/api-error';
+
+// This sets the mock adapter on the default instance
+const mock = new MockAdapter(axiosInstance);
+
+vi.mock('@coze-arch/logger', () => ({
+  logger: {
+    info: vi.fn(),
+    persist: {
+      error: vi.fn(),
+    },
+  },
+}));
+
+vi.mock('../src/eventbus', () => ({
+  emitAPIErrorEvent: vi.fn(),
+  APIErrorEvent: {
+    UNAUTHORIZED: 'unauthorized',
+    COUNTRY_RESTRICTED: 'countryRestricted',
+    COZE_TOKEN_INSUFFICIENT: 'cozeTokenInsufficient',
+  },
+}));
+vi.mock('../src/api-error', async () => {
+  const actual = (await vi.importActual('../src/api-error')) as any;
+
+  return {
+    ...actual,
+    reportHttpError: vi.fn(),
+  };
+});
+
+vi.mock('@coze-arch/web-context', () => ({
+  redirect: vi.fn(),
+}));
+
+describe('axiosInstance', () => {
+  beforeEach(() => {
+    mock.reset();
+    vi.clearAllMocks();
+  });
+  it('should fetch users', async () => {
+    // Mock any GET request to /users
+    // arguments for reply are (status, data, headers)
+    mock.onGet('/users').reply(200, {
+      code: 0,
+      data: { users: [{ id: 1, name: 'John Smith' }] },
+    });
+
+    const response = await axiosInstance.get('/users');
+
+    expect(response.status).toBe(200);
+    expect(response.data.data.users[0].id).toBe(1);
+  });
+
+  it('should throw api errors if code not equal to zero', async () => {
+    mock.onGet('/users').reply(200, {
+      code: 1,
+      msg: 'fake error',
+    });
+
+    await expect(() => axiosInstance.get('/users')).rejects.toThrowError(
+      ApiError,
+    );
+    expect(reportHttpError).toBeCalledWith(
+      ReportEventNames.ApiError,
+      expect.any(ApiError),
+    );
+  });
+
+  it('should emit special events when not login', async () => {
+    mock.onGet('/users').reply(200, {
+      // 700012006 => not login
+      code: 700012006,
+      msg: 'fake error',
+    });
+
+    await expect(axiosInstance.get('/users')).rejects.toThrow(ApiError);
+    expect(emitAPIErrorEvent).toBeCalledWith(
+      'unauthorized',
+      expect.any(ApiError),
+    );
+    expect(reportHttpError).toBeCalledWith(
+      ReportEventNames.ApiError,
+      expect.any(ApiError),
+    );
+
+    mock.onGet('/users2').reply(200, {
+      // 700012015 => COUNTRY_RESTRICTED
+      code: 700012015,
+      msg: 'fake error',
+    });
+
+    await expect(() => axiosInstance.get('/users2')).rejects.toThrowError(
+      ApiError,
+    );
+    expect(emitAPIErrorEvent).toBeCalledWith(
+      'countryRestricted',
+      expect.any(ApiError),
+    );
+    expect(reportHttpError).toBeCalledWith(
+      ReportEventNames.ApiError,
+      expect.any(ApiError),
+    );
+
+    mock.onGet('/users4').reply(200, {
+      // 702082020 => COZE_TOKEN_INSUFFICIENT
+      code: 702082020,
+      msg: 'fake error',
+    });
+
+    await expect(axiosInstance.get('/users4')).rejects.toThrow(ApiError);
+    expect(emitAPIErrorEvent).toBeCalledWith(
+      'cozeTokenInsufficient',
+      expect.any(ApiError),
+    );
+    expect(reportHttpError).toBeCalledWith(
+      ReportEventNames.ApiError,
+      expect.any(ApiError),
+    );
+
+    mock.onGet('/users5').reply(200, {
+      // 702095072 => COZE_TOKEN_INSUFFICIENT
+      code: 702095072,
+      msg: 'fake error',
+    });
+
+    await expect(axiosInstance.get('/users5')).rejects.toThrow(ApiError);
+    expect(emitAPIErrorEvent).toBeCalledWith(
+      'cozeTokenInsufficient',
+      expect.any(ApiError),
+    );
+    expect(reportHttpError).toBeCalledWith(
+      ReportEventNames.ApiError,
+      expect.any(ApiError),
+    );
+  });
+
+  it('should logger error when network error', async () => {
+    mock.onGet('/users3').networkError();
+    try {
+      await expect(() => axiosInstance.get('/users3')).rejects.toThrow(Error);
+    } catch (error) {
+      expect(isAxiosError(error)).toBe(true);
+      expect(reportHttpError).toBeCalledWith(
+        ReportEventNames.NetworkError,
+        expect.any(AxiosError),
+      );
+    }
+  });
+
+  it('should handle unauthorized response', async () => {
+    mock.onGet('/users').reply(401, {
+      code: 401,
+      data: {
+        redirect_uri: '/login',
+      },
+      message: 'Unauthorized',
+    });
+
+    await expect(() => axiosInstance.get('/users')).rejects.toThrowError(Error);
+    expect(reportHttpError).toBeCalledWith(
+      ReportEventNames.NetworkError,
+      expect.any(Error),
+    );
+
+    expect(redirect).toBeCalledWith('/login');
+  });
+
+  it('should set content-type header for post request', async () => {
+    mock.onPost('/api/mock').reply(200, {
+      code: 0,
+      data: {},
+    });
+    const response = await axiosInstance.post('/api/mock');
+    expect(response.config.headers['Content-Type']).toBe('application/json');
+    expect(response.config.data).toBe(JSON.stringify({}));
+  });
+  it('should set content-type header for get request', async () => {
+    mock.onGet('/api/mock').reply(200, {
+      code: 0,
+      data: {},
+    });
+    const response = await axiosInstance.request({
+      url: '/api/mock',
+      method: 'GET',
+    });
+    expect(response.config.headers['Content-Type']).toBe('application/json');
+  });
+  it("won't override exist data", async () => {
+    mock.onPost('/api/mock').reply(200, {
+      code: 0,
+      data: {},
+    });
+    const response = await axiosInstance.post('/api/mock', { data: '1' });
+    expect(response.config.headers['Content-Type']).toBe('application/json');
+    expect(response.config.data).toBe(JSON.stringify({ data: '1' }));
+  });
+  it("won't override exist content-type header", async () => {
+    mock.onPost('/api/mock').reply(200, {
+      code: 0,
+      data: {},
+    });
+    const response = await axiosInstance.post('/api/mock', undefined, {
+      headers: {
+        'Content-Type': 'text/plain',
+      },
+    });
+    expect(response.config.headers['Content-Type']).toBe('text/plain');
+  });
+  it('should set handle object header', async () => {
+    mock.onPost('/api/mock').reply(200, {
+      code: 0,
+      data: {},
+    });
+
+    axiosInstance.interceptors.request.use(config => {
+      // @ts-expect-error just for test
+      config.headers = { 'Content-Type': 'application/json' };
+      return config;
+    });
+    const response = await axiosInstance.request({
+      url: '/api/mock',
+      method: 'POST',
+    });
+    expect(response.config.headers['Content-Type']).toBe('application/json');
+  });
+});

frontend/packages/arch/bot-http/__tests__/eventbus.test.ts

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import {
+  APIErrorEvent,
+  clearAPIErrorEvent,
+  emitAPIErrorEvent,
+  handleAPIErrorEvent,
+  removeAPIErrorEvent,
+  startAPIErrorEvent,
+  stopAPIErrorEvent,
+} from '../src/eventbus';
+
+const mockEmit = vi.fn();
+const mockOn = vi.fn();
+const mockOff = vi.fn();
+const mockStart = vi.fn();
+const mockStop = vi.fn();
+const mockClear = vi.fn();
+
+vi.mock('@coze-arch/web-context', () => ({
+  GlobalEventBus: class MockGlobalEventBus {
+    static create() {
+      return new MockGlobalEventBus();
+    }
+    emit() {
+      mockEmit();
+    }
+    on() {
+      mockOn();
+    }
+    off() {
+      mockOff();
+    }
+    start() {
+      mockStart();
+    }
+    stop() {
+      mockStop();
+    }
+    clear() {
+      mockClear();
+    }
+  },
+}));
+
+describe('eventbus', () => {
+  test('emitAPIErrorEvent', () => {
+    emitAPIErrorEvent(APIErrorEvent.COUNTRY_RESTRICTED);
+    expect(mockEmit).toHaveBeenCalled();
+  });
+
+  test('handleAPIErrorEvent', () => {
+    handleAPIErrorEvent(APIErrorEvent.COUNTRY_RESTRICTED, vi.fn());
+    expect(mockOn).toHaveBeenCalled();
+  });
+
+  test('removeAPIErrorEvent', () => {
+    removeAPIErrorEvent(APIErrorEvent.COUNTRY_RESTRICTED, vi.fn());
+    expect(mockOff).toHaveBeenCalled();
+  });
+
+  test('stopAPIErrorEvent', () => {
+    stopAPIErrorEvent();
+    expect(mockStop).toHaveBeenCalled();
+  });
+
+  test('startAPIErrorEvent', () => {
+    startAPIErrorEvent();
+    expect(mockStart).toHaveBeenCalled();
+  });
+
+  test('clearAPIErrorEvent', () => {
+    clearAPIErrorEvent();
+    expect(mockClear).toHaveBeenCalled();
+  });
+});

frontend/packages/arch/bot-http/__tests__/global-interceptor.test.ts

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import MockAdapter from 'axios-mock-adapter';
+
+vi.mock('@coze-arch/logger', () => ({
+  logger: {
+    info: vi.fn(),
+    persist: {
+      error: vi.fn(),
+    },
+  },
+}));
+
+vi.mock('../src/eventbus', () => ({
+  emitAPIErrorEvent: vi.fn(),
+  APIErrorEvent: {
+    UNAUTHORIZED: 'unauthorized',
+    COUNTRY_RESTRICTED: 'countryRestricted',
+    COZE_TOKEN_INSUFFICIENT: 'cozeTokenInsufficient',
+  },
+}));
+vi.mock('../src/api-error', async () => {
+  const actual = (await vi.importActual('../src/api-error')) as any;
+
+  return {
+    ...actual,
+    reportHttpError: vi.fn(),
+  };
+});
+
+vi.mock('@coze-arch/web-context', () => ({
+  redirect: vi.fn(),
+}));
+
+describe('globalRequestInterceptor', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+  });
+
+  it('should run intercept logic', async () => {
+    const { addGlobalRequestInterceptor, axiosInstance } =
+      await vi.importActual('../src/axios');
+    // This sets the mock adapter on the default instance
+    const mock = new MockAdapter(axiosInstance);
+
+    addGlobalRequestInterceptor(config => {
+      config.headers.set('x-tt-foo', 'bar');
+      return config;
+    });
+
+    mock.onGet('/users').reply(200, {
+      code: 0,
+      data: { users: [{ id: 1, name: 'John Smith' }] },
+    });
+
+    const response = await axiosInstance.get('/users');
+
+    expect(response.config.headers['x-tt-foo']).toEqual('bar');
+  });
+
+  it('run extra interceptor logic', async () => {
+    const { addGlobalResponseInterceptor, axiosInstance } =
+      await vi.importActual('../src/axios');
+    const mock = new MockAdapter(axiosInstance);
+    const removeInterceptor = addGlobalResponseInterceptor(obj => {
+      obj.data.data.oh = 2;
+      return obj;
+    });
+
+    mock.onGet('/oh').reply(200, {
+      code: 0,
+      data: { oh: 1 },
+    });
+    const response = await axiosInstance.get('/oh');
+    expect(response.data.data.oh).toBe(2);
+
+    removeInterceptor();
+    const response2 = await axiosInstance.get('/oh');
+    expect(response2.data.data.oh).toBe(1);
+  });
+
+  it('should support remove interceptors', async () => {
+    const {
+      addGlobalRequestInterceptor,
+      removeGlobalRequestInterceptor,
+      axiosInstance,
+    } = await vi.importActual('../src/axios');
+    // This sets the mock adapter on the default instance
+
+    const mock = new MockAdapter(axiosInstance);
+    const id = addGlobalRequestInterceptor(config => {
+      config.headers.set('x-tt-foo', 'bar');
+      console.log('wfe', 'wefe');
+      return config;
+    });
+    removeGlobalRequestInterceptor(id);
+
+    mock.onGet('/users').reply(200, {
+      code: 0,
+      data: { users: [{ id: 1, name: 'John Smith' }] },
+    });
+
+    const response = await axiosInstance.get('/users');
+
+    expect(response.config.headers['x-tt-foo']).toBeUndefined();
+  });
+});

frontend/packages/arch/bot-http/config/rush-project.json

@@ -0,0 +1,12 @@
+{
+  "operationSettings": [
+    {
+      "operationName": "test:cov",
+      "outputFolderNames": ["coverage"]
+    },
+    {
+      "operationName": "ts-check",
+      "outputFolderNames": ["./dist"]
+    }
+  ]
+}

frontend/packages/arch/bot-http/eslint.config.js

@@ -0,0 +1,7 @@
+const { defineConfig } = require('@coze-arch/eslint-config');
+
+module.exports = defineConfig({
+  packageRoot: __dirname,
+  preset: 'node',
+  rules: {},
+});

frontend/packages/arch/bot-http/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@coze-arch/bot-http",
+  "version": "0.0.1",
+  "description": "Global Context for whole hot studio web app. You should keep using this package instead of call `window.xxx` directly",
+  "author": "fanwenjie.fe@bytedance.com",
+  "main": "./src/index.ts",
+  "scripts": {
+    "build": "exit 0",
+    "lint": "eslint ./ --cache",
+    "test": "NODE_OPTIONS='--max_old_space_size=2048' NODE_ENV=test vitest --run --passWithNoTests",
+    "test:cov": "npm run test -- --coverage"
+  },
+  "dependencies": {
+    "@coze-arch/logger": "workspace:*",
+    "axios": "^1.4.0"
+  },
+  "devDependencies": {
+    "@coze-arch/bot-typings": "workspace:*",
+    "@coze-arch/eslint-config": "workspace:*",
+    "@coze-arch/ts-config": "workspace:*",
+    "@coze-arch/vitest-config": "workspace:*",
+    "@coze-arch/web-context": "workspace:*",
+    "@vitest/coverage-v8": "~3.0.5",
+    "axios-mock-adapter": "^1.22.0",
+    "debug": "^4.3.4",
+    "sucrase": "^3.32.0",
+    "tsconfig-paths": "4.1.0",
+    "vitest": "~3.0.5"
+  },
+  "// deps": "debug@^4.3.4 为脚本自动补齐，请勿改动"
+}
+

frontend/packages/arch/bot-http/src/api-error.ts

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import { AxiosError, type AxiosResponse } from 'axios';
+import { logger } from '@coze-arch/logger';
+
+// 上报事件枚举
+export enum ReportEventNames {
+  NetworkError = 'flow-infra-network-error',
+  ApiError = 'flow-infra-api-error',
+}
+interface ApiErrorOptions {
+  hasShowedError?: boolean;
+}
+
+export class ApiError extends AxiosError {
+  hasShowedError: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public raw?: any;
+  type: string;
+
+  // eslint-disable-next-line max-params
+  constructor(
+    public code: string,
+    public msg: string | undefined,
+    response: AxiosResponse,
+    options: ApiErrorOptions = {},
+  ) {
+    const { hasShowedError = false } = options;
+
+    super(msg, code, response.config, response.request, response);
+    this.name = 'ApiError';
+    this.type = 'Api Response Error';
+    this.hasShowedError = hasShowedError;
+    this.raw = response.data;
+  }
+}
+
+export const isApiError = (error: unknown): error is ApiError =>
+  error instanceof ApiError;
+
+// 上报http错误，apiError&axiosError
+export const reportHttpError = (
+  eventName: ReportEventNames,
+  error: AxiosError,
+) => {
+  try {
+    const { response, config } = error;
+    const {
+      code = '',
+      msg = '',
+      message,
+    } = response?.data as {
+      code?: string;
+      msg?: string;
+      message?: string;
+    };
+    const { status: httpStatusCode, headers } = response || {};
+    const { method: httpMethod, url: urlPath } = config || {};
+    const logId = headers?.['x-tt-logid'];
+    const customErrorCode = String(code);
+    const customErrorMsg = message ?? msg;
+
+    logger.persist.error({
+      eventName,
+      error,
+      meta: {
+        message: error.message,
+        name: error.name,
+        httpStatusCode: String(httpStatusCode),
+        httpMethod,
+        urlPath,
+        logId,
+        customErrorCode,
+        customErrorMsg,
+      },
+    });
+  } catch (e) {
+    logger.persist.error({
+      error: e as Error,
+      message: error.message,
+    });
+  }
+};

frontend/packages/arch/bot-http/src/axios.ts

@@ -0,0 +1,187 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import axios, { type AxiosResponse, isAxiosError } from 'axios';
+import { redirect } from '@coze-arch/web-context';
+import { logger } from '@coze-arch/logger';
+
+import { emitAPIErrorEvent, APIErrorEvent } from './eventbus';
+import { ApiError, reportHttpError, ReportEventNames } from './api-error';
+
+interface UnauthorizedResponse {
+  data: {
+    redirect_uri: string;
+  };
+  code: number;
+  msg: string;
+}
+
+export enum ErrorCodes {
+  NOT_LOGIN = 700012006,
+  COUNTRY_RESTRICTED = 700012015,
+  COZE_TOKEN_INSUFFICIENT = 702082020,
+  COZE_TOKEN_INSUFFICIENT_WORKFLOW = 702095072,
+}
+
+export const axiosInstance = axios.create();
+
+const HTTP_STATUS_COE_UNAUTHORIZED = 401;
+
+type ResponseInterceptorOnFulfilled = (res: AxiosResponse) => AxiosResponse;
+const customInterceptors = {
+  response: new Set<ResponseInterceptorOnFulfilled>(),
+};
+
+axiosInstance.interceptors.response.use(
+  response => {
+    logger.info({
+      namespace: 'api',
+      scope: 'response',
+      message: '----',
+      meta: { response },
+    });
+    const { data = {} } = response;
+
+    // 新增接口返回message字段
+    const { code, msg, message } = data;
+
+    if (code !== 0) {
+      const apiError = new ApiError(String(code), message ?? msg, response);
+
+      switch (code) {
+        case ErrorCodes.NOT_LOGIN: {
+          // @ts-expect-error type safe
+          apiError.config.__disableErrorToast = true;
+          emitAPIErrorEvent(APIErrorEvent.UNAUTHORIZED, apiError);
+          break;
+        }
+        case ErrorCodes.COUNTRY_RESTRICTED: {
+          // @ts-expect-error type safe
+          apiError.config.__disableErrorToast = true;
+          emitAPIErrorEvent(APIErrorEvent.COUNTRY_RESTRICTED, apiError);
+          break;
+        }
+        case ErrorCodes.COZE_TOKEN_INSUFFICIENT: {
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-expect-error
+          apiError.config.__disableErrorToast = true;
+          emitAPIErrorEvent(APIErrorEvent.COZE_TOKEN_INSUFFICIENT, apiError);
+          break;
+        }
+        case ErrorCodes.COZE_TOKEN_INSUFFICIENT_WORKFLOW: {
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-expect-error
+          apiError.config.__disableErrorToast = true;
+          emitAPIErrorEvent(APIErrorEvent.COZE_TOKEN_INSUFFICIENT, apiError);
+          break;
+        }
+        default: {
+          break;
+        }
+      }
+
+      reportHttpError(ReportEventNames.ApiError, apiError);
+      return Promise.reject(apiError);
+    }
+    let res = response;
+    for (const interceptor of customInterceptors.response) {
+      res = interceptor(res);
+    }
+
+    return res;
+  },
+  error => {
+    if (isAxiosError(error)) {
+      reportHttpError(ReportEventNames.NetworkError, error);
+      if (error.response?.status === HTTP_STATUS_COE_UNAUTHORIZED) {
+        // 401 身份过期&没有身份
+        if (typeof error.response.data === 'object') {
+          const unauthorizedData = error.response.data as UnauthorizedResponse;
+          const redirectUri = unauthorizedData?.data?.redirect_uri;
+          if (redirectUri) {
+            redirect(redirectUri);
+          }
+        }
+      }
+    }
+
+    return Promise.reject(error);
+  },
+);
+
+axiosInstance.interceptors.request.use(config => {
+  const setHeader = (key: string, value: string) => {
+    if (typeof config.headers.set === 'function') {
+      config.headers.set(key, value);
+    } else {
+      config.headers[key] = value;
+    }
+  };
+  const getHeader = (key: string) => {
+    if (typeof config.headers.get === 'function') {
+      return config.headers.get(key);
+    }
+    return config.headers[key];
+  };
+  setHeader('x-requested-with', 'XMLHttpRequest');
+  if (
+    ['post', 'get'].includes(config.method?.toLowerCase() ?? '') &&
+    !getHeader('content-type')
+  ) {
+    // 新的 csrf 防护需要 post/get 请求全部带上这个 header
+    setHeader('content-type', 'application/json');
+    if (!config.data) {
+      // axios 会自动在 data 为空时清除 content-type，所以需要设置一个空对象
+      config.data = {};
+    }
+  }
+  return config;
+});
+
+type AddRequestInterceptorShape = typeof axiosInstance.interceptors.request.use;
+/**
+ * 添加全局 axios 的 interceptor 处理器，方便在上层扩展 axios 行为。
+ * 请注意，该接口会影响所有 bot-http 下的请求，请注意保证行为的稳定性
+ */
+export const addGlobalRequestInterceptor: AddRequestInterceptorShape = (
+  onFulfilled,
+  onRejected?,
+) => {
+  // PS: 这里不期望直接暴露 axios 实例到上层，因为不知道会被怎么修改使用
+  // 因此，这里需要暴露若干方法，将行为与副作用限制在可控范围内
+  const id = axiosInstance.interceptors.request.use(onFulfilled, onRejected);
+  return id;
+};
+
+type RemoveRequestInterceptorShape =
+  typeof axiosInstance.interceptors.request.eject;
+/**
+ * 删除全局 axios 的 interceptor 处理器，其中，id 参数为调用 addGlobalRequestInterceptor 返回的值
+ */
+export const removeGlobalRequestInterceptor: RemoveRequestInterceptorShape = (
+  id: number,
+) => {
+  axiosInstance.interceptors.request.eject(id);
+};
+
+export const addGlobalResponseInterceptor = (
+  onFulfilled: ResponseInterceptorOnFulfilled,
+) => {
+  customInterceptors.response.add(onFulfilled);
+  return () => {
+    customInterceptors.response.delete(onFulfilled);
+  };
+};

frontend/packages/arch/bot-http/src/eventbus.ts

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import { GlobalEventBus } from '@coze-arch/web-context';
+
+// api 请求有关事件
+export enum APIErrorEvent {
+  // 无登录状态
+  UNAUTHORIZED = 'unauthorized',
+  // 登录了 没权限
+  NOACCESS = 'noAccess',
+  // 风控拦截
+  SHARK_BLOCK = 'sharkBlocked',
+  // 国家限制
+  COUNTRY_RESTRICTED = 'countryRestricted',
+  // COZE TOKEN 不足
+  COZE_TOKEN_INSUFFICIENT = 'cozeTokenInsufficient',
+}
+
+const getEventBus = () => GlobalEventBus.create<APIErrorEvent>('bot-http');
+
+export const emitAPIErrorEvent = (event: APIErrorEvent, ...data: unknown[]) => {
+  const evenBus = getEventBus();
+
+  evenBus.emit(event, ...data);
+};
+
+export const handleAPIErrorEvent = (
+  event: APIErrorEvent,
+  fn: (...args: unknown[]) => void,
+) => {
+  const evenBus = getEventBus();
+
+  evenBus.on(event, fn);
+};
+
+export const removeAPIErrorEvent = (
+  event: APIErrorEvent,
+  fn: (...args: unknown[]) => void,
+) => {
+  const evenBus = getEventBus();
+
+  evenBus.off(event, fn);
+};
+
+export const stopAPIErrorEvent = () => {
+  const evenBus = getEventBus();
+
+  evenBus.stop();
+};
+
+export const startAPIErrorEvent = () => {
+  const evenBus = getEventBus();
+
+  evenBus.start();
+};
+
+export const clearAPIErrorEvent = () => {
+  const evenBus = getEventBus();
+
+  evenBus.clear();
+};

frontend/packages/arch/bot-http/src/global.d.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+/// <reference types='@coze-arch/bot-typings' />

frontend/packages/arch/bot-http/src/index.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+export {
+  APIErrorEvent,
+  handleAPIErrorEvent,
+  removeAPIErrorEvent,
+  stopAPIErrorEvent,
+  startAPIErrorEvent,
+  clearAPIErrorEvent,
+  emitAPIErrorEvent,
+} from './eventbus';
+
+export {
+  axiosInstance,
+  addGlobalRequestInterceptor,
+  removeGlobalRequestInterceptor,
+  addGlobalResponseInterceptor,
+  ErrorCodes,
+} from './axios';
+export { ApiError, isApiError } from './api-error';
+export { type AxiosRequestConfig } from 'axios';

frontend/packages/arch/bot-http/tsconfig.build.json

@@ -0,0 +1,34 @@
+{
+  "extends": "@coze-arch/ts-config/tsconfig.web.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "useUnknownInCatchVariables": false,
+    "types": ["vitest/globals"],
+    "strictNullChecks": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "dist/tsconfig.build.tsbuildinfo"
+  },
+  "include": ["./src"],
+  "references": [
+    {
+      "path": "../bot-typings/tsconfig.build.json"
+    },
+    {
+      "path": "../../../config/eslint-config/tsconfig.build.json"
+    },
+    {
+      "path": "../../../config/ts-config/tsconfig.build.json"
+    },
+    {
+      "path": "../../../config/vitest-config/tsconfig.build.json"
+    },
+    {
+      "path": "../logger/tsconfig.build.json"
+    },
+    {
+      "path": "../web-context/tsconfig.build.json"
+    }
+  ],
+  "$schema": "https://json.schemastore.org/tsconfig"
+}

frontend/packages/arch/bot-http/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "composite": true
+  },
+  "references": [
+    {
+      "path": "./tsconfig.build.json"
+    },
+    {
+      "path": "./tsconfig.misc.json"
+    }
+  ],
+  "exclude": ["**/*"]
+}

frontend/packages/arch/bot-http/tsconfig.misc.json

@@ -0,0 +1,19 @@
+{
+  "extends": "@coze-arch/ts-config/tsconfig.web.json",
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "include": ["__tests__", "vitest.config.mts"],
+  "exclude": ["./dist"],
+  "references": [
+    {
+      "path": "./tsconfig.build.json"
+    }
+  ],
+  "compilerOptions": {
+    "jsx": "preserve",
+    "rootDir": "./",
+    "outDir": "./dist",
+    "useUnknownInCatchVariables": false,
+    "types": ["vitest/globals"],
+    "strictNullChecks": true
+  }
+}

frontend/packages/arch/bot-http/vitest.config.mts

@@ -0,0 +1,12 @@
+import { defineConfig } from '@coze-arch/vitest-config';
+
+export default defineConfig({
+  dirname: __dirname,
+  preset: 'web',
+  test: {
+    coverage: {
+      all: true,
+      exclude: ['src/index.ts'],
+    },
+  },
+});