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

package/README.MD

@@ -1,39 +1,52 @@
 # 📦 Custom Directus Logs Utility
 
-A lightweight utility class for logging errors, creating activity logs, and sending notifications in Directus extensions.
+A modular utility for logging errors, tracking activity, and sending notifications (Directus in-app + Slack) from Directus extensions.
 
-## 📋 Requirements:
+## 📋 Requirements
 
-### 1. Logs Collection (logs)
+### 1. Logs Collection (`logs`)
 
-You need to create a collection named `logs` with the following fields:
+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)
+### 2. Global Collection (`global`)
 
-Add the following field to the `global` collection:
+Add the following field to the `global` singleton 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           |
+| `slack_webhook_url`      | input                           | Incoming webhook URL for Slack notifications |
 
-This recipient will be used to send internal notifications when errors occur.
+All linked users will receive internal Directus notifications when errors occur (unless a recipient override is passed).
 
-## 🚀 Features
+### 3. Environment Variables
+
+| Variable      | Required | Description                                                   |
+| ------------- | -------- | ------------------------------------------------------------- |
+| `BACKEND_URL` | Optional | Shown in notifications; falls back to `PUBLIC_URL`            |
+| `BRANCH`      | Optional | Environment label (e.g. `main`, `staging`); defaults to `dev` |
+
+---
 
--   Save error logs to the logs collection
+## 🚀 Features
 
--   Create Directus activity records
+- Persist structured error logs to a Directus collection
+- Send Slack Block Kit notifications via incoming webhook
+- Send Directus in-app notifications with automatic recipient resolution
+- Create Directus activity records
+- Shared project metadata (name, URL, environment) injected into all notifications
+- Recipient deduplication
+- Graceful fallbacks — all methods catch and log their own errors
 
--   Send internal Directus notifications
+---
 
 ## 📦 Installation
 
@@ -41,15 +54,128 @@ This recipient will be used to send internal notifications when errors occur.
 npm i @serhii.mazur/directus-gu-logs
 ```
 
+---
+
+## 🗂 Architecture
+
+The package is split into three focused classes:
+
+```
+Logs                  ← main entry point; orchestrates everything
+├── SlackNotifier     ← formats and sends Slack Block Kit payloads
+└── DirectusNotifier  ← resolves recipients, sends in-app notifications
+```
+
+All three are exported and can be used independently if needed.
+
+---
+
 ## 🧩 Usage
 
+### Basic (via `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");
+
+// Persist error log to DB + notify Slack
+await logs.printLogs("myFunction", "Something went wrong");
+
+// Persist error log without Slack notification
+await logs.printLogs("myFunction", "Something went wrong", false);
 
-await logs.printLogs("myFunction", "message");
-await logs.createActivity("create", "collection", "id");
+// Create a Directus activity record
+await logs.createActivity("create", "collection_name", "item_id");
+
+// Send Directus in-app notification (recipients from global settings)
 await logs.createNotification("An error occurred");
-await logs.createNotification("An error occurred", "Custom subject", "recipient_id");
+
+// With custom subject
+await logs.createNotification("An error occurred", "Custom Subject");
+
+// Override recipient
+await logs.createNotification("An error occurred", "Custom Subject", "user_id");
+
+// With linked collection + item
+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");
 ```
+
+### Advanced (direct class usage)
+
+```ts
+import { SlackNotifier, DirectusNotifier } from "@serhii.mazur/directus-gu-logs";
+
+// Use SlackNotifier standalone
+const slack = new SlackNotifier(context, "my-extension");
+await slack.notify("Custom message", "Alert Title", projectMeta);
+
+// Send a raw Slack payload
+await slack.send({ text: "plain fallback", blocks: [...] });
+
+// Use DirectusNotifier standalone
+const directus = new DirectusNotifier(context, "my-extension");
+await directus.notify("Message", projectMeta, {
+  subject: "Custom Subject",
+  recipientOverride: "user-uuid",
+  collection: "pages",
+  item: "42",
+});
+```
+
+---
+
+## ⚙️ Constructor
+
+### `Logs`
+
+```ts
+constructor(
+  context: ApiExtensionContext,
+  extension: string,
+  collectionName: string = "logs"
+)
+```
+
+| Param            | Type                | Default | Description                      |
+| ---------------- | ------------------- | ------- | -------------------------------- |
+| `context`        | ApiExtensionContext | —       | Directus extension context       |
+| `extension`      | string              | —       | Name of your extension           |
+| `collectionName` | string              | `logs`  | Target collection for error logs |
+
+---
+
+## 🧠 How It Works
+
+### `printLogs(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
+3. Always writes to `context.logger.error` as well
+4. Catches its own failure — a broken DB write won't throw
+
+### `createActivity(action, collection, id)`
+
+Creates a Directus activity record via `ActivityService`. User, IP, and user agent are set to `null` in extension hook context where no accountability is available.
+
+### `createNotification(message, subject?, recipientOverride?, collection?, item?)`
+
+Resolves recipients in this order:
+
+1. `recipientOverride` (if provided)
+2. `global.error_notice_recipient` linked users
+
+Then sends one in-app notification per recipient. Each notification includes:
+
+- Custom or default subject with the project name appended
+- The message body
+- Environment label, backend URL, and UTC timestamp
+
+### `createSlackNotification(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/index.d.ts

@@ -1,13 +1,3 @@
-import { ApiExtensionContext } from "@directus/extensions";
-import type { PrimaryKey } from "@directus/types";
-export declare class Logs {
-    protected context: ApiExtensionContext;
-    protected extension: string;
-    protected collectionName: string;
-    constructor(context: ApiExtensionContext, extension: string, collectionName?: string);
-    private getSchema;
-    private createOne;
-    printLogs(functionName: string, error: string): 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>;
-}
+export { Logs } from "./services/Logs";
+export { SlackNotifier } from "./services/SlackNotifier";
+export type { LogEntry, RecipientLinkRow, ProjectMeta, SlackBlock, SlackPayload, ApiExtensionContext, PrimaryKey, } from "./types";

package/dist/index.js

@@ -1,119 +1,2 @@
-export class Logs {
-    constructor(context, extension, collectionName = "logs") {
-        this.context = context;
-        this.extension = extension;
-        this.collectionName = collectionName;
-    }
-    async getSchema() {
-        return await this.context.getSchema();
-    }
-    async createOne(data) {
-        const schema = await this.getSchema();
-        const itemsService = new this.context.services.ItemsService(this.collectionName, {
-            database: this.context.database,
-            schema,
-        });
-        return await itemsService.createOne(data);
-    }
-    async printLogs(functionName, error) {
-        const data = {
-            collection: this.collectionName,
-            date_created: new Date().toISOString(),
-            extension: this.extension,
-            function_name: functionName,
-            error,
-        };
-        try {
-            await this.createOne(data);
-            console.error(`🚀 [${this.extension}] ${functionName}:`, error);
-        }
-        catch (error) {
-            console.error("❌ Failed to save logs:", error);
-        }
-    }
-    async createActivity(action, collection, id) {
-        try {
-            const schema = await this.getSchema();
-            const services = this.context.services;
-            const accountability = services.accountability;
-            const activityService = new services.ActivityService({
-                schema: schema,
-                accountability: accountability,
-                knex: this.context.database,
-            });
-            await activityService.createOne({
-                action,
-                user: accountability?.user ?? null,
-                collection,
-                ip: accountability?.ip ?? null,
-                user_agent: accountability?.userAgent ?? null,
-                origin: accountability?.origin ?? null,
-                item: id,
-            });
-        }
-        catch (error) {
-            console.error("❌ Failed to create activity log:", error);
-        }
-    }
-    async createNotification(message, customSubject = null, recipientOverride = null, collection = null, item = null) {
-        try {
-            const schema = await this.getSchema();
-            const { database, services } = this.context;
-            // 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);
-            }
-            if (recipients.length === 0) {
-                this.printLogs(this.extension, "No recipients defined (override or global settings)");
-                return;
-            }
-            const notificationService = new services.NotificationsService({ schema });
-            // 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",
-                day: "2-digit",
-                year: "numeric",
-                hour: "2-digit",
-                minute: "2-digit",
-                hour12: false,
-                timeZone: "UTC",
-            }).format(now);
-            // Compose subject & message
-            const subject = customSubject
-                ? `${customSubject} - ${projectName}`
-                : `Directus Error Notification - ${projectName}`;
-            const fullMessage = `
-${message}<br><br>
-<strong>Environment:</strong> ${environment}<br>
-<strong>Backend URL:</strong> <a href="${backendUrl}" target="_blank">${backendUrl}</a><br>
-<strong>Date/Time (UTC):</strong> ${timestamp}
-`.trim();
-            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);
-        }
-    }
-}
+export { Logs } from "./services/Logs";
+export { SlackNotifier } from "./services/SlackNotifier";

package/dist/indexNew.d.ts

@@ -0,0 +1,3 @@
+export { Logs } from "./services/Logs";
+export { SlackNotifier } from "./services/SlackNotifier";
+export type { LogEntry, RecipientLinkRow, ProjectMeta, SlackBlock, SlackPayload, ApiExtensionContext, PrimaryKey, } from "./types";

package/dist/indexNew.js

@@ -0,0 +1,2 @@
+export { Logs } from "./services/Logs";
+export { SlackNotifier } from "./services/SlackNotifier";

package/dist/services/DirectusNotifier.d.ts

@@ -0,0 +1,13 @@
+import type { ApiExtensionContext, ProjectMeta } from "../types";
+export declare class DirectusNotifier {
+    private readonly context;
+    private readonly extension;
+    constructor(context: ApiExtensionContext, extension: string);
+    private getSchema;
+    notify(message: string, meta: ProjectMeta, options?: {
+        subject?: string | null;
+        recipientOverride?: string | null;
+        collection?: string | null;
+        item?: string | null;
+    }): Promise<void>;
+}

package/dist/services/DirectusNotifier.js

@@ -0,0 +1,77 @@
+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((v) => Boolean(v)) ?? [];
+    return Array.from(new Set(recipients));
+}
+export class DirectusNotifier {
+    constructor(context, extension) {
+        this.context = context;
+        this.extension = extension;
+    }
+    async getSchema() {
+        return this.context.getSchema();
+    }
+    async notify(message, meta, options = {}) {
+        const { subject = null, recipientOverride = null, collection = null, item = null } = options;
+        try {
+            const schema = await this.getSchema();
+            const { database, services } = this.context;
+            let recipients = [];
+            if (recipientOverride) {
+                recipients = [recipientOverride];
+            }
+            else {
+                const globalService = new services.ItemsService("global", { database, schema });
+                const globalSettings = await globalService.readSingleton({
+                    fields: ["error_notice_recipient.directus_users_id.id"],
+                });
+                recipients = extractRecipientIds(globalSettings?.error_notice_recipient);
+            }
+            if (recipients.length === 0) {
+                this.context.logger.warn({
+                    msg: `[${this.extension}] No notification recipients defined (override or global settings)`,
+                });
+                return;
+            }
+            const notificationService = new services.NotificationsService({ schema });
+            const now = new Date();
+            const 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(now);
+            const resolvedSubject = subject
+                ? `${subject} - ${meta.projectName}`
+                : `Directus Error Notification - ${meta.projectName}`;
+            const fullMessage = [
+                message,
+                `<strong>Environment:</strong> ${meta.environment}`,
+                `<strong>Backend URL:</strong> <a href="${meta.backendUrl}" target="_blank">${meta.backendUrl}</a>`,
+                `<strong>Date/Time (UTC):</strong> ${timestamp}`,
+            ].join("<br><br>");
+            for (const recipient of recipients) {
+                await notificationService.createOne({
+                    recipient,
+                    sender: recipient,
+                    subject: resolvedSubject,
+                    message: fullMessage,
+                    collection,
+                    item,
+                });
+            }
+        }
+        catch (error) {
+            this.context.logger.error({ msg: "❌ Failed to send Directus notification", error });
+        }
+    }
+}

package/dist/services/Logs.d.ts

@@ -0,0 +1,21 @@
+import type { ApiExtensionContext, PrimaryKey } from "../types";
+import { SlackNotifier } from "../services/SlackNotifier";
+import { DirectusNotifier } from "./DirectusNotifier";
+export declare class Logs {
+    protected readonly context: ApiExtensionContext;
+    protected readonly extension: string;
+    protected readonly collectionName: string;
+    protected readonly slack: SlackNotifier;
+    protected readonly directus: DirectusNotifier;
+    constructor(context: ApiExtensionContext, extension: string, collectionName?: string);
+    private getSchema;
+    private getProjectMeta;
+    private createOne;
+    /**
+     * Persists an error entry to the logs collection, optionally notifying via Slack.
+     */
+    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>;
+}

package/dist/services/Logs.js

@@ -0,0 +1,96 @@
+import { SlackNotifier } from "../services/SlackNotifier";
+import { DirectusNotifier } from "./DirectusNotifier";
+export class Logs {
+    constructor(context, extension, collectionName = "logs") {
+        this.context = context;
+        this.extension = extension;
+        this.collectionName = collectionName;
+        this.slack = new SlackNotifier(context, extension);
+        this.directus = new DirectusNotifier(context, extension);
+    }
+    async getSchema() {
+        return this.context.getSchema();
+    }
+    async getProjectMeta() {
+        const settings = await this.context.database.select("project_name").from("directus_settings").first();
+        return {
+            projectName: settings?.project_name ?? "Unknown Project",
+            backendUrl: process.env.BACKEND_URL ?? this.context.env?.PUBLIC_URL ?? "Unknown URL",
+            environment: process.env.BRANCH ?? "dev",
+        };
+    }
+    async createOne(data) {
+        const schema = await this.getSchema();
+        const itemsService = new this.context.services.ItemsService(this.collectionName, {
+            database: this.context.database,
+            schema,
+        });
+        return await itemsService.createOne(data);
+    }
+    /**
+     * Persists an error entry to the logs collection, optionally notifying via Slack.
+     */
+    async printLogs(functionName, error, notifySlack = true) {
+        const data = {
+            collection: this.collectionName,
+            date_created: new Date().toISOString(),
+            extension: this.extension,
+            function_name: functionName,
+            error,
+        };
+        try {
+            await this.createOne(data);
+            this.context.logger.info({ msg: `🚀 [${this.extension}] ${functionName}:`, error });
+        }
+        catch (err) {
+            this.context.logger.error({ msg: "❌ Failed to save log entry", error: err });
+            return;
+        }
+        try {
+            if (notifySlack) {
+                const meta = await this.getProjectMeta();
+                await this.slack.notify(`*Function:* ${functionName}\n*Error:* ${error}`, "Extension Error", meta);
+            }
+        }
+        catch (err) {
+            this.context.logger.error({ msg: "Slack failed", err });
+        }
+    }
+    async createActivity(action, collection, id) {
+        try {
+            const schema = await this.getSchema();
+            const { services, database } = this.context;
+            const accountability = services.accountability;
+            const activityService = new services.ActivityService({
+                schema,
+                accountability,
+                knex: database,
+            });
+            await activityService.createOne({
+                action,
+                user: accountability?.user ?? null,
+                collection,
+                ip: accountability?.ip ?? null,
+                user_agent: accountability?.userAgent ?? null,
+                origin: accountability?.origin ?? null,
+                item: id,
+            });
+        }
+        catch (error) {
+            this.context.logger.error({ msg: "❌ Failed to create activity log", error });
+        }
+    }
+    async createNotification(message, customSubject = null, recipientOverride = null, collection = null, item = null) {
+        const meta = await this.getProjectMeta();
+        await this.directus.notify(message, meta, {
+            subject: customSubject,
+            recipientOverride,
+            collection,
+            item,
+        });
+    }
+    async createSlackNotification(message, customSubject = null) {
+        const meta = await this.getProjectMeta();
+        await this.slack.notify(message, customSubject, meta);
+    }
+}

package/dist/services/SlackNotifier.d.ts

@@ -0,0 +1,9 @@
+import type { ApiExtensionContext, ProjectMeta, SlackPayload } from "../types";
+export declare class SlackNotifier {
+    private readonly context;
+    private readonly extension;
+    constructor(context: ApiExtensionContext, extension: string);
+    getWebHookUrl(): Promise<any>;
+    send(payload: SlackPayload): Promise<void>;
+    notify(message: string, subject: string | null | undefined, meta: ProjectMeta): Promise<void>;
+}

package/dist/services/SlackNotifier.js

@@ -0,0 +1,53 @@
+export class SlackNotifier {
+    constructor(context, extension) {
+        this.context = context;
+        this.extension = extension;
+    }
+    async getWebHookUrl() {
+        const settings = await this.context.database.select("slack_webhook_url").from("global").first();
+        return settings?.slack_webhook_url;
+    }
+    async send(payload) {
+        const webhook = await this.getWebHookUrl();
+        if (!webhook) {
+            this.context.logger.info({ msg: "⚠️ SLACK_WEBHOOK_URL is not configured" });
+            return;
+        }
+        try {
+            await fetch(webhook, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+            });
+        }
+        catch (error) {
+            this.context.logger.error({ msg: "❌ Failed to send Slack message", error });
+        }
+    }
+    async notify(message, subject = null, meta) {
+        const title = subject ?? "Directus Error Notification";
+        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 },
+                },
+            ],
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+import type { ApiExtensionContext } from "@directus/extensions";
+import type { PrimaryKey } from "@directus/types";
+export interface LogEntry {
+    collection: string;
+    date_created: string;
+    extension: string;
+    function_name: string;
+    error: string;
+}
+export interface RecipientLinkRow {
+    directus_users_id?: string | {
+        id?: string | null;
+    } | null;
+}
+export interface ProjectMeta {
+    projectName: string;
+    backendUrl: string;
+    environment: string;
+}
+export interface SlackBlock {
+    type: string;
+    text?: {
+        type: string;
+        text: string;
+        emoji?: boolean;
+    };
+    fields?: {
+        type: string;
+        text: string;
+    }[];
+}
+export interface SlackPayload {
+    text: string;
+    blocks?: SlackBlock[];
+}
+export type { ApiExtensionContext };
+export type { PrimaryKey };

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

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

package/src/index.ts

@@ -1,159 +1,11 @@
-import { ApiExtensionContext } from "@directus/extensions";
-import type { PrimaryKey } from "@directus/types";
-
-interface LogEntry {
-	collection: string;
-	date_created: string;
-	extension: string;
-	function_name: string;
-	error: string;
-}
-
-export class Logs {
-	protected context: ApiExtensionContext;
-	protected extension: string;
-	protected collectionName: string;
-
-	constructor(context: ApiExtensionContext, extension: string, collectionName: string = "logs") {
-		this.context = context;
-		this.extension = extension;
-		this.collectionName = collectionName;
-	}
-
-	private async getSchema() {
-		return await this.context.getSchema();
-	}
-
-	private async createOne(data: Record<string, any>) {
-		const schema = await this.getSchema();
-
-		const itemsService = new this.context.services.ItemsService(this.collectionName, {
-			database: this.context.database,
-			schema,
-		});
-
-		return await itemsService.createOne(data);
-	}
-
-	async printLogs(functionName: string, error: string) {
-		const data: LogEntry = {
-			collection: this.collectionName,
-			date_created: new Date().toISOString(),
-			extension: this.extension,
-			function_name: functionName,
-			error,
-		};
-
-		try {
-			await this.createOne(data);
-			console.error(`🚀 [${this.extension}] ${functionName}:`, error);
-		} catch (error) {
-			console.error("❌ Failed to save logs:", error);
-		}
-	}
-
-	async createActivity(action: string, collection: string, id: PrimaryKey) {
-		try {
-			const schema = await this.getSchema();
-			const services = this.context.services;
-			const accountability = services.accountability;
-
-			const activityService = new services.ActivityService({
-				schema: schema,
-				accountability: accountability,
-				knex: this.context.database,
-			});
-
-			await activityService.createOne({
-				action,
-				user: accountability?.user ?? null,
-				collection,
-				ip: accountability?.ip ?? null,
-				user_agent: accountability?.userAgent ?? null,
-				origin: accountability?.origin ?? null,
-				item: id,
-			});
-		} catch (error) {
-			console.error("❌ Failed to create activity log:", error);
-		}
-	}
-
-	async createNotification(
-		message: string,
-		customSubject: string | null = null,
-		recipientOverride: string | null = null,
-		collection: string | null = null,
-		item: string | null = null
-	) {
-		try {
-			const schema = await this.getSchema();
-			const { database, services } = this.context;
-
-			// Check for passed recipient, fallback to global settings
-			let recipients: string[] = [];
-
-			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
-				);
-			}
-
-			if (recipients.length === 0) {
-				this.printLogs(this.extension, "No recipients defined (override or global settings)");
-				return;
-			}
-
-			const notificationService = new services.NotificationsService({ schema });
-
-			// 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",
-				day: "2-digit",
-				year: "numeric",
-				hour: "2-digit",
-				minute: "2-digit",
-				hour12: false,
-				timeZone: "UTC",
-			}).format(now);
-
-			// Compose subject & message
-			const subject = customSubject
-				? `${customSubject} - ${projectName}`
-				: `Directus Error Notification - ${projectName}`;
-
-			const fullMessage = `
-${message}<br><br>
-<strong>Environment:</strong> ${environment}<br>
-<strong>Backend URL:</strong> <a href="${backendUrl}" target="_blank">${backendUrl}</a><br>
-<strong>Date/Time (UTC):</strong> ${timestamp}
-`.trim();
-
-			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);
-		}
-	}
-}
+export { Logs } from "./services/Logs";
+export { SlackNotifier } from "./services/SlackNotifier";
+export type {
+	LogEntry,
+	RecipientLinkRow,
+	ProjectMeta,
+	SlackBlock,
+	SlackPayload,
+	ApiExtensionContext,
+	PrimaryKey,
+} from "./types";

package/src/services/DirectusNotifier.ts

@@ -0,0 +1,100 @@
+import type { ApiExtensionContext, ProjectMeta, RecipientLinkRow } from "../types";
+
+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((v): v is string => Boolean(v)) ?? [];
+
+	return Array.from(new Set(recipients));
+}
+
+export class DirectusNotifier {
+	constructor(
+		private readonly context: ApiExtensionContext,
+		private readonly extension: string,
+	) {}
+
+	private async getSchema() {
+		return this.context.getSchema();
+	}
+
+	async notify(
+		message: string,
+		meta: ProjectMeta,
+		options: {
+			subject?: string | null;
+			recipientOverride?: string | null;
+			collection?: string | null;
+			item?: string | null;
+		} = {},
+	): Promise<void> {
+		const { subject = null, recipientOverride = null, collection = null, item = null } = options;
+
+		try {
+			const schema = await this.getSchema();
+			const { database, services } = this.context;
+
+			let recipients: string[] = [];
+
+			if (recipientOverride) {
+				recipients = [recipientOverride];
+			} else {
+				const globalService = new services.ItemsService("global", { database, schema });
+				const globalSettings = await globalService.readSingleton({
+					fields: ["error_notice_recipient.directus_users_id.id"],
+				});
+
+				recipients = extractRecipientIds(globalSettings?.error_notice_recipient);
+			}
+
+			if (recipients.length === 0) {
+				this.context.logger.warn({
+					msg: `[${this.extension}] No notification recipients defined (override or global settings)`,
+				});
+				return;
+			}
+
+			const notificationService = new services.NotificationsService({ schema });
+
+			const now = new Date();
+			const 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(now);
+
+			const resolvedSubject = subject
+				? `${subject} - ${meta.projectName}`
+				: `Directus Error Notification - ${meta.projectName}`;
+
+			const fullMessage = [
+				message,
+				`<strong>Environment:</strong> ${meta.environment}`,
+				`<strong>Backend URL:</strong> <a href="${meta.backendUrl}" target="_blank">${meta.backendUrl}</a>`,
+				`<strong>Date/Time (UTC):</strong> ${timestamp}`,
+			].join("<br><br>");
+
+			for (const recipient of recipients) {
+				await notificationService.createOne({
+					recipient,
+					sender: recipient,
+					subject: resolvedSubject,
+					message: fullMessage,
+					collection,
+					item,
+				});
+			}
+		} catch (error) {
+			this.context.logger.error({ msg: "❌ Failed to send Directus notification", error });
+		}
+	}
+}

package/src/services/Logs.ts

@@ -0,0 +1,122 @@
+import type { ApiExtensionContext, LogEntry, PrimaryKey, ProjectMeta } from "../types";
+import { SlackNotifier } from "../services/SlackNotifier";
+import { DirectusNotifier } from "./DirectusNotifier";
+
+export class Logs {
+	protected readonly slack: SlackNotifier;
+	protected readonly directus: DirectusNotifier;
+
+	constructor(
+		protected readonly context: ApiExtensionContext,
+		protected readonly extension: string,
+		protected readonly collectionName: string = "logs",
+	) {
+		this.slack = new SlackNotifier(context, extension);
+		this.directus = new DirectusNotifier(context, extension);
+	}
+
+	private async getSchema() {
+		return this.context.getSchema();
+	}
+
+	private async getProjectMeta(): Promise<ProjectMeta> {
+		const settings = await this.context.database.select("project_name").from("directus_settings").first();
+
+		return {
+			projectName: settings?.project_name ?? "Unknown Project",
+			backendUrl: process.env.BACKEND_URL ?? this.context.env?.PUBLIC_URL ?? "Unknown URL",
+			environment: process.env.BRANCH ?? "dev",
+		};
+	}
+
+	private async createOne(data: Record<string, any>) {
+		const schema = await this.getSchema();
+
+		const itemsService = new this.context.services.ItemsService(this.collectionName, {
+			database: this.context.database,
+			schema,
+		});
+
+		return await itemsService.createOne(data);
+	}
+
+	/**
+	 * Persists an error entry to the logs collection, optionally notifying via Slack.
+	 */
+	async printLogs(functionName: string, error: string, notifySlack = true): Promise<void> {
+		const data: LogEntry = {
+			collection: this.collectionName,
+			date_created: new Date().toISOString(),
+			extension: this.extension,
+			function_name: functionName,
+			error,
+		};
+
+		try {
+			await this.createOne(data);
+
+			this.context.logger.info({ msg: `🚀 [${this.extension}] ${functionName}:`, error });
+		} catch (err) {
+			this.context.logger.error({ msg: "❌ Failed to save log entry", error: err });
+			return;
+		}
+
+		try {
+			if (notifySlack) {
+				const meta = await this.getProjectMeta();
+				await this.slack.notify(`*Function:* ${functionName}\n*Error:* ${error}`, "Extension Error", meta);
+			}
+		} catch (err) {
+			this.context.logger.error({ msg: "Slack failed", err });
+		}
+	}
+
+	async createActivity(action: string, collection: string, id: PrimaryKey): Promise<void> {
+		try {
+			const schema = await this.getSchema();
+			const { services, database } = this.context;
+			const accountability = services.accountability;
+
+			const activityService = new services.ActivityService({
+				schema,
+				accountability,
+				knex: database,
+			});
+
+			await activityService.createOne({
+				action,
+				user: accountability?.user ?? null,
+				collection,
+				ip: accountability?.ip ?? null,
+				user_agent: accountability?.userAgent ?? null,
+				origin: accountability?.origin ?? null,
+				item: id,
+			});
+		} catch (error) {
+			this.context.logger.error({ msg: "❌ Failed to create activity log", error });
+		}
+	}
+
+	async createNotification(
+		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();
+
+		await this.directus.notify(message, meta, {
+			subject: customSubject,
+			recipientOverride,
+			collection,
+			item,
+		});
+	}
+
+	async createSlackNotification(message: string, customSubject: string | null = null): Promise<void> {
+		const meta = await this.getProjectMeta();
+
+		await this.slack.notify(message, customSubject, meta);
+	}
+}

package/src/services/SlackNotifier.ts

@@ -0,0 +1,61 @@
+import type { ApiExtensionContext, ProjectMeta, SlackPayload } from "../types";
+
+export class SlackNotifier {
+	constructor(
+		private readonly context: ApiExtensionContext,
+		private readonly extension: string,
+	) {}
+
+	async getWebHookUrl() {
+		const settings = await this.context.database.select("slack_webhook_url").from("global").first();
+
+		return settings?.slack_webhook_url;
+	}
+
+	async send(payload: SlackPayload): Promise<void> {
+		const webhook = await this.getWebHookUrl();
+
+		if (!webhook) {
+			this.context.logger.info({ msg: "⚠️ SLACK_WEBHOOK_URL is not configured" });
+			return;
+		}
+
+		try {
+			await fetch(webhook, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(payload),
+			});
+		} 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> {
+		const title = subject ?? "Directus Error Notification";
+
+		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 },
+				},
+			],
+		});
+	}
+}

package/src/types.ts

@@ -0,0 +1,35 @@
+import type { ApiExtensionContext } from "@directus/extensions";
+import type { PrimaryKey } from "@directus/types";
+
+export interface LogEntry {
+	collection: string;
+	date_created: string;
+	extension: string;
+	function_name: string;
+	error: string;
+}
+
+export interface RecipientLinkRow {
+	directus_users_id?: string | { id?: string | null } | null;
+}
+
+export interface ProjectMeta {
+	projectName: string;
+	backendUrl: string;
+	environment: string;
+}
+
+export interface SlackBlock {
+	type: string;
+	text?: { type: string; text: string; emoji?: boolean };
+	fields?: { type: string; text: string }[];
+}
+
+export interface SlackPayload {
+	text: string;
+	blocks?: SlackBlock[];
+}
+
+export type { ApiExtensionContext };
+
+export type { PrimaryKey };