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

package/README.MD

@@ -1,12 +1,12 @@
 # 📦 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                  |
 | --------------- | --------- | ---------------------------- |
@@ -16,24 +16,38 @@ You need to create a collection named `logs` with the following fields:
 | `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                        |
-| ------------------------ | ------------------------------- | ---------------------------------- |
-| `error_notice_recipient` | m2m → directus_users (junction) | Recipients 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 |
+| `slack_notifications`    | boolen                          | Toggle Slack notifications                   |
 
-All linked users from this field will receive internal notifications when errors occur.
+All linked users will receive internal Directus notifications when errors occur (unless a recipient override is passed).
+
+### 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` |
+
+---
 
 ## 🚀 Features
 
-- Save structured error logs to a collection
+- 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
-- Send internal Directus notifications
-- Automatic recipient resolution from global settings
-- Support for manual recipient override
-- Includes project metadata in notifications (environment, URL, timestamp)
+- Shared project metadata (name, URL, environment) injected into all notifications
+- Recipient deduplication
+- Graceful fallbacks — all methods catch and log their own errors
+
+---
 
 ## 📦 Installation
 
@@ -41,36 +55,84 @@ All linked users from this field will receive internal notifications when errors
 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");
 
-// Save error log
-await logs.printLogs("myFunction", "Something went wrong");
+// Persist error log to DB + notify Slack
+await logs.logError("myFunction", "Something went wrong", true);
 
-// Create activity record
+// Persist error log without Slack notification
+await logs.logError("myFunction", "Something went wrong");
+
+// Create a Directus activity record
 await logs.createActivity("create", "collection_name", "item_id");
 
-// Send notification (auto recipients from global settings)
+// Send Directus in-app notification (recipients from global settings)
 await logs.createNotification("An error occurred");
 
-// Send notification with custom subject
+// With custom subject
 await logs.createNotification("An error occurred", "Custom Subject");
 
-// Send notification to specific recipient
+// Override recipient
 await logs.createNotification("An error occurred", "Custom Subject", "user_id");
 
-// Send notification with related collection + item
+// With linked collection + item
 await logs.createNotification("An error occurred", "Custom Subject", null, "collection_name", "item_id");
+
+// Send Slack notification directly
+await logs.notifySlack("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,
@@ -79,44 +141,42 @@ constructor(
 )
 ```
 
-| Param            | Type                | Description                          |
-| ---------------- | ------------------- | ------------------------------------ |
-| `context`        | ApiExtensionContext | Directus extension context           |
-| `extension`      | string              | Name of your extension               |
-| `collectionName` | string (optional)   | Logs collection name (default: 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
 
-### Logging
+### `logError(functionName, error, notifySlack?)`
 
-- Saves structured logs into the logs collection
-- Automatically attaches timestamp and extension name
-- Fallback to console if DB write fails
+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)`
 
-### Activity Tracking
+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.
 
-- Uses Directus ActivityService
-- Automatically includes:
-    - user
-    - IP address
-    - user agent
-    - origin
+### `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:
 
-### 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
+- Custom or default subject with the project name appended
+- The message body
+- Environment label, backend URL, and UTC timestamp
+
+### `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/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,133 +1,2 @@
-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;
-        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;
-            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 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)");
-                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,23 @@
+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.
+     */
+    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, notifySlack?: boolean): Promise<void>;
+    notifySlack(message: string, customSubject?: string | null): Promise<void>;
+}

package/dist/services/Logs.js

@@ -0,0 +1,118 @@
+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",
+            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) {
+        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 logError(functionName, error, notifySlack = false) {
+        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.error({ 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}`, meta, "Extension Error");
+            }
+        }
+        catch (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();
+            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 (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 meta = await this.getProjectMeta();
+        await this.directus.notify(message, meta, {
+            subject: customSubject,
+            recipientOverride,
+            collection,
+            item,
+        });
+        try {
+            if (notifySlack) {
+                const meta = await this.getProjectMeta();
+                await this.slack.notify(`*Error:* ${message}`, meta, customSubject);
+            }
+        }
+        catch (err) {
+            this.context.logger.error({ msg: "Slack failed", error: err });
+        }
+    }
+    async notifySlack(message, customSubject = null) {
+        const meta = await this.getProjectMeta();
+        await this.slack.notify(message, meta, customSubject);
+    }
+}

package/dist/services/SlackNotifier.d.ts

@@ -0,0 +1,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);
+    private getEnvironmentIcon;
+    private buildBlocks;
+    send(payload: SlackPayload): Promise<void>;
+    notify(message: string, meta: ProjectMeta, subject?: string | null): Promise<void>;
+    private getConfig;
+    clearConfigCache(): void;
+}