@hotmeshio/hotmesh 0.10.2 → 0.12.0

package/build/services/store/index.d.ts

@@ -91,5 +91,57 @@ declare abstract class StoreService<Provider extends ProviderClient, Transaction
     abstract setThrottleRate(options: ThrottleOptions): Promise<void>;
     abstract getThrottleRates(): Promise<StringStringType>;
     abstract getThrottleRate(topic: string): Promise<number>;
+    /**
+     * Fetch activity inputs for a workflow. Used by the exporter to enrich
+     * timeline events with activity arguments.
+     *
+     * @param workflowId - The workflow ID
+     * @param symbolField - The compressed symbol field for activity arguments
+     * @returns Map of job_id -> parsed input arguments and activityName:index -> parsed inputs
+     */
+    getActivityInputs?(workflowId: string, symbolField: string): Promise<{
+        byJobId: Map<string, any>;
+        byNameIndex: Map<string, any>;
+    }>;
+    /**
+     * Fetch child workflow inputs in batch. Used by the exporter to enrich
+     * child workflow events with their arguments.
+     *
+     * @param childJobKeys - Array of child job keys to fetch
+     * @param symbolField - The compressed symbol field for workflow arguments
+     * @returns Map of child_workflow_id -> parsed input arguments
+     */
+    getChildWorkflowInputs?(childJobKeys: string[], symbolField: string): Promise<Map<string, any>>;
+    /**
+     * Fetch stream message history for a job from worker_streams.
+     * Returns raw activity input/output data from soft-deleted messages.
+     *
+     * @param jobId - The job ID (metadata.jid in stream messages)
+     * @param options - Optional filters for activity or message types
+     * @returns Array of stream history entries ordered by creation time
+     */
+    getStreamHistory?(jobId: string, options?: {
+        activity?: string;
+        types?: string[];
+    }): Promise<import('../../types/exporter').StreamHistoryEntry[]>;
+    /**
+     * Fetch job record and attributes by key. Used by the exporter to
+     * reconstruct execution history for expired jobs.
+     *
+     * @param jobKey - The job key (e.g., "hmsh:durable:j:workflowId")
+     * @returns Job row and all attributes
+     */
+    getJobByKeyDirect?(jobKey: string): Promise<{
+        job: {
+            id: string;
+            key: string;
+            status: number;
+            created_at: Date;
+            updated_at: Date;
+            expired_at?: Date;
+            is_live: boolean;
+        };
+        attributes: Record<string, string>;
+    }>;
 }
 export { StoreService };

package/build/services/store/providers/postgres/exporter-sql.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SQL queries for exporter enrichment (Postgres provider).
+ * These queries support the exporter's input enrichment and direct query features.
+ */
+/**
+ * Fetch job record by key.
+ */
+export declare const GET_JOB_BY_KEY = "\n  SELECT id, key, status, created_at, updated_at, expired_at, is_live\n  FROM {schema}.jobs\n  WHERE key = $1\n  LIMIT 1\n";
+/**
+ * Fetch all attributes for a job.
+ */
+export declare const GET_JOB_ATTRIBUTES = "\n  SELECT field, value\n  FROM {schema}.jobs_attributes\n  WHERE job_id = $1\n  ORDER BY field\n";
+/**
+ * Fetch activity inputs for a workflow.
+ * Matches all activity jobs for the given workflow and extracts their input arguments.
+ */
+export declare const GET_ACTIVITY_INPUTS = "\n  SELECT j.key, ja.value\n  FROM {schema}.jobs j\n  JOIN {schema}.jobs_attributes ja ON ja.job_id = j.id\n  WHERE j.key LIKE $1\n    AND ja.field = $2\n";
+/**
+ * Fetch all worker stream messages for a job AND its child activities.
+ * Child activity jobs use the pattern: -{parentJobId}-$activityName-N
+ * Uses the partial index on (jid, created_at) WHERE jid != '' for efficiency.
+ * Includes both active and expired messages for full execution history.
+ */
+export declare const GET_STREAM_HISTORY_BY_JID = "\n  SELECT\n    id, jid, aid, dad, msg_type, topic, workflow_name,\n    message, created_at, expired_at\n  FROM {schema}.worker_streams\n  WHERE jid = $1 OR jid LIKE '-' || $1 || '-%'\n  ORDER BY created_at, id\n";
+/**
+ * Fetch worker stream messages for a job filtered by message type.
+ * Includes child activity messages.
+ */
+export declare const GET_STREAM_HISTORY_BY_JID_AND_TYPE = "\n  SELECT\n    id, jid, aid, dad, msg_type, topic, workflow_name,\n    message, created_at, expired_at\n  FROM {schema}.worker_streams\n  WHERE (jid = $1 OR jid LIKE '-' || $1 || '-%')\n    AND msg_type = ANY($2::text[])\n  ORDER BY created_at, id\n";
+/**
+ * Fetch worker stream messages for a job filtered by activity ID.
+ * Includes child activity messages.
+ */
+export declare const GET_STREAM_HISTORY_BY_JID_AND_AID = "\n  SELECT\n    id, jid, aid, dad, msg_type, topic, workflow_name,\n    message, created_at, expired_at\n  FROM {schema}.worker_streams\n  WHERE (jid = $1 OR jid LIKE '-' || $1 || '-%')\n    AND aid = $2\n  ORDER BY created_at, id\n";
+/**
+ * Fetch child workflow inputs in batch.
+ * Uses parameterized IN clause for exact-match efficiency.
+ * Note: This query template must be built dynamically with the correct number of placeholders.
+ */
+export declare function buildChildWorkflowInputsQuery(childCount: number, schema: string): string;

package/build/services/store/providers/postgres/exporter-sql.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * SQL queries for exporter enrichment (Postgres provider).
+ * These queries support the exporter's input enrichment and direct query features.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChildWorkflowInputsQuery = exports.GET_STREAM_HISTORY_BY_JID_AND_AID = exports.GET_STREAM_HISTORY_BY_JID_AND_TYPE = exports.GET_STREAM_HISTORY_BY_JID = exports.GET_ACTIVITY_INPUTS = exports.GET_JOB_ATTRIBUTES = exports.GET_JOB_BY_KEY = void 0;
+/**
+ * Fetch job record by key.
+ */
+exports.GET_JOB_BY_KEY = `
+  SELECT id, key, status, created_at, updated_at, expired_at, is_live
+  FROM {schema}.jobs
+  WHERE key = $1
+  LIMIT 1
+`;
+/**
+ * Fetch all attributes for a job.
+ */
+exports.GET_JOB_ATTRIBUTES = `
+  SELECT field, value
+  FROM {schema}.jobs_attributes
+  WHERE job_id = $1
+  ORDER BY field
+`;
+/**
+ * Fetch activity inputs for a workflow.
+ * Matches all activity jobs for the given workflow and extracts their input arguments.
+ */
+exports.GET_ACTIVITY_INPUTS = `
+  SELECT j.key, ja.value
+  FROM {schema}.jobs j
+  JOIN {schema}.jobs_attributes ja ON ja.job_id = j.id
+  WHERE j.key LIKE $1
+    AND ja.field = $2
+`;
+/**
+ * Fetch all worker stream messages for a job AND its child activities.
+ * Child activity jobs use the pattern: -{parentJobId}-$activityName-N
+ * Uses the partial index on (jid, created_at) WHERE jid != '' for efficiency.
+ * Includes both active and expired messages for full execution history.
+ */
+exports.GET_STREAM_HISTORY_BY_JID = `
+  SELECT
+    id, jid, aid, dad, msg_type, topic, workflow_name,
+    message, created_at, expired_at
+  FROM {schema}.worker_streams
+  WHERE jid = $1 OR jid LIKE '-' || $1 || '-%'
+  ORDER BY created_at, id
+`;
+/**
+ * Fetch worker stream messages for a job filtered by message type.
+ * Includes child activity messages.
+ */
+exports.GET_STREAM_HISTORY_BY_JID_AND_TYPE = `
+  SELECT
+    id, jid, aid, dad, msg_type, topic, workflow_name,
+    message, created_at, expired_at
+  FROM {schema}.worker_streams
+  WHERE (jid = $1 OR jid LIKE '-' || $1 || '-%')
+    AND msg_type = ANY($2::text[])
+  ORDER BY created_at, id
+`;
+/**
+ * Fetch worker stream messages for a job filtered by activity ID.
+ * Includes child activity messages.
+ */
+exports.GET_STREAM_HISTORY_BY_JID_AND_AID = `
+  SELECT
+    id, jid, aid, dad, msg_type, topic, workflow_name,
+    message, created_at, expired_at
+  FROM {schema}.worker_streams
+  WHERE (jid = $1 OR jid LIKE '-' || $1 || '-%')
+    AND aid = $2
+  ORDER BY created_at, id
+`;
+/**
+ * Fetch child workflow inputs in batch.
+ * Uses parameterized IN clause for exact-match efficiency.
+ * Note: This query template must be built dynamically with the correct number of placeholders.
+ */
+function buildChildWorkflowInputsQuery(childCount, schema) {
+    const placeholders = Array.from({ length: childCount }, (_, i) => `$${i + 1}`).join(',');
+    return `
+    SELECT j.key, ja.value
+    FROM ${schema}.jobs j
+    JOIN ${schema}.jobs_attributes ja ON ja.job_id = j.id
+    WHERE j.key IN (${placeholders})
+      AND ja.field = $${childCount + 1}
+  `;
+}
+exports.buildChildWorkflowInputsQuery = buildChildWorkflowInputsQuery;

package/build/services/store/providers/postgres/kvtables.js

@@ -221,6 +221,12 @@ const KVTables = (context) => ({
                         await client.query(`
               CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_pruned_at
               ON ${fullTableName} (pruned_at) WHERE pruned_at IS NULL;
+            `);
+                        // Index for paginated entity listing with sort (dashboard entity queries)
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_entity_created
+              ON ${fullTableName} (entity, created_at DESC)
+              WHERE entity IS NOT NULL;
             `);
                         // Create function to update is_live flag in the schema
                         await client.query(`

package/build/services/store/providers/postgres/postgres.d.ts

@@ -194,5 +194,47 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
      * Enhanced shouldScout that can handle notifications
      */
     shouldScout(): Promise<boolean>;
+    /**
+     * Fetch activity inputs for a workflow. Used by the exporter to enrich
+     * timeline events with activity arguments.
+     */
+    getActivityInputs(workflowId: string, symbolField: string): Promise<{
+        byJobId: Map<string, any>;
+        byNameIndex: Map<string, any>;
+    }>;
+    /**
+     * Fetch child workflow inputs in batch. Used by the exporter to enrich
+     * child workflow events with their arguments.
+     */
+    getChildWorkflowInputs(childJobKeys: string[], symbolField: string): Promise<Map<string, any>>;
+    /**
+     * Fetch job record and attributes by key. Used by the exporter to
+     * reconstruct execution history for expired jobs.
+     */
+    getJobByKeyDirect(jobKey: string): Promise<{
+        job: {
+            id: string;
+            key: string;
+            status: number;
+            created_at: Date;
+            updated_at: Date;
+            expired_at?: Date;
+            is_live: boolean;
+        };
+        attributes: Record<string, string>;
+    }>;
+    /**
+     * Fetch stream message history for a job from worker_streams.
+     * Returns raw activity input/output data from soft-deleted messages.
+     */
+    getStreamHistory(jobId: string, options?: {
+        activity?: string;
+        types?: string[];
+    }): Promise<import('../../../../types/exporter').StreamHistoryEntry[]>;
+    /**
+     * Parse a HotMesh-encoded value string.
+     * Values may be prefixed with `/s` (JSON), `/d` (number), `/t` or `/f` (boolean), `/n` (null).
+     */
+    private parseHmshValue;
 }
 export { PostgresStoreService };

package/build/services/store/providers/postgres/postgres.js

@@ -1284,5 +1284,156 @@ class PostgresStoreService extends __1.StoreService {
         }
         return false;
     }
+    // ── Exporter queries ───────────────────────────────────────────────────────
+    /**
+     * Fetch activity inputs for a workflow. Used by the exporter to enrich
+     * timeline events with activity arguments.
+     */
+    async getActivityInputs(workflowId, symbolField) {
+        const { GET_ACTIVITY_INPUTS } = await Promise.resolve().then(() => __importStar(require('./exporter-sql')));
+        const schemaName = this.kvsql().safeName(this.appId);
+        const sql = GET_ACTIVITY_INPUTS.replace(/{schema}/g, schemaName);
+        const jobKeyPattern = `hmsh:${this.appId}:j:-${workflowId}-%`;
+        const result = await this.pgClient.query(sql, [jobKeyPattern, symbolField]);
+        const byJobId = new Map();
+        const byNameIndex = new Map();
+        for (const row of result.rows) {
+            const jobKey = row.key;
+            const jobId = jobKey.replace(`hmsh:${this.appId}:j:`, '');
+            try {
+                const parsed = this.parseHmshValue(row.value);
+                byJobId.set(jobId, parsed);
+                // Extract activityName and executionIndex from job_id
+                // Format: -workflowId-$activityName-executionIndex
+                const match = jobId.match(/\$([^-]+)-(\d+)$/);
+                if (match) {
+                    const activityName = match[1];
+                    const executionIndex = match[2];
+                    byNameIndex.set(`${activityName}:${executionIndex}`, parsed);
+                }
+            }
+            catch {
+                // Skip unparseable values
+            }
+        }
+        return { byJobId, byNameIndex };
+    }
+    /**
+     * Fetch child workflow inputs in batch. Used by the exporter to enrich
+     * child workflow events with their arguments.
+     */
+    async getChildWorkflowInputs(childJobKeys, symbolField) {
+        if (childJobKeys.length === 0) {
+            return new Map();
+        }
+        const { buildChildWorkflowInputsQuery } = await Promise.resolve().then(() => __importStar(require('./exporter-sql')));
+        const schemaName = this.kvsql().safeName(this.appId);
+        const sql = buildChildWorkflowInputsQuery(childJobKeys.length, schemaName);
+        const result = await this.pgClient.query(sql, [...childJobKeys, symbolField]);
+        const childInputMap = new Map();
+        for (const row of result.rows) {
+            const jobKey = row.key;
+            const childId = jobKey.replace(`hmsh:${this.appId}:j:`, '');
+            try {
+                const parsed = this.parseHmshValue(row.value);
+                childInputMap.set(childId, parsed);
+            }
+            catch {
+                // Skip unparseable values
+            }
+        }
+        return childInputMap;
+    }
+    /**
+     * Fetch job record and attributes by key. Used by the exporter to
+     * reconstruct execution history for expired jobs.
+     */
+    async getJobByKeyDirect(jobKey) {
+        const { GET_JOB_BY_KEY, GET_JOB_ATTRIBUTES } = await Promise.resolve().then(() => __importStar(require('./exporter-sql')));
+        const schemaName = this.kvsql().safeName(this.appId);
+        const jobSql = GET_JOB_BY_KEY.replace(/{schema}/g, schemaName);
+        const jobResult = await this.pgClient.query(jobSql, [jobKey]);
+        if (jobResult.rows.length === 0) {
+            throw new Error(`No job found for key "${jobKey}"`);
+        }
+        const job = jobResult.rows[0];
+        const attrSql = GET_JOB_ATTRIBUTES.replace(/{schema}/g, schemaName);
+        const attrResult = await this.pgClient.query(attrSql, [job.id]);
+        const attributes = {};
+        for (const row of attrResult.rows) {
+            attributes[row.field] = row.value;
+        }
+        return { job, attributes };
+    }
+    /**
+     * Fetch stream message history for a job from worker_streams.
+     * Returns raw activity input/output data from soft-deleted messages.
+     */
+    async getStreamHistory(jobId, options) {
+        const { GET_STREAM_HISTORY_BY_JID, GET_STREAM_HISTORY_BY_JID_AND_TYPE, GET_STREAM_HISTORY_BY_JID_AND_AID, } = await Promise.resolve().then(() => __importStar(require('./exporter-sql')));
+        const schemaName = this.kvsql().safeName(this.appId);
+        let sql;
+        let params;
+        if (options?.activity) {
+            sql = GET_STREAM_HISTORY_BY_JID_AND_AID.replace(/{schema}/g, schemaName);
+            params = [jobId, options.activity];
+        }
+        else if (options?.types?.length) {
+            sql = GET_STREAM_HISTORY_BY_JID_AND_TYPE.replace(/{schema}/g, schemaName);
+            params = [jobId, options.types];
+        }
+        else {
+            sql = GET_STREAM_HISTORY_BY_JID.replace(/{schema}/g, schemaName);
+            params = [jobId];
+        }
+        const result = await this.pgClient.query(sql, params);
+        return result.rows.map((row) => {
+            let parsed = {};
+            try {
+                parsed = JSON.parse(row.message);
+            }
+            catch {
+                // message may not be valid JSON
+            }
+            return {
+                id: parseInt(row.id),
+                jid: row.jid,
+                aid: row.aid,
+                dad: row.dad,
+                msg_type: row.msg_type,
+                topic: row.topic,
+                workflow_name: row.workflow_name,
+                data: parsed.data || {},
+                status: parsed.status,
+                code: parsed.code,
+                created_at: row.created_at instanceof Date
+                    ? row.created_at.toISOString()
+                    : String(row.created_at),
+                expired_at: row.expired_at
+                    ? (row.expired_at instanceof Date
+                        ? row.expired_at.toISOString()
+                        : String(row.expired_at))
+                    : undefined,
+            };
+        });
+    }
+    /**
+     * Parse a HotMesh-encoded value string.
+     * Values may be prefixed with `/s` (JSON), `/d` (number), `/t` or `/f` (boolean), `/n` (null).
+     */
+    parseHmshValue(raw) {
+        if (typeof raw !== 'string')
+            return undefined;
+        const prefix = raw.slice(0, 2);
+        const rest = raw.slice(2);
+        switch (prefix) {
+            case '/t': return true;
+            case '/f': return false;
+            case '/d': return Number(rest);
+            case '/n': return null;
+            case '/s': return JSON.parse(rest);
+            default: return raw;
+        }
+    }
 }
 exports.PostgresStoreService = PostgresStoreService;

package/build/services/stream/index.d.ts

@@ -64,6 +64,7 @@ export declare abstract class StreamService<ClientProvider extends ProviderClien
         maxMessageSize: number;
         maxBatchSize: number;
     };
+    deadLetterMessages?(streamName: string, groupName: string, messageIds: string[]): Promise<number>;
     stopNotificationConsumer?(streamName: string, groupName: string): Promise<void>;
     cleanup?(): Promise<void>;
 }

package/build/services/stream/providers/postgres/kvtables.d.ts

@@ -1,3 +1,3 @@
 import { ILogger } from '../../../logger';
 export declare function deploySchema(streamClient: any, appId: string, logger: ILogger): Promise<void>;
-export declare function getNotificationChannelName(streamName: string, groupName: string): string;
+export declare function getNotificationChannelName(streamName: string, isEngine: boolean): string;