@dxtmisha/wiki 0.25.1 → 0.39.2

package/src/media/functional/functional-basic/api/api.ru.mdx

@@ -0,0 +1,135 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/# Api'/>
+
+# Api
+
+Класс `Api` — это основной инструмент для работы с HTTP-запросами. Он предоставляет простой интерфейс для стандартных методов и управляет глобальными настройками, такими как базовый URL, заголовки по умолчанию и хуки жизненного цикла.
+
+## Базовое использование
+
+Самый простой способ выполнить запрос — использовать статические методы `get`, `post`, `put`, или `delete`. Все методы поддерживают типизацию ответа через Generic.
+
+```javascript
+import { Api } from '@dxtmisha/functional-basic'
+
+// Простой GET запрос с типизацией
+const data = await Api.get<User[]>({ path: 'users' })
+
+// POST запрос с отправкой данных в теле
+const newUser = await Api.post<User>({
+  path: 'users',
+  request: { name: 'Иван Иванов', job: 'Разработчик' }
+})
+```
+
+## Глобальная конфигурация
+
+Вы можете настроить поведение API глобально, например, при инициализации приложения. Это избавит от необходимости указывать полные пути и общие заголовки в каждом вызове.
+
+```javascript
+// Установка базового URL для всех относительных путей
+Api.setUrl('https://api.example.com/v1/')
+
+// Добавление общих заголовков (например, токен авторизации)
+Api.setHeaders({
+  'Authorization': 'Bearer YOUR_TOKEN'
+})
+
+// Установка общих параметров, которые будут добавлены к каждому запросу
+Api.setRequestDefault({
+  app_version: '1.0.0'
+})
+```
+
+## Хуки жизненного цикла
+
+Библиотека позволяет внедрить глобальную логику, которая будет срабатывать для каждого запроса. Это удобно для динамического добавления токенов, логирования или централизованной обработки ошибок сервера.
+
+### Хук подготовки (setPreparation)
+
+Выполняется непосредственно перед отправкой запроса на сервер.
+
+- **Параметры**: получает объект `apiFetch`, содержащий все настройки текущего запроса (путь, метод, данные и т.д.).
+- **Применение**: проверка прав доступа, добавление динамических параметров в `apiFetch.request` или простое логирование начала операции.
+
+```javascript
+Api.setPreparation(async (apiFetch) => {
+  // Можно изменить apiFetch перед отправкой
+  console.log(`Запуск запроса: ${apiFetch.path}`)
+})
+```
+
+### Хук завершения (setEnd)
+
+Выполняется после того, как сервер вернул ответ, но до того, как данные попадут в ваш код.
+
+- **Параметры**: получает нативный объект `Response` и объект настроек `apiFetch`.
+- **Возвращает**: Promise с объектом `{ reset?: boolean, data?: any }`.
+- **Флаг reset**: если вернуть `true`, библиотека прервет текущую цепочку и выполнит запрос заново. Это полезно для автоматического обновления истекшего токена (Refresh Token).
+- **Поле data**: позволяет подменить или дополнить данные, которые вернет метод `Api.request`.
+
+```javascript
+Api.setEnd(async (response, apiFetch) => {
+  // Например, обработка ошибки 401 (Unauthorized)
+  if (response.status === 401) {
+    const isRefreshed = await myAuthService.refreshToken()
+    
+    if (isRefreshed) {
+      return { reset: true } // Повторить запрос с новым токеном
+    }
+  }
+  
+  return {} // Продолжить стандартную обработку
+})
+```
+
+## Эмуляция ответов
+
+Встроенный менеджер `ApiResponse` (доступен через `Api.getResponse()`) позволяет перехватывать запросы и возвращать мок-данные. Это крайне полезно при разработке интерфейса, когда бэкенд еще не готов, или для написания тестов.
+
+### Регистрация моков
+
+Вы можете добавлять как статические ответы, так и динамические функции.
+
+```javascript
+const responseManager = Api.getResponse()
+
+// 1. Статический ответ на GET запрос
+responseManager.add({
+  path: 'profile',
+  method: 'GET',
+  response: { id: 1, name: 'Admin' },
+  lag: true // Имитация задержки сети (0-2 сек)
+})
+
+// 2. Динамический ответ на основе параметров запроса
+responseManager.add({
+  path: 'users/search',
+  method: 'GET',
+  response: (request) => {
+    return {
+      results: [`Результат для: ${request.query}`],
+      count: 1
+    }
+  }
+})
+
+// 3. Перехват POST запроса с любым телом
+responseManager.add({
+  path: 'users/update',
+  method: 'POST',
+  request: '*any', // Игнорировать проверку тела запроса
+  response: { success: true }
+})
+```
+
+### Режим разработки
+
+Для удобства отладки можно включить логирование эмуляции в консоль. В этом режиме менеджер будет предупреждать в консоли о каждом перехваченном запросе.
+
+```javascript
+Api.getResponse().setDevMode(true)
+```
+
+Эмулятор срабатывает **до** выполнения реального `fetch`. Если подходящий мок не найден, `Api` выполнит обычный сетевой запрос.

package/src/media/functional/functional-basic/api/api.vi.mdx

@@ -0,0 +1,135 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/# Api'/>
+
+# Api
+
+Lớp `Api` là công cụ trung tâm để thực hiện các yêu cầu HTTP. Nó cung cấp một giao diện đơn giản cho các phương thức phổ biến và quản lý các cài đặt toàn cục như URL cơ sở, tiêu đề mặc định và các hook vòng đời.
+
+## Cách dùng cơ bản
+
+Cách đơn giản nhất để thực hiện yêu cầu là sử dụng các phương thức tĩnh `get`, `post`, `put`, hoặc `delete`. Tất cả các phương thức đều hỗ trợ định nghĩa kiểu dữ liệu (typing) thông qua Generic.
+
+```javascript
+import { Api } from '@dxtmisha/functional-basic'
+
+// Yêu cầu GET đơn giản với định nghĩa kiểu
+const data = await Api.get<User[]>({ path: 'users' })
+
+// Yêu cầu POST kèm dữ liệu trong body
+const newUser = await Api.post<User>({
+  path: 'users',
+  request: { name: 'Nguyễn Văn A', job: 'Lập trình viên' }
+})
+```
+
+## Cấu hình toàn cục
+
+Bạn có thể cấu hình hành vi của API trên toàn hệ thống, ví dụ như khi khởi tạo ứng dụng. Việc này giúp loại bỏ sự cần thiết phải chỉ định các đường dẫn đầy đủ và các tiêu đề chung trong mỗi lần gọi.
+
+```javascript
+// Đặt URL cơ sở cho tất cả các đường dẫn tương đối
+Api.setUrl('https://api.example.com/v1/')
+
+// Thêm các tiêu đề chung (ví dụ: token xác thực)
+Api.setHeaders({
+  'Authorization': 'Bearer YOUR_TOKEN'
+})
+
+// Đặt các tham số chung sẽ được thêm vào mọi yêu cầu
+Api.setRequestDefault({
+  app_version: '1.0.0'
+})
+```
+
+## Hook vòng đời
+
+Thư viện cho phép bạn chèn logic toàn cục sẽ được kích hoạt cho mọi yêu cầu. Việc này rất hữu ích để thêm token động, ghi log hoặc xử lý tập trung các lỗi máy chủ.
+
+### Hook chuẩn bị (setPreparation)
+
+Được thực thi ngay trước khi yêu cầu được gửi đến máy chủ.
+
+- **Tham số**: Nhận đối tượng `apiFetch`, chứa tất cả các tham số của yêu cầu hiện tại (đường dẫn, phương thức, dữ liệu, v.v.).
+- **Sử dụng**: Kiểm tra quyền truy cập, thêm các tham số động vào `apiFetch.request`, hoặc đơn giản là ghi log bắt đầu một hoạt động.
+
+```javascript
+Api.setPreparation(async (apiFetch) => {
+  // Bạn có thể sửa đổi apiFetch trước khi gửi
+  console.log(`Bắt đầu yêu cầu đến: ${apiFetch.path}`)
+})
+```
+
+### Hook kết thúc (setEnd)
+
+Được thực thi sau khi máy chủ trả về phản hồi, nhưng trước khi dữ liệu đến mã của bạn.
+
+- **Tham số**: Nhận đối tượng `Response` gốc và đối tượng cài đặt `apiFetch`.
+- **Trả về**: Một Promise với đối tượng `{ reset?: boolean, data?: any }`.
+- **Cờ reset**: Nếu trả về `true`, thư viện sẽ hủy chuỗi hiện tại và thực hiện lại yêu cầu. Việc này rất hữu ích để tự động xử lý token hết hạn (Refresh Token).
+- **Trường data**: Cho phép bạn thay thế hoặc bổ sung dữ liệu được trả về bởi phương thức `Api.request`.
+
+```javascript
+Api.setEnd(async (response, apiFetch) => {
+  // Ví dụ: xử lý lỗi 401 Unauthorized
+  if (response.status === 401) {
+    const isRefreshed = await myAuthService.refreshToken()
+    
+    if (isRefreshed) {
+      return { reset: true } // Thử lại yêu cầu với token mới
+    }
+  }
+  
+  return {} // Tiếp tục xử lý tiêu chuẩn
+})
+```
+
+## Giả lập phản hồi
+
+Trình quản lý `ApiResponse` tích hợp sẵn (có thể truy cập qua `Api.getResponse()`) cho phép bạn chặn các yêu cầu và trả về dữ liệu giả (mock). Điều này cực kỳ hữu ích cho việc phát triển giao diện khi backend chưa sẵn sàng hoặc để viết các bài kiểm thử.
+
+### Đăng ký Mock
+
+Bạn có thể thêm cả phản hồi tĩnh và các hàm động.
+
+```javascript
+const responseManager = Api.getResponse()
+
+// 1. Phản hồi tĩnh cho yêu cầu GET
+responseManager.add({
+  path: 'profile',
+  method: 'GET',
+  response: { id: 1, name: 'Admin' },
+  lag: true // Mô phỏng độ trễ mạng (0-2 giây)
+})
+
+// 2. Phản hồi động dựa trên các tham số yêu cầu
+responseManager.add({
+  path: 'users/search',
+  method: 'GET',
+  response: (request) => {
+    return {
+      results: [`Kết quả cho: ${request.query}`],
+      count: 1
+    }
+  }
+})
+
+// 3. Chặn yêu cầu POST với bất kỳ body nào
+responseManager.add({
+  path: 'users/update',
+  method: 'POST',
+  request: '*any', // Bỏ qua việc kiểm tra body yêu cầu
+  response: { success: true }
+})
+```
+
+### Chế độ phát triển
+
+Để gỡ lỗi dễ dàng hơn, bạn có thể bật tính năng ghi nhận (logging) giả lập trong console. Trong chế độ này, trình quản lý sẽ cảnh báo trong console về mỗi yêu cầu bị chặn.
+
+```javascript
+Api.getResponse().setDevMode(true)
+```
+
+Trình giả lập sẽ kích hoạt **trước khi** lệnh `fetch` thực sự được thực hiện. Nếu không tìm thấy mock phù hợp, `Api` sẽ thực hiện một yêu cầu mạng thông thường.

package/src/media/functional/functional-basic/broadcast-message/broadcast-message.en.mdx

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/# Cross-tab messaging'/>
+
+# Cross-tab messaging
+
+The `BroadcastMessage` class provides a simple wrapper around the native `BroadcastChannel` API for synchronization and communication between different browser tabs or windows within the same origin.
+
+## Basic Usage
+
+To start communicating, create an instance of the class by specifying a channel name and a callback function to handle incoming messages.
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional-basic'
+
+// 1. Initialize the channel
+const messenger = new BroadcastMessage('my-feature-channel', (event) => {
+  console.log('Received message:', event.data)
+})
+
+// 2. Send a message to other tabs
+messenger.post({ action: 'update', id: 123 })
+```
+
+The library automatically prefixes channel names with a unique session ID to ensure that messages from different application instances do not conflict.
+
+## Handling Messages
+
+You can update or set callbacks after initialization using the following methods:
+
+- `setCallback(callback)` — sets the main message handler.
+- `setCallbackError(callback)` — sets a handler for message errors (e.g., serialization issues).
+
+```javascript
+messenger.setCallback((event) => {
+  if (event.data.type === 'REFRESH') {
+    window.location.reload()
+  }
+})
+```
+
+## Advanced Access
+
+If you need direct access to the underlying `BroadcastChannel` instance, use the `getChannel()` method.
+
+```javascript
+const nativeChannel = messenger.getChannel()
+
+if (nativeChannel) {
+  console.log('Current channel name:', nativeChannel.name)
+}
+```

package/src/media/functional/functional-basic/broadcast-message/broadcast-message.ru.mdx

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/# Межвкладочные сообщения'/>
+
+# Межвкладочные сообщения
+
+Класс `BroadcastMessage` является удобной оберткой над нативным API `BroadcastChannel`, позволяя синхронизировать данные и передавать сообщения между различными вкладками или окнами браузера в рамках одного домена.
+
+## Базовое использование
+
+Для начала работы создайте экземпляр класса, указав имя канала и функцию обратного вызова (callback) для обработки входящих сообщений.
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional-basic'
+
+// 1. Инициализация канала
+const messenger = new BroadcastMessage('my-feature-channel', (event) => {
+  console.log('Получено сообщение:', event.data)
+})
+
+// 2. Отправка сообщения в другие вкладки
+messenger.post({ action: 'update', id: 123 })
+```
+
+Библиотека автоматически добавляет уникальный префикс к имени канала для изоляции сообщений разных сессий приложения.
+
+## Обработка сообщений
+
+Вы можете установить или обновить обработчики сообщений после инициализации с помощью следующих методов:
+
+- `setCallback(callback)` — устанавливает основной обработчик входящих сообщений.
+- `setCallbackError(callback)` — устанавливает обработчик ошибок сообщений (например, при проблемах с десериализацией).
+
+```javascript
+messenger.setCallback((event) => {
+  if (event.data.type === 'REFRESH') {
+    window.location.reload()
+  }
+})
+```
+
+## Дополнительные возможности
+
+Если вам нужен прямой доступ к нативному инстансу `BroadcastChannel`, используйте метод `getChannel()`.
+
+```javascript
+const nativeChannel = messenger.getChannel()
+
+if (nativeChannel) {
+  console.log('Имя нативного канала:', nativeChannel.name)
+}
+```

package/src/media/functional/functional-basic/broadcast-message/broadcast-message.vi.mdx

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/# Truyền tin giữa các tab'/>
+
+# Truyền tin giữa các tab
+
+Lớp `BroadcastMessage` cung cấp một wrapper đơn giản cho API `BroadcastChannel` gốc, cho phép đồng bộ hóa dữ liệu và truyền tin nhắn giữa các tab hoặc cửa sổ trình duyệt khác nhau trong cùng một origin.
+
+## Cách sử dụng cơ bản
+
+Để bắt đầu giao tiếp, hãy tạo một instance của lớp bằng cách chỉ định tên kênh và một hàm callback để xử lý các tin nhắn đến.
+
+```javascript
+import { BroadcastMessage } from '@dxtmisha/functional-basic'
+
+// 1. Khởi tạo kênh
+const messenger = new BroadcastMessage('my-feature-channel', (event) => {
+  console.log('Nhận được tin nhắn:', event.data)
+})
+
+// 2. Gửi tin nhắn đến các tab khác
+messenger.post({ action: 'update', id: 123 })
+```
+
+Thư viện tự động thêm tiền tố (prefix) duy nhất vào tên kênh để đảm bảo rằng tin nhắn từ các phiên ứng dụng khác nhau không bị xung đột.
+
+## Xử lý tin nhắn
+
+Bạn có thể cập nhật hoặc thiết lập các callback sau khi khởi tạo bằng các phương thức sau:
+
+- `setCallback(callback)` — thiết lập trình xử lý tin nhắn chính.
+- `setCallbackError(callback)` — thiết lập trình xử lý cho các lỗi tin nhắn (ví dụ: vấn đề tuần tự hóa).
+
+```javascript
+messenger.setCallback((event) => {
+  if (event.data.type === 'REFRESH') {
+    window.location.reload()
+  }
+})
+```
+
+## Truy cập nâng cao
+
+Nếu bạn cần truy cập trực tiếp vào instance `BroadcastChannel` gốc, hãy sử dụng phương thức `getChannel()`.
+
+```javascript
+const nativeChannel = messenger.getChannel()
+
+if (nativeChannel) {
+  console.log('Tên kênh gốc hiện tại:', nativeChannel.name)
+}
+```

package/src/media/functional/functional-basic/classes/Api/Api.en.mdx

@@ -0,0 +1,78 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/Api - Request Management'/>
+
+# Api Class
+
+`Api` is a static wrapper class around the `ApiInstance` instance for efficient network request operations.
+
+All methods of the `Api` class are automatically delegated to an internal global `ApiInstance` object. This allows you to work with HTTP requests without the need to manually instantiate objects:
+
+```typescript
+import { Api } from '@dxtmisha/functional'
+
+// These calls interact with the same global instance under the hood
+Api.setUrl('https://api.example.com/v1/')
+Api.setHeaders({ 'Authorization': 'Bearer token123' })
+
+const data = await Api.get({ path: 'users' })
+```
+
+## Methods
+
+### Instance Access
+
+- `getItem(): ApiInstance` — Returns the internal `ApiInstance` object used by all static method delegations.
+
+### Information Methods
+
+- `isLocalhost(): boolean` — Returns `true` if the code is running on a local development server.
+- `getStatus(): ApiStatus` — Returns the `ApiStatus` manager for tracking the state and errors of the last request.
+- `getResponse(): ApiResponse` — Returns the responses/emulation manager `ApiResponse`.
+- `getUrl(path: string, api?: boolean): string` — Returns the full URL for the request. Dynamic placeholders `{locale}`, `{country}`, `{language}` are automatically replaced.
+- `getBody(request?, method?): string | FormData | undefined` — Returns data for the request body.
+- `getBodyForGet(request, path?, method?): string` — Returns the query string for GET method requests.
+
+### Configuration Methods
+
+All configuration methods return the `Api` class itself for chaining:
+
+- `setUrl(url: string): Api` — Sets the base URL for all requests.
+- `setHeaders(headers: Record<string, string>): Api` — Sets default headers for all requests.
+- `setRequestDefault(request: Record<string, any>): Api` — Sets default request data merged into every request body.
+- `setPreparation(callback): Api` — Sets a callback function executed before each request.
+- `setEnd(callback): Api` — Sets a callback function executed after each request.
+- `setConfig(config?: ApiConfig): Api` — Applies a full configuration object at once (`urlRoot`, `headers`, `requestDefault`, `preparation`, `end`).
+
+### Request Methods
+
+- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Core request executor. Accepts a string path or an `ApiFetch` configuration object.
+- `get<T>(request: ApiFetch): Promise<T>` — Sends an HTTP GET request.
+- `post<T>(request: ApiFetch): Promise<T>` — Sends an HTTP POST request.
+- `put<T>(request: ApiFetch): Promise<T>` — Sends an HTTP PUT request.
+- `delete<T>(request: ApiFetch): Promise<T>` — Sends an HTTP DELETE request.
+
+## setConfig
+
+The `setConfig` method allows applying multiple configuration options at once using an `ApiConfig` object:
+
+```typescript
+import { Api } from '@dxtmisha/functional'
+
+Api.setConfig({
+  urlRoot: 'https://api.example.com/v1/',
+  headers: { 'Authorization': 'Bearer token123' },
+  requestDefault: { source: 'webapp' },
+  preparation: async (apiFetch) => {
+    console.log('Preparing:', apiFetch.path)
+  },
+  end: async (response, apiFetch) => {
+    if (response.status === 401) {
+      return { reset: true }
+    }
+    return {}
+  }
+})
+```
+
+> **Important:** The exhaustive details on `ApiFetch` options, lifecycle hooks, response emulation, and response data structure are documented in the core **ApiInstance** documentation.

package/src/media/functional/functional-basic/classes/Api/Api.ru.mdx

@@ -0,0 +1,78 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/Api - Управление запросами'/>
+
+# Класс Api
+
+`Api` — это статичная обертка над инстансом `ApiInstance`.
+
+Все вызовы методов `Api` автоматически делегируются внутреннему глобальному объекту `ApiInstance`. Это позволяет работать с HTTP запросами без необходимости самостоятельного создания инстансов:
+
+```typescript
+import { Api } from '@dxtmisha/functional'
+
+// Эти вызовы обращаются к одному и тому же глобальному инстансу под капотом
+Api.setUrl('https://api.example.com/v1/')
+Api.setHeaders({ 'Authorization': 'Bearer token123' })
+
+const data = await Api.get({ path: 'users' })
+```
+
+## Методы
+
+### Доступ к инстансу
+
+- `getItem(): ApiInstance` — Возвращает внутренний объект `ApiInstance`, используемый всеми статическими методами.
+
+### Информационные методы
+
+- `isLocalhost(): boolean` — Возвращает `true`, если код работает на локальном сервере разработки.
+- `getStatus(): ApiStatus` — Возвращает менеджер `ApiStatus` для отслеживания состояния и ошибок последнего запроса.
+- `getResponse(): ApiResponse` — Возвращает менеджер ответов/эмуляции `ApiResponse`.
+- `getUrl(path: string, api?: boolean): string` — Возвращает полный URL запроса. Динамические заполнители `{locale}`, `{country}`, `{language}` заменяются автоматически.
+- `getBody(request?, method?): string | FormData | undefined` — Возвращает данные для тела запроса.
+- `getBodyForGet(request, path?, method?): string` — Возвращает строку параметров запроса для метода GET.
+
+### Методы конфигурации
+
+Все методы конфигурации возвращают сам класс `Api` для цепочечного вызова:
+
+- `setUrl(url: string): Api` — Устанавливает базовый URL для всех запросов.
+- `setHeaders(headers: Record<string, string>): Api` — Устанавливает заголовки по умолчанию для всех запросов.
+- `setRequestDefault(request: Record<string, any>): Api` — Устанавливает данные запроса по умолчанию, объединяемые с каждым телом запроса.
+- `setPreparation(callback): Api` — Устанавливает функцию обратного вызова, выполняемую перед каждым запросом.
+- `setEnd(callback): Api` — Устанавливает функцию обратного вызова, выполняемую после каждого запроса.
+- `setConfig(config?: ApiConfig): Api` — Применяет полный объект конфигурации сразу (`urlRoot`, `headers`, `requestDefault`, `preparation`, `end`).
+
+### Методы запросов
+
+- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Основной исполнитель запросов. Принимает строку пути или объект конфигурации `ApiFetch`.
+- `get<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP GET запрос.
+- `post<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP POST запрос.
+- `put<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP PUT запрос.
+- `delete<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP DELETE запрос.
+
+## setConfig
+
+Метод `setConfig` позволяет применить несколько параметров конфигурации одновременно с помощью объекта `ApiConfig`:
+
+```typescript
+import { Api } from '@dxtmisha/functional'
+
+Api.setConfig({
+  urlRoot: 'https://api.example.com/v1/',
+  headers: { 'Authorization': 'Bearer token123' },
+  requestDefault: { source: 'webapp' },
+  preparation: async (apiFetch) => {
+    console.log('Подготовка:', apiFetch.path)
+  },
+  end: async (response, apiFetch) => {
+    if (response.status === 401) {
+      return { reset: true }
+    }
+    return {}
+  }
+})
+```
+
+> **Важно:** Полный список параметров (`ApiFetch`), хуков (Lifecycle Hooks), эмуляции ответов и структуры данных ответа описан в документации базового класса **ApiInstance**.

package/src/media/functional/functional-basic/classes/Api/Api.vi.mdx

@@ -0,0 +1,78 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/Api - Quản lý yêu cầu (Request)'/>
+
+# Lớp Api
+
+`Api` là một lớp tĩnh (static wrapper) bao bọc xung quanh một đối tượng `ApiInstance`.
+
+Mọi phương thức của lớp `Api` đều được tự động ủy quyền (delegate) cho một đối tượng `ApiInstance` chung (global object) bên trong. Điều này cho phép bạn làm việc với các yêu cầu HTTP mà không cần phải tự khởi tạo (instantiate) các đối tượng:
+
+```typescript
+import { Api } from '@dxtmisha/functional'
+
+// Các lệnh gọi này tương tác với cùng một đối tượng toàn phần (global instance) bên dưới
+Api.setUrl('https://api.example.com/v1/')
+Api.setHeaders({ 'Authorization': 'Bearer token123' })
+
+const data = await Api.get({ path: 'users' })
+```
+
+## Các phương thức
+
+### Truy cập instance
+
+- `getItem(): ApiInstance` — Trả về đối tượng `ApiInstance` nội bộ được sử dụng bởi tất cả các phương thức tĩnh.
+
+### Phương thức thông tin
+
+- `isLocalhost(): boolean` — Trả về `true` nếu mã đang chạy trên máy chủ phát triển cục bộ.
+- `getStatus(): ApiStatus` — Trả về trình quản lý `ApiStatus` để theo dõi trạng thái và lỗi của yêu cầu cuối cùng.
+- `getResponse(): ApiResponse` — Trả về trình quản lý phản hồi/mô phỏng `ApiResponse`.
+- `getUrl(path: string, api?: boolean): string` — Trả về URL đầy đủ cho yêu cầu. Các trình giữ chỗ động `{locale}`, `{country}`, `{language}` được thay thế tự động.
+- `getBody(request?, method?): string | FormData | undefined` — Trả về dữ liệu cho phần thân (body) của yêu cầu.
+- `getBodyForGet(request, path?, method?): string` — Trả về chuỗi tham số truy vấn (query string) cho phương thức GET.
+
+### Phương thức cấu hình
+
+Tất cả các phương thức cấu hình đều trả về chính lớp `Api` để hỗ trợ chuỗi lệnh (chaining):
+
+- `setUrl(url: string): Api` — Đặt URL cơ sở cho tất cả các yêu cầu.
+- `setHeaders(headers: Record<string, string>): Api` — Đặt các headers mặc định cho tất cả các yêu cầu.
+- `setRequestDefault(request: Record<string, any>): Api` — Đặt dữ liệu yêu cầu mặc định được hợp nhất vào mọi thân yêu cầu (request body).
+- `setPreparation(callback): Api` — Đặt hàm callback được thực thi trước mỗi yêu cầu.
+- `setEnd(callback): Api` — Đặt hàm callback được thực thi sau mỗi yêu cầu.
+- `setConfig(config?: ApiConfig): Api` — Áp dụng toàn bộ đối tượng cấu hình cùng một lúc (`urlRoot`, `headers`, `requestDefault`, `preparation`, `end`).
+
+### Phương thức yêu cầu
+
+- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Trình thực thi yêu cầu chính. Chấp nhận chuỗi đường dẫn hoặc đối tượng cấu hình `ApiFetch`.
+- `get<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP GET.
+- `post<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP POST.
+- `put<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP PUT.
+- `delete<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP DELETE.
+
+## setConfig
+
+Phương thức `setConfig` cho phép áp dụng nhiều tùy chọn cấu hình cùng lúc bằng đối tượng `ApiConfig`:
+
+```typescript
+import { Api } from '@dxtmisha/functional'
+
+Api.setConfig({
+  urlRoot: 'https://api.example.com/v1/',
+  headers: { 'Authorization': 'Bearer token123' },
+  requestDefault: { source: 'webapp' },
+  preparation: async (apiFetch) => {
+    console.log('Chuẩn bị:', apiFetch.path)
+  },
+  end: async (response, apiFetch) => {
+    if (response.status === 401) {
+      return { reset: true }
+    }
+    return {}
+  }
+})
+```
+
+> **Quan trọng:** Toàn bộ danh sách đầy đủ về các tùy chọn `ApiFetch`, hook vòng đời, mô phỏng phản hồi và cấu trúc dữ liệu phản hồi đã được ghi chép chi tiết tại tài liệu gốc của lớp **ApiInstance**.