バージョン: 🚧 Canary

🚀 Product Features

Product features provide complete, pre-composed functionality for product management operations in Nodeblocks applications. These features combine schemas, routes, and handlers to create ready-to-use API endpoints for product CRUD operations, batch operations, and product copying.

🎯 Overview

Product features are designed to:

Provide complete product management with full CRUD operations
Support batch operations for efficient bulk product handling
Include validation and routing for secure product operations
Support filtering and pagination for product listings
Handle product copying and duplication workflows

📋 Feature Structure

Each product feature follows a consistent composition pattern:

Schema: Validates product input data and parameters
Route: Provides HTTP endpoint with product handlers
Composition: Combines schema and route using compose function

🔧 Available Product Features

`createProductFeature`

Product creation feature with schema validation and routing.

Purpose: Handles product creation with complete validation

Composition:

Schema: createProductSchema - validates name and description
Route: createProductRoute - POST /products with creation handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.createProductFeature, [{ dataStores: db }])));

API Endpoint: POST /api/products

`createProductBatchFeature`

Batch product creation feature with schema validation and routing.

Purpose: Handles batch product creation with validation

Composition:

Schema: createProductBatchSchema - validates array of product objects
Route: createProductBatchRoute - POST /products/batch with batch creation handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.createProductBatchFeature, [{ dataStores: db }])));

API Endpoint: POST /api/products/batch

`getProductFeatures`

Product retrieval feature for getting individual product data.

Purpose: Fetches product information with proper validation

Composition:

Schema: getProductSchema - validates path parameters
Route: getProductRoute - GET /products/:productId with retrieval handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.getProductFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/products/:productId

`findProductsFeatures`

Product search feature with filtering and pagination.

Purpose: Provides product listing with search capabilities

Composition:

Schema: findProductsSchema - validates query parameters for filtering
Route: findProductsRoute - GET /products with search and pagination

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.findProductsFeatures, [{ dataStores: db }])));

API Endpoint: GET /api/products

`editProductFeatures`

Product update feature with schema validation and routing.

Purpose: Modifies product information with proper validation

Composition:

Schema: updateProductSchema - validates optional name and description
Route: updateProductRoute - PATCH /products/:productId with update handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.editProductFeatures, [{ dataStores: db }])));

API Endpoint: PATCH /api/products/:productId

`editProductBatchFeatures`

Batch product update feature with schema validation and routing.

Purpose: Handles batch product updates with validation

Composition:

Schema: updateProductBatchSchema - validates ids array and data object
Route: updateProductBatchRoute - PATCH /products/batch with batch update handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.editProductBatchFeatures, [{ dataStores: db }])));

API Endpoint: PATCH /api/products/batch

`deleteProductFeatures`

Product deletion feature with routing.

Purpose: Removes products with access control and cleanup

Composition:

Schema: deleteProductSchema - validates path parameters
Route: deleteProductRoute - DELETE /products/:productId with deletion handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.deleteProductFeatures, [{ dataStores: db }])));

API Endpoint: DELETE /api/products/:productId

`deleteProductBatchFeatures`

Batch product deletion feature with schema validation and routing.

Purpose: Handles batch product deletion with validation

Composition:

Schema: deleteProductBatchSchema - validates array of string IDs
Route: deleteProductBatchRoute - DELETE /products/batch with batch deletion handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.deleteProductBatchFeatures, [{ dataStores: db }])));

API Endpoint: DELETE /api/products/batch

`copyProductFeatures`

Product copying feature with routing.

Purpose: Creates product copies with proper duplication

Composition:

Schema: copyProductSchema - validates path parameters
Route: copyProductRoute - POST /products/:productId/copy with copy handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.copyProductFeatures, [{ dataStores: db }])));

API Endpoint: POST /api/products/:productId/copy

`copyProductBatchFeatures`

Batch product copying feature with schema validation and routing.

Purpose: Handles batch product copying with validation

Composition:

Schema: copyProductBatchSchema - validates array of string IDs
Route: copyProductBatchRoute - POST /products/batch/copy with batch copy handler

Usage:

import { features } from '@nodeblocks/backend-sdk';


// With database configuration
app.use('/api', defService(partial(features.copyProductBatchFeatures, [{ dataStores: db }])));

API Endpoint: POST /api/products/batch/copy

`getProductImageUploadUrlFeature`

Generates a pre-signed URL to upload a product image.

Purpose: Issues a signed upload URL with unique object name and returns it with the generated objectId

Composition:

Schema: getSignedImageUploadUrlSchema - validates content type and file size
Route: getProductImageUploadUrlRoute - GET /products/:productId/image-upload-url

Usage:

import { features } from '@nodeblocks/backend-sdk';

// With file storage service in configuration:
app.use(
  '/api',
  defService(partial(features.getProductImageUploadUrlFeature, [{ configuration: { fileStorageDriver } }]))
);

API Endpoint: GET /api/products/:productId/image-upload-url

`createProductImageFeature`

Creates a new product image for an existing product with validation and routing.

Purpose: Handles product image creation with complete validation and retrieval

Composition:

Schema: createProductImageSchema - validates objectId and type for new product images
Route: createProductImageRoute - POST /products/:productId/images with image creation handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// With database configuration:
app.use('/api', defService(partial(features.createProductImageFeature, [{ dataStores: db }])));

API Endpoint: POST /api/products/:productId/images

Request Body:

{
  "objectId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "image/png"
}

Response (201 Created):

{
  "id": "generated-image-id",
  "objectId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "image/png",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Features:

Automatic base entity generation for images (id, createdAt, updatedAt)
Image added to product's images array
Image retrieval after creation for response
Proper error handling for missing products or database failures

`deleteProductImageFeature`

Deletes a product image with validation and file storage cleanup.

Purpose: Handles product image deletion with complete validation and storage cleanup

Composition:

Schema: deleteProductImageSchema - validates productId and imageId path parameters
Route: deleteProductImageRoute - DELETE /products/:productId/images/:imageId with deletion handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// With database and file storage configuration:
app.use('/api', defService(
  partial(features.deleteProductImageFeature, [
    { dataStores: db, fileStorageDriver }
  ])
));

API Endpoint: DELETE /api/products/:productId/images/:imageId

Response (204 No Content): Empty response body on successful deletion

Features:

Removes image from product's images array
Deletes actual image file from file storage
Updates product's updatedAt timestamp
Atomic operation with proper rollback handling
Proper error handling for missing products or images

Error Responses:

404: Product not found or image not found
500: Database operation failed or file deletion failed

`createProductVariantFeature`

Product variant creation feature with schema validation and routing.

Purpose: Creates new product variants for existing products with full validation and normalization

Composition:

Schema: createProductVariantSchema - validates variant data with required title
Route: createProductVariantRoute - POST /products/:productId/variants with creation and normalization handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.createProductVariantFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.createProductVariantFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: POST /api/products/:productId/variants

Request Body:

{
  "title": "Blue Baseball Cap",
  "description": "Premium baseball cap in blue color",
  "sku": "BBC-BLUE",
  "imageIds": ["img-456", "img-789"],
  "price": {
    "amount": 2999,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  }
}

Response (201 Created):

{
  "id": "uuid-string",
  "productId": "prod-123",
  "title": "Blue Baseball Cap",
  "description": "Premium baseball cap in blue color",
  "sku": "BBC-BLUE",
  "imageIds": ["img-456", "img-789"],
  "price": {
    "amount": 2999,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  },
  "delFlg": 0,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Key Features:

Required Title: Every variant must have a descriptive title for identification
Flexible Pricing: Optional pricing structure with amount, currency, tax settings
Image Support: Can reference existing product images via imageIds array
SKU Management: Optional stock keeping unit for inventory tracking
Parent Association: Automatically associates variant with parent product
Data Normalization: Removes MongoDB _id fields from API responses
Auto-generated Fields: ID, timestamps, and delFlg are automatically managed

Authorization:

Currently restricted to admin users only (checkIdentityType(['admin']))
TODO: Add organization-based access control
TODO: Add email verification requirements

Validation Rules:

title is required and must be a non-empty string
All other fields are optional
imageIds must be an array of strings if provided
price object follows specific structure if provided
No additional properties allowed (strict schema)

Error Responses:

400 Bad Request: Invalid request body or missing required title
401 Unauthorized: Authentication failed
403 Forbidden: Non-admin user attempting creation
404 Not Found: Product variant not found after creation (unexpected)
500 Internal Server Error: Database operation failed

Handler Process:

Validates request body and path parameters
Creates variant in database with auto-generated fields
Retrieves created variant to confirm successful creation
Normalizes response data (removes _id)
Returns 201 Created with normalized variant data

Use Cases:

Adding color variations (Red, Blue, Green shirts)
Size variations (Small, Medium, Large)
Material variations (Cotton, Polyester)
Style variations (V-neck, Crew neck)
Custom product configurations

`createProductVariantBulkFeature`

Product variants bulk creation feature with schema validation and routing.

Purpose: Creates multiple product variants in a single operation with comprehensive validation, normalization, and error handling.

Composition:

Schema: createProductVariantBulkSchema - validates array of product variant data with required fields
Route: createProductVariantBulkRoute - POST /product/:productId/variants/bulk with bulk creation and normalization handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.createProductVariantBulkFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.createProductVariantBulkFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: POST /api/product/:productId/variants/bulk

Request Body (Array of Variants):

[
  {
    "title": "Small - Red",
    "description": "Small size in red color",
    "sku": "S-RED",
    "price": {
      "amount": 1999,
      "currency": "USD"
    },
    "imageIds": ["img-456"],
    "isActive": true
  },
  {
    "title": "Medium - Blue",
    "description": "Medium size in blue color",
    "sku": "M-BLUE",
    "price": {
      "amount": 2099,
      "currency": "USD"
    },
    "imageIds": ["img-789"],
    "isActive": true
  }
]

Response (201 Created, Array of Created Variants):

[
  {
    "id": "uuid-1",
    "productId": "prod-123",
    "title": "Small - Red",
    "description": "Small size in red color",
    "sku": "S-RED",
    "price": {
      "amount": 1999,
      "currency": "USD"
    },
    "imageIds": ["img-456"],
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "uuid-2",
    "productId": "prod-123",
    "title": "Medium - Blue",
    "description": "Medium size in blue color",
    "sku": "M-BLUE",
    "price": {
      "amount": 2099,
      "currency": "USD"
    },
    "imageIds": ["img-789"],
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
]

Key Features:

Bulk Efficiency: Creates multiple variants in single database operation
Atomic Operations: All variants succeed or entire operation fails
Comprehensive Validation: Validates entire array and individual variant requirements
Error Specificity: Detailed error reporting for bulk write failures including index information
Data Normalization: Automatic MongoDB field cleanup in API responses
Size Constraints: Limited to 1-100 variants per request for performance

Authorization:

Currently restricted to admin users only (checkIdentityType(['admin']))
TODO: Add organization-based access control
TODO: Add email verification requirements
TODO: Add product ownership validation for each variant

Validation Rules:

Array must contain 1-100 variant objects
Each variant must have title field
Path parameter productId is required
All other fields are optional
No additional properties allowed in request items
Price object follows standard pricing structure if provided

Error Responses:

400 Bad Request: Invalid request body, missing required fields, or constraint violations
401 Unauthorized: Authentication failed
403 Forbidden: Non-admin user attempting bulk creation
500 Internal Server Error: Database operation failed or bulk write error with specific index information

Handler Process:

Validates authentication, path parameters, and request body array structure
Performs bulk database insertion of all variants with product association
Retrieves created variants by their generated IDs
Normalizes response data (removes MongoDB _id fields)
Returns 201 Created with array of normalized variant data

Use Cases:

Bulk Product Setup: Initial setup of size/color variants for new products
Catalog Migration: Importing product variants from external systems
Seasonal Updates: Adding multiple variants for seasonal product lines
Admin Operations: Efficient management of large product catalogs

Performance Benefits:

Single database transaction for multiple variants
Reduced network overhead compared to individual API calls
Optimized for large-scale product management operations

`updateProductVariantBulkFeature`

Product variants bulk update feature with schema validation and routing.

Purpose: Updates multiple product variants in a single operation with comprehensive validation, data normalization, and error handling.

Composition:

Schema: updateProductVariantBulkSchema - validates variant IDs array, update data, and productId path parameter
Route: updateProductVariantBulkRoute - PATCH /product/:productId/variants/bulk with bulk update and normalization handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.updateProductVariantBulkFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.updateProductVariantBulkFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: PATCH /api/product/:productId/variants/bulk

Request Body:

{
  "ids": ["var-123", "var-456", "var-789"],
  "data": {
    "description": "Updated description for all variants",
    "price": {
      "amount": 2999,
      "currency": "USD",
      "taxIncluded": true,
      "taxable": true
    },
    "sku": "UPDATED-SKU",
    "title": "Updated Title",
    "imageIds": ["img-456", "img-789"]
  }
}

Response (200 OK):

[
  {
    "id": "var-123",
    "productId": "prod-123",
    "title": "Updated Title",
    "description": "Updated description for all variants",
    "sku": "UPDATED-SKU",
    "price": {
      "amount": 2999,
      "currency": "USD",
      "taxIncluded": true,
      "taxable": true
    },
    "imageIds": ["img-456", "img-789"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-16T14:20:00Z"
  },
  {
    "id": "var-456",
    "productId": "prod-123",
    "title": "Updated Title",
    "description": "Updated description for all variants",
    "sku": "UPDATED-SKU",
    "price": {
      "amount": 2999,
      "currency": "USD",
      "taxIncluded": true,
      "taxable": true
    },
    "imageIds": ["img-456", "img-789"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-16T14:20:00Z"
  }
]

Key Features:

Bulk Efficiency: Updates multiple variants in single database operation
Atomic Operations: All updates succeed or entire operation fails
Comprehensive Validation: Validates entire array and individual variant requirements
Error Specificity: Detailed error reporting for bulk write failures
Data Normalization: Automatic MongoDB field cleanup in API responses
Flexible Updates: Update any combination of variant fields (partial updates supported)
Size Constraints: Limited to 1-100 variants per request for performance

Authorization:

Currently restricted to admin users only (checkIdentityType(['admin']))
TODO: Add organization-based access control
TODO: Add email verification requirements
TODO: Add product ownership validation for each variant

Validation Rules:

Path parameter productId is required
Request body must contain ids array (1-100 items) and data object
All fields in data object are optional (for partial updates)
Price object follows standard pricing structure if provided
Image IDs must be valid strings if provided

Error Responses:

400 Bad Request: Invalid request body, missing required fields, or constraint violations
401 Unauthorized: Authentication failed
403 Forbidden: Non-admin user attempting bulk update
404 Not Found: One or more product variants not found
500 Internal Server Error: Database operation failed or bulk write error

Handler Process:

Validates authentication, path parameters, and request body array structure
Performs bulk database update of all specified variants
Retrieves updated variants by their generated IDs
Normalizes response data (removes MongoDB _id fields)
Returns 200 OK with array of normalized variant data

Use Cases:

Bulk Price Updates: Update pricing across multiple product variants simultaneously
Catalog Maintenance: Apply description or SKU changes to multiple variants at once
Seasonal Adjustments: Modify pricing, descriptions, or images for seasonal product lines
Inventory Management: Update stock levels or availability status for multiple variants
Admin Operations: Efficient management of large product catalogs with similar updates

Data Flow:

Input: Product ID (path), variant IDs array, and update data
Validation: Authentication, authorization, and data structure validation
Database Operation: MongoDB updateMany with $set operations
Response Processing: Data normalization and formatting
Output: Array of updated, normalized variant objects

Performance Notes:

Uses MongoDB updateMany for efficient bulk operations
Single database transaction for atomicity
Data normalization applied to result set
Suitable for high-volume catalog management operations

`deleteProductVariantBulkFeature`

Product variants bulk deletion feature with schema validation and routing.

Purpose: Deletes multiple product variants in a single operation with comprehensive validation, error handling, and clean response formatting.

Composition:

Schema: deleteProductVariantBulkSchema - validates variant ID array and productId path parameter
Route: deleteProductVariantBulkRoute - POST /product/:productId/variants/bulk-delete with bulk deletion handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.deleteProductVariantBulkFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.deleteProductVariantBulkFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: POST /api/product/:productId/variants/bulk-delete

Request Body:

["var-123", "var-456", "var-789"]

Response (204 No Content): Empty response body on successful deletion

Key Features:

Bulk Efficiency: Deletes multiple variants in single database operation
Atomic Operations: All deletions succeed or entire operation fails
Comprehensive Validation: Validates entire array and individual variant requirements
Clean Response: Returns 204 No Content for successful bulk deletions
Error Specificity: Detailed error reporting for bulk write failures
Size Constraints: Limited to 1-100 variants per request for performance

Authorization:

Currently restricted to admin users only (checkIdentityType(['admin']))
TODO: Add organization-based access control
TODO: Add email verification requirements
TODO: Add product ownership validation for each variant

Validation Rules:

Path parameter productId is required
Request body must be an array of 1-100 variant ID strings
No additional properties allowed in request body

Error Responses:

400 Bad Request: Invalid request body, missing required fields, or constraint violations
401 Unauthorized: Authentication failed
403 Forbidden: Non-admin user attempting bulk deletion
500 Internal Server Error: Database operation failed or no variants deleted

Handler Process:

Validates authentication, path parameters, and request body array structure
Performs bulk database deletion of all specified variants
Validates that at least one variant was deleted
Returns 204 No Content on successful bulk deletion

Use Cases:

Bulk Cleanup: Remove multiple obsolete or discontinued product variants
Catalog Restructuring: Delete variants during product line reorganization
Data Maintenance: Clean up duplicate or invalid variant entries
Admin Operations: Efficient management of large product catalogs

Data Flow:

Input: Product ID (path), variant IDs array
Validation: Authentication, authorization, and data structure validation
Database Operation: MongoDB deleteMany with ID filter
Response Processing: Empty body formatting for 204 response
Output: 204 No Content status with empty response body

Performance Notes:

Uses MongoDB deleteMany for efficient bulk operations
Single database transaction for atomicity
Minimal response payload (204 No Content)
Suitable for high-volume catalog cleanup operations

`getProductVariantFeature`

Product variant retrieval feature with schema validation and routing.

Purpose: Retrieves individual product variant details with proper validation and normalization

Composition:

Schema: getProductVariantSchema - validates productId and productVariantId path parameters
Route: getProductVariantRoute - GET /products/:productId/variants/:productVariantId with retrieval and normalization handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.getProductVariantFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.getProductVariantFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: GET /api/products/:productId/variants/:productVariantId

Response (200 OK):

{
  "id": "uuid-string",
  "productId": "prod-123",
  "title": "Blue Baseball Cap",
  "description": "Premium baseball cap in blue color",
  "sku": "BBC-BLUE",
  "imageIds": ["img-456", "img-789"],
  "price": {
    "amount": 2999,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  },
  "delFlg": 0,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Key Features:

Individual Variant Retrieval: Get detailed information for a specific product variant
Parent Product Scoping: Ensures variant belongs to the specified product
Data Normalization: Removes MongoDB _id fields from API responses
Authentication Required: Requires valid authentication token
Flexible Authorization: Currently open to all authenticated users
Comprehensive Error Handling: Specific error classes for different failure scenarios

Authorization:

Requires authentication only (no role restrictions currently)
TODO: Add organization-based access control
TODO: Add email verification requirements

Validation Rules:

productId must be a valid string (required path parameter)
productVariantId must be a valid string (required path parameter)
Variant must exist and belong to the specified product

Error Responses:

401 Unauthorized: Authentication failed
404 Not Found: Product variant not found or doesn't belong to specified product
500 Internal Server Error: Database operation failed

Handler Process:

Validates authentication and path parameters
Retrieves product variant from database with product scoping
Normalizes response data (removes _id)
Returns 200 OK with normalized variant data

Use Cases:

Displaying detailed variant information in product pages
Admin review of specific variant configurations
E-commerce cart/checkout variant selection
Inventory management systems
Variant comparison and editing interfaces

`updateProductVariantFeature`

Product variant update feature with schema validation and routing.

Purpose: Updates existing product variant data with partial update support and validation

Composition:

Schema: updateProductVariantSchema - validates optional variant fields with required path parameters
Route: updateProductVariantRoute - PATCH /products/:productId/variants/:productVariantId with update and normalization handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.updateProductVariantFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.updateProductVariantFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: PATCH /api/products/:productId/variants/:productVariantId

Request Body (all fields optional):

{
  "title": "Updated Title",
  "description": "Updated description",
  "sku": "UPDATED-SKU",
  "imageIds": ["img-789", "img-101"],
  "price": {
    "amount": 2999,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  }
}

Response (200 OK):

{
  "id": "uuid-string",
  "productId": "prod-123",
  "title": "Updated Title",
  "description": "Updated description",
  "sku": "UPDATED-SKU",
  "imageIds": ["img-789", "img-101"],
  "price": {
    "amount": 2999,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  },
  "delFlg": 0,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Key Features:

Partial Updates: Update only the fields you want to change
Flexible Pricing: Update individual price components (amount, currency, tax settings)
Image Management: Replace or modify image references
Validation: Strict validation prevents invalid data
Atomic Operations: Database updates are atomic with proper error handling
Audit Trail: Automatic updatedAt timestamp management
Data Normalization: MongoDB _id fields removed from responses

Authorization:

Currently restricted to admin users only (checkIdentityType(['admin']))
TODO: Add organization-based access control
TODO: Add email verification requirements

Validation Rules:

Path parameters productId and productVariantId are required
Request body fields are all optional (empty body allowed)
Variant must exist and belong to specified product
Strict schema validation (no additional properties)

Error Responses:

400 Bad Request: Invalid request body or schema validation failure
401 Unauthorized: Authentication failed
403 Forbidden: Non-admin user attempting update
404 Not Found: Product variant not found
500 Internal Server Error: Database operation failed

Handler Process:

Validates authentication and path parameters
Updates product variant in database with provided fields only
Retrieves updated variant to confirm successful modification
Normalizes response data (removes _id)
Returns 200 OK with normalized updated variant data

Use Cases:

Price updates for seasonal sales or promotions
Inventory adjustments (SKU changes)
Content updates (title, description changes)
Image gallery modifications
Tax setting adjustments
Partial data corrections

Performance Notes:

Uses MongoDB $set operator for efficient partial updates
Only updates updatedAt timestamp for changed documents
Atomic database operations ensure data consistency

`deleteProductVariantFeature`

Product variant deletion feature with schema validation and routing.

Purpose: Removes product variants from the database with proper validation and error handling

Composition:

Schema: deleteProductVariantSchema - validates productId and productVariantId path parameters
Route: deleteProductVariantRoute - DELETE /products/:productId/variants/:productVariantId with deletion handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.deleteProductVariantFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.deleteProductVariantFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: DELETE /api/products/:productId/variants/:productVariantId

Response (204 No Content): Empty response body on successful deletion

Key Features:

Permanent Deletion: Removes product variants completely from database
Path Parameter Validation: Ensures both product and variant IDs are provided
Existence Verification: Confirms variant exists before deletion
Atomic Operations: Database deletion is atomic and verified
Empty Response: Returns 204 No Content for successful deletions
Comprehensive Error Handling: Specific error classes for different failure scenarios

Authorization:

Currently restricted to admin users only (checkIdentityType(['admin']))
TODO: Add organization-based access control
TODO: Add email verification requirements

Validation Rules:

Path parameters productId and productVariantId are required
Variant must exist in database to be deleted
No request body validation (DELETE operations)

Error Responses:

401 Unauthorized: Authentication failed
403 Forbidden: Non-admin user attempting deletion
500 Internal Server Error: Database operation failed or variant not found

Handler Process:

Validates authentication and path parameters
Deletes product variant from database by ID
Verifies deletion was successful (checks deletedCount)
Normalizes empty response body
Returns 204 No Content on successful deletion

Use Cases:

Removing discontinued product variants
Cleaning up test or demo data
Deleting variants with inventory issues
Administrative data management
Product catalog maintenance

Data Integrity Notes:

Deletion is permanent and cannot be undone
Consider cascading effects (orders, carts referencing the variant)
TODO: Add cascading deletion for related data when product is deleted

Performance Notes:

Uses MongoDB deleteOne for efficient single document deletion
Atomic operation ensures data consistency
No additional queries beyond the deletion verification

`findProductVariantsFeature`

Product variants retrieval feature with schema validation and routing.

Purpose: Lists product variants for a specific product with pagination and data normalization

Composition:

Schema: findProductVariantsSchema - validates productId path parameter and pagination query parameters
Route: findProductVariantsRoute - GET /products/:productId/variants with retrieval handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.findProductVariantsFeature));

// With database configuration:
app.use('/api', defService(
  partial(features.findProductVariantsFeature, [
    { dataStores: { productVariants: db.collection('productVariants') } }
  ])
));

API Endpoint: GET /api/products/:productId/variants

Response (200 OK):

{
  "data": [
    {
      "id": "string",
      "productId": "string",
      "title": "string",
      "description": "string",
      "sku": "string",
      "imageIds": ["string"],
      "price": {
        "amount": "number",
        "currency": "string"
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Key Features:

Pagination Support: Built-in pagination with configurable page size and navigation
Data Normalization: Automatic removal of MongoDB _id fields from API responses
Flexible Filtering: Filter variants by product ID with extensible query options
Comprehensive Response: Includes both data array and pagination metadata
Error Handling: Specific error classes for database failures and normalization issues

Authorization:

Currently no authentication or authorization required
TODO: Add product existence validation
TODO: Add organization-based access control

Validation Rules:

Path parameter productId is required
Optional pagination parameters (page, limit, sort, order)
Query parameter validation for pagination and sorting

Error Responses:

500 Internal Server Error: Database operation failed

Handler Process:

Validates path parameters and optional query parameters
Builds database filter for product variant retrieval
Queries MongoDB collection with pagination
Normalizes documents by removing _id fields
Formats response with data and pagination metadata
Returns 200 OK with paginated variant list

Use Cases:

Displaying product variants in e-commerce product pages
Admin interface for managing product variants
API consumers retrieving variant information for a product
Building product catalog displays with pagination

Data Flow:

Input: Product ID and optional pagination parameters
Database Query: MongoDB find operation with productId filter
Data Processing: Pagination wrapper, document normalization
Output: Structured response with variants array and pagination metadata

Performance Notes:

Uses MongoDB find with cursor for efficient querying
Pagination handled at database level for optimal performance
Document normalization applied to result set
Suitable for high-traffic product catalog operations

`findProductsByOrganizationIdFeature`

Product retrieval by organization ID feature with schema validation and routing.

Purpose: Retrieves products scoped to a specific organization with pagination, image normalization, and proper authorization controls.

Composition:

Schema: findByOrganizationIdSchema - validates organization ID path parameter and pagination
Route: findProductsByOrganizationIdRoute - GET /products/organizations/:organizationId with retrieval handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.findProductsByOrganizationIdFeature));

// With database and file storage configuration:
app.use('/api', defService(
  partial(features.findProductsByOrganizationIdFeature, [
    { dataStores: db, fileStorageDriver }
  ])
));

API Endpoint: GET /api/products/organizations/:organizationId

Request Parameters:

Path parameter: organizationId (string) - Organization identifier
Query parameters: page, limit, sort, order (pagination options)

Response (200 OK):

{
  "data": [
    {
      "id": "prod-123",
      "organizationId": "org-456",
      "name": "Premium Widget",
      "description": "High-quality widget for professionals",
      "images": [
        {
          "id": "img-789",
          "objectId": "abc123...",
          "type": "image/jpeg",
          "url": "https://storage.googleapis.com/bucket/abc123..."
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Key Features:

Organization Scoping: Products are filtered by organization ID for multi-tenant support
Image Normalization: Automatic URL generation for product images using file storage driver
Pagination Support: Built-in pagination with configurable page size and navigation
Data Normalization: Removes MongoDB _id fields and enriches data with generated URLs
Role-Based Access: Requires organization membership (owner, admin, or member role)

Authorization:

Requires authentication (isAuthenticated)
Requires organization membership (hasOrgRole(['owner', 'admin', 'member']))
TODO: Add email verification requirements

Validation Rules:

organizationId must be a valid string (required path parameter)
User must have access to the specified organization
Optional pagination parameters (page, limit, sort, order)

Error Responses:

401 Unauthorized: Authentication failed
403 Forbidden: User doesn't have access to the organization
500 Internal Server Error: Database operation failed or file storage error

Handler Process:

Validates authentication and organization access
Builds organization-specific filter for product retrieval
Queries products with pagination and sorting
Normalizes product images with signed URLs
Formats response with data array and pagination metadata
Returns 200 OK with paginated product list

Use Cases:

Organization-specific product catalogs in multi-tenant applications
Admin dashboards for managing products within an organization
API consumers retrieving products for a specific business entity
Building organization-scoped e-commerce interfaces

Performance Notes:

Uses MongoDB find with organization filtering for efficient querying
Pagination handled at database level for optimal performance
Image URL generation adds processing overhead for media-rich products
Suitable for organization-scoped product catalog operations

`getProductLikersFeature`

Product followers retrieval feature with schema validation and routing.

Purpose: Retrieves users who have liked a specific product with pagination, avatar normalization, and proper authorization controls.

Composition:

Schema: getProductLikersSchema - validates product ID parameter
Route: getProductLikersRoute - GET /products/:productId/likers with followers retrieval handler

Usage:

import { features } from '@nodeblocks/backend-sdk';

// Direct usage:
app.use('/api', defService(features.getProductLikersFeature));

// With database and file storage configuration:
app.use('/api', defService(
  partial(features.getProductLikersFeature, [
    { dataStores: db, fileStorageDriver }
  ])
));

API Endpoint: GET /api/products/:productId/likers

Request Parameters:

Path parameter: productId (string) - Product identifier to find likers for
Query parameters: page, limit, sort, order (pagination options)

Response (200 OK):

{
  "data": [
    {
      "id": "user-123",
      "name": "John Doe",
      "avatar": {
        "id": "avatar-456",
        "objectId": "abc123...",
        "type": "image/jpeg",
        "url": "https://storage.googleapis.com/bucket/abc123..."
      }
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Key Features:

Product Likers Retrieval: Finds all users who have liked a specific product
Avatar Normalization: Automatic URL generation for user avatars using file storage driver
Pagination Support: Built-in pagination with configurable page size and navigation
Data Normalization: Removes MongoDB _id fields and enriches data with generated URLs
Admin-Only Access: Restricted to admin users for privacy and security

Authorization:

Requires authentication (isAuthenticated)
Restricted to admin users only (checkIdentityType(['admin']))
TODO: Consider implementing product owner access or public access with rate limiting

Validation Rules:

productId must be a valid string (required path parameter)
Product must exist in the database
User must have admin privileges

Error Responses:

401 Unauthorized: Authentication failed
403 Forbidden: Non-admin user attempting to view likers
404 Not Found: Product not found
500 Internal Server Error: Database operation failed or file storage error

Handler Process:

Validates authentication and admin privileges
Retrieves product to confirm it exists
Builds filter to find users who liked the product
Queries users collection with pagination
Normalizes user avatars with signed URLs
Formats response with user data and pagination metadata
Returns 200 OK with paginated likers list

Use Cases:

Admin dashboards showing product engagement metrics
Analytics for understanding which products are most popular
Product owner insights into their audience
Social features for displaying liker counts or profiles

Performance Notes:

Uses MongoDB $elemMatch for efficient array querying
Pagination handled at database level for optimal performance
Avatar URL generation adds processing overhead for user-rich results
Suitable for admin analytics and product management operations

Product Domain Overview - Product domain overview
Product Blocks - Product block functions
Product Routes - Product HTTP endpoints
Product Schemas - Product data validation

🎯 Overview​

📋 Feature Structure​

🔧 Available Product Features​

createProductFeature​

createProductBatchFeature​

getProductFeatures​

findProductsFeatures​

editProductFeatures​

editProductBatchFeatures​

deleteProductFeatures​

deleteProductBatchFeatures​

copyProductFeatures​

copyProductBatchFeatures​

getProductImageUploadUrlFeature​

createProductImageFeature​

deleteProductImageFeature​

createProductVariantFeature​

createProductVariantBulkFeature​

updateProductVariantBulkFeature​

deleteProductVariantBulkFeature​

getProductVariantFeature​

updateProductVariantFeature​

deleteProductVariantFeature​

findProductVariantsFeature​

findProductsByOrganizationIdFeature​

getProductLikersFeature​

🔗 Related Documentation​

🎯 Overview

📋 Feature Structure

🔧 Available Product Features

`createProductFeature`

`createProductBatchFeature`

`getProductFeatures`

`findProductsFeatures`

`editProductFeatures`

`editProductBatchFeatures`

`deleteProductFeatures`

`deleteProductBatchFeatures`

`copyProductFeatures`

`copyProductBatchFeatures`

`getProductImageUploadUrlFeature`

`createProductImageFeature`

`deleteProductImageFeature`

`createProductVariantFeature`

`createProductVariantBulkFeature`

`updateProductVariantBulkFeature`

`deleteProductVariantBulkFeature`

`getProductVariantFeature`

`updateProductVariantFeature`

`deleteProductVariantFeature`

`findProductVariantsFeature`

`findProductsByOrganizationIdFeature`

`getProductLikersFeature`

🔗 Related Documentation