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

package/README.MD

@@ -8,32 +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 |
-| `developer_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
 
@@ -46,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,17 +70,20 @@ 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 recipients = [];
             if (recipientOverride) {
                 recipients = [recipientOverride];
             }
             else {
-                const globalSettings = await database
-                    .select("notice_recipient", "developer_notice_recipient")
-                    .from("global")
-                    .first();
-                recipients = [globalSettings?.notice_recipient, globalSettings?.developer_notice_recipient].filter(Boolean);
+                const globalSettings = await globalService.readSingleton({
+                    fields: ["error_notice_recipient.directus_users_id.id"],
+                });
+                recipients = extractRecipientIds(globalSettings?.error_notice_recipient);
             }
             if (recipients.length === 0) {
                 this.printLogs(this.extension, "No recipients defined (override or global settings)");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serhii.mazur/directus-gu-logs",
-	"version": "1.0.7",
+	"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,6 +105,10 @@ 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 recipients: string[] = [];
@@ -95,14 +116,11 @@ export class Logs {
 			if (recipientOverride) {
 				recipients = [recipientOverride];
 			} else {
-				const globalSettings = await database
-					.select("notice_recipient", "developer_notice_recipient")
-					.from("global")
-					.first();
-
-				recipients = [globalSettings?.notice_recipient, globalSettings?.developer_notice_recipient].filter(
-					Boolean
-				);
+				const globalSettings = await globalService.readSingleton({
+					fields: ["error_notice_recipient.directus_users_id.id"],
+				});
+
+				recipients = extractRecipientIds(globalSettings?.error_notice_recipient);
 			}
 
 			if (recipients.length === 0) {