{"_id":"@logickernel/mailotron","_rev":"6-92b2a1c8392fa615152af93c4a50915b","name":"@logickernel/mailotron","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@logickernel/mailotron","version":"0.1.0","keywords":["email","alias","plus-addressing"],"author":"","license":"ISC","_id":"@logickernel/mailotron@0.1.0","maintainers":[{"name":"yepayepayepa","email":"victor.valle@lkmx.io"}],"dist":{"shasum":"a3636bbf383deb4638fc7802eab0ea9cf261028c","tarball":"https://registry.npmjs.org/@logickernel/mailotron/-/mailotron-0.1.0.tgz","fileCount":6,"integrity":"sha512-0ql8zBhzQqbtEXwHm1qZXP0hUyCW2y3OrOt2O+6VO+ee3Kvx/BDfI7PuU7qz/FjbPPGSVCjUJ9Psl0ra5lPJMg==","signatures":[{"sig":"MEUCIQCobHOvQhLvbknfCC/psTPJpdHEAWLC9nC9ohH48KIToQIgBHBI7q1q9TFztOIOE3CUTlHAkjSYricezyTzIjUxjO4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26329},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"}},"gitHead":"fa22723e139108cb842a919aa77907cc586dfaf3","scripts":{"test":"jest","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build","test:integration":"ts-node test/integration.ts"},"_npmUser":{"name":"yepayepayepa","email":"victor.valle@lkmx.io"},"_npmVersion":"11.9.0","description":"Mail automation library toolkit","directories":{},"_nodeVersion":"22.17.1","dependencies":{"imap":"^0.8.19","dotenv":"^17.2.3","mailparser":"^3.9.1","@logickernel/logger":"^0.12.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","ts-jest":"^29.4.6","ts-node":"^10.9.2","nodemailer":"^8.0.1","typescript":"^5.9.3","@types/imap":"^0.8.43","@types/jest":"^30.0.0","@types/node":"^25.3.3","@types/mailparser":"^3.4.6","@types/nodemailer":"^7.0.11"},"_npmOperationalInternal":{"tmp":"tmp/mailotron_0.1.0_1772592093114_0.09926228543409232","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@logickernel/mailotron","version":"0.1.1","keywords":["email","alias","plus-addressing"],"author":"","license":"ISC","_id":"@logickernel/mailotron@0.1.1","maintainers":[{"name":"yepayepayepa","email":"victor.valle@lkmx.io"}],"dist":{"shasum":"81649dfb6009e2e3b56a85d4f492ed6869cf276c","tarball":"https://registry.npmjs.org/@logickernel/mailotron/-/mailotron-0.1.1.tgz","fileCount":6,"integrity":"sha512-uqaPSorPNYCYo5g+na75TWhG55S5k8Q8dnxBbR5uH2lGqglkLSekyU1mSTPP861m5wr8Jq3gB+NvkH/eCnuwFA==","signatures":[{"sig":"MEYCIQCIK6c0AYh5lLiqboaG7+iBCqmhZwKcIuJ2rfBot1K84AIhAO0Rddz+BIxK1E6hj2ovoDj8PP1dyiPxkRWegP4DCmCa","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26704},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"}},"gitHead":"67a767655ed39a6bc2d00265559fe0801d92f1d1","scripts":{"test":"jest","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build","test:integration":"ts-node test/integration.ts"},"_npmUser":{"name":"yepayepayepa","email":"victor.valle@lkmx.io"},"_npmVersion":"11.9.0","description":"Mail automation library toolkit","directories":{},"_nodeVersion":"22.17.1","dependencies":{"imap":"^0.8.19","dotenv":"^17.2.3","mailparser":"^3.9.1","@logickernel/logger":"^0.12.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","ts-jest":"^29.4.6","ts-node":"^10.9.2","nodemailer":"^8.0.1","typescript":"^5.9.3","@types/imap":"^0.8.43","@types/jest":"^30.0.0","@types/node":"^25.3.3","@types/mailparser":"^3.4.6","@types/nodemailer":"^7.0.11"},"_npmOperationalInternal":{"tmp":"tmp/mailotron_0.1.1_1772592302844_0.3563363790808498","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@logickernel/mailotron","version":"0.1.2","keywords":["email","alias","plus-addressing"],"author":"","license":"ISC","_id":"@logickernel/mailotron@0.1.2","maintainers":[{"name":"yepayepayepa","email":"victor.valle@lkmx.io"}],"dist":{"shasum":"9e4f7d0eaf65b7aa3c83558a981dd91264b26a9f","tarball":"https://registry.npmjs.org/@logickernel/mailotron/-/mailotron-0.1.2.tgz","fileCount":6,"integrity":"sha512-jgcxe3qmkEGPswVrpr8htIhIiw34Lt7pkwRGajx6qK/jBXS//yA4o/jNCUuxKv6xHLTxKN+1IiZkwjpCtPWJVA==","signatures":[{"sig":"MEQCIAvBhlTx4EaVByuV2RZ27yee1yIkcU1J/ccIi/eKs2hOAiBsJ4blAr9i/D8X/+dstWJsUxwc9d0zL18Ya0TsGOoyhQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26697},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"}},"gitHead":"4f84f0bf9ca1944d02cea9524c3276269885ba1f","scripts":{"test":"jest","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build","test:integration":"ts-node test/integration.ts"},"_npmUser":{"name":"yepayepayepa","email":"victor.valle@lkmx.io"},"_npmVersion":"11.9.0","description":"Mail automation library toolkit","directories":{},"_nodeVersion":"22.17.1","dependencies":{"imap":"^0.8.19","dotenv":"^17.2.3","mailparser":"^3.9.1","@logickernel/logger":"^0.12.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","ts-jest":"^29.4.6","ts-node":"^10.9.2","nodemailer":"^8.0.1","typescript":"^5.9.3","@types/imap":"^0.8.43","@types/jest":"^30.0.0","@types/node":"^25.3.3","@types/mailparser":"^3.4.6","@types/nodemailer":"^7.0.11"},"_npmOperationalInternal":{"tmp":"tmp/mailotron_0.1.2_1772595367355_0.6553438263401601","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@logickernel/mailotron","version":"0.1.3","keywords":["email","alias","plus-addressing"],"author":"","license":"ISC","_id":"@logickernel/mailotron@0.1.3","maintainers":[{"name":"yepayepayepa","email":"victor.valle@lkmx.io"}],"dist":{"shasum":"2d7489dfc817413b86f8985ead8ebc29eedc5e9f","tarball":"https://registry.npmjs.org/@logickernel/mailotron/-/mailotron-0.1.3.tgz","fileCount":6,"integrity":"sha512-KTpozZFIs5OPLEZbqUGodb5KyUywHIy/D+LbvVilyFmII3TEQiXWHDnPGnNMrhc9eBB9qBhMaSfxou/R6l0WTQ==","signatures":[{"sig":"MEUCIQC3UFM463Co05heng6cv3rNHlF5Sm/sdCKG5OhyRK0czAIgWTA/0ibWy0TQ9jOkeBUC7MgDFwj0oIeMn2tHAuQ0/E8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25792},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"}},"gitHead":"2738e6d533847d2c61c2b58ce7c05d63a54a4b29","scripts":{"test":"jest","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build","test:integration":"ts-node test/integration.ts"},"_npmUser":{"name":"yepayepayepa","email":"victor.valle@lkmx.io"},"_npmVersion":"11.9.0","description":"Mail automation library toolkit","directories":{},"_nodeVersion":"22.17.1","dependencies":{"imap":"^0.8.19","dotenv":"^17.2.3","mailparser":"^3.9.1","@logickernel/logger":"^0.12.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","ts-jest":"^29.4.6","ts-node":"^10.9.2","nodemailer":"^8.0.1","typescript":"^5.9.3","@types/imap":"^0.8.43","@types/jest":"^30.0.0","@types/node":"^25.3.3","@types/mailparser":"^3.4.6","@types/nodemailer":"^7.0.11"},"_npmOperationalInternal":{"tmp":"tmp/mailotron_0.1.3_1772633416745_0.36225452740685404","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@logickernel/mailotron","version":"0.1.4","keywords":["email","alias","plus-addressing"],"author":"","license":"ISC","_id":"@logickernel/mailotron@0.1.4","maintainers":[{"name":"yepayepayepa","email":"victor.valle@lkmx.io"}],"dist":{"shasum":"3dfe7af6ca70481ca1708aefccaed1e2eb24f58a","tarball":"https://registry.npmjs.org/@logickernel/mailotron/-/mailotron-0.1.4.tgz","fileCount":6,"integrity":"sha512-dP4dRRvck0V+CiB1beXQfPVwk2plid0OWlonE5lVcEXQA0FTCroP/uAE6gIZejS02/8wm0UfZvP+p5tikQBb7Q==","signatures":[{"sig":"MEYCIQC00DKJBlnefXpA+GFC7Sz85Zemkl+nKwG1wfMa45dIhAIhAKLWMFcrk5Cdx/jvZGU7jM9XO28KCmy/WTwZSfvcsY0M","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25916},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"}},"gitHead":"613986210fe2323a1c36dfe7ef7a3b70c4fc097b","scripts":{"test":"jest","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build","test:integration":"ts-node test/integration.ts"},"_npmUser":{"name":"yepayepayepa","email":"victor.valle@lkmx.io"},"_npmVersion":"11.9.0","description":"Mail automation library toolkit","directories":{},"_nodeVersion":"22.17.1","dependencies":{"imap":"^0.8.19","dotenv":"^17.2.3","mailparser":"^3.9.1","@logickernel/logger":"^0.12.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","ts-jest":"^29.4.6","ts-node":"^10.9.2","nodemailer":"^8.0.1","typescript":"^5.9.3","@types/imap":"^0.8.43","@types/jest":"^30.0.0","@types/node":"^25.3.3","@types/mailparser":"^3.4.6","@types/nodemailer":"^7.0.11"},"_npmOperationalInternal":{"tmp":"tmp/mailotron_0.1.4_1772633587084_0.12877166789022643","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@logickernel/mailotron","version":"0.2.0","description":"Mail automation library toolkit","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"require":"./dist/index.js","types":"./dist/index.d.ts"}},"type":"commonjs","scripts":{"build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","test":"jest","test:integration":"ts-node test/integration.ts","prepublishOnly":"npm run build"},"keywords":["email","alias","plus-addressing"],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"dependencies":{"@logickernel/logger":"^0.15.0","dotenv":"^17.2.3","imap":"^0.8.19","mailparser":"^3.9.1"},"devDependencies":{"@types/imap":"^0.8.43","@types/jest":"^30.0.0","@types/mailparser":"^3.4.6","@types/node":"^25.3.3","@types/nodemailer":"^7.0.11","jest":"^30.2.0","nodemailer":"^8.0.1","ts-jest":"^29.4.6","ts-node":"^10.9.2","typescript":"^5.9.3"},"gitHead":"c0064547427fd4640c65fd2e7b2fdb1f4a81d593","_id":"@logickernel/mailotron@0.2.0","_nodeVersion":"22.17.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-BeVN+Og8HRSgTPAj5Jhxl/tfTG/Cbf3pDnYt5NfQ8cVzuu8QJX4YBvxcdU15uhwmrRfXSPtnJkKYD7JaF+dsOQ==","shasum":"0f0044cef9f2e680cbccc08132e3669a01e82510","tarball":"https://registry.npmjs.org/@logickernel/mailotron/-/mailotron-0.2.0.tgz","fileCount":10,"unpackedSize":23590,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCuhk1udEQDtNN6Q3uyLpw7UcCW09p5Uh3uEraVDWy2KAIgWu8LKhHv3Piea81UdlWFhTyMcjE4Cvnl+m8NlG2k5fM="}]},"_npmUser":{"name":"yepayepayepa","email":"victor.valle@lkmx.io"},"directories":{},"maintainers":[{"name":"yepayepayepa","email":"victor.valle@lkmx.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mailotron_0.2.0_1775011009244_0.8177867794175024"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-04T02:41:32.927Z","modified":"2026-04-01T02:36:49.501Z","0.1.0":"2026-03-04T02:41:33.274Z","0.1.1":"2026-03-04T02:45:03.009Z","0.1.2":"2026-03-04T03:36:07.525Z","0.1.3":"2026-03-04T14:10:16.888Z","0.1.4":"2026-03-04T14:13:07.269Z","0.2.0":"2026-04-01T02:36:49.387Z"},"license":"ISC","keywords":["email","alias","plus-addressing"],"description":"Mail automation library toolkit","maintainers":[{"name":"yepayepayepa","email":"victor.valle@lkmx.io"}],"readme":"# @logickernel/mailotron\n\nA TypeScript library for email automation in tests. Generates unique plus-addressed inboxes and waits for emails to arrive via IMAP.\n\nIt relies on **Gmail's plus-addressing**: a Gmail mailbox like `you@gmail.com` also receives mail at `you+<tag>@gmail.com`. Gmail requires the tag to be numeric, so Mailotron generates unique numeric suffixes to give each test its own dedicated inbox.\n\n## Installation\n\n```sh\nnpm install @logickernel/mailotron\n```\n\n## Quick start\n\n```ts\nimport { getInbox, waitForEmail } from '@logickernel/mailotron';\n\n// 1. Generate a unique inbox alias\nconst address = getInbox();\n// → 'you+17725849001@gmail.com'\n\n// 2. Trigger something that sends an email to address …\n\n// 3. Wait for it to arrive\ntry {\n  const email = await waitForEmail(address, 'Welcome', { timeout: 30 });\n  console.log(email.subject); // 'Welcome to Acme'\n  console.log(email.text);    // plain-text body\n} catch (err) {\n  // Thrown when no matching email arrives within the timeout\n  throw new Error(`Email not received: ${(err as Error).message}`);\n}\n```\n\n## Configuration\n\nCopy `.env.template` to `.env` and fill in your credentials:\n\n```sh\ncp .env.template .env\n```\n\n**Required**\n\n| Variable | Description |\n|---|---|\n| `MAILOTRON_EMAIL_ADDRESS` | Base Gmail address used by `getInbox()` |\n| `MAILOTRON_IMAP_PASSWORD` | IMAP app password |\n\n**Optional**\n\nThe defaults below work out of the box with Gmail and Google Workspace. \nOnly change these if you know what you are doing.\n\n| Variable | Default | Description |\n|---|---|---|\n| `MAILOTRON_IMAP_USER` | `MAILOTRON_EMAIL_ADDRESS` | IMAP login username |\n| `MAILOTRON_IMAP_HOST` | `imap.gmail.com` | IMAP server hostname |\n| `MAILOTRON_IMAP_PORT` | `993` | IMAP server port |\n| `MAILOTRON_IMAP_SECURE` | `true` | Set to `false` to disable TLS |\n| `MAILOTRON_SMTP_HOST` | `smtp.gmail.com` | SMTP host (integration tests) |\n| `MAILOTRON_SMTP_PORT` | `587` | SMTP port (integration tests) |\n| `MAILOTRON_SMTP_PASSWORD` | `MAILOTRON_IMAP_PASSWORD` | SMTP password (integration tests) |\n| `LOGGER_CONSOLE_FORMAT` | — | Set to `plain` for unformatted logs |\n\n### Gmail App Password\n\nGmail requires an **App Password** rather than your account password:\n\n1. Enable 2-Step Verification on your Google account.\n2. Go to **Security → App passwords** and generate a password for \"Mail\".\n3. Use that 16-character password (no spaces) as `MAILOTRON_IMAP_PASSWORD`.\n\n## API\n\n### `getInbox(): string`\n\nReturns a unique plus-addressed inbox alias derived from `MAILOTRON_EMAIL_ADDRESS`, e.g. `you+17725849001@example.com`.\n\nThrows if `MAILOTRON_EMAIL_ADDRESS` is not set or is not a valid email address.\n\n---\n\n### `waitForEmail(emailAddress, pattern, options?): Promise<Email>`\n\nPolls IMAP until an email addressed to `emailAddress` whose subject, text, or HTML matches `pattern` arrives, then resolves with a structured `Email` object.\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `emailAddress` | `string` | — | Recipient address to match (plus-tag or base) |\n| `pattern` | `string \\| RegExp` | — | Tested against subject, text body, and HTML |\n| `options.timeout` | `number` | `10` | Seconds before rejecting with a Timeout error |\n| `options.since` | `Date \\| number` | 10 min ago | Only consider emails received after this point |\n\n```ts\ninterface Email {\n  subject: string;\n  text: string;\n  html: string;\n  messageId: string;\n  from: string;\n  to: string[];\n  cc: string[];\n  bcc: string[];\n  replyTo: string;\n  /** ISO 8601 string, or null if the message had no Date header */\n  date: string | null;\n  priority: string;\n  attachments: EmailAttachment[];\n}\n\ninterface EmailAttachment {\n  filename: string;\n  contentType: string;\n  size: number;\n}\n```\n\nRejects with `Error('Timeout: …')` if no matching email arrives within the timeout.\n\n---\n\n### `disconnect()`\n\nCloses the shared IMAP connection and clears internal state. Call this in test teardown (`afterAll`) or let it happen automatically on process exit.\n\n```typescript\nimport { disconnect } from \"@logickernel/mailotron\"\n\nafterAll(() => {\n  disconnect()\n})\n```\n\n---\n\n### `available`\n\nBoolean indicating whether mailotron credentials are configured (`MAILOTRON_EMAIL_ADDRESS` is set). Use this to skip email-dependent tests:\n\n```typescript\nimport { available } from \"@logickernel/mailotron\"\n\ntest.skip(!available, \"mailotron not configured\")\n```\n\n\n## Development\n\n```sh\nnpm run build          # compile TypeScript → dist/\nnpm run typecheck      # type-check without emitting\nnpm test               # unit tests (Jest + ts-jest, no network required)\nnpm run test:integration  # end-to-end test (requires .env with SMTP + IMAP credentials)\n```\n","readmeFilename":"README.md"}