digitaltwin-core/dist/utils/http_responses.d.ts

Minimalist framework to collect and handle data in a Digital Twin project

/**
 * @fileoverview HTTP response utilities for consistent API responses
 *
 * This module provides helper functions to create standardized DataResponse objects,
 * reducing boilerplate code in component handlers and ensuring consistent API responses.
 */
import type { DataResponse } from '../components/types.js';
/**
 * HTTP status codes commonly used in the Digital Twin framework.
 */
export declare const HttpStatus: {
    readonly OK: 200;
    readonly CREATED: 201;
    readonly MULTI_STATUS: 207;
    readonly BAD_REQUEST: 400;
    readonly UNAUTHORIZED: 401;
    readonly FORBIDDEN: 403;
    readonly NOT_FOUND: 404;
    readonly INTERNAL_SERVER_ERROR: 500;
};
export type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
/**
 * Creates a JSON response with the specified status and data.
 *
 * @param status - HTTP status code
 * @param data - Data to serialize as JSON
 * @returns DataResponse with JSON content type
 *
 * @example
 * ```typescript
 * return jsonResponse(200, { message: 'Success' })
 * return jsonResponse(400, { error: 'Invalid input' })
 * ```
 */
export declare function jsonResponse(status: number, data: object): DataResponse;
/**
 * Creates a successful JSON response (HTTP 200).
 *
 * @param data - Data to serialize as JSON
 * @returns DataResponse with status 200
 *
 * @example
 * ```typescript
 * return successResponse({ message: 'Asset uploaded successfully' })
 * ```
 */
export declare function successResponse(data: object): DataResponse;
/**
 * Creates an error response from an Error object or string.
 *
 * @param error - Error object or error message string
 * @param status - HTTP status code (default: 500)
 * @returns DataResponse with error message
 *
 * @example
 * ```typescript
 * return errorResponse(new Error('Something went wrong'))
 * return errorResponse('Invalid input', 400)
 * ```
 */
export declare function errorResponse(error: unknown, status?: number): DataResponse;
/**
 * Creates a 400 Bad Request response.
 *
 * @param message - Error message describing what's wrong with the request
 * @returns DataResponse with status 400
 *
 * @example
 * ```typescript
 * return badRequestResponse('Missing required fields: description, source')
 * ```
 */
export declare function badRequestResponse(message: string): DataResponse;
/**
 * Creates a 401 Unauthorized response.
 *
 * @param message - Error message (default: 'Authentication required')
 * @returns DataResponse with status 401
 *
 * @example
 * ```typescript
 * return unauthorizedResponse()
 * return unauthorizedResponse('Invalid authentication headers')
 * ```
 */
export declare function unauthorizedResponse(message?: string): DataResponse;
/**
 * Creates a 403 Forbidden response.
 *
 * @param message - Error message describing why access is denied
 * @returns DataResponse with status 403
 *
 * @example
 * ```typescript
 * return forbiddenResponse('You can only modify your own assets')
 * ```
 */
export declare function forbiddenResponse(message: string): DataResponse;
/**
 * Creates a 404 Not Found response.
 *
 * @param message - Error message (default: 'Resource not found')
 * @returns DataResponse with status 404
 *
 * @example
 * ```typescript
 * return notFoundResponse('Asset not found')
 * ```
 */
export declare function notFoundResponse(message?: string): DataResponse;
/**
 * Creates a plain text response.
 *
 * @param status - HTTP status code
 * @param content - Text content
 * @returns DataResponse with text/plain content type
 *
 * @example
 * ```typescript
 * return textResponse(404, 'Asset not found')
 * ```
 */
export declare function textResponse(status: number, content: string): DataResponse;
/**
 * Creates a binary/file response.
 *
 * @param content - File content as Buffer
 * @param contentType - MIME type of the file
 * @param filename - Optional filename for Content-Disposition header (triggers download)
 * @returns DataResponse with appropriate content type
 *
 * @example
 * ```typescript
 * // For display/use in browser
 * return fileResponse(buffer, 'model/gltf-binary')
 *
 * // For download
 * return fileResponse(buffer, 'model/gltf-binary', 'model.glb')
 * ```
 */
export declare function fileResponse(content: Buffer, contentType: string, filename?: string): DataResponse;
/**
 * Creates a 207 Multi-Status response for batch operations.
 *
 * @param message - Summary message
 * @param results - Array of individual operation results
 * @returns DataResponse with status 207
 *
 * @example
 * ```typescript
 * return multiStatusResponse('3/5 assets uploaded successfully', results)
 * ```
 */
export declare function multiStatusResponse(message: string, results: unknown[]): DataResponse;
//# sourceMappingURL=http_responses.d.ts.map