retold-data-service 2.0.13 → 2.0.16

package/source/services/integration-telemetry/IntegrationTelemetry-Command-Dashboard.js

@@ -0,0 +1,60 @@
+/**
+ * IntegrationTelemetry — Dashboard Routes
+ *
+ * GET  {prefix}/dashboard             — tenant dashboard summary
+ * GET  {prefix}/dashboard/corporate   — corporate dashboard (all tenants)
+ *
+ * @param {Object} pTelemetryService - The RetoldDataServiceIntegrationTelemetry instance
+ * @param {Object} pOratorServiceServer - The Orator ServiceServer instance
+ */
+module.exports = (pTelemetryService, pOratorServiceServer) =>
+{
+	let tmpPrefix = pTelemetryService.routePrefix;
+
+	// ────────────────────────────────────────────────────────────────
+	// GET /telemetry/dashboard
+	// Aggregated dashboard for a single tenant.
+	//
+	// Query params:
+	//   tenant_id  — required (defaults to service default)
+	// ────────────────────────────────────────────────────────────────
+	pOratorServiceServer.get(`${tmpPrefix}/dashboard`,
+		(pRequest, pResponse, fNext) =>
+		{
+			let tmpTenantID = pRequest.params.tenant_id || pTelemetryService.options.DefaultTenantID || 'default';
+
+			let tmpProvider = pTelemetryService.getStorageProvider();
+			tmpProvider.getDashboardSummary(tmpTenantID,
+				(pError, pDashboard) =>
+				{
+					if (pError)
+					{
+						pResponse.send(500, { Success: false, Error: `${pError}` });
+						return fNext();
+					}
+					pResponse.send(200, { Success: true, Dashboard: pDashboard });
+					return fNext();
+				});
+		});
+
+	// ────────────────────────────────────────────────────────────────
+	// GET /telemetry/dashboard/corporate
+	// Aggregated dashboard across all tenants.
+	// ────────────────────────────────────────────────────────────────
+	pOratorServiceServer.get(`${tmpPrefix}/dashboard/corporate`,
+		(pRequest, pResponse, fNext) =>
+		{
+			let tmpProvider = pTelemetryService.getStorageProvider();
+			tmpProvider.getCorporateDashboardSummary(
+				(pError, pDashboard) =>
+				{
+					if (pError)
+					{
+						pResponse.send(500, { Success: false, Error: `${pError}` });
+						return fNext();
+					}
+					pResponse.send(200, { Success: true, Dashboard: pDashboard });
+					return fNext();
+				});
+		});
+};

package/source/services/integration-telemetry/IntegrationTelemetry-Command-Integrations.js

@@ -0,0 +1,132 @@
+/**
+ * IntegrationTelemetry — Integration-Level Routes
+ *
+ * GET  {prefix}/integrations                              — list distinct integration names
+ * GET  {prefix}/integrations/:IntegrationName/runs        — runs filtered by integration
+ * GET  {prefix}/integrations/:IntegrationName/summary     — summary stats for an integration
+ *
+ * @param {Object} pTelemetryService - The RetoldDataServiceIntegrationTelemetry instance
+ * @param {Object} pOratorServiceServer - The Orator ServiceServer instance
+ */
+module.exports = (pTelemetryService, pOratorServiceServer) =>
+{
+	let tmpPrefix = pTelemetryService.routePrefix;
+
+	// ────────────────────────────────────────────────────────────────
+	// GET /telemetry/integrations
+	// List distinct integration names for a tenant.
+	//
+	// Query params:
+	//   tenant_id  — required (defaults to service default)
+	// ────────────────────────────────────────────────────────────────
+	pOratorServiceServer.get(`${tmpPrefix}/integrations`,
+		(pRequest, pResponse, fNext) =>
+		{
+			let tmpTenantID = pRequest.params.tenant_id || pTelemetryService.options.DefaultTenantID || 'default';
+
+			let tmpProvider = pTelemetryService.getStorageProvider();
+			tmpProvider.listRuns(tmpTenantID, { Limit: 10000 },
+				(pError, pRecords) =>
+				{
+					if (pError)
+					{
+						pResponse.send(500, { Success: false, Error: `${pError}` });
+						return fNext();
+					}
+
+					// Extract unique integration names
+					let tmpNames = {};
+					for (let i = 0; i < pRecords.length; i++)
+					{
+						let tmpName = pRecords[i].IntegrationName || 'Unknown';
+						if (!tmpNames[tmpName])
+						{
+							tmpNames[tmpName] = { Name: tmpName, RunCount: 0, LatestRun: null };
+						}
+						tmpNames[tmpName].RunCount++;
+						if (!tmpNames[tmpName].LatestRun || new Date(pRecords[i].StartedAt) > new Date(tmpNames[tmpName].LatestRun))
+						{
+							tmpNames[tmpName].LatestRun = pRecords[i].StartedAt;
+						}
+					}
+
+					let tmpIntegrations = Object.values(tmpNames);
+					tmpIntegrations.sort((a, b) => (b.LatestRun || '').localeCompare(a.LatestRun || ''));
+
+					pResponse.send(200,
+						{
+							Success: true,
+							TenantID: tmpTenantID,
+							Count: tmpIntegrations.length,
+							Integrations: tmpIntegrations
+						});
+					return fNext();
+				});
+		});
+
+	// ────────────────────────────────────────────────────────────────
+	// GET /telemetry/integrations/:IntegrationName/runs
+	// List runs filtered by a specific integration name.
+	//
+	// Query params:
+	//   tenant_id, limit, offset, outcome, from, to
+	// ────────────────────────────────────────────────────────────────
+	pOratorServiceServer.get(`${tmpPrefix}/integrations/:IntegrationName/runs`,
+		(pRequest, pResponse, fNext) =>
+		{
+			let tmpTenantID = pRequest.params.tenant_id || pTelemetryService.options.DefaultTenantID || 'default';
+			let tmpIntegrationName = decodeURIComponent(pRequest.params.IntegrationName);
+			let tmpOptions = (
+				{
+					Limit: pRequest.params.limit,
+					Offset: pRequest.params.offset,
+					Outcome: pRequest.params.outcome,
+					From: pRequest.params.from,
+					To: pRequest.params.to
+				});
+
+			let tmpProvider = pTelemetryService.getStorageProvider();
+			tmpProvider.listRunsByIntegration(tmpTenantID, tmpIntegrationName, tmpOptions,
+				(pError, pRecords) =>
+				{
+					if (pError)
+					{
+						pResponse.send(500, { Success: false, Error: `${pError}` });
+						return fNext();
+					}
+					pResponse.send(200,
+						{
+							Success: true,
+							TenantID: tmpTenantID,
+							IntegrationName: tmpIntegrationName,
+							Count: pRecords.length,
+							Runs: pRecords
+						});
+					return fNext();
+				});
+		});
+
+	// ────────────────────────────────────────────────────────────────
+	// GET /telemetry/integrations/:IntegrationName/summary
+	// Aggregated summary for a specific integration.
+	// ────────────────────────────────────────────────────────────────
+	pOratorServiceServer.get(`${tmpPrefix}/integrations/:IntegrationName/summary`,
+		(pRequest, pResponse, fNext) =>
+		{
+			let tmpTenantID = pRequest.params.tenant_id || pTelemetryService.options.DefaultTenantID || 'default';
+			let tmpIntegrationName = decodeURIComponent(pRequest.params.IntegrationName);
+
+			let tmpProvider = pTelemetryService.getStorageProvider();
+			tmpProvider.getIntegrationSummary(tmpTenantID, tmpIntegrationName,
+				(pError, pSummary) =>
+				{
+					if (pError)
+					{
+						pResponse.send(500, { Success: false, Error: `${pError}` });
+						return fNext();
+					}
+					pResponse.send(200, { Success: true, Summary: pSummary });
+					return fNext();
+				});
+		});
+};

package/source/services/integration-telemetry/IntegrationTelemetry-Command-Runs.js

@@ -0,0 +1,93 @@
+/**
+ * IntegrationTelemetry — Run History Routes
+ *
+ * GET  {prefix}/runs           — list runs for a tenant
+ * GET  {prefix}/runs/:RunID    — single run detail
+ *
+ * @param {Object} pTelemetryService - The RetoldDataServiceIntegrationTelemetry instance
+ * @param {Object} pOratorServiceServer - The Orator ServiceServer instance
+ */
+module.exports = (pTelemetryService, pOratorServiceServer) =>
+{
+	let tmpPrefix = pTelemetryService.routePrefix;
+
+	// ────────────────────────────────────────────────────────────────
+	// GET /telemetry/runs
+	// List runs for a tenant with optional filtering.
+	//
+	// Query params:
+	//   tenant_id  — required (defaults to service default)
+	//   limit      — max records (default 50)
+	//   offset     — pagination offset
+	//   outcome    — filter by outcome (Success, Error, Partial, Stopped)
+	//   from       — ISO date lower bound
+	//   to         — ISO date upper bound
+	// ────────────────────────────────────────────────────────────────
+	pOratorServiceServer.get(`${tmpPrefix}/runs`,
+		(pRequest, pResponse, fNext) =>
+		{
+			let tmpTenantID = pRequest.params.tenant_id || pTelemetryService.options.DefaultTenantID || 'default';
+			let tmpOptions = (
+				{
+					Limit: pRequest.params.limit,
+					Offset: pRequest.params.offset,
+					Outcome: pRequest.params.outcome,
+					From: pRequest.params.from,
+					To: pRequest.params.to
+				});
+
+			let tmpProvider = pTelemetryService.getStorageProvider();
+			tmpProvider.listRuns(tmpTenantID, tmpOptions,
+				(pError, pRecords) =>
+				{
+					if (pError)
+					{
+						pResponse.send(500, { Success: false, Error: `${pError}` });
+						return fNext();
+					}
+					pResponse.send(200,
+						{
+							Success: true,
+							TenantID: tmpTenantID,
+							Count: pRecords.length,
+							Runs: pRecords
+						});
+					return fNext();
+				});
+		});
+
+	// ────────────────────────────────────────────────────────────────
+	// GET /telemetry/runs/:RunID
+	// Read a single run record by RunID.
+	// ────────────────────────────────────────────────────────────────
+	pOratorServiceServer.get(`${tmpPrefix}/runs/:RunID`,
+		(pRequest, pResponse, fNext) =>
+		{
+			let tmpTenantID = pRequest.params.tenant_id || pTelemetryService.options.DefaultTenantID || 'default';
+			let tmpRunID = pRequest.params.RunID;
+
+			if (!tmpRunID)
+			{
+				pResponse.send(400, { Success: false, Error: 'RunID is required.' });
+				return fNext();
+			}
+
+			let tmpProvider = pTelemetryService.getStorageProvider();
+			tmpProvider.readRun(tmpTenantID, tmpRunID,
+				(pError, pRecord) =>
+				{
+					if (pError)
+					{
+						pResponse.send(500, { Success: false, Error: `${pError}` });
+						return fNext();
+					}
+					if (!pRecord)
+					{
+						pResponse.send(404, { Success: false, Error: `Run [${tmpRunID}] not found for tenant [${tmpTenantID}].` });
+						return fNext();
+					}
+					pResponse.send(200, { Success: true, Run: pRecord });
+					return fNext();
+				});
+		});
+};

package/source/services/integration-telemetry/IntegrationTelemetry-StorageProvider-Base.js

@@ -0,0 +1,116 @@
+/**
+ * Integration Telemetry — Storage Provider Base
+ *
+ * Abstract interface for pluggable telemetry persistence.  Production
+ * deployments supply their own implementation; the built-in Bibliograph
+ * provider is used when no custom provider is wired.
+ *
+ * All methods follow the callback-last (pError, pResult) convention used
+ * throughout the retold codebase.
+ *
+ * @param {Object} pFable - The Fable instance (passed through for logging)
+ * @param {Object} pOptions - Provider-specific configuration
+ */
+class IntegrationTelemetryStorageProviderBase
+{
+	constructor(pFable, pOptions)
+	{
+		this.fable = pFable;
+		this.options = pOptions || {};
+	}
+
+	/**
+	 * Persist a single telemetry run record.
+	 *
+	 * @param {string} pTenantID - Tenant identifier
+	 * @param {Object} pRunRecord - The normalised telemetry record
+	 * @param {Function} fCallback - (pError)
+	 */
+	writeRun(pTenantID, pRunRecord, fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.writeRun is not implemented.'));
+	}
+
+	/**
+	 * Read a single run by its RunID.
+	 *
+	 * @param {string} pTenantID - Tenant identifier
+	 * @param {string} pRunID - The UUID of the run
+	 * @param {Function} fCallback - (pError, pRunRecord)
+	 */
+	readRun(pTenantID, pRunID, fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.readRun is not implemented.'));
+	}
+
+	/**
+	 * List run records for a tenant with optional filtering.
+	 *
+	 * @param {string} pTenantID - Tenant identifier
+	 * @param {Object} pOptions - { Limit, Offset, Outcome, From, To }
+	 * @param {Function} fCallback - (pError, pRecords)
+	 */
+	listRuns(pTenantID, pOptions, fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.listRuns is not implemented.'));
+	}
+
+	/**
+	 * List run records for a specific integration within a tenant.
+	 *
+	 * @param {string} pTenantID - Tenant identifier
+	 * @param {string} pIntegrationName - Integration name
+	 * @param {Object} pOptions - { Limit, Offset, Outcome, From, To }
+	 * @param {Function} fCallback - (pError, pRecords)
+	 */
+	listRunsByIntegration(pTenantID, pIntegrationName, pOptions, fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.listRunsByIntegration is not implemented.'));
+	}
+
+	/**
+	 * List runs across all tenants (corporate dashboard).
+	 *
+	 * @param {Object} pOptions - { Limit, Offset, Outcome, From, To }
+	 * @param {Function} fCallback - (pError, pRecords)
+	 */
+	listAllTenantRuns(pOptions, fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.listAllTenantRuns is not implemented.'));
+	}
+
+	/**
+	 * Compute an aggregate summary for a specific integration.
+	 *
+	 * @param {string} pTenantID - Tenant identifier
+	 * @param {string} pIntegrationName - Integration name
+	 * @param {Function} fCallback - (pError, pSummary)
+	 */
+	getIntegrationSummary(pTenantID, pIntegrationName, fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.getIntegrationSummary is not implemented.'));
+	}
+
+	/**
+	 * Compute an aggregate dashboard for a single tenant.
+	 *
+	 * @param {string} pTenantID - Tenant identifier
+	 * @param {Function} fCallback - (pError, pDashboard)
+	 */
+	getDashboardSummary(pTenantID, fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.getDashboardSummary is not implemented.'));
+	}
+
+	/**
+	 * Compute an aggregate dashboard across all tenants (corporate view).
+	 *
+	 * @param {Function} fCallback - (pError, pDashboard)
+	 */
+	getCorporateDashboardSummary(fCallback)
+	{
+		return fCallback(new Error('IntegrationTelemetryStorageProvider.getCorporateDashboardSummary is not implemented.'));
+	}
+}
+
+module.exports = IntegrationTelemetryStorageProviderBase;