@message-queue-toolkit/core 24.2.0 → 25.1.0

package/dist/queues/MessageSchemaContainer.d.ts

@@ -1,16 +1,62 @@
 import type { Either } from '@lokalise/node-core';
 import type { CommonEventDefinition } from '@message-queue-toolkit/schemas';
 import type { ZodSchema } from 'zod/v4';
+import { type MessageTypeResolverConfig } from './MessageTypeResolver.ts';
+export type SchemaEntry<MessagePayloadSchemas extends object> = {
+    schema: ZodSchema<MessagePayloadSchemas>;
+    /**
+     * Explicit message type for this schema.
+     * Required when using a custom resolver function.
+     */
+    messageType?: string;
+};
+export type DefinitionEntry = {
+    definition: CommonEventDefinition;
+    /**
+     * Explicit message type for this definition.
+     * Required when using a custom resolver function.
+     */
+    messageType?: string;
+};
 export type MessageSchemaContainerOptions<MessagePayloadSchemas extends object> = {
-    messageDefinitions: readonly CommonEventDefinition[];
-    messageSchemas: readonly ZodSchema<MessagePayloadSchemas>[];
-    messageTypeField?: string;
+    messageDefinitions: readonly DefinitionEntry[];
+    messageSchemas: readonly SchemaEntry<MessagePayloadSchemas>[];
+    /**
+     * Configuration for resolving message types.
+     */
+    messageTypeResolver?: MessageTypeResolverConfig;
 };
 export declare class MessageSchemaContainer<MessagePayloadSchemas extends object> {
     readonly messageDefinitions: Record<string | symbol, CommonEventDefinition>;
     private readonly messageSchemas;
-    private readonly messageTypeField?;
+    private readonly messageTypeResolver?;
     constructor(options: MessageSchemaContainerOptions<MessagePayloadSchemas>);
-    resolveSchema(message: Record<string, any>): Either<Error, ZodSchema<MessagePayloadSchemas>>;
-    private resolveMap;
+    /**
+     * Resolves the schema for a message based on its type.
+     *
+     * @param message - The parsed message data
+     * @param attributes - Optional message-level attributes (e.g., PubSub attributes)
+     * @returns Either an error or the resolved schema
+     */
+    resolveSchema(message: Record<string, any>, attributes?: Record<string, unknown>): Either<Error, ZodSchema<MessagePayloadSchemas>>;
+    /**
+     * Resolves message type from message data and optional attributes.
+     * Only called when messageTypeResolver is configured.
+     */
+    private resolveMessageTypeFromData;
+    /**
+     * Gets the field path used for extracting message type from schemas during registration.
+     * Returns undefined for literal or custom resolver modes.
+     */
+    private getMessageTypePathForSchema;
+    /**
+     * Gets the literal message type if configured.
+     */
+    private getLiteralMessageType;
+    /**
+     * Validates that multiple schemas can be properly mapped at registration time.
+     */
+    private validateMultipleSchemas;
+    private resolveSchemaMap;
+    private resolveDefinitionMap;
 }

package/dist/queues/MessageSchemaContainer.js

@@ -1,41 +1,149 @@
+import { extractMessageTypeFromSchema, isMessageTypeLiteralConfig, isMessageTypePathConfig, isMessageTypeResolverFnConfig, resolveMessageType, } from "./MessageTypeResolver.js";
 const DEFAULT_SCHEMA_KEY = Symbol('NO_MESSAGE_TYPE');
 export class MessageSchemaContainer {
     messageDefinitions;
     messageSchemas;
-    messageTypeField;
+    messageTypeResolver;
     constructor(options) {
-        this.messageTypeField = options.messageTypeField;
-        this.messageSchemas = this.resolveMap(options.messageSchemas);
-        this.messageDefinitions = this.resolveMap(options.messageDefinitions ?? []);
+        this.messageTypeResolver = options.messageTypeResolver;
+        this.messageSchemas = this.resolveSchemaMap(options.messageSchemas);
+        this.messageDefinitions = this.resolveDefinitionMap(options.messageDefinitions ?? []);
     }
+    /**
+     * Resolves the schema for a message based on its type.
+     *
+     * @param message - The parsed message data
+     * @param attributes - Optional message-level attributes (e.g., PubSub attributes)
+     * @returns Either an error or the resolved schema
+     */
     resolveSchema(
     // biome-ignore lint/suspicious/noExplicitAny: This is expected
-    message) {
-        const messageType = this.messageTypeField ? message[this.messageTypeField] : undefined;
-        const schema = this.messageSchemas[messageType ?? DEFAULT_SCHEMA_KEY];
+    message, attributes) {
+        // If no resolver configured, use the single default schema
+        if (!this.messageTypeResolver) {
+            const schema = this.messageSchemas[DEFAULT_SCHEMA_KEY];
+            if (!schema) {
+                return {
+                    error: new Error('No messageTypeResolver configured and no default schema available'),
+                };
+            }
+            return { result: schema };
+        }
+        let messageType;
+        try {
+            messageType = this.resolveMessageTypeFromData(message, attributes);
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e : new Error(String(e)) };
+        }
+        const schema = this.messageSchemas[messageType];
         if (!schema) {
             return {
-                error: new Error(`Unsupported message type: ${messageType ?? DEFAULT_SCHEMA_KEY.toString()}`),
+                error: new Error(`Unsupported message type: ${messageType}`),
             };
         }
         return { result: schema };
     }
-    resolveMap(array) {
+    /**
+     * Resolves message type from message data and optional attributes.
+     * Only called when messageTypeResolver is configured.
+     */
+    resolveMessageTypeFromData(messageData, messageAttributes) {
+        // This method is only called after checking messageTypeResolver exists in resolveSchema
+        const resolver = this.messageTypeResolver;
+        const context = { messageData, messageAttributes };
+        return resolveMessageType(resolver, context);
+    }
+    /**
+     * Gets the field path used for extracting message type from schemas during registration.
+     * Returns undefined for literal or custom resolver modes.
+     */
+    getMessageTypePathForSchema() {
+        if (this.messageTypeResolver && isMessageTypePathConfig(this.messageTypeResolver)) {
+            return this.messageTypeResolver.messageTypePath;
+        }
+        // For literal or custom resolver, we don't extract type from schema
+        return undefined;
+    }
+    /**
+     * Gets the literal message type if configured.
+     */
+    getLiteralMessageType() {
+        if (this.messageTypeResolver && isMessageTypeLiteralConfig(this.messageTypeResolver)) {
+            return this.messageTypeResolver.literal;
+        }
+        return undefined;
+    }
+    /**
+     * Validates that multiple schemas can be properly mapped at registration time.
+     */
+    validateMultipleSchemas(schemaCount) {
+        if (schemaCount <= 1)
+            return;
+        if (!this.messageTypeResolver) {
+            throw new Error('Multiple schemas require messageTypeResolver to be configured. ' +
+                'Use messageTypePath config (to extract types from schema literals) or literal config.');
+        }
+        // Custom resolver function cannot be used with multiple schemas because
+        // we can't know what types it will return until runtime.
+        if (isMessageTypeResolverFnConfig(this.messageTypeResolver)) {
+            throw new Error('Custom resolver function cannot be used with multiple schemas. ' +
+                'The resolver works for runtime type resolution, but at registration time ' +
+                'we cannot determine which schema corresponds to which type. ' +
+                'Use messageTypePath config (to extract types from schema literals) or register only a single schema.');
+        }
+    }
+    resolveSchemaMap(entries) {
         const result = {};
-        for (const item of array) {
+        this.validateMultipleSchemas(entries.length);
+        const literalType = this.getLiteralMessageType();
+        const messageTypePath = this.getMessageTypePathForSchema();
+        for (const entry of entries) {
             let type;
-            if (this.messageTypeField) {
-                type =
-                    'publisherSchema' in item
-                        ? // @ts-expect-error
-                            item.publisherSchema?.shape[this.messageTypeField]?.value
-                        : // @ts-expect-error
-                            item.shape?.[this.messageTypeField]?.value;
+            // Priority 1: Explicit messageType on the entry
+            if (entry.messageType) {
+                type = entry.messageType;
             }
+            // Priority 2: Literal type from resolver config (same for all schemas)
+            else if (literalType) {
+                type = literalType;
+            }
+            // Priority 3: Extract type from schema shape using the field path
+            else if (messageTypePath) {
+                // @ts-expect-error - ZodSchema has shape property at runtime
+                type = extractMessageTypeFromSchema(entry.schema, messageTypePath);
+            }
+            // If no type extracted, use DEFAULT_SCHEMA_KEY (single schema fallback)
             const key = type ?? DEFAULT_SCHEMA_KEY;
             if (result[key])
                 throw new Error(`Duplicate schema for type: ${key.toString()}`);
-            result[key] = item;
+            result[key] = entry.schema;
+        }
+        return result;
+    }
+    resolveDefinitionMap(entries) {
+        const result = {};
+        const literalType = this.getLiteralMessageType();
+        const messageTypePath = this.getMessageTypePathForSchema();
+        for (const entry of entries) {
+            let type;
+            // Priority 1: Explicit messageType on the entry
+            if (entry.messageType) {
+                type = entry.messageType;
+            }
+            // Priority 2: Literal type from resolver config (same for all definitions)
+            else if (literalType) {
+                type = literalType;
+            }
+            // Priority 3: Extract type from definition's publisherSchema using the field path
+            else if (messageTypePath) {
+                type = extractMessageTypeFromSchema(entry.definition.publisherSchema, messageTypePath);
+            }
+            // If no type extracted, use DEFAULT_SCHEMA_KEY (single definition fallback)
+            const key = type ?? DEFAULT_SCHEMA_KEY;
+            if (result[key])
+                throw new Error(`Duplicate definition for type: ${key.toString()}`);
+            result[key] = entry.definition;
         }
         return result;
     }

package/dist/queues/MessageSchemaContainer.js.map

@@ -1 +1 @@
-{"version":3,"file":"MessageSchemaContainer.js","sourceRoot":"","sources":["../../lib/queues/MessageSchemaContainer.ts"],"names":[],"mappings":"AAUA,MAAM,kBAAkB,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAA;AAEpD,MAAM,OAAO,sBAAsB;IACjB,kBAAkB,CAAgD;IAEjE,cAAc,CAA2D;IACzE,gBAAgB,CAAS;IAE1C,YAAY,OAA6D;QACvE,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAA;QAChD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAA;QAC7D,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAA;IAC7E,CAAC;IAEM,aAAa;IAClB,+DAA+D;IAC/D,OAA4B;QAE5B,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAEtF,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,IAAI,kBAAkB,CAAC,CAAA;QACrE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,KAAK,EAAE,IAAI,KAAK,CACd,6BAA6B,WAAW,IAAI,kBAAkB,CAAC,QAAQ,EAAE,EAAE,CAC5E;aACF,CAAA;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA;IAC3B,CAAC;IAEO,UAAU,CAChB,KAAmB;QAEnB,MAAM,MAAM,GAA+B,EAAE,CAAA;QAE7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAwB,CAAA;YAE5B,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC1B,IAAI;oBACF,iBAAiB,IAAI,IAAI;wBACvB,CAAC,CAAC,mBAAmB;4BACnB,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,KAAK;wBAC3D,CAAC,CAAC,mBAAmB;4BACnB,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,KAAK,CAAA;YAClD,CAAC;YAED,MAAM,GAAG,GAAG,IAAI,IAAI,kBAAkB,CAAA;YACtC,IAAI,MAAM,CAAC,GAAG,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;YAEhF,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;QACpB,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}
+{"version":3,"file":"MessageSchemaContainer.js","sourceRoot":"","sources":["../../lib/queues/MessageSchemaContainer.ts"],"names":[],"mappings":"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"}

package/dist/queues/MessageTypeResolver.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Context passed to a custom message type resolver function.
+ * Contains both the parsed message data and any message-level attributes/metadata.
+ */
+export type MessageTypeResolverContext = {
+    /**
+     * The parsed/decoded message body (e.g., JSON-parsed data field in PubSub)
+     */
+    messageData: unknown;
+    /**
+     * Message-level attributes/metadata (e.g., PubSub message attributes, SQS message attributes)
+     * This is where Cloud Storage notifications put eventType, for example.
+     */
+    messageAttributes?: Record<string, unknown>;
+};
+/**
+ * Function that extracts the message type from a message.
+ * Used for routing messages to appropriate handlers and schemas.
+ *
+ * The function MUST return a valid message type string. If the type cannot be
+ * determined, the function should either:
+ * - Return a default type (e.g., 'unknown' or a fallback handler type)
+ * - Throw an error with a descriptive message
+ *
+ * @example
+ * // Extract from attributes (e.g., Cloud Storage notifications)
+ * const resolver: MessageTypeResolverFn = ({ messageAttributes }) => {
+ *   const eventType = messageAttributes?.eventType as string | undefined
+ *   if (!eventType) {
+ *     throw new Error('eventType attribute is required')
+ *   }
+ *   return eventType
+ * }
+ *
+ * @example
+ * // Extract from nested data with fallback
+ * const resolver: MessageTypeResolverFn = ({ messageData }) => {
+ *   const data = messageData as { metadata?: { eventName?: string } }
+ *   return data.metadata?.eventName ?? 'default.event'
+ * }
+ */
+export type MessageTypeResolverFn = (context: MessageTypeResolverContext) => string;
+/**
+ * Configuration for resolving message types.
+ *
+ * Three modes are supported:
+ *
+ * 1. **Field path** (string): Extract type from a field in the message using dot notation.
+ *    Supports nested paths like 'metadata.type' or 'detail.eventType'.
+ *    @example { messageTypePath: 'type' } // extracts from message.type
+ *    @example { messageTypePath: 'detail-type' } // for EventBridge events
+ *    @example { messageTypePath: 'metadata.eventType' } // nested path
+ *
+ * 2. **Constant type** (object with `literal`): All messages are treated as the same type.
+ *    Useful when a subscription/queue only receives one type of message.
+ *    @example { literal: 'order.created' }
+ *
+ * 3. **Custom resolver** (object with `resolver`): Full flexibility via callback function.
+ *    Use when type needs to be extracted from attributes or requires transformation.
+ *    @example
+ *    {
+ *      resolver: ({ messageAttributes }) => messageAttributes?.eventType as string
+ *    }
+ *
+ * @example
+ * // Cloud Storage notifications via PubSub - type is in attributes
+ * const config: MessageTypeResolverConfig = {
+ *   resolver: ({ messageAttributes }) => {
+ *     const eventType = messageAttributes?.eventType as string | undefined
+ *     if (!eventType) {
+ *       throw new Error('eventType attribute is required for Cloud Storage notifications')
+ *     }
+ *     // Optionally map to your internal event types
+ *     if (eventType === 'OBJECT_FINALIZE') return 'storage.object.created'
+ *     if (eventType === 'OBJECT_DELETE') return 'storage.object.deleted'
+ *     return eventType
+ *   }
+ * }
+ *
+ * @example
+ * // CloudEvents format - type might be in envelope or data
+ * const config: MessageTypeResolverConfig = {
+ *   resolver: ({ messageData, messageAttributes }) => {
+ *     // Check for CloudEvents binary mode (type in attributes)
+ *     if (messageAttributes?.['ce-type']) {
+ *       return messageAttributes['ce-type'] as string
+ *     }
+ *     // Fall back to type in message data
+ *     const data = messageData as { type?: string }
+ *     if (!data.type) {
+ *       throw new Error('Message type not found in CloudEvents envelope or message data')
+ *     }
+ *     return data.type
+ *   }
+ * }
+ */
+export type MessageTypeResolverConfig = {
+    /**
+     * Path to the field containing the message type.
+     * Supports dot notation for nested paths (e.g., 'metadata.type', 'detail.eventType').
+     */
+    messageTypePath: string;
+} | {
+    /**
+     * Constant message type for all messages.
+     * Use when all messages in a queue/subscription are of the same type.
+     */
+    literal: string;
+} | {
+    /**
+     * Custom function to extract message type from message data and/or attributes.
+     * Provides full flexibility for complex routing scenarios.
+     */
+    resolver: MessageTypeResolverFn;
+};
+/**
+ * Type guard to check if config uses field path mode
+ */
+export declare function isMessageTypePathConfig(config: MessageTypeResolverConfig): config is {
+    messageTypePath: string;
+};
+/**
+ * Type guard to check if config uses literal/constant mode
+ */
+export declare function isMessageTypeLiteralConfig(config: MessageTypeResolverConfig): config is {
+    literal: string;
+};
+/**
+ * Type guard to check if config uses custom resolver mode
+ */
+export declare function isMessageTypeResolverFnConfig(config: MessageTypeResolverConfig): config is {
+    resolver: MessageTypeResolverFn;
+};
+/**
+ * Resolves message type using the provided configuration.
+ *
+ * @param config - The resolver configuration
+ * @param context - Context containing message data and attributes
+ * @returns The resolved message type
+ * @throws Error if message type cannot be resolved (for messageTypePath mode)
+ */
+export declare function resolveMessageType(config: MessageTypeResolverConfig, context: MessageTypeResolverContext): string;
+/**
+ * Extracts message type from schema definition using the field path.
+ * Used during handler/schema registration to build the routing map.
+ * Supports dot notation for nested paths (e.g., 'metadata.type').
+ *
+ * @param schema - Zod schema with shape property
+ * @param messageTypePath - Path to the field containing the type literal (supports dot notation)
+ * @returns The literal type value from the schema, or undefined if field doesn't exist or isn't a literal
+ */
+export declare function extractMessageTypeFromSchema(schema: {
+    shape?: Record<string, any>;
+}, messageTypePath: string | undefined): string | undefined;

package/dist/queues/MessageTypeResolver.js

@@ -0,0 +1,82 @@
+import { getProperty } from 'dot-prop';
+/**
+ * Type guard to check if config uses field path mode
+ */
+export function isMessageTypePathConfig(config) {
+    return 'messageTypePath' in config;
+}
+/**
+ * Type guard to check if config uses literal/constant mode
+ */
+export function isMessageTypeLiteralConfig(config) {
+    return 'literal' in config;
+}
+/**
+ * Type guard to check if config uses custom resolver mode
+ */
+export function isMessageTypeResolverFnConfig(config) {
+    return 'resolver' in config;
+}
+/**
+ * Resolves message type using the provided configuration.
+ *
+ * @param config - The resolver configuration
+ * @param context - Context containing message data and attributes
+ * @returns The resolved message type
+ * @throws Error if message type cannot be resolved (for messageTypePath mode)
+ */
+export function resolveMessageType(config, context) {
+    if (isMessageTypeLiteralConfig(config)) {
+        return config.literal;
+    }
+    if (isMessageTypePathConfig(config)) {
+        const rawMessageType = getProperty(context.messageData, config.messageTypePath);
+        if (rawMessageType === undefined || rawMessageType === null) {
+            throw new Error(`Unable to resolve message type: path '${config.messageTypePath}' not found in message data`);
+        }
+        if (typeof rawMessageType !== 'string') {
+            throw new Error(`Unable to resolve message type: path '${config.messageTypePath}' contains a non-string value (got ${typeof rawMessageType})`);
+        }
+        return rawMessageType;
+    }
+    // Custom resolver function - must return a string (user handles errors/defaults)
+    return config.resolver(context);
+}
+/**
+ * Extracts message type from schema definition using the field path.
+ * Used during handler/schema registration to build the routing map.
+ * Supports dot notation for nested paths (e.g., 'metadata.type').
+ *
+ * @param schema - Zod schema with shape property
+ * @param messageTypePath - Path to the field containing the type literal (supports dot notation)
+ * @returns The literal type value from the schema, or undefined if field doesn't exist or isn't a literal
+ */
+export function extractMessageTypeFromSchema(
+// biome-ignore lint/suspicious/noExplicitAny: Schema shape can be any
+schema, messageTypePath) {
+    if (!messageTypePath) {
+        return undefined;
+    }
+    const pathParts = messageTypePath.split('.');
+    // biome-ignore lint/suspicious/noExplicitAny: Schema shape can be any
+    let current = schema;
+    for (const part of pathParts) {
+        if (!current?.shape) {
+            return undefined;
+        }
+        current = current.shape[part];
+        if (!current) {
+            return undefined;
+        }
+    }
+    // Check if the final field has a literal value (z.literal() creates a field with .value)
+    if (!('value' in current)) {
+        return undefined;
+    }
+    const value = current.value;
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    return value;
+}
+//# sourceMappingURL=MessageTypeResolver.js.map

package/dist/queues/MessageTypeResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageTypeResolver.js","sourceRoot":"","sources":["../../lib/queues/MessageTypeResolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AA2HtC;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAiC;IAEjC,OAAO,iBAAiB,IAAI,MAAM,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAiC;IAEjC,OAAO,SAAS,IAAI,MAAM,CAAA;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAiC;IAEjC,OAAO,UAAU,IAAI,MAAM,CAAA;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAiC,EACjC,OAAmC;IAEnC,IAAI,0BAA0B,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,OAAO,CAAA;IACvB,CAAC;IAED,IAAI,uBAAuB,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,eAAe,CAAC,CAAA;QAC/E,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;YAC5D,MAAM,IAAI,KAAK,CACb,yCAAyC,MAAM,CAAC,eAAe,6BAA6B,CAC7F,CAAA;QACH,CAAC;QACD,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,yCAAyC,MAAM,CAAC,eAAe,sCAAsC,OAAO,cAAc,GAAG,CAC9H,CAAA;QACH,CAAC;QACD,OAAO,cAAc,CAAA;IACvB,CAAC;IAED,iFAAiF;IACjF,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B;AAC1C,sEAAsE;AACtE,MAAuC,EACvC,eAAmC;IAEnC,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC5C,sEAAsE;IACtE,IAAI,OAAO,GAAQ,MAAM,CAAA;IAEzB,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;YACpB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED,yFAAyF;IACzF,IAAI,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/types/MessageQueueTypes.d.ts

@@ -1,4 +1,4 @@
-import type { CommonLogger, TransactionObservabilityManager } from '@lokalise/node-core';
+import type { CommonLogger, ErrorReporter, TransactionObservabilityManager } from '@lokalise/node-core';
 import type { ZodSchema } from 'zod/v4';
 import type { PublicHandlerSpy } from '../queues/HandlerSpy.ts';
 export interface QueueConsumer {
@@ -28,5 +28,6 @@ export interface AsyncPublisher<MessagePayloadType extends object, MessageOption
 export type { TransactionObservabilityManager };
 export type ExtraParams = {
     logger?: CommonLogger;
+    errorReporter?: ErrorReporter;
 };
 export type SchemaMap<SupportedMessageTypes extends string> = Record<SupportedMessageTypes, ZodSchema<any>>;