@serhii.mazur/directus-gu-logs 1.0.9 → 1.0.11

package/README.MD

@@ -24,6 +24,7 @@ Add the following field to the `global` singleton collection:
 | ------------------------ | ------------------------------- | -------------------------------------------- |
 | `error_notice_recipient` | m2m → directus_users (junction) | Recipients for error notifications           |
 | `slack_webhook_url`      | input                           | Incoming webhook URL for Slack notifications |
+| `slack_notifications`    | boolen                          | Toggle Slack notifications                   |
 
 All linked users will receive internal Directus notifications when errors occur (unless a recipient override is passed).
 
@@ -80,10 +81,10 @@ import { Logs } from "@serhii.mazur/directus-gu-logs";
 const logs = new Logs(context, "my-extension");
 
 // Persist error log to DB + notify Slack
-await logs.printLogs("myFunction", "Something went wrong");
+await logs.logError("myFunction", "Something went wrong", true);
 
 // Persist error log without Slack notification
-await logs.printLogs("myFunction", "Something went wrong", false);
+await logs.logError("myFunction", "Something went wrong");
 
 // Create a Directus activity record
 await logs.createActivity("create", "collection_name", "item_id");
@@ -101,7 +102,7 @@ await logs.createNotification("An error occurred", "Custom Subject", "user_id");
 await logs.createNotification("An error occurred", "Custom Subject", null, "collection_name", "item_id");
 
 // Send Slack notification directly
-await logs.createSlackNotification("Deploy failed on main", "CI Alert");
+await logs.notifySlack("Deploy failed on main", "CI Alert");
 ```
 
 ### Advanced (direct class usage)
@@ -150,7 +151,7 @@ constructor(
 
 ## 🧠 How It Works
 
-### `printLogs(functionName, error, notifySlack?)`
+### `logError(functionName, error, notifySlack?)`
 
 1. Writes a structured entry to the logs collection
 2. If `notifySlack` is `true` (default), sends a Slack Block Kit message with extension name, function, and error
@@ -174,7 +175,7 @@ Then sends one in-app notification per recipient. Each notification includes:
 - The message body
 - Environment label, backend URL, and UTC timestamp
 
-### `createSlackNotification(message, subject?)`
+### `notifySlack(message, subject?)`
 
 Sends a formatted Slack Block Kit message via `slack_webhook_url`. Silently skips if the var is not set. The payload includes project name, environment, extension name, backend URL, and the message body.
 

package/dist/services/Logs.d.ts

@@ -14,8 +14,11 @@ export declare class Logs {
     /**
      * Persists an error entry to the logs collection, optionally notifying via Slack.
      */
+    logError(functionName: string, error: string, notifySlack?: boolean): Promise<void>;
+    /** @deprecated Use logError() instead */
     printLogs(functionName: string, error: string, notifySlack?: boolean): Promise<void>;
     createActivity(action: string, collection: string, id: PrimaryKey): Promise<void>;
-    createNotification(message: string, customSubject?: string | null, recipientOverride?: string | null, collection?: string | null, item?: string | null): Promise<void>;
-    createSlackNotification(message: string, customSubject?: string | null): Promise<void>;
+    createNotification(message: string, customSubject?: string | null, recipientOverride?: string | null, collection?: string | null, item?: string | null, notifySlack?: boolean): Promise<void>;
+    notifyEmail(message: string, customSubject?: string | null, recipientOverride?: string | null, collection?: string | null, item?: string | null): Promise<void>;
+    notifySlack(message: string, customSubject?: string | null): Promise<void>;
 }

package/dist/services/Logs.js

@@ -17,6 +17,15 @@ export class Logs {
             projectName: settings?.project_name ?? "Unknown Project",
             backendUrl: process.env.BACKEND_URL ?? this.context.env?.PUBLIC_URL ?? "Unknown URL",
             environment: process.env.BRANCH ?? "dev",
+            timestamp: new Intl.DateTimeFormat("en-US", {
+                month: "2-digit",
+                day: "2-digit",
+                year: "numeric",
+                hour: "2-digit",
+                minute: "2-digit",
+                hour12: false,
+                timeZone: "UTC",
+            }).format(new Date()),
         };
     }
     async createOne(data) {
@@ -30,7 +39,7 @@ export class Logs {
     /**
      * Persists an error entry to the logs collection, optionally notifying via Slack.
      */
-    async printLogs(functionName, error, notifySlack = true) {
+    async logError(functionName, error, notifySlack = false) {
         const data = {
             collection: this.collectionName,
             date_created: new Date().toISOString(),
@@ -40,7 +49,7 @@ export class Logs {
         };
         try {
             await this.createOne(data);
-            this.context.logger.info({ msg: `🚀 [${this.extension}] ${functionName}:`, error });
+            this.context.logger.error({ msg: `🚀 [${this.extension}] ${functionName}:`, error });
         }
         catch (err) {
             this.context.logger.error({ msg: "❌ Failed to save log entry", error: err });
@@ -49,13 +58,17 @@ export class Logs {
         try {
             if (notifySlack) {
                 const meta = await this.getProjectMeta();
-                await this.slack.notify(`*Function:* ${functionName}\n*Error:* ${error}`, "Extension Error", meta);
+                await this.slack.notify(`*Function:* ${functionName}\n*Error:* ${error}`, meta, "Extension Error");
             }
         }
         catch (err) {
-            this.context.logger.error({ msg: "Slack failed", err });
+            this.context.logger.error({ msg: "Slack failed", error: err });
         }
     }
+    /** @deprecated Use logError() instead */
+    async printLogs(functionName, error, notifySlack = false) {
+        return this.logError(functionName, error, notifySlack);
+    }
     async createActivity(action, collection, id) {
         try {
             const schema = await this.getSchema();
@@ -76,11 +89,24 @@ export class Logs {
                 item: id,
             });
         }
-        catch (error) {
-            this.context.logger.error({ msg: "❌ Failed to create activity log", error });
+        catch (err) {
+            this.context.logger.error({ msg: "❌ Failed to create activity log", error: err });
+        }
+    }
+    async createNotification(message, customSubject = null, recipientOverride = null, collection = null, item = null, notifySlack = true) {
+        const slackEnabled = await this.slack.isEnabled();
+        if (slackEnabled && notifySlack) {
+            try {
+                await this.notifySlack(`*Error:* ${message}`, customSubject);
+                return;
+            }
+            catch (err) {
+                this.context.logger.error({ msg: "❌ Slack notification failed", error: err });
+            }
         }
+        await this.notifyEmail(message, customSubject, recipientOverride, collection, item);
     }
-    async createNotification(message, customSubject = null, recipientOverride = null, collection = null, item = null) {
+    async notifyEmail(message, customSubject = null, recipientOverride = null, collection = null, item = null) {
         const meta = await this.getProjectMeta();
         await this.directus.notify(message, meta, {
             subject: customSubject,
@@ -89,8 +115,8 @@ export class Logs {
             item,
         });
     }
-    async createSlackNotification(message, customSubject = null) {
+    async notifySlack(message, customSubject = null) {
         const meta = await this.getProjectMeta();
-        await this.slack.notify(message, customSubject, meta);
+        await this.slack.notify(message, meta, customSubject);
     }
 }

package/dist/services/SlackNotifier.d.ts

@@ -2,8 +2,15 @@ import type { ApiExtensionContext, ProjectMeta, SlackPayload } from "../types";
 export declare class SlackNotifier {
     private readonly context;
     private readonly extension;
+    private configCache;
+    private configCachedAt;
+    private readonly CONFIG_CACHE_TTL;
     constructor(context: ApiExtensionContext, extension: string);
-    getWebHookUrl(): Promise<any>;
+    private getEnvironmentIcon;
+    private buildBlocks;
     send(payload: SlackPayload): Promise<void>;
-    notify(message: string, subject: string | null | undefined, meta: ProjectMeta): Promise<void>;
+    notify(message: string, meta: ProjectMeta, subject?: string | null): Promise<void>;
+    isEnabled(): Promise<boolean>;
+    private getConfig;
+    clearConfigCache(): void;
 }

package/dist/services/SlackNotifier.js

@@ -2,52 +2,98 @@ export class SlackNotifier {
     constructor(context, extension) {
         this.context = context;
         this.extension = extension;
+        this.configCachedAt = 0;
+        this.CONFIG_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
     }
-    async getWebHookUrl() {
-        const settings = await this.context.database.select("slack_webhook_url").from("global").first();
-        return settings?.slack_webhook_url;
+    getEnvironmentIcon(environment) {
+        switch (environment.toLowerCase()) {
+            case "main":
+            case "master":
+                return "🚨🔴";
+            case "staging":
+                return "🟠";
+            case "develop":
+                return "🟡";
+            default:
+                return "⚪";
+        }
+    }
+    buildBlocks(title, envIcon, message, meta) {
+        return [
+            { type: "divider" },
+            {
+                type: "header",
+                text: { type: "plain_text", text: `${envIcon} ${title}: ${this.extension}` },
+            },
+            {
+                type: "section",
+                fields: [
+                    { type: "mrkdwn", text: `*Project*\n${meta.projectName}` },
+                    { type: "mrkdwn", text: `*Environment*\n${meta.environment}` },
+                    { type: "mrkdwn", text: `*Timestamp (UTC)*\n${meta.timestamp}` },
+                    { type: "mrkdwn", text: `*Backend*\n${meta.backendUrl}` },
+                ],
+            },
+            { type: "section", text: { type: "mrkdwn", text: message } },
+            { type: "divider" },
+        ];
     }
     async send(payload) {
-        const webhook = await this.getWebHookUrl();
-        if (!webhook) {
-            this.context.logger.info({ msg: "⚠️ SLACK_WEBHOOK_URL is not configured" });
+        const config = await this.getConfig();
+        if (!config) {
+            this.context.logger.warn({ msg: "⚠️ Slack config not found" });
+            return;
+        }
+        if (!Boolean(config?.slack_notifications)) {
+            this.context.logger.info({ msg: "⚠️ Slack notifications are disabled" });
+            return;
+        }
+        if (!config.slack_webhook_url) {
+            this.context.logger.warn({ msg: "⚠️ Slack webhook URL is not configured" });
             return;
         }
         try {
-            await fetch(webhook, {
+            await fetch(config.slack_webhook_url, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify(payload),
             });
+            this.context.logger.debug({ msg: `✅ Slack notification sent [${this.extension}]` });
         }
         catch (error) {
             this.context.logger.error({ msg: "❌ Failed to send Slack message", error });
         }
     }
-    async notify(message, subject = null, meta) {
+    async notify(message, meta, subject = null) {
         const title = subject ?? "Directus Error Notification";
+        const envIcon = this.getEnvironmentIcon(meta.environment);
         await this.send({
             text: title,
-            blocks: [
-                {
-                    type: "header",
-                    text: { type: "plain_text", text: `🚨 ${title}` },
-                },
-                {
-                    type: "section",
-                    fields: [
-                        { type: "mrkdwn", text: `*Project*\n${meta.projectName}` },
-                        { type: "mrkdwn", text: `*Environment*\n${meta.environment}` },
-                        { type: "mrkdwn", text: `*Extension*\n${this.extension}` },
-                        { type: "mrkdwn", text: `*Backend*\n${meta.backendUrl}` },
-                    ],
-                },
-                { type: "divider" },
-                {
-                    type: "section",
-                    text: { type: "mrkdwn", text: message },
-                },
-            ],
+            blocks: this.buildBlocks(title, envIcon, message, meta),
         });
     }
+    async isEnabled() {
+        const config = await this.getConfig();
+        return Boolean(config?.slack_notifications && config?.slack_webhook_url);
+    }
+    async getConfig() {
+        const now = Date.now();
+        if (this.configCache && now - this.configCachedAt < this.CONFIG_CACHE_TTL) {
+            return this.configCache;
+        }
+        const result = await this.context.database
+            .select("slack_webhook_url", "slack_notifications")
+            .from("global")
+            .first();
+        if (result) {
+            this.configCache = result;
+            this.configCachedAt = now;
+        }
+        return result;
+    }
+    clearConfigCache() {
+        this.configCache = undefined;
+        this.configCachedAt = 0;
+        this.context.logger.debug({ msg: "🔄 Slack config cache cleared" });
+    }
 }

package/dist/types.d.ts

@@ -16,6 +16,7 @@ export interface ProjectMeta {
     projectName: string;
     backendUrl: string;
     environment: string;
+    timestamp: string;
 }
 export interface SlackBlock {
     type: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@serhii.mazur/directus-gu-logs",
-	"version": "1.0.9",
-	"description": "Helper class Logs for using in Directus extensions",
+	"version": "1.0.11",
+	"description": "Reusable logging utility for Directus extensions — persists error entries, tracks activity, and sends notifications via Slack and Directus inbox.",
 	"type": "module",
 	"main": "./dist/index.js",
 	"scripts": {

package/src/services/Logs.ts

@@ -26,6 +26,15 @@ export class Logs {
 			projectName: settings?.project_name ?? "Unknown Project",
 			backendUrl: process.env.BACKEND_URL ?? this.context.env?.PUBLIC_URL ?? "Unknown URL",
 			environment: process.env.BRANCH ?? "dev",
+			timestamp: new Intl.DateTimeFormat("en-US", {
+				month: "2-digit",
+				day: "2-digit",
+				year: "numeric",
+				hour: "2-digit",
+				minute: "2-digit",
+				hour12: false,
+				timeZone: "UTC",
+			}).format(new Date()),
 		};
 	}
 
@@ -43,7 +52,7 @@ export class Logs {
 	/**
 	 * Persists an error entry to the logs collection, optionally notifying via Slack.
 	 */
-	async printLogs(functionName: string, error: string, notifySlack = true): Promise<void> {
+	async logError(functionName: string, error: string, notifySlack = false): Promise<void> {
 		const data: LogEntry = {
 			collection: this.collectionName,
 			date_created: new Date().toISOString(),
@@ -55,7 +64,7 @@ export class Logs {
 		try {
 			await this.createOne(data);
 
-			this.context.logger.info({ msg: `🚀 [${this.extension}] ${functionName}:`, error });
+			this.context.logger.error({ msg: `🚀 [${this.extension}] ${functionName}:`, error });
 		} catch (err) {
 			this.context.logger.error({ msg: "❌ Failed to save log entry", error: err });
 			return;
@@ -64,13 +73,18 @@ export class Logs {
 		try {
 			if (notifySlack) {
 				const meta = await this.getProjectMeta();
-				await this.slack.notify(`*Function:* ${functionName}\n*Error:* ${error}`, "Extension Error", meta);
+				await this.slack.notify(`*Function:* ${functionName}\n*Error:* ${error}`, meta, "Extension Error");
 			}
 		} catch (err) {
-			this.context.logger.error({ msg: "Slack failed", err });
+			this.context.logger.error({ msg: "Slack failed", error: err });
 		}
 	}
 
+	/** @deprecated Use logError() instead */
+	async printLogs(functionName: string, error: string, notifySlack = false): Promise<void> {
+		return this.logError(functionName, error, notifySlack);
+	}
+
 	async createActivity(action: string, collection: string, id: PrimaryKey): Promise<void> {
 		try {
 			const schema = await this.getSchema();
@@ -92,8 +106,8 @@ export class Logs {
 				origin: accountability?.origin ?? null,
 				item: id,
 			});
-		} catch (error) {
-			this.context.logger.error({ msg: "❌ Failed to create activity log", error });
+		} catch (err) {
+			this.context.logger.error({ msg: "❌ Failed to create activity log", error: err });
 		}
 	}
 
@@ -103,6 +117,28 @@ export class Logs {
 		recipientOverride: string | null = null,
 		collection: string | null = null,
 		item: string | null = null,
+		notifySlack = true,
+	): Promise<void> {
+		const slackEnabled = await this.slack.isEnabled();
+
+		if (slackEnabled && notifySlack) {
+			try {
+				await this.notifySlack(`*Error:* ${message}`, customSubject);
+				return;
+			} catch (err) {
+				this.context.logger.error({ msg: "❌ Slack notification failed", error: err });
+			}
+		}
+
+		await this.notifyEmail(message, customSubject, recipientOverride, collection, item);
+	}
+
+	async notifyEmail(
+		message: string,
+		customSubject: string | null = null,
+		recipientOverride: string | null = null,
+		collection: string | null = null,
+		item: string | null = null,
 	): Promise<void> {
 		const meta = await this.getProjectMeta();
 
@@ -114,9 +150,9 @@ export class Logs {
 		});
 	}
 
-	async createSlackNotification(message: string, customSubject: string | null = null): Promise<void> {
+	async notifySlack(message: string, customSubject: string | null = null): Promise<void> {
 		const meta = await this.getProjectMeta();
 
-		await this.slack.notify(message, customSubject, meta);
+		await this.slack.notify(message, meta, customSubject);
 	}
 }

package/src/services/SlackNotifier.ts

@@ -1,61 +1,119 @@
 import type { ApiExtensionContext, ProjectMeta, SlackPayload } from "../types";
 
 export class SlackNotifier {
+	private configCache: { slack_webhook_url: string | null; slack_notifications: boolean } | undefined;
+	private configCachedAt: number = 0;
+	private readonly CONFIG_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
 	constructor(
 		private readonly context: ApiExtensionContext,
 		private readonly extension: string,
 	) {}
 
-	async getWebHookUrl() {
-		const settings = await this.context.database.select("slack_webhook_url").from("global").first();
+	private getEnvironmentIcon(environment: string): string {
+		switch (environment.toLowerCase()) {
+			case "main":
+			case "master":
+				return "🚨🔴";
+			case "staging":
+				return "🟠";
+			case "develop":
+				return "🟡";
+			default:
+				return "⚪";
+		}
+	}
 
-		return settings?.slack_webhook_url;
+	private buildBlocks(title: string, envIcon: string, message: string, meta: ProjectMeta) {
+		return [
+			{ type: "divider" },
+			{
+				type: "header",
+				text: { type: "plain_text", text: `${envIcon} ${title}: ${this.extension}` },
+			},
+			{
+				type: "section",
+				fields: [
+					{ type: "mrkdwn", text: `*Project*\n${meta.projectName}` },
+					{ type: "mrkdwn", text: `*Environment*\n${meta.environment}` },
+					{ type: "mrkdwn", text: `*Timestamp (UTC)*\n${meta.timestamp}` },
+					{ type: "mrkdwn", text: `*Backend*\n${meta.backendUrl}` },
+				],
+			},
+			{ type: "section", text: { type: "mrkdwn", text: message } },
+			{ type: "divider" },
+		];
 	}
 
 	async send(payload: SlackPayload): Promise<void> {
-		const webhook = await this.getWebHookUrl();
+		const config = await this.getConfig();
+
+		if (!config) {
+			this.context.logger.warn({ msg: "⚠️ Slack config not found" });
+			return;
+		}
 
-		if (!webhook) {
-			this.context.logger.info({ msg: "⚠️ SLACK_WEBHOOK_URL is not configured" });
+		if (!Boolean(config?.slack_notifications)) {
+			this.context.logger.info({ msg: "⚠️ Slack notifications are disabled" });
+			return;
+		}
+
+		if (!config!.slack_webhook_url) {
+			this.context.logger.warn({ msg: "⚠️ Slack webhook URL is not configured" });
 			return;
 		}
 
 		try {
-			await fetch(webhook, {
+			await fetch(config.slack_webhook_url, {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
 				body: JSON.stringify(payload),
 			});
+
+			this.context.logger.debug({ msg: `✅ Slack notification sent [${this.extension}]` });
 		} catch (error) {
 			this.context.logger.error({ msg: "❌ Failed to send Slack message", error });
 		}
 	}
 
-	async notify(message: string, subject: string | null = null, meta: ProjectMeta): Promise<void> {
+	async notify(message: string, meta: ProjectMeta, subject: string | null = null): Promise<void> {
 		const title = subject ?? "Directus Error Notification";
+		const envIcon = this.getEnvironmentIcon(meta.environment);
 
 		await this.send({
 			text: title,
-			blocks: [
-				{
-					type: "header",
-					text: { type: "plain_text", text: `🚨 ${title}` },
-				},
-				{
-					type: "section",
-					fields: [
-						{ type: "mrkdwn", text: `*Project*\n${meta.projectName}` },
-						{ type: "mrkdwn", text: `*Environment*\n${meta.environment}` },
-						{ type: "mrkdwn", text: `*Extension*\n${this.extension}` },
-						{ type: "mrkdwn", text: `*Backend*\n${meta.backendUrl}` },
-					],
-				},
-				{ type: "divider" },
-				{
-					type: "section",
-					text: { type: "mrkdwn", text: message },
-				},
-			],
+			blocks: this.buildBlocks(title, envIcon, message, meta),
 		});
 	}
+
+	async isEnabled(): Promise<boolean> {
+		const config = await this.getConfig();
+		return Boolean(config?.slack_notifications && config?.slack_webhook_url);
+	}
+
+	private async getConfig(): Promise<{ slack_webhook_url: string | null; slack_notifications: boolean } | undefined> {
+		const now = Date.now();
+
+		if (this.configCache && now - this.configCachedAt < this.CONFIG_CACHE_TTL) {
+			return this.configCache;
+		}
+
+		const result = await this.context.database
+			.select("slack_webhook_url", "slack_notifications")
+			.from("global")
+			.first();
+
+		if (result) {
+			this.configCache = result;
+			this.configCachedAt = now;
+		}
+
+		return result;
+	}
+
+	clearConfigCache(): void {
+		this.configCache = undefined;
+		this.configCachedAt = 0;
+		this.context.logger.debug({ msg: "🔄 Slack config cache cleared" });
+	}
 }

package/src/types.ts

@@ -17,6 +17,7 @@ export interface ProjectMeta {
 	projectName: string;
 	backendUrl: string;
 	environment: string;
+	timestamp: string;
 }
 
 export interface SlackBlock {