@mesh-sync/worker-backend-client 1.0.5 → 4.0.2

package/README.md

@@ -100,6 +100,194 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 ## Available Message Types
 
 
+### backend-logging-event
+
+**Description:** Centralized logging event for capturing all warn/error/failure logs from meshsync-backend.
+This event is sent to ELK for centralized monitoring, alerting, and debugging.
+
+Automatically emitted by the custom Pino logger interceptor when:
+- logger.warn() is called
+- logger.error() is called
+- uncaught exceptions occur
+- request failures happen (4xx, 5xx responses)
+
+Used for:
+- System health monitoring
+- Error tracking and alerting
+- Performance degradation detection
+- Security incident tracking
+- Compliance and audit trails
+
+
+**Method:** `client.backendLoggingEvent(data)`
+
+**Payload Type:** `BackendLoggingEventMessage`
+
+**Fields:**
+
+- `eventType` (string) [✓]: Type of logging event
+
+- `timestamp` (string) [✓]: ISO 8601 timestamp when the log was generated
+
+- `level` (string) [✓]: Log level severity
+
+- `message` (string) [✓]: Human-readable log message
+
+- `context` (string) [✓]: Logger context (typically the class/service name)
+
+- `requestId` (string) [✗]: Unique request ID for correlation (X-Request-Id header)
+
+- `userId` (string) [✗]: ID of the authenticated user (if available)
+
+- `httpMethod` (string) [✗]: HTTP method of the request
+
+- `httpUrl` (string) [✗]: Request URL path (without query params for privacy)
+
+- `httpStatusCode` (integer) [✗]: HTTP response status code
+
+- `errorType` (string) [✗]: Error class/type name
+
+- `errorStack` (string) [✗]: Stack trace (sanitized, no sensitive data)
+
+- `errorCode` (string) [✗]: Application-specific error code for categorization
+
+- `metadata` (object) [✗]: Additional structured context (sanitized, no PII)
+
+- `environment` (string) [✗]: Deployment environment
+
+- `serviceVersion` (string) [✗]: Backend service version
+
+- `hostname` (string) [✗]: Server hostname/pod name
+
+- `durationMs` (number) [✗]: Operation duration in milliseconds (if applicable)
+
+
+
+### etsy-analytics-sync-completed
+
+**Description:** Contains synced analytics data for Etsy listings. Backend stores this in etsy_analytics_snapshots table and indexes to ELK.
+
+
+**Method:** `client.etsyAnalyticsSyncCompleted(data)`
+
+**Payload Type:** `EtsyAnalyticsSyncCompletedMessage`
+
+**Fields:**
+
+- `originalJobId` (string) [✗]: 
+
+- `status` (string) [✗]: 
+
+- `syncedCount` (integer) [✗]: Number of listings successfully synced
+
+- `errorCount` (integer) [✗]: Number of listings that failed
+
+- `results` (array) [✗]: Analytics for each synced listing
+
+- `errors` (array) [✗]: Errors for failed listings
+
+- `syncedAt` (string) [✗]: 
+
+- `nextScheduledSync` (string) [✗]: When next automatic sync should occur
+
+
+
+### etsy-analytics-sync-request
+
+**Description:** Syncs analytics data from Etsy API for one or more listings. Fetches views, favorites, sales, revenue, and traffic source data.
+Can sync: - Specific listings (provide listingIds) - All user listings (provide userId, empty listingIds) - Shop-level analytics (provide shopId)
+
+
+**Method:** `client.etsyAnalyticsSyncRequest(data)`
+
+**Payload Type:** `EtsyAnalyticsSyncRequestMessage`
+
+**Fields:**
+
+- `listingIds` (array) [✗]: Internal listing IDs to sync. Empty = sync all for user.
+
+- `userId` (string) [✗]: User whose listings to sync (if listingIds empty)
+
+- `shopId` (string) [✗]: Etsy shop ID for shop-level analytics
+
+- `timeRange` (object) [✗]: Date range for historical analytics
+
+- `syncOptions` (object) [✗]: 
+
+- `etsyCredentials` (object) [✗]: Encrypted Etsy OAuth credentials
+
+- `webhookUrl` (string) [✗]: 
+
+
+
+### etsy-publish-listing-completed
+
+**Description:** Indicates completion of Etsy listing publication. Contains external Etsy listing ID and URL, or error details if failed.
+
+
+**Method:** `client.etsyPublishListingCompleted(data)`
+
+**Payload Type:** `EtsyPublishListingCompletedMessage`
+
+**Fields:**
+
+- `originalJobId` (string) [✗]: BullMQ job ID from request
+
+- `listingId` (string) [✗]: Internal marketplace_items ID
+
+- `metamodelId` (string) [✗]: Metamodel that was published
+
+- `materialName` (string) [✗]: Material variant name
+
+- `status` (string) [✗]: Publication result
+
+- `etsyListingId` (string) [✗]: External Etsy listing ID (only if status=SUCCESS)
+
+- `etsyListingUrl` (string) [✗]: URL to view listing on Etsy (only if status=SUCCESS)
+
+- `etsyFileId` (string) [✗]: Etsy digital file ID (only if status=SUCCESS)
+
+- `error` (object) [✗]: Error details (only if status=FAILED)
+
+- `publishedAt` (string) [✗]: When the listing was created (only if status=SUCCESS)
+
+- `processingDuration` (integer) [✗]: Processing time in milliseconds
+
+
+
+### etsy-publish-listing-request
+
+**Description:** Publishes a single metamodel listing to Etsy for a specific material variant. Creates Etsy listing, uploads digital file, and returns external listing ID.
+This message is enqueued for EACH material variant when publishing a metamodel.
+Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
+
+
+**Method:** `client.etsyPublishListingRequest(data)`
+
+**Payload Type:** `EtsyPublishListingRequestMessage`
+
+**Fields:**
+
+- `listingId` (string) [✗]: Internal marketplace_items table ID
+
+- `metamodelId` (string) [✗]: Metamodel being published
+
+- `ownerId` (string) [✗]: User ID who owns the metamodel
+
+- `materialVariant` (object) [✗]: Material-specific listing configuration
+
+- `baseListingData` (object) [✗]: Common listing information
+
+- `publishOptions` (object) [✗]: 
+
+- `etsyCredentials` (object) [✗]: Encrypted Etsy OAuth credentials
+
+- `fileMetadata` (object) [✗]: Digital file to upload
+
+- `webhookUrl` (string) [✗]: Callback URL for completion notification
+
+
+
 ### file-download-completed
 
 **Description:** Notifies that a file download has been processed, indicating success or failure.
@@ -126,7 +314,7 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 ### file-download-request
 
-**Description:** Handles file download requests.
+**Description:** Downloads model file from storage provider to MinIO for processing pipeline. Acts as parent job for thumbnail generation, technical metadata analysis, and metadata generation.
 
 **Method:** `client.fileDownloadRequest(data)`
 
@@ -136,8 +324,368 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 - `modelId` (string) [✗]: The unique identifier for the model to be downloaded.
 
+- `ownerId` (string) [✗]: The identifier of the user who owns the model.
+
 - `storageLocation` (object) [✗]: The storage location of the model.
 
+- `minioDestination` (object) [✗]: Destination in MinIO where file will be uploaded after download.
+
+- `autoEnqueueChildren` (boolean) [✗]: Automatically enqueue thumbnail generation, technical metadata analysis, and metadata generation jobs after download completes.
+
+- `previewType` (string) [✗]: Preview type for thumbnail generation (passed to child job).
+
+- `generate360Views` (boolean) [✗]: Generate 16 angle views for 360° preview (passed to child job).
+
+
+
+### marketplace-analytics-sync-completed
+
+**Description:** Contains synced analytics data for marketplace listings. Backend stores this in marketplace_analytics_snapshots table and indexes to ELK. Works with any marketplace provider.
+
+**Method:** `client.marketplaceAnalyticsSyncCompleted(data)`
+
+**Payload Type:** `MarketplaceAnalyticsSyncCompletedMessage`
+
+**Fields:**
+
+- `originalJobId` (string) [✗]: BullMQ job ID from original request
+
+- `marketplaceProvider` (string) [✗]: Marketplace provider type (etsy, ebay, etc.)
+
+- `status` (string) [✗]: Sync result (SUCCESS, PARTIAL_SUCCESS, or FAILED)
+
+- `syncedCount` (integer) [✗]: Number of listings successfully synced
+
+- `errorCount` (integer) [✗]: Number of listings that failed
+
+- `results` (array) [✗]: Analytics for each synced listing
+
+- `errors` (array) [✗]: Errors for failed listings
+
+- `syncedAt` (string) [✗]: When sync completed (ISO 8601)
+
+- `nextScheduledSync` (string) [✗]: When next automatic sync should occur (ISO 8601)
+
+
+
+### marketplace-analytics-sync-request
+
+**Description:** Syncs analytics data from marketplace API for one or more listings. Fetches views, favorites, sales, revenue, and traffic source data. Can sync: specific listings, all user listings, or shop-level analytics. Works with any marketplace provider that supports analytics (etsy, ebay, etc.).
+
+**Method:** `client.marketplaceAnalyticsSyncRequest(data)`
+
+**Payload Type:** `MarketplaceAnalyticsSyncRequestMessage`
+
+**Fields:**
+
+- `marketplaceProvider` (string) [✗]: Marketplace provider type (etsy, ebay, etc.)
+
+- `marketplaceConnectionId` (string) [✗]: UUID of the marketplace connection configuration
+
+- `listingIds` (array) [✗]: Internal listing UUIDs to sync. Empty array = sync all for user.
+
+- `userId` (string) [✗]: UUID of user whose listings to sync (if listingIds empty)
+
+- `externalShopId` (string) [✗]: External marketplace shop ID for shop-level analytics
+
+- `timeRange` (object) [✗]: Date range for historical analytics
+
+- `syncOptions` (object) [✗]: Optional sync configuration
+
+- `marketplaceCredentials` (object) [✗]: Encrypted marketplace credentials (retrieved from marketplaceConnectionId)
+
+- `webhookUrl` (string) [✗]: Callback URL for completion notification
+
+
+
+### marketplace-connection-sync-completed
+
+**Description:** Notification that marketplace connection sync has completed. Contains updated connection metadata, profile information, and sync statistics.
+
+
+**Method:** `client.marketplaceConnectionSyncCompleted(data)`
+
+**Payload Type:** `MarketplaceConnectionSyncCompletedMessage`
+
+**Fields:**
+
+- `requestId` (string) [✗]: Original request ID for correlation
+
+- `connectionId` (string) [✗]: Marketplace connection that was synced
+
+- `marketplaceId` (string) [✗]: Marketplace provider ID
+
+- `userId` (string) [✗]: Connection owner user ID
+
+- `status` (string) [✗]: Overall sync result status
+
+- `syncType` (string) [✗]: Type of sync that was performed
+
+- `connectionData` (object) [✗]: Updated connection information
+
+- `categories` (array) [✗]: Available marketplace categories
+
+- `statistics` (object) [✗]: Sync operation statistics
+
+- `completedAt` (string) [✗]: When sync completed
+
+- `error` (object) [✗]: Error details if sync failed
+
+
+
+### marketplace-connection-sync-request
+
+**Description:** Requests synchronization of marketplace connection data including: - Profile information and shop details - Account status and permissions - Available categories and shipping profiles - Rate limits and API quotas
+This is typically triggered after initial connection or periodically to keep marketplace metadata up to date.
+
+
+**Method:** `client.marketplaceConnectionSyncRequest(data)`
+
+**Payload Type:** `MarketplaceConnectionSyncRequestMessage`
+
+**Fields:**
+
+- `connectionId` (string) [✗]: Internal marketplace connection ID
+
+- `marketplaceId` (string) [✗]: Marketplace provider ID (etsy, ebay, etc.)
+
+- `userId` (string) [✗]: User who owns this connection
+
+- `syncType` (string) [✗]: Type of sync to perform
+
+- `priority` (string) [✗]: Processing priority
+
+- `requestId` (string) [✗]: Unique request identifier for tracking
+
+- `webhookUrl` (string) [✗]: Webhook URL to call when sync completes
+
+- `metadata` (object) [✗]: Additional context data
+
+
+
+### marketplace-credential-rotation-completed
+
+**Description:** Notification that marketplace credential rotation has completed. Contains the rotation results, new credential metadata, and any issues encountered.
+
+
+**Method:** `client.marketplaceCredentialRotationCompleted(data)`
+
+**Payload Type:** `MarketplaceCredentialRotationCompletedMessage`
+
+**Fields:**
+
+- `requestId` (string) [✗]: Original rotation request ID
+
+- `connectionId` (string) [✗]: Marketplace connection that was rotated
+
+- `marketplaceId` (string) [✗]: Marketplace provider ID
+
+- `userId` (string) [✗]: Connection owner user ID
+
+- `status` (string) [✗]: Overall rotation operation status
+
+- `rotationType` (string) [✗]: Type of rotation that was performed
+
+- `reason` (string) [✗]: Original reason for rotation
+
+- `newCredentials` (object) [✗]: Metadata about new credentials
+
+- `oldCredentials` (object) [✗]: Status of previous credentials
+
+- `operationDetails` (object) [✗]: Details of the rotation operation
+
+- `connectionStatus` (object) [✗]: Connection status after credential rotation
+
+- `nextRotation` (object) [✗]: Information about next scheduled rotation
+
+- `error` (object) [✗]: Error details if rotation failed
+
+- `notifications` (array) [✗]: Notifications sent as part of rotation
+
+
+
+### marketplace-credential-rotation-request
+
+**Description:** Requests rotation/refresh of marketplace connection credentials. This is used for: - OAuth token refresh when tokens are near expiry - API key rotation for enhanced security - Re-authentication after connection errors - Scheduled credential updates
+
+
+**Method:** `client.marketplaceCredentialRotationRequest(data)`
+
+**Payload Type:** `MarketplaceCredentialRotationRequestMessage`
+
+**Fields:**
+
+- `connectionId` (string) [✗]: Marketplace connection ID requiring credential rotation
+
+- `marketplaceId` (string) [✗]: Marketplace provider ID (etsy, ebay, etc.)
+
+- `userId` (string) [✗]: User who owns the connection
+
+- `rotationType` (string) [✗]: Type of credential rotation to perform
+
+- `reason` (string) [✗]: Reason for credential rotation
+
+- `urgency` (string) [✗]: How urgently the rotation is needed
+
+- `currentCredentials` (object) [✗]: Current credential metadata (no actual secrets)
+
+- `options` (object) [✗]: Rotation configuration options
+
+- `requestId` (string) [✗]: Unique request identifier
+
+- `webhookUrl` (string) [✗]: Webhook URL for completion notification
+
+- `scheduledAt` (string) [✗]: When this rotation was scheduled (if scheduled)
+
+- `metadata` (object) [✗]: Additional request context
+
+
+
+### marketplace-listing-sync-completed
+
+**Description:** Notification that marketplace listing sync operation has completed. Contains detailed results of the sync including created/updated listings, errors encountered, and performance statistics.
+
+
+**Method:** `client.marketplaceListingSyncCompleted(data)`
+
+**Payload Type:** `MarketplaceListingSyncCompletedMessage`
+
+**Fields:**
+
+- `requestId` (string) [✗]: Original request ID for correlation
+
+- `connectionId` (string) [✗]: Marketplace connection that was synced
+
+- `marketplaceId` (string) [✗]: Marketplace provider ID
+
+- `userId` (string) [✗]: Connection owner user ID
+
+- `status` (string) [✗]: Overall sync operation status
+
+- `syncDirection` (string) [✗]: Direction of sync that was performed
+
+- `statistics` (object) [✗]: Detailed sync operation statistics
+
+- `results` (object) [✗]: Detailed sync results by operation
+
+- `successfulListings` (array) [✗]: Details of successfully processed listings
+
+- `failedListings` (array) [✗]: Details of listings that failed to sync
+
+- `errors` (array) [✗]: Non-listing-specific errors encountered
+
+- `completedAt` (string) [✗]: When sync operation completed
+
+- `nextSyncRecommendedAt` (string) [✗]: When next sync is recommended
+
+
+
+### marketplace-listing-sync-request
+
+**Description:** Requests synchronization of marketplace listings for a connection. Can sync specific listings or all listings for a marketplace connection.
+Includes bidirectional sync: - Pull: Fetch listings from marketplace to update local database - Push: Update marketplace listings with local changes - Full: Both pull and push operations
+
+
+**Method:** `client.marketplaceListingSyncRequest(data)`
+
+**Payload Type:** `MarketplaceListingSyncRequestMessage`
+
+**Fields:**
+
+- `connectionId` (string) [✗]: Marketplace connection ID
+
+- `marketplaceId` (string) [✗]: Marketplace provider ID (etsy, ebay, etc.)
+
+- `userId` (string) [✗]: User who owns the connection
+
+- `syncDirection` (string) [✗]: Direction of sync operation
+
+- `syncScope` (string) [✗]: Scope of listings to sync
+
+- `listingIds` (array) [✗]: Specific listing IDs to sync (if syncScope=specific)
+
+- `externalListingIds` (array) [✗]: External marketplace listing IDs to sync
+
+- `options` (object) [✗]: Sync configuration options
+
+- `priority` (string) [✗]: Processing priority
+
+- `requestId` (string) [✗]: Unique request identifier
+
+- `webhookUrl` (string) [✗]: Webhook URL for completion notification
+
+- `metadata` (object) [✗]: Additional request context
+
+
+
+### marketplace-publish-listing-completed
+
+**Description:** Indicates completion of marketplace listing publication. Contains external listing ID and URL, or error details if failed. Works with any marketplace provider (etsy, ebay, etc.).
+
+**Method:** `client.marketplacePublishListingCompleted(data)`
+
+**Payload Type:** `MarketplacePublishListingCompletedMessage`
+
+**Fields:**
+
+- `originalJobId` (string) [✗]: BullMQ job ID from original request
+
+- `listingId` (string) [✗]: Internal marketplace_items UUID
+
+- `metamodelId` (string) [✗]: UUID of the metamodel that was published
+
+- `marketplaceProvider` (string) [✗]: Marketplace provider type (etsy, ebay, etc.)
+
+- `materialName` (string) [✗]: Material variant name
+
+- `status` (string) [✗]: Publication result (SUCCESS or FAILED)
+
+- `externalListingId` (string) [✗]: External marketplace listing ID (only if status=SUCCESS)
+
+- `externalListingUrl` (string) [✗]: URL to view listing on marketplace (only if status=SUCCESS)
+
+- `externalFileId` (string) [✗]: External marketplace file ID (only if status=SUCCESS)
+
+- `error` (object) [✗]: Error details (only if status=FAILED)
+
+- `publishedAt` (string) [✗]: When the listing was created (ISO 8601, only if status=SUCCESS)
+
+- `processingDuration` (integer) [✗]: Processing time in milliseconds
+
+
+
+### marketplace-publish-listing-request
+
+**Description:** Publishes a single metamodel listing to a marketplace for a specific material variant. Creates listing, uploads digital file, and returns external listing ID. This message is enqueued for EACH material variant when publishing a metamodel. The marketplace type (etsy, ebay, etc.) is determined by the marketplaceProvider field.
+
+**Method:** `client.marketplacePublishListingRequest(data)`
+
+**Payload Type:** `MarketplacePublishListingRequestMessage`
+
+**Fields:**
+
+- `listingId` (string) [✗]: Internal marketplace_items table UUID
+
+- `metamodelId` (string) [✗]: UUID of the metamodel being published
+
+- `ownerId` (string) [✗]: UUID of the user who owns the metamodel
+
+- `marketplaceProvider` (string) [✗]: Marketplace provider type (etsy, ebay, leboncoin, etc.)
+
+- `marketplaceConnectionId` (string) [✗]: UUID of the marketplace connection configuration
+
+- `materialVariant` (object) [✗]: Material-specific listing configuration
+
+- `baseListingData` (object) [✗]: Common listing information shared across variants
+
+- `publishOptions` (object) [✗]: Publishing configuration (marketplace-specific options)
+
+- `marketplaceCredentials` (object) [✗]: Encrypted marketplace credentials (retrieved from marketplaceConnectionId)
+
+- `fileMetadata` (object) [✗]: Digital file to upload
+
+- `webhookUrl` (string) [✗]: Callback URL for completion notification
+
 
 
 ### media-batch-download-completed
@@ -233,6 +781,43 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 
 
+### model-analytics-collection-request
+
+**Description:** Request to collect marketplace analytics for a specific metamodel.
+Triggered by backend scheduler every 6 hours for popular/tagged metamodels.
+
+Worker performs targeted market searches based on metamodel metadata
+and stores aggregated statistics in Elasticsearch for trend analysis.
+
+
+**Method:** `client.modelAnalyticsCollectionRequest(data)`
+
+**Payload Type:** `ModelAnalyticsCollectionRequestMessage`
+
+**Fields:**
+
+- `metamodelId` (string) [✓]: The metamodel ID to collect analytics for
+
+- `ownerId` (string) [✓]: Owner user ID for audit trail
+
+- `primaryCategory` (string) [✗]: Primary classification category (e.g., "miniature", "terrain")
+
+- `subCategory` (string) [✗]: Sub-category for more specific targeting
+
+- `tags` (array) [✗]: Relevant tags from metamodel metadata (max 10)
+
+- `franchise` (string) [✗]: Franchise name if detected (e.g., "Dungeons & Dragons")
+
+- `confidence` (number) [✗]: Classification confidence score
+
+- `priority` (string) [✗]: Collection priority level
+
+- `triggeredBy` (string) [✗]: Source of trigger (e.g., "backend-scheduler", "manual")
+
+- `triggeredAt` (string) [✗]: Timestamp when collection was triggered
+
+
+
 ### model-discovery-folder-processed-event
 
 **Description:** Handles model discovery folder processed events.
@@ -339,7 +924,7 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 ### model-metadata-generation-request
 
-**Description:** Handles model metadata generation requests.
+**Description:** Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
 
 **Method:** `client.modelMetadataGenerationRequest(data)`
 
@@ -349,9 +934,13 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 - `modelId` (string) [✗]: The unique identifier for the model.
 
-- `storageConnectionId` (string) [✗]: The ID of the storage connection.
+- `ownerId` (string) [✗]: The identifier of the user who owns the model.
 
-- `filePath` (string) [✗]: The path to the model file.
+- `storageConnectionId` (string) [✗]: The ID of the storage connection (legacy - used if minioPath not provided).
+
+- `filePath` (string) [✗]: The path to the model file (legacy - used if minioPath not provided).
+
+- `minioPath` (string) [✗]: Path to model in MinIO (e.g., 'raw_models/{modelId}/original.glb'). If provided, file will be read from MinIO instead of downloading from storage provider.
 
 - `fileName` (string) [✗]: The name of the model file.
 
@@ -361,6 +950,8 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 - `storageProviderType` (string) [✗]: The type of the storage provider.
 
+- `parentJobId` (string) [✗]: ID of parent file-download job (for BullMQ dependency tracking).
+
 - `modelThumbnailUrl` (string) [✗]: The URL of the model thumbnail.
 
 - `metamodel` (object) [✗]: The metamodel of the model.
@@ -405,6 +996,120 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 
 
+### model-sellability-analysis-completed
+
+**Description:** Contains sellability analysis results including Etsy-specific recommendations, material pricing, and marketplace compatibility scores
+
+**Method:** `client.modelSellabilityAnalysisCompleted(data)`
+
+**Payload Type:** `ModelSellabilityAnalysisCompletedMessage`
+
+**Fields:**
+
+- `metamodelId` (string) [✗]: Metamodel UUID
+
+- `ownerId` (string) [✗]: Owner user ID
+
+- `sellabilityScore` (number) [✗]: Overall sellability score (0-100)
+
+- `pricingRecommendations` (object) [✗]: Pricing analysis and recommendations with material-specific pricing (v2.0.0)
+
+- `marketplaceRecommendations` (array) [✗]: Recommended marketplaces with Etsy-specific scoring (v2.0.0)
+
+- `demandAnalysis` (object) [✗]: Market demand insights
+
+- `qualityFactors` (object) [✗]: Quality-related factors affecting sellability
+
+- `recommendations` (array) [✗]: Actionable recommendations to improve sellability
+
+- `analyzedAt` (string) [✗]: Analysis completion timestamp (ISO 8601)
+
+- `analysisVersion` (string) [✗]: Analysis algorithm version
+
+- `error` (object) [✗]: Error information if analysis failed
+
+
+
+### model-sellability-analysis-request
+
+**Description:** Analyzes a metamodel to determine sellability score, pricing recommendations, and optimal marketplace selection. Enhanced with Etsy-specific analysis including competitor pricing, category demand trends, and material suitability.
+
+**Method:** `client.modelSellabilityAnalysisRequest(data)`
+
+**Payload Type:** `ModelSellabilityAnalysisRequestMessage`
+
+**Fields:**
+
+- `metamodelId` (string) [✗]: UUID of the metamodel to analyze. Worker will fetch all model metadata, technical metadata, enriched metadata, and child models from PostgreSQL.
+
+- `ownerId` (string) [✗]: UUID of the user who owns the metamodel
+
+- `analysisOptions` (object) [✗]: Optional analysis configuration
+
+
+
+### model-semantic-analysis-completed
+
+**Description:** Handles completion of 3D model semantic analysis with generated tags and similarity results.
+
+**Method:** `client.modelSemanticAnalysisCompleted(data)`
+
+**Payload Type:** `ModelSemanticAnalysisCompletedMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: The unique identifier for the model.
+
+- `userId` (string) [✗]: The user ID who owns the model.
+
+- `processingStatus` (string) [✗]: Final processing status.
+
+- `semanticMetadata` (object) [✗]: Generated semantic metadata and analysis results.
+
+- `processingTime` (object) [✗]: Processing performance metrics.
+
+- `qualityMetrics` (object) [✗]: Processing quality and confidence metrics.
+
+- `error` (object) [✗]: Error information if processing failed.
+
+- `debugInfo` (object) [✗]: Additional debug information for troubleshooting.
+
+
+
+### model-semantic-analysis-request
+
+**Description:** Handles 3D model semantic analysis requests using ULIP-2 neural networks and FAISS vector similarity search.
+
+**Method:** `client.modelSemanticAnalysisRequest(data)`
+
+**Payload Type:** `ModelSemanticAnalysisRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: The unique identifier for the model.
+
+- `userId` (string) [✗]: The user ID who owns the model.
+
+- `storageConnectionId` (string) [✗]: The ID of the storage connection.
+
+- `filePath` (string) [✗]: The path to the 3D model file in storage.
+
+- `fileName` (string) [✗]: The name of the model file.
+
+- `fileSize` (number) [✗]: The size of the model file in bytes.
+
+- `storageProviderType` (string) [✗]: The type of the storage provider (S3, GoogleDrive, SFTP, etc).
+
+- `processingOptions` (object) [✗]: Configuration options for semantic analysis.
+
+- `priority` (number) [✗]: Processing priority (1=highest, 10=lowest).
+
+- `webhookUrl` (string) [✗]: Optional webhook URL for completion notification.
+
+- `retryCount` (number) [✗]: Current retry attempt number.
+
+
+
 ### model-technical-metadata-completed
 
 **Description:** Reports comprehensive results of technical metadata analysis including geometry, quality metrics, and print-readiness assessment
@@ -507,7 +1212,11 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 - `ownerId` (string) [✗]: User ID who owns the model
 
-- `storageLocation` (object) [✗]: Location of the 3D model file
+- `storageLocation` (object) [✗]: Location of the 3D model file (legacy - used for direct download if minioPath not provided)
+
+- `minioPath` (string) [✗]: Path to model in MinIO (e.g., 'raw_models/{modelId}/original.glb'). If provided, file will be read from MinIO instead of downloading from storage provider.
+
+- `parentJobId` (string) [✗]: ID of parent file-download job (for BullMQ dependency tracking).
 
 - `analysisOptions` (object) [✗]: Optional analysis configuration parameters
 
@@ -539,7 +1248,7 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 ### thumbnail-generation-request
 
-**Description:** Handles thumbnail generation requests with customization options.
+**Description:** Handles thumbnail generation requests with customization options. Supports both storage provider downloads and MinIO-cached files.
 
 **Method:** `client.thumbnailGenerationRequest(data)`
 
@@ -551,14 +1260,129 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 - `ownerId` (string) [✗]: The identifier of the user who owns the entity.
 
-- `storageLocation` (object) [✗]: The storage location of the model.
+- `storageLocation` (object) [✗]: The storage location of the model (legacy - used for direct download if minioPath not provided).
+
+- `minioPath` (string) [✗]: Path to model in MinIO (e.g., 'raw_models/{modelId}/original.glb'). If provided, file will be read from MinIO instead of downloading from storage provider.
 
 - `previewType` (string) [✗]: The type of preview to generate, e.g., 'default', 'static', 'glb'.
 
+- `generate360Views` (boolean) [✗]: Generate 16 angle views for 360° preview (4 horizontal x 4 vertical angles).
+
+- `parentJobId` (string) [✗]: ID of parent file-download job (for BullMQ dependency tracking).
+
 - `customization` (object) [✗]: User-defined customizations for the thumbnail.
 
 
 
+### user-engagement-event
+
+**Description:** User engagement and onboarding tracking events for analytics and behavioral insights.
+
+Captures key user actions throughout their journey:
+- Account creation and onboarding steps
+- Feature usage and adoption
+- Model management activities
+- Marketplace interactions
+- Subscription changes
+
+Used for:
+- User onboarding funnel analysis
+- Feature adoption tracking
+- User retention metrics
+- A/B testing and experimentation
+- Personalization and recommendations
+- Product analytics dashboards
+
+
+**Method:** `client.userEngagementEvent(data)`
+
+**Payload Type:** `UserEngagementEventMessage`
+
+**Fields:**
+
+- `eventType` (string) [✓]: Category of user engagement event
+
+- `action` (string) [✓]: Specific user action performed
+
+- `timestamp` (string) [✓]: ISO 8601 timestamp when the action occurred
+
+- `userId` (string) [✓]: Unique identifier of the user
+
+- `userEmail` (string) [✗]: User's email (hashed for privacy in analytics)
+
+- `userCreatedAt` (string) [✗]: When the user account was created (for cohort analysis)
+
+- `userPlanTier` (string) [✗]: Current subscription plan tier
+
+- `sessionId` (string) [✗]: User session identifier for grouping actions
+
+- `requestId` (string) [✗]: Request ID for correlation with logs
+
+- `actionDetails` (object) [✗]: Additional context about the action
+
+- `source` (string) [✗]: Where the action originated
+
+- `httpMethod` (string) [✗]: HTTP method used
+
+- `httpUrl` (string) [✗]: API endpoint path
+
+- `httpStatusCode` (integer) [✗]: HTTP response status code
+
+- `durationMs` (number) [✗]: Action duration in milliseconds
+
+- `experimentId` (string) [✗]: A/B test or experiment ID
+
+- `experimentVariant` (string) [✗]: Experiment variant/group
+
+- `environment` (string) [✗]: Deployment environment
+
+- `clientInfo` (object) [✗]: Client/browser information (anonymized)
+
+
+
+### worker-analytics-event
+
+**Description:** Analytics event emitted by workers for tracking processing metrics, user behavior,
+and model statistics. Consumed by worker-analytic-collector and forwarded to ELK.
+
+All workers MUST emit this event upon job completion (success or failure).
+Each worker includes its specific metrics in the `metrics` object.
+
+
+**Method:** `client.workerAnalyticsEvent(data)`
+
+**Payload Type:** `WorkerAnalyticsEventMessage`
+
+**Fields:**
+
+- `eventType` (string) [✓]: Type of analytics event
+
+- `workerId` (string) [✓]: Identifier of the worker that processed the job
+
+- `jobId` (string) [✓]: Unique job identifier from BullMQ
+
+- `timestamp` (string) [✓]: ISO 8601 timestamp of event emission
+
+- `userId` (string) [✗]: User who owns the model/triggered the job
+
+- `modelId` (string) [✗]: Model identifier (if applicable)
+
+- `metamodelId` (string) [✗]: Metamodel identifier (if applicable)
+
+- `storageItemId` (string) [✗]: Storage item identifier (for download events)
+
+- `status` (string) [✗]: Job completion status
+
+- `errorCode` (string) [✗]: Error code if status is failure
+
+- `errorMessage` (string) [✗]: Error message if status is failure
+
+- `timing` (object) [✗]: Processing time metrics in milliseconds
+
+- `metrics` (object) [✗]: Worker-specific metrics. Structure varies by eventType.
+
+
+
 ## Configuration
 
 ### Environment Variables
@@ -597,11 +1421,86 @@ new WorkerClient(config: WorkerClientConfig)
   - Get the current status of a job
 
 
+- `backendLoggingEvent(data: BackendLoggingEventMessage): Promise<JobResponse>`
+  - Centralized logging event for capturing all warn/error/failure logs from meshsync-backend.
+This event is sent to ELK for centralized monitoring, alerting, and debugging.
+
+Automatically emitted by the custom Pino logger interceptor when:
+- logger.warn() is called
+- logger.error() is called
+- uncaught exceptions occur
+- request failures happen (4xx, 5xx responses)
+
+Used for:
+- System health monitoring
+- Error tracking and alerting
+- Performance degradation detection
+- Security incident tracking
+- Compliance and audit trails
+
+
+- `etsyAnalyticsSyncCompleted(data: EtsyAnalyticsSyncCompletedMessage): Promise<JobResponse>`
+  - Contains synced analytics data for Etsy listings. Backend stores this in etsy_analytics_snapshots table and indexes to ELK.
+
+
+- `etsyAnalyticsSyncRequest(data: EtsyAnalyticsSyncRequestMessage): Promise<JobResponse>`
+  - Syncs analytics data from Etsy API for one or more listings. Fetches views, favorites, sales, revenue, and traffic source data.
+Can sync: - Specific listings (provide listingIds) - All user listings (provide userId, empty listingIds) - Shop-level analytics (provide shopId)
+
+
+- `etsyPublishListingCompleted(data: EtsyPublishListingCompletedMessage): Promise<JobResponse>`
+  - Indicates completion of Etsy listing publication. Contains external Etsy listing ID and URL, or error details if failed.
+
+
+- `etsyPublishListingRequest(data: EtsyPublishListingRequestMessage): Promise<JobResponse>`
+  - Publishes a single metamodel listing to Etsy for a specific material variant. Creates Etsy listing, uploads digital file, and returns external listing ID.
+This message is enqueued for EACH material variant when publishing a metamodel.
+Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
+
+
 - `fileDownloadCompleted(data: FileDownloadCompletedMessage): Promise<JobResponse>`
   - Notifies that a file download has been processed, indicating success or failure.
 
 - `fileDownloadRequest(data: FileDownloadRequestMessage): Promise<JobResponse>`
-  - Handles file download requests.
+  - Downloads model file from storage provider to MinIO for processing pipeline. Acts as parent job for thumbnail generation, technical metadata analysis, and metadata generation.
+
+- `marketplaceAnalyticsSyncCompleted(data: MarketplaceAnalyticsSyncCompletedMessage): Promise<JobResponse>`
+  - Contains synced analytics data for marketplace listings. Backend stores this in marketplace_analytics_snapshots table and indexes to ELK. Works with any marketplace provider.
+
+- `marketplaceAnalyticsSyncRequest(data: MarketplaceAnalyticsSyncRequestMessage): Promise<JobResponse>`
+  - Syncs analytics data from marketplace API for one or more listings. Fetches views, favorites, sales, revenue, and traffic source data. Can sync: specific listings, all user listings, or shop-level analytics. Works with any marketplace provider that supports analytics (etsy, ebay, etc.).
+
+- `marketplaceConnectionSyncCompleted(data: MarketplaceConnectionSyncCompletedMessage): Promise<JobResponse>`
+  - Notification that marketplace connection sync has completed. Contains updated connection metadata, profile information, and sync statistics.
+
+
+- `marketplaceConnectionSyncRequest(data: MarketplaceConnectionSyncRequestMessage): Promise<JobResponse>`
+  - Requests synchronization of marketplace connection data including: - Profile information and shop details - Account status and permissions - Available categories and shipping profiles - Rate limits and API quotas
+This is typically triggered after initial connection or periodically to keep marketplace metadata up to date.
+
+
+- `marketplaceCredentialRotationCompleted(data: MarketplaceCredentialRotationCompletedMessage): Promise<JobResponse>`
+  - Notification that marketplace credential rotation has completed. Contains the rotation results, new credential metadata, and any issues encountered.
+
+
+- `marketplaceCredentialRotationRequest(data: MarketplaceCredentialRotationRequestMessage): Promise<JobResponse>`
+  - Requests rotation/refresh of marketplace connection credentials. This is used for: - OAuth token refresh when tokens are near expiry - API key rotation for enhanced security - Re-authentication after connection errors - Scheduled credential updates
+
+
+- `marketplaceListingSyncCompleted(data: MarketplaceListingSyncCompletedMessage): Promise<JobResponse>`
+  - Notification that marketplace listing sync operation has completed. Contains detailed results of the sync including created/updated listings, errors encountered, and performance statistics.
+
+
+- `marketplaceListingSyncRequest(data: MarketplaceListingSyncRequestMessage): Promise<JobResponse>`
+  - Requests synchronization of marketplace listings for a connection. Can sync specific listings or all listings for a marketplace connection.
+Includes bidirectional sync: - Pull: Fetch listings from marketplace to update local database - Push: Update marketplace listings with local changes - Full: Both pull and push operations
+
+
+- `marketplacePublishListingCompleted(data: MarketplacePublishListingCompletedMessage): Promise<JobResponse>`
+  - Indicates completion of marketplace listing publication. Contains external listing ID and URL, or error details if failed. Works with any marketplace provider (etsy, ebay, etc.).
+
+- `marketplacePublishListingRequest(data: MarketplacePublishListingRequestMessage): Promise<JobResponse>`
+  - Publishes a single metamodel listing to a marketplace for a specific material variant. Creates listing, uploads digital file, and returns external listing ID. This message is enqueued for EACH material variant when publishing a metamodel. The marketplace type (etsy, ebay, etc.) is determined by the marketplaceProvider field.
 
 - `mediaBatchDownloadCompleted(data: MediaBatchDownloadCompletedMessage): Promise<JobResponse>`
   - Notifies that a batch media download has been completed.
@@ -616,6 +1515,14 @@ new WorkerClient(config: WorkerClientConfig)
 - `metamodelMetadataGenerationRequest(data: MetamodelMetadataGenerationRequestMessage): Promise<JobResponse>`
   - Handles metamodel metadata generation requests via Ollama. Aggregates data from constituent models and generates AI-enhanced metadata.
 
+- `modelAnalyticsCollectionRequest(data: ModelAnalyticsCollectionRequestMessage): Promise<JobResponse>`
+  - Request to collect marketplace analytics for a specific metamodel.
+Triggered by backend scheduler every 6 hours for popular/tagged metamodels.
+
+Worker performs targeted market searches based on metamodel metadata
+and stores aggregated statistics in Elasticsearch for trend analysis.
+
+
 - `modelDiscoveryFolderProcessedEvent(data: ModelDiscoveryFolderProcessedEventMessage): Promise<JobResponse>`
   - Handles model discovery folder processed events.
 
@@ -632,7 +1539,7 @@ new WorkerClient(config: WorkerClientConfig)
   - Handles model metadata generation completed.
 
 - `modelMetadataGenerationRequest(data: ModelMetadataGenerationRequestMessage): Promise<JobResponse>`
-  - Handles model metadata generation requests.
+  - Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
 
 - `modelMetamodelDetectionFound(data: ModelMetamodelDetectionFoundMessage): Promise<JobResponse>`
   - Handles model metamodel detection found with hierarchical relationships.
@@ -640,6 +1547,18 @@ new WorkerClient(config: WorkerClientConfig)
 - `modelMetamodelDetectionRequest(data: ModelMetamodelDetectionRequestMessage): Promise<JobResponse>`
   - Handles model metamodel detection requests.
 
+- `modelSellabilityAnalysisCompleted(data: ModelSellabilityAnalysisCompletedMessage): Promise<JobResponse>`
+  - Contains sellability analysis results including Etsy-specific recommendations, material pricing, and marketplace compatibility scores
+
+- `modelSellabilityAnalysisRequest(data: ModelSellabilityAnalysisRequestMessage): Promise<JobResponse>`
+  - Analyzes a metamodel to determine sellability score, pricing recommendations, and optimal marketplace selection. Enhanced with Etsy-specific analysis including competitor pricing, category demand trends, and material suitability.
+
+- `modelSemanticAnalysisCompleted(data: ModelSemanticAnalysisCompletedMessage): Promise<JobResponse>`
+  - Handles completion of 3D model semantic analysis with generated tags and similarity results.
+
+- `modelSemanticAnalysisRequest(data: ModelSemanticAnalysisRequestMessage): Promise<JobResponse>`
+  - Handles 3D model semantic analysis requests using ULIP-2 neural networks and FAISS vector similarity search.
+
 - `modelTechnicalMetadataCompleted(data: ModelTechnicalMetadataCompletedMessage): Promise<JobResponse>`
   - Reports comprehensive results of technical metadata analysis including geometry, quality metrics, and print-readiness assessment
 
@@ -650,7 +1569,34 @@ new WorkerClient(config: WorkerClientConfig)
   - Handles thumbnail generation completed.
 
 - `thumbnailGenerationRequest(data: ThumbnailGenerationRequestMessage): Promise<JobResponse>`
-  - Handles thumbnail generation requests with customization options.
+  - Handles thumbnail generation requests with customization options. Supports both storage provider downloads and MinIO-cached files.
+
+- `userEngagementEvent(data: UserEngagementEventMessage): Promise<JobResponse>`
+  - User engagement and onboarding tracking events for analytics and behavioral insights.
+
+Captures key user actions throughout their journey:
+- Account creation and onboarding steps
+- Feature usage and adoption
+- Model management activities
+- Marketplace interactions
+- Subscription changes
+
+Used for:
+- User onboarding funnel analysis
+- Feature adoption tracking
+- User retention metrics
+- A/B testing and experimentation
+- Personalization and recommendations
+- Product analytics dashboards
+
+
+- `workerAnalyticsEvent(data: WorkerAnalyticsEventMessage): Promise<JobResponse>`
+  - Analytics event emitted by workers for tracking processing metrics, user behavior,
+and model statistics. Consumed by worker-analytic-collector and forwarded to ELK.
+
+All workers MUST emit this event upon job completion (success or failure).
+Each worker includes its specific metrics in the `metrics` object.
+
 
 
 ### Response Types