@objectstack/plugin-email 4.0.1

package/dist/index.d.ts

@@ -0,0 +1,256 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+import { IEmailTransport, EmailAddress, NormalizedEmailMessage, TransportSendResult, SendEmailInput } from '@objectstack/spec/contracts';
+import { EmailTemplateDefinition } from '@objectstack/spec/system';
+
+/**
+ * Plugin configuration.
+ */
+interface EmailServicePluginOptions {
+    /**
+     * Pluggable delivery transport. When omitted the plugin builds one
+     * from `provider`/`apiKey`; if both omitted, falls back to
+     * `LogTransport` (no real send).
+     */
+    transport?: IEmailTransport;
+    /** Provider tag — `'log' | 'resend' | 'postmark'`. Default `'log'`. */
+    provider?: 'log' | 'resend' | 'postmark';
+    /** API key for resend/postmark. */
+    apiKey?: string;
+    /** Provider-specific extra options (e.g. Postmark messageStream). */
+    providerOptions?: Record<string, unknown>;
+    /** Default `From` address applied when `input.from` is omitted. */
+    defaultFrom?: EmailAddress;
+    /** Persist each attempt to sys_email. Default true when ObjectQL engine present. */
+    persist?: boolean;
+    /** Retry attempts on transport throw. Default 0. */
+    retries?: number;
+    /** Default template render context (merged into every sendTemplate call). */
+    defaultTemplateContext?: Record<string, unknown>;
+    /** Seed built-in auth templates into sys_email_template on startup. Default true. */
+    seedTemplates?: boolean;
+    /** Additional templates seeded alongside the built-ins. */
+    templates?: EmailTemplateDefinition[];
+}
+/**
+ * EmailServicePlugin — registers the `email` service.
+ *
+ * Lifecycle:
+ *   - `init`: register sys_email + sys_email_template via manifest;
+ *     build transport (config → provider+apiKey → LogTransport fallback);
+ *     register a transport-only EmailService so dependents can resolve it.
+ *   - `start` (kernel:ready): wire ObjectQL-backed sys_email persistence
+ *     + sys_email_template TemplateLoader; seed built-in auth templates
+ *     (upsert by `(name, locale)`).
+ */
+declare class EmailServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: string;
+    dependencies: string[];
+    private readonly options;
+    private service?;
+    constructor(options?: EmailServicePluginOptions);
+    private resolveTransport;
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    /**
+     * Translate the `mail` settings namespace snapshot into a transport
+     * and `defaultFrom`, then hot-swap them on the running EmailService.
+     *
+     * Behaviour:
+     *  - `provider = 'log' | 'smtp'` keeps the LogTransport (real SMTP
+     *    delivery requires `@objectstack/plugin-mail-smtp`, which is not
+     *    a dependency of this package). The from-address is still applied.
+     *  - `provider = 'resend' | 'postmark'` rebuilds the transport using
+     *    `api_key` from settings. If `api_key` is missing the swap is
+     *    skipped and a warning is logged — the previous transport stays.
+     *
+     * Env-locked fields (handled in SettingsService.get) still resolve
+     * before this method ever sees them, so an env override transparently
+     * wins.
+     */
+    private applyMailSettings;
+    private upsertTemplate;
+}
+
+/**
+ * Internal persistence shim — typed loosely so the service can run
+ * without an ObjectQL engine wired (e.g. unit tests, serverless).
+ */
+interface EmailPersistence {
+    insert(row: Record<string, any>): Promise<{
+        id: string;
+    } | string>;
+    update?(id: string, patch: Record<string, any>): Promise<void>;
+}
+/**
+ * Format an EmailAddress (string or {name,address}) into the canonical
+ * `"Display" <addr>` form. Throws if address is malformed.
+ */
+declare function formatAddress(addr: EmailAddress): string;
+/**
+ * Validate input + apply default-from + canonicalize recipients.
+ * Throws Error('VALIDATION_FAILED: <reason>') for malformed payloads.
+ */
+declare function normalizeMessage(input: SendEmailInput, defaultFrom?: EmailAddress): NormalizedEmailMessage;
+/**
+ * Development transport — never actually sends. Logs to the provided
+ * logger and returns a synthetic Message-ID. Useful for local dev,
+ * tests, and "dry run" environments.
+ */
+declare class LogTransport implements IEmailTransport {
+    private readonly logger?;
+    private counter;
+    constructor(logger?: {
+        info: (msg: string, meta?: any) => void;
+    } | undefined);
+    send(message: NormalizedEmailMessage): Promise<TransportSendResult>;
+}
+/**
+ * Loader for sys_email_template rows. Injected by EmailServicePlugin
+ * on `kernel:ready`. Returns the best-matching row for `(name, locale)`
+ * or `null` when none exists / inactive.
+ */
+interface TemplateLoader {
+    load(name: string, locale: string | undefined): Promise<EmailTemplateRow | null>;
+}
+/**
+ * Row shape returned by the loader — mirrors sys_email_template
+ * columns relevant to rendering.
+ */
+interface EmailTemplateRow {
+    name: string;
+    locale: string;
+    subject: string;
+    body_html: string;
+    body_text?: string | null;
+    from_name?: string | null;
+    from_address?: string | null;
+    reply_to?: string | null;
+    active?: boolean;
+    variables_json?: string | null;
+}
+interface EmailServiceOptions {
+    transport: IEmailTransport;
+    defaultFrom?: EmailAddress;
+    /** Persist each attempt to sys_email. Omit to disable persistence. */
+    persistence?: EmailPersistence;
+    /** Resolve named templates for sendTemplate(). Omit to disable templates. */
+    templateLoader?: TemplateLoader;
+    /** Retry attempts on transport throw. Default 0 (no retry). */
+    retries?: number;
+    /** Logger for diagnostic output. */
+    logger?: {
+        info: (msg: string, meta?: any) => void;
+        warn: (msg: string, meta?: any) => void;
+        error?: (msg: string, meta?: any) => void;
+    };
+    /** Default render context merged into every sendTemplate call (e.g. `{ appName }`). */
+    defaultTemplateContext?: Record<string, unknown>;
+}
+
+/**
+ * Render `template` with values from `data`. Missing placeholders
+ * render as empty strings (no throw); call `requireVars()` first if
+ * you need strict validation.
+ */
+declare function renderTemplate(template: string, data: Record<string, any>): string;
+/**
+ * Throw `Error('MISSING_VARIABLES: a, b')` when required vars are
+ * absent from `data`. Used by `IEmailService.sendTemplate()` to
+ * fail fast rather than send a half-rendered email.
+ */
+declare function requireVars(data: Record<string, any>, required: ReadonlyArray<string>): void;
+/**
+ * Strip HTML tags + collapse whitespace to derive a plain-text body
+ * from an HTML template. Conservative: keeps line breaks at block
+ * boundaries (<br>, </p>, </div>) so the resulting text is at least
+ * paragraph-shaped.
+ */
+declare function htmlToText(html: string): string;
+
+/**
+ * ResendTransport — SaaS delivery via https://resend.com
+ *
+ * Implements `IEmailTransport` using the Resend HTTPS API. Zero
+ * external dependencies (uses fetch). API docs:
+ * https://resend.com/docs/api-reference/emails/send-email
+ *
+ * @example
+ * ```ts
+ * new EmailServicePlugin({
+ *   transport: new ResendTransport(process.env.RESEND_API_KEY!),
+ *   defaultFrom: { name: 'Acme', address: 'no-reply@acme.com' },
+ * });
+ * ```
+ */
+interface ResendTransportOptions {
+    apiKey: string;
+    /** Override the API host (used by tests / proxies). */
+    endpoint?: string;
+}
+declare class ResendTransport implements IEmailTransport {
+    private readonly apiKey;
+    private readonly endpoint;
+    constructor(apiKeyOrOptions: string | ResendTransportOptions);
+    send(message: NormalizedEmailMessage): Promise<TransportSendResult>;
+}
+
+/**
+ * PostmarkTransport — SaaS delivery via https://postmarkapp.com
+ *
+ * Implements `IEmailTransport` using the Postmark HTTPS API. Zero
+ * external dependencies (uses fetch). API docs:
+ * https://postmarkapp.com/developer/user-guide/send-email-with-api
+ *
+ * @example
+ * ```ts
+ * new EmailServicePlugin({
+ *   transport: new PostmarkTransport({
+ *     apiKey: process.env.POSTMARK_TOKEN!,
+ *     messageStream: 'outbound',
+ *   }),
+ *   defaultFrom: { name: 'Acme', address: 'no-reply@acme.com' },
+ * });
+ * ```
+ */
+interface PostmarkTransportOptions {
+    apiKey: string;
+    /** Postmark message stream (default 'outbound'). */
+    messageStream?: string;
+    /** Override the API host. */
+    endpoint?: string;
+}
+declare class PostmarkTransport implements IEmailTransport {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly messageStream;
+    constructor(opts: PostmarkTransportOptions);
+    send(message: NormalizedEmailMessage): Promise<TransportSendResult>;
+}
+
+interface MakeTransportOptions {
+    provider: 'log' | 'resend' | 'postmark';
+    apiKey?: string;
+    options?: Record<string, unknown>;
+    logger?: {
+        info: (msg: string, meta?: any) => void;
+    };
+}
+/**
+ * Build an IEmailTransport from a provider tag + opts. Used by
+ * EmailServicePlugin to materialise the transport selected by
+ * `EmailServiceConfig.provider`.
+ *
+ * Throws when a non-`log` provider is requested without an `apiKey`.
+ */
+declare function makeTransport(opts: MakeTransportOptions): IEmailTransport;
+
+declare const AUTH_PASSWORD_RESET_TEMPLATE: EmailTemplateDefinition;
+declare const AUTH_VERIFY_EMAIL_TEMPLATE: EmailTemplateDefinition;
+declare const AUTH_MAGIC_LINK_TEMPLATE: EmailTemplateDefinition;
+declare const AUTH_INVITATION_TEMPLATE: EmailTemplateDefinition;
+declare const AUTH_TWO_FACTOR_OTP_TEMPLATE: EmailTemplateDefinition;
+declare const BUILTIN_AUTH_TEMPLATES: EmailTemplateDefinition[];
+
+export { AUTH_INVITATION_TEMPLATE, AUTH_MAGIC_LINK_TEMPLATE, AUTH_PASSWORD_RESET_TEMPLATE, AUTH_TWO_FACTOR_OTP_TEMPLATE, AUTH_VERIFY_EMAIL_TEMPLATE, BUILTIN_AUTH_TEMPLATES, type EmailPersistence, type EmailServiceOptions, EmailServicePlugin, type EmailServicePluginOptions, type EmailTemplateRow, LogTransport, type MakeTransportOptions, PostmarkTransport, type PostmarkTransportOptions, ResendTransport, type ResendTransportOptions, type TemplateLoader, formatAddress, htmlToText, makeTransport, normalizeMessage, renderTemplate, requireVars };