@mesh-sync/worker-backend-client 1.0.6 → 4.0.0-pr.51.20260312131431

package/README.md

@@ -100,6 +100,89 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 ## Available Message Types
 
 
+### analytics-collection-request
+
+**Description:** Request to trigger a manual market data collection job.
+Used for ad-hoc scraping of specific queries on marketplaces.
+
+
+**Method:** `client.analyticsCollectionRequest(data)`
+
+**Payload Type:** `AnalyticsCollectionRequestMessage`
+
+**Fields:**
+
+- `marketplace` (string) [✗]: The marketplace to scrape (etsy, ebay, etc.)
+
+- `query` (string) [✓]: The search query to use
+
+- `options` (object) [✗]: Collection options (pages, filters, etc.)
+
+
+
+### 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.
@@ -121,6 +204,8 @@ await client.sendToQueue(MessageTypes.FILE_DOWNLOAD_REQUEST, {
 
 - `results` (array) [✗]: Analytics for each synced listing
 
+- `credentialUpdate` (object) [✗]: New credentials if token was refreshed during operation
+
 - `errors` (array) [✗]: Errors for failed listings
 
 - `syncedAt` (string) [✗]: 
@@ -147,6 +232,8 @@ Can sync: - Specific listings (provide listingIds) - All user listings (provide
 
 - `shopId` (string) [✗]: Etsy shop ID for shop-level analytics
 
+- `credentials` (object) [✗]: Etsy OAuth credentials
+
 - `timeRange` (object) [✗]: Date range for historical analytics
 
 - `syncOptions` (object) [✗]: 
@@ -182,6 +269,8 @@ Can sync: - Specific listings (provide listingIds) - All user listings (provide
 
 - `etsyListingUrl` (string) [✗]: URL to view listing on Etsy (only if status=SUCCESS)
 
+- `credentialUpdate` (object) [✗]: New credentials if token was refreshed during operation
+
 - `etsyFileId` (string) [✗]: Etsy digital file ID (only if status=SUCCESS)
 
 - `error` (object) [✗]: Error details (only if status=FAILED)
@@ -211,6 +300,8 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 - `ownerId` (string) [✗]: User ID who owns the metamodel
 
+- `credentials` (object) [✗]: Etsy OAuth credentials
+
 - `materialVariant` (object) [✗]: Material-specific listing configuration
 
 - `baseListingData` (object) [✗]: Common listing information
@@ -251,7 +342,15 @@ 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.
+
+Retry Configuration:
+- Automatic retry enabled for transient failures (connection errors, timeouts)
+- Default: 5 attempts with exponential backoff (2s, 4s, 8s, 16s, 32s)
+- Retry on: STORAGE_TIMEOUT, NETWORK_ERROR, MINIO_UNAVAILABLE, CONNECTION_REFUSED
+- No retry on: INVALID_CREDENTIALS, FILE_NOT_FOUND, PERMISSION_DENIED
+
 
 **Method:** `client.fileDownloadRequest(data)`
 
@@ -261,562 +360,1588 @@ 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.
 
+- `metadata` (object) [✗]: Optional metadata from discovery. For Thingiverse, contains downloadUrl for direct file access.
 
+- `credentials` (object) [✗]: Decrypted credentials required for this specific download operation. Injected by the backend.
 
-### marketplace-analytics-sync-completed
+- `minioDestination` (object) [✗]: Destination in MinIO where file will be uploaded after download.
 
-**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.
+- `autoEnqueueChildren` (boolean) [✗]: Automatically enqueue thumbnail generation, technical metadata analysis, and metadata generation jobs after download completes.
 
-**Method:** `client.marketplaceAnalyticsSyncCompleted(data)`
+- `previewType` (string) [✗]: Preview type for thumbnail generation (passed to child job).
 
-**Payload Type:** `MarketplaceAnalyticsSyncCompletedMessage`
+- `generate360Views` (boolean) [✗]: Generate 16 angle views for 360° preview (passed to child job).
 
-**Fields:**
+- `webhookUrl` (string) [✗]: Optional webhook URL to call when download completes. If provided, worker will POST completion status to this endpoint.
 
-- `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)
+### file-vectorize-completed
 
-- `syncedCount` (integer) [✗]: Number of listings successfully synced
+**Description:** Result of the vectorization process containing the embedding vector.
 
-- `errorCount` (integer) [✗]: Number of listings that failed
+**Method:** `client.fileVectorizeCompleted(data)`
 
-- `results` (array) [✗]: Analytics for each synced listing
+**Payload Type:** `FileVectorizeCompletedMessage`
 
-- `errors` (array) [✗]: Errors for failed listings
+**Fields:**
 
-- `syncedAt` (string) [✗]: When sync completed (ISO 8601)
+- `fileId` (string) [✗]: 
 
-- `nextScheduledSync` (string) [✗]: When next automatic sync should occur (ISO 8601)
+- `vector` (array) [✗]: The computed embedding vector
 
+- `modelName` (string) [✗]: 
 
+- `dimension` (integer) [✗]: Length of the vector (e.g., 512)
 
-### 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)`
+### file-vectorize-request
 
-**Payload Type:** `MarketplaceAnalyticsSyncRequestMessage`
+**Description:** Request to generate a vector embedding for an image file using CLIP.
 
-**Fields:**
+**Method:** `client.fileVectorizeRequest(data)`
 
-- `marketplaceProvider` (string) [✗]: Marketplace provider type (etsy, ebay, etc.)
+**Payload Type:** `FileVectorizeRequestMessage`
 
-- `marketplaceConnectionId` (string) [✗]: UUID of the marketplace connection configuration
+**Fields:**
 
-- `listingIds` (array) [✗]: Internal listing UUIDs to sync. Empty array = sync all for user.
+- `fileId` (string) [✗]: The ID of the file in the database
 
-- `userId` (string) [✗]: UUID of user whose listings to sync (if listingIds empty)
+- `storageItem` () [✗]: Location of the image file
 
-- `externalShopId` (string) [✗]: External marketplace shop ID for shop-level analytics
+- `modelName` (string) [✗]: Optional: Specific model version to use
 
-- `timeRange` (object) [✗]: Date range for historical analytics
 
-- `syncOptions` (object) [✗]: Optional sync configuration
 
-- `marketplaceCredentials` (object) [✗]: Encrypted marketplace credentials (retrieved from marketplaceConnectionId)
+### ip-check-completed
 
-- `webhookUrl` (string) [✗]: Callback URL for completion notification
+**Description:** Contains IP verification results including trademark risk, copyright risk, detected brands/franchises, and analysis confidence scores
 
+**Method:** `client.ipCheckCompleted(data)`
 
+**Payload Type:** `IpCheckCompletedMessage`
 
-### marketplace-publish-listing-completed
+**Fields:**
 
-**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.).
+- `modelId` (string) [✗]: Model UUID that was analyzed
 
-**Method:** `client.marketplacePublishListingCompleted(data)`
+- `ownerId` (string) [✗]: Owner user ID
 
-**Payload Type:** `MarketplacePublishListingCompletedMessage`
+- `entityType` (string) [✗]: Type of entity checked: 'model' or 'metamodel'
 
-**Fields:**
+- `status` (string) [✗]: Overall IP check outcome: 'clear', 'flagged', or 'error'
 
-- `originalJobId` (string) [✗]: BullMQ job ID from original request
+- `trademarkRisk` (string) [✗]: Detected trademark infringement risk level: 'none', 'low', 'medium', 'high'
 
-- `listingId` (string) [✗]: Internal marketplace_items UUID
+- `copyrightRisk` (string) [✗]: Detected copyright infringement risk level: 'none', 'low', 'medium', 'high'
 
-- `metamodelId` (string) [✗]: UUID of the metamodel that was published
+- `matchedBrands` (array) [✗]: Brand names detected in model name or content
 
-- `marketplaceProvider` (string) [✗]: Marketplace provider type (etsy, ebay, etc.)
+- `matchedFranchises` (array) [✗]: Franchise/character names detected
 
-- `materialName` (string) [✗]: Material variant name
+- `similarModelsCount` (integer) [✗]: Number of visually similar models found
 
-- `status` (string) [✗]: Publication result (SUCCESS or FAILED)
+- `confidence` (number) [✗]: Overall confidence score for the analysis (0.0-1.0)
 
-- `externalListingId` (string) [✗]: External marketplace listing ID (only if status=SUCCESS)
+- `riskScorePercent` (integer) [✗]: Risk score as 0-100 integer (FR-024: >70 HIGH, 40-70 MEDIUM, <40 LOW)
 
-- `externalListingUrl` (string) [✗]: URL to view listing on marketplace (only if status=SUCCESS)
+- `riskLevel` (string) [✗]: Overall risk level: 'none', 'low', 'medium', 'high'
 
-- `externalFileId` (string) [✗]: External marketplace file ID (only if status=SUCCESS)
+- `recommendation` (string) [✗]: Recommended action: 'block' (HIGH risk), 'warn' (MEDIUM risk), 'allow' (LOW/NONE risk)
 
-- `error` (object) [✗]: Error details (only if status=FAILED)
+- `suggestedChanges` (object) [✗]: Suggested modifications to reduce IP risk
 
-- `publishedAt` (string) [✗]: When the listing was created (ISO 8601, only if status=SUCCESS)
+- `heuristicResults` (object) [✗]: Detailed results from each heuristic check
 
-- `processingDuration` (integer) [✗]: Processing time in milliseconds
+- `error` (object) [✗]: Error details if status is 'error'
 
+- `processingDurationMs` (integer) [✗]: Total 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.
+### ip-check-request
 
-**Method:** `client.marketplacePublishListingRequest(data)`
+**Description:** Triggers intellectual property verification analysis for a model thumbnail, detecting potential trademark and copyright issues using perceptual hashing, text analysis, and optional reverse image search.
 
-**Payload Type:** `MarketplacePublishListingRequestMessage`
+**Method:** `client.ipCheckRequest(data)`
+
+**Payload Type:** `IpCheckRequestMessage`
 
 **Fields:**
 
-- `listingId` (string) [✗]: Internal marketplace_items table UUID
+- `modelId` (string) [✗]: Unique identifier for the model to analyze
 
-- `metamodelId` (string) [✗]: UUID of the metamodel being published
+- `ownerId` (string) [✗]: User ID who owns the model
 
-- `ownerId` (string) [✗]: UUID of the user who owns the metamodel
+- `entityType` (string) [✗]: Type of entity being checked: 'model' or 'metamodel'
 
-- `marketplaceProvider` (string) [✗]: Marketplace provider type (etsy, ebay, leboncoin, etc.)
+- `modelName` (string) [✗]: Name of the model for trademark/franchise text detection
 
-- `marketplaceConnectionId` (string) [✗]: UUID of the marketplace connection configuration
+- `tags` (array) [✗]: Model tags for IP reference detection
 
-- `materialVariant` (object) [✗]: Material-specific listing configuration
+- `description` (string) [✗]: Model description for text-based IP analysis
 
-- `baseListingData` (object) [✗]: Common listing information shared across variants
+- `thumbnailUrl` (string) [✗]: URL to fetch the thumbnail image for visual analysis
 
-- `publishOptions` (object) [✗]: Publishing configuration (marketplace-specific options)
+- `minioPath` (string) [✗]: Path to thumbnail in MinIO if stored internally
 
-- `marketplaceCredentials` (object) [✗]: Encrypted marketplace credentials (retrieved from marketplaceConnectionId)
+- `additionalImageUrls` (array) [✗]: Optional additional images for more comprehensive analysis (e.g., 360° views)
 
-- `fileMetadata` (object) [✗]: Digital file to upload
+- `analysisOptions` (object) [✗]: Optional analysis configuration
 
-- `webhookUrl` (string) [✗]: Callback URL for completion notification
 
 
+### marketplace-connection-sync-completed
 
-### media-batch-download-completed
+**Description:** Notification that marketplace connection sync has completed. Contains updated connection metadata, profile information, and sync statistics.
 
-**Description:** Notifies that a batch media download has been completed.
 
-**Method:** `client.mediaBatchDownloadCompleted(data)`
+**Method:** `client.marketplaceConnectionSyncCompleted(data)`
 
-**Payload Type:** `MediaBatchDownloadCompletedMessage`
+**Payload Type:** `MarketplaceConnectionSyncCompletedMessage`
 
 **Fields:**
 
-- `batchId` (string) [✓]: The unique identifier for the batch download operation.
-
-- `status` (string) [✓]: The final status of the batch download operation.
-
-- `processedFiles` (array) [✗]: List of successfully processed files.
-
-- `failedFiles` (array) [✗]: List of files that failed to process.
-
-- `processedAt` (string) [✓]: Timestamp when the batch processing completed.
+- `requestId` (string) [✗]: Original request ID for correlation
 
-- `statistics` (object) [✗]: Statistics about the batch processing.
+- `connectionId` (string) [✗]: Marketplace connection that was synced
 
+- `marketplaceId` (string) [✗]: Marketplace provider ID
 
+- `userId` (string) [✗]: Connection owner user ID
 
-### media-batch-download-request
+- `status` (string) [✗]: Overall sync result status
 
-**Description:** Request to download and process a batch of media files from a storage provider. Images are compressed and resized to specified dimensions, converted to WebP format. Text files and documents are processed and stored with metadata. All processed files are uploaded to MinIO S3 storage under the media/{batchId}/ prefix.
+- `syncType` (string) [✗]: Type of sync that was performed
 
+- `connectionData` (object) [✗]: Updated connection information
 
-**Method:** `client.mediaBatchDownloadRequest(data)`
+- `categories` (array) [✗]: Available marketplace categories
 
-**Payload Type:** `MediaBatchDownloadRequestMessage`
+- `statistics` (object) [✗]: Sync operation statistics
 
-**Fields:**
+- `completedAt` (string) [✗]: When sync completed
 
-- `batchId` (string) [✗]: Unique identifier for this batch of media files. Used for organizing processed files in S3 storage (media/{batchId}/) and correlating with completion responses.
+- `error` (object) [✗]: Error details if sync failed
 
 
-- `storageConnectionId` (string) [✗]: UUID of the StorageConnection entity from which to download the media files. Used to authenticate and access the source storage provider.
 
+### marketplace-connection-sync-request
 
-- `mediaFiles` (array) [✗]: Array of media files to download and process. Must contain at least one file. Each file includes metadata for identification and processing.
+**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.
 
 
-- `compressionSettings` (object) [✗]: Optional compression settings that override deployment environment defaults. If not provided, uses values from MAX_IMAGE_WIDTH, MAX_IMAGE_HEIGHT, IMAGE_QUALITY, and OUTPUT_FORMAT environment variables.
+**Method:** `client.marketplaceConnectionSyncRequest(data)`
 
+**Payload Type:** `MarketplaceConnectionSyncRequestMessage`
 
+**Fields:**
 
+- `connectionId` (string) [✗]: Internal marketplace connection ID
 
-### metamodel-metadata-generation-completed
+- `marketplaceId` (string) [✗]: Marketplace provider ID (etsy, ebay, etc.)
 
-**Description:** Handles metamodel metadata generation completion. Contains AI-generated metadata and aggregated technical analysis.
+- `userId` (string) [✗]: User who owns this connection
 
-**Method:** `client.metamodelMetadataGenerationCompleted(data)`
+- `syncType` (string) [✗]: Type of sync to perform
 
-**Payload Type:** `MetamodelMetadataGenerationCompletedMessage`
+- `priority` (string) [✗]: Processing priority
 
-**Fields:**
+- `requestId` (string) [✗]: Unique request identifier for tracking
 
-- `metamodelId` (string) [✓]: The unique identifier for the metamodel
+- `webhookUrl` (string) [✗]: Webhook URL to call when sync completes
 
-- `metadata` (object) [✓]: AI-generated metadata for the metamodel
+- `metadata` (object) [✗]: Additional context data
 
-- `technicalMetadata` (object) [✓]: Aggregated technical analysis from constituent models
 
 
+### marketplace-credential-rotation-completed
 
-### metamodel-metadata-generation-request
+**Description:** Notification that marketplace credential rotation has completed. Contains the rotation results, new credential metadata, and any issues encountered.
 
-**Description:** Handles metamodel metadata generation requests via Ollama. Aggregates data from constituent models and generates AI-enhanced metadata.
 
-**Method:** `client.metamodelMetadataGenerationRequest(data)`
+**Method:** `client.marketplaceCredentialRotationCompleted(data)`
 
-**Payload Type:** `MetamodelMetadataGenerationRequestMessage`
+**Payload Type:** `MarketplaceCredentialRotationCompletedMessage`
 
 **Fields:**
 
-- `metamodelId` (string) [✗]: The unique identifier for the metamodel
+- `requestId` (string) [✗]: Original rotation request ID
 
-- `constituentModelIds` (array) [✗]: Array of model IDs that compose this metamodel
+- `connectionId` (string) [✗]: Marketplace connection that was rotated
 
-- `name` (string) [✗]: The name of the metamodel
+- `marketplaceId` (string) [✗]: Marketplace provider ID
 
-- `ownerId` (string) [✗]: The owner's user ID
+- `userId` (string) [✗]: Connection owner user ID
 
-- `libraryId` (string) [✗]: The library containing this metamodel
+- `status` (string) [✗]: Overall rotation operation status
 
-- `constituentModels` (array) [✗]: Enriched metadata for constituent models (includes storage items)
+- `rotationType` (string) [✗]: Type of rotation that was performed
 
-- `webhookUrl` (string) [✗]: Optional webhook URL for async completion notification
+- `reason` (string) [✗]: Original reason for rotation
 
+- `newCredentials` (object) [✗]: Metadata about new credentials
 
+- `oldCredentials` (object) [✗]: Status of previous credentials
 
-### model-discovery-folder-processed-event
+- `operationDetails` (object) [✗]: Details of the rotation operation
 
-**Description:** Handles model discovery folder processed events.
+- `connectionStatus` (object) [✗]: Connection status after credential rotation
 
-**Method:** `client.modelDiscoveryFolderProcessedEvent(data)`
+- `nextRotation` (object) [✗]: Information about next scheduled rotation
 
-**Payload Type:** `ModelDiscoveryFolderProcessedEventMessage`
+- `error` (object) [✗]: Error details if rotation failed
 
-**Fields:**
+- `notifications` (array) [✗]: Notifications sent as part of rotation
 
-- `connectionId` (string) [✗]: The unique identifier for the connection.
 
-- `folderPath` (string) [✗]: The path to the processed folder.
 
-- `discoveredFiles` (array) [✗]: A list of files discovered in the folder.
+### marketplace-credential-rotation-request
 
-- `folderSignature` (object) [✗]: A signature representing the state of the folder.
+**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
 
-- `processedAt` (string) [✗]: The timestamp when the folder was processed.
 
-- `statistics` (object) [✗]: Statistics about the processed folder.
+**Method:** `client.marketplaceCredentialRotationRequest(data)`
 
+**Payload Type:** `MarketplaceCredentialRotationRequestMessage`
 
+**Fields:**
 
-### model-discovery-scan-found-event
+- `connectionId` (string) [✗]: Marketplace connection ID requiring credential rotation
 
-**Description:** Handles model discovery scan found events.
+- `marketplaceId` (string) [✗]: Marketplace provider ID (etsy, ebay, etc.)
 
-**Method:** `client.modelDiscoveryScanFoundEvent(data)`
+- `userId` (string) [✗]: User who owns the connection
 
-**Payload Type:** `ModelDiscoveryScanFoundEventMessage`
+- `rotationType` (string) [✗]: Type of credential rotation to perform
 
-**Fields:**
+- `reason` (string) [✗]: Reason for credential rotation
 
-- `modelId` (string) [✗]: The unique identifier for the model.
+- `urgency` (string) [✗]: How urgently the rotation is needed
 
-- `name` (string) [✗]: The name of the model.
+- `currentCredentials` (object) [✗]: Current credential metadata (no actual secrets)
 
-- `fileName` (string) [✗]: The name of the model file.
+- `options` (object) [✗]: Rotation configuration options
 
-- `description` (string) [✗]: A description of the model.
+- `requestId` (string) [✗]: Unique request identifier
 
-- `fileTypes` (array) [✗]: An array of file types associated with the model.
+- `webhookUrl` (string) [✗]: Webhook URL for completion notification
 
-- `size` (number) [✗]: The size of the model file in bytes.
+- `scheduledAt` (string) [✗]: When this rotation was scheduled (if scheduled)
 
-- `storageLocation` (object) [✗]: The storage location of the model.
+- `metadata` (object) [✗]: Additional request context
 
-- `providerType` (string) [✗]: The type of the storage provider.
 
-- `metadata` (object) [✗]: A flexible object for additional metadata.
 
+### marketplace-intelligence-completed
 
+**Description:** Response from marketplace intelligence scraping.
+Contains aggregated similarity data from marketplace searches.
 
-### model-discovery-scan-progress-event
+Consumed by worker-backend to update pipeline context before
+sellability analysis runs.
 
-**Description:** Handles model discovery scan progress events.
 
-**Method:** `client.modelDiscoveryScanProgressEvent(data)`
+**Method:** `client.marketplaceIntelligenceCompleted(data)`
 
-**Payload Type:** `ModelDiscoveryScanProgressEventMessage`
+**Payload Type:** `MarketplaceIntelligenceCompletedMessage`
 
 **Fields:**
 
-- `payload` (object) [✗]: Contains the discovery scan progress details.
+- `modelId` (string) [✓]: UUID of the model that was researched
 
+- `ownerId` (string) [✓]: UUID of the model owner
 
+- `status` (string) [✓]: Result status
 
-### model-discovery-scan-request
+- `marketData` (object) [✗]: Aggregated market intelligence across all scraped marketplaces
 
-**Description:** Handles model discovery scan requests events.
+- `marketplaceBreakdown` (array) [✗]: Results per marketplace
 
-**Method:** `client.modelDiscoveryScanRequest(data)`
+- `similarityScore` (number) [✗]: How saturated the market is for this model type (0=unique, 100=very common)
 
-**Payload Type:** `ModelDiscoveryScanRequestMessage`
+- `error` (object) [✗]: Error information if status is FAILED
 
-**Fields:**
+- `analyzedAt` (string) [✗]: When the analysis completed
 
-- `libraryId` (string) [✗]: The ID of the library to scan.
+- `analysisVersion` (string) [✗]: Version of the intelligence collector
 
-- `storageConnectionId` (string) [✗]: The ID of the storage connection to scan.
 
-- `providerType` (string) [✗]: The type of the storage provider.
 
-- `path` (string) [✗]: The specific path within the storage connection to scan for this library.
+### marketplace-intelligence-event
 
+**Description:** Public marketplace intelligence data scraped from external marketplaces.
 
+This event contains:
+- Listing details (title, price, images)
+- Engagement metrics (views, favorites, reviews)
+- Shop information
+- Market positioning data
 
-### model-metadata-generation-completed
+Unlike marketplace-listing-sync-request (private user data), this focuses on:
+- Broad market trends and pricing analysis
+- Competitive intelligence and demand signals
+- Product popularity and sentiment
 
-**Description:** Handles model metadata generation completed.
+Consumed by worker-analytic-collector for Elasticsearch indexing.
+Used for market research, pricing optimization, and trend detection.
 
-**Method:** `client.modelMetadataGenerationCompleted(data)`
 
-**Payload Type:** `ModelMetadataGenerationCompletedMessage`
+**Method:** `client.marketplaceIntelligenceEvent(data)`
 
-**Fields:**
+**Payload Type:** `MarketplaceIntelligenceEventMessage`
 
-- `modelId` (string) [✓]: The unique identifier for the model.
+**Fields:**
 
-- `metadata` (object) [✓]: The enriched metadata for the model.
+- `marketplace` (string) [✓]: Source marketplace
 
+- `externalId` (string) [✓]: Marketplace-native listing ID
 
+- `listing` (object) [✓]: Core listing information
 
-### model-metadata-generation-request
+- `metrics` (object) [✗]: Public engagement and sales metrics
 
-**Description:** Handles model metadata generation requests.
+- `metadata` (object) [✗]: Additional listing context and categorization
 
-**Method:** `client.modelMetadataGenerationRequest(data)`
+- `queryContext` (object) [✗]: Search context that found this listing
 
-**Payload Type:** `ModelMetadataGenerationRequestMessage`
+- `collectedAt` (string) [✓]: ISO 8601 timestamp when data was scraped
 
-**Fields:**
+- `collectorVersion` (string) [✗]: Version of collector that scraped this data
 
-- `modelId` (string) [✗]: The unique identifier for the model.
+- `scrapingMethod` (string) [✗]: Method used for scraping
 
-- `storageConnectionId` (string) [✗]: The ID of the storage connection.
 
-- `filePath` (string) [✗]: The path to the model file.
 
-- `fileName` (string) [✗]: The name of the model file.
+### marketplace-intelligence-request
 
-- `fileSize` (number) [✗]: The size of the model file in bytes.
+**Description:** Triggers automated marketplace scraping to find similar/competing listings
+for a given model. This is a pipeline stage that runs after metadata generation
+to inform sellability analysis with real market data.
 
-- `fileLastModified` (string) [✗]: The last modified date of the model file.
+The worker-analytic-collector (or marketplace-connectors worker) will:
+1. Use model metadata (title, tags, category) to build search queries
+2. Scrape connected marketplaces (Etsy, eBay, etc.) for similar listings
+3. Emit marketplace-intelligence-event results for Elasticsearch indexing
+4. Return aggregated similarity data to the pipeline context
 
-- `storageProviderType` (string) [✗]: The type of the storage provider.
+Pipeline integration:
+- Triggered after: metadata-generation (needs model title/tags/category)
+- Results feed into: sellability-analysis (market positioning data)
 
-- `modelThumbnailUrl` (string) [✗]: The URL of the model thumbnail.
 
-- `metamodel` (object) [✗]: The metamodel of the model.
+**Method:** `client.marketplaceIntelligenceRequest(data)`
 
+**Payload Type:** `MarketplaceIntelligenceRequestMessage`
 
+**Fields:**
 
-### model-metamodel-detection-found
+- `modelId` (string) [✓]: UUID of the model to research
 
-**Description:** Handles model metamodel detection found with hierarchical relationships.
+- `ownerId` (string) [✓]: UUID of the model owner
 
-**Method:** `client.modelMetamodelDetectionFound(data)`
+- `searchContext` (object) [✗]: Model metadata used to build marketplace search queries
 
-**Payload Type:** `ModelMetamodelDetectionFoundMessage`
+- `scrapingOptions` (object) [✗]: Configuration for the marketplace scraping
 
-**Fields:**
+- `pipelineId` (string) [✗]: Pipeline execution ID for correlation
 
-- `metamodels` (array) [✓]: List of metamodel nodes in hierarchical structure (roots and children).
+- `executionId` (string) [✗]: Pipeline execution UUID for correlation
 
 
 
-### model-metamodel-detection-request
+### marketplace-listing-description-generation-completed
 
-**Description:** Handles model metamodel detection requests.
+**Description:** Notifies backend that marketplace description generation completed. Contains generated description with metadata tracking (AI model, confidence, generation timestamp) and suggested price.
 
-**Method:** `client.modelMetamodelDetectionRequest(data)`
+**Method:** `client.marketplaceListingDescriptionGenerationCompleted(data)`
 
-**Payload Type:** `ModelMetamodelDetectionRequestMessage`
+**Payload Type:** `MarketplaceListingDescriptionGenerationCompletedMessage`
 
 **Fields:**
 
-- `connectionId` (string) [✓]: The unique identifier for the storage connection.
+- `modelId` (string) [✓]: UUID of the model that was processed
 
-- `folderPath` (string) [✓]: The path to the folder that was processed.
+- `entityType` (string) [✓]: Type of entity processed
 
-- `discoveredFiles` (array) [✓]: A list of files discovered in the folder.
+- `targetMarketplace` (string) [✗]: Target marketplace ID (e.g., 'etsy', 'ebay')
 
-- `folderSignature` (object) [✓]: A signature representing the state of the folder.
+- `description` (string) [✓]: SEO-optimized marketplace description (3-5 sentences)
 
-- `processedAt` (string) [✓]: The timestamp when the folder was processed.
+- `metadata` (object) [✓]: Content generation metadata for tracking
 
-- `statistics` (object) [✓]: Statistics about the processed folder.
+- `suggestedPrice` (object) [✗]: Volume-based price calculation for 3D printed item
 
+- `error` (string) [✗]: Error message if generation failed
 
 
-### model-sellability-analysis-completed
 
-**Description:** Contains sellability analysis results including Etsy-specific recommendations, material pricing, and marketplace compatibility scores
+### marketplace-listing-description-generation-request
 
-**Method:** `client.modelSellabilityAnalysisCompleted(data)`
+**Description:** Generates SEO-optimized marketplace description for a 3D model using LLM vision analysis. Worker receives model data, technical metadata, and thumbnail URLs to generate compelling product descriptions tailored to the target marketplace.
 
-**Payload Type:** `ModelSellabilityAnalysisCompletedMessage`
+**Method:** `client.marketplaceListingDescriptionGenerationRequest(data)`
+
+**Payload Type:** `MarketplaceListingDescriptionGenerationRequestMessage`
 
 **Fields:**
 
-- `metamodelId` (string) [✗]: Metamodel UUID
+- `modelId` (string) [✓]: UUID of the model (reference only)
 
-- `ownerId` (string) [✗]: Owner user ID
+- `entityType` (string) [✓]: Type of entity being processed
 
-- `sellabilityScore` (number) [✗]: Overall sellability score (0-100)
+- `entityName` (string) [✓]: Name/title of the model or metamodel
 
-- `pricingRecommendations` (object) [✗]: Pricing analysis and recommendations with material-specific pricing (v2.0.0)
+- `targetMarketplace` (string) [✓]: Target marketplace ID (e.g., 'etsy', 'ebay', 'thingiverse')
 
-- `marketplaceRecommendations` (array) [✗]: Recommended marketplaces with Etsy-specific scoring (v2.0.0)
+- `userId` (string) [✓]: UUID of the user requesting generation
 
-- `demandAnalysis` (object) [✗]: Market demand insights
+- `webhookUrl` (string) [✗]: Callback URL for completion notification
 
-- `qualityFactors` (object) [✗]: Quality-related factors affecting sellability
+- `technicalMetadata` (object) [✗]: Technical analysis data for context
 
-- `recommendations` (array) [✗]: Actionable recommendations to improve sellability
+- `thumbnailUrls` (array) [✗]: URLs to 360-degree thumbnail views
 
-- `analyzedAt` (string) [✗]: Analysis completion timestamp (ISO 8601)
+- `existingTags` (array) [✗]: Currently assigned tags for context
 
-- `analysisVersion` (string) [✗]: Analysis algorithm version
+- `existingCategory` (string) [✗]: Current classification for context
 
-- `error` (object) [✗]: Error information if analysis failed
+- `brandVoice` (string) [✗]: Desired tone/voice for the listing (e.g., 'professional', 'playful')
 
+- `targetMarket` (string) [✗]: Target geographic market (e.g., 'US', 'EU')
 
+- `keywords` (array) [✗]: Specific keywords to include
 
-### 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)`
+### marketplace-listing-sync-completed
 
-**Payload Type:** `ModelSellabilityAnalysisRequestMessage`
+**Description:** Notification that marketplace listing sync operation has completed. Contains detailed results of the sync including created/updated listings, errors encountered, and performance statistics.
 
-**Fields:**
 
-- `metamodelId` (string) [✗]: UUID of the metamodel to analyze. Worker will fetch all model metadata, technical metadata, enriched metadata, and child models from PostgreSQL.
+**Method:** `client.marketplaceListingSyncCompleted(data)`
 
-- `ownerId` (string) [✗]: UUID of the user who owns the metamodel
+**Payload Type:** `MarketplaceListingSyncCompletedMessage`
 
-- `analysisOptions` (object) [✗]: Optional analysis configuration
+**Fields:**
 
+- `requestId` (string) [✗]: Original request ID for correlation
 
+- `connectionId` (string) [✗]: Marketplace connection that was synced
 
-### model-technical-metadata-completed
+- `marketplaceId` (string) [✗]: Marketplace provider ID
 
-**Description:** Reports comprehensive results of technical metadata analysis including geometry, quality metrics, and print-readiness assessment
+- `userId` (string) [✗]: Connection owner user ID
 
-**Method:** `client.modelTechnicalMetadataCompleted(data)`
+- `status` (string) [✗]: Overall sync operation status
 
-**Payload Type:** `ModelTechnicalMetadataCompletedMessage`
+- `syncDirection` (string) [✗]: Direction of sync that was performed
 
-**Fields:**
+- `statistics` (object) [✗]: Detailed sync operation statistics
 
-- `originalJobId` (string) [✗]: ID of the original analysis request job
+- `results` (object) [✗]: Detailed sync results by operation
 
-- `modelId` (string) [✗]: ID of the analyzed model
+- `successfulListings` (array) [✗]: Details of successfully processed listings
 
-- `status` (string) [✗]: Analysis completion status
+- `failedListings` (array) [✗]: Details of listings that failed to sync
 
-- `vertices` (integer) [✗]: Number of vertices in the mesh
+- `errors` (array) [✗]: Non-listing-specific errors encountered
 
-- `faces` (integer) [✗]: Number of faces/polygons in the mesh
+- `completedAt` (string) [✗]: When sync operation completed
 
-- `edges` (integer) [✗]: Number of edges in the mesh
+- `nextSyncRecommendedAt` (string) [✗]: When next sync is recommended
 
-- `detailLevel` (string) [✗]: Visual detail level based on polygon density
 
-- `boundingBox` (object) [✗]: 3D bounding box dimensions in millimeters
 
-- `volumeCubicMm` (number) [✗]: Model volume in cubic millimeters (for material calculation)
+### marketplace-listing-sync-request
 
-- `surfaceAreaSqMm` (number) [✗]: Total surface area in square millimeters
+**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
 
-- `minWallThickness` (number) [✗]: Minimum wall thickness detected in millimeters (critical for printability)
 
-- `maxWallThickness` (number) [✗]: Maximum wall thickness detected in millimeters
+**Method:** `client.marketplaceListingSyncRequest(data)`
 
-- `manifold` (boolean) [✗]: Is the mesh watertight/manifold? Critical for 3D printing (true = printable)
+**Payload Type:** `MarketplaceListingSyncRequestMessage`
 
-- `nonManifoldEdges` (integer) [✗]: Number of non-manifold edges (repair needed if > 0)
+**Fields:**
 
-- `holes` (integer) [✗]: Number of holes/boundary loops in the mesh (0 = closed mesh)
+- `connectionId` (string) [✗]: Marketplace connection ID
 
-- `flippedNormals` (integer) [✗]: Number of faces with inverted normals (causes rendering/slicing issues)
+- `marketplaceId` (string) [✗]: Marketplace provider ID (etsy, ebay, etc.)
 
-- `selfIntersections` (integer) [✗]: Number of self-intersecting faces (0 = clean geometry)
+- `userId` (string) [✗]: User who owns the connection
 
-- `qualityScore` (number) [✗]: Overall quality score 0-100 (100 = perfect for printing, <60 needs repair)
+- `syncDirection` (string) [✗]: Direction of sync operation
 
-- `printabilityScore` (number) [✗]: Printability score 0-100 (considers supports, orientation, size constraints)
+- `syncScope` (string) [✗]: Scope of listings to sync
 
-- `requiresSupports` (boolean) [✗]: Does this model require support structures for 3D printing?
+- `listingIds` (array) [✗]: Specific listing IDs to sync (if syncScope=specific)
 
-- `overhangs` (array) [✗]: Detected overhang areas requiring support structures
+- `externalListingIds` (array) [✗]: External marketplace listing IDs to sync
 
-- `estimatedPrintTimeMinutes` (integer) [✗]: Estimated print time in minutes using normal quality settings (0.2mm layers, 20% infill)
+- `options` (object) [✗]: Sync configuration options
 
-- `printTimeEstimates` (object) [✗]: Print time estimates for different quality presets
+- `priority` (string) [✗]: Processing priority
 
-- `estimatedMaterialGrams` (number) [✗]: Estimated material usage in grams using 20% infill (assumes PLA density 1.24g/cm³)
+- `requestId` (string) [✗]: Unique request identifier
 
-- `materialEstimates` (object) [✗]: Material usage estimates for different infill percentages
+- `webhookUrl` (string) [✗]: Webhook URL for completion notification
 
-- `recommendedOrientation` (object) [✗]: Recommended print orientation for minimal support material and best results
+- `metadata` (object) [✗]: Additional request context
 
-- `originalUnit` (string) [✗]: Original file format unit detected from metadata or inferred from scale
 
-- `formatVersion` (string) [✗]: File format version (e.g., 'STL Binary', 'OBJ v4', 'PLY 1.0')
 
-- `hasColorData` (boolean) [✗]: Does the file contain per-vertex color information?
+### marketplace-listing-tags-generation-completed
 
-- `hasTextureCoordinates` (boolean) [✗]: Does the file contain UV texture mapping coordinates?
+**Description:** Notifies backend that marketplace tags generation completed. Contains generated tags optimized for discoverability with metadata tracking.
 
-- `hasVertexNormals` (boolean) [✗]: Does the file contain per-vertex normal vectors?
+**Method:** `client.marketplaceListingTagsGenerationCompleted(data)`
 
-- `analyzedBy` (string) [✗]: Tool/service that performed the analysis
+**Payload Type:** `MarketplaceListingTagsGenerationCompletedMessage`
 
-- `analysisVersion` (string) [✗]: Version of the analysis algorithm (for tracking improvements)
+**Fields:**
 
-- `analysisConfidence` (number) [✗]: Confidence level of analysis results (0.0 = uncertain, 1.0 = highly confident)
+- `modelId` (string) [✓]: UUID of the model that was processed
 
-- `analysisWarnings` (array) [✗]: Warnings or issues detected during analysis (structured for programmatic handling)
+- `entityType` (string) [✓]: Type of entity processed
 
-- `analyzedAt` (string) [✗]: ISO 8601 timestamp when analysis was performed (e.g., '2025-11-19T14:35:22Z')
+- `tags` (array) [✓]: Generated searchability tags (style, technical, usage keywords)
 
-- `errorMessage` (string) [✗]: Detailed error message if status is FAILED
+- `metadata` (object) [✓]: Content generation metadata for tracking
 
-- `errorCode` (string) [✗]: Machine-readable error code for programmatic error handling
+- `error` (string) [✗]: Error message if generation failed
 
 
 
-### model-technical-metadata-request
+### marketplace-listing-tags-generation-request
 
-**Description:** Triggers comprehensive technical analysis of a 3D model file to extract geometry, quality metrics, and print-readiness information
+**Description:** Generates searchability tags for a 3D model optimized for marketplace discoverability. Worker creates style, technical, and usage keywords following marketplace tag limits and SEO best practices.
 
-**Method:** `client.modelTechnicalMetadataRequest(data)`
+**Method:** `client.marketplaceListingTagsGenerationRequest(data)`
+
+**Payload Type:** `MarketplaceListingTagsGenerationRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✓]: UUID of the model (reference only)
+
+- `entityType` (string) [✓]: Type of entity being processed
+
+- `entityName` (string) [✓]: Name/title of the model or metamodel
+
+- `targetMarketplace` (string) [✓]: Target marketplace ID (e.g., 'etsy', 'ebay', 'thingiverse')
+
+- `userId` (string) [✓]: UUID of the user requesting generation
+
+- `webhookUrl` (string) [✗]: Callback URL for completion notification
+
+- `technicalMetadata` (object) [✗]: Technical analysis data for tag generation
+
+- `thumbnailUrls` (array) [✗]: URLs to 360-degree thumbnail views for visual analysis
+
+- `existingTags` (array) [✗]: Currently assigned tags to supplement or replace
+
+- `existingCategory` (string) [✗]: Current classification for category-based tags
+
+- `tagLimit` (number) [✗]: Maximum number of tags for marketplace (e.g., 13 for Etsy)
+
+- `targetMarket` (string) [✗]: Target geographic market (e.g., 'US', 'EU')
+
+- `style` (string) [✗]: Artistic style of the model (e.g., 'realistic', 'low-poly')
+
+- `useCases` (array) [✗]: Intended uses for the model
+
+
+
+### marketplace-listing-title-generation-completed
+
+**Description:** Notifies backend that marketplace title generation completed. Contains generated title with metadata tracking.
+
+**Method:** `client.marketplaceListingTitleGenerationCompleted(data)`
+
+**Payload Type:** `MarketplaceListingTitleGenerationCompletedMessage`
+
+**Fields:**
+
+- `modelId` (string) [✓]: UUID of the model that was processed
+
+- `entityType` (string) [✓]: Type of entity processed
+
+- `title` (string) [✓]: Marketplace-optimized title
+
+- `metadata` (object) [✓]: Content generation metadata for tracking
+
+- `error` (string) [✗]: Error message if generation failed
+
+
+
+### marketplace-listing-title-generation-request
+
+**Description:** Generates marketplace-optimized title for a 3D model. Worker creates concise, SEO-friendly titles following marketplace character limits and best practices.
+
+**Method:** `client.marketplaceListingTitleGenerationRequest(data)`
+
+**Payload Type:** `MarketplaceListingTitleGenerationRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✓]: UUID of the model (reference only)
+
+- `entityType` (string) [✓]: Type of entity being processed
+
+- `currentName` (string) [✓]: Current model/metamodel name
+
+- `targetMarketplace` (string) [✓]: Target marketplace ID (e.g., 'etsy', 'ebay', 'thingiverse')
+
+- `userId` (string) [✓]: UUID of the user requesting generation
+
+- `webhookUrl` (string) [✗]: Callback URL for completion notification
+
+- `technicalMetadata` (object) [✗]: Technical analysis data for context
+
+- `existingTags` (array) [✗]: Currently assigned tags for SEO keywords
+
+- `existingCategory` (string) [✗]: Current classification for categorization
+
+- `characterLimit` (number) [✗]: Maximum character count for marketplace (e.g., 140 for Etsy)
+
+- `brandVoice` (string) [✗]: Desired tone/voice for the listing (e.g., 'professional', 'playful')
+
+- `targetMarket` (string) [✗]: Target geographic market (e.g., 'US', 'EU')
+
+- `keywords` (array) [✗]: Specific keywords to include
+
+
+
+### marketplace-listing-update-completed
+
+**Description:** Result of a listing update operation
+
+**Method:** `client.marketplaceListingUpdateCompleted(data)`
+
+**Payload Type:** `MarketplaceListingUpdateCompletedMessage`
+
+**Fields:**
+
+- `marketplace` (string) [✗]: Target marketplace
+
+- `listingId` (string) [✗]: External ID of the listing
+
+- `status` (string) [✗]: Status of the update (success, failed)
+
+- `result` (object) [✗]: Result details from the marketplace API
+
+- `error` (string) [✗]: Error message if failed
+
+
+
+### marketplace-listing-update-request
+
+**Description:** Request to update an existing listing on a marketplace (price, quantity, etc.)
+
+**Method:** `client.marketplaceListingUpdateRequest(data)`
+
+**Payload Type:** `MarketplaceListingUpdateRequestMessage`
+
+**Fields:**
+
+- `marketplace` (string) [✗]: Target marketplace (etsy, ebay, etc.)
+
+- `listingId` (string) [✗]: External ID of the listing to update
+
+- `updates` (object) [✗]: Fields to update
+
+- `credentials` (object) [✗]: User credentials for the marketplace
+
+
+
+### media-batch-download-completed
+
+**Description:** Notifies that a batch media download has been completed.
+
+**Method:** `client.mediaBatchDownloadCompleted(data)`
+
+**Payload Type:** `MediaBatchDownloadCompletedMessage`
+
+**Fields:**
+
+- `batchId` (string) [✓]: The unique identifier for the batch download operation.
+
+- `status` (string) [✓]: The final status of the batch download operation.
+
+- `processedFiles` (array) [✗]: List of successfully processed files.
+
+- `failedFiles` (array) [✗]: List of files that failed to process.
+
+- `processedAt` (string) [✓]: Timestamp when the batch processing completed.
+
+- `statistics` (object) [✗]: Statistics about the batch processing.
+
+
+
+### media-batch-download-request
+
+**Description:** Request to download and process a batch of media files from a storage provider. Images are compressed and resized to specified dimensions, converted to WebP format. Text files and documents are processed and stored with metadata. All processed files are uploaded to MinIO S3 storage under the media/{batchId}/ prefix.
+
+
+**Method:** `client.mediaBatchDownloadRequest(data)`
+
+**Payload Type:** `MediaBatchDownloadRequestMessage`
+
+**Fields:**
+
+- `batchId` (string) [✗]: Unique identifier for this batch of media files. Used for organizing processed files in S3 storage (media/{batchId}/) and correlating with completion responses.
+
+
+- `downloadStrategy` (string) [✗]: Download strategy for media files: - storage_provider: Download from authenticated storage connection (Google Drive, SFTP, etc.) - external_url: Download from public HTTP URLs (CDN, API responses, Thingiverse, etc.)
+
+
+- `entityType` (string) [✗]: Type of entity these media files belong to. Used for linking downloaded media to the correct entity in the database.
+
+
+- `entityId` (string) [✗]: UUID of the model or metamodel entity that owns these media files. Used for creating storage item associations after download.
+
+
+- `storageConnectionId` (string) [✗]: UUID of the StorageConnection entity from which to download the media files. Required when downloadStrategy is 'storage_provider'. Used to authenticate and access the source storage provider.
+
+
+- `credentials` (object) [✗]: Decrypted credentials for the storage provider (Fat Payload pattern). Required when downloadStrategy is 'storage_provider'.
+
+
+- `mediaFiles` (array) [✗]: Array of media files to download and process. Must contain at least one file. Each file includes metadata for identification and processing.
+
+
+- `compressionSettings` (object) [✗]: Optional compression settings that override deployment environment defaults. If not provided, uses values from MAX_IMAGE_WIDTH, MAX_IMAGE_HEIGHT, IMAGE_QUALITY, and OUTPUT_FORMAT environment variables.
+
+
+
+
+### metamodel-metadata-generation-completed
+
+**Description:** Handles metamodel metadata generation completion. Contains AI-generated metadata and aggregated technical analysis.
+
+**Method:** `client.metamodelMetadataGenerationCompleted(data)`
+
+**Payload Type:** `MetamodelMetadataGenerationCompletedMessage`
+
+**Fields:**
+
+- `metamodelId` (string) [✓]: The unique identifier for the metamodel
+
+- `metadata` (object) [✓]: AI-generated metadata for the metamodel
+
+- `technicalMetadata` (object) [✓]: Aggregated technical analysis from constituent models
+
+
+
+### metamodel-metadata-generation-request
+
+**Description:** Handles metamodel metadata generation requests via Ollama. Aggregates data from constituent models and generates AI-enhanced metadata.
+
+**Method:** `client.metamodelMetadataGenerationRequest(data)`
+
+**Payload Type:** `MetamodelMetadataGenerationRequestMessage`
+
+**Fields:**
+
+- `metamodelId` (string) [✗]: The unique identifier for the metamodel
+
+- `constituentModelIds` (array) [✗]: Array of model IDs that compose this metamodel
+
+- `name` (string) [✗]: The name of the metamodel
+
+- `ownerId` (string) [✗]: The owner's user ID
+
+- `libraryId` (string) [✗]: The library containing this metamodel
+
+- `constituentModels` (array) [✗]: Enriched metadata for constituent models (includes storage items)
+
+- `webhookUrl` (string) [✗]: Optional webhook URL for async completion notification
+
+
+
+### 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.
+
+**Method:** `client.modelDiscoveryFolderProcessedEvent(data)`
+
+**Payload Type:** `ModelDiscoveryFolderProcessedEventMessage`
+
+**Fields:**
+
+- `connectionId` (string) [✗]: The unique identifier for the connection.
+
+- `folderPath` (string) [✗]: The path to the processed folder.
+
+- `discoveredFiles` (array) [✗]: A list of files discovered in the folder.
+
+- `folderSignature` (object) [✗]: A signature representing the state of the folder.
+
+- `processedAt` (string) [✗]: The timestamp when the folder was processed.
+
+- `statistics` (object) [✗]: Statistics about the processed folder.
+
+
+
+### model-discovery-scan-found-event
+
+**Description:** Handles model discovery scan found events.
+
+**Method:** `client.modelDiscoveryScanFoundEvent(data)`
+
+**Payload Type:** `ModelDiscoveryScanFoundEventMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: The unique identifier for the model.
+
+- `name` (string) [✗]: The name of the model.
+
+- `fileName` (string) [✗]: The name of the model file.
+
+- `description` (string) [✗]: A description of the model.
+
+- `fileTypes` (array) [✗]: An array of file types associated with the model.
+
+- `size` (number) [✗]: The size of the model file in bytes.
+
+- `storageLocation` (object) [✗]: The storage location of the model.
+
+- `providerType` (string) [✗]: The type of the storage provider.
+
+- `metadata` (object) [✗]: A flexible object for additional metadata.
+
+
+
+### model-discovery-scan-progress-event
+
+**Description:** Handles model discovery scan progress events.
+
+**Method:** `client.modelDiscoveryScanProgressEvent(data)`
+
+**Payload Type:** `ModelDiscoveryScanProgressEventMessage`
+
+**Fields:**
+
+- `payload` (object) [✗]: Contains the discovery scan progress details.
+
+
+
+### model-discovery-scan-request
+
+**Description:** Handles model discovery scan requests events.
+
+**Method:** `client.modelDiscoveryScanRequest(data)`
+
+**Payload Type:** `ModelDiscoveryScanRequestMessage`
+
+**Fields:**
+
+- `libraryId` (string) [✗]: The ID of the library to scan.
+
+- `storageConnectionId` (string) [✗]: The ID of the storage connection to scan.
+
+- `providerType` (string) [✗]: The type of the storage provider.
+
+- `path` (string) [✗]: The specific path within the storage connection to scan for this library.
+
+- `credentials` (object) [✗]: Decrypted credentials for the storage provider.
+
+- `configuration` (object) [✗]: Configuration for the storage connection (e.g. scanRootPath).
+
+
+
+### model-finder-index-request
+
+**Description:** DEPRECATED (2026-02-18) — FR-023 retired. Merge 3D rendering into worker-file-vectorize.
+
+**Method:** `client.modelFinderIndexRequest(data)`
+
+**Payload Type:** `ModelFinderIndexRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: 
+
+- `storageItem` () [✗]: 
+
+
+
+### model-finder-response
+
+**Description:** DEPRECATED (2026-02-18) — FR-023 retired. Merge 3D rendering into worker-file-vectorize.
+
+**Method:** `client.modelFinderResponse(data)`
+
+**Payload Type:** `ModelFinderResponseMessage`
+
+**Fields:**
+
+- `requestId` (string) [✗]: 
+
+- `results` (array) [✗]: 
+
+
+
+### model-finder-search-request
+
+**Description:** DEPRECATED (2026-02-18) — FR-023 retired. Merge 3D rendering into worker-file-vectorize.
+
+**Method:** `client.modelFinderSearchRequest(data)`
+
+**Payload Type:** `ModelFinderSearchRequestMessage`
+
+**Fields:**
+
+- `referenceModelId` (string) [✗]: Optional: Search using an existing model as reference
+
+- `referenceImageId` (string) [✗]: Optional: Search using an uploaded image
+
+- `limit` (integer) [✗]: 
+
+
+
+### 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)`
+
+**Payload Type:** `ModelMetadataGenerationCompletedMessage`
+
+**Fields:**
+
+- `modelId` (string) [✓]: UUID of the model that was processed.
+
+- `metadata` (object) [✓]: Enriched marketplace metadata generated by LLM.
+
+
+
+### model-metadata-generation-request
+
+**Description:** Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM vision analysis. Worker receives all necessary data in the payload (Model, TechnicalMetadata, Thumbnails) and does NOT query the database. Prerequisites: file download, technical metadata, and thumbnail generation must be complete before this message is sent.
+
+**Method:** `client.modelMetadataGenerationRequest(data)`
+
+**Payload Type:** `ModelMetadataGenerationRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: UUID of the model (reference only)
+
+- `model` (object) [✗]: Core model entity data
+
+- `technicalMetadata` (object) [✗]: Geometric and technical analysis results
+
+- `thumbnails` (array) [✗]: List of 360 degree thumbnail views (URLs or paths)
+
+
+
+### model-metamodel-detection-found
+
+**Description:** Handles model metamodel detection found with hierarchical relationships.
+
+**Method:** `client.modelMetamodelDetectionFound(data)`
+
+**Payload Type:** `ModelMetamodelDetectionFoundMessage`
+
+**Fields:**
+
+- `metamodels` (array) [✓]: List of metamodel nodes in hierarchical structure (roots and children).
+
+- `ekgEdges` (array) [✗]: EKG edges derived from Louvain clustering (OPTIONAL - new field)
+
+
+
+### model-metamodel-detection-request
+
+**Description:** Handles model metamodel detection requests.
+
+**Method:** `client.modelMetamodelDetectionRequest(data)`
+
+**Payload Type:** `ModelMetamodelDetectionRequestMessage`
+
+**Fields:**
+
+- `connectionId` (string) [✓]: The unique identifier for the storage connection.
+
+- `folderPath` (string) [✓]: The path to the folder that was processed.
+
+- `discoveredFiles` (array) [✗]: A list of files discovered in the folder. Worker should check this first, then manifestUrl.
+
+- `manifestUrl` (string) [✗]: URL to a JSON file containing the list of discovered files (for large folders)
+
+- `folderSignature` (object) [✓]: A signature representing the state of the folder.
+
+- `processedAt` (string) [✓]: The timestamp when the folder was processed.
+
+- `statistics` (object) [✓]: Statistics about the processed folder.
+
+
+
+### model-print-analysis-completed
+
+**Description:** Reports completion of 3D print analysis — contains estimation, printability, and cost breakdown per FR-022
+
+**Method:** `client.modelPrintAnalysisCompleted(data)`
+
+**Payload Type:** `ModelPrintAnalysisCompletedMessage`
+
+**Fields:**
+
+- `originalJobId` (string) [✗]: ID of the original analysis request job
+
+- `modelId` (string) [✗]: UUID of the analysed model
+
+- `status` (string) [✗]: Analysis result status
+
+- `errorMessage` (string) [✗]: Error description when status is FAILED
+
+- `material` (string) [✗]: Material type used for estimation
+
+- `quality` (string) [✗]: Quality preset used
+
+- `printTimeMinutes` (number) [✗]: Estimated total print time in minutes
+
+- `materialGrams` (number) [✗]: Estimated material consumption in grams (body only)
+
+- `needsSupport` (boolean) [✗]: Whether the model requires support structures
+
+- `supportMaterialGrams` (number) [✗]: Estimated support material in grams
+
+- `overhangPercentage` (number) [✗]: Percentage of surface area with overhangs > 45°
+
+- `minWallThicknessMm` (number) [✗]: Thinnest detected wall in millimeters
+
+- `solidVolumeCm3` (number) [✗]: Solid volume of the mesh in cm³
+
+- `surfaceAreaCm2` (number) [✗]: Total surface area in cm²
+
+- `boundingBox` (object) [✗]: Bounding box in millimeters
+
+- `estimatedCostEUR` (number) [✗]: Total estimated production cost in EUR
+
+- `costBreakdown` (object) [✗]: Granular cost breakdown per WF-009 MaterialCostCalculatorService
+
+
+
+### model-print-analysis-request
+
+**Description:** Triggers 3D print analysis for a model — estimates print time, material usage, support needs, and cost breakdown per FR-022
+
+**Method:** `client.modelPrintAnalysisRequest(data)`
+
+**Payload Type:** `ModelPrintAnalysisRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: UUID of the model to analyse
+
+- `ownerId` (string) [✗]: UUID of the user who owns the model
+
+- `material` (string) [✗]: Material type enum value (e.g. PLA, PETG, RESIN_STANDARD)
+
+- `quality` (string) [✗]: Print quality preset
+
+- `webhookUrl` (string) [✗]: URL called when analysis completes or fails
+
+- `minioPath` (string) [✗]: Path to model in MinIO storage for geometry analysis (e.g. 'raw_models/{modelId}/original.glb')
+
+
+
+### 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.
+
+- `ownerId` (string) [✗]: UUID of the user who owns the metamodel
+
+- `metamodelData` (object) [✗]: Full metamodel data including technical metadata, enriched metadata, and child models. Injected by backend to avoid DB access.
+
+- `manifestUrl` (string) [✗]: URL to a JSON manifest containing the metamodel data if it is too large for the message payload.
+
+- `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
+
+**Method:** `client.modelTechnicalMetadataCompleted(data)`
+
+**Payload Type:** `ModelTechnicalMetadataCompletedMessage`
+
+**Fields:**
+
+- `originalJobId` (string) [✗]: ID of the original analysis request job
+
+- `modelId` (string) [✗]: ID of the analyzed model
+
+- `status` (string) [✗]: Analysis completion status
+
+- `vertices` (integer) [✗]: Number of vertices in the mesh
+
+- `faces` (integer) [✗]: Number of faces/polygons in the mesh
+
+- `edges` (integer) [✗]: Number of edges in the mesh
+
+- `detailLevel` (string) [✗]: Visual detail level based on polygon density
+
+- `boundingBox` (object) [✗]: 3D bounding box dimensions in millimeters
+
+- `volumeCubicMm` (number) [✗]: Model volume in cubic millimeters (for material calculation)
+
+- `surfaceAreaSqMm` (number) [✗]: Total surface area in square millimeters
+
+- `minWallThickness` (number) [✗]: Minimum wall thickness detected in millimeters (critical for printability)
+
+- `maxWallThickness` (number) [✗]: Maximum wall thickness detected in millimeters
+
+- `manifold` (boolean) [✗]: Is the mesh watertight/manifold? Critical for 3D printing (true = printable)
+
+- `nonManifoldEdges` (integer) [✗]: Number of non-manifold edges (repair needed if > 0)
+
+- `holes` (integer) [✗]: Number of holes/boundary loops in the mesh (0 = closed mesh)
+
+- `flippedNormals` (integer) [✗]: Number of faces with inverted normals (causes rendering/slicing issues)
+
+- `selfIntersections` (integer) [✗]: Number of self-intersecting faces (0 = clean geometry)
+
+- `qualityScore` (number) [✗]: Overall quality score 0-100 (100 = perfect for printing, <60 needs repair)
+
+- `printabilityScore` (number) [✗]: Printability score 0-100 (considers supports, orientation, size constraints)
+
+- `requiresSupports` (boolean) [✗]: Does this model require support structures for 3D printing?
+
+- `overhangs` (array) [✗]: Detected overhang areas requiring support structures
+
+- `estimatedPrintTimeMinutes` (integer) [✗]: Estimated print time in minutes using normal quality settings (0.2mm layers, 20% infill)
+
+- `printTimeEstimates` (object) [✗]: Print time estimates for different quality presets
+
+- `estimatedMaterialGrams` (number) [✗]: Estimated material usage in grams using 20% infill (assumes PLA density 1.24g/cm³)
+
+- `materialEstimates` (object) [✗]: Material usage estimates for different infill percentages
+
+- `recommendedOrientation` (object) [✗]: Recommended print orientation for minimal support material and best results
+
+- `slicerRecommendations` (object) [✗]: Slicer-derived recommended print settings based on model analysis (feeds into print job creation as defaults)
+
+- `originalUnit` (string) [✗]: Original file format unit detected from metadata or inferred from scale
+
+- `formatVersion` (string) [✗]: File format version (e.g., 'STL Binary', 'OBJ v4', 'PLY 1.0')
+
+- `hasColorData` (boolean) [✗]: Does the file contain per-vertex color information?
+
+- `hasTextureCoordinates` (boolean) [✗]: Does the file contain UV texture mapping coordinates?
+
+- `hasVertexNormals` (boolean) [✗]: Does the file contain per-vertex normal vectors?
+
+- `analyzedBy` (string) [✗]: Tool/service that performed the analysis
+
+- `analysisVersion` (string) [✗]: Version of the analysis algorithm (for tracking improvements)
+
+- `analysisConfidence` (number) [✗]: Confidence level of analysis results (0.0 = uncertain, 1.0 = highly confident)
+
+- `analysisWarnings` (array) [✗]: Warnings or issues detected during analysis (structured for programmatic handling)
+
+- `analyzedAt` (string) [✗]: ISO 8601 timestamp when analysis was performed (e.g., '2025-11-19T14:35:22Z')
+
+- `errorMessage` (string) [✗]: Detailed error message if status is FAILED
+
+- `errorCode` (string) [✗]: Machine-readable error code for programmatic error handling
+
+
+
+### model-technical-metadata-request
+
+**Description:** Triggers comprehensive technical analysis of a 3D model file to extract geometry, quality metrics, and print-readiness information
+
+**Method:** `client.modelTechnicalMetadataRequest(data)`
 
 **Payload Type:** `ModelTechnicalMetadataRequestMessage`
 
 **Fields:**
 
-- `modelId` (string) [✗]: Unique identifier for the model to analyze
+- `modelId` (string) [✗]: Unique identifier for the model to analyze
+
+- `ownerId` (string) [✗]: User ID who owns the model
+
+- `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
+
+
+
+### slicing-fdm-request
+
+**Description:** Request FDM slicing simulation via OrcaSlicer (preferred) or heuristic fallback. Accepts OrcaSlicer-compatible printer/process/filament JSON profiles.
+
+**Method:** `client.slicingFdmRequest(data)`
+
+**Payload Type:** `SlicingFdmRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: UUID of the model
+
+- `storageItemId` (string) [✗]: UUID or path of the storage item to download the STL/3MF
+
+- `profileId` (string) [✗]: UUID of the user's slicer profile from the database
+
+- `profileName` (string) [✗]: Human-readable profile name (e.g. 'My Bambu X1C - PLA Fine')
+
+- `printerProfile` (object) [✗]: OrcaSlicer printer profile JSON: nozzle_diameter, bed_shape, max speeds, acceleration, retraction
+
+- `processProfile` (object) [✗]: OrcaSlicer process profile JSON: layer_height, sparse_infill_density, wall_loops, speeds, support settings
+
+- `filamentProfile` (object) [✗]: OrcaSlicer filament profile JSON: filament_type, filament_density, temperature, flow_ratio, retraction
+
+- `layerHeight` (number) [✗]: Override: layer height in mm (takes precedence over processProfile)
+
+- `infillPercentage` (number) [✗]: Override: infill percentage (0-100)
+
+- `nozzleDiameter` (number) [✗]: Override: nozzle diameter in mm
+
+- `printSpeed` (number) [✗]: Override: outer wall print speed in mm/s
+
+- `wallCount` (integer) [✗]: Override: number of wall loops / perimeters
+
+- `supportEnabled` (boolean) [✗]: Override: generate support structures
+
+- `materialDensity` (number) [✗]: Override: filament density in g/cm³ (default: 1.24 PLA)
+
+- `webhookUrl` (string) [✗]: URL to POST the slicing result back to
+
+
+
+### slicing-fdm-result
+
+**Description:** Result of FDM slicing simulation from OrcaSlicer (toolpath) or heuristic fallback. Contains exact physical metrics for cost calculation.
+
+**Method:** `client.slicingFdmResult(data)`
+
+**Payload Type:** `SlicingFdmResultMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: UUID of the model
 
-- `ownerId` (string) [✗]: User ID who owns the model
+- `status` (string) [✗]: Status of the simulation
 
-- `storageLocation` (object) [✗]: Location of the 3D model file
+- `printTimeHours` (number) [✗]: Exact print time in hours (from toolpath analysis)
 
-- `analysisOptions` (object) [✗]: Optional analysis configuration parameters
+- `materialWeightGrams` (number) [✗]: Total filament weight in grams (including supports)
+
+- `materialVolumeCm3` (number) [✗]: Extruded material volume in cm³
+
+- `maxZHeightMM` (number) [✗]: Maximum Z height in mm
+
+- `supportMaterialWeightGrams` (number) [✗]: Support structure filament weight in grams
+
+- `layerCount` (integer) [✗]: Total number of layers
+
+- `totalExtrusionLengthMm` (number) [✗]: Total filament extrusion length in mm
+
+- `slicingMethod` (string) [✗]: Engine that produced the result
+
+- `slicerVersion` (string) [✗]: Version of the slicer engine used
+
+- `profileUsed` (string) [✗]: Name or ID of the slicer profile used
+
+- `errorCode` (string) [✗]: Error code if simulation failed
+
+- `errorMessage` (string) [✗]: Error message if simulation failed
+
+
+
+### slicing-sla-request
+
+**Description:** Request SLA/MSLA slicing simulation via PySLM cross-sectional analysis. Accepts resin printer profile with exposure, lift, and layer parameters.
+
+**Method:** `client.slicingSlaRequest(data)`
+
+**Payload Type:** `SlicingSlaRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: UUID of the model
+
+- `storageItemId` (string) [✗]: UUID or path of the storage item to download the STL/3MF
+
+- `technology` (string) [✗]: SLA or MSLA
+
+- `profileId` (string) [✗]: UUID of the user's slicer profile from the database
+
+- `profileName` (string) [✗]: Human-readable profile name (e.g. 'Elegoo Mars 3 - Standard Grey')
+
+- `layerHeight` (number) [✗]: Layer height in mm (default: 0.05)
+
+- `exposureTime` (number) [✗]: Normal layer UV exposure time in seconds (default: 2.5)
+
+- `bottomExposureTime` (number) [✗]: Bottom/burn-in layer exposure time in seconds (default: 30)
+
+- `bottomLayers` (integer) [✗]: Number of bottom/burn-in layers (default: 5)
+
+- `liftHeight` (number) [✗]: Platform lift height in mm between layers (default: 5.0)
+
+- `liftSpeed` (number) [✗]: Platform lift speed in mm/min (default: 60)
+
+- `retractSpeed` (number) [✗]: Platform retract speed in mm/min (default: 150)
+
+- `resinDensity` (number) [✗]: Resin density in g/cm³ (default: 1.1)
+
+- `supportEnabled` (boolean) [✗]: Generate support structures (default: true for SLA)
+
+- `webhookUrl` (string) [✗]: URL to POST the slicing result back to
+
+
+
+### slicing-sla-result
+
+**Description:** Result of SLA/MSLA slicing simulation from PySLM cross-sectional analysis. Contains exact resin usage and print time metrics.
+
+**Method:** `client.slicingSlaResult(data)`
+
+**Payload Type:** `SlicingSlaResultMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: UUID of the model
+
+- `status` (string) [✗]: Status of the simulation
+
+- `printTimeHours` (number) [✗]: Exact print time in hours (from cross-sectional analysis)
+
+- `materialWeightGrams` (number) [✗]: Total resin weight in grams (including supports)
+
+- `materialVolumeCm3` (number) [✗]: Cured resin volume in cm³ (from cross-sectional area integration)
+
+- `maxZHeightMM` (number) [✗]: Maximum Z height in mm
+
+- `supportMaterialWeightGrams` (number) [✗]: Support structure resin weight in grams
+
+- `layerCount` (integer) [✗]: Total number of layers
+
+- `maxCrossSectionAreaMm2` (number) [✗]: Maximum cross-sectional area in mm² (affects MSLA peel force)
+
+- `slicingMethod` (string) [✗]: Engine that produced the result
+
+- `slicerVersion` (string) [✗]: Version of PySLM / trimesh used
+
+- `profileUsed` (string) [✗]: Name or ID of the slicer profile used
+
+- `errorCode` (string) [✗]: Error code if simulation failed
+
+- `errorMessage` (string) [✗]: Error message if simulation failed
+
+
+
+### texture-generation-completed
+
+**Description:** Emitted when AI texture generation completes (success or failure). Contains artifact S3 URLs on success, or error details on failure. The credit reservation should be confirmed (success) or released (failure) based on the status.
+
+**Method:** `client.textureGenerationCompleted(data)`
+
+**Payload Type:** `TextureGenerationCompletedMessage`
+
+**Fields:**
+
+- `jobId` (string) [✗]: The unique job identifier matching the original request.
+
+- `modelId` (string) [✗]: The ID of the model that was textured.
+
+- `tenantId` (string) [✗]: The tenant who owns the model.
+
+- `status` (string) [✗]: The result status of the texture generation.
+
+- `artifacts` (object) [✗]: S3 URLs of generated texture artifacts. Present only when status is 'completed'.
+
+- `error` (object) [✗]: Error details. Present only when status is 'failed'.
+
+- `metrics` (object) [✗]: Pipeline performance metrics.
+
+- `creditReservationId` (string) [✗]: Credit reservation ID to confirm (on success) or release (on failure).
+
+
+
+### texture-generation-request
+
+**Description:** Request AI-powered texture generation for a 3D model. Requires a mesh file URL and a text prompt describing the desired texture. Credits are reserved before dispatch.
+
+**Method:** `client.textureGenerationRequest(data)`
+
+**Payload Type:** `TextureGenerationRequestMessage`
+
+**Fields:**
+
+- `jobId` (string) [✗]: Unique job identifier for tracking.
+
+- `modelId` (string) [✗]: The unique identifier for the model to texture.
+
+- `tenantId` (string) [✗]: The identifier of the tenant requesting the generation.
+
+- `meshUrl` (string) [✗]: S3 URL to the source mesh file (GLB, OBJ, or STL).
+
+- `prompt` (string) [✗]: Text description of the desired texture (1-500 characters). Example: 'weathered bronze with green patina'.
+
+- `stylePreset` (string) [✗]: Style preset to guide the texture generation aesthetic.
+
+- `resolution` (integer) [✗]: Output texture resolution (width = height in pixels).
+
+- `creditReservationId` (string) [✗]: Credit reservation ID from the credit ledger. Must be confirmed on completion or released on failure.
 
 
 
@@ -838,6 +1963,12 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 - `thumbnailPath` (string) [✗]: The path to the generated thumbnail.
 
+- `thumbnail360Views` (array) [✗]: Array of 360° thumbnail view paths (16 angles) for vision-based analysis.
+
+- `gltfPreviewPath` (string) [✗]: The path to the generated GLTF/GLB 3D preview file.
+
+- `animatedPreviewPath` (string) [✗]: The path to the generated animated MP4 preview file.
+
 - `errorMessage` (string) [✗]: An error message if the thumbnail generation failed.
 
 - `storageLocation` (object) [✗]: The storage location of the model.
@@ -846,7 +1977,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 +1989,197 @@ 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) for enhanced vision-based metadata analysis.
+
+- `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:**
+
+- `eventVersion` (string) [✓]: Schema version for forward-compatible evolution
+
+- `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 — MUST be SHA-256 hashed at the producer side before publishing (GDPR/CNIL compliance). Never send raw email.
+
+- `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 backend logs
+
+- `correlationId` (string) [✗]: Correlation ID to link engagement events across frontend and backend boundaries, and to pipeline traces
+
+- `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 +2218,29 @@ new WorkerClient(config: WorkerClientConfig)
   - Get the current status of a job
 
 
+- `analyticsCollectionRequest(data: AnalyticsCollectionRequestMessage): Promise<JobResponse>`
+  - Request to trigger a manual market data collection job.
+Used for ad-hoc scraping of specific queries on marketplaces.
+
+
+- `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,19 +2264,119 @@ 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.
+
+Retry Configuration:
+- Automatic retry enabled for transient failures (connection errors, timeouts)
+- Default: 5 attempts with exponential backoff (2s, 4s, 8s, 16s, 32s)
+- Retry on: STORAGE_TIMEOUT, NETWORK_ERROR, MINIO_UNAVAILABLE, CONNECTION_REFUSED
+- No retry on: INVALID_CREDENTIALS, FILE_NOT_FOUND, PERMISSION_DENIED
+
+
+- `fileVectorizeCompleted(data: FileVectorizeCompletedMessage): Promise<JobResponse>`
+  - Result of the vectorization process containing the embedding vector.
+
+- `fileVectorizeRequest(data: FileVectorizeRequestMessage): Promise<JobResponse>`
+  - Request to generate a vector embedding for an image file using CLIP.
+
+- `ipCheckCompleted(data: IpCheckCompletedMessage): Promise<JobResponse>`
+  - Contains IP verification results including trademark risk, copyright risk, detected brands/franchises, and analysis confidence scores
+
+- `ipCheckRequest(data: IpCheckRequestMessage): Promise<JobResponse>`
+  - Triggers intellectual property verification analysis for a model thumbnail, detecting potential trademark and copyright issues using perceptual hashing, text analysis, and optional reverse image search.
+
+- `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
+
+
+- `marketplaceIntelligenceCompleted(data: MarketplaceIntelligenceCompletedMessage): Promise<JobResponse>`
+  - Response from marketplace intelligence scraping.
+Contains aggregated similarity data from marketplace searches.
+
+Consumed by worker-backend to update pipeline context before
+sellability analysis runs.
+
+
+- `marketplaceIntelligenceEvent(data: MarketplaceIntelligenceEventMessage): Promise<JobResponse>`
+  - Public marketplace intelligence data scraped from external marketplaces.
+
+This event contains:
+- Listing details (title, price, images)
+- Engagement metrics (views, favorites, reviews)
+- Shop information
+- Market positioning data
+
+Unlike marketplace-listing-sync-request (private user data), this focuses on:
+- Broad market trends and pricing analysis
+- Competitive intelligence and demand signals
+- Product popularity and sentiment
+
+Consumed by worker-analytic-collector for Elasticsearch indexing.
+Used for market research, pricing optimization, and trend detection.
+
+
+- `marketplaceIntelligenceRequest(data: MarketplaceIntelligenceRequestMessage): Promise<JobResponse>`
+  - Triggers automated marketplace scraping to find similar/competing listings
+for a given model. This is a pipeline stage that runs after metadata generation
+to inform sellability analysis with real market data.
+
+The worker-analytic-collector (or marketplace-connectors worker) will:
+1. Use model metadata (title, tags, category) to build search queries
+2. Scrape connected marketplaces (Etsy, eBay, etc.) for similar listings
+3. Emit marketplace-intelligence-event results for Elasticsearch indexing
+4. Return aggregated similarity data to the pipeline context
+
+Pipeline integration:
+- Triggered after: metadata-generation (needs model title/tags/category)
+- Results feed into: sellability-analysis (market positioning data)
+
+
+- `marketplaceListingDescriptionGenerationCompleted(data: MarketplaceListingDescriptionGenerationCompletedMessage): Promise<JobResponse>`
+  - Notifies backend that marketplace description generation completed. Contains generated description with metadata tracking (AI model, confidence, generation timestamp) and suggested price.
+
+- `marketplaceListingDescriptionGenerationRequest(data: MarketplaceListingDescriptionGenerationRequestMessage): Promise<JobResponse>`
+  - Generates SEO-optimized marketplace description for a 3D model using LLM vision analysis. Worker receives model data, technical metadata, and thumbnail URLs to generate compelling product descriptions tailored to the target marketplace.
 
-- `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.
+- `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.
 
-- `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.).
 
-- `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.).
+- `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
 
-- `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.
+
+- `marketplaceListingTagsGenerationCompleted(data: MarketplaceListingTagsGenerationCompletedMessage): Promise<JobResponse>`
+  - Notifies backend that marketplace tags generation completed. Contains generated tags optimized for discoverability with metadata tracking.
+
+- `marketplaceListingTagsGenerationRequest(data: MarketplaceListingTagsGenerationRequestMessage): Promise<JobResponse>`
+  - Generates searchability tags for a 3D model optimized for marketplace discoverability. Worker creates style, technical, and usage keywords following marketplace tag limits and SEO best practices.
+
+- `marketplaceListingTitleGenerationCompleted(data: MarketplaceListingTitleGenerationCompletedMessage): Promise<JobResponse>`
+  - Notifies backend that marketplace title generation completed. Contains generated title with metadata tracking.
+
+- `marketplaceListingTitleGenerationRequest(data: MarketplaceListingTitleGenerationRequestMessage): Promise<JobResponse>`
+  - Generates marketplace-optimized title for a 3D model. Worker creates concise, SEO-friendly titles following marketplace character limits and best practices.
+
+- `marketplaceListingUpdateCompleted(data: MarketplaceListingUpdateCompletedMessage): Promise<JobResponse>`
+  - Result of a listing update operation
+
+- `marketplaceListingUpdateRequest(data: MarketplaceListingUpdateRequestMessage): Promise<JobResponse>`
+  - Request to update an existing listing on a marketplace (price, quantity, etc.)
 
 - `mediaBatchDownloadCompleted(data: MediaBatchDownloadCompletedMessage): Promise<JobResponse>`
   - Notifies that a batch media download has been completed.
@@ -954,6 +2391,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.
 
@@ -966,11 +2411,20 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 - `modelDiscoveryScanRequest(data: ModelDiscoveryScanRequestMessage): Promise<JobResponse>`
   - Handles model discovery scan requests events.
 
+- `modelFinderIndexRequest(data: ModelFinderIndexRequestMessage): Promise<JobResponse>`
+  - DEPRECATED (2026-02-18) — FR-023 retired. Merge 3D rendering into worker-file-vectorize.
+
+- `modelFinderResponse(data: ModelFinderResponseMessage): Promise<JobResponse>`
+  - DEPRECATED (2026-02-18) — FR-023 retired. Merge 3D rendering into worker-file-vectorize.
+
+- `modelFinderSearchRequest(data: ModelFinderSearchRequestMessage): Promise<JobResponse>`
+  - DEPRECATED (2026-02-18) — FR-023 retired. Merge 3D rendering into worker-file-vectorize.
+
 - `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 vision analysis. Worker receives all necessary data in the payload (Model, TechnicalMetadata, Thumbnails) and does NOT query the database. Prerequisites: file download, technical metadata, and thumbnail generation must be complete before this message is sent.
 
 - `modelMetamodelDetectionFound(data: ModelMetamodelDetectionFoundMessage): Promise<JobResponse>`
   - Handles model metamodel detection found with hierarchical relationships.
@@ -978,23 +2432,93 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 - `modelMetamodelDetectionRequest(data: ModelMetamodelDetectionRequestMessage): Promise<JobResponse>`
   - Handles model metamodel detection requests.
 
+- `modelPrintAnalysisCompleted(data: ModelPrintAnalysisCompletedMessage): Promise<JobResponse>`
+  - Reports completion of 3D print analysis — contains estimation, printability, and cost breakdown per FR-022
+
+- `modelPrintAnalysisRequest(data: ModelPrintAnalysisRequestMessage): Promise<JobResponse>`
+  - Triggers 3D print analysis for a model — estimates print time, material usage, support needs, and cost breakdown per FR-022
+
 - `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
 
 - `modelTechnicalMetadataRequest(data: ModelTechnicalMetadataRequestMessage): Promise<JobResponse>`
   - Triggers comprehensive technical analysis of a 3D model file to extract geometry, quality metrics, and print-readiness information
 
+- `slicingFdmRequest(data: SlicingFdmRequestMessage): Promise<JobResponse>`
+  - Request FDM slicing simulation via OrcaSlicer (preferred) or heuristic fallback. Accepts OrcaSlicer-compatible printer/process/filament JSON profiles.
+
+- `slicingFdmResult(data: SlicingFdmResultMessage): Promise<JobResponse>`
+  - Result of FDM slicing simulation from OrcaSlicer (toolpath) or heuristic fallback. Contains exact physical metrics for cost calculation.
+
+- `slicingSlaRequest(data: SlicingSlaRequestMessage): Promise<JobResponse>`
+  - Request SLA/MSLA slicing simulation via PySLM cross-sectional analysis. Accepts resin printer profile with exposure, lift, and layer parameters.
+
+- `slicingSlaResult(data: SlicingSlaResultMessage): Promise<JobResponse>`
+  - Result of SLA/MSLA slicing simulation from PySLM cross-sectional analysis. Contains exact resin usage and print time metrics.
+
+- `textureGenerationCompleted(data: TextureGenerationCompletedMessage): Promise<JobResponse>`
+  - Emitted when AI texture generation completes (success or failure). Contains artifact S3 URLs on success, or error details on failure. The credit reservation should be confirmed (success) or released (failure) based on the status.
+
+- `textureGenerationRequest(data: TextureGenerationRequestMessage): Promise<JobResponse>`
+  - Request AI-powered texture generation for a 3D model. Requires a mesh file URL and a text prompt describing the desired texture. Credits are reserved before dispatch.
+
 - `thumbnailGenerationCompleted(data: ThumbnailGenerationCompletedMessage): Promise<JobResponse>`
   - 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