@mesh-sync/worker-backend-client 1.0.6 → 4.0.3

package/README.md

@@ -100,6 +100,69 @@ 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.
@@ -251,7 +314,7 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 ### 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)`
 
@@ -261,8 +324,18 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 - `modelId` (string) [✗]: The unique identifier for the model to be downloaded.
 
+- `ownerId` (string) [✗]: The identifier of the user who owns the model. Optional - if not provided, will be retrieved from StorageConnection.
+
 - `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
@@ -325,6 +398,226 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 
 
+### 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.).
@@ -488,6 +781,43 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 
 
+### 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.
@@ -578,7 +908,7 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 ### model-metadata-generation-completed
 
-**Description:** Handles model metadata generation completed.
+**Description:** Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
 
 **Method:** `client.modelMetadataGenerationCompleted(data)`
 
@@ -586,15 +916,15 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 **Fields:**
 
-- `modelId` (string) [✓]: The unique identifier for the model.
+- `modelId` (string) [✓]: UUID of the model that was processed.
 
-- `metadata` (object) [✓]: The enriched metadata for the model.
+- `metadata` (object) [✓]: Enriched marketplace metadata generated by LLM.
 
 
 
 ### model-metadata-generation-request
 
-**Description:** Handles model metadata generation requests.
+**Description:** Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker fetches model data from database and uses thumbnails for enhanced analysis when available. Prerequisites: file download, thumbnail generation (optional for vision), and technical metadata analysis (strongly recommended).
 
 **Method:** `client.modelMetadataGenerationRequest(data)`
 
@@ -602,23 +932,17 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 **Fields:**
 
-- `modelId` (string) [✗]: The unique identifier for the model.
-
-- `storageConnectionId` (string) [✗]: The ID of the storage connection.
-
-- `filePath` (string) [✗]: The path to the model file.
-
-- `fileName` (string) [✗]: The name of the model file.
+- `modelId` (string) [✗]: UUID of the model to generate metadata for. Worker queries database for: Model.fileName, Model.fileSize, Model.storageItem (path, provider). For vision-enhanced analysis, worker queries thumbnail_media table for thumbnail paths.
 
-- `fileSize` (number) [✗]: The size of the model file in bytes.
+- `ownerId` (string) [✗]: UUID of the model owner. Used for authorization and audit logging.
 
-- `fileLastModified` (string) [✗]: The last modified date of the model file.
+- `parentJobId` (string) [✗]: ID of parent job (file-download, thumbnail-generation, or technical-analysis) for BullMQ dependency tracking. Ensures metadata generation runs after prerequisites complete. Should reference thumbnail-generation job when vision analysis is desired.
 
-- `storageProviderType` (string) [✗]: The type of the storage provider.
+- `technicalMetadata` (object) [✗]: Technical analysis results (geometry, quality metrics, printability) passed from backend. Worker-core-lib Model schema lacks technical_metadata column, so backend must provide this data. Used for enhanced LLM prompt context. Include: vertexCount, faceCount, surfaceArea, volume, qualityScore, printabilityScore, detectedIssues, etc.
 
-- `modelThumbnailUrl` (string) [✗]: The URL of the model thumbnail.
+- `thumbnailPath` (string) [✗]: Path to generated thumbnail in MinIO storage (e.g., 'thumbnails/{modelId}/thumbnail.webp'). If provided, enables vision-enhanced metadata generation. Worker can also query thumbnail_media table, but explicit path improves performance.
 
-- `metamodel` (object) [✗]: The metamodel of the model.
+- `enableVisionAnalysis` (boolean) [✗]: Flag to enable vision-based metadata enrichment using thumbnail images. Requires thumbnailPath or available thumbnail in database. Vision analysis generates more accurate descriptions, tags, and classifications based on visual appearance.
 
 
 
@@ -712,6 +1036,68 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 
 
+### 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
@@ -814,7 +1200,11 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 - `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
 
@@ -846,7 +1236,7 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 ### 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)`
 
@@ -858,14 +1248,193 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 - `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.
+
+
+
+### worker-metrics-enriched-event
+
+**Description:** Enriched metrics event for detailed worker monitoring, cost tracking,
+and performance analysis. Published to backend.logging.events for
+centralized monitoring and cost attribution.
+
+This event is emitted by all workers on job completion and includes:
+- LLM token usage and cost breakdown
+- System resource consumption (CPU, RAM, disk I/O)
+- Detailed timing breakdown by stage
+- User and context attribution
+- Model-specific metadata
+
+
+**Method:** `client.workerMetricsEnrichedEvent(data)`
+
+**Payload Type:** `WorkerMetricsEnrichedEventMessage`
+
+**Fields:**
+
+- `eventType` (string) [✓]: Fixed type for enriched worker metrics
+
+- `workerId` (string) [✓]: Identifier of the worker
+
+- `jobId` (string) [✓]: Unique BullMQ job identifier
+
+- `timestamp` (string) [✓]: ISO 8601 timestamp when job completed
+
+- `status` (string) [✓]: Job completion status
+
+- `userId` (string) [✗]: User who owns the resource/triggered the job
+
+- `tenantId` (string) [✗]: Organization/tenant ID (for multi-tenant deployments)
+
+- `sessionId` (string) [✗]: Session ID for correlating user actions
+
+- `requestId` (string) [✗]: Request ID from originating API call (X-Request-Id)
+
+- `modelId` (string) [✗]: Model ID being processed
+
+- `metamodelId` (string) [✗]: Metamodel ID being processed
+
+- `storageItemId` (string) [✗]: Storage item ID (for file operations)
+
+- `timing` (object) [✗]: Comprehensive timing breakdown
+
+- `llmUsage` (object) [✗]: LLM token usage and cost breakdown
+
+- `resources` (object) [✗]: System resource consumption during job
+
+- `workerMetrics` (object) [✗]: Worker-specific metrics (varies by worker type)
+
+- `error` (object) [✗]: Error details if status is failure
+
+- `environment` (string) [✗]: Deployment environment
+
+- `region` (string) [✗]: Cloud region/datacenter
+
+- `workerVersion` (string) [✗]: Worker service version
+
+- `hostname` (string) [✗]: Pod/container hostname
+
+
+
 ## Configuration
 
 ### Environment Variables
@@ -904,6 +1473,24 @@ 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.
 
@@ -927,7 +1514,7 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
   - 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.
@@ -935,6 +1522,32 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 - `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.).
 
@@ -954,6 +1567,14 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 - `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.
 
@@ -967,10 +1588,10 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
   - Handles model discovery scan requests events.
 
 - `modelMetadataGenerationCompleted(data: ModelMetadataGenerationCompletedMessage): Promise<JobResponse>`
-  - Handles model metadata generation completed.
+  - Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
 
 - `modelMetadataGenerationRequest(data: ModelMetadataGenerationRequestMessage): Promise<JobResponse>`
-  - Handles model metadata generation requests.
+  - Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker fetches model data from database and uses thumbnails for enhanced analysis when available. Prerequisites: file download, thumbnail generation (optional for vision), and technical metadata analysis (strongly recommended).
 
 - `modelMetamodelDetectionFound(data: ModelMetamodelDetectionFoundMessage): Promise<JobResponse>`
   - Handles model metamodel detection found with hierarchical relationships.
@@ -984,6 +1605,12 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 - `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
 
@@ -994,7 +1621,47 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
   - 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.
+
+
+- `workerMetricsEnrichedEvent(data: WorkerMetricsEnrichedEventMessage): Promise<JobResponse>`
+  - Enriched metrics event for detailed worker monitoring, cost tracking,
+and performance analysis. Published to backend.logging.events for
+centralized monitoring and cost attribution.
+
+This event is emitted by all workers on job completion and includes:
+- LLM token usage and cost breakdown
+- System resource consumption (CPU, RAM, disk I/O)
+- Detailed timing breakdown by stage
+- User and context attribution
+- Model-specific metadata
+
 
 
 ### Response Types