@simpleapps-com/augur-api 0.3.0 → 0.3.2

package/dist/esm/services/slack/client.js

@@ -0,0 +1,312 @@
+import { BaseServiceClient } from '../../core/base-client';
+import { HealthCheckParamsSchema, HealthCheckResponseSchema, WebHookRequestParamsSchema, WebHookResponseSchema, WebHookRefreshParamsSchema, WebHookRefreshResponseSchema, } from './schemas';
+/**
+ * Slack Integration Service Client
+ *
+ * Provides comprehensive Slack integration capabilities including webhook management,
+ * message delivery, channel notifications, and real-time communication features.
+ * Supports modern Slack Block Kit formatting and legacy attachment formats.
+ *
+ * @service slack
+ * @domain communication-and-notifications
+ */
+export class SlackClient extends BaseServiceClient {
+    constructor(http, baseUrl) {
+        super('slack', http, baseUrl || 'https://slack.augur-api.com');
+    }
+    getServiceDescription() {
+        return 'Slack integration service for webhooks, notifications, and team communication';
+    }
+    /**
+     * Check Slack service health and connectivity
+     *
+     * @fullPath api.slack.healthCheck.get
+     * @service slack
+     * @domain system-health
+     * @dataMethod healthCheckData
+     * @discoverable true
+     * @searchTerms ["health", "status", "availability", "ping", "check", "slack service", "webhook connectivity", "integration status"]
+     * @relatedEndpoints ["api.slack.webHook.send", "api.slack.webHook.refresh", "api.joomla.healthCheck.get", "api.commerce.healthCheck.get", "api.customers.healthCheck.get"]
+     * @commonPatterns ["Health check", "Service status", "Slack connectivity test", "System monitoring", "Integration verification"]
+     * @workflow ["system-monitoring", "health-checks", "service-discovery", "slack-integration-verification", "webhook-status-check"]
+     * @prerequisites ["Service is running", "Valid authentication token", "x-site-id header", "Slack API connectivity"]
+     * @nextSteps ["Use webhook endpoints if healthy", "Verify Slack API connectivity", "Monitor integration metrics", "Test message delivery"]
+     * @businessRules ["Returns service and Slack connectivity status", "Requires standard authentication", "Standard health check format", "Includes webhook status"]
+     * @functionalArea "system-monitoring"
+     * @caching "No caching - real-time status required"
+     * @performance "Fast response, minimal processing, use for Slack integration monitoring"
+     *
+     * @param params Health check parameters with site ID
+     * @returns Promise<HealthCheckResponse> Service health status with Slack connectivity information
+     *
+     * @example
+     * ```typescript
+     * // Check if Slack service is healthy
+     * const response = await client.healthCheck({ 'x-site-id': 'SITE123' });
+     * console.log(response.data.status); // 'healthy'
+     * console.log(response.data.slack_connectivity); // true/false
+     * console.log(response.status); // HTTP status code
+     *
+     * // Get just the health status
+     * const status = await client.healthCheckData({ 'x-site-id': 'SITE123' });
+     * console.log(status); // Health data object
+     * ```
+     */
+    async healthCheck(params) {
+        return this.executeRequest({
+            method: 'GET',
+            path: '/health-check',
+            paramsSchema: HealthCheckParamsSchema,
+            responseSchema: HealthCheckResponseSchema,
+        }, params);
+    }
+    /**
+     * Send messages and manage Slack webhooks
+     *
+     * @fullPath api.slack.webHook.send
+     * @service slack
+     * @domain communication-and-notifications
+     * @dataMethod webHookData
+     * @discoverable true
+     * @searchTerms ["slack", "webhook", "message", "notification", "send", "channel", "team communication", "alerts", "blocks", "attachments"]
+     * @relatedEndpoints ["api.slack.webHook.refresh", "api.joomla.users.notifications", "api.commerce.orders.notifications", "api.customers.alerts.create"]
+     * @commonPatterns ["Send Slack message", "Team notification", "Alert delivery", "Webhook integration", "Channel broadcast", "User notification"]
+     * @workflow ["notification-delivery", "team-communication", "alert-management", "webhook-integration", "message-broadcasting", "incident-response"]
+     * @prerequisites ["Valid Slack webhook URL", "Channel permissions", "Valid authentication token", "x-site-id header", "Message content"]
+     * @nextSteps ["Monitor delivery status", "Handle webhook responses", "Update notification preferences", "Track message engagement"]
+     * @businessRules ["Supports Slack Block Kit and legacy attachments", "Requires webhook URL or channel", "Message formatting follows Slack standards", "Delivery status tracking", "Retry logic for failed deliveries"]
+     * @functionalArea "communication-and-notifications"
+     * @crossSite "Multi-site webhook configuration and message routing"
+     * @caching "No caching - real-time message delivery required"
+     * @performance "Async delivery with status tracking, batch messages for high volume, use blocks for rich formatting"
+     *
+     * @param params Webhook request parameters including message content, formatting, and delivery options
+     * @returns Promise<WebHookResponse> Webhook delivery status and message metadata
+     *
+     * @example
+     * ```typescript
+     * // Send simple text message
+     * const simpleMessage = {
+     *   text: "Hello from the API!",
+     *   channel: "#general",
+     *   'x-site-id': 'SITE123'
+     * };
+     * const response = await client.webHook(simpleMessage);
+     * console.log(response.data.delivery_status); // 'sent', 'delivered', 'failed'
+     *
+     * // Send rich message with blocks (modern Slack formatting)
+     * const richMessage = {
+     *   channel: "#alerts",
+     *   blocks: [{
+     *     type: "section",
+     *     text: {
+     *       type: "mrkdwn",
+     *       text: "*Order Alert* :warning:\nNew high-value order received"
+     *     }
+     *   }, {
+     *     type: "section",
+     *     fields: [{
+     *       type: "mrkdwn",
+     *       text: "*Order ID:*\n#12345"
+     *     }, {
+     *       type: "mrkdwn",
+     *       text: "*Amount:*\n$1,250.00"
+     *     }]
+     *   }],
+     *   'x-site-id': 'SITE123'
+     * };
+     * const alertResponse = await client.webHook(richMessage);
+     *
+     * // Send message with legacy attachments
+     * const attachmentMessage = {
+     *   text: "Order Processing Update",
+     *   channel: "#orders",
+     *   attachments: [{
+     *     color: "good",
+     *     title: "Order #12345 Processed",
+     *     text: "Customer order has been successfully processed and shipped.",
+     *     fields: [{
+     *       title: "Customer",
+     *       value: "John Doe",
+     *       short: true
+     *     }, {
+     *       title: "Total",
+     *       value: "$299.99",
+     *       short: true
+     *     }],
+     *     footer: "Order System",
+     *     ts: Date.now() / 1000
+     *   }],
+     *   'x-site-id': 'SITE123'
+     * };
+     * const orderUpdate = await client.webHook(attachmentMessage);
+     *
+     * // Get just the webhook data
+     * const deliveryStatus = await client.webHookData(simpleMessage);
+     * console.log(deliveryStatus); // Direct webhook data access
+     *
+     * // Configure webhook for automated notifications
+     * const webhookConfig = {
+     *   url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+     *   channel: "#automation",
+     *   username: "API Bot",
+     *   icon_emoji: ":robot_face:",
+     *   webhook_type: "incoming",
+     *   'x-site-id': 'SITE123'
+     * };
+     * const configResponse = await client.webHook(webhookConfig);
+     * ```
+     */
+    async webHook(params) {
+        return this.executeRequest({
+            method: 'POST',
+            path: '/web-hook',
+            paramsSchema: WebHookRequestParamsSchema,
+            responseSchema: WebHookResponseSchema,
+        }, params);
+    }
+    /**
+     * Refresh Slack webhook configurations and connectivity
+     *
+     * @fullPath api.slack.webHook.refresh
+     * @service slack
+     * @domain communication-and-notifications
+     * @dataMethod webHookRefreshData
+     * @discoverable true
+     * @searchTerms ["webhook", "refresh", "configuration", "update", "sync", "connectivity", "channels", "integration refresh"]
+     * @relatedEndpoints ["api.slack.webHook.send", "api.slack.healthCheck.get", "api.joomla.configuration.refresh", "api.commerce.settings.sync"]
+     * @commonPatterns ["Refresh webhook config", "Update integration", "Sync channels", "Reconnect webhooks", "Configuration update"]
+     * @workflow ["webhook-management", "integration-maintenance", "configuration-sync", "connectivity-restoration", "channel-discovery"]
+     * @prerequisites ["Valid authentication token", "x-site-id header", "Webhook configurations exist", "Slack API connectivity"]
+     * @nextSteps ["Verify refreshed configurations", "Test webhook delivery", "Update channel mappings", "Monitor integration health"]
+     * @businessRules ["Refreshes all webhook configurations", "Discovers new channels", "Validates existing webhooks", "Updates connectivity status", "Handles configuration errors"]
+     * @functionalArea "communication-and-notifications"
+     * @crossSite "Multi-site webhook configuration refresh"
+     * @caching "Cache refreshed configuration for 1 hour"
+     * @performance "May take several seconds for full refresh, run periodically to maintain connectivity"
+     *
+     * @param params Webhook refresh parameters including force refresh option
+     * @returns Promise<WebHookRefreshResponse> Refresh results with configuration status and channel information
+     *
+     * @example
+     * ```typescript
+     * // Standard webhook refresh
+     * const refreshResponse = await client.webHookRefresh({ 'x-site-id': 'SITE123' });
+     * console.log(refreshResponse.data.refreshed); // true/false
+     * console.log(refreshResponse.data.active_webhooks); // Count of active webhooks
+     * console.log(refreshResponse.data.channels); // Available channels
+     *
+     * // Force refresh (bypasses cache)
+     * const forceRefresh = await client.webHookRefresh({
+     *   'x-site-id': 'SITE123',
+     *   force: true
+     * });
+     * console.log(forceRefresh.data.configuration_status); // 'valid', 'invalid', 'partial'
+     *
+     * // Get just the refresh data
+     * const refreshData = await client.webHookRefreshData({ 'x-site-id': 'SITE123' });
+     * console.log(refreshData); // Direct refresh data access
+     *
+     * // Handle refresh errors
+     * const refreshResult = await client.webHookRefresh({ 'x-site-id': 'SITE123' });
+     * if (refreshResult.data.errors && refreshResult.data.errors.length > 0) {
+     *   console.log('Refresh errors:', refreshResult.data.errors);
+     *   // Handle configuration issues
+     * }
+     *
+     * // Monitor webhook health after refresh
+     * if (refreshResult.data.inactive_webhooks > 0) {
+     *   console.log(`${refreshResult.data.inactive_webhooks} webhooks need attention`);
+     *   // Investigate inactive webhooks
+     * }
+     * ```
+     */
+    async webHookRefresh(params) {
+        return this.executeRequest({
+            method: 'GET',
+            path: '/web-hook/refresh',
+            paramsSchema: WebHookRefreshParamsSchema,
+            responseSchema: WebHookRefreshResponseSchema,
+        }, params);
+    }
+    // Data methods - return data portion only for convenience
+    /**
+     * Get Slack service health data without full response metadata
+     *
+     * @fullPath api.slack.healthCheckData.get
+     * @service slack
+     * @domain system-health
+     * @dataMethod healthCheckData
+     * @discoverable true
+     * @searchTerms ["health data", "service status", "slack connectivity", "integration status"]
+     * @relatedEndpoints ["api.slack.healthCheck.get", "api.slack.webHook.send"]
+     * @commonPatterns ["Get health status", "Check connectivity", "Service monitoring"]
+     * @workflow ["system-monitoring", "health-checks", "integration-verification"]
+     * @prerequisites ["Valid authentication token", "x-site-id header"]
+     * @nextSteps ["Use Slack endpoints if healthy", "Monitor service metrics"]
+     * @businessRules ["Returns only health data object", "No response metadata included"]
+     * @functionalArea "system-monitoring"
+     * @caching "No caching - real-time status required"
+     * @performance "Direct data access, faster for simple health checks"
+     *
+     * @param params Health check parameters with site ID
+     * @returns Promise<HealthCheckData> Direct health status data object
+     */
+    async healthCheckData(params) {
+        const response = await this.healthCheck(params);
+        return response.data;
+    }
+    /**
+     * Send Slack webhook and get data without full response metadata
+     *
+     * @fullPath api.slack.webHookData.send
+     * @service slack
+     * @domain communication-and-notifications
+     * @dataMethod webHookData
+     * @discoverable true
+     * @searchTerms ["webhook data", "message data", "delivery status", "notification result"]
+     * @relatedEndpoints ["api.slack.webHook.send", "api.slack.webHook.refresh"]
+     * @commonPatterns ["Send message data", "Get delivery status", "Direct webhook access"]
+     * @workflow ["notification-delivery", "team-communication", "alert-management"]
+     * @prerequisites ["Valid webhook configuration", "Message content", "Valid authentication token"]
+     * @nextSteps ["Monitor delivery status", "Handle webhook responses", "Track message engagement"]
+     * @businessRules ["Returns only webhook data", "No response metadata included", "Direct access to delivery status"]
+     * @functionalArea "communication-and-notifications"
+     * @caching "No caching - real-time delivery tracking"
+     * @performance "Direct data access, optimal for webhook status monitoring"
+     *
+     * @param params Webhook request parameters
+     * @returns Promise<WebHookData> Direct webhook delivery data without response wrapper
+     */
+    async webHookData(params) {
+        const response = await this.webHook(params);
+        return response.data;
+    }
+    /**
+     * Refresh webhooks and get data without full response metadata
+     *
+     * @fullPath api.slack.webHookRefreshData.get
+     * @service slack
+     * @domain communication-and-notifications
+     * @dataMethod webHookRefreshData
+     * @discoverable true
+     * @searchTerms ["refresh data", "webhook config", "integration status", "channel data"]
+     * @relatedEndpoints ["api.slack.webHookRefresh.get", "api.slack.webHook.send"]
+     * @commonPatterns ["Get refresh data", "Configuration status", "Channel information"]
+     * @workflow ["webhook-management", "integration-maintenance", "configuration-sync"]
+     * @prerequisites ["Valid authentication token", "x-site-id header", "Webhook configurations"]
+     * @nextSteps ["Verify configurations", "Test webhook delivery", "Update channel mappings"]
+     * @businessRules ["Returns only refresh data", "No response metadata included", "Direct access to configuration status"]
+     * @functionalArea "communication-and-notifications"
+     * @caching "Cache for 1 hour after refresh"
+     * @performance "Direct data access, optimal for configuration monitoring"
+     *
+     * @param params Webhook refresh parameters
+     * @returns Promise<WebHookRefreshData> Direct refresh data without response wrapper
+     */
+    async webHookRefreshData(params) {
+        const response = await this.webHookRefresh(params);
+        return response.data;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/services/slack/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/services/slack/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,uBAAuB,EAEvB,yBAAyB,EAEzB,0BAA0B,EAE1B,qBAAqB,EAErB,0BAA0B,EAE1B,4BAA4B,GAI7B,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;GASG;AACH,MAAM,OAAO,WAAY,SAAQ,iBAAiB;IAChD,YAAY,IAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,6BAA6B,CAAC,CAAC;IACjE,CAAC;IAES,qBAAqB;QAC7B,OAAO,+EAA+E,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,KAAK,CAAC,WAAW,CAAC,MAAyB;QACzC,OAAO,IAAI,CAAC,cAAc,CACxB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,eAAe;YACrB,YAAY,EAAE,uBAAuB;YACrC,cAAc,EAAE,yBAAyB;SAC1C,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgGG;IACH,KAAK,CAAC,OAAO,CAAC,MAA4B;QACxC,OAAO,IAAI,CAAC,cAAc,CACxB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,WAAW;YACjB,YAAY,EAAE,0BAA0B;YACxC,cAAc,EAAE,qBAAqB;SACtC,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuDG;IACH,KAAK,CAAC,cAAc,CAAC,MAA4B;QAC/C,OAAO,IAAI,CAAC,cAAc,CACxB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,mBAAmB;YACzB,YAAY,EAAE,0BAA0B;YACxC,cAAc,EAAE,4BAA4B;SAC7C,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAED,0DAA0D;IAE1D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,eAAe,CAAC,MAAyB;QAC7C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,WAAW,CAAC,MAA4B;QAC5C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5C,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAA4B;QACnD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACnD,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;CACF"}

package/dist/esm/services/slack/index.d.ts

@@ -0,0 +1,4 @@
+export { SlackClient } from './client';
+export type { HealthCheckParams, WebHookRequestParams, WebHookRefreshParams, HealthCheckData, WebHookData, WebHookRefreshData, HealthCheckResponse, WebHookResponse, WebHookRefreshResponse, } from './schemas';
+export { HealthCheckParamsSchema, WebHookRequestParamsSchema, WebHookRefreshParamsSchema, HealthCheckDataSchema, WebHookDataSchema, WebHookRefreshDataSchema, HealthCheckResponseSchema, WebHookResponseSchema, WebHookRefreshResponseSchema, } from './schemas';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/services/slack/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/slack/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,WAAW,CAAC"}

package/dist/esm/services/slack/index.js

@@ -0,0 +1,5 @@
+// Export client
+export { SlackClient } from './client';
+// Export schemas for validation
+export { HealthCheckParamsSchema, WebHookRequestParamsSchema, WebHookRefreshParamsSchema, HealthCheckDataSchema, WebHookDataSchema, WebHookRefreshDataSchema, HealthCheckResponseSchema, WebHookResponseSchema, WebHookRefreshResponseSchema, } from './schemas';
+//# sourceMappingURL=index.js.map

package/dist/esm/services/slack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/services/slack/index.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAevC,gCAAgC;AAChC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,WAAW,CAAC"}