@vctrl/hooks/utils/server-communication.d.ts

vctrl/hooks is a React hooks package designed to simplify 3D model loading and management within React applications. It's part of the vectreal-core ecosystem and is primarily used in the vctrl/viewer React component and the official website application.

import { ServerOptions, TextureBinaryPayload, TextureCompressOptions } from '../../../core/src/index.ts';
/**
 * Configuration for a server request.
 */
export interface ServerRequestConfig {
    /** Server endpoint URL or path */
    endpoint: string;
    /** HTTP method (GET, POST, etc.) */
    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
    /** Request body (FormData, JSON, or other) */
    body?: FormData | Record<string, unknown> | string;
    /** Optional server options (headers, auth, etc.) */
    serverOptions?: ServerOptions;
    /** Content type for JSON bodies (default: 'application/json') */
    contentType?: string;
}
/**
 * Unified server communication service for handling HTTP requests.
 * Provides a consistent interface for API calls with built-in error handling,
 * authentication, and response parsing.
 *
 * @example
 * ```typescript
 * // Simple GET request
 * const data = await ServerCommunicationService.request<SceneData>({
 *   endpoint: '/api/load-scene',
 *   method: 'GET'
 * })
 *
 * // POST with FormData
 * const formData = new FormData()
 * formData.append('model', file)
 * const result = await ServerCommunicationService.request({
 *   endpoint: '/api/optimize',
 *   method: 'POST',
 *   body: formData,
 *   serverOptions: { apiKey: 'secret' }
 * })
 *
 * // POST with JSON
 * const response = await ServerCommunicationService.request({
 *   endpoint: '/api/save',
 *   method: 'POST',
 *   body: { sceneId: '123', settings: {...} },
 *   serverOptions: { headers: { 'X-Custom': 'value' } }
 * })
 * ```
 */
export declare class ServerCommunicationService {
    private static extractApiData;
    /**
     * Creates default server options with required endpoint.
     * Merges provided options with defaults.
     */
    static createDefaultServerOptions(serverOptions?: ServerOptions): ServerOptions & Required<Pick<ServerOptions, 'endpoint'>>;
    /**
     * Creates request headers for server communication.
     * Includes authentication token if apiKey is provided.
     */
    static createRequestHeaders(serverOptions?: ServerOptions, additionalHeaders?: HeadersInit): HeadersInit;
    /**
     * Extracts error message from a failed response.
     * Attempts to parse JSON error data, falls back to text.
     */
    static extractErrorMessage(response: Response): Promise<string>;
    /**
     * Handles server response errors and throws appropriate errors.
     */
    static handleServerResponseError(response: Response): Promise<never>;
    /**
     * Prepares FormData for a single texture optimization request.
     */
    static prepareTextureOptimizationFormData(texture: TextureBinaryPayload, options?: TextureCompressOptions): FormData;
    /**
     * Performs a generic HTTP request with error handling.
     * Returns parsed response data.
     *
     * @template T - Expected response data type
     * @param config - Request configuration
     * @returns Promise resolving to parsed response data
     * @throws Error if request fails or response is not ok
     */
    static request<T = unknown>(config: ServerRequestConfig): Promise<T>;
    /**
     * Performs a GET request.
     * Convenience method for common GET operations.
     */
    static get<T = unknown>(endpoint: string, serverOptions?: ServerOptions): Promise<T>;
    /**
     * Performs a POST request with JSON body.
     * Convenience method for common POST operations.
     */
    static post<T = unknown>(endpoint: string, body: Record<string, unknown>, serverOptions?: ServerOptions): Promise<T>;
    /**
     * Performs a POST request with FormData body.
     * Convenience method for file uploads.
     */
    static postFormData<T = unknown>(endpoint: string, formData: FormData, serverOptions?: ServerOptions): Promise<T>;
    /**
     * Fetches scene data from the server.
     * Specialized method for loading 3D scenes with their associated settings.
     *
     * This method handles the vectreal-platform API format which uses:
     * - FormData with 'action' and 'sceneId' parameters
     * - POST request to the scene-settings endpoint
     * - Returns scene data including GLTF JSON and asset data
     *
     * @param sceneId - The unique identifier of the scene to load
     * @param serverOptions - Optional server configuration (endpoint, auth, headers)
     * @returns Promise resolving to the scene data
     * @throws Error if the request fails or scene doesn't exist
     *
     * @example
     * ```typescript
     * const sceneData = await ServerCommunicationService.loadScene('abc-123', {
     *   endpoint: '/api/scenes/abc-123',
     *   apiKey: 'optional-auth-token'
     * })
     * ```
     */
    static loadScene<T = unknown>(sceneId: string, serverOptions?: ServerOptions): Promise<T>;
}