ntfy-mcp-server 1.0.0

package/dist/services/ntfy/errors.js

@@ -0,0 +1,134 @@
+/**
+ * Custom error classes for the ntfy service
+ */
+import { BaseErrorCode, McpError } from '../../types-global/errors.js';
+import { ErrorHandler } from '../../utils/errorHandler.js';
+/**
+ * Get message from an error object
+ * @param error The error to extract message from
+ * @returns Error message as string
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (error === null) {
+        return 'Null error occurred';
+    }
+    if (error === undefined) {
+        return 'Undefined error occurred';
+    }
+    return typeof error === 'string'
+        ? error
+        : String(error);
+}
+/**
+ * Base error class for ntfy service errors
+ */
+export class NtfyError extends McpError {
+    constructor(message, details) {
+        const errorCode = details?.errorCode || BaseErrorCode.SERVICE_UNAVAILABLE;
+        super(errorCode, message, details);
+        this.name = 'NtfyError';
+    }
+}
+/**
+ * Error thrown when connection to ntfy server fails
+ */
+export class NtfyConnectionError extends NtfyError {
+    constructor(message, url) {
+        super(message, { url });
+        this.url = url;
+        this.name = 'NtfyConnectionError';
+    }
+}
+/**
+ * Error thrown when authentication fails
+ */
+export class NtfyAuthenticationError extends NtfyError {
+    constructor(message) {
+        super(message, { errorCode: BaseErrorCode.UNAUTHORIZED });
+        this.name = 'NtfyAuthenticationError';
+        this.code = BaseErrorCode.UNAUTHORIZED; // Ensure code is set correctly
+    }
+}
+/**
+ * Error thrown when a message cannot be parsed
+ */
+export class NtfyParseError extends NtfyError {
+    constructor(message, rawData) {
+        super(message, {
+            rawData: rawData?.substring(0, 100), // Truncate large data for logging
+            errorCode: BaseErrorCode.VALIDATION_ERROR
+        });
+        this.rawData = rawData;
+        this.name = 'NtfyParseError';
+        this.code = BaseErrorCode.VALIDATION_ERROR; // Ensure code is set correctly
+    }
+}
+/**
+ * Error thrown when a subscription is closed unexpectedly
+ */
+export class NtfySubscriptionClosedError extends NtfyError {
+    constructor(message, reason) {
+        super(message, { reason });
+        this.reason = reason;
+        this.name = 'NtfySubscriptionClosedError';
+    }
+}
+/**
+ * Error thrown when an invalid topic name is provided
+ */
+export class NtfyInvalidTopicError extends NtfyError {
+    constructor(message, topic) {
+        super(message, { topic, errorCode: BaseErrorCode.VALIDATION_ERROR });
+        this.topic = topic;
+        this.name = 'NtfyInvalidTopicError';
+        this.code = BaseErrorCode.VALIDATION_ERROR; // Ensure code is set correctly
+    }
+}
+/**
+ * Error thrown when a timeout occurs
+ */
+export class NtfyTimeoutError extends NtfyError {
+    constructor(message, timeoutMs) {
+        super(message, { timeoutMs, errorCode: BaseErrorCode.TIMEOUT });
+        this.timeoutMs = timeoutMs;
+        this.name = 'NtfyTimeoutError';
+        this.code = BaseErrorCode.TIMEOUT; // Ensure code is set correctly
+    }
+}
+/**
+ * Error mapping for ntfy errors
+ */
+export const NTFY_ERROR_MAPPINGS = [
+    {
+        pattern: /authentication|unauthorized|auth.*failed/i,
+        errorCode: BaseErrorCode.UNAUTHORIZED,
+        factory: (error) => new NtfyAuthenticationError(getErrorMessage(error))
+    },
+    {
+        pattern: /parse|invalid.*json|invalid.*format/i,
+        errorCode: BaseErrorCode.VALIDATION_ERROR,
+        factory: (error, context) => new NtfyParseError(getErrorMessage(error), context?.rawData)
+    },
+    {
+        pattern: /invalid.*topic/i,
+        errorCode: BaseErrorCode.VALIDATION_ERROR,
+        factory: (error, context) => new NtfyInvalidTopicError(getErrorMessage(error), context?.topic)
+    },
+    {
+        pattern: /timed out|timeout|deadline exceeded/i,
+        errorCode: BaseErrorCode.TIMEOUT,
+        factory: (error, context) => new NtfyTimeoutError(getErrorMessage(error), context?.timeoutMs)
+    },
+    {
+        pattern: /connection|network|failed to connect|refused/i,
+        errorCode: BaseErrorCode.SERVICE_UNAVAILABLE,
+        factory: (error, context) => new NtfyConnectionError(getErrorMessage(error), context?.url)
+    }
+];
+/**
+ * Create an error mapper function for ntfy errors
+ */
+export const ntfyErrorMapper = ErrorHandler.createErrorMapper(NTFY_ERROR_MAPPINGS, BaseErrorCode.SERVICE_UNAVAILABLE);

package/dist/services/ntfy/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Ntfy service for subscribing to and publishing messages to ntfy topics
+ *
+ * This module provides functionality to:
+ * 1. Subscribe to ntfy topics to receive notifications
+ * 2. Publish messages to ntfy topics
+ * 3. Utility functions for working with ntfy
+ */
+import { NtfySubscriber } from './subscriber.js';
+import { NtfySubscriptionHandlers, NtfySubscriptionOptions } from './types.js';
+import { publish, NtfyPublishOptions, NtfyPublishResponse } from './publisher.js';
+import { buildSubscriptionUrl, buildSubscriptionUrlSync, createBasicAuthHeader, createBasicAuthHeaderSync, isValidTopic, validateTopicSync } from './utils.js';
+import { DEFAULT_NTFY_BASE_URL, DEFAULT_SUBSCRIPTION_OPTIONS, DEFAULT_REQUEST_TIMEOUT } from './constants.js';
+export * from './types.js';
+export * from './errors.js';
+export { NtfySubscriber };
+export { publish, NtfyPublishOptions, NtfyPublishResponse };
+export { buildSubscriptionUrl, buildSubscriptionUrlSync, createBasicAuthHeader, createBasicAuthHeaderSync, isValidTopic, validateTopicSync };
+export { DEFAULT_NTFY_BASE_URL, DEFAULT_SUBSCRIPTION_OPTIONS, DEFAULT_REQUEST_TIMEOUT };
+/**
+ * Create a new ntfy subscriber with the given handlers
+ * @param handlers Event handlers for the subscription
+ * @returns A new NtfySubscriber instance
+ */
+export declare function createSubscriber(handlers?: NtfySubscriptionHandlers): NtfySubscriber;
+/**
+ * Subscribe to a ntfy topic
+ * @param topic Topic to subscribe to
+ * @param handlers Event handlers for the subscription
+ * @param options Subscription options
+ * @returns A function to unsubscribe
+ */
+export declare function subscribe(topic: string, handlers: NtfySubscriptionHandlers, options?: NtfySubscriptionOptions): Promise<() => void>;

package/dist/services/ntfy/index.js

@@ -0,0 +1,56 @@
+/**
+ * Ntfy service for subscribing to and publishing messages to ntfy topics
+ *
+ * This module provides functionality to:
+ * 1. Subscribe to ntfy topics to receive notifications
+ * 2. Publish messages to ntfy topics
+ * 3. Utility functions for working with ntfy
+ */
+import { NtfySubscriber } from './subscriber.js';
+import { publish } from './publisher.js';
+import { buildSubscriptionUrl, buildSubscriptionUrlSync, createBasicAuthHeader, createBasicAuthHeaderSync, isValidTopic, validateTopicSync } from './utils.js';
+import { createRequestContext } from '../../utils/requestContext.js';
+import { idGenerator } from '../../utils/idGenerator.js';
+import { DEFAULT_NTFY_BASE_URL, DEFAULT_SUBSCRIPTION_OPTIONS, DEFAULT_REQUEST_TIMEOUT } from './constants.js';
+// Export types
+export * from './types.js';
+export * from './errors.js';
+// Export main classes
+export { NtfySubscriber };
+// Export publisher functions
+export { publish };
+// Export utility functions
+export { 
+// Export both sync and async versions of utilities
+buildSubscriptionUrl, buildSubscriptionUrlSync, createBasicAuthHeader, createBasicAuthHeaderSync, isValidTopic, validateTopicSync };
+// Export constants
+export { DEFAULT_NTFY_BASE_URL, DEFAULT_SUBSCRIPTION_OPTIONS, DEFAULT_REQUEST_TIMEOUT };
+/**
+ * Create a new ntfy subscriber with the given handlers
+ * @param handlers Event handlers for the subscription
+ * @returns A new NtfySubscriber instance
+ */
+export function createSubscriber(handlers = {}) {
+    const requestCtx = createRequestContext({
+        operation: 'createSubscriber',
+        subscriberId: idGenerator.generateRandomString(8)
+    });
+    return new NtfySubscriber(handlers);
+}
+/**
+ * Subscribe to a ntfy topic
+ * @param topic Topic to subscribe to
+ * @param handlers Event handlers for the subscription
+ * @param options Subscription options
+ * @returns A function to unsubscribe
+ */
+export async function subscribe(topic, handlers, options = {}) {
+    const requestCtx = createRequestContext({
+        operation: 'subscribe',
+        topic,
+        subscriberId: idGenerator.generateRandomString(8)
+    });
+    const subscriber = new NtfySubscriber(handlers);
+    await subscriber.subscribe(topic, options);
+    return () => subscriber.unsubscribe();
+}

package/dist/services/ntfy/publisher.d.ts

@@ -0,0 +1,66 @@
+import { NtfyAction, NtfyAttachment, NtfyPriority } from './types.js';
+/**
+ * Options for publishing to ntfy topics
+ */
+export interface NtfyPublishOptions {
+    /** Base URL for the ntfy server */
+    baseUrl?: string;
+    /** Authentication token */
+    auth?: string;
+    /** Basic auth username */
+    username?: string;
+    /** Basic auth password */
+    password?: string;
+    /** Additional headers to include in requests */
+    headers?: Record<string, string>;
+    /** Message title */
+    title?: string;
+    /** Message tags (emojis) */
+    tags?: string[];
+    /** Message priority (1-5) */
+    priority?: NtfyPriority;
+    /** URL to open when notification is clicked */
+    click?: string;
+    /** Message actions (buttons, etc.) */
+    actions?: NtfyAction[];
+    /** Message attachment */
+    attachment?: NtfyAttachment;
+    /** Email addresses to send the notification to */
+    email?: string;
+    /** Delay the message for a specific time (e.g., 30m, 1h, tomorrow) */
+    delay?: string;
+    /** Cache the message for a specific duration (e.g., 10m, 1h, 1d) */
+    cache?: string;
+    /** Firebase Cloud Messaging (FCM) topic to forward to */
+    firebase?: string;
+    /** Unique ID for the message */
+    id?: string;
+    /** Message expiration (e.g., 10m, 1h, 1d) */
+    expires?: string;
+    /** Whether the message should be X-Forwarded */
+    markdown?: boolean;
+}
+/**
+ * Response from publishing to ntfy
+ */
+export interface NtfyPublishResponse {
+    /** Server-assigned message ID */
+    id: string;
+    /** Time the message was received */
+    time: number;
+    /** Message expiration timestamp (if set) */
+    expires?: number;
+    /** Topic the message was published to */
+    topic: string;
+}
+/**
+ * Publish a message to a ntfy topic
+ *
+ * @param topic - Topic to publish to
+ * @param message - Message to publish
+ * @param options - Publishing options
+ * @returns Promise resolving to the publish response
+ * @throws NtfyInvalidTopicError if the topic name is invalid
+ * @throws NtfyConnectionError if the connection fails
+ */
+export declare function publish(topic: string, message: string, options?: NtfyPublishOptions): Promise<NtfyPublishResponse>;

package/dist/services/ntfy/publisher.js

@@ -0,0 +1,229 @@
+/**
+ * Ntfy publisher implementation for sending notifications
+ */
+import { DEFAULT_NTFY_BASE_URL, DEFAULT_REQUEST_TIMEOUT, ERROR_MESSAGES } from './constants.js';
+import { NtfyAuthenticationError, NtfyConnectionError, NtfyInvalidTopicError, ntfyErrorMapper } from './errors.js';
+import { createTimeout, validateTopicSync, createRequestHeadersSync } from './utils.js';
+import { BaseErrorCode, McpError } from '../../types-global/errors.js';
+import { ErrorHandler } from '../../utils/errorHandler.js';
+import { logger } from '../../utils/logger.js';
+import { sanitizeInput, sanitizeInputForLogging } from '../../utils/sanitization.js';
+import { createRequestContext } from '../../utils/requestContext.js';
+import { idGenerator } from '../../utils/idGenerator.js';
+// Create a module-specific logger
+const publisherLogger = logger.createChildLogger({
+    module: 'NtfyPublisher',
+    serviceId: idGenerator.generateRandomString(8)
+});
+/**
+ * Publish a message to a ntfy topic
+ *
+ * @param topic - Topic to publish to
+ * @param message - Message to publish
+ * @param options - Publishing options
+ * @returns Promise resolving to the publish response
+ * @throws NtfyInvalidTopicError if the topic name is invalid
+ * @throws NtfyConnectionError if the connection fails
+ */
+export async function publish(topic, message, options = {}) {
+    return ErrorHandler.tryCatch(async () => {
+        // Create request context for tracking
+        const requestCtx = createRequestContext({
+            operation: 'publishNtfyMessage',
+            topic,
+            messageLength: message?.length,
+            hasTitle: !!options.title,
+            hasTags: Array.isArray(options.tags) && options.tags.length > 0,
+            priority: options.priority,
+            publishId: idGenerator.generateRandomString(8)
+        });
+        publisherLogger.info('Publishing message', {
+            topic,
+            messageLength: message?.length,
+            hasTitle: !!options.title,
+            hasTags: Array.isArray(options.tags) && options.tags.length > 0,
+            priority: options.priority,
+            requestId: requestCtx.requestId
+        });
+        // Validate topic synchronously for better performance
+        if (!validateTopicSync(topic)) {
+            publisherLogger.error('Invalid topic name', {
+                topic,
+                requestId: requestCtx.requestId
+            });
+            throw new NtfyInvalidTopicError(ERROR_MESSAGES.INVALID_TOPIC, topic);
+        }
+        // Build URL
+        const baseUrl = sanitizeInput.url(options.baseUrl || DEFAULT_NTFY_BASE_URL);
+        const url = `${baseUrl}/${sanitizeInput.string(topic)}`;
+        publisherLogger.debug('Publishing to URL', {
+            url,
+            requestId: requestCtx.requestId
+        });
+        // Prepare headers - using sync version for performance
+        const initialHeaders = createRequestHeadersSync({
+            auth: options.auth,
+            username: options.username,
+            password: options.password,
+            headers: options.headers,
+        });
+        // Convert HeadersInit to a Record for easier manipulation
+        const headers = {};
+        // Copy initial headers to our record object
+        if (initialHeaders instanceof Headers) {
+            initialHeaders.forEach((value, key) => {
+                headers[key] = value;
+            });
+        }
+        else if (Array.isArray(initialHeaders)) {
+            for (const [key, value] of initialHeaders) {
+                headers[key] = value;
+            }
+        }
+        else if (initialHeaders) {
+            Object.assign(headers, initialHeaders);
+        }
+        // Set content type
+        headers['Content-Type'] = 'text/plain';
+        // Add special headers for ntfy features
+        if (options.title) {
+            headers['X-Title'] = sanitizeInput.string(options.title);
+        }
+        if (options.tags && options.tags.length > 0) {
+            // Sanitize each tag
+            const sanitizedTags = options.tags.map(tag => sanitizeInput.string(tag));
+            headers['X-Tags'] = sanitizedTags.join(',');
+        }
+        if (options.priority) {
+            headers['X-Priority'] = options.priority.toString();
+        }
+        if (options.click) {
+            headers['X-Click'] = sanitizeInput.url(options.click);
+        }
+        if (options.actions && options.actions.length > 0) {
+            // We need to sanitize the actions
+            const sanitizedActions = options.actions.map(action => ({
+                id: sanitizeInput.string(action.id),
+                label: sanitizeInput.string(action.label),
+                action: sanitizeInput.string(action.action),
+                url: action.url ? sanitizeInput.url(action.url) : undefined,
+                method: action.method ? sanitizeInput.string(action.method) : undefined,
+                headers: action.headers,
+                body: action.body ? sanitizeInput.string(action.body) : undefined,
+                clear: action.clear
+            }));
+            headers['X-Actions'] = JSON.stringify(sanitizedActions);
+        }
+        if (options.attachment) {
+            headers['X-Attach'] = sanitizeInput.url(options.attachment.url);
+            if (options.attachment.name) {
+                headers['X-Filename'] = sanitizeInput.string(options.attachment.name);
+            }
+        }
+        if (options.email) {
+            headers['X-Email'] = sanitizeInput.string(options.email);
+        }
+        if (options.delay) {
+            headers['X-Delay'] = sanitizeInput.string(options.delay);
+        }
+        if (options.cache) {
+            headers['X-Cache'] = sanitizeInput.string(options.cache);
+        }
+        if (options.firebase) {
+            headers['X-Firebase'] = sanitizeInput.string(options.firebase);
+        }
+        if (options.id) {
+            headers['X-ID'] = sanitizeInput.string(options.id);
+        }
+        if (options.expires) {
+            headers['X-Expires'] = sanitizeInput.string(options.expires);
+        }
+        if (options.markdown) {
+            headers['X-Markdown'] = 'true';
+        }
+        // Send request with timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), DEFAULT_REQUEST_TIMEOUT);
+        try {
+            publisherLogger.debug('Sending HTTP request', {
+                url,
+                method: 'POST',
+                requestId: requestCtx.requestId
+            });
+            const response = await Promise.race([
+                fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: message,
+                    signal: controller.signal,
+                }),
+                createTimeout(DEFAULT_REQUEST_TIMEOUT),
+            ]);
+            clearTimeout(timeoutId);
+            // Check response status
+            if (!response.ok) {
+                publisherLogger.error('HTTP error from ntfy server', {
+                    status: response.status,
+                    statusText: response.statusText,
+                    url,
+                    requestId: requestCtx.requestId
+                });
+                // Provide more specific error messages based on status code
+                let errorMessage = `HTTP Error: ${response.status} ${response.statusText}`;
+                switch (response.status) {
+                    case 401:
+                        errorMessage = 'Authentication failed: invalid credentials';
+                        throw new NtfyAuthenticationError(errorMessage);
+                    case 403:
+                        errorMessage = 'Access forbidden: insufficient permissions';
+                        throw new McpError(BaseErrorCode.FORBIDDEN, errorMessage, { url, statusCode: response.status });
+                    case 404:
+                        errorMessage = 'Topic or resource not found';
+                        throw new McpError(BaseErrorCode.NOT_FOUND, errorMessage, { url, statusCode: response.status, topic });
+                    case 429:
+                        errorMessage = 'Too many requests: rate limit exceeded';
+                        throw new McpError(BaseErrorCode.RATE_LIMITED, errorMessage, { url, statusCode: response.status });
+                    case 500:
+                    case 502:
+                    case 503:
+                    case 504:
+                        errorMessage = `Server error: ${response.statusText}`;
+                    // Fall through to default error handling
+                    default:
+                        throw new NtfyConnectionError(errorMessage, url);
+                }
+            }
+            // Parse response
+            const result = await response.json();
+            publisherLogger.info('Message published successfully', {
+                messageId: result.id,
+                topic: result.topic,
+                requestId: requestCtx.requestId
+            });
+            return result;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof NtfyInvalidTopicError) {
+                throw error;
+            }
+            publisherLogger.error('Failed to publish message', {
+                error: error instanceof Error ? error.message : String(error),
+                topic,
+                url,
+                requestId: requestCtx.requestId
+            });
+            throw new NtfyConnectionError(`Error publishing to topic: ${error instanceof Error ? error.message : String(error)}`, url);
+        }
+    }, {
+        operation: 'publishNtfyMessage',
+        context: { topic },
+        input: {
+            message: message?.length > 100 ? `${message.substring(0, 100)}...` : message,
+            options: sanitizeInputForLogging(options)
+        },
+        errorCode: BaseErrorCode.SERVICE_UNAVAILABLE,
+        errorMapper: ntfyErrorMapper,
+        rethrow: true
+    });
+}

package/dist/services/ntfy/subscriber.d.ts

@@ -0,0 +1,81 @@
+import { NtfySubscriptionHandlers, NtfySubscriptionOptions } from './types.js';
+/**
+ * NtfySubscriber class for subscribing to ntfy topics
+ */
+export declare class NtfySubscriber {
+    private handlers;
+    private abortController?;
+    private cleanupFn?;
+    private connectionActive;
+    private lastKeepaliveTime;
+    private reconnectAttempts;
+    private keepaliveCheckInterval?;
+    private logger;
+    private subscriberId;
+    private currentTopic?;
+    /**
+     * Creates a new NtfySubscriber instance
+     * @param handlers Event handlers for the subscription
+     */
+    constructor(handlers?: NtfySubscriptionHandlers);
+    /**
+     * Subscribe to a ntfy topic
+     * @param topic Topic to subscribe to (can be comma-separated for multiple topics)
+     * @param options Subscription options
+     * @returns Promise that resolves when the subscription is established
+     * @throws NtfyInvalidTopicError if the topic name is invalid
+     * @throws NtfyConnectionError if the connection fails
+     */
+    subscribe(topic: string, options?: NtfySubscriptionOptions): Promise<void>;
+    /**
+     * Unsubscribe from the current topic
+     */
+    unsubscribe(): void;
+    /**
+     * Start a subscription to a topic
+     * @param topic Topic to subscribe to
+     * @param format Format to subscribe in (json, sse, raw, ws)
+     * @param options Subscription options
+     */
+    private startSubscription;
+    /**
+     * Process a JSON stream from ntfy
+     * @param reader ReadableStreamDefaultReader to read from
+     * @param requestId Request ID for logging
+     */
+    private processJsonStream;
+    /**
+     * Handle a message from ntfy
+     * @param message Message from ntfy
+     * @param requestId Request ID for logging
+     */
+    private handleMessage;
+    /**
+     * Handle a parse error
+     * @param error Error that occurred
+     * @param rawData Raw data that caused the error
+     * @param requestId Request ID for logging
+     */
+    private handleParseError;
+    /**
+     * Handle a subscription error
+     * @param error Error that occurred
+     * @param requestId Request ID for logging
+     */
+    private handleSubscriptionError;
+    /**
+     * Start the keepalive check interval
+     */
+    private startKeepaliveCheck;
+    /**
+     * Stop the keepalive check interval
+     */
+    private stopKeepaliveCheck;
+    /**
+     * Schedule a reconnection attempt
+     * @param topic Topic to reconnect to
+     * @param format Format to reconnect with
+     * @param options Subscription options
+     */
+    private scheduleReconnect;
+}