arcanajs 3.0.1 → 5.0.0

package/dist/lib/mail/MailService.d.ts

@@ -0,0 +1,57 @@
+import { Mailable } from "./Mailable";
+import { MailConfig, MailMessage } from "./types";
+/**
+ * Core mail service for sending emails
+ */
+export declare class MailService {
+    private static config?;
+    private static transporter?;
+    /**
+     * Initialize the mail service
+     */
+    static init(config: MailConfig): Promise<void>;
+    /**
+     * Create nodemailer transporter based on configuration
+     */
+    private static createTransporter;
+    /**
+     * Create SMTP transporter
+     */
+    private static createSMTPTransporter;
+    /**
+     * Create SendGrid transporter
+     */
+    private static createSendGridTransporter;
+    /**
+     * Create Mailgun transporter
+     */
+    private static createMailgunTransporter;
+    /**
+     * Create AWS SES transporter
+     */
+    private static createSESTransporter;
+    /**
+     * Create log-only transporter (for testing)
+     */
+    private static createLogTransporter;
+    /**
+     * Send an email immediately
+     */
+    static send(mailable: Mailable | MailMessage): Promise<void>;
+    /**
+     * Queue an email for async sending
+     */
+    static queue(mailable: Mailable): Promise<void>;
+    /**
+     * Send a raw email message
+     */
+    static sendRaw(message: MailMessage): Promise<void>;
+    /**
+     * Get the mail configuration
+     */
+    static getConfig(): MailConfig | undefined;
+    /**
+     * Verify transporter connection
+     */
+    static verify(): Promise<boolean>;
+}

package/dist/lib/mail/Mailable.d.ts

@@ -0,0 +1,106 @@
+import { MailAttachment, MailMessage } from "./types";
+/**
+ * Abstract base class for creating email messages
+ *
+ * @example
+ * ```typescript
+ * class WelcomeEmail extends Mailable {
+ *   constructor(private user: User) {
+ *     super();
+ *   }
+ *
+ *   build() {
+ *     return this
+ *       .to(this.user.email)
+ *       .subject('Welcome to ArcanaJS!')
+ *       .view('emails/welcome', { name: this.user.name });
+ *   }
+ * }
+ *
+ * // Send the email
+ * await new WelcomeEmail(user).send();
+ * ```
+ */
+export declare abstract class Mailable {
+    protected message: Partial<MailMessage>;
+    protected viewName?: string;
+    protected viewData?: Record<string, any>;
+    /**
+     * Build the email message
+     * Must be implemented by subclasses
+     */
+    abstract build(): this;
+    /**
+     * Set the recipient(s)
+     */
+    to(address: string | string[], name?: string): this;
+    /**
+     * Set the sender
+     */
+    from(address: string, name?: string): this;
+    /**
+     * Set the email subject
+     */
+    subject(subject: string): this;
+    /**
+     * Set the email view template
+     */
+    view(template: string, data?: Record<string, any>): this;
+    /**
+     * Set HTML content directly
+     */
+    html(content: string): this;
+    /**
+     * Set plain text content
+     */
+    text(content: string): this;
+    /**
+     * Add CC recipient(s)
+     */
+    cc(address: string | string[]): this;
+    /**
+     * Add BCC recipient(s)
+     */
+    bcc(address: string | string[]): this;
+    /**
+     * Set reply-to address
+     */
+    replyTo(address: string): this;
+    /**
+     * Add an attachment
+     */
+    attach(attachment: MailAttachment): this;
+    /**
+     * Attach a file from path
+     */
+    attachFromPath(path: string, filename?: string): this;
+    /**
+     * Attach data as a file
+     */
+    attachData(content: string | Buffer, filename: string, contentType?: string): this;
+    /**
+     * Set email priority
+     */
+    priority(level: "high" | "normal" | "low"): this;
+    /**
+     * Add custom headers
+     */
+    withHeaders(headers: Record<string, string>): this;
+    /**
+     * Get the built message
+     * @internal
+     */
+    getMessage(): {
+        message: Partial<MailMessage>;
+        viewName?: string;
+        viewData?: Record<string, any>;
+    };
+    /**
+     * Send the email immediately
+     */
+    send(): Promise<void>;
+    /**
+     * Queue the email for async sending
+     */
+    queue(): Promise<void>;
+}

package/dist/lib/mail/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./Mailable";
+export * from "./MailProvider";
+export * from "./MailService";
+export * from "./queue";
+export * from "./types";
+export * from "./utils";

package/dist/lib/mail/queue/MailQueue.d.ts

@@ -0,0 +1,51 @@
+import { Mailable } from "../Mailable";
+import { MailQueueConfig } from "../types";
+/**
+ * Mail queue for async email processing
+ */
+export declare class MailQueue {
+    private static config?;
+    private static queue;
+    private static processing;
+    private static redisClient?;
+    /**
+     * Initialize the mail queue
+     */
+    static init(config: MailQueueConfig): Promise<void>;
+    /**
+     * Initialize Redis connection
+     */
+    private static initRedis;
+    /**
+     * Add a job to the queue
+     */
+    static add(mailable: Mailable): Promise<void>;
+    /**
+     * Start processing the queue
+     */
+    private static startProcessing;
+    /**
+     * Process next job in queue
+     */
+    private static processNext;
+    /**
+     * Handle failed job
+     */
+    private static handleFailedJob;
+    /**
+     * Store failed job for manual review
+     */
+    private static storeFailedJob;
+    /**
+     * Generate unique job ID
+     */
+    private static generateId;
+    /**
+     * Get queue size
+     */
+    static size(): Promise<number>;
+    /**
+     * Clear the queue
+     */
+    static clear(): Promise<void>;
+}

package/dist/lib/mail/queue/index.d.ts

@@ -0,0 +1 @@
+export * from "./MailQueue";

package/dist/lib/mail/types/MailConfig.d.ts

@@ -0,0 +1,146 @@
+import { Transporter } from "nodemailer";
+/**
+ * Supported mail transport drivers
+ */
+export type MailDriver = "smtp" | "sendgrid" | "mailgun" | "ses" | "log";
+/**
+ * SMTP Configuration
+ */
+export interface SMTPConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    tls?: {
+        rejectUnauthorized?: boolean;
+    };
+}
+/**
+ * SendGrid Configuration
+ */
+export interface SendGridConfig {
+    apiKey: string;
+}
+/**
+ * Mailgun Configuration
+ */
+export interface MailgunConfig {
+    apiKey: string;
+    domain: string;
+    host?: string;
+}
+/**
+ * AWS SES Configuration
+ */
+export interface SESConfig {
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/**
+ * Mail Queue Configuration
+ */
+export interface MailQueueConfig {
+    enabled: boolean;
+    driver: "memory" | "redis";
+    redis?: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+    };
+    retries?: number;
+    retryDelay?: number;
+}
+/**
+ * Mail Template Configuration
+ */
+export interface MailTemplateConfig {
+    engine: "ejs" | "handlebars";
+    viewsPath: string;
+    layoutsPath?: string;
+    defaultLayout?: string;
+    inlineCss?: boolean;
+}
+/**
+ * Default Sender Configuration
+ */
+export interface MailFromConfig {
+    address: string;
+    name?: string;
+}
+/**
+ * Main Mail Configuration
+ */
+export interface MailConfig {
+    /**
+     * Default mail driver to use
+     */
+    default: MailDriver;
+    /**
+     * Default "from" address and name
+     */
+    from: MailFromConfig;
+    /**
+     * SMTP Configuration
+     */
+    smtp?: SMTPConfig;
+    /**
+     * SendGrid Configuration
+     */
+    sendgrid?: SendGridConfig;
+    /**
+     * Mailgun Configuration
+     */
+    mailgun?: MailgunConfig;
+    /**
+     * AWS SES Configuration
+     */
+    ses?: SESConfig;
+    /**
+     * Queue Configuration
+     */
+    queue?: MailQueueConfig;
+    /**
+     * Template Configuration
+     */
+    templates?: MailTemplateConfig;
+    /**
+     * Reply-to address
+     */
+    replyTo?: MailFromConfig;
+}
+/**
+ * Mail Message Options
+ */
+export interface MailMessage {
+    to: string | string[];
+    from?: MailFromConfig;
+    subject: string;
+    html?: string;
+    text?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    attachments?: MailAttachment[];
+    headers?: Record<string, string>;
+    priority?: "high" | "normal" | "low";
+}
+/**
+ * Mail Attachment
+ */
+export interface MailAttachment {
+    filename: string;
+    content?: string | Buffer;
+    path?: string;
+    contentType?: string;
+    cid?: string;
+}
+/**
+ * Nodemailer Transporter Type
+ */
+export type MailTransporter = Transporter;

package/dist/lib/mail/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./MailConfig";

package/dist/lib/mail/utils/TemplateRenderer.d.ts

@@ -0,0 +1,34 @@
+import { MailTemplateConfig } from "../types";
+/**
+ * Template renderer for email views
+ */
+export declare class TemplateRenderer {
+    private static config?;
+    /**
+     * Initialize the template renderer
+     */
+    static init(config: MailTemplateConfig): void;
+    /**
+     * Render a template to HTML
+     */
+    static render(templateName: string, data?: Record<string, any>): Promise<{
+        html: string;
+        text: string;
+    }>;
+    /**
+     * Render EJS template
+     */
+    private static renderEJS;
+    /**
+     * Render Handlebars template
+     */
+    private static renderHandlebars;
+    /**
+     * Apply layout to rendered content
+     */
+    private static applyLayout;
+    /**
+     * Convert HTML to plain text
+     */
+    private static htmlToText;
+}

package/dist/lib/mail/utils/index.d.ts

@@ -0,0 +1 @@
+export * from "./TemplateRenderer";

package/dist/lib/server/ArcanaJSServer.d.ts

@@ -1,6 +1,7 @@
 import { Express, RequestHandler } from "express";
 import React from "react";
-export interface ArcanaJSConfig<TDb = any> {
+import { ServiceProvider } from "./support/ServiceProvider";
+export interface ArcanaJSConfig {
     port?: number | string;
     views?: Record<string, React.FC<any>>;
     viewsDir?: string;
@@ -14,39 +15,71 @@ export interface ArcanaJSConfig<TDb = any> {
     distDir?: string;
     indexFile?: string;
     layout?: React.FC<any>;
-    /** Optional function to establish a DB connection. Should return a Promise resolving to the DB client/connection. */
-    dbConnect?: () => Promise<TDb> | TDb;
     /** Automatically register SIGINT/SIGTERM handlers to call stop(). Default: true */
     autoHandleSignals?: boolean;
+    /** Auth configuration */
+    auth?: any;
+    /** Mail configuration */
+    mail?: any;
+    /** Database configuration */
+    database?: any;
+    /** Service providers to load */
+    providers?: (new (app: ArcanaJSServer) => ServiceProvider)[];
 }
 declare global {
     namespace Express {
-        interface Request {
+        interface Response {
             /**
-             * Normalized DB object optionally attached to the request by ArcanaJSServer.
-             * It may be either the raw client, or an object like `{ client, db, close }`.
+             * Sends a success response with a standard format.
+             *
+             * @param data - The data payload to include in the response (default: {}).
+             * @param message - A descriptive message for the success (default: "Success").
+             * @param status - The HTTP status code to return (default: 200).
+             * @returns The Express Response object.
              */
-            db?: any;
+            success: (data?: string | object | null, message?: string, status?: number) => Response;
+            /**
+             * Sends an error response with a standard format.
+             *
+             * @param message - A descriptive message for the error (default: "Error").
+             * @param status - The HTTP status code to return (default: 500).
+             * @param error - Additional error details or object (default: null).
+             * @param data - Optional data payload to include in the error response (default: null).
+             * @returns The Express Response object.
+             */
+            error: (message?: string, status?: number, error?: string | object | null | undefined | unknown, data?: string | object | null) => Response;
+            /**
+             * Renders a React page using ArcanaJS SSR.
+             *
+             * @param page - The name of the page component to render.
+             * @param data - Initial data to pass to the page component (default: {}).
+             * @param params - Route parameters (default: {}).
+             * @returns The Express Response object.
+             */
+            renderPage(page: string, data?: any, params?: Record<string, string>): Response;
         }
     }
 }
-declare class ArcanaJSServer<TDb = any> {
+import { Container } from "./Container";
+declare class ArcanaJSServer {
     app: Express;
+    container: Container;
     private config;
     private serverInstance?;
     private _sigintHandler?;
     private _sigtermHandler?;
-    constructor(config: ArcanaJSConfig<TDb>);
-    /**
-     * Normalize different DB client shapes into a single object exposing:
-     * { client?: any, db?: any, close: async () => void }
-     */
-    private normalizeDb;
-    private initialize;
+    private providers;
+    private initialized;
+    constructor(config: ArcanaJSConfig);
+    private initializeAsync;
+    private loadConfigurations;
+    private registerProviders;
+    private bootProviders;
+    private setupMiddleware;
     private loadViewsFromContext;
     private loadViewsFromAlias;
     private discoverViews;
-    start(): void;
+    start(): Promise<void>;
     /**
      * Stop the HTTP server and close DB connection if present.
      */

package/dist/lib/server/Container.d.ts

@@ -0,0 +1,39 @@
+import "reflect-metadata";
+export type ClassConstructor<T = any> = new (...args: any[]) => T;
+export type FactoryFunction<T = any> = (container: Container) => T;
+export declare class Container {
+    private static instance;
+    private bindings;
+    private singletons;
+    constructor();
+    /**
+     * Get the global container instance
+     */
+    static getInstance(): Container;
+    /**
+     * Bind a class or factory to the container
+     */
+    bind<T>(key: string | ClassConstructor<T>, value: ClassConstructor<T> | FactoryFunction<T>): void;
+    /**
+     * Bind a singleton to the container
+     */
+    singleton<T>(key: string | ClassConstructor<T>, value: ClassConstructor<T> | FactoryFunction<T>): void;
+    /**
+     * Resolve a dependency from the container
+     */
+    make<T>(key: string | ClassConstructor<T>): T;
+    /**
+     * Check if a service is registered in the container
+     */
+    has(key: string | ClassConstructor): boolean;
+    /**
+     * Alias for make() - resolve a dependency from the container
+     */
+    resolve<T>(key: string | ClassConstructor<T>): T;
+    /**
+     * Instantiate a class, resolving its dependencies
+     */
+    private build;
+    private isConstructor;
+}
+export declare const container: Container;

package/dist/lib/server/MiddlewareBinder.d.ts

@@ -0,0 +1,4 @@
+import { NextFunction, Request, Response } from "express";
+export default class MiddlewareBinder {
+    static handle(middleware: any, method?: string): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+}

package/dist/lib/server/ResponseHandlerMiddleware.d.ts

@@ -1,27 +1,2 @@
 import type { NextFunction, Request, Response } from "express";
-declare global {
-    namespace Express {
-        interface Response {
-            /**
-             * Sends a success response with a standard format.
-             *
-             * @param data - The data payload to include in the response (default: {}).
-             * @param message - A descriptive message for the success (default: "Success").
-             * @param status - The HTTP status code to return (default: 200).
-             * @returns The Express Response object.
-             */
-            success: (data?: string | object | null, message?: string, status?: number) => Response;
-            /**
-             * Sends an error response with a standard format.
-             *
-             * @param message - A descriptive message for the error (default: "Error").
-             * @param status - The HTTP status code to return (default: 500).
-             * @param error - Additional error details or object (default: null).
-             * @param data - Optional data payload to include in the error response (default: null).
-             * @returns The Express Response object.
-             */
-            error: (message?: string, status?: number, error?: string | object | null, data?: string | object | null) => Response;
-        }
-    }
-}
 export declare const responseHandler: (req: Request, res: Response, next: NextFunction) => void;