@mesh-sync/worker-backend-client 4.0.6 → 4.0.9

package/README.md

@@ -184,6 +184,8 @@ Used for:
 
 - `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) [✗]: 
@@ -210,6 +212,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) [✗]: 
@@ -245,6 +249,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)
@@ -274,6 +280,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
@@ -314,7 +322,15 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 ### file-download-request
 
-**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.
+**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)`
 
@@ -328,6 +344,10 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 - `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.
+
 - `minioDestination` (object) [✗]: Destination in MinIO where file will be uploaded after download.
 
 - `autoEnqueueChildren` (boolean) [✗]: Automatically enqueue thumbnail generation, technical metadata analysis, and metadata generation jobs after download completes.
@@ -340,6 +360,44 @@ Example: Publishing a metamodel with PLA, Resin, ABS materials creates 3 jobs.
 
 
 
+### file-vectorize-completed
+
+**Description:** Result of the vectorization process containing the embedding vector.
+
+**Method:** `client.fileVectorizeCompleted(data)`
+
+**Payload Type:** `FileVectorizeCompletedMessage`
+
+**Fields:**
+
+- `fileId` (string) [✗]: 
+
+- `vector` (array) [✗]: The computed embedding vector
+
+- `modelName` (string) [✗]: 
+
+- `dimension` (integer) [✗]: Length of the vector (e.g., 512)
+
+
+
+### file-vectorize-request
+
+**Description:** Request to generate a vector embedding for an image file using CLIP.
+
+**Method:** `client.fileVectorizeRequest(data)`
+
+**Payload Type:** `FileVectorizeRequestMessage`
+
+**Fields:**
+
+- `fileId` (string) [✗]: The ID of the file in the database
+
+- `storageItem` () [✗]: Location of the image file
+
+- `modelName` (string) [✗]: Optional: Specific model version to use
+
+
+
 ### marketplace-analytics-sync-completed
 
 **Description:** Contains synced analytics data for marketplace listings. Backend stores this in marketplace_analytics_snapshots table and indexes to ELK. Works with any marketplace provider.
@@ -728,7 +786,19 @@ Includes bidirectional sync: - Pull: Fetch listings from marketplace to update l
 - `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.
 
 
-- `storageConnectionId` (string) [✗]: UUID of the StorageConnection entity from which to download the media files. Used to authenticate and access the source storage provider.
+- `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.
@@ -906,6 +976,60 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 - `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:** Request to index a 3D model for similarity search.
+
+**Method:** `client.modelFinderIndexRequest(data)`
+
+**Payload Type:** `ModelFinderIndexRequestMessage`
+
+**Fields:**
+
+- `modelId` (string) [✗]: 
+
+- `storageItem` () [✗]: 
+
+
+
+### model-finder-response
+
+**Description:** Response containing search results from the model finder.
+
+**Method:** `client.modelFinderResponse(data)`
+
+**Payload Type:** `ModelFinderResponseMessage`
+
+**Fields:**
+
+- `requestId` (string) [✗]: 
+
+- `results` (array) [✗]: 
+
+
+
+### model-finder-search-request
+
+**Description:** Request to search for similar 3D models.
+
+**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
@@ -926,7 +1050,7 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 ### model-metadata-generation-request
 
-**Description:** Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM vision analysis of thumbnails by default. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (required for default vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (REQUIRED for vision-enhanced analysis, default behavior). Vision analysis can be disabled via ENABLE_VISION_METADATA_GENERATION environment variable (default: true).
+**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)`
 
@@ -934,9 +1058,13 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 **Fields:**
 
-- `modelId` (string) [✗]: UUID of the model to generate metadata for. Worker queries database to retrieve: 1) Model entity (name, fileName, fileSize, ownerId, storageItem relationship), 2) Model.technicalMetadata relationship (vertices, faces, quality scores, printability metrics), 3) AssociatedMedia.thumbnails (via associatedMediaId) for vision-enhanced analysis. All data fetched from PostgreSQL - no additional parameters required.
+- `modelId` (string) [✗]: UUID of the model (reference only)
+
+- `model` (object) [✗]: Core model entity data
 
-- `parentJobId` (string) [✗]: ID of parent thumbnail-generation job for BullMQ dependency tracking. SHOULD be set to thumbnail-generation job ID to ensure thumbnails are ready before metadata generation (required for default vision analysis). If omitted, worker will check for thumbnail existence and wait/retry if ENABLE_VISION_METADATA_GENERATION=true.
+- `technicalMetadata` (object) [✗]: Geometric and technical analysis results
+
+- `thumbnails` (array) [✗]: List of 360 degree thumbnail views (URLs or paths)
 
 
 
@@ -968,7 +1096,9 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 - `folderPath` (string) [✓]: The path to the folder that was processed.
 
-- `discoveredFiles` (array) [✓]: A list of files discovered in the folder.
+- `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.
 
@@ -1022,10 +1152,14 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 **Fields:**
 
-- `metamodelId` (string) [✗]: UUID of the metamodel to analyze. Worker will fetch all model metadata, technical metadata, enriched metadata, and child models from PostgreSQL.
+- `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
 
 
@@ -1222,6 +1356,8 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 - `thumbnailPath` (string) [✗]: The path to the generated thumbnail.
 
+- `thumbnail360Views` (array) [✗]: Array of 360° thumbnail view paths (16 angles) for vision-based analysis.
+
 - `errorMessage` (string) [✗]: An error message if the thumbnail generation failed.
 
 - `storageLocation` (object) [✗]: The storage location of the model.
@@ -1248,7 +1384,7 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 - `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).
+- `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).
 
@@ -1508,7 +1644,21 @@ 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>`
-  - Downloads model file from storage provider to MinIO for processing pipeline. Acts as parent job for thumbnail generation, technical metadata analysis, and metadata generation.
+  - 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.
 
 - `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.
@@ -1581,11 +1731,20 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 - `modelDiscoveryScanRequest(data: ModelDiscoveryScanRequestMessage): Promise<JobResponse>`
   - Handles model discovery scan requests events.
 
+- `modelFinderIndexRequest(data: ModelFinderIndexRequestMessage): Promise<JobResponse>`
+  - Request to index a 3D model for similarity search.
+
+- `modelFinderResponse(data: ModelFinderResponseMessage): Promise<JobResponse>`
+  - Response containing search results from the model finder.
+
+- `modelFinderSearchRequest(data: ModelFinderSearchRequestMessage): Promise<JobResponse>`
+  - Request to search for similar 3D models.
+
 - `modelMetadataGenerationCompleted(data: ModelMetadataGenerationCompletedMessage): Promise<JobResponse>`
   - Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
 
 - `modelMetadataGenerationRequest(data: ModelMetadataGenerationRequestMessage): Promise<JobResponse>`
-  - Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM vision analysis of thumbnails by default. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (required for default vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (REQUIRED for vision-enhanced analysis, default behavior). Vision analysis can be disabled via ENABLE_VISION_METADATA_GENERATION environment variable (default: true).
+  - 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.

package/dist/client.d.ts

@@ -96,11 +96,31 @@ export declare class WorkerClient {
      */
     fileDownloadCompleted(data: types.FileDownloadCompletedMessage): Promise<JobResponse>;
     /**
-     * Downloads model file from storage provider to MinIO for processing pipeline. Acts as parent job for thumbnail generation, technical metadata analysis, and metadata generation.
+     * 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
+  
      * @param data - The message payload
      * @returns Job response with job ID
      */
     fileDownloadRequest(data: types.FileDownloadRequestMessage): Promise<JobResponse>;
+    /**
+     * Result of the vectorization process containing the embedding vector.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    fileVectorizeCompleted(data: types.FileVectorizeCompletedMessage): Promise<JobResponse>;
+    /**
+     * Request to generate a vector embedding for an image file using CLIP.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    fileVectorizeRequest(data: types.FileVectorizeRequestMessage): 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.
      * @param data - The message payload
@@ -229,6 +249,24 @@ export declare class WorkerClient {
      * @returns Job response with job ID
      */
     modelDiscoveryScanRequest(data: types.ModelDiscoveryScanRequestMessage): Promise<JobResponse>;
+    /**
+     * Request to index a 3D model for similarity search.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    modelFinderIndexRequest(data: types.ModelFinderIndexRequestMessage): Promise<JobResponse>;
+    /**
+     * Response containing search results from the model finder.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    modelFinderResponse(data: types.ModelFinderResponseMessage): Promise<JobResponse>;
+    /**
+     * Request to search for similar 3D models.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    modelFinderSearchRequest(data: types.ModelFinderSearchRequestMessage): Promise<JobResponse>;
     /**
      * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
      * @param data - The message payload
@@ -236,7 +274,7 @@ export declare class WorkerClient {
      */
     modelMetadataGenerationCompleted(data: types.ModelMetadataGenerationCompletedMessage): Promise<JobResponse>;
     /**
-     * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM vision analysis of thumbnails by default. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (required for default vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (REQUIRED for vision-enhanced analysis, default behavior). Vision analysis can be disabled via ENABLE_VISION_METADATA_GENERATION environment variable (default: true).
+     * 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.
      * @param data - The message payload
      * @returns Job response with job ID
      */

package/dist/client.js

@@ -131,13 +131,37 @@ export class WorkerClient {
         return this.sendToQueue(types.MessageTypes.FILE_DOWNLOAD_COMPLETED, data);
     }
     /**
-     * Downloads model file from storage provider to MinIO for processing pipeline. Acts as parent job for thumbnail generation, technical metadata analysis, and metadata generation.
+     * 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
+  
      * @param data - The message payload
      * @returns Job response with job ID
      */
     async fileDownloadRequest(data) {
         return this.sendToQueue(types.MessageTypes.FILE_DOWNLOAD_REQUEST, data);
     }
+    /**
+     * Result of the vectorization process containing the embedding vector.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    async fileVectorizeCompleted(data) {
+        return this.sendToQueue(types.MessageTypes.FILE_VECTORIZE_COMPLETED, data);
+    }
+    /**
+     * Request to generate a vector embedding for an image file using CLIP.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    async fileVectorizeRequest(data) {
+        return this.sendToQueue(types.MessageTypes.FILE_VECTORIZE_REQUEST, data);
+    }
     /**
      * Contains synced analytics data for marketplace listings. Backend stores this in marketplace_analytics_snapshots table and indexes to ELK. Works with any marketplace provider.
      * @param data - The message payload
@@ -304,6 +328,30 @@ export class WorkerClient {
     async modelDiscoveryScanRequest(data) {
         return this.sendToQueue(types.MessageTypes.MODEL_DISCOVERY_SCAN_REQUEST, data);
     }
+    /**
+     * Request to index a 3D model for similarity search.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    async modelFinderIndexRequest(data) {
+        return this.sendToQueue(types.MessageTypes.MODEL_FINDER_INDEX_REQUEST, data);
+    }
+    /**
+     * Response containing search results from the model finder.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    async modelFinderResponse(data) {
+        return this.sendToQueue(types.MessageTypes.MODEL_FINDER_RESPONSE, data);
+    }
+    /**
+     * Request to search for similar 3D models.
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    async modelFinderSearchRequest(data) {
+        return this.sendToQueue(types.MessageTypes.MODEL_FINDER_SEARCH_REQUEST, data);
+    }
     /**
      * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
      * @param data - The message payload
@@ -313,7 +361,7 @@ export class WorkerClient {
         return this.sendToQueue(types.MessageTypes.MODEL_METADATA_GENERATION_COMPLETED, data);
     }
     /**
-     * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM vision analysis of thumbnails by default. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (required for default vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (REQUIRED for vision-enhanced analysis, default behavior). Vision analysis can be disabled via ENABLE_VISION_METADATA_GENERATION environment variable (default: true).
+     * 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.
      * @param data - The message payload
      * @returns Job response with job ID
      */

package/dist/types.d.ts

@@ -9,6 +9,8 @@ export declare const MessageTypes: {
     readonly ETSY_PUBLISH_LISTING_REQUEST: "etsy-publish-listing-request";
     readonly FILE_DOWNLOAD_COMPLETED: "file-download-completed";
     readonly FILE_DOWNLOAD_REQUEST: "file-download-request";
+    readonly FILE_VECTORIZE_COMPLETED: "file-vectorize-completed";
+    readonly FILE_VECTORIZE_REQUEST: "file-vectorize-request";
     readonly MARKETPLACE_ANALYTICS_SYNC_COMPLETED: "marketplace-analytics-sync-completed";
     readonly MARKETPLACE_ANALYTICS_SYNC_REQUEST: "marketplace-analytics-sync-request";
     readonly MARKETPLACE_CONNECTION_SYNC_COMPLETED: "marketplace-connection-sync-completed";
@@ -28,6 +30,9 @@ export declare const MessageTypes: {
     readonly MODEL_DISCOVERY_SCAN_FOUND_EVENT: "model-discovery-scan-found-event";
     readonly MODEL_DISCOVERY_SCAN_PROGRESS_EVENT: "model-discovery-scan-progress-event";
     readonly MODEL_DISCOVERY_SCAN_REQUEST: "model-discovery-scan-request";
+    readonly MODEL_FINDER_INDEX_REQUEST: "model-finder-index-request";
+    readonly MODEL_FINDER_RESPONSE: "model-finder-response";
+    readonly MODEL_FINDER_SEARCH_REQUEST: "model-finder-search-request";
     readonly MODEL_METADATA_GENERATION_COMPLETED: "model-metadata-generation-completed";
     readonly MODEL_METADATA_GENERATION_REQUEST: "model-metadata-generation-request";
     readonly MODEL_METAMODEL_DETECTION_FOUND: "model-metamodel-detection-found";
@@ -116,6 +121,8 @@ export interface EtsyAnalyticsSyncCompletedMessage {
     errorCount?: string | number | boolean;
     /** Analytics for each synced listing */
     results?: Array<Record<string, string | number | boolean>>;
+    /** New credentials if token was refreshed during operation */
+    credentialUpdate?: Record<string, string | number | boolean>;
     /** Errors for failed listings */
     errors?: Array<Record<string, string | number | boolean>>;
     /**  */
@@ -135,6 +142,8 @@ export interface EtsyAnalyticsSyncRequestMessage {
     userId?: string;
     /** Etsy shop ID for shop-level analytics */
     shopId?: string;
+    /** Etsy OAuth credentials */
+    credentials?: Record<string, string | number | boolean>;
     /** Date range for historical analytics */
     timeRange?: Record<string, string | number | boolean>;
     /**  */
@@ -163,6 +172,8 @@ export interface EtsyPublishListingCompletedMessage {
     etsyListingId?: string;
     /** URL to view listing on Etsy (only if status=SUCCESS) */
     etsyListingUrl?: string;
+    /** New credentials if token was refreshed during operation */
+    credentialUpdate?: Record<string, string | number | boolean>;
     /** Etsy digital file ID (only if status=SUCCESS) */
     etsyFileId?: string;
     /** Error details (only if status=FAILED) */
@@ -185,6 +196,8 @@ export interface EtsyPublishListingRequestMessage {
     metamodelId?: string;
     /** User ID who owns the metamodel */
     ownerId?: string;
+    /** Etsy OAuth credentials */
+    credentials?: Record<string, string | number | boolean>;
     /** Material-specific listing configuration */
     materialVariant?: Record<string, string | number | boolean>;
     /** Common listing information */
@@ -216,7 +229,15 @@ export interface FileDownloadCompletedMessage {
     downloadedAt?: string;
 }
 /**
- * Downloads model file from storage provider to MinIO for processing pipeline. Acts as parent job for thumbnail generation, technical metadata analysis, and metadata generation.
+ * 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
+
  */
 export interface FileDownloadRequestMessage {
     /** The unique identifier for the model to be downloaded. */
@@ -225,6 +246,10 @@ export interface FileDownloadRequestMessage {
     ownerId?: string;
     /** The storage location of the model. */
     storageLocation?: Record<string, string | number | boolean>;
+    /** Optional metadata from discovery. For Thingiverse, contains downloadUrl for direct file access. */
+    metadata?: Record<string, string | number | boolean>;
+    /** Decrypted credentials required for this specific download operation. Injected by the backend. */
+    credentials?: Record<string, string | number | boolean>;
     /** Destination in MinIO where file will be uploaded after download. */
     minioDestination?: Record<string, string | number | boolean>;
     /** Automatically enqueue thumbnail generation, technical metadata analysis, and metadata generation jobs after download completes. */
@@ -236,6 +261,30 @@ export interface FileDownloadRequestMessage {
     /** Optional webhook URL to call when download completes. If provided, worker will POST completion status to this endpoint. */
     webhookUrl?: string;
 }
+/**
+ * Result of the vectorization process containing the embedding vector.
+ */
+export interface FileVectorizeCompletedMessage {
+    /**  */
+    fileId?: string;
+    /** The computed embedding vector */
+    vector?: Array<Record<string, string | number | boolean>>;
+    /**  */
+    modelName?: string;
+    /** Length of the vector (e.g., 512) */
+    dimension?: string | number | boolean;
+}
+/**
+ * Request to generate a vector embedding for an image file using CLIP.
+ */
+export interface FileVectorizeRequestMessage {
+    /** The ID of the file in the database */
+    fileId?: string;
+    /** Location of the image file */
+    storageItem?: string | number | boolean;
+    /** Optional: Specific model version to use */
+    modelName?: string;
+}
 /**
  * Contains synced analytics data for marketplace listings. Backend stores this in marketplace_analytics_snapshots table and indexes to ELK. Works with any marketplace provider.
  */
@@ -541,9 +590,21 @@ export interface MediaBatchDownloadRequestMessage {
     /** Unique identifier for this batch of media files. Used for organizing processed files in S3 storage (media/{batchId}/) and correlating with completion responses.
    */
     batchId?: string;
-    /** UUID of the StorageConnection entity from which to download the media files. Used to authenticate and access the source storage provider.
+    /** 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.)
+   */
+    downloadStrategy?: string;
+    /** Type of entity these media files belong to. Used for linking downloaded media to the correct entity in the database.
+   */
+    entityType?: string;
+    /** UUID of the model or metamodel entity that owns these media files. Used for creating storage item associations after download.
+   */
+    entityId?: 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.
    */
     storageConnectionId?: string;
+    /** Decrypted credentials for the storage provider (Fat Payload pattern). Required when downloadStrategy is 'storage_provider'.
+   */
+    credentials?: Record<string, string | number | boolean>;
     /** Array of media files to download and process. Must contain at least one file. Each file includes metadata for identification and processing.
    */
     mediaFiles?: Array<Record<string, string | number | boolean>>;
@@ -670,6 +731,39 @@ export interface ModelDiscoveryScanRequestMessage {
     providerType?: string;
     /** The specific path within the storage connection to scan for this library. */
     path?: string;
+    /** Decrypted credentials for the storage provider. */
+    credentials?: Record<string, string | number | boolean>;
+    /** Configuration for the storage connection (e.g. scanRootPath). */
+    configuration?: Record<string, string | number | boolean>;
+}
+/**
+ * Request to index a 3D model for similarity search.
+ */
+export interface ModelFinderIndexRequestMessage {
+    /**  */
+    modelId?: string;
+    /**  */
+    storageItem?: string | number | boolean;
+}
+/**
+ * Response containing search results from the model finder.
+ */
+export interface ModelFinderResponseMessage {
+    /**  */
+    requestId?: string;
+    /**  */
+    results?: Array<Record<string, string | number | boolean>>;
+}
+/**
+ * Request to search for similar 3D models.
+ */
+export interface ModelFinderSearchRequestMessage {
+    /** Optional: Search using an existing model as reference */
+    referenceModelId?: string;
+    /** Optional: Search using an uploaded image */
+    referenceImageId?: string;
+    /**  */
+    limit?: string | number | boolean;
 }
 /**
  * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
@@ -681,13 +775,17 @@ export interface ModelMetadataGenerationCompletedMessage {
     metadata: Record<string, string | number | boolean>;
 }
 /**
- * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM vision analysis of thumbnails by default. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (required for default vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (REQUIRED for vision-enhanced analysis, default behavior). Vision analysis can be disabled via ENABLE_VISION_METADATA_GENERATION environment variable (default: true).
+ * 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.
  */
 export interface ModelMetadataGenerationRequestMessage {
-    /** UUID of the model to generate metadata for. Worker queries database to retrieve: 1) Model entity (name, fileName, fileSize, ownerId, storageItem relationship), 2) Model.technicalMetadata relationship (vertices, faces, quality scores, printability metrics), 3) AssociatedMedia.thumbnails (via associatedMediaId) for vision-enhanced analysis. All data fetched from PostgreSQL - no additional parameters required. */
+    /** UUID of the model (reference only) */
     modelId?: string;
-    /** ID of parent thumbnail-generation job for BullMQ dependency tracking. SHOULD be set to thumbnail-generation job ID to ensure thumbnails are ready before metadata generation (required for default vision analysis). If omitted, worker will check for thumbnail existence and wait/retry if ENABLE_VISION_METADATA_GENERATION=true. */
-    parentJobId?: string;
+    /** Core model entity data */
+    model?: Record<string, string | number | boolean>;
+    /** Geometric and technical analysis results */
+    technicalMetadata?: Record<string, string | number | boolean>;
+    /** List of 360 degree thumbnail views (URLs or paths) */
+    thumbnails?: Array<Record<string, string | number | boolean>>;
 }
 /**
  * Handles model metamodel detection found with hierarchical relationships.
@@ -704,8 +802,10 @@ export interface ModelMetamodelDetectionRequestMessage {
     connectionId: string;
     /** The path to the folder that was processed. */
     folderPath: string;
-    /** A list of files discovered in the folder. */
-    discoveredFiles: Array<Record<string, string | number | boolean>>;
+    /** A list of files discovered in the folder. Worker should check this first, then manifestUrl. */
+    discoveredFiles?: Array<Record<string, string | number | boolean>>;
+    /** URL to a JSON file containing the list of discovered files (for large folders) */
+    manifestUrl?: string;
     /** A signature representing the state of the folder. */
     folderSignature: Record<string, string | number | boolean>;
     /** The timestamp when the folder was processed. */
@@ -744,10 +844,14 @@ export interface ModelSellabilityAnalysisCompletedMessage {
  * 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.
  */
 export interface ModelSellabilityAnalysisRequestMessage {
-    /** UUID of the metamodel to analyze. Worker will fetch all model metadata, technical metadata, enriched metadata, and child models from PostgreSQL. */
+    /** UUID of the metamodel to analyze. */
     metamodelId?: string;
     /** UUID of the user who owns the metamodel */
     ownerId?: string;
+    /** Full metamodel data including technical metadata, enriched metadata, and child models. Injected by backend to avoid DB access. */
+    metamodelData?: Record<string, string | number | boolean>;
+    /** URL to a JSON manifest containing the metamodel data if it is too large for the message payload. */
+    manifestUrl?: string;
     /** Optional analysis configuration */
     analysisOptions?: Record<string, string | number | boolean>;
 }
@@ -909,6 +1013,8 @@ export interface ThumbnailGenerationCompletedMessage {
     status?: string;
     /** The path to the generated thumbnail. */
     thumbnailPath?: string;
+    /** Array of 360° thumbnail view paths (16 angles) for vision-based analysis. */
+    thumbnail360Views?: Array<Record<string, string | number | boolean>>;
     /** An error message if the thumbnail generation failed. */
     errorMessage?: string;
     /** The storage location of the model. */
@@ -928,7 +1034,7 @@ export interface ThumbnailGenerationRequestMessage {
     minioPath?: string;
     /** The type of preview to generate, e.g., 'default', 'static', 'glb'. */
     previewType?: string;
-    /** Generate 16 angle views for 360° preview (4 horizontal x 4 vertical angles). */
+    /** Generate 16 angle views for 360° preview (4 horizontal x 4 vertical angles) for enhanced vision-based metadata analysis. */
     generate360Views?: boolean;
     /** ID of parent file-download job (for BullMQ dependency tracking). */
     parentJobId?: string;

package/dist/types.js

@@ -10,6 +10,8 @@ export const MessageTypes = {
     ETSY_PUBLISH_LISTING_REQUEST: 'etsy-publish-listing-request',
     FILE_DOWNLOAD_COMPLETED: 'file-download-completed',
     FILE_DOWNLOAD_REQUEST: 'file-download-request',
+    FILE_VECTORIZE_COMPLETED: 'file-vectorize-completed',
+    FILE_VECTORIZE_REQUEST: 'file-vectorize-request',
     MARKETPLACE_ANALYTICS_SYNC_COMPLETED: 'marketplace-analytics-sync-completed',
     MARKETPLACE_ANALYTICS_SYNC_REQUEST: 'marketplace-analytics-sync-request',
     MARKETPLACE_CONNECTION_SYNC_COMPLETED: 'marketplace-connection-sync-completed',
@@ -29,6 +31,9 @@ export const MessageTypes = {
     MODEL_DISCOVERY_SCAN_FOUND_EVENT: 'model-discovery-scan-found-event',
     MODEL_DISCOVERY_SCAN_PROGRESS_EVENT: 'model-discovery-scan-progress-event',
     MODEL_DISCOVERY_SCAN_REQUEST: 'model-discovery-scan-request',
+    MODEL_FINDER_INDEX_REQUEST: 'model-finder-index-request',
+    MODEL_FINDER_RESPONSE: 'model-finder-response',
+    MODEL_FINDER_SEARCH_REQUEST: 'model-finder-search-request',
     MODEL_METADATA_GENERATION_COMPLETED: 'model-metadata-generation-completed',
     MODEL_METADATA_GENERATION_REQUEST: 'model-metadata-generation-request',
     MODEL_METAMODEL_DETECTION_FOUND: 'model-metamodel-detection-found',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-sync/worker-backend-client",
-  "version": "4.0.6",
+  "version": "4.0.9",
   "description": "Auto-generated TypeScript client for worker-backend - provides type-safe methods for enqueueing jobs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",