@holo-js/mail 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+import * as _holo_js_config from '@holo-js/config';
+import { NormalizedHoloMailConfig, HoloAppEnv } from '@holo-js/config';
+export { HoloMailConfig, NormalizedHoloMailConfig, defineMailConfig } from '@holo-js/config';
+import { ResolvedMail, MailDriverExecutionContext, MailSendResult, MailPreviewPolicy, MailPreviewFormat, MailRuntimeBindings, MailDefinition, MailDefinitionInput, MailOverrideInput, MailPreviewResult, PendingMailSend, MailDelayValue, MailDriver, ResolvedMailAttachment, MailAddress, MailJsonObject, MailRenderSource, MailViewRenderInput, RegisteredMailDriver, RegisterMailDriverOptions } from './contracts.js';
+export { BuiltInMailDriverRegistry, HoloMailDriverRegistry, MailAddressInput, MailAttachmentBase, MailAttachmentContent, MailAttachmentDisposition, MailAttachmentHelperOptions, MailAttachmentInput, MailAttachmentMetadata, MailAttachmentResolutionContext, MailAttachmentResolutionPlan, MailContentAttachment, MailContentAttachmentHelperOptions, MailContentSourceKind, MailDriverName, MailJsonValue, MailPathAttachment, MailPreviewInput, MailPriority, MailQueueOptions, MailRecipientsInput, MailRenderPreviewInput, MailResolvableAttachment, MailResolvedAttachmentPayload, MailSendInput, MailSendOptions, MailStorageAttachment, MailStorageAttachmentHelperOptions, MailViewRenderer, attachContent, attachFromPath, attachFromStorage, createAttachmentMetadata, createAttachmentResolutionPlan, createAttachmentResolutionPlans, defineMail, inferMimeTypeFromName, isAttachmentQueueSafe, isMailDefinition, mailInternals, mergeMailDefinitionInputs, normalizeMailDefinition, resolveAttachmentDefinition, resolveNormalizedAttachment } from './contracts.js';
+
+type RuntimeState = {
+    bindings?: MailRuntimeBindings;
+    fakeSent?: FakeSentMail[];
+    previewArtifacts?: MailPreviewArtifact[];
+    loadQueueModule?: () => Promise<QueueModule>;
+    loadDbModule?: () => Promise<DbModule | null>;
+    loadNodemailerModule?: () => Promise<NodemailerModule>;
+    loadStorageModule?: () => Promise<StorageModule>;
+};
+type MutableSendOptions = {
+    mailer?: string;
+    connection?: string;
+    queue?: string;
+    delay?: MailDelayValue;
+    afterCommit?: boolean;
+};
+type ResolvedEnvelope = {
+    readonly config: NormalizedHoloMailConfig;
+    readonly mailer: string;
+    readonly from: MailAddress;
+    readonly replyTo: MailAddress;
+    readonly to: readonly MailAddress[];
+    readonly cc: readonly MailAddress[];
+    readonly bcc: readonly MailAddress[];
+};
+type RenderedContent = {
+    readonly kind: 'text' | 'html' | 'markdown' | 'render';
+    readonly html?: string;
+    readonly text?: string;
+    readonly source: Readonly<{
+        readonly kind: 'text' | 'html' | 'markdown' | 'render';
+        readonly markdown?: string;
+        readonly rawHtml?: string;
+        readonly render?: Readonly<MailRenderSource>;
+    }>;
+};
+type PreviewComputation = ResolvedEnvelope & {
+    readonly preview: MailPreviewResult;
+};
+type SendPreparation = {
+    readonly attachments: readonly ResolvedMailAttachment[];
+};
+type ResolvedDriver = {
+    readonly mailer: string;
+    readonly driver: string;
+    readonly implementation: MailDriver;
+};
+type ResolvedQueuePlan = {
+    readonly queued: boolean;
+    readonly connection?: string;
+    readonly queue?: string;
+    readonly delay?: MailDelayValue;
+    readonly afterCommit: boolean;
+};
+type QueueDispatchChain = {
+    onConnection(name: string): QueueDispatchChain;
+    onQueue(name: string): QueueDispatchChain;
+    delay(value: number | Date): QueueDispatchChain;
+    dispatch(): Promise<unknown>;
+};
+type QueueModule = {
+    defineJob(definition: {
+        handle(payload: QueuedMailDeliveryPayload): Promise<unknown> | unknown;
+    }): unknown;
+    dispatch(jobName: string, payload: QueuedMailDeliveryPayload): QueueDispatchChain;
+    getRegisteredQueueJob(name: string): unknown;
+    registerQueueJob(definition: unknown, options: {
+        name: string;
+    }): void;
+};
+type DbModule = {
+    connectionAsyncContext: {
+        getActive(): {
+            connection: {
+                getScope(): {
+                    kind: string;
+                };
+                afterCommit(callback: () => Promise<void>): void;
+            };
+        } | undefined;
+    };
+};
+type NodemailerAddress = {
+    readonly address: string;
+    readonly name?: string;
+};
+type NodemailerAttachment = {
+    readonly filename: string;
+    readonly contentType?: string;
+    readonly contentDisposition?: string;
+    readonly cid?: string;
+    readonly path?: string;
+    readonly content?: string | Uint8Array;
+};
+type NodemailerMailMessage = {
+    readonly messageId: string;
+    readonly from: NodemailerAddress;
+    readonly replyTo: NodemailerAddress;
+    readonly to: readonly NodemailerAddress[];
+    readonly cc?: readonly NodemailerAddress[];
+    readonly bcc?: readonly NodemailerAddress[];
+    readonly subject: string;
+    readonly html?: string;
+    readonly text?: string;
+    readonly attachments?: readonly NodemailerAttachment[];
+    readonly headers?: Readonly<Record<string, string>>;
+};
+type NodemailerSendResult = {
+    readonly messageId?: string;
+    readonly response?: string;
+};
+type NodemailerTransport = {
+    sendMail(message: NodemailerMailMessage): Promise<NodemailerSendResult>;
+};
+type NodemailerModule = {
+    createTransport(options: Record<string, unknown>): NodemailerTransport;
+};
+type StorageDisk = {
+    readonly driver: string;
+    path(path: string): string;
+    getBytes(path: string): Promise<Uint8Array | null>;
+};
+type StorageModule = {
+    Storage: {
+        disk(diskName?: string): StorageDisk;
+    };
+};
+type SerializedQueuedAttachment = Readonly<{
+    readonly source: ResolvedMailAttachment['source'];
+    readonly name: string;
+    readonly contentType?: string;
+    readonly disposition: ResolvedMailAttachment['disposition'];
+    readonly contentId?: string;
+    readonly path?: string;
+    readonly storage?: {
+        readonly path: string;
+        readonly disk?: string;
+    };
+    readonly content?: string | Readonly<{
+        readonly encoding: 'base64';
+        readonly value: string;
+    }>;
+}>;
+type QueuedResolvedMailPayload = Readonly<Omit<ResolvedMail, 'attachments'> & {
+    readonly attachments: readonly SerializedQueuedAttachment[];
+}>;
+type QueuedMailDeliveryPayload = Readonly<{
+    readonly messageId: string;
+    readonly mailer: string;
+    readonly driver: string;
+    readonly queued: true;
+    readonly deferred?: boolean;
+    readonly mail: QueuedResolvedMailPayload;
+}>;
+interface FakeSentMail {
+    readonly messageId: string;
+    readonly createdAt: Date;
+    readonly mail: Readonly<ResolvedMail>;
+    readonly context: Readonly<MailDriverExecutionContext>;
+    readonly result: Readonly<MailSendResult>;
+}
+interface MailPreviewArtifact {
+    readonly messageId: string;
+    readonly createdAt: Date;
+    readonly mail: Readonly<ResolvedMail>;
+    readonly context: Readonly<MailDriverExecutionContext>;
+    readonly result: Readonly<MailSendResult>;
+}
+declare class MailError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string, options?: ErrorOptions);
+}
+declare class MailPreviewDisabledError extends MailError {
+    readonly policy: MailPreviewPolicy;
+    constructor(policy: MailPreviewPolicy);
+}
+declare class MailPreviewFormatUnavailableError extends MailError {
+    readonly format: MailPreviewFormat;
+    constructor(format: MailPreviewFormat);
+}
+declare class MailSendError extends MailError {
+    readonly messageId: string;
+    readonly mailer: string;
+    readonly driver: string;
+    constructor(details: {
+        readonly messageId: string;
+        readonly mailer: string;
+        readonly driver: string;
+        readonly message?: string;
+    }, options?: ErrorOptions);
+}
+declare function getRuntimeState(): RuntimeState;
+declare function getRuntimeBindings(): MailRuntimeBindings;
+declare function dynamicImport<TModule>(specifier: string): Promise<TModule>;
+declare function loadQueueModule(): Promise<QueueModule>;
+declare function loadDbModule(): Promise<DbModule | null>;
+declare function resolveNodemailerModule(module: unknown): NodemailerModule;
+declare function loadNodemailerModule(): Promise<NodemailerModule>;
+declare function resolveStorageModule(module: unknown): StorageModule;
+declare function loadStorageModule(): Promise<StorageModule>;
+declare function getFakeSentState(): FakeSentMail[];
+declare function getPreviewArtifactState(): MailPreviewArtifact[];
+declare function normalizeExecutionString(value: string, label: string): string;
+declare function normalizeExecutionDelay(value: MailDelayValue): MailDelayValue;
+declare function getResolvedConfig(): NormalizedHoloMailConfig;
+declare function resolveCurrentEnvironment(): HoloAppEnv;
+declare function createPreviewPolicy(config?: NormalizedHoloMailConfig): MailPreviewPolicy;
+declare function assertPreviewEnabled(config?: NormalizedHoloMailConfig): void;
+declare function createPreviewHtml(preview: MailPreviewResult): string;
+declare function escapeHtml(value: string): string;
+declare function formatAddress(address: {
+    readonly email: string;
+    readonly name?: string;
+}): string;
+declare function renderPreviewResponse(preview: MailPreviewResult, format: MailPreviewFormat): Response;
+declare function getMailerConfig(mailer: string, config?: NormalizedHoloMailConfig): _holo_js_config.NormalizedHoloMailMailerConfig;
+declare function isQueueRequested(mail: MailDefinition, mailer: string, options: MutableSendOptions | Readonly<MutableSendOptions>, config?: NormalizedHoloMailConfig): boolean;
+declare function resolveQueuePlan(mail: MailDefinition, options: MutableSendOptions | Readonly<MutableSendOptions>, mailer: string, config?: NormalizedHoloMailConfig): ResolvedQueuePlan;
+declare function prepareMailSend(mail: MailDefinition, queued: boolean): Promise<SendPreparation>;
+declare function createResolvedMail(preview: MailPreviewResult, attachments: readonly ResolvedMailAttachment[]): ResolvedMail;
+declare function createSendContext(messageId: string, resolvedDriver: ResolvedDriver, queued: boolean, deferred?: boolean): MailDriverExecutionContext;
+declare function freezeSendResult(result: MailSendResult): Readonly<MailSendResult>;
+declare function createBaseSendResult(context: MailDriverExecutionContext, overrides?: Partial<MailSendResult>): Readonly<MailSendResult>;
+declare function normalizeDriverResult(result: MailSendResult | undefined, context: MailDriverExecutionContext): Readonly<MailSendResult>;
+declare function createMailRecord<TRecord extends FakeSentMail | MailPreviewArtifact>(context: MailDriverExecutionContext, mail: Readonly<ResolvedMail>, result: Readonly<MailSendResult>): TRecord;
+declare function persistPreviewArtifact(artifact: MailPreviewArtifact): Promise<void>;
+declare function createSmtpAddress(address: MailAddress): NodemailerAddress;
+declare function createSmtpHeaders(mail: Readonly<ResolvedMail>): Readonly<Record<string, string>> | undefined;
+declare function createSmtpAttachment(attachment: ResolvedMailAttachment): Promise<NodemailerAttachment>;
+declare function createSmtpMessage(mail: Readonly<ResolvedMail>, context: Readonly<MailDriverExecutionContext>): Promise<NodemailerMailMessage>;
+declare function sendViaSmtp(mail: Readonly<ResolvedMail>, context: Readonly<MailDriverExecutionContext>): Promise<Readonly<MailSendResult>>;
+declare function resolveDriver(mail: MailDefinition, options: MutableSendOptions | Readonly<MutableSendOptions>, config: NormalizedHoloMailConfig): ResolvedDriver;
+declare function resolveDriverByName(mailer: string, driver: string): ResolvedDriver;
+declare function serializeQueuedAttachment(attachment: ResolvedMailAttachment): SerializedQueuedAttachment;
+declare function deserializeQueuedAttachment(attachment: SerializedQueuedAttachment): ResolvedMailAttachment;
+declare function createQueuedMailPayload(mail: ResolvedMail, context: MailDriverExecutionContext): QueuedMailDeliveryPayload;
+declare function createResolvedMailFromQueuedPayload(payload: QueuedMailDeliveryPayload): ResolvedMail;
+declare function deliverResolvedMail(mail: ResolvedMail, resolvedDriver: ResolvedDriver, context: MailDriverExecutionContext): Promise<Readonly<MailSendResult>>;
+declare function runQueuedMailDelivery(payload: QueuedMailDeliveryPayload): Promise<Readonly<MailSendResult>>;
+declare function ensureMailQueueJobRegistered(queueModule?: QueueModule): Promise<QueueModule>;
+declare function dispatchQueuedMail(mail: ResolvedMail, context: MailDriverExecutionContext, plan: ResolvedQueuePlan): Promise<Readonly<MailSendResult>>;
+declare function deferSendUntilCommit(context: MailDriverExecutionContext, callback: () => Promise<Readonly<MailSendResult>>): Promise<Readonly<MailSendResult> | null>;
+declare function renderView(input: MailViewRenderInput): Promise<string>;
+declare function stripMarkdownSyntax(markdown: string): string;
+declare function renderMarkdownInline(markdown: string): string;
+declare function renderMarkdown(markdown: string): string;
+declare function resolveSourceKind(mail: MailDefinition): RenderedContent['kind'];
+declare function resolveMailerName(mail: MailDefinition, config: NormalizedHoloMailConfig): string;
+declare function resolveEnvelope(mail: MailDefinition): ResolvedEnvelope;
+declare function createMarkdownWrapperProps(mail: MailDefinition, envelope: ResolvedEnvelope, html: string, text: string): MailJsonObject;
+declare function renderContent(mail: MailDefinition, envelope: ResolvedEnvelope): Promise<RenderedContent>;
+declare function computePreview(mail: MailDefinition): Promise<PreviewComputation>;
+declare class PendingSend implements PendingMailSend<MailSendResult> {
+    #private;
+    constructor(mail: MailDefinition, options?: MutableSendOptions);
+    using(name: string): PendingSend;
+    onConnection(name: string): PendingSend;
+    onQueue(name: string): PendingSend;
+    delay(value: MailDelayValue): PendingSend;
+    afterCommit(): PendingSend;
+    then<TResult1 = MailSendResult, TResult2 = never>(onfulfilled?: ((value: MailSendResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult1 = never>(onrejected?: ((reason: unknown) => TResult1 | PromiseLike<TResult1>) | null): Promise<MailSendResult | TResult1>;
+    finally(onfinally?: (() => void) | null): Promise<MailSendResult>;
+    private execute;
+}
+interface MailRuntimeFacade {
+    sendMail(mail: MailDefinition | MailDefinitionInput, overrides?: MailOverrideInput): PendingMailSend<MailSendResult>;
+    previewMail(mail: MailDefinition | MailDefinitionInput, overrides?: MailOverrideInput): Promise<MailPreviewResult>;
+    renderMailPreview(mail: MailDefinition | MailDefinitionInput, overrides?: MailOverrideInput, format?: MailPreviewFormat): Promise<Response>;
+}
+declare function listFakeSentMails(): readonly FakeSentMail[];
+declare function resetFakeSentMails(): void;
+declare function listPreviewMailArtifacts(): readonly MailPreviewArtifact[];
+declare function resetPreviewMailArtifacts(): void;
+declare function resolveMailInput(mail: MailDefinition | MailDefinitionInput, overrides?: MailOverrideInput): MailDefinition;
+declare function configureMailRuntime(bindings?: MailRuntimeBindings): void;
+declare function getMailRuntimeBindings(): MailRuntimeBindings;
+declare function resetMailRuntime(): void;
+declare function sendMail(mail: MailDefinition | MailDefinitionInput, overrides?: MailOverrideInput): PendingMailSend<MailSendResult>;
+declare function previewMail(mail: MailDefinition | MailDefinitionInput, overrides?: MailOverrideInput): Promise<MailPreviewResult>;
+declare function renderMailPreview(mail: MailDefinition | MailDefinitionInput, overrides?: MailOverrideInput, format?: MailPreviewFormat): Promise<Response>;
+declare function getMailRuntime(): MailRuntimeFacade;
+declare const mailRuntimeInternals: {
+    HOLO_MAIL_DELIVER_JOB: string;
+    MailSendError: typeof MailSendError;
+    MailError: typeof MailError;
+    MailPreviewDisabledError: typeof MailPreviewDisabledError;
+    MailPreviewFormatUnavailableError: typeof MailPreviewFormatUnavailableError;
+    PendingSend: typeof PendingSend;
+    assertPreviewEnabled: typeof assertPreviewEnabled;
+    builtInDrivers: Readonly<Record<string, MailDriver<MailSendResult>>>;
+    createBaseSendResult: typeof createBaseSendResult;
+    createMailRecord: typeof createMailRecord;
+    createQueuedMailPayload: typeof createQueuedMailPayload;
+    createResolvedMail: typeof createResolvedMail;
+    createSmtpAddress: typeof createSmtpAddress;
+    createSmtpAttachment: typeof createSmtpAttachment;
+    createSmtpHeaders: typeof createSmtpHeaders;
+    createSmtpMessage: typeof createSmtpMessage;
+    createSendContext: typeof createSendContext;
+    createResolvedMailFromQueuedPayload: typeof createResolvedMailFromQueuedPayload;
+    computePreview: typeof computePreview;
+    createMarkdownWrapperProps: typeof createMarkdownWrapperProps;
+    createPreviewHtml: typeof createPreviewHtml;
+    createPreviewPolicy: typeof createPreviewPolicy;
+    deferSendUntilCommit: typeof deferSendUntilCommit;
+    deliverResolvedMail: typeof deliverResolvedMail;
+    deserializeQueuedAttachment: typeof deserializeQueuedAttachment;
+    dispatchQueuedMail: typeof dispatchQueuedMail;
+    dynamicImport: typeof dynamicImport;
+    ensureMailQueueJobRegistered: typeof ensureMailQueueJobRegistered;
+    escapeHtml: typeof escapeHtml;
+    formatAddress: typeof formatAddress;
+    freezeSendResult: typeof freezeSendResult;
+    getFakeSentState: typeof getFakeSentState;
+    getMailerConfig: typeof getMailerConfig;
+    getPreviewArtifactState: typeof getPreviewArtifactState;
+    getResolvedConfig: typeof getResolvedConfig;
+    getRuntimeBindings: typeof getRuntimeBindings;
+    getRuntimeState: typeof getRuntimeState;
+    loadDbModule: typeof loadDbModule;
+    loadNodemailerModule: typeof loadNodemailerModule;
+    loadQueueModule: typeof loadQueueModule;
+    loadStorageModule: typeof loadStorageModule;
+    isQueueRequested: typeof isQueueRequested;
+    normalizeExecutionDelay: typeof normalizeExecutionDelay;
+    normalizeExecutionString: typeof normalizeExecutionString;
+    normalizeDriverResult: typeof normalizeDriverResult;
+    persistPreviewArtifact: typeof persistPreviewArtifact;
+    prepareMailSend: typeof prepareMailSend;
+    renderContent: typeof renderContent;
+    renderMarkdown: typeof renderMarkdown;
+    renderMarkdownInline: typeof renderMarkdownInline;
+    renderPreviewResponse: typeof renderPreviewResponse;
+    renderView: typeof renderView;
+    resolveDriver: typeof resolveDriver;
+    resolveDriverByName: typeof resolveDriverByName;
+    resolveCurrentEnvironment: typeof resolveCurrentEnvironment;
+    resolveEnvelope: typeof resolveEnvelope;
+    resolveQueuePlan: typeof resolveQueuePlan;
+    resolveMailInput: typeof resolveMailInput;
+    resolveMailerName: typeof resolveMailerName;
+    resolveNodemailerModule: typeof resolveNodemailerModule;
+    resolveSourceKind: typeof resolveSourceKind;
+    resolveStorageModule: typeof resolveStorageModule;
+    runQueuedMailDelivery: typeof runQueuedMailDelivery;
+    sendViaSmtp: typeof sendViaSmtp;
+    serializeQueuedAttachment: typeof serializeQueuedAttachment;
+    setDbModuleLoader(loader: (() => Promise<DbModule | null>) | undefined): void;
+    setNodemailerModuleLoader(loader: (() => Promise<NodemailerModule>) | undefined): void;
+    setQueueModuleLoader(loader: (() => Promise<QueueModule>) | undefined): void;
+    setStorageModuleLoader(loader: (() => Promise<StorageModule>) | undefined): void;
+    stripMarkdownSyntax: typeof stripMarkdownSyntax;
+};
+
+declare function normalizeDriverName(value: string): string;
+declare function getRegistry(): Map<string, RegisteredMailDriver>;
+declare function registerMailDriver<TDriver extends string>(name: TDriver, driver: MailDriver, options?: RegisterMailDriverOptions): void;
+declare function getRegisteredMailDriver<TDriver extends string>(name: TDriver): RegisteredMailDriver<TDriver> | undefined;
+declare function listRegisteredMailDrivers(): readonly RegisteredMailDriver[];
+declare function resetMailDriverRegistry(): void;
+declare const mailRegistryInternals: {
+    getRegistry: typeof getRegistry;
+    normalizeDriverName: typeof normalizeDriverName;
+};
+
+declare const mail: Readonly<{
+    previewMail: typeof previewMail;
+    renderMailPreview: typeof renderMailPreview;
+    sendMail: typeof sendMail;
+}>;
+
+export { type FakeSentMail, MailAddress, MailDefinition, MailDefinitionInput, MailDelayValue, MailDriver, MailDriverExecutionContext, MailError, MailJsonObject, MailOverrideInput, type MailPreviewArtifact, MailPreviewDisabledError, MailPreviewFormat, MailPreviewFormatUnavailableError, MailPreviewPolicy, MailPreviewResult, MailRenderSource, MailRuntimeBindings, MailSendError, MailSendResult, MailViewRenderInput, PendingMailSend, RegisterMailDriverOptions, RegisteredMailDriver, ResolvedMail, ResolvedMailAttachment, configureMailRuntime, mail as default, getMailRuntime, getMailRuntimeBindings, getRegisteredMailDriver, listFakeSentMails, listPreviewMailArtifacts, listRegisteredMailDrivers, mailRegistryInternals, mailRuntimeInternals, previewMail, registerMailDriver, renderMailPreview, resetFakeSentMails, resetMailDriverRegistry, resetMailRuntime, resetPreviewMailArtifacts, sendMail };