@omega.js/backend 0.1.0

package/test/email/templates.test.js

@@ -0,0 +1,288 @@
+/**
+ * Test: Email template rendering (campaign/transactional templates)
+ *
+ * Pure rendering tests — no network, no Firebase, no SendGrid.
+ * Verifies the prepare → render pipeline for card, plain, order, feedback templates.
+ */
+const { renderEmail } = require('../../dist/manager/libraries/email/generators/lib/mjml-template.js');
+const { resolveEmailTemplate: resolveTemplate } = require('../../dist/manager/libraries/email/generators/lib/templates/index.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const TEST_BRAND = {
+  id: 'testco',
+  name: 'TestCo',
+  // Deliberately different from brand.name so the footer assertions prove the parent
+  // identity is read from config rather than defaulted.
+  company: 'TestCo Holdings Inc',
+  url: 'https://testco.example',
+  contact: { email: 'hello@testco.example' },
+  images: {
+    brandmark: 'https://cdn.example.com/brandmark-1024.png',
+    companyWordmark: 'https://cdn.example.com/company-wordmark.png',
+  },
+  address: {
+    line1: '123 Main St',
+    city: 'Testville',
+    region: 'TS',
+    postalCode: '12345',
+  },
+};
+
+const TEMPLATES = ['card', 'plain', 'order', 'feedback'];
+
+async function render(templateName, dataOverrides = {}) {
+  const data = {
+    brand: TEST_BRAND,
+    content: {
+      title: 'Test Title',
+      message: '<p>Hello <strong>world</strong></p>',
+    },
+    email: {
+      subject: 'Test Subject',
+      preview: 'Preview text',
+      unsubscribeUrl: 'https://testco.example/portal/email-preferences',
+    },
+    signoff: { type: 'team' },
+    ...dataOverrides,
+  };
+
+  return renderEmail({ brand: TEST_BRAND, template: templateName, data });
+}
+
+module.exports = defineCases({
+  description: 'Email template rendering (card, plain, order, feedback)',
+  type: 'suite',
+  auth: 'none',
+  timeout: 30000,
+  tests: [
+    {
+      name: 'every registered template resolves and has build()',
+      async run({ assert }) {
+        for (const name of TEMPLATES) {
+          const t = resolveTemplate(name);
+          assert.ok(t, `Template "${name}" should resolve`);
+          assert.ok(typeof t.build === 'function', `Template "${name}" should expose build()`);
+          assert.ok(t.meta?.name, `Template "${name}" should expose meta.name`);
+        }
+      },
+    },
+
+    {
+      name: 'every template renders valid HTML without MJML errors',
+      async run({ assert }) {
+        for (const name of TEMPLATES) {
+          const result = await render(name);
+          assert.ok(result.html.includes('<html'), `${name}: produces HTML`);
+          assert.equal(result.template, name, `${name}: reports correct template name`);
+          // plain uses width="100%" which MJML warns about (expected — it bypasses the 600px default)
+          if (name !== 'plain') {
+            assert.equal(result.errors.length, 0, `${name}: no MJML errors`);
+          }
+        }
+      },
+    },
+
+    {
+      name: 'card template renders brand, title, message, signoff, and footer',
+      async run({ assert }) {
+        const result = await render('card');
+
+        assert.ok(result.html.includes('TestCo'), 'card: brand name renders');
+        assert.ok(result.html.includes('Test Title'), 'card: title renders');
+        assert.ok(result.html.includes('Hello <strong>world</strong>'), 'card: HTML message preserved');
+        assert.ok(result.html.includes('Sincerely'), 'card: team signoff renders');
+        assert.ok(result.html.includes('TestCo Holdings Inc'), 'card: configured parent company renders');
+        assert.ok(result.html.includes('company-wordmark.png'), 'card: configured company wordmark renders');
+        assert.ok(result.html.includes('123 Main St'), 'card: address renders');
+      },
+    },
+
+    {
+      name: 'card template renders personal signoff with image and link',
+      async run({ assert }) {
+        const result = await render('card', {
+          signoff: {
+            type: 'personal',
+            name: 'Jane Doe',
+            image: 'https://example.com/headshot.jpg',
+            url: 'https://example.com',
+            urlText: '@janedoe',
+          },
+        });
+
+        assert.ok(result.html.includes('Jane Doe'), 'card: personal signoff name renders');
+        assert.ok(result.html.includes('Warm regards'), 'card: personal signoff greeting renders');
+        assert.ok(result.html.includes('headshot.jpg'), 'card: personal signoff image renders');
+        assert.ok(result.html.includes('@janedoe'), 'card: personal signoff link text renders');
+      },
+    },
+
+    {
+      name: 'card template renders CTA button when provided',
+      async run({ assert }) {
+        const result = await render('card', {
+          content: {
+            title: 'Test',
+            message: '<p>Click below</p>',
+            button: { url: 'https://testco.example/action', text: 'Get Started' },
+          },
+        });
+
+        assert.ok(result.html.includes('Get Started'), 'card: button text renders');
+        assert.ok(result.html.includes('testco.example/action'), 'card: button URL renders');
+      },
+    },
+
+    {
+      name: 'card template includes hidden ASM tags for SendGrid',
+      async run({ assert }) {
+        const result = await render('card');
+
+        assert.ok(
+          result.html.includes('asm_group_unsubscribe_raw_url'),
+          'card: hidden ASM unsubscribe tag present',
+        );
+        assert.ok(
+          result.html.includes('asm_preferences_raw_url'),
+          'card: hidden ASM preferences tag present',
+        );
+      },
+    },
+
+    {
+      name: 'plain template renders without card wrapper',
+      async run({ assert }) {
+        const result = await render('plain');
+
+        assert.ok(result.html.includes('TestCo'), 'plain: brand name renders');
+        assert.ok(result.html.includes('Hello <strong>world</strong>'), 'plain: message renders');
+      },
+    },
+
+    {
+      name: 'order template renders order summary when data provided',
+      async run({ assert }) {
+        const result = await render('order', {
+          content: {
+            event: 'confirmation',
+            id: 'ORD-12345',
+            type: 'subscription',
+            unified: {
+              product: { id: 'premium', name: 'Premium' },
+              payment: { price: 9.99, frequency: 'monthly' },
+            },
+            _computed: { totalToday: '9.99' },
+          },
+        });
+
+        assert.ok(result.html.includes('ORD-12345'), 'order: order ID renders');
+        assert.ok(result.html.includes('9.99'), 'order: price renders');
+      },
+    },
+
+    {
+      name: 'order template names the PRODUCT on a one-time receipt',
+      async run({ assert }) {
+        // A one-time row was labelled `Order #<id>` — the id the header already
+        // prints above it — so the receipt for a $49.99 purchase named the
+        // product nowhere at all
+        // ([#668](https://github.com/Omega-JS-Stack/omega/issues/668)).
+        const result = await render('order', {
+          content: {
+            event: 'confirmation',
+            id: 'ORD-ONETIME',
+            type: 'one-time',
+            unified: {
+              product: { id: 'launch-kit', name: 'Starter Library' },
+              payment: { price: 49.99 },
+            },
+            _computed: { totalToday: '49.99' },
+          },
+        });
+
+        assert.ok(result.html.includes('Starter Library'), 'order: a one-time receipt names what was bought');
+        assert.ok(result.html.includes('One-time purchase'), 'order: and says nothing renews, where a subscription names its cadence');
+        assert.ok(!result.html.includes('Billed'), 'order: a one-time buy is billed on no cadence');
+        assert.ok(result.html.includes('49.99'), 'order: the price still renders');
+        assert.ok(result.html.includes('ORD-ONETIME'), 'order: and the order id still rides the header');
+      },
+    },
+
+    {
+      name: 'order template renders a percent promo line',
+      async run({ assert }) {
+        const result = await render('order', {
+          content: {
+            event: 'confirmation',
+            id: 'ORD-PERCENT',
+            type: 'subscription',
+            unified: {
+              product: { id: 'premium', name: 'Premium' },
+              payment: { price: 49.99, frequency: 'monthly' },
+            },
+            _computed: { promoCode: 'WELCOME15', promoPercent: 15, promoSavings: '7.50', totalToday: '42.49' },
+          },
+        });
+
+        assert.ok(result.html.includes('WELCOME15'), 'order: the redeemed code renders');
+        assert.ok(result.html.includes('15% off'), 'order: a percent code reads as "15% off"');
+        assert.ok(result.html.includes('7.50'), 'order: the savings render');
+      },
+    },
+
+    {
+      name: 'order template renders an amount promo line as money, not a percent',
+      async run({ assert }) {
+        // A flat-dollar code has no percent to quote — the line used to render
+        // "undefined% off" for one ([#239](https://github.com/Omega-JS-Stack/omega/issues/239))
+        const result = await render('order', {
+          content: {
+            event: 'confirmation',
+            id: 'ORD-AMOUNT',
+            type: 'subscription',
+            unified: {
+              product: { id: 'premium', name: 'Premium' },
+              payment: { price: 49.99, frequency: 'monthly' },
+            },
+            _computed: { promoCode: 'WELCOME10OFF', promoAmount: '10.00', promoSavings: '10.00', totalToday: '39.99' },
+          },
+        });
+
+        assert.ok(result.html.includes('WELCOME10OFF'), 'order: the redeemed code renders');
+        assert.ok(result.html.includes('$10.00 off'), 'order: an amount code reads as "$10.00 off", formatted like every other amount');
+        assert.ok(!result.html.includes('% off'), 'order: an amount code never quotes a percentage');
+        assert.ok(!result.html.includes('undefined'), 'order: nothing renders as undefined');
+      },
+    },
+
+    {
+      name: 'feedback template renders',
+      async run({ assert }) {
+        const result = await render('feedback');
+
+        assert.ok(result.html.includes('<html'), 'feedback: produces valid HTML');
+        assert.ok(result.html.includes('TestCo'), 'feedback: brand name renders');
+      },
+    },
+
+    {
+      name: 'direct template names resolve correctly',
+      async run({ assert }) {
+        const names = { card: 'card', plain: 'plain', order: 'order', feedback: 'feedback' };
+
+        for (const [name, expected] of Object.entries(names)) {
+          const t = resolveTemplate(name);
+          assert.equal(t.meta.name, expected, `Template "${name}" should resolve`);
+        }
+      },
+    },
+
+    {
+      name: 'unknown template falls back to card',
+      async run({ assert }) {
+        const t = resolveTemplate('nonexistent-template');
+        assert.equal(t.meta.name, 'card', 'Unknown template should fall back to card');
+      },
+    },
+  ],
+});

package/test/email/testing-capture.test.js

@@ -0,0 +1,260 @@
+/**
+ * Test: the testing-mode email capture — the sink that stands in for SendGrid
+ * ([#774](https://github.com/Omega-JS-Stack/omega/issues/774)).
+ *
+ * Outside extended mode nothing proved an email was sent: every caller gated
+ * itself on `ctx.isTesting()` and returned before the mailer, so a broken welcome
+ * email or a broken order receipt failed no test — the way the signoff crash on
+ * [#640](https://github.com/Omega-JS-Stack/omega/issues/640) went unnoticed. The
+ * gate now lives in `Transactional.send()`, past `build()`: the brand, the
+ * recipients, the template data and the MJML render all run for real and what
+ * would have gone to SendGrid is recorded instead.
+ *
+ * This suite proves the sink itself — the gate, the store, the summary, the
+ * append bound — and then the seam, by sending a real email through the runner's
+ * own Manager and reading it back out of the store.
+ *
+ * Plain-node (no emulator, no network): the store is a file and the capture path
+ * touches no Firestore, which is the whole reason a file was chosen over a
+ * test-only collection (see the module header on src/test/utils/email-capture.js).
+ *
+ * The extended lane is asserted through the GATE only, never through a send: an
+ * extended send delivers real mail, and no test may do that.
+ *
+ * Run: npx omega test framework:email/testing-capture
+ */
+const assert = require('node:assert');
+const os = require('os');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const capture = require('../../dist/test/utils/email-capture.js');
+const { TEMP_DIR_NAME } = require('../../dist/test/utils/test-mode-file.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// A stand-in project root for the store tests, so they never disturb the real
+// project's `.temp/` (which the mailer case below uses for real).
+const SCRATCH_DIR = path.join(os.tmpdir(), '_test-omega-email-capture');
+const scratchManager = () => ({ cwd: path.join(SCRATCH_DIR, 'dist') });
+
+/** A testing ctx, and its extended twin */
+const testingCtx = { isTesting: () => true };
+const productionCtx = { isTesting: () => false };
+
+module.exports = defineCases({
+  description: 'Testing-mode email capture: the sink that stands in for SendGrid (#774)',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'testing-mode captures, extended mode and production do not',
+
+      run() {
+        const wasExtended = process.env.TEST_EXTENDED_MODE;
+        delete process.env.TEST_EXTENDED_MODE;
+
+        try {
+          assert.equal(capture.isCapturing(testingCtx), true, 'a testing send is captured');
+          assert.equal(capture.isCapturing(productionCtx), false, 'a production send is delivered');
+
+          // The lane that deliberately sends real mail is untouched by #774.
+          process.env.TEST_EXTENDED_MODE = 'true';
+          assert.equal(capture.isCapturing(testingCtx), false, 'extended mode still delivers');
+
+          // Read per call, never cached: the test command flips this on a RUNNING
+          // emulator through .temp/test-mode.json.
+          delete process.env.TEST_EXTENDED_MODE;
+          assert.equal(capture.isCapturing(testingCtx), true, 'and flips back within the same process');
+
+          // The one direction a fallback must never take: a ctx that cannot answer
+          // would read as "not testing", which hands a test's email to SendGrid.
+          assert.throws(() => capture.isCapturing({}), /no isTesting/, 'a ctx that cannot answer fails loudly');
+          assert.throws(() => capture.isCapturing(null), /no isTesting/, 'and so does no ctx at all');
+        } finally {
+          if (wasExtended === undefined) {
+            delete process.env.TEST_EXTENDED_MODE;
+          } else {
+            process.env.TEST_EXTENDED_MODE = wasExtended;
+          }
+        }
+      },
+    },
+
+    {
+      name: 'the store sits beside the test-mode file, one project up from the staged tree',
+
+      run() {
+        const Manager = scratchManager();
+
+        // The emulator's workers and the test runner are different processes with
+        // different staged trees; the parent of each is the same project root,
+        // which is exactly how the test-mode watcher finds the file it shares.
+        assert.equal(capture.resolveProjectDir(Manager), SCRATCH_DIR, 'the project root is the parent of Manager.cwd');
+        assert.equal(
+          capture.getCaptureFilePath(SCRATCH_DIR),
+          path.join(SCRATCH_DIR, TEMP_DIR_NAME, capture.CAPTURE_FILENAME),
+          'and the store lives in the same .temp/ as test-mode.json',
+        );
+
+        assert.throws(
+          () => capture.resolveProjectDir({}),
+          /Manager\.cwd is unset/,
+          'a Manager that never booted fails loudly rather than writing to some other directory',
+        );
+      },
+    },
+
+    {
+      name: 'records round-trip through the store, in send order, and clear empties it',
+
+      run() {
+        const Manager = scratchManager();
+
+        capture.clearCaptured(Manager);
+        assert.deepEqual(capture.readCaptured(Manager), [], 'a missing store reads as no emails, never as an error');
+
+        capture.recordCaptured(Manager, {
+          to: [{ email: 'first@test.dev', name: 'First' }],
+          template: 'card',
+          subject: 'Welcome aboard',
+          html: '<p>Hello <strong>First</strong></p>',
+        });
+        capture.recordCaptured(Manager, {
+          to: [{ email: 'second@test.dev' }, { email: 'cc@test.dev' }],
+          template: 'order',
+          subject: 'Your order',
+          html: '<p>Receipt</p>',
+          sendAt: 1900000000,
+        });
+
+        const records = capture.readCaptured(Manager);
+
+        assert.equal(records.length, 2, 'both sends are recorded');
+        assert.deepEqual(records[0].to, ['first@test.dev'], 'the record names the recipient by address');
+        assert.equal(records[0].template, 'card');
+        assert.equal(records[0].subject, 'Welcome aboard');
+        assert.equal(records[0].summary, 'Hello First', 'and carries the rendered text');
+        assert.equal(records[0].sendAt, null, 'an immediate send is scheduled for nothing');
+        assert.deepEqual(records[1].to, ['second@test.dev', 'cc@test.dev'], 'every recipient of a send lands in one record');
+        assert.equal(records[1].sendAt, 1900000000, 'a scheduled send records the second it is due');
+
+        capture.clearCaptured(Manager);
+        assert.deepEqual(capture.readCaptured(Manager), [], 'clear empties the store, so a test reads only its own act');
+      },
+    },
+
+    {
+      name: 'a rendered body reduces to the visible text a test asserts against',
+
+      run() {
+        const html = `
+          <style>.x { color: red; }</style>
+          <!-- a comment -->
+          <h2>Order&nbsp;confirmed</h2>
+          <p><strong>Sandbox Brand&amp;Co Premium</strong><br/><span>Billed monthly</span></p>
+          <p>&#128512; &ndash; total</p>
+        `;
+
+        assert.equal(
+          capture.summarize(html),
+          'Order confirmed Sandbox Brand&Co Premium Billed monthly 😀 – total',
+          'styles and markup drop out, entities decode, whitespace collapses',
+        );
+        assert.equal(capture.summarize(''), '', 'an empty body summarizes to nothing');
+        assert.equal(capture.summarize(undefined), '', 'and so does a missing one');
+        assert.equal(capture.summarize('x'.repeat(capture.SUMMARY_LIMIT + 500)).length, capture.SUMMARY_LIMIT, 'a long body is capped');
+      },
+    },
+
+    {
+      name: 'a record stays inside the atomic-append bound, so two processes never tear a line',
+
+      run() {
+        const Manager = scratchManager();
+
+        capture.clearCaptured(Manager);
+        capture.recordCaptured(Manager, {
+          to: [{ email: 'huge@test.dev' }],
+          template: 'card',
+          subject: 'A very long email',
+          // Every character survives summarize() as itself, so this is the worst case
+          html: 'w'.repeat(50000),
+        });
+
+        const contents = jetpack.read(capture.getCaptureFilePath(SCRATCH_DIR), 'utf8');
+        const lines = contents.split('\n').filter((line) => line.trim());
+
+        assert.equal(lines.length, 1, 'one send is one line');
+        assert.ok(
+          lines[0].length <= capture.LINE_LIMIT,
+          `a record must fit the PIPE_BUF bound the appends rely on, got ${lines[0].length}`,
+        );
+        assert.equal(capture.readCaptured(Manager).length, 1, 'and it still parses');
+
+        capture.clearCaptured(Manager);
+        jetpack.remove(SCRATCH_DIR);
+      },
+    },
+
+    {
+      name: 'a record that cannot be trimmed under the bound throws instead of tearing the store',
+
+      run() {
+        const Manager = scratchManager();
+
+        capture.clearCaptured(Manager);
+
+        // The bound lives on the ENVELOPE too: a recipient list this long fills the
+        // line on its own, so there is nothing left for the summary to give back.
+        // Appending it would tear a concurrent process's line and lose both records.
+        const bulk = Array.from({ length: 200 }, (unused, index) => ({ email: `_test-bulk-${index}@a-fairly-long-domain.example.com` }));
+
+        assert.throws(
+          () => capture.recordCaptured(Manager, { to: bulk, template: 'card', subject: 'Bulk', html: '<p>hi</p>' }),
+          /nothing left to trim/,
+          'an unrecordable send fails loudly rather than corrupting the store',
+        );
+        assert.deepEqual(capture.readCaptured(Manager), [], 'and nothing was written');
+
+        jetpack.remove(SCRATCH_DIR);
+      },
+    },
+
+    {
+      name: 'the mailer records instead of sending, past a real render',
+
+      async run({ Manager, ctx }) {
+        // The REAL mailer, the REAL brand, the REAL MJML render — only the delivery
+        // is replaced. A template that throws (the #640 signoff crash) fails here.
+        capture.clearCaptured(Manager);
+
+        const result = await Manager.Email(ctx).send({
+          sender: 'account',
+          to: '_test.capture-seam@test.dev',
+          subject: 'The seam records this one',
+          template: 'card',
+          categories: ['account/checkup'],
+          copy: false,
+          data: {
+            content: {
+              title: 'Captured',
+              message: 'This email was never handed to SendGrid.',
+            },
+          },
+        });
+
+        assert.equal(result.status, 'captured', 'a testing send reports what happened to it');
+        assert.ok(result.options.content[0].value.includes('<html'), 'and it went through the full render on the way');
+
+        const records = capture.readCaptured(Manager);
+
+        assert.equal(records.length, 1, `exactly one email was recorded, got ${records.length}`);
+        assert.deepEqual(records[0].to, ['_test.capture-seam@test.dev']);
+        assert.equal(records[0].template, 'card');
+        assert.equal(records[0].subject, 'The seam records this one');
+        assert.match(records[0].summary, /This email was never handed to SendGrid\./, 'the summary carries the rendered body text');
+
+        capture.clearCaptured(Manager);
+      },
+    },
+  ],
+});

package/test/email/transactional-send.test.js

@@ -0,0 +1,36 @@
+/**
+ * Test: Single transactional email send
+ * Verifies the full pipeline end-to-end: prepare → render → deliver via SendGrid.
+ */
+
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Transactional email send',
+  auth: 'admin',
+  skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE not set' : false,
+  timeout: 30000,
+
+  async run({ http, assert, config }) {
+    const response = await http.post('backend-manager/admin/email', {
+      subject: '[TEST] Transactional pipeline — card template',
+      to: `_test-email-send@${config.domain}`,
+      template: 'card',
+      sender: 'hello',
+      copy: false,
+      data: {
+        content: {
+          title: 'Pipeline Test',
+          message: '# It works\n\nMarkdown → HTML → MJML → email.\n\n- **Bold** and *italic*\n- `Code` inline\n- A [link](https://example.com)',
+        },
+        signoff: { type: 'personal' },
+      },
+    });
+
+    assert.isSuccess(response, 'Should send successfully');
+    assert.equal(response.data.status, 'sent', 'Status should be sent');
+    assert.ok(response.data.options.content?.[0]?.value?.includes('<html'), 'Should have rendered HTML');
+    assert.ok(response.data.options.content[0].value.includes('It works'), 'Markdown should be rendered');
+    assert.ok(response.data.options.asm, 'Should have ASM group');
+    assert.ok(response.data.options.headers['List-Unsubscribe'], 'Should have unsubscribe header');
+  },
+});