@serhii.mazur/directus-gu-logs 1.0.6 → 1.0.8

package/README.MD

@@ -8,31 +8,32 @@ A lightweight utility class for logging errors, creating activity logs, and send
 
 You need to create a collection named `logs` with the following fields:
 
-| Field Name      | Type     | Description              |
-| --------------- | -------- | ------------------------ |
-| `collection`    | string   | Name of the collection   |
-| `date_created`  | datetime | Timestamp of the log     |
-| `extension`     | string   | Extension identifier     |
-| `function_name` | string   | Name of the function     |
-| `error`         | code     | Error message/code block |
+| Field Name      | Type      | Description                  |
+| --------------- | --------- | ---------------------------- |
+| `collection`    | string    | Name of the collection       |
+| `date_created`  | datetime  | Timestamp of the log         |
+| `extension`     | string    | Extension identifier         |
+| `function_name` | string    | Name of the function         |
+| `error`         | text/code | Error message or stack trace |
 
 ### 2. Global Collection (global)
 
 Add the following field to the `global` collection:
 
-| Field Name         | Type                 | Description                       |
-| ------------------ | -------------------- | --------------------------------- |
-| `notice_recipient` | m2o → directus_users | Recipient for error notifications |
+| Field Name               | Type                            | Description                        |
+| ------------------------ | ------------------------------- | ---------------------------------- |
+| `error_notice_recipient` | m2m → directus_users (junction) | Recipients for error notifications |
 
-This recipient will be used to send internal notifications when errors occur.
+All linked users from this field will receive internal notifications when errors occur.
 
 ## 🚀 Features
 
--   Save error logs to the logs collection
-
--   Create Directus activity records
-
--   Send internal Directus notifications
+- Save structured error logs to a collection
+- Create Directus activity records
+- Send internal Directus notifications
+- Automatic recipient resolution from global settings
+- Support for manual recipient override
+- Includes project metadata in notifications (environment, URL, timestamp)
 
 ## 📦 Installation
 
@@ -45,10 +46,77 @@ npm i @serhii.mazur/directus-gu-logs
 ```ts
 import { Logs } from "@serhii.mazur/directus-gu-logs";
 
-const logs = new Logs(context, "my-extension", "logs");
+const logs = new Logs(context, "my-extension");
+
+// Save error log
+await logs.printLogs("myFunction", "Something went wrong");
 
-await logs.printLogs("myFunction", "message");
-await logs.createActivity("create", "collection", "id");
+// Create activity record
+await logs.createActivity("create", "collection_name", "item_id");
+
+// Send notification (auto recipients from global settings)
 await logs.createNotification("An error occurred");
-await logs.createNotification("An error occurred", "Custom subject", "recipient_id");
+
+// Send notification with custom subject
+await logs.createNotification("An error occurred", "Custom Subject");
+
+// Send notification to specific recipient
+await logs.createNotification("An error occurred", "Custom Subject", "user_id");
+
+// Send notification with related collection + item
+await logs.createNotification("An error occurred", "Custom Subject", null, "collection_name", "item_id");
+```
+
+---
+
+## ⚙️ Constructor
+
+```ts
+constructor(
+  context: ApiExtensionContext,
+  extension: string,
+  collectionName: string = "logs"
+)
 ```
+
+| Param            | Type                | Description                          |
+| ---------------- | ------------------- | ------------------------------------ |
+| `context`        | ApiExtensionContext | Directus extension context           |
+| `extension`      | string              | Name of your extension               |
+| `collectionName` | string (optional)   | Logs collection name (default: logs) |
+
+## 🧠 How It Works
+
+### Logging
+
+- Saves structured logs into the logs collection
+- Automatically attaches timestamp and extension name
+- Fallback to console if DB write fails
+
+---
+
+### Activity Tracking
+
+- Uses Directus ActivityService
+- Automatically includes:
+    - user
+    - IP address
+    - user agent
+    - origin
+
+---
+
+### Notifications
+
+- Resolves recipients in this order:
+    1. Explicit recipientOverride
+    2. global.notice_recipient
+    3. global.developer_notice_recipient
+- Automatically:
+    - Deduplicates recipients
+    - Includes project metadata:
+        - Project name
+        - Backend URL
+        - Environment (branch)
+        - UTC timestamp
+- Sends one notification per recipient

package/dist/index.js

@@ -1,3 +1,14 @@
+function extractRecipientIds(rows) {
+    const recipients = rows
+        ?.map(row => {
+        const user = row?.directus_users_id;
+        if (typeof user === "string")
+            return user;
+        return typeof user?.id === "string" ? user.id : null;
+    })
+        .filter((value) => Boolean(value)) ?? [];
+    return Array.from(new Set(recipients));
+}
 export class Logs {
     constructor(context, extension, collectionName = "logs") {
         this.context = context;
@@ -59,14 +70,23 @@ export class Logs {
         try {
             const schema = await this.getSchema();
             const { database, services } = this.context;
+            const globalService = new services.ItemsService("global", {
+                database,
+                schema,
+            });
             // Check for passed recipient, fallback to global settings
-            let recipient = recipientOverride;
-            if (!recipient) {
-                const globalSettings = await database.select("notice_recipient").from("global").first();
-                recipient = globalSettings?.notice_recipient;
+            let recipients = [];
+            if (recipientOverride) {
+                recipients = [recipientOverride];
+            }
+            else {
+                const globalSettings = await globalService.readSingleton({
+                    fields: ["error_notice_recipient.directus_users_id.id"],
+                });
+                recipients = extractRecipientIds(globalSettings?.error_notice_recipient);
             }
-            if (!recipient) {
-                this.printLogs(this.extension, "No recipient defined (override or global settings)");
+            if (recipients.length === 0) {
+                this.printLogs(this.extension, "No recipients defined (override or global settings)");
                 return;
             }
             const notificationService = new services.NotificationsService({ schema });
@@ -95,14 +115,16 @@ ${message}<br><br>
 <strong>Backend URL:</strong> <a href="${backendUrl}" target="_blank">${backendUrl}</a><br>
 <strong>Date/Time (UTC):</strong> ${timestamp}
 `.trim();
-            await notificationService.createOne({
-                recipient,
-                sender: recipient,
-                subject,
-                message: fullMessage,
-                collection,
-                item,
-            });
+            for (const recipient of recipients) {
+                await notificationService.createOne({
+                    recipient,
+                    sender: recipient,
+                    subject,
+                    message: fullMessage,
+                    collection,
+                    item,
+                });
+            }
         }
         catch (error) {
             console.error("❌ Failed to create notification:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serhii.mazur/directus-gu-logs",
-	"version": "1.0.6",
+	"version": "1.0.8",
 	"description": "Helper class Logs for using in Directus extensions",
 	"type": "module",
 	"main": "./dist/index.js",

package/src/index.ts

@@ -9,6 +9,23 @@ interface LogEntry {
 	error: string;
 }
 
+interface RecipientLinkRow {
+	directus_users_id?: string | { id?: string | null } | null;
+}
+
+function extractRecipientIds(rows: RecipientLinkRow[] | undefined): string[] {
+	const recipients =
+		rows
+			?.map(row => {
+				const user = row?.directus_users_id;
+				if (typeof user === "string") return user;
+				return typeof user?.id === "string" ? user.id : null;
+			})
+			.filter((value): value is string => Boolean(value)) ?? [];
+
+	return Array.from(new Set(recipients));
+}
+
 export class Logs {
 	protected context: ApiExtensionContext;
 	protected extension: string;
@@ -88,16 +105,26 @@ export class Logs {
 		try {
 			const schema = await this.getSchema();
 			const { database, services } = this.context;
+			const globalService = new services.ItemsService("global", {
+				database,
+				schema,
+			});
 
 			// Check for passed recipient, fallback to global settings
-			let recipient = recipientOverride;
-			if (!recipient) {
-				const globalSettings = await database.select("notice_recipient").from("global").first();
-				recipient = globalSettings?.notice_recipient;
+			let recipients: string[] = [];
+
+			if (recipientOverride) {
+				recipients = [recipientOverride];
+			} else {
+				const globalSettings = await globalService.readSingleton({
+					fields: ["error_notice_recipient.directus_users_id.id"],
+				});
+
+				recipients = extractRecipientIds(globalSettings?.error_notice_recipient);
 			}
 
-			if (!recipient) {
-				this.printLogs(this.extension, "No recipient defined (override or global settings)");
+			if (recipients.length === 0) {
+				this.printLogs(this.extension, "No recipients defined (override or global settings)");
 				return;
 			}
 
@@ -105,9 +132,11 @@ export class Logs {
 
 			// Project Data
 			const settings = await database.select("project_name").from("directus_settings").first();
+
 			const projectName = settings?.project_name || "Unknown Project";
 			const backendUrl = process.env.BACKEND_URL || this.context.env?.PUBLIC_URL || "Unknown URL";
 			const environment = process.env.BRANCH || "dev";
+
 			const now = new Date();
 			const timestamp = new Intl.DateTimeFormat("en-US", {
 				month: "2-digit",
@@ -131,14 +160,16 @@ ${message}<br><br>
 <strong>Date/Time (UTC):</strong> ${timestamp}
 `.trim();
 
-			await notificationService.createOne({
-				recipient,
-				sender: recipient,
-				subject,
-				message: fullMessage,
-				collection,
-				item,
-			});
+			for (const recipient of recipients) {
+				await notificationService.createOne({
+					recipient,
+					sender: recipient,
+					subject,
+					message: fullMessage,
+					collection,
+					item,
+				});
+			}
 		} catch (error) {
 			console.error("❌ Failed to create notification:", error);
 		}