@iskra-bun/web-kit 0.1.0

package/src/features/email/index.ts

@@ -0,0 +1,103 @@
+import type { Feature } from "../../types";
+import type { Kernel } from "../../kernel";
+import type { Context, Next } from "hono";
+
+export interface EmailConfig {
+    provider: "smtp" | "sendgrid" | "mock" | "mailgun" | "ses";
+    smtp?: {
+        host: string;
+        port: number;
+        username: string;
+        password: string;
+        secure?: boolean;
+    };
+    apiKey?: string;
+    apiSecret?: string;
+    region?: string;
+    domain?: string;
+    baseUrl?: string;
+    from?: { name?: string; email: string };
+    templateDir?: string;
+}
+
+export interface EmailMessage {
+    to: string | string[];
+    from?: { name?: string; email: string };
+    subject: string;
+    text?: string;
+    html?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    attachments?: Array<{ filename: string; content: Uint8Array | string; contentType?: string }>;
+    headers?: Record<string, string>;
+}
+
+export interface TemplateData {
+    [key: string]: unknown;
+}
+
+export interface EmailAdapter {
+    send(message: EmailMessage): Promise<{ messageId: string; success: boolean }>;
+    sendTemplate(templateName: string, to: string | string[], data: TemplateData): Promise<{ messageId: string; success: boolean }>;
+}
+
+class MockEmailAdapter implements EmailAdapter {
+    async send(message: EmailMessage) {
+        console.log("📧 [MOCK] Sent to", message.to, "Subject:", message.subject);
+        return { messageId: `mock-${Date.now()}`, success: true };
+    }
+    async sendTemplate(name: string, to: string | string[], data: TemplateData) {
+        return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });
+    }
+}
+
+declare module "hono" {
+    interface ContextVariableMap {
+        email: EmailAdapter;
+    }
+}
+
+export class EmailFeature implements Feature {
+    name = "email";
+    private adapter?: EmailAdapter;
+
+    constructor(private config: EmailConfig) { }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        this.adapter = await this.createAdapter(this.config);
+        const app = kernel.getApp();
+        app.use("*", async (c: Context, next: Next) => {
+            if (this.adapter) c.set("email", this.adapter);
+            await next();
+        });
+        console.log(`✅ EmailFeature initialized (${this.config.provider})`);
+    }
+
+    private async createAdapter(config: EmailConfig): Promise<EmailAdapter> {
+        switch (config.provider) {
+            case "mock": return new MockEmailAdapter();
+            case "smtp": {
+                // Lazy load to avoid import issues if not installed/configured in all envs (though we added deps)
+                const { SmtpEmailAdapter } = await import("./providers/smtp");
+                return new SmtpEmailAdapter(config);
+            }
+            case "sendgrid": {
+                const { SendGridEmailAdapter } = await import("./providers/sendgrid");
+                return new SendGridEmailAdapter(config);
+            }
+            case "mailgun": {
+                const { MailgunEmailAdapter } = await import("./providers/mailgun");
+                return new MailgunEmailAdapter(config);
+            }
+            default: throw new Error(`Provider ${config.provider} not implemented`);
+        }
+    }
+
+    getAdapter(): EmailAdapter {
+        if (!this.adapter) throw new Error("Email not initialized");
+        return this.adapter;
+    }
+}
+
+export { MockEmailAdapter };

package/src/features/email/providers/mailgun.ts

@@ -0,0 +1,99 @@
+import type { EmailAdapter, EmailMessage, EmailConfig, TemplateData } from "../index";
+
+export class MailgunEmailAdapter implements EmailAdapter {
+    private apiKey: string;
+    private domain: string;
+    private baseUrl: string;
+    private defaultFrom?: { name?: string; email: string };
+
+    constructor(config: EmailConfig) {
+        if (!config.apiKey) throw new Error("Mailgun requires apiKey");
+        if (!config.domain) throw new Error("Mailgun requires domain");
+
+        this.apiKey = config.apiKey;
+        this.domain = config.domain;
+        this.baseUrl = config.baseUrl || "https://api.mailgun.net/v3";
+        this.defaultFrom = config.from;
+    }
+
+    async send(message: EmailMessage): Promise<{ messageId: string; success: boolean }> {
+        const form = new FormData();
+
+        const from = message.from || this.defaultFrom;
+        if (from) {
+            form.append("from", from.name ? `${from.name} <${from.email}>` : from.email);
+        }
+
+        const to = Array.isArray(message.to) ? message.to.join(",") : message.to;
+        form.append("to", to);
+        form.append("subject", message.subject);
+
+        if (message.text) form.append("text", message.text);
+        if (message.html) form.append("html", message.html);
+        if (message.cc) form.append("cc", Array.isArray(message.cc) ? message.cc.join(",") : message.cc);
+        if (message.bcc) form.append("bcc", Array.isArray(message.bcc) ? message.bcc.join(",") : message.bcc);
+        if (message.replyTo) form.append("h:Reply-To", message.replyTo);
+
+        if (message.headers) {
+            for (const [key, value] of Object.entries(message.headers)) {
+                form.append(`h:${key}`, value);
+            }
+        }
+
+        if (message.attachments) {
+            for (const att of message.attachments) {
+                const content = typeof att.content === "string"
+                    ? new TextEncoder().encode(att.content)
+                    : att.content;
+                const bytes = new Uint8Array(content);
+                const blob = new Blob([bytes], { type: att.contentType || "application/octet-stream" });
+                form.append("attachment", blob, att.filename);
+            }
+        }
+
+        const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
+            method: "POST",
+            headers: {
+                Authorization: "Basic " + btoa(`api:${this.apiKey}`),
+            },
+            body: form,
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Mailgun API error (${response.status}): ${errorText}`);
+        }
+
+        const result = await response.json() as { id: string; message: string };
+        return { messageId: result.id, success: true };
+    }
+
+    async sendTemplate(templateName: string, to: string | string[], data: TemplateData): Promise<{ messageId: string; success: boolean }> {
+        const form = new FormData();
+
+        if (this.defaultFrom) {
+            const from = this.defaultFrom;
+            form.append("from", from.name ? `${from.name} <${from.email}>` : from.email);
+        }
+
+        form.append("to", Array.isArray(to) ? to.join(",") : to);
+        form.append("template", templateName);
+        form.append("h:X-Mailgun-Variables", JSON.stringify(data));
+
+        const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
+            method: "POST",
+            headers: {
+                Authorization: "Basic " + btoa(`api:${this.apiKey}`),
+            },
+            body: form,
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Mailgun API error (${response.status}): ${errorText}`);
+        }
+
+        const result = await response.json() as { id: string; message: string };
+        return { messageId: result.id, success: true };
+    }
+}

package/src/features/email/providers/sendgrid.ts

@@ -0,0 +1,42 @@
+import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from "../index";
+import sgMail from "@sendgrid/mail";
+
+export class SendGridEmailAdapter implements EmailAdapter {
+    constructor(private config: EmailConfig) {
+        if (!config.apiKey) throw new Error("SendGrid API Key required");
+        sgMail.setApiKey(config.apiKey);
+    }
+
+    async send(message: EmailMessage) {
+        const from = message.from || this.config.from;
+        if (!from) throw new Error("From address required");
+
+        const msg = {
+            to: message.to,
+            from: from.name ? { email: from.email, name: from.name } : from.email,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            cc: message.cc as any,
+            bcc: message.bcc as any,
+            replyTo: message.replyTo,
+            attachments: message.attachments?.map(a => ({
+                filename: a.filename,
+                content: typeof a.content === 'string' ? a.content : Buffer.from(a.content).toString("base64"),
+                type: a.contentType,
+                disposition: "attachment"
+            }))
+        } as any;
+
+        const [response] = await sgMail.send(msg);
+        return { messageId: response.headers["x-message-id"] as string, success: true };
+    }
+
+    async sendTemplate(templateName: string, to: string | string[], data: TemplateData) {
+        return this.send({
+            to,
+            subject: `Template: ${templateName}`,
+            html: `<p>Template ${templateName} rendered with ${JSON.stringify(data)}</p>`
+        });
+    }
+}

package/src/features/email/providers/smtp.ts

@@ -0,0 +1,51 @@
+import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from "../index";
+import * as nodemailer from "nodemailer";
+
+export class SmtpEmailAdapter implements EmailAdapter {
+    private transporter: nodemailer.Transporter;
+
+    constructor(private config: EmailConfig) {
+        if (!config.smtp) throw new Error("SMTP config required");
+        this.transporter = nodemailer.createTransport({
+            host: config.smtp.host,
+            port: config.smtp.port,
+            secure: config.smtp.secure ?? false,
+            auth: {
+                user: config.smtp.username,
+                pass: config.smtp.password
+            }
+        });
+    }
+
+    async send(message: EmailMessage) {
+        const from = message.from || this.config.from;
+        if (!from) throw new Error("From address required");
+
+        const info = await this.transporter.sendMail({
+            from: from.name ? `"${from.name}" <${from.email}>` : from.email,
+            to: Array.isArray(message.to) ? message.to.join(", ") : message.to,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            cc: message.cc ? (Array.isArray(message.cc) ? message.cc.join(", ") : message.cc) : undefined,
+            bcc: message.bcc ? (Array.isArray(message.bcc) ? message.bcc.join(", ") : message.bcc) : undefined,
+            replyTo: message.replyTo,
+            attachments: message.attachments?.map(a => ({
+                filename: a.filename,
+                content: typeof a.content === 'string' ? a.content : Buffer.from(a.content),
+                contentType: a.contentType
+            }))
+        });
+
+        return { messageId: (info as any).messageId, success: true };
+    }
+
+    async sendTemplate(templateName: string, to: string | string[], data: TemplateData) {
+        // Simple mock template engine
+        return this.send({
+            to,
+            subject: `Template: ${templateName}`,
+            html: `<p>Template ${templateName} rendered with ${JSON.stringify(data)}</p>`
+        });
+    }
+}

package/src/features/error-handler.ts

@@ -0,0 +1,147 @@
+import type { Feature, ErrorHandlerConfig } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { IskraError } from '@iskra-bun/core';
+import { HttpError } from '../errors';
+
+export class ErrorHandlerFeature implements Feature {
+    name = "error-handler";
+
+    private config: ErrorHandlerConfig;
+
+    constructor(config: ErrorHandlerConfig = {}) {
+        this.config = {
+            includeStack: config.includeStack !== undefined
+                ? config.includeStack
+                : process.env.NODE_ENV === "development",
+            customHandlers: config.customHandlers,
+            logger: config.logger,
+        };
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const app = kernel.getApp();
+
+        app.onError((err, c) => {
+            return this.handleError(err, c);
+        });
+
+        console.log("✅ Error handler feature initialized");
+    }
+
+    private handleError(err: Error | HTTPException, c: Context): Response {
+        if (this.config.logger) {
+            this.config.logger(err as Error, c);
+        } else {
+            console.error("Error:", err);
+        }
+
+        // Iskra HttpError — convertir a HTTPException para mantener compatibilidad con Hono
+        if (err instanceof HttpError) {
+            const status = err.status;
+            if (this.config.customHandlers?.[status]) {
+                return this.config.customHandlers[status](err, c);
+            }
+
+            const response: any = {
+                error: err.message,
+                status,
+                code: err.code,
+            };
+
+            if (Object.keys(err.context).length > 0) {
+                response.context = err.context;
+            }
+
+            if (this.config.includeStack && err.stack) {
+                response.stack = err.stack;
+            }
+
+            const requestId = c.get("requestId");
+            if (requestId) response.requestId = requestId;
+
+            return c.json(response, status as any);
+        }
+
+        // IskraError genérico (no-HTTP) — devolver como 500
+        if (err instanceof IskraError) {
+            const status = 500;
+            if (this.config.customHandlers?.[status]) {
+                return this.config.customHandlers[status](err, c);
+            }
+
+            const response: any = {
+                error: this.config.includeStack ? err.message : "Internal Server Error",
+                status,
+                code: err.code,
+            };
+
+            if (this.config.includeStack && err.stack) {
+                response.stack = err.stack;
+            }
+
+            const requestId = c.get("requestId");
+            if (requestId) response.requestId = requestId;
+
+            return c.json(response, status);
+        }
+
+        // Hono HTTPException nativa
+        if (err instanceof HTTPException) {
+            const status = err.status;
+            if (this.config.customHandlers?.[status]) {
+                return this.config.customHandlers[status](err, c);
+            }
+
+            const response: any = {
+                error: err.message || this.getStatusText(status),
+                status,
+            };
+
+            if (this.config.includeStack && err.stack) {
+                response.stack = err.stack;
+            }
+
+            return c.json(response, status);
+        }
+
+        // Error genérico
+        const status = 500;
+        if (this.config.customHandlers?.[status]) {
+            return this.config.customHandlers[status](err, c);
+        }
+
+        const response: any = {
+            error: this.config.includeStack ? err.message : "Internal Server Error",
+            status,
+        };
+
+        if (this.config.includeStack && err.stack) {
+            response.stack = err.stack;
+        }
+
+        const requestId = c.get("requestId");
+        if (requestId) {
+            response.requestId = requestId;
+        }
+
+        return c.json(response, status);
+    }
+
+    private getStatusText(status: number): string {
+        const statusTexts: Record<number, string> = {
+            400: "Bad Request",
+            401: "Unauthorized",
+            403: "Forbidden",
+            404: "Not Found",
+            500: "Internal Server Error",
+        };
+        return statusTexts[status] || "Error";
+    }
+}
+
+export function createHttpError(status: number, message: string): HTTPException {
+    // @ts-expect-error - status is a number, HTTPException expects a ContentfulStatusCode
+    return new HTTPException(status, { message });
+}

package/src/features/health.ts

@@ -0,0 +1,94 @@
+import type { Feature, HealthCheckConfig } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context } from "hono";
+
+export class HealthCheckFeature implements Feature {
+    name = "health";
+
+    private kernel?: Kernel;
+    private config: Required<Omit<HealthCheckConfig, "checks">> & { checks?: HealthCheckConfig["checks"] };
+
+    constructor(config: HealthCheckConfig = {}) {
+        this.config = {
+            path: config.path || "/health",
+            readinessPath: config.readinessPath || "/health/ready",
+            livenessPath: config.livenessPath || "/health/live",
+            includeDetails: config.includeDetails !== undefined ? config.includeDetails : true,
+            checks: config.checks,
+        };
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        this.kernel = kernel;
+        const app = kernel.getApp();
+
+        app.get(this.config.path, async (c: Context) => await this.handleHealthCheck(c));
+        app.get(this.config.readinessPath, async (c: Context) => await this.handleReadinessCheck(c));
+        app.get(this.config.livenessPath, async (c: Context) => await this.handleLivenessCheck(c));
+
+        console.log("✅ Health check feature initialized");
+    }
+
+    private async handleHealthCheck(c: Context) {
+        const response: any = {
+            status: "ok",
+            timestamp: new Date().toISOString(),
+        };
+
+        if (this.config.includeDetails && this.kernel) {
+            // @ts-expect-error - features is a private kernel field accessed for diagnostics
+            response.features = Array.from(this.kernel.features.keys());
+            const featureHealth: any = {};
+
+            const dbFeature = this.kernel.getFeature("db");
+            if (dbFeature) await this.checkFeatureHealth(c, dbFeature, featureHealth, "db", "query", "SELECT 1");
+
+            const cacheFeature = this.kernel.getFeature("cache");
+            if (cacheFeature) await this.checkFeatureHealth(c, cacheFeature, featureHealth, "cache", "exists", "__health_check__");
+
+            if (Object.keys(featureHealth).length > 0) {
+                response.checks = featureHealth;
+            }
+
+            if (this.config.checks) {
+                const customChecks: any = {};
+                for (const [name, check] of Object.entries(this.config.checks)) {
+                    try {
+                        customChecks[name] = await check(c);
+                    } catch (error) {
+                        customChecks[name] = { status: "error", error: String(error) };
+                    }
+                }
+                response.customChecks = customChecks;
+            }
+        }
+
+        return c.json(response);
+    }
+
+    private async checkFeatureHealth(c: Context, feature: any, report: any, key: string, method: string, ...args: any[]) {
+        try {
+            // Abstracted check logic
+            const instance = c.get(key as any);
+            if (instance && typeof instance[method] === "function") {
+                await instance[method](...args);
+                report[key] = { status: "ok" };
+            }
+        } catch (e) {
+            report[key] = { status: "error", error: String(e) };
+        }
+    }
+
+    private async handleReadinessCheck(c: Context) {
+        // Simplified readiness check
+        return c.json({ status: "ready" });
+    }
+
+    private async handleLivenessCheck(c: Context) {
+        return c.json({
+            status: "alive",
+            timestamp: new Date().toISOString(),
+            uptime: process.uptime()
+        });
+    }
+}