@vorionsys/platform-core 0.1.0

package/dist/intent/response.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Standardized API Response Envelope for INTENT Module
+ *
+ * Provides consistent API response formatting for better client integration.
+ * Includes success/error envelopes, pagination, and trace context support.
+ *
+ * @packageDocumentation
+ */
+import { VorionError } from '../common/errors.js';
+/**
+ * Standard HTTP status codes used in API responses
+ */
+export declare const HttpStatus: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly ACCEPTED: 202;
+    readonly NO_CONTENT: 204;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+};
+export type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
+/**
+ * Error information in the response envelope
+ */
+export interface ApiError {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details for debugging */
+    details?: Record<string, unknown>;
+    /** Trace ID for distributed tracing correlation */
+    traceId?: string;
+}
+/**
+ * Pagination information for list responses
+ */
+export interface PaginationInfo {
+    /** Current page number (1-indexed) */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Total number of items across all pages */
+    totalItems: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+/**
+ * Cursor-based pagination information
+ */
+export interface CursorPaginationInfo {
+    /** Cursor for the next page */
+    nextCursor?: string | undefined;
+    /** Cursor for the previous page */
+    prevCursor?: string | undefined;
+    /** Whether there are more items */
+    hasMore: boolean;
+    /** Number of items returned */
+    count: number;
+}
+/**
+ * Response metadata
+ */
+export interface ResponseMeta {
+    /** Unique request identifier for tracking */
+    requestId: string;
+    /** ISO 8601 timestamp when response was generated */
+    timestamp: string;
+    /** Page-based pagination information */
+    pagination?: PaginationInfo;
+    /** Cursor-based pagination information */
+    cursor?: CursorPaginationInfo;
+}
+/**
+ * Standard API response envelope
+ *
+ * @typeParam T - The type of the response data
+ */
+export interface ApiResponse<T> {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response data (present on success) */
+    data?: T;
+    /** Error information (present on failure) */
+    error?: ApiError;
+    /** Response metadata */
+    meta?: ResponseMeta;
+}
+/**
+ * Options for creating response metadata
+ */
+export interface MetaOptions {
+    /** Custom request ID (generated if not provided) */
+    requestId?: string | undefined;
+    /** Page-based pagination info */
+    pagination?: PaginationInfo | undefined;
+    /** Cursor-based pagination info */
+    cursor?: CursorPaginationInfo | undefined;
+}
+/**
+ * Options for paginated responses
+ */
+export interface PaginatedOptions {
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    pageSize: number;
+    /** Total items count */
+    totalItems: number;
+    /** Custom request ID */
+    requestId?: string | undefined;
+}
+/**
+ * Options for cursor-based paginated responses
+ */
+export interface CursorPaginatedOptions {
+    /** Next page cursor */
+    nextCursor?: string | undefined;
+    /** Previous page cursor */
+    prevCursor?: string | undefined;
+    /** Whether more items exist */
+    hasMore: boolean;
+    /** Custom request ID */
+    requestId?: string | undefined;
+}
+/**
+ * Create a successful API response
+ *
+ * @typeParam T - The type of the response data
+ * @param data - The response data
+ * @param options - Optional metadata configuration
+ * @returns Standardized success response
+ *
+ * @example
+ * ```typescript
+ * const response = successResponse({ id: '123', name: 'Test' });
+ * // { success: true, data: { id: '123', name: 'Test' }, meta: { requestId: '...', timestamp: '...' } }
+ * ```
+ */
+export declare function successResponse<T>(data: T, options?: MetaOptions): ApiResponse<T>;
+/**
+ * Create an error API response
+ *
+ * @param code - Machine-readable error code
+ * @param message - Human-readable error message
+ * @param details - Additional error details
+ * @param requestId - Optional request ID for tracking
+ * @returns Standardized error response
+ *
+ * @example
+ * ```typescript
+ * const response = errorResponse('VALIDATION_ERROR', 'Invalid input', { field: 'email' });
+ * // { success: false, error: { code: 'VALIDATION_ERROR', message: 'Invalid input', details: {...}, traceId: '...' }, meta: {...} }
+ * ```
+ */
+export declare function errorResponse(code: string, message: string, details?: Record<string, unknown>, requestId?: string): ApiResponse<never>;
+/**
+ * Create a paginated API response (page-based)
+ *
+ * @typeParam T - The type of items in the response
+ * @param items - Array of items for the current page
+ * @param options - Pagination options including page, pageSize, and totalItems
+ * @returns Standardized paginated response
+ *
+ * @example
+ * ```typescript
+ * const response = paginatedResponse(items, { page: 1, pageSize: 20, totalItems: 100 });
+ * // { success: true, data: [...], meta: { pagination: { page: 1, pageSize: 20, totalItems: 100, totalPages: 5 }, ... } }
+ * ```
+ */
+export declare function paginatedResponse<T>(items: T[], options: PaginatedOptions): ApiResponse<T[]>;
+/**
+ * Create a cursor-based paginated API response
+ *
+ * @typeParam T - The type of items in the response
+ * @param items - Array of items for the current page
+ * @param options - Cursor pagination options
+ * @returns Standardized cursor-paginated response
+ *
+ * @example
+ * ```typescript
+ * const response = cursorPaginatedResponse(items, { nextCursor: 'abc123', hasMore: true });
+ * // { success: true, data: [...], meta: { cursor: { nextCursor: 'abc123', hasMore: true, count: 10 }, ... } }
+ * ```
+ */
+export declare function cursorPaginatedResponse<T>(items: T[], options: CursorPaginatedOptions): ApiResponse<T[]>;
+/**
+ * Create a "created" response (HTTP 201)
+ *
+ * @typeParam T - The type of the created resource
+ * @param data - The created resource data
+ * @param options - Optional metadata configuration
+ * @returns Standardized success response for created resources
+ */
+export declare function createdResponse<T>(data: T, options?: MetaOptions): ApiResponse<T>;
+/**
+ * Create an "accepted" response (HTTP 202) for async operations
+ *
+ * @typeParam T - The type of the response data
+ * @param data - Optional response data (e.g., tracking information)
+ * @param options - Optional metadata configuration
+ * @returns Standardized success response for accepted requests
+ */
+export declare function acceptedResponse<T>(data?: T, options?: MetaOptions): ApiResponse<T | undefined>;
+/**
+ * Map VorionError to appropriate HTTP status code
+ *
+ * @param error - The VorionError instance
+ * @returns HTTP status code
+ */
+export declare function getHttpStatusFromError(error: VorionError): HttpStatusCode;
+/**
+ * Map error code to HTTP status code
+ *
+ * @param code - The error code string
+ * @returns HTTP status code
+ */
+export declare function getHttpStatusFromCode(code: string): HttpStatusCode;
+/**
+ * Create an error response from a VorionError
+ *
+ * @param error - The VorionError instance
+ * @param requestId - Optional request ID for tracking
+ * @returns Standardized error response
+ */
+export declare function errorResponseFromVorionError(error: VorionError, requestId?: string): ApiResponse<never>;
+/**
+ * Create an error response from any error (including non-VorionError)
+ *
+ * @param error - The error (VorionError or standard Error)
+ * @param requestId - Optional request ID for tracking
+ * @returns Standardized error response with appropriate HTTP status
+ */
+export declare function errorResponseFromError(error: unknown, requestId?: string): {
+    response: ApiResponse<never>;
+    status: HttpStatusCode;
+};
+/**
+ * Type guard to check if a response is successful
+ *
+ * @param response - The API response to check
+ * @returns True if the response indicates success
+ */
+export declare function isSuccessResponse<T>(response: ApiResponse<T>): response is ApiResponse<T> & {
+    success: true;
+    data: T;
+};
+/**
+ * Type guard to check if a response is an error
+ *
+ * @param response - The API response to check
+ * @returns True if the response indicates an error
+ */
+export declare function isErrorResponse<T>(response: ApiResponse<T>): response is ApiResponse<T> & {
+    success: false;
+    error: ApiError;
+};
+//# sourceMappingURL=response.d.ts.map

package/dist/intent/response.d.ts.map

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

package/dist/intent/response.js

@@ -0,0 +1,402 @@
+/**
+ * Standardized API Response Envelope for INTENT Module
+ *
+ * Provides consistent API response formatting for better client integration.
+ * Includes success/error envelopes, pagination, and trace context support.
+ *
+ * @packageDocumentation
+ */
+import { randomUUID } from 'node:crypto';
+import { getTraceContext } from '../common/trace.js';
+import { getConfig } from '../common/config.js';
+import { ValidationError, NotFoundError, UnauthorizedError, ForbiddenError, ConflictError, RateLimitError, ConfigurationError, DatabaseError, ExternalServiceError, TimeoutError, isVorionError, } from '../common/errors.js';
+/**
+ * Standard HTTP status codes used in API responses
+ */
+export const HttpStatus = {
+    // Success
+    OK: 200,
+    CREATED: 201,
+    ACCEPTED: 202,
+    NO_CONTENT: 204,
+    // Client errors
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    UNPROCESSABLE_ENTITY: 422,
+    TOO_MANY_REQUESTS: 429,
+    // Server errors
+    INTERNAL_SERVER_ERROR: 500,
+    BAD_GATEWAY: 502,
+    SERVICE_UNAVAILABLE: 503,
+    GATEWAY_TIMEOUT: 504,
+};
+/**
+ * Generate response metadata
+ */
+function createMeta(options) {
+    const meta = {
+        requestId: options?.requestId ?? randomUUID(),
+        timestamp: new Date().toISOString(),
+    };
+    if (options?.pagination) {
+        meta.pagination = options.pagination;
+    }
+    if (options?.cursor) {
+        meta.cursor = options.cursor;
+    }
+    return meta;
+}
+/**
+ * Get trace ID from current context or generate a new one
+ */
+function getOrCreateTraceId() {
+    const traceContext = getTraceContext();
+    return traceContext?.traceId;
+}
+/**
+ * Create a successful API response
+ *
+ * @typeParam T - The type of the response data
+ * @param data - The response data
+ * @param options - Optional metadata configuration
+ * @returns Standardized success response
+ *
+ * @example
+ * ```typescript
+ * const response = successResponse({ id: '123', name: 'Test' });
+ * // { success: true, data: { id: '123', name: 'Test' }, meta: { requestId: '...', timestamp: '...' } }
+ * ```
+ */
+export function successResponse(data, options) {
+    return {
+        success: true,
+        data,
+        meta: createMeta(options),
+    };
+}
+/**
+ * Create an error API response
+ *
+ * @param code - Machine-readable error code
+ * @param message - Human-readable error message
+ * @param details - Additional error details
+ * @param requestId - Optional request ID for tracking
+ * @returns Standardized error response
+ *
+ * @example
+ * ```typescript
+ * const response = errorResponse('VALIDATION_ERROR', 'Invalid input', { field: 'email' });
+ * // { success: false, error: { code: 'VALIDATION_ERROR', message: 'Invalid input', details: {...}, traceId: '...' }, meta: {...} }
+ * ```
+ */
+export function errorResponse(code, message, details, requestId) {
+    const config = getConfig();
+    const traceId = getOrCreateTraceId();
+    const error = {
+        code,
+        message,
+    };
+    // Include details in non-production environments or if explicitly allowed
+    if (details && config.env !== 'production') {
+        error.details = details;
+    }
+    if (traceId) {
+        error.traceId = traceId;
+    }
+    return {
+        success: false,
+        error,
+        meta: createMeta({ requestId }),
+    };
+}
+/**
+ * Create a paginated API response (page-based)
+ *
+ * @typeParam T - The type of items in the response
+ * @param items - Array of items for the current page
+ * @param options - Pagination options including page, pageSize, and totalItems
+ * @returns Standardized paginated response
+ *
+ * @example
+ * ```typescript
+ * const response = paginatedResponse(items, { page: 1, pageSize: 20, totalItems: 100 });
+ * // { success: true, data: [...], meta: { pagination: { page: 1, pageSize: 20, totalItems: 100, totalPages: 5 }, ... } }
+ * ```
+ */
+export function paginatedResponse(items, options) {
+    const totalPages = Math.ceil(options.totalItems / options.pageSize);
+    return {
+        success: true,
+        data: items,
+        meta: createMeta({
+            requestId: options.requestId,
+            pagination: {
+                page: options.page,
+                pageSize: options.pageSize,
+                totalItems: options.totalItems,
+                totalPages,
+            },
+        }),
+    };
+}
+/**
+ * Create a cursor-based paginated API response
+ *
+ * @typeParam T - The type of items in the response
+ * @param items - Array of items for the current page
+ * @param options - Cursor pagination options
+ * @returns Standardized cursor-paginated response
+ *
+ * @example
+ * ```typescript
+ * const response = cursorPaginatedResponse(items, { nextCursor: 'abc123', hasMore: true });
+ * // { success: true, data: [...], meta: { cursor: { nextCursor: 'abc123', hasMore: true, count: 10 }, ... } }
+ * ```
+ */
+export function cursorPaginatedResponse(items, options) {
+    const cursor = {
+        hasMore: options.hasMore,
+        count: items.length,
+    };
+    if (options.nextCursor) {
+        cursor.nextCursor = options.nextCursor;
+    }
+    if (options.prevCursor) {
+        cursor.prevCursor = options.prevCursor;
+    }
+    return {
+        success: true,
+        data: items,
+        meta: createMeta({
+            requestId: options.requestId,
+            cursor,
+        }),
+    };
+}
+/**
+ * Create a "created" response (HTTP 201)
+ *
+ * @typeParam T - The type of the created resource
+ * @param data - The created resource data
+ * @param options - Optional metadata configuration
+ * @returns Standardized success response for created resources
+ */
+export function createdResponse(data, options) {
+    return successResponse(data, options);
+}
+/**
+ * Create an "accepted" response (HTTP 202) for async operations
+ *
+ * @typeParam T - The type of the response data
+ * @param data - Optional response data (e.g., tracking information)
+ * @param options - Optional metadata configuration
+ * @returns Standardized success response for accepted requests
+ */
+export function acceptedResponse(data, options) {
+    return {
+        success: true,
+        data,
+        meta: createMeta(options),
+    };
+}
+/**
+ * Map VorionError to appropriate HTTP status code
+ *
+ * @param error - The VorionError instance
+ * @returns HTTP status code
+ */
+export function getHttpStatusFromError(error) {
+    // Use the error's statusCode if available
+    if (error.statusCode) {
+        return error.statusCode;
+    }
+    // Fallback based on error type
+    if (error instanceof ValidationError)
+        return HttpStatus.BAD_REQUEST;
+    if (error instanceof NotFoundError)
+        return HttpStatus.NOT_FOUND;
+    if (error instanceof UnauthorizedError)
+        return HttpStatus.UNAUTHORIZED;
+    if (error instanceof ForbiddenError)
+        return HttpStatus.FORBIDDEN;
+    if (error instanceof ConflictError)
+        return HttpStatus.CONFLICT;
+    if (error instanceof RateLimitError)
+        return HttpStatus.TOO_MANY_REQUESTS;
+    if (error instanceof ConfigurationError)
+        return HttpStatus.INTERNAL_SERVER_ERROR;
+    if (error instanceof DatabaseError)
+        return HttpStatus.INTERNAL_SERVER_ERROR;
+    if (error instanceof ExternalServiceError)
+        return HttpStatus.BAD_GATEWAY;
+    if (error instanceof TimeoutError)
+        return HttpStatus.GATEWAY_TIMEOUT;
+    return HttpStatus.INTERNAL_SERVER_ERROR;
+}
+/**
+ * Map error code to HTTP status code
+ *
+ * @param code - The error code string
+ * @returns HTTP status code
+ */
+export function getHttpStatusFromCode(code) {
+    const codeMap = {
+        // Validation errors
+        VALIDATION_ERROR: HttpStatus.BAD_REQUEST,
+        INVALID_INPUT: HttpStatus.BAD_REQUEST,
+        INVALID_STATE_TRANSITION: HttpStatus.BAD_REQUEST,
+        INVALID_STATE: HttpStatus.BAD_REQUEST,
+        POLICY_VALIDATION_ERROR: HttpStatus.BAD_REQUEST,
+        ESCALATION_ERROR: HttpStatus.BAD_REQUEST,
+        // Authentication errors
+        UNAUTHORIZED: HttpStatus.UNAUTHORIZED,
+        TOKEN_INVALID: HttpStatus.UNAUTHORIZED,
+        TOKEN_REVOKED: HttpStatus.UNAUTHORIZED,
+        TOKEN_EXPIRED: HttpStatus.UNAUTHORIZED,
+        // Authorization errors
+        FORBIDDEN: HttpStatus.FORBIDDEN,
+        TRUST_INSUFFICIENT: HttpStatus.FORBIDDEN,
+        // Not found errors
+        NOT_FOUND: HttpStatus.NOT_FOUND,
+        INTENT_NOT_FOUND: HttpStatus.NOT_FOUND,
+        ESCALATION_NOT_FOUND: HttpStatus.NOT_FOUND,
+        POLICY_NOT_FOUND: HttpStatus.NOT_FOUND,
+        AUDIT_RECORD_NOT_FOUND: HttpStatus.NOT_FOUND,
+        WEBHOOK_NOT_FOUND: HttpStatus.NOT_FOUND,
+        JOB_NOT_FOUND: HttpStatus.NOT_FOUND,
+        APPROVER_NOT_FOUND: HttpStatus.NOT_FOUND,
+        // Conflict errors
+        CONFLICT: HttpStatus.CONFLICT,
+        INTENT_LOCKED: HttpStatus.CONFLICT,
+        POLICY_NOT_DRAFT: HttpStatus.CONFLICT,
+        // Rate limit errors
+        RATE_LIMIT_EXCEEDED: HttpStatus.TOO_MANY_REQUESTS,
+        INTENT_RATE_LIMIT: HttpStatus.TOO_MANY_REQUESTS,
+        // Server errors
+        INTERNAL_ERROR: HttpStatus.INTERNAL_SERVER_ERROR,
+        VORION_ERROR: HttpStatus.INTERNAL_SERVER_ERROR,
+        DATABASE_ERROR: HttpStatus.INTERNAL_SERVER_ERROR,
+        CONFIGURATION_ERROR: HttpStatus.INTERNAL_SERVER_ERROR,
+        ENCRYPTION_ERROR: HttpStatus.INTERNAL_SERVER_ERROR,
+        ENQUEUE_FAILED: HttpStatus.INTERNAL_SERVER_ERROR,
+        // External service errors
+        EXTERNAL_SERVICE_ERROR: HttpStatus.BAD_GATEWAY,
+        // Timeout errors
+        TIMEOUT: HttpStatus.GATEWAY_TIMEOUT,
+    };
+    return codeMap[code] ?? HttpStatus.INTERNAL_SERVER_ERROR;
+}
+/**
+ * Create an error response from a VorionError
+ *
+ * @param error - The VorionError instance
+ * @param requestId - Optional request ID for tracking
+ * @returns Standardized error response
+ */
+export function errorResponseFromVorionError(error, requestId) {
+    const config = getConfig();
+    const traceId = getOrCreateTraceId();
+    const apiError = {
+        code: error.code,
+        message: config.env === 'production' ? sanitizeErrorMessage(error.message) : error.message,
+    };
+    // Include details in non-production or if error explicitly provides them
+    if (error.details && config.env !== 'production') {
+        apiError.details = error.details;
+    }
+    if (traceId) {
+        apiError.traceId = traceId;
+    }
+    return {
+        success: false,
+        error: apiError,
+        meta: createMeta({ requestId }),
+    };
+}
+/**
+ * Create an error response from any error (including non-VorionError)
+ *
+ * @param error - The error (VorionError or standard Error)
+ * @param requestId - Optional request ID for tracking
+ * @returns Standardized error response with appropriate HTTP status
+ */
+export function errorResponseFromError(error, requestId) {
+    if (isVorionError(error)) {
+        return {
+            response: errorResponseFromVorionError(error, requestId),
+            status: getHttpStatusFromError(error),
+        };
+    }
+    const config = getConfig();
+    const traceId = getOrCreateTraceId();
+    const message = error instanceof Error ? error.message : 'An unexpected error occurred';
+    const apiError = {
+        code: 'INTERNAL_ERROR',
+        message: config.env === 'production' ? 'An unexpected error occurred' : message,
+    };
+    if (traceId) {
+        apiError.traceId = traceId;
+    }
+    return {
+        response: {
+            success: false,
+            error: apiError,
+            meta: createMeta({ requestId }),
+        },
+        status: HttpStatus.INTERNAL_SERVER_ERROR,
+    };
+}
+/**
+ * Sanitize error message for production
+ * Removes potentially sensitive information from error messages
+ *
+ * @param message - The original error message
+ * @returns Sanitized message safe for production
+ */
+function sanitizeErrorMessage(message) {
+    // List of patterns that might leak sensitive information
+    const sensitivePatterns = [
+        /password/i,
+        /secret/i,
+        /token/i,
+        /key/i,
+        /credential/i,
+        /connection string/i,
+        /database.*error/i,
+        /sql.*error/i,
+        /internal.*error/i,
+    ];
+    for (const pattern of sensitivePatterns) {
+        if (pattern.test(message)) {
+            return 'An error occurred while processing your request';
+        }
+    }
+    // Remove stack traces if present
+    const stackTraceIndex = message.indexOf('\n    at ');
+    if (stackTraceIndex !== -1) {
+        return message.substring(0, stackTraceIndex);
+    }
+    return message;
+}
+/**
+ * Type guard to check if a response is successful
+ *
+ * @param response - The API response to check
+ * @returns True if the response indicates success
+ */
+export function isSuccessResponse(response) {
+    return response.success === true && response.data !== undefined;
+}
+/**
+ * Type guard to check if a response is an error
+ *
+ * @param response - The API response to check
+ * @returns True if the response indicates an error
+ */
+export function isErrorResponse(response) {
+    return response.success === false && response.error !== undefined;
+}
+//# sourceMappingURL=response.js.map

package/dist/intent/response.js.map

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