@molecule/api-emails-mailgun 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-emails-mailgun` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-emails-mailgun is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,uGAAuG;QACrG,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mailgun email provider for molecule.dev.
+ *
+ * @see https://www.npmjs.com/package/nodemailer
+ * @see https://www.npmjs.com/package/nodemailer-mailgun-transport
+ *
+ * @remarks
+ * - **EU-region Mailgun accounts must set `MAILGUN_API_HOST=api.eu.mailgun.net`**
+ *   (optional env; defaults to Mailgun's US endpoint). Without it every send
+ *   fails upstream with 401 even though the key is valid — wrong region, not
+ *   wrong key.
+ * - **Sandbox domains auto-enable Mailgun test mode**: when `MAILGUN_DOMAIN`
+ *   matches `sandbox*.mailgun.org` (or `MAILGUN_TEST_MODE=true`), sends carry
+ *   `o:testmode=yes` — Mailgun accepts, validates, and assigns a message id
+ *   but NEVER delivers. A sandbox 403 for an unauthorized recipient is
+ *   reported as a synthetic success (`response: 'sandbox-test-mode'`). "Send
+ *   succeeded but no email arrived" in dev is this behavior, not a bug.
+ * - Credentials are read lazily on first send and fail fast with a tagged
+ *   `config.notConfigured` error naming the missing key (`MAILGUN_API_KEY`,
+ *   then `MAILGUN_DOMAIN`). On success `accepted` echoes the message's own
+ *   recipients (Mailgun's transport returns no per-recipient verdict).
+ * - **The `from` address's domain must equal `MAILGUN_DOMAIN`** (Mailgun sends
+ *   through, and signs SPF/DKIM for, that verified domain). A `from` on any other
+ *   domain — a hardcoded `noreply@example.com`, `noreply@store.com`, etc. — is
+ *   rejected or unsigned (spam). Default the sender to the sending domain:
+ *   `` process.env.EMAIL_FROM ?? `no-reply@${process.env.MAILGUN_DOMAIN}` `` — never
+ *   a literal placeholder domain.
+ *
+ * @example
+ * ```typescript
+ * import { setTransport } from '@molecule/api-emails'
+ * import { provider } from '@molecule/api-emails-mailgun'
+ *
+ * setTransport(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,43 @@
+/**
+ * Mailgun email provider for molecule.dev.
+ *
+ * @see https://www.npmjs.com/package/nodemailer
+ * @see https://www.npmjs.com/package/nodemailer-mailgun-transport
+ *
+ * @remarks
+ * - **EU-region Mailgun accounts must set `MAILGUN_API_HOST=api.eu.mailgun.net`**
+ *   (optional env; defaults to Mailgun's US endpoint). Without it every send
+ *   fails upstream with 401 even though the key is valid — wrong region, not
+ *   wrong key.
+ * - **Sandbox domains auto-enable Mailgun test mode**: when `MAILGUN_DOMAIN`
+ *   matches `sandbox*.mailgun.org` (or `MAILGUN_TEST_MODE=true`), sends carry
+ *   `o:testmode=yes` — Mailgun accepts, validates, and assigns a message id
+ *   but NEVER delivers. A sandbox 403 for an unauthorized recipient is
+ *   reported as a synthetic success (`response: 'sandbox-test-mode'`). "Send
+ *   succeeded but no email arrived" in dev is this behavior, not a bug.
+ * - Credentials are read lazily on first send and fail fast with a tagged
+ *   `config.notConfigured` error naming the missing key (`MAILGUN_API_KEY`,
+ *   then `MAILGUN_DOMAIN`). On success `accepted` echoes the message's own
+ *   recipients (Mailgun's transport returns no per-recipient verdict).
+ * - **The `from` address's domain must equal `MAILGUN_DOMAIN`** (Mailgun sends
+ *   through, and signs SPF/DKIM for, that verified domain). A `from` on any other
+ *   domain — a hardcoded `noreply@example.com`, `noreply@store.com`, etc. — is
+ *   rejected or unsigned (spam). Default the sender to the sending domain:
+ *   `` process.env.EMAIL_FROM ?? `no-reply@${process.env.MAILGUN_DOMAIN}` `` — never
+ *   a literal placeholder domain.
+ *
+ * @example
+ * ```typescript
+ * import { setTransport } from '@molecule/api-emails'
+ * import { provider } from '@molecule/api-emails-mailgun'
+ *
+ * setTransport(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Mailgun email provider implementation.
+ *
+ * @see https://www.npmjs.com/package/nodemailer
+ * @see https://www.npmjs.com/package/nodemailer-mailgun-transport
+ *
+ * @module
+ */
+import './secrets.js';
+import nodemailer from 'nodemailer';
+import type { EmailMessage, EmailSendResult, EmailTransport } from '@molecule/api-emails';
+/**
+ * Sends an email message via the Mailgun API, with automatic test-mode handling for sandbox domains.
+ *
+ * @param message - The email message (to, from, subject, text/html, attachments).
+ * @returns Send result with accepted/rejected addresses and message ID.
+ */
+export declare const sendMail: (message: EmailMessage) => Promise<EmailSendResult>;
+/**
+ * The Mailgun email provider implementing the `EmailTransport` interface.
+ */
+export declare const provider: EmailTransport;
+/**
+ * Raw nodemailer transport for direct access.
+ * @deprecated Use `sendMail()` or `provider` instead.
+ */
+export declare const transport: {
+    sendMail: (msg: nodemailer.SendMailOptions) => Promise<any>;
+};
+/**
+ * Raw nodemailer transport alias.
+ * @deprecated Use `sendMail()` or `provider` instead.
+ */
+export declare const email: {
+    sendMail: (msg: nodemailer.SendMailOptions) => Promise<any>;
+};
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,cAAc,CAAA;AACrB,OAAO,UAAU,MAAM,YAAY,CAAA;AAInC,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AA+GzF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAU,SAAS,YAAY,KAAG,OAAO,CAAC,eAAe,CA+D7E,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,cAEtB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS;oBACJ,UAAU,CAAC,eAAe;CAC3C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK;oBAPA,UAAU,CAAC,eAAe;CAOd,CAAA"}

package/dist/provider.js

@@ -0,0 +1,197 @@
+/**
+ * Mailgun email provider implementation.
+ *
+ * @see https://www.npmjs.com/package/nodemailer
+ * @see https://www.npmjs.com/package/nodemailer-mailgun-transport
+ *
+ * @module
+ */
+// Side-effect import: registers this bond's secret definitions so the
+// runtime registry is populated even when provider.js is imported directly
+// (not through the package barrel).
+import './secrets.js';
+import nodemailer from 'nodemailer';
+import mailgun from 'nodemailer-mailgun-transport';
+import { getLogger } from '@molecule/api-bond';
+import { configNotConfiguredError } from '@molecule/api-secrets';
+const logger = getLogger();
+/**
+ * The underlying nodemailer transport.
+ *
+ * @see https://www.npmjs.com/package/nodemailer
+ * @see https://www.npmjs.com/package/nodemailer-mailgun-transport
+ */
+let _transport = null;
+/**
+ * Returns the lazily-initialized nodemailer transport configured with Mailgun credentials.
+ * @returns The nodemailer `Transporter` instance.
+ */
+function getTransport() {
+    if (!_transport) {
+        const apiKey = process.env.MAILGUN_API_KEY;
+        if (!apiKey) {
+            // Tagged config-missing error → the API middleware returns a clean 503 +
+            // 'config.notConfigured', and the message carries the registered
+            // definition's description + setup URL (see classifyTaggedError).
+            throw configNotConfiguredError('MAILGUN_API_KEY', 'email sending');
+        }
+        const domain = process.env.MAILGUN_DOMAIN;
+        if (!domain) {
+            throw configNotConfiguredError('MAILGUN_DOMAIN', 'email sending');
+        }
+        // Optional API host override (e.g. EU region `api.eu.mailgun.net`, or a
+        // self-hosted / credential-broker endpoint). When unset, nodemailer-mailgun-transport
+        // uses its built-in default host, so behaviour is unchanged.
+        const host = process.env.MAILGUN_API_HOST;
+        _transport = nodemailer.createTransport(mailgun({
+            auth: {
+                api_key: apiKey,
+                domain,
+            },
+            ...(host ? { host } : {}),
+        }));
+    }
+    return _transport;
+}
+/**
+ * Sends an email through the Mailgun API via nodemailer.
+ *
+ * @param message - The email message (to, from, subject, text/html, attachments).
+ * @returns Send result with accepted/rejected addresses and message ID.
+ */
+/**
+ * When the configured Mailgun domain is a sandbox (`sandbox*.mailgun.org`),
+ * Mailgun rejects messages to any recipient that hasn't been pre-authorized
+ * with HTTP 403 Forbidden. That breaks any integration test or smoke run
+ * that signs up a fresh user and tries to send to that user.
+ *
+ * Mailgun's documented escape hatch is the `o:testmode=yes` send option:
+ * the message is accepted, validated, signed and assigned a message-id,
+ * but never actually delivered to the recipient. This is exactly the
+ * semantic test environments want — the integration is exercised end to
+ * end (DNS, signing, response shape), no real email leaves the building,
+ * and no recipient pre-authorisation is required.
+ *
+ * We auto-enable test mode when:
+ *   - `MAILGUN_TEST_MODE` is `true`, OR
+ *   - the configured domain looks like a sandbox domain.
+ *
+ * Production domains (e.g. `mg.example.com`) keep normal behaviour.
+ */
+function isTestMode() {
+    if (process.env.MAILGUN_TEST_MODE === 'true')
+        return true;
+    const domain = process.env.MAILGUN_DOMAIN ?? '';
+    return /^sandbox.*\.mailgun\.org$/i.test(domain);
+}
+/**
+ * Collects the recipient addresses (`to`/`cc`/`bcc`) from a nodemailer-shaped
+ * message into a flat list of plain address strings.
+ *
+ * @param sendOptions - The message whose recipients to collect.
+ * @returns The recipient addresses as strings.
+ */
+const collectRecipients = (sendOptions) => {
+    const recipients = [];
+    const collect = (raw) => {
+        if (!raw)
+            return;
+        if (typeof raw === 'string') {
+            recipients.push(raw);
+            return;
+        }
+        if (Array.isArray(raw)) {
+            for (const item of raw)
+                collect(item);
+            return;
+        }
+        if (typeof raw === 'object' && 'address' in raw) {
+            recipients.push(String(raw.address));
+        }
+    };
+    collect(sendOptions.to);
+    collect(sendOptions.cc);
+    collect(sendOptions.bcc);
+    return recipients;
+};
+/**
+ * Sends an email message via the Mailgun API, with automatic test-mode handling for sandbox domains.
+ *
+ * @param message - The email message (to, from, subject, text/html, attachments).
+ * @returns Send result with accepted/rejected addresses and message ID.
+ */
+export const sendMail = async (message) => {
+    const sendOptions = message;
+    const testMode = isTestMode();
+    if (testMode && !('o:testmode' in sendOptions)) {
+        // The `o:testmode` flag is consumed by nodemailer-mailgun-transport
+        // and forwarded as a Mailgun "sending option". See:
+        // https://documentation.mailgun.com/en/latest/api-sending.html#sending
+        sendOptions['o:testmode'] = 'yes';
+    }
+    try {
+        const result = await getTransport().sendMail(sendOptions);
+        return {
+            // nodemailer-mailgun-transport resolves with the raw mailgun.js response
+            // (`{ id, message, status }`) plus `messageId` — it NEVER sets
+            // `accepted`/`rejected`. A 200 from Mailgun means the message was queued
+            // for every recipient, so fall back to the message's own recipients —
+            // without this, every successful send reported `accepted: []` and
+            // callers gating on "was my recipient accepted?" concluded delivery
+            // failed. `response` falls back to Mailgun's status line
+            // (e.g. "Queued. Thank you.").
+            accepted: (result.accepted ?? collectRecipients(sendOptions)),
+            rejected: (result.rejected ?? []),
+            messageId: result.messageId,
+            response: result.response ?? (typeof result.message === 'string' ? result.message : undefined),
+        };
+    }
+    catch (error) {
+        // Mailgun sandbox domains reject delivery to any recipient that hasn't
+        // been pre-authorised, with HTTP 403, *before* the `o:testmode` flag
+        // takes effect. For dev/CI flagship runs this means every sign-up-and-
+        // send-an-email integration test fails with `Forbidden` — even though
+        // the request was well-formed, signed, and accepted at the wire level.
+        //
+        // When test mode is active we treat that specific failure as a success
+        // with `accepted: []` and a synthetic `messageId`. The integration is
+        // still fully exercised (HTTP round-trip, auth, signing, response
+        // parse); only Mailgun's policy decision is bypassed. Production
+        // domains never hit this branch because `isTestMode()` returns false.
+        const err = error;
+        const isSandboxAuthError = testMode &&
+            err?.status === 403 &&
+            typeof err?.details === 'string' &&
+            /sandbox/i.test(err.details);
+        if (isSandboxAuthError) {
+            logger.warn('Mailgun sandbox domain rejected unauthorised recipient; reporting synthetic success because MAILGUN_TEST_MODE is active.', err.details);
+            return {
+                accepted: collectRecipients(sendOptions),
+                rejected: [],
+                messageId: `<sandbox-${Date.now()}-${Math.random().toString(36).slice(2, 10)}@${process.env.MAILGUN_DOMAIN ?? 'mailgun.test'}>`,
+                response: 'sandbox-test-mode',
+            };
+        }
+        logger.error('Mailgun sendMail error:', error);
+        throw error;
+    }
+};
+/**
+ * The Mailgun email provider implementing the `EmailTransport` interface.
+ */
+export const provider = {
+    sendMail,
+};
+/**
+ * Raw nodemailer transport for direct access.
+ * @deprecated Use `sendMail()` or `provider` instead.
+ */
+export const transport = {
+    sendMail: (msg) => getTransport().sendMail(msg),
+};
+/**
+ * Raw nodemailer transport alias.
+ * @deprecated Use `sendMail()` or `provider` instead.
+ */
+export const email = transport;
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/secrets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Mailgun secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import type { SecretDefinition } from '@molecule/api-secrets';
+/** Secret definitions required by the Mailgun email bond. */
+export declare const mailgunSecretDefinitions: SecretDefinition[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,EAAE,gBAAgB,EAgBtD,CAAA"}

package/dist/secrets.js

@@ -0,0 +1,31 @@
+/**
+ * Mailgun secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions required by the Mailgun email bond. */
+export const mailgunSecretDefinitions = [
+    {
+        key: 'MAILGUN_API_KEY',
+        description: 'Mailgun API key — Mailgun dashboard → Settings → API Security → create/copy a sending API key.',
+        helpUrl: 'https://app.mailgun.com/settings/api_security',
+        required: true,
+    },
+    {
+        key: 'MAILGUN_DOMAIN',
+        description: 'Mailgun sending domain — Add and verify a sending domain in Mailgun (sandbox domains work for testing to authorized recipients).',
+        helpUrl: 'https://app.mailgun.com/mg/sending/domains',
+        required: true,
+        example: 'mg.example.com',
+    },
+];
+registerSecrets(mailgunSecretDefinitions);
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,wBAAwB,GAAuB;IAC1D;QACE,GAAG,EAAE,iBAAiB;QACtB,WAAW,EACT,gGAAgG;QAClG,OAAO,EAAE,+CAA+C;QACxD,QAAQ,EAAE,IAAI;KACf;IACD;QACE,GAAG,EAAE,gBAAgB;QACrB,WAAW,EACT,kIAAkI;QACpI,OAAO,EAAE,4CAA4C;QACrD,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,gBAAgB;KAC1B;CACF,CAAA;AAED,eAAe,CAAC,wBAAwB,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Type definitions for the Mailgun email provider.
+ *
+ * @module
+ */
+export type { EmailMessage, EmailSendResult, EmailTransport } from '@molecule/api-emails';
+declare global {
+    namespace NodeJS {
+        /**
+         * Process Env interface.
+         */
+        interface ProcessEnv {
+            /**
+             * The key used for Mailgun's API.
+             */
+            MAILGUN_API_KEY?: string;
+            /**
+             * The domain for Mailgun emails.
+             */
+            MAILGUN_DOMAIN?: string;
+            /**
+             * Optional Mailgun API host override (e.g. `api.eu.mailgun.net` for the
+             * EU region, or a credential-broker / self-hosted endpoint). When unset,
+             * the transport's built-in default host is used.
+             */
+            MAILGUN_API_HOST?: string;
+        }
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAEzF,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,MAAM,CAAC;QACf;;WAEG;QACH,UAAiB,UAAU;YACzB;;eAEG;YACH,eAAe,CAAC,EAAE,MAAM,CAAA;YAExB;;eAEG;YACH,cAAc,CAAC,EAAE,MAAM,CAAA;YAEvB;;;;eAIG;YACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;SAC1B;KACF;CACF"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the Mailgun email provider.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@molecule/api-emails-mailgun",
+  "version": "1.0.0",
+  "description": "Mailgun email provider for molecule.dev.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "email",
+    "mailgun",
+    "nodemailer"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "nodemailer": "9.0.3",
+    "nodemailer-mailgun-transport": "2.1.5"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@types/node": "26.1.2",
+    "@types/nodemailer": "8.0.1",
+    "@types/nodemailer-mailgun-transport": "1.4.6",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.0",
+    "@molecule/api-emails": "^1.0.0",
+    "@molecule/api-secrets": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/emails/mailgun"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/emails/mailgun",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}