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

package/README.md

@@ -324,7 +324,7 @@ 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.
+- `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.
 
@@ -908,7 +908,7 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 ### model-metadata-generation-completed
 
-**Description:** Handles model metadata generation completed.
+**Description:** Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
 
 **Method:** `client.modelMetadataGenerationCompleted(data)`
 
@@ -916,15 +916,15 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 **Fields:**
 
-- `modelId` (string) [✓]: The unique identifier for the model.
+- `modelId` (string) [✓]: UUID of the model that was processed.
 
-- `metadata` (object) [✓]: The enriched metadata for the model.
+- `metadata` (object) [✓]: Enriched marketplace metadata generated by LLM.
 
 
 
 ### model-metadata-generation-request
 
-**Description:** Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+**Description:** Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (for vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (optional for vision enhancement).
 
 **Method:** `client.modelMetadataGenerationRequest(data)`
 
@@ -932,29 +932,9 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
 
 **Fields:**
 
-- `modelId` (string) [✗]: The unique identifier for the model.
-
-- `ownerId` (string) [✗]: The identifier of the user who owns the model.
-
-- `storageConnectionId` (string) [✗]: The ID of the storage connection (legacy - used if minioPath not provided).
-
-- `filePath` (string) [✗]: The path to the model file (legacy - used if minioPath not provided).
+- `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.
 
-- `minioPath` (string) [✗]: Path to model in MinIO (e.g., 'raw_models/{modelId}/original.glb'). If provided, file will be read from MinIO instead of downloading from storage provider.
-
-- `fileName` (string) [✗]: The name of the model file.
-
-- `fileSize` (number) [✗]: The size of the model file in bytes.
-
-- `fileLastModified` (string) [✗]: The last modified date of the model file.
-
-- `storageProviderType` (string) [✗]: The type of the storage provider.
-
-- `parentJobId` (string) [✗]: ID of parent file-download job (for BullMQ dependency tracking).
-
-- `modelThumbnailUrl` (string) [✗]: The URL of the model thumbnail.
-
-- `metamodel` (object) [✗]: The metamodel of the model.
+- `parentJobId` (string) [✗]: Optional ID of parent job for BullMQ dependency tracking. Set to thumbnail-generation job ID if you want metadata generation to wait until thumbnails are ready (enables vision analysis). Set to technical-metadata job ID for basic generation without vision. Not required for manual/retry scenarios.
 
 
 
@@ -1383,6 +1363,70 @@ Each worker includes its specific metrics in the `metrics` object.
 
 
 
+### 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
@@ -1536,10 +1580,10 @@ and stores aggregated statistics in Elasticsearch for trend analysis.
   - Handles model discovery scan requests events.
 
 - `modelMetadataGenerationCompleted(data: ModelMetadataGenerationCompletedMessage): Promise<JobResponse>`
-  - Handles model metadata generation completed.
+  - Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
 
 - `modelMetadataGenerationRequest(data: ModelMetadataGenerationRequestMessage): Promise<JobResponse>`
-  - Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+  - Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (for vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (optional for vision enhancement).
 
 - `modelMetamodelDetectionFound(data: ModelMetamodelDetectionFoundMessage): Promise<JobResponse>`
   - Handles model metamodel detection found with hierarchical relationships.
@@ -1598,6 +1642,19 @@ 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
 

package/dist/client.d.ts

@@ -230,13 +230,13 @@ export declare class WorkerClient {
      */
     modelDiscoveryScanRequest(data: types.ModelDiscoveryScanRequestMessage): 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.
      * @param data - The message payload
      * @returns Job response with job ID
      */
     modelMetadataGenerationCompleted(data: types.ModelMetadataGenerationCompletedMessage): Promise<JobResponse>;
     /**
-     * Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+     * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (for vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (optional for vision enhancement).
      * @param data - The message payload
      * @returns Job response with job ID
      */
@@ -334,4 +334,20 @@ export declare class WorkerClient {
      * @returns Job response with job ID
      */
     workerAnalyticsEvent(data: types.WorkerAnalyticsEventMessage): 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
+  
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    workerMetricsEnrichedEvent(data: types.WorkerMetricsEnrichedEventMessage): Promise<JobResponse>;
 }

package/dist/client.js

@@ -305,7 +305,7 @@ export class WorkerClient {
         return this.sendToQueue(types.MessageTypes.MODEL_DISCOVERY_SCAN_REQUEST, data);
     }
     /**
-     * Handles model metadata generation completed.
+     * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
      * @param data - The message payload
      * @returns Job response with job ID
      */
@@ -313,7 +313,7 @@ export class WorkerClient {
         return this.sendToQueue(types.MessageTypes.MODEL_METADATA_GENERATION_COMPLETED, data);
     }
     /**
-     * Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+     * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (for vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (optional for vision enhancement).
      * @param data - The message payload
      * @returns Job response with job ID
      */
@@ -437,4 +437,22 @@ export class WorkerClient {
     async workerAnalyticsEvent(data) {
         return this.sendToQueue(types.MessageTypes.WORKER_ANALYTICS_EVENT, data);
     }
+    /**
+     * 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
+  
+     * @param data - The message payload
+     * @returns Job response with job ID
+     */
+    async workerMetricsEnrichedEvent(data) {
+        return this.sendToQueue(types.MessageTypes.WORKER_METRICS_ENRICHED_EVENT, data);
+    }
 }

package/dist/types.d.ts

@@ -42,6 +42,7 @@ export declare const MessageTypes: {
     readonly THUMBNAIL_GENERATION_REQUEST: "thumbnail-generation-request";
     readonly USER_ENGAGEMENT_EVENT: "user-engagement-event";
     readonly WORKER_ANALYTICS_EVENT: "worker-analytics-event";
+    readonly WORKER_METRICS_ENRICHED_EVENT: "worker-metrics-enriched-event";
 };
 export type MessageType = typeof MessageTypes[keyof typeof MessageTypes];
 /**
@@ -220,7 +221,7 @@ export interface FileDownloadCompletedMessage {
 export interface FileDownloadRequestMessage {
     /** The unique identifier for the model to be downloaded. */
     modelId?: string;
-    /** The identifier of the user who owns the model. */
+    /** The identifier of the user who owns the model. Optional - if not provided, will be retrieved from StorageConnection. */
     ownerId?: string;
     /** The storage location of the model. */
     storageLocation?: Record<string, string | number | boolean>;
@@ -669,42 +670,22 @@ export interface ModelDiscoveryScanRequestMessage {
     path?: string;
 }
 /**
- * Handles model metadata generation completed.
+ * Notifies backend that enriched marketplace metadata generation completed. Backend updates Model entity with generated description, tags, classification, etc.
  */
 export interface ModelMetadataGenerationCompletedMessage {
-    /** The unique identifier for the model. */
+    /** UUID of the model that was processed. */
     modelId: string;
-    /** The enriched metadata for the model. */
+    /** Enriched marketplace metadata generated by LLM. */
     metadata: Record<string, string | number | boolean>;
 }
 /**
- * Handles model metadata generation requests. Supports both storage provider downloads and MinIO-cached files.
+ * Generates enriched marketplace metadata (SEO descriptions, tags, categories) for 3D models using LLM analysis with optional vision capabilities. Worker queries database by modelId to retrieve: Model (fileName, fileSize, ownerId, storageItem), TechnicalMetadata (geometry, quality, printability), and ThumbnailMedia (for vision analysis). Prerequisites: file download completed, technical metadata analysis completed (strongly recommended), thumbnail generation completed (optional for vision enhancement).
  */
 export interface ModelMetadataGenerationRequestMessage {
-    /** The unique identifier for the model. */
+    /** 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;
-    /** The identifier of the user who owns the model. */
-    ownerId?: string;
-    /** The ID of the storage connection (legacy - used if minioPath not provided). */
-    storageConnectionId?: string;
-    /** The path to the model file (legacy - used if minioPath not provided). */
-    filePath?: 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. */
-    minioPath?: string;
-    /** The name of the model file. */
-    fileName?: string;
-    /** The size of the model file in bytes. */
-    fileSize?: number;
-    /** The last modified date of the model file. */
-    fileLastModified?: string;
-    /** The type of the storage provider. */
-    storageProviderType?: string;
-    /** ID of parent file-download job (for BullMQ dependency tracking). */
+    /** Optional ID of parent job for BullMQ dependency tracking. Set to thumbnail-generation job ID if you want metadata generation to wait until thumbnails are ready (enables vision analysis). Set to technical-metadata job ID for basic generation without vision. Not required for manual/retry scenarios. */
     parentJobId?: string;
-    /** The URL of the model thumbnail. */
-    modelThumbnailUrl?: string;
-    /** The metamodel of the model. */
-    metamodel?: Record<string, string | number | boolean>;
 }
 /**
  * Handles model metamodel detection found with hierarchical relationships.
@@ -1047,3 +1028,60 @@ export interface WorkerAnalyticsEventMessage {
     /** Worker-specific metrics. Structure varies by eventType. */
     metrics?: Record<string, string | number | boolean>;
 }
+/**
+ * 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
+
+ */
+export interface WorkerMetricsEnrichedEventMessage {
+    /** Fixed type for enriched worker metrics */
+    eventType: string;
+    /** Identifier of the worker */
+    workerId: string;
+    /** Unique BullMQ job identifier */
+    jobId: string;
+    /** ISO 8601 timestamp when job completed */
+    timestamp: string;
+    /** Job completion status */
+    status: string;
+    /** User who owns the resource/triggered the job */
+    userId?: string;
+    /** Organization/tenant ID (for multi-tenant deployments) */
+    tenantId?: string;
+    /** Session ID for correlating user actions */
+    sessionId?: string;
+    /** Request ID from originating API call (X-Request-Id) */
+    requestId?: string;
+    /** Model ID being processed */
+    modelId?: string;
+    /** Metamodel ID being processed */
+    metamodelId?: string;
+    /** Storage item ID (for file operations) */
+    storageItemId?: string;
+    /** Comprehensive timing breakdown */
+    timing?: Record<string, string | number | boolean>;
+    /** LLM token usage and cost breakdown */
+    llmUsage?: Record<string, string | number | boolean>;
+    /** System resource consumption during job */
+    resources?: Record<string, string | number | boolean>;
+    /** Worker-specific metrics (varies by worker type) */
+    workerMetrics?: Record<string, string | number | boolean>;
+    /** Error details if status is failure */
+    error?: Record<string, string | number | boolean>;
+    /** Deployment environment */
+    environment?: string;
+    /** Cloud region/datacenter */
+    region?: string;
+    /** Worker service version */
+    workerVersion?: string;
+    /** Pod/container hostname */
+    hostname?: string;
+}

package/dist/types.js

@@ -43,4 +43,5 @@ export const MessageTypes = {
     THUMBNAIL_GENERATION_REQUEST: 'thumbnail-generation-request',
     USER_ENGAGEMENT_EVENT: 'user-engagement-event',
     WORKER_ANALYTICS_EVENT: 'worker-analytics-event',
+    WORKER_METRICS_ENRICHED_EVENT: 'worker-metrics-enriched-event',
 };

package/package.json

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