@brightchain/brightchain-api-lib 0.2.1 → 0.5.0

package/src/lib/controllers/api/blocks.d.ts

@@ -0,0 +1,246 @@
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { ApiErrorResponse, ApiRequestHandler, TypedHandlers } from '@digitaldefiance/node-express-suite';
+import { IBrightChainApplication } from '../../interfaces/application';
+import { IBrightenBlockResponse, IDeleteBlockResponse, IGetBlockMetadataResponse, IGetBlockResponse, IStoreBlockResponse } from '../../interfaces/blockResponses';
+import { DefaultBackendIdType } from '../../shared-types';
+import { BaseController } from '../base';
+/**
+ * Error codes for block API operations
+ * @deprecated Use ErrorCode from '../../utils/errorResponse' instead
+ */
+export declare enum BlockErrorCode {
+    BLOCK_NOT_FOUND = "BLOCK_NOT_FOUND",
+    BLOCK_VALIDATION_FAILED = "BLOCK_VALIDATION_FAILED",
+    BLOCK_SIZE_MISMATCH = "BLOCK_SIZE_MISMATCH",
+    INSUFFICIENT_RANDOM_BLOCKS = "INSUFFICIENT_RANDOM_BLOCKS",
+    BLOCK_ALREADY_EXISTS = "BLOCK_ALREADY_EXISTS",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+type BlockApiResponse = IStoreBlockResponse | IGetBlockResponse | IGetBlockMetadataResponse | IDeleteBlockResponse | IBrightenBlockResponse | ApiErrorResponse;
+interface BlocksHandlers extends TypedHandlers {
+    storeBlock: ApiRequestHandler<IStoreBlockResponse | ApiErrorResponse>;
+    getBlock: ApiRequestHandler<IGetBlockResponse | ApiErrorResponse>;
+    getBlockMetadata: ApiRequestHandler<IGetBlockMetadataResponse | ApiErrorResponse>;
+    deleteBlock: ApiRequestHandler<IDeleteBlockResponse | ApiErrorResponse>;
+    brightenBlock: ApiRequestHandler<IBrightenBlockResponse | ApiErrorResponse>;
+}
+/**
+ * Controller for block storage operations.
+ *
+ * Provides REST API endpoints for storing, retrieving, and managing blocks
+ * in the BrightChain distributed storage system.
+ *
+ * ## Endpoints
+ *
+ * ### POST /api/blocks
+ * Store a new block with optional durability settings.
+ *
+ * **Request Body:**
+ * - `data` (string, required): Base64-encoded block data
+ * - `canRead` (boolean, optional): Whether the block can be read (default: true)
+ * - `canPersist` (boolean, optional): Whether the block can be persisted (default: true)
+ * - `options` (object, optional): Block storage options
+ *   - `expiresAt` (string): ISO date when the block expires
+ *   - `durabilityLevel` (string): 'ephemeral' | 'standard' | 'high_durability'
+ *
+ * **Response:** Block ID and metadata
+ *
+ * ### GET /api/blocks/:blockId
+ * Retrieve a block by its ID.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Hex-encoded block checksum
+ *
+ * **Response:** Block data (base64) and metadata
+ *
+ * ### GET /api/blocks/:blockId/metadata
+ * Get metadata for a block without retrieving the data.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Hex-encoded block checksum
+ *
+ * **Response:** Block metadata including durability level, access count, etc.
+ *
+ * ### DELETE /api/blocks/:blockId
+ * Delete a block and its associated parity blocks.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Hex-encoded block checksum
+ *
+ * **Response:** Success confirmation
+ *
+ * ### POST /api/blocks/brighten
+ * Brighten a block by XORing it with random blocks for Owner-Free storage.
+ *
+ * **Request Body:**
+ * - `blockId` (string, required): Hex-encoded block checksum to brighten
+ * - `randomBlockCount` (number, required): Number of random blocks to XOR with
+ *
+ * **Response:** Brightened block ID and list of random block IDs used
+ *
+ * @requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 11.7
+ */
+export declare class BlocksController<TID extends PlatformID = DefaultBackendIdType> extends BaseController<TID, BlockApiResponse, BlocksHandlers, CoreLanguageCode> {
+    private blocksService;
+    constructor(application: IBrightChainApplication<TID>);
+    protected initRouteDefinitions(): void;
+    /**
+     * POST /api/blocks
+     * Store a new block with optional durability settings.
+     *
+     * The block data is stored with the configured durability level, which determines
+     * how many parity blocks are generated for FEC recovery:
+     * - 'ephemeral': No parity blocks
+     * - 'standard': 1 parity block
+     * - 'high_durability': 2+ parity blocks
+     *
+     * @param req - Request containing base64-encoded block data and options
+     * @returns Block ID and metadata on success, or error response
+     *
+     * @example
+     * ```json
+     * // Request
+     * POST /api/blocks
+     * {
+     *   "data": "SGVsbG8gV29ybGQ=",
+     *   "options": {
+     *     "durabilityLevel": "standard",
+     *     "expiresAt": "2025-12-31T23:59:59Z"
+     *   }
+     * }
+     *
+     * // Response
+     * {
+     *   "blockId": "abc123...",
+     *   "success": true,
+     *   "metadata": {
+     *     "blockId": "abc123...",
+     *     "durabilityLevel": "standard",
+     *     "parityBlockIds": ["abc123.p0"],
+     *     ...
+     *   }
+     * }
+     * ```
+     */
+    private handleStoreBlock;
+    /**
+     * GET /api/blocks/:blockId
+     * Retrieve a block by its ID.
+     *
+     * Returns the block data and metadata. The access count and last access
+     * timestamp in the metadata are updated on each retrieval.
+     *
+     * @param req - Request containing the block ID parameter
+     * @returns Block data (base64) and metadata on success, or 404 if not found
+     *
+     * @example
+     * ```json
+     * // Request
+     * GET /api/blocks/abc123...
+     *
+     * // Response
+     * {
+     *   "blockId": "abc123...",
+     *   "data": "SGVsbG8gV29ybGQ=",
+     *   "canRead": true,
+     *   "canPersist": true,
+     *   "metadata": { ... }
+     * }
+     * ```
+     */
+    private handleGetBlock;
+    /**
+     * GET /api/blocks/:blockId/metadata
+     * Get metadata for a block without retrieving the data.
+     *
+     * Useful for checking block status, durability level, replication status,
+     * and access patterns without the overhead of retrieving the full block data.
+     *
+     * @param req - Request containing the block ID parameter
+     * @returns Block metadata on success, or 404 if not found
+     *
+     * @example
+     * ```json
+     * // Request
+     * GET /api/blocks/abc123.../metadata
+     *
+     * // Response
+     * {
+     *   "blockId": "abc123...",
+     *   "metadata": {
+     *     "blockId": "abc123...",
+     *     "createdAt": "2025-01-15T10:00:00Z",
+     *     "durabilityLevel": "standard",
+     *     "parityBlockIds": ["abc123.p0"],
+     *     "accessCount": 5,
+     *     "lastAccessedAt": "2025-01-16T14:30:00Z",
+     *     "replicationStatus": "replicated",
+     *     "size": 4096,
+     *     "checksum": "abc123..."
+     *   }
+     * }
+     * ```
+     */
+    private handleGetBlockMetadata;
+    /**
+     * DELETE /api/blocks/:blockId
+     * Delete a block and its associated parity blocks.
+     *
+     * This operation removes:
+     * - The block data file
+     * - All associated parity block files
+     * - The block metadata
+     *
+     * @param req - Request containing the block ID parameter
+     * @returns Success confirmation on success, or 404 if not found
+     *
+     * @example
+     * ```json
+     * // Request
+     * DELETE /api/blocks/abc123...
+     *
+     * // Response
+     * {
+     *   "blockId": "abc123...",
+     *   "success": true
+     * }
+     * ```
+     */
+    private handleDeleteBlock;
+    /**
+     * POST /api/blocks/brighten
+     * Brighten a block by XORing it with random blocks for Owner-Free storage.
+     *
+     * This operation implements the Owner-Free storage pattern where the original
+     * data cannot be reconstructed without all the random blocks used in the
+     * XOR operation. The brightened block is stored and its ID is returned along
+     * with the IDs of all random blocks used.
+     *
+     * @param req - Request containing block ID and random block count
+     * @returns Brightened block ID and list of random block IDs used
+     * @throws INSUFFICIENT_RANDOM_BLOCKS if not enough random blocks are available
+     *
+     * @example
+     * ```json
+     * // Request
+     * POST /api/blocks/brighten
+     * {
+     *   "blockId": "abc123...",
+     *   "randomBlockCount": 3
+     * }
+     *
+     * // Response
+     * {
+     *   "brightenedBlockId": "def456...",
+     *   "randomBlockIds": ["rand1...", "rand2...", "rand3..."],
+     *   "originalBlockId": "abc123..."
+     * }
+     * ```
+     */
+    private handleBrightenBlock;
+}
+export {};
+//# sourceMappingURL=blocks.d.ts.map

package/src/lib/controllers/api/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/controllers/api/blocks.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EAEd,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAQvE,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAQ1D,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGzC;;;GAGG;AACH,oBAAY,cAAc;IACxB,eAAe,oBAAoB;IACnC,uBAAuB,4BAA4B;IACnD,mBAAmB,wBAAwB;IAC3C,0BAA0B,+BAA+B;IACzD,oBAAoB,yBAAyB;IAC7C,gBAAgB,qBAAqB;IACrC,YAAY,iBAAiB;IAC7B,cAAc,mBAAmB;CAClC;AAED,KAAK,gBAAgB,GACjB,mBAAmB,GACnB,iBAAiB,GACjB,yBAAyB,GACzB,oBAAoB,GACpB,sBAAsB,GACtB,gBAAgB,CAAC;AAErB,UAAU,cAAe,SAAQ,aAAa;IAC5C,UAAU,EAAE,iBAAiB,CAAC,mBAAmB,GAAG,gBAAgB,CAAC,CAAC;IACtE,QAAQ,EAAE,iBAAiB,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,CAAC;IAClE,gBAAgB,EAAE,iBAAiB,CACjC,yBAAyB,GAAG,gBAAgB,CAC7C,CAAC;IACF,WAAW,EAAE,iBAAiB,CAAC,oBAAoB,GAAG,gBAAgB,CAAC,CAAC;IACxE,aAAa,EAAE,iBAAiB,CAAC,sBAAsB,GAAG,gBAAgB,CAAC,CAAC;CAC7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,qBAAa,gBAAgB,CAC3B,GAAG,SAAS,UAAU,GAAG,oBAAoB,CAC7C,SAAQ,cAAc,CACtB,GAAG,EACH,gBAAgB,EAChB,cAAc,EACd,gBAAgB,CACjB;IACC,OAAO,CAAC,aAAa,CAAgB;gBAEzB,WAAW,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAOrD,SAAS,CAAC,oBAAoB,IAAI,IAAI;IAsCtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,OAAO,CAAC,gBAAgB,CA+DtB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,cAAc,CA4BpB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,OAAO,CAAC,sBAAsB,CA6B5B;IAEF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,iBAAiB,CAyBvB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,CAAC,mBAAmB,CAoCzB;CACH"}

package/src/lib/controllers/api/blocks.js

@@ -0,0 +1,414 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlocksController = exports.BlockErrorCode = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+const node_express_suite_1 = require("@digitaldefiance/node-express-suite");
+const blockServiceFactory_1 = require("../../services/blockServiceFactory");
+const errorResponse_1 = require("../../utils/errorResponse");
+const base_1 = require("../base");
+/**
+ * Error codes for block API operations
+ * @deprecated Use ErrorCode from '../../utils/errorResponse' instead
+ */
+var BlockErrorCode;
+(function (BlockErrorCode) {
+    BlockErrorCode["BLOCK_NOT_FOUND"] = "BLOCK_NOT_FOUND";
+    BlockErrorCode["BLOCK_VALIDATION_FAILED"] = "BLOCK_VALIDATION_FAILED";
+    BlockErrorCode["BLOCK_SIZE_MISMATCH"] = "BLOCK_SIZE_MISMATCH";
+    BlockErrorCode["INSUFFICIENT_RANDOM_BLOCKS"] = "INSUFFICIENT_RANDOM_BLOCKS";
+    BlockErrorCode["BLOCK_ALREADY_EXISTS"] = "BLOCK_ALREADY_EXISTS";
+    BlockErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    BlockErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    BlockErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(BlockErrorCode || (exports.BlockErrorCode = BlockErrorCode = {}));
+/**
+ * Controller for block storage operations.
+ *
+ * Provides REST API endpoints for storing, retrieving, and managing blocks
+ * in the BrightChain distributed storage system.
+ *
+ * ## Endpoints
+ *
+ * ### POST /api/blocks
+ * Store a new block with optional durability settings.
+ *
+ * **Request Body:**
+ * - `data` (string, required): Base64-encoded block data
+ * - `canRead` (boolean, optional): Whether the block can be read (default: true)
+ * - `canPersist` (boolean, optional): Whether the block can be persisted (default: true)
+ * - `options` (object, optional): Block storage options
+ *   - `expiresAt` (string): ISO date when the block expires
+ *   - `durabilityLevel` (string): 'ephemeral' | 'standard' | 'high_durability'
+ *
+ * **Response:** Block ID and metadata
+ *
+ * ### GET /api/blocks/:blockId
+ * Retrieve a block by its ID.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Hex-encoded block checksum
+ *
+ * **Response:** Block data (base64) and metadata
+ *
+ * ### GET /api/blocks/:blockId/metadata
+ * Get metadata for a block without retrieving the data.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Hex-encoded block checksum
+ *
+ * **Response:** Block metadata including durability level, access count, etc.
+ *
+ * ### DELETE /api/blocks/:blockId
+ * Delete a block and its associated parity blocks.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Hex-encoded block checksum
+ *
+ * **Response:** Success confirmation
+ *
+ * ### POST /api/blocks/brighten
+ * Brighten a block by XORing it with random blocks for Owner-Free storage.
+ *
+ * **Request Body:**
+ * - `blockId` (string, required): Hex-encoded block checksum to brighten
+ * - `randomBlockCount` (number, required): Number of random blocks to XOR with
+ *
+ * **Response:** Brightened block ID and list of random block IDs used
+ *
+ * @requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 11.7
+ */
+class BlocksController extends base_1.BaseController {
+    constructor(application) {
+        super(application);
+        /**
+         * POST /api/blocks
+         * Store a new block with optional durability settings.
+         *
+         * The block data is stored with the configured durability level, which determines
+         * how many parity blocks are generated for FEC recovery:
+         * - 'ephemeral': No parity blocks
+         * - 'standard': 1 parity block
+         * - 'high_durability': 2+ parity blocks
+         *
+         * @param req - Request containing base64-encoded block data and options
+         * @returns Block ID and metadata on success, or error response
+         *
+         * @example
+         * ```json
+         * // Request
+         * POST /api/blocks
+         * {
+         *   "data": "SGVsbG8gV29ybGQ=",
+         *   "options": {
+         *     "durabilityLevel": "standard",
+         *     "expiresAt": "2025-12-31T23:59:59Z"
+         *   }
+         * }
+         *
+         * // Response
+         * {
+         *   "blockId": "abc123...",
+         *   "success": true,
+         *   "metadata": {
+         *     "blockId": "abc123...",
+         *     "durabilityLevel": "standard",
+         *     "parityBlockIds": ["abc123.p0"],
+         *     ...
+         *   }
+         * }
+         * ```
+         */
+        this.handleStoreBlock = async (req) => {
+            try {
+                const { data, canRead = true, canPersist = true, options, } = req.body;
+                // Validate required fields
+                if (!data) {
+                    return (0, errorResponse_1.validationError)('Missing required field: data');
+                }
+                // Get authenticated member from session
+                const sessionsController = this.application.getController('sessions');
+                let member;
+                try {
+                    member = sessionsController.getMemberFromSession(req.headers.authorization);
+                }
+                catch {
+                    return (0, errorResponse_1.unauthorizedError)();
+                }
+                // Parse options if provided
+                const blockStoreOptions = options
+                    ? {
+                        expiresAt: options.expiresAt
+                            ? new Date(options.expiresAt)
+                            : undefined,
+                        durabilityLevel: options.durabilityLevel,
+                    }
+                    : undefined;
+                const result = await this.blocksService.storeBlock(Buffer.from(data, 'base64'), member, canRead, canPersist, blockStoreOptions);
+                return {
+                    statusCode: 200,
+                    response: {
+                        blockId: result.blockId,
+                        success: true,
+                        metadata: result.metadata,
+                    },
+                };
+            }
+            catch (_error) {
+                if (_error instanceof brightchain_lib_1.StoreError) {
+                    return (0, errorResponse_1.mapStoreError)(_error);
+                }
+                return (0, errorResponse_1.handleError)(_error);
+            }
+        };
+        /**
+         * GET /api/blocks/:blockId
+         * Retrieve a block by its ID.
+         *
+         * Returns the block data and metadata. The access count and last access
+         * timestamp in the metadata are updated on each retrieval.
+         *
+         * @param req - Request containing the block ID parameter
+         * @returns Block data (base64) and metadata on success, or 404 if not found
+         *
+         * @example
+         * ```json
+         * // Request
+         * GET /api/blocks/abc123...
+         *
+         * // Response
+         * {
+         *   "blockId": "abc123...",
+         *   "data": "SGVsbG8gV29ybGQ=",
+         *   "canRead": true,
+         *   "canPersist": true,
+         *   "metadata": { ... }
+         * }
+         * ```
+         */
+        this.handleGetBlock = async (req) => {
+            try {
+                const { blockId } = req.params;
+                if (!blockId) {
+                    return (0, errorResponse_1.validationError)('Missing required parameter: blockId');
+                }
+                const block = await this.blocksService.getBlock(blockId);
+                return {
+                    statusCode: 200,
+                    response: {
+                        blockId,
+                        data: block.data,
+                        canRead: true,
+                        canPersist: true,
+                        metadata: block.metadata,
+                    },
+                };
+            }
+            catch (_error) {
+                if (_error instanceof brightchain_lib_1.StoreError) {
+                    return (0, errorResponse_1.mapStoreError)(_error);
+                }
+                return (0, errorResponse_1.handleError)(_error);
+            }
+        };
+        /**
+         * GET /api/blocks/:blockId/metadata
+         * Get metadata for a block without retrieving the data.
+         *
+         * Useful for checking block status, durability level, replication status,
+         * and access patterns without the overhead of retrieving the full block data.
+         *
+         * @param req - Request containing the block ID parameter
+         * @returns Block metadata on success, or 404 if not found
+         *
+         * @example
+         * ```json
+         * // Request
+         * GET /api/blocks/abc123.../metadata
+         *
+         * // Response
+         * {
+         *   "blockId": "abc123...",
+         *   "metadata": {
+         *     "blockId": "abc123...",
+         *     "createdAt": "2025-01-15T10:00:00Z",
+         *     "durabilityLevel": "standard",
+         *     "parityBlockIds": ["abc123.p0"],
+         *     "accessCount": 5,
+         *     "lastAccessedAt": "2025-01-16T14:30:00Z",
+         *     "replicationStatus": "replicated",
+         *     "size": 4096,
+         *     "checksum": "abc123..."
+         *   }
+         * }
+         * ```
+         */
+        this.handleGetBlockMetadata = async (req) => {
+            try {
+                const { blockId } = req.params;
+                if (!blockId) {
+                    return (0, errorResponse_1.validationError)('Missing required parameter: blockId');
+                }
+                const metadata = await this.blocksService.getBlockMetadata(blockId);
+                if (!metadata) {
+                    return (0, errorResponse_1.notFoundError)('Block', blockId);
+                }
+                return {
+                    statusCode: 200,
+                    response: {
+                        blockId,
+                        metadata,
+                    },
+                };
+            }
+            catch (_error) {
+                if (_error instanceof brightchain_lib_1.StoreError) {
+                    return (0, errorResponse_1.mapStoreError)(_error);
+                }
+                return (0, errorResponse_1.handleError)(_error);
+            }
+        };
+        /**
+         * DELETE /api/blocks/:blockId
+         * Delete a block and its associated parity blocks.
+         *
+         * This operation removes:
+         * - The block data file
+         * - All associated parity block files
+         * - The block metadata
+         *
+         * @param req - Request containing the block ID parameter
+         * @returns Success confirmation on success, or 404 if not found
+         *
+         * @example
+         * ```json
+         * // Request
+         * DELETE /api/blocks/abc123...
+         *
+         * // Response
+         * {
+         *   "blockId": "abc123...",
+         *   "success": true
+         * }
+         * ```
+         */
+        this.handleDeleteBlock = async (req) => {
+            try {
+                const { blockId } = req.params;
+                if (!blockId) {
+                    return (0, errorResponse_1.validationError)('Missing required parameter: blockId');
+                }
+                await this.blocksService.deleteBlock(blockId);
+                return {
+                    statusCode: 200,
+                    response: {
+                        blockId,
+                        success: true,
+                    },
+                };
+            }
+            catch (_error) {
+                if (_error instanceof brightchain_lib_1.StoreError) {
+                    return (0, errorResponse_1.mapStoreError)(_error);
+                }
+                return (0, errorResponse_1.handleError)(_error);
+            }
+        };
+        /**
+         * POST /api/blocks/brighten
+         * Brighten a block by XORing it with random blocks for Owner-Free storage.
+         *
+         * This operation implements the Owner-Free storage pattern where the original
+         * data cannot be reconstructed without all the random blocks used in the
+         * XOR operation. The brightened block is stored and its ID is returned along
+         * with the IDs of all random blocks used.
+         *
+         * @param req - Request containing block ID and random block count
+         * @returns Brightened block ID and list of random block IDs used
+         * @throws INSUFFICIENT_RANDOM_BLOCKS if not enough random blocks are available
+         *
+         * @example
+         * ```json
+         * // Request
+         * POST /api/blocks/brighten
+         * {
+         *   "blockId": "abc123...",
+         *   "randomBlockCount": 3
+         * }
+         *
+         * // Response
+         * {
+         *   "brightenedBlockId": "def456...",
+         *   "randomBlockIds": ["rand1...", "rand2...", "rand3..."],
+         *   "originalBlockId": "abc123..."
+         * }
+         * ```
+         */
+        this.handleBrightenBlock = async (req) => {
+            try {
+                const { blockId, randomBlockCount } = req.body;
+                // Validate required fields
+                if (!blockId) {
+                    return (0, errorResponse_1.validationError)('Missing required field: blockId');
+                }
+                if (randomBlockCount === undefined || randomBlockCount < 1) {
+                    return (0, errorResponse_1.validationError)('randomBlockCount must be a positive integer');
+                }
+                const result = await this.blocksService.brightenBlock(blockId, randomBlockCount);
+                return {
+                    statusCode: 200,
+                    response: {
+                        brightenedBlockId: result.brightenedBlockId,
+                        randomBlockIds: result.randomBlockIds,
+                        originalBlockId: result.originalBlockId,
+                    },
+                };
+            }
+            catch (_error) {
+                if (_error instanceof brightchain_lib_1.StoreError) {
+                    return (0, errorResponse_1.mapStoreError)(_error);
+                }
+                return (0, errorResponse_1.handleError)(_error);
+            }
+        };
+        this.blocksService = blockServiceFactory_1.BlockServiceFactory.getInstance().getService(application);
+    }
+    initRouteDefinitions() {
+        this.routeDefinitions = [
+            (0, node_express_suite_1.routeConfig)('post', '/', {
+                useAuthentication: true,
+                useCryptoAuthentication: false,
+                handlerKey: 'storeBlock',
+            }),
+            (0, node_express_suite_1.routeConfig)('get', '/:blockId', {
+                handlerKey: 'getBlock',
+                useAuthentication: true,
+                useCryptoAuthentication: false,
+            }),
+            (0, node_express_suite_1.routeConfig)('get', '/:blockId/metadata', {
+                handlerKey: 'getBlockMetadata',
+                useAuthentication: true,
+                useCryptoAuthentication: false,
+            }),
+            (0, node_express_suite_1.routeConfig)('delete', '/:blockId', {
+                handlerKey: 'deleteBlock',
+                useAuthentication: true,
+                useCryptoAuthentication: false,
+            }),
+            (0, node_express_suite_1.routeConfig)('post', '/brighten', {
+                handlerKey: 'brightenBlock',
+                useAuthentication: true,
+                useCryptoAuthentication: false,
+            }),
+        ];
+        this.handlers = {
+            storeBlock: this.handleStoreBlock.bind(this),
+            getBlock: this.handleGetBlock.bind(this),
+            getBlockMetadata: this.handleGetBlockMetadata.bind(this),
+            deleteBlock: this.handleDeleteBlock.bind(this),
+            brightenBlock: this.handleBrightenBlock.bind(this),
+        };
+    }
+}
+exports.BlocksController = BlocksController;
+//# sourceMappingURL=blocks.js.map

package/src/lib/controllers/api/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/controllers/api/blocks.ts"],"names":[],"mappings":";;;AAAA,uDAAuD;AACvD,kEAIsC;AAGtC,4EAK6C;AAiB7C,4EAAyE;AAEzE,6DAMmC;AACnC,kCAAyC;AAGzC;;;GAGG;AACH,IAAY,cASX;AATD,WAAY,cAAc;IACxB,qDAAmC,CAAA;IACnC,qEAAmD,CAAA;IACnD,6DAA2C,CAAA;IAC3C,2EAAyD,CAAA;IACzD,+DAA6C,CAAA;IAC7C,uDAAqC,CAAA;IACrC,+CAA6B,CAAA;IAC7B,mDAAiC,CAAA;AACnC,CAAC,EATW,cAAc,8BAAd,cAAc,QASzB;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAa,gBAEX,SAAQ,qBAKT;IAGC,YAAY,WAAyC;QACnD,KAAK,CAAC,WAAW,CAAC,CAAC;QA4CrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAqCG;QACK,qBAAgB,GAEpB,KAAK,EAAE,GAAG,EAAE,EAAE;YAChB,IAAI,CAAC;gBACH,MAAM,EACJ,IAAI,EACJ,OAAO,GAAG,IAAI,EACd,UAAU,GAAG,IAAI,EACjB,OAAO,GACR,GAAI,GAAoC,CAAC,IAAI,CAAC;gBAE/C,2BAA2B;gBAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;oBACV,OAAO,IAAA,+BAAe,EAAC,8BAA8B,CAAC,CAAC;gBACzD,CAAC;gBAED,wCAAwC;gBACxC,MAAM,kBAAkB,GACtB,IAAI,CAAC,WAAW,CAAC,aAAa,CAAqB,UAAU,CAAC,CAAC;gBAEjE,IAAI,MAAM,CAAC;gBACX,IAAI,CAAC;oBACH,MAAM,GAAG,kBAAkB,CAAC,oBAAoB,CAC7C,GAAG,CAAC,OAAe,CAAC,aAAuB,CAC7C,CAAC;gBACJ,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,IAAA,iCAAiB,GAAE,CAAC;gBAC7B,CAAC;gBAED,4BAA4B;gBAC5B,MAAM,iBAAiB,GAAkC,OAAO;oBAC9D,CAAC,CAAC;wBACE,SAAS,EAAE,OAAO,CAAC,SAAS;4BAC1B,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;4BAC7B,CAAC,CAAC,SAAS;wBACb,eAAe,EAAE,OAAO,CAAC,eAEZ;qBACd;oBACH,CAAC,CAAC,SAAS,CAAC;gBAEd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,UAAU,CAChD,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAC3B,MAAM,EACN,OAAO,EACP,UAAU,EACV,iBAAiB,CAClB,CAAC;gBAEF,OAAO;oBACL,UAAU,EAAE,GAAG;oBACf,QAAQ,EAAE;wBACR,OAAO,EAAE,MAAM,CAAC,OAAO;wBACvB,OAAO,EAAE,IAAI;wBACb,QAAQ,EAAE,MAAM,CAAC,QAAQ;qBAC1B;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,IAAI,MAAM,YAAY,4BAAU,EAAE,CAAC;oBACjC,OAAO,IAAA,6BAAa,EAAC,MAAM,CAAC,CAAC;gBAC/B,CAAC;gBACD,OAAO,IAAA,2BAAW,EAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC;QAEF;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;QACK,mBAAc,GAElB,KAAK,EAAE,GAAG,EAAE,EAAE;YAChB,IAAI,CAAC;gBACH,MAAM,EAAE,OAAO,EAAE,GAAI,GAAkC,CAAC,MAAM,CAAC;gBAE/D,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,IAAA,+BAAe,EAAC,qCAAqC,CAAC,CAAC;gBAChE,CAAC;gBAED,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;gBAEzD,OAAO;oBACL,UAAU,EAAE,GAAG;oBACf,QAAQ,EAAE;wBACR,OAAO;wBACP,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,OAAO,EAAE,IAAI;wBACb,UAAU,EAAE,IAAI;wBAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;qBACzB;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,IAAI,MAAM,YAAY,4BAAU,EAAE,CAAC;oBACjC,OAAO,IAAA,6BAAa,EAAC,MAAM,CAAC,CAAC;gBAC/B,CAAC;gBACD,OAAO,IAAA,2BAAW,EAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC;QAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA+BG;QACK,2BAAsB,GAE1B,KAAK,EAAE,GAAG,EAAE,EAAE;YAChB,IAAI,CAAC;gBACH,MAAM,EAAE,OAAO,EAAE,GAAI,GAA0C,CAAC,MAAM,CAAC;gBAEvE,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,IAAA,+BAAe,EAAC,qCAAqC,CAAC,CAAC;gBAChE,CAAC;gBAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBAEpE,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,IAAA,6BAAa,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACzC,CAAC;gBAED,OAAO;oBACL,UAAU,EAAE,GAAG;oBACf,QAAQ,EAAE;wBACR,OAAO;wBACP,QAAQ;qBACT;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,IAAI,MAAM,YAAY,4BAAU,EAAE,CAAC;oBACjC,OAAO,IAAA,6BAAa,EAAC,MAAM,CAAC,CAAC;gBAC/B,CAAC;gBACD,OAAO,IAAA,2BAAW,EAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC;QAEF;;;;;;;;;;;;;;;;;;;;;;;WAuBG;QACK,sBAAiB,GAErB,KAAK,EAAE,GAAG,EAAE,EAAE;YAChB,IAAI,CAAC;gBACH,MAAM,EAAE,OAAO,EAAE,GAAI,GAAqC,CAAC,MAAM,CAAC;gBAElE,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,IAAA,+BAAe,EAAC,qCAAqC,CAAC,CAAC;gBAChE,CAAC;gBAED,MAAM,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;gBAE9C,OAAO;oBACL,UAAU,EAAE,GAAG;oBACf,QAAQ,EAAE;wBACR,OAAO;wBACP,OAAO,EAAE,IAAI;qBACd;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,IAAI,MAAM,YAAY,4BAAU,EAAE,CAAC;oBACjC,OAAO,IAAA,6BAAa,EAAC,MAAM,CAAC,CAAC;gBAC/B,CAAC;gBACD,OAAO,IAAA,2BAAW,EAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC;QAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA6BG;QACK,wBAAmB,GAEvB,KAAK,EAAE,GAAG,EAAE,EAAE;YAChB,IAAI,CAAC;gBACH,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,GACjC,GACD,CAAC,IAAI,CAAC;gBAEP,2BAA2B;gBAC3B,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,IAAA,+BAAe,EAAC,iCAAiC,CAAC,CAAC;gBAC5D,CAAC;gBAED,IAAI,gBAAgB,KAAK,SAAS,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;oBAC3D,OAAO,IAAA,+BAAe,EAAC,6CAA6C,CAAC,CAAC;gBACxE,CAAC;gBAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,aAAa,CACnD,OAAO,EACP,gBAAgB,CACjB,CAAC;gBAEF,OAAO;oBACL,UAAU,EAAE,GAAG;oBACf,QAAQ,EAAE;wBACR,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;wBAC3C,cAAc,EAAE,MAAM,CAAC,cAAc;wBACrC,eAAe,EAAE,MAAM,CAAC,eAAe;qBACxC;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,IAAI,MAAM,YAAY,4BAAU,EAAE,CAAC;oBACjC,OAAO,IAAA,6BAAa,EAAC,MAAM,CAAC,CAAC;gBAC/B,CAAC;gBACD,OAAO,IAAA,2BAAW,EAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC;QA7XA,IAAI,CAAC,aAAa,GAAG,yCAAmB,CAAC,WAAW,EAAE,CAAC,UAAU,CAC/D,WAAkB,CACnB,CAAC;IACJ,CAAC;IAES,oBAAoB;QAC5B,IAAI,CAAC,gBAAgB,GAAG;YACtB,IAAA,gCAAW,EAAC,MAAM,EAAE,GAAG,EAAE;gBACvB,iBAAiB,EAAE,IAAI;gBACvB,uBAAuB,EAAE,KAAK;gBAC9B,UAAU,EAAE,YAAY;aACzB,CAAC;YACF,IAAA,gCAAW,EAAC,KAAK,EAAE,WAAW,EAAE;gBAC9B,UAAU,EAAE,UAAU;gBACtB,iBAAiB,EAAE,IAAI;gBACvB,uBAAuB,EAAE,KAAK;aAC/B,CAAC;YACF,IAAA,gCAAW,EAAC,KAAK,EAAE,oBAAoB,EAAE;gBACvC,UAAU,EAAE,kBAAkB;gBAC9B,iBAAiB,EAAE,IAAI;gBACvB,uBAAuB,EAAE,KAAK;aAC/B,CAAC;YACF,IAAA,gCAAW,EAAC,QAAQ,EAAE,WAAW,EAAE;gBACjC,UAAU,EAAE,aAAa;gBACzB,iBAAiB,EAAE,IAAI;gBACvB,uBAAuB,EAAE,KAAK;aAC/B,CAAC;YACF,IAAA,gCAAW,EAAC,MAAM,EAAE,WAAW,EAAE;gBAC/B,UAAU,EAAE,eAAe;gBAC3B,iBAAiB,EAAE,IAAI;gBACvB,uBAAuB,EAAE,KAAK;aAC/B,CAAC;SACH,CAAC;QAEF,IAAI,CAAC,QAAQ,GAAG;YACd,UAAU,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5C,QAAQ,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YACxC,gBAAgB,EAAE,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC;YACxD,WAAW,EAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;YAC9C,aAAa,EAAE,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC;SACnD,CAAC;IACJ,CAAC;CAqVF;AA1YD,4CA0YC"}