@shogo-ai/email 1.4.1

package/dist/types-CCHryvHe.d.cts

@@ -0,0 +1,196 @@
+/**
+ * Email Module Types
+ *
+ * Type definitions for the email system.
+ * Designed for simplicity - template strings with {{variable}} interpolation.
+ */
+/**
+ * Email address - can be a simple string or object with name
+ */
+type EmailAddress = string | {
+    email: string;
+    name?: string;
+};
+/**
+ * Normalize email address to string format
+ */
+declare function formatEmailAddress(address: EmailAddress): string;
+/**
+ * Parameters for sending an email
+ */
+interface SendEmailParams {
+    /** Recipient email address(es) */
+    to: EmailAddress | EmailAddress[];
+    /** Email subject line */
+    subject: string;
+    /** HTML content of the email */
+    html: string;
+    /** Plain text content (auto-generated from HTML if not provided) */
+    text?: string;
+    /** Sender email address (uses default from config if not specified) */
+    from?: EmailAddress;
+    /** Reply-to address */
+    replyTo?: EmailAddress;
+    /** CC recipients */
+    cc?: EmailAddress | EmailAddress[];
+    /** BCC recipients */
+    bcc?: EmailAddress | EmailAddress[];
+}
+/**
+ * Parameters for sending a templated email
+ */
+interface SendTemplateParams<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /** Recipient email address(es) */
+    to: EmailAddress | EmailAddress[];
+    /** Template name */
+    template: string;
+    /** Template data for variable interpolation */
+    data: TData;
+    /** Sender email address (uses default from config if not specified) */
+    from?: EmailAddress;
+    /** Reply-to address */
+    replyTo?: EmailAddress;
+    /** CC recipients */
+    cc?: EmailAddress | EmailAddress[];
+    /** BCC recipients */
+    bcc?: EmailAddress | EmailAddress[];
+}
+/**
+ * Result from sending an email
+ */
+interface EmailResult {
+    /** Whether the email was sent successfully */
+    success: boolean;
+    /** Message ID from the email provider (if successful) */
+    messageId?: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Supported email providers
+ */
+type EmailProviderType = 'smtp' | 'ses' | 'oci-email';
+/**
+ * SMTP configuration
+ */
+interface SmtpConfig {
+    /** SMTP server hostname */
+    host: string;
+    /** SMTP server port */
+    port: number;
+    /** SMTP authentication username */
+    user: string;
+    /** SMTP authentication password */
+    password: string;
+    /** Use TLS/SSL (default: true for port 465, STARTTLS for others) */
+    secure?: boolean;
+}
+/**
+ * AWS SES configuration
+ */
+interface SesConfig {
+    /** AWS region (e.g., 'us-east-1') */
+    region: string;
+    /** AWS access key ID (optional if using IAM role) */
+    accessKeyId?: string;
+    /** AWS secret access key (optional if using IAM role) */
+    secretAccessKey?: string;
+}
+/**
+ * OCI Email Delivery configuration (SMTP-based)
+ */
+interface OciEmailConfig {
+    /** SMTP host (e.g., 'smtp.email.us-ashburn-1.oci.oraclecloud.com') */
+    host: string;
+    /** SMTP port (default: 587) */
+    port: number;
+    /** SMTP auth username (OCI SMTP credential) */
+    user: string;
+    /** SMTP auth password (OCI SMTP credential) */
+    password: string;
+    /** Default sender address */
+    fromAddress?: string;
+}
+/**
+ * Email provider configuration
+ */
+interface EmailConfig {
+    /** Provider type */
+    provider: EmailProviderType;
+    /** Default sender email address */
+    defaultFrom: EmailAddress;
+    /** Provider-specific configuration */
+    smtp?: SmtpConfig;
+    ses?: SesConfig;
+    ociEmail?: OciEmailConfig;
+}
+/**
+ * Email template definition
+ */
+interface EmailTemplate<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /** Template name (identifier) */
+    name: string;
+    /** Subject line template (supports {{variable}} interpolation) */
+    subject: string;
+    /** HTML body template (supports {{variable}} interpolation) */
+    html: string;
+    /** Plain text body template (optional, auto-generated from HTML if not provided) */
+    text?: string;
+    /** Default data values */
+    defaults?: Partial<TData>;
+}
+/**
+ * Template registry type
+ */
+type TemplateRegistry = Record<string, EmailTemplate>;
+/**
+ * Email service interface - the main API
+ */
+interface IEmailService {
+    /**
+     * Send a raw email with explicit subject/body
+     */
+    send(params: SendEmailParams): Promise<EmailResult>;
+    /**
+     * Send a templated email
+     */
+    sendTemplate<TData extends Record<string, unknown>>(params: SendTemplateParams<TData>): Promise<EmailResult>;
+    /**
+     * Register a custom template
+     */
+    registerTemplate<TData extends Record<string, unknown>>(template: EmailTemplate<TData>): void;
+    /**
+     * Check if the service is configured and ready
+     */
+    isConfigured(): boolean;
+}
+/**
+ * Email provider interface - implemented by SMTP, SES, etc.
+ */
+interface IEmailProvider {
+    /**
+     * Send an email via this provider
+     */
+    send(params: SendEmailParams): Promise<EmailResult>;
+    /**
+     * Check if provider is configured
+     */
+    isConfigured(): boolean;
+}
+/**
+ * Email error codes
+ */
+type EmailErrorCode = 'config_missing' | 'connection_error' | 'authentication_error' | 'invalid_recipient' | 'send_failed' | 'template_not_found' | 'provider_not_configured';
+/**
+ * Email error class
+ */
+declare class EmailError extends Error {
+    code: EmailErrorCode;
+    cause?: unknown;
+    constructor(code: EmailErrorCode, message: string, cause?: unknown);
+    static configMissing(field: string): EmailError;
+    static templateNotFound(name: string): EmailError;
+    static providerNotConfigured(): EmailError;
+}
+
+export { type EmailTemplate as E, type IEmailProvider as I, type OciEmailConfig as O, type SendEmailParams as S, type TemplateRegistry as T, type EmailAddress as a, type EmailConfig as b, EmailError as c, type EmailErrorCode as d, type EmailProviderType as e, type EmailResult as f, type IEmailService as g, type SendTemplateParams as h, type SesConfig as i, type SmtpConfig as j, formatEmailAddress as k };

package/dist/types-CCHryvHe.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Email Module Types
+ *
+ * Type definitions for the email system.
+ * Designed for simplicity - template strings with {{variable}} interpolation.
+ */
+/**
+ * Email address - can be a simple string or object with name
+ */
+type EmailAddress = string | {
+    email: string;
+    name?: string;
+};
+/**
+ * Normalize email address to string format
+ */
+declare function formatEmailAddress(address: EmailAddress): string;
+/**
+ * Parameters for sending an email
+ */
+interface SendEmailParams {
+    /** Recipient email address(es) */
+    to: EmailAddress | EmailAddress[];
+    /** Email subject line */
+    subject: string;
+    /** HTML content of the email */
+    html: string;
+    /** Plain text content (auto-generated from HTML if not provided) */
+    text?: string;
+    /** Sender email address (uses default from config if not specified) */
+    from?: EmailAddress;
+    /** Reply-to address */
+    replyTo?: EmailAddress;
+    /** CC recipients */
+    cc?: EmailAddress | EmailAddress[];
+    /** BCC recipients */
+    bcc?: EmailAddress | EmailAddress[];
+}
+/**
+ * Parameters for sending a templated email
+ */
+interface SendTemplateParams<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /** Recipient email address(es) */
+    to: EmailAddress | EmailAddress[];
+    /** Template name */
+    template: string;
+    /** Template data for variable interpolation */
+    data: TData;
+    /** Sender email address (uses default from config if not specified) */
+    from?: EmailAddress;
+    /** Reply-to address */
+    replyTo?: EmailAddress;
+    /** CC recipients */
+    cc?: EmailAddress | EmailAddress[];
+    /** BCC recipients */
+    bcc?: EmailAddress | EmailAddress[];
+}
+/**
+ * Result from sending an email
+ */
+interface EmailResult {
+    /** Whether the email was sent successfully */
+    success: boolean;
+    /** Message ID from the email provider (if successful) */
+    messageId?: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Supported email providers
+ */
+type EmailProviderType = 'smtp' | 'ses' | 'oci-email';
+/**
+ * SMTP configuration
+ */
+interface SmtpConfig {
+    /** SMTP server hostname */
+    host: string;
+    /** SMTP server port */
+    port: number;
+    /** SMTP authentication username */
+    user: string;
+    /** SMTP authentication password */
+    password: string;
+    /** Use TLS/SSL (default: true for port 465, STARTTLS for others) */
+    secure?: boolean;
+}
+/**
+ * AWS SES configuration
+ */
+interface SesConfig {
+    /** AWS region (e.g., 'us-east-1') */
+    region: string;
+    /** AWS access key ID (optional if using IAM role) */
+    accessKeyId?: string;
+    /** AWS secret access key (optional if using IAM role) */
+    secretAccessKey?: string;
+}
+/**
+ * OCI Email Delivery configuration (SMTP-based)
+ */
+interface OciEmailConfig {
+    /** SMTP host (e.g., 'smtp.email.us-ashburn-1.oci.oraclecloud.com') */
+    host: string;
+    /** SMTP port (default: 587) */
+    port: number;
+    /** SMTP auth username (OCI SMTP credential) */
+    user: string;
+    /** SMTP auth password (OCI SMTP credential) */
+    password: string;
+    /** Default sender address */
+    fromAddress?: string;
+}
+/**
+ * Email provider configuration
+ */
+interface EmailConfig {
+    /** Provider type */
+    provider: EmailProviderType;
+    /** Default sender email address */
+    defaultFrom: EmailAddress;
+    /** Provider-specific configuration */
+    smtp?: SmtpConfig;
+    ses?: SesConfig;
+    ociEmail?: OciEmailConfig;
+}
+/**
+ * Email template definition
+ */
+interface EmailTemplate<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /** Template name (identifier) */
+    name: string;
+    /** Subject line template (supports {{variable}} interpolation) */
+    subject: string;
+    /** HTML body template (supports {{variable}} interpolation) */
+    html: string;
+    /** Plain text body template (optional, auto-generated from HTML if not provided) */
+    text?: string;
+    /** Default data values */
+    defaults?: Partial<TData>;
+}
+/**
+ * Template registry type
+ */
+type TemplateRegistry = Record<string, EmailTemplate>;
+/**
+ * Email service interface - the main API
+ */
+interface IEmailService {
+    /**
+     * Send a raw email with explicit subject/body
+     */
+    send(params: SendEmailParams): Promise<EmailResult>;
+    /**
+     * Send a templated email
+     */
+    sendTemplate<TData extends Record<string, unknown>>(params: SendTemplateParams<TData>): Promise<EmailResult>;
+    /**
+     * Register a custom template
+     */
+    registerTemplate<TData extends Record<string, unknown>>(template: EmailTemplate<TData>): void;
+    /**
+     * Check if the service is configured and ready
+     */
+    isConfigured(): boolean;
+}
+/**
+ * Email provider interface - implemented by SMTP, SES, etc.
+ */
+interface IEmailProvider {
+    /**
+     * Send an email via this provider
+     */
+    send(params: SendEmailParams): Promise<EmailResult>;
+    /**
+     * Check if provider is configured
+     */
+    isConfigured(): boolean;
+}
+/**
+ * Email error codes
+ */
+type EmailErrorCode = 'config_missing' | 'connection_error' | 'authentication_error' | 'invalid_recipient' | 'send_failed' | 'template_not_found' | 'provider_not_configured';
+/**
+ * Email error class
+ */
+declare class EmailError extends Error {
+    code: EmailErrorCode;
+    cause?: unknown;
+    constructor(code: EmailErrorCode, message: string, cause?: unknown);
+    static configMissing(field: string): EmailError;
+    static templateNotFound(name: string): EmailError;
+    static providerNotConfigured(): EmailError;
+}
+
+export { type EmailTemplate as E, type IEmailProvider as I, type OciEmailConfig as O, type SendEmailParams as S, type TemplateRegistry as T, type EmailAddress as a, type EmailConfig as b, EmailError as c, type EmailErrorCode as d, type EmailProviderType as e, type EmailResult as f, type IEmailService as g, type SendTemplateParams as h, type SesConfig as i, type SmtpConfig as j, formatEmailAddress as k };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@shogo-ai/email",
+  "version": "1.4.1",
+  "description": "Shogo Email — multi-provider transactional email (SES, SMTP, OCI) with built-in transactional templates.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.cjs",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.cts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "bun --no-env-file test src/"
+  },
+  "peerDependencies": {
+    "nodemailer": ">=6.0.0",
+    "@aws-sdk/client-ses": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "nodemailer": {
+      "optional": true
+    },
+    "@aws-sdk/client-ses": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/nodemailer": "^7.0.11",
+    "tsup": "^8.0.0",
+    "typescript": "^6.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "shogo",
+    "email",
+    "smtp",
+    "ses",
+    "transactional",
+    "nodemailer"
+  ],
+  "author": "Shogo Labs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shogo-labs/shogo-ai.git",
+    "directory": "packages/email"
+  },
+  "homepage": "https://github.com/shogo-labs/shogo-ai/tree/main/packages/email#readme",
+  "bugs": {
+    "url": "https://github.com/shogo-labs/shogo-ai/issues"
+  }
+}