@omega.js/backend 0.1.0

package/test/routes/verts/crud.test.js

@@ -0,0 +1,194 @@
+/**
+ * Test: /omega/verts admin CRUD — create/read/update/delete + auth gating
+ *
+ * Run: npx omega test backend:routes/verts/crud
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Verts admin CRUD',
+  type: 'suite',
+  tests: [
+    {
+      name: 'create-requires-auth',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('none').post('omega/verts', { title: 'Nope', link: 'https://x.example' });
+
+        assert.isError(response, 401, 'Unauthenticated create should 401');
+      },
+    },
+
+    {
+      name: 'create-requires-admin',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('basic').post('omega/verts', { title: 'Nope', link: 'https://x.example' });
+
+        assert.isError(response, 403, 'Non-admin create should 403');
+      },
+    },
+
+    {
+      name: 'admin-creates-vert-with-defaults',
+      timeout: 15000,
+      async run({ http, assert, firestore, state }) {
+        const response = await http.as('admin').post('omega/verts', {
+          title: 'CRUD Test Vert',
+          description: 'A test vert.',
+          button: 'Go',
+          link: 'https://crud-shop.example/item',
+          footer: 'Sponsored',
+          targeting: { categories: ['testing'] },
+        });
+
+        assert.isSuccess(response, 'Create should succeed');
+        assert.hasProperty(response, 'data.vert.id', 'Response should contain the vert id');
+
+        state.vertId = response.data.vert.id;
+
+        const doc = await firestore.get(`verts/${state.vertId}`);
+
+        assert.ok(doc, 'Vert doc should exist in Firestore');
+        assert.equal(doc.title, 'CRUD Test Vert', 'Title should persist');
+        assert.equal(doc.enabled, true, 'enabled should default to true');
+        assert.equal(doc.weight, 1, 'weight should default to 1');
+        assert.deepEqual(doc.targeting, { sites: [], categories: ['testing'], keywords: [] }, 'targeting should normalize to the full shape');
+        assert.deepEqual(doc.whitelist, [], 'whitelist should default empty');
+        assert.deepEqual(doc.blacklist, [], 'blacklist should default empty');
+        assert.hasProperty(doc, 'metadata.created.timestamp', 'metadata.created should be set');
+        assert.hasProperty(doc, 'metadata.updated.timestamp', 'metadata.updated should be set');
+      },
+    },
+
+    {
+      name: 'create-rejects-missing-title',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('admin').post('omega/verts', { link: 'https://x.example' });
+
+        assert.isError(response, 400, 'Missing title should 400');
+      },
+    },
+
+    {
+      name: 'create-rejects-invalid-link',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('admin').post('omega/verts', { title: 'Bad Link', link: 'javascript:alert(1)' });
+
+        assert.isError(response, 400, 'Non-http(s) link should 400');
+      },
+    },
+
+    {
+      name: 'list-requires-admin',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('basic').get('omega/verts');
+
+        assert.isError(response, 403, 'Non-admin list should 403');
+      },
+    },
+
+    {
+      name: 'admin-lists-and-gets-verts',
+      timeout: 15000,
+      async run({ http, assert, state }) {
+        const list = await http.as('admin').get('omega/verts');
+
+        assert.isSuccess(list, 'List should succeed');
+        assert.ok(list.data.verts.some((vert) => vert.id === state.vertId), 'List should contain the created vert');
+
+        const single = await http.as('admin').get('omega/verts', { id: state.vertId });
+
+        assert.isSuccess(single, 'Get by id should succeed');
+        assert.propertyEquals(single, 'data.vert.title', 'CRUD Test Vert', 'Single get should return the vert');
+      },
+    },
+
+    {
+      name: 'get-unknown-id-returns-404',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('admin').get('omega/verts', { id: 'does-not-exist' });
+
+        assert.isError(response, 404, 'Unknown id should 404');
+      },
+    },
+
+    {
+      name: 'admin-updates-provided-fields-only',
+      timeout: 15000,
+      async run({ http, assert, firestore, state }) {
+        const response = await http.as('admin').put('omega/verts', {
+          id: state.vertId,
+          title: 'Updated Vert',
+          weight: 5,
+          enabled: false,
+        });
+
+        assert.isSuccess(response, 'Update should succeed');
+
+        const doc = await firestore.get(`verts/${state.vertId}`);
+
+        assert.equal(doc.title, 'Updated Vert', 'Title should update');
+        assert.equal(doc.weight, 5, 'Weight should update');
+        assert.equal(doc.enabled, false, 'Enabled should update');
+        assert.equal(doc.link, 'https://crud-shop.example/item', 'Untouched fields should persist');
+        assert.hasProperty(doc, 'metadata.created.timestamp', 'metadata.created should survive updates');
+      },
+    },
+
+    {
+      name: 'update-requires-admin',
+      timeout: 15000,
+      async run({ http, assert, state }) {
+        const response = await http.as('basic').put('omega/verts', { id: state.vertId, title: 'Hijack' });
+
+        assert.isError(response, 403, 'Non-admin update should 403');
+      },
+    },
+
+    {
+      name: 'update-unknown-id-returns-404',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('admin').put('omega/verts', { id: 'does-not-exist', title: 'Ghost' });
+
+        assert.isError(response, 404, 'Unknown id should 404');
+      },
+    },
+
+    {
+      name: 'delete-requires-admin',
+      timeout: 15000,
+      async run({ http, assert, state }) {
+        const response = await http.as('basic').delete('omega/verts', { id: state.vertId });
+
+        assert.isError(response, 403, 'Non-admin delete should 403');
+      },
+    },
+
+    {
+      name: 'admin-deletes-vert',
+      timeout: 15000,
+      async run({ http, assert, firestore, state }) {
+        const response = await http.as('admin').delete('omega/verts', { id: state.vertId });
+
+        assert.isSuccess(response, 'Delete should succeed');
+        assert.equal(await firestore.exists(`verts/${state.vertId}`), false, 'Vert doc should be gone');
+      },
+    },
+
+    {
+      name: 'delete-unknown-id-returns-404',
+      timeout: 15000,
+      async run({ http, assert }) {
+        const response = await http.as('admin').delete('omega/verts', { id: 'does-not-exist' });
+
+        assert.isError(response, 404, 'Unknown id should 404');
+      },
+    },
+  ],
+});

package/test/routes/verts/redirect.test.js

@@ -0,0 +1,147 @@
+/**
+ * Test: GET /omega/verts/redirect — fail-closed click redirect
+ *
+ * Uses native fetch with redirect: 'manual' to assert the 302 Location.
+ *
+ * Run: npx omega test backend:routes/verts/redirect
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Verts redirect route (fail-closed)',
+  type: 'suite',
+  tests: [
+    {
+      name: 'redirects-to-stored-link-with-utm',
+      timeout: 30000,
+      async run({ assert, firestore, config }) {
+        await firestore.set('verts/redirect-a', {
+          id: 'redirect-a',
+          enabled: true,
+          title: 'Redirect Vert',
+          link: 'https://shop.example/product?ref=house',
+          weight: 1,
+        });
+
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect?id=redirect-a&parent=site.example&brand=site-brand`, { redirect: 'manual' });
+
+        assert.equal(response.status, 302, 'Redirect should 302');
+
+        const location = new URL(response.headers.get('location'));
+
+        assert.equal(location.origin + location.pathname, 'https://shop.example/product', 'Location should be the STORED link');
+        assert.equal(location.searchParams.get('ref'), 'house', 'Existing query params should survive');
+        assert.equal(location.searchParams.get('utm_source'), 'site-brand', 'utm_source should be the host brand id');
+        assert.equal(location.searchParams.get('utm_medium'), 'omega-vert', 'utm_medium should be omega-vert');
+        assert.equal(location.searchParams.get('utm_campaign'), 'redirect-a', 'utm_campaign should be the vert id');
+      },
+    },
+
+    {
+      name: 'no-brand-falls-back-to-the-parent-host',
+      timeout: 30000,
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect?id=redirect-a&parent=site.example`, { redirect: 'manual' });
+
+        assert.equal(response.status, 302, 'Redirect should 302');
+
+        const location = new URL(response.headers.get('location'));
+
+        assert.equal(location.searchParams.get('utm_source'), 'site.example', 'utm_source should fall back to the parent host');
+      },
+    },
+
+    {
+      name: 'no-brand-and-no-parent-omits-utm-source',
+      timeout: 30000,
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect?id=redirect-a`, { redirect: 'manual' });
+
+        assert.equal(response.status, 302, 'Redirect should 302');
+
+        const location = new URL(response.headers.get('location'));
+
+        assert.equal(location.searchParams.get('utm_source'), null, 'utm_source should be absent without a brand id or a parent');
+        assert.equal(location.searchParams.get('utm_medium'), 'omega-vert', 'utm_medium should still be omega-vert');
+      },
+    },
+
+    {
+      name: 'unknown-id-returns-404',
+      timeout: 30000,
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect?id=does-not-exist`, { redirect: 'manual' });
+
+        assert.equal(response.status, 404, 'Unknown vert id should 404');
+      },
+    },
+
+    {
+      name: 'missing-id-returns-400',
+      timeout: 30000,
+      async run({ assert, config }) {
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect`, { redirect: 'manual' });
+
+        assert.equal(response.status, 400, 'Missing id should fail schema validation with 400');
+      },
+    },
+
+    {
+      name: 'caller-supplied-url-is-ignored',
+      timeout: 30000,
+      async run({ assert, config }) {
+        // A url param must NEVER influence the destination — fail closed
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect?id=redirect-a&url=${encodeURIComponent('https://evil.example/phish')}`, { redirect: 'manual' });
+
+        assert.equal(response.status, 302, 'Redirect should 302');
+
+        const location = new URL(response.headers.get('location'));
+
+        assert.equal(location.hostname, 'shop.example', 'Location must be the stored link host, never the caller URL');
+        assert.ok(!response.headers.get('location').includes('evil.example'), 'Caller-supplied URL must be ignored');
+      },
+    },
+
+    {
+      name: 'vert-with-invalid-link-fails-closed',
+      timeout: 30000,
+      async run({ assert, firestore, config }) {
+        await firestore.set('verts/redirect-bad-link', {
+          id: 'redirect-bad-link',
+          enabled: true,
+          title: 'Bad Link',
+          link: 'javascript:alert(1)',
+          weight: 1,
+        });
+
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect?id=redirect-bad-link`, { redirect: 'manual' });
+
+        assert.equal(response.status, 404, 'A non-http(s) stored link should fail closed with 404');
+      },
+    },
+
+    {
+      name: 'disabled-vert-still-redirects-to-its-own-link',
+      timeout: 30000,
+      async run({ assert, firestore, config }) {
+        // Clicks on a just-disabled vert must still resolve — it is still only
+        // ITS stored link
+        await firestore.set('verts/redirect-disabled', {
+          id: 'redirect-disabled',
+          enabled: false,
+          title: 'Disabled Vert',
+          link: 'https://disabled-shop.example/item',
+          weight: 1,
+        });
+
+        const response = await fetch(`${config.apiUrl}/omega/verts/redirect?id=redirect-disabled`, { redirect: 'manual' });
+
+        assert.equal(response.status, 302, 'Disabled vert should still redirect (stored link only)');
+
+        const location = new URL(response.headers.get('location'));
+
+        assert.equal(location.hostname, 'disabled-shop.example', 'Location should be the disabled vert\'s stored link');
+      },
+    },
+  ],
+});

package/test/routes/verts/selection.test.js

@@ -0,0 +1,237 @@
+/**
+ * Test: Verts selection scoring (pure logic)
+ *
+ * Eligibility filters (enabled, whitelist, blacklist, never-self), contextual
+ * tag matching, vertId pin, and the weighted-random distribution shape.
+ * Pure functions — called directly per the no-mock doctrine's only exception.
+ *
+ * Run: npx omega test backend:routes/verts/selection
+ */
+const { isEligible, filterEligible, scoreVert, weightedPick, selectVert, normalizeHost, normalizeBrandId, parseTags } = require('../../../dist/manager/routes/verts/utils.js');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+function makeAd(id, overrides) {
+  return {
+    id,
+    enabled: true,
+    title: `Vert ${id}`,
+    link: `https://${id}-shop.example/products`,
+    weight: 1,
+    targeting: { sites: [], categories: [], keywords: [] },
+    whitelist: [],
+    blacklist: [],
+    ...overrides,
+  };
+}
+
+module.exports = defineCases({
+  description: 'Verts selection scoring',
+  type: 'group',
+  tests: [
+    {
+      name: 'normalize-host-handles-urls-and-hosts',
+      async run({ assert }) {
+        assert.equal(normalizeHost('https://www.Example.com/path?q=1'), 'example.com', 'URL should normalize to bare host');
+        assert.equal(normalizeHost('Example.com'), 'example.com', 'Bare host should lowercase');
+        assert.equal(normalizeHost('example.com:8080'), 'example.com', 'Port should strip');
+        assert.equal(normalizeHost(''), '', 'Empty should stay empty');
+        assert.equal(normalizeHost(null), '', 'Null should stay empty');
+      },
+    },
+
+    {
+      name: 'normalize-brand-id-keeps-only-config-slugs',
+      async run({ assert }) {
+        assert.equal(normalizeBrandId('Daily-Build'), 'daily-build', 'A real slug should lowercase through');
+        assert.equal(normalizeBrandId(' omega.js '), 'omega.js', 'Surrounding whitespace should trim');
+        assert.equal(normalizeBrandId('utm spam&x=1'), '', 'Free text should never reach an advertiser URL');
+        assert.equal(normalizeBrandId('9lives'), '', 'A slug starts with a letter');
+        assert.equal(normalizeBrandId(''), '', 'Empty should stay empty');
+        assert.equal(normalizeBrandId(null), '', 'Null should stay empty');
+      },
+    },
+
+    {
+      name: 'parse-tags-normalizes-comma-list',
+      async run({ assert }) {
+        assert.deepEqual(parseTags(' Music, audio-tools ,,DEV '), ['music', 'audio-tools', 'dev'], 'Tags should trim, lowercase, drop empties');
+        assert.deepEqual(parseTags(''), [], 'Empty string should give no tags');
+      },
+    },
+
+    {
+      name: 'disabled-verts-are-ineligible',
+      async run({ assert }) {
+        assert.equal(isEligible(makeAd('a', { enabled: false }), 'site.example'), false, 'Disabled vert should be ineligible');
+        assert.equal(isEligible(makeAd('a'), 'site.example'), true, 'Enabled vert should be eligible');
+      },
+    },
+
+    {
+      name: 'whitelist-restricts-to-listed-hosts',
+      async run({ assert }) {
+        const vert = makeAd('a', { whitelist: ['allowed.example'] });
+
+        assert.equal(isEligible(vert, 'allowed.example'), true, 'Whitelisted host should be eligible');
+        assert.equal(isEligible(vert, 'other.example'), false, 'Non-whitelisted host should be ineligible');
+        assert.equal(isEligible(vert, ''), false, 'Unknown parent should fail closed for whitelisted verts');
+      },
+    },
+
+    {
+      name: 'blacklist-excludes-listed-hosts',
+      async run({ assert }) {
+        const vert = makeAd('a', { blacklist: ['blocked.example'] });
+
+        assert.equal(isEligible(vert, 'blocked.example'), false, 'Blacklisted host should be ineligible');
+        assert.equal(isEligible(vert, 'other.example'), true, 'Other hosts should be eligible');
+      },
+    },
+
+    {
+      name: 'never-advertise-self',
+      async run({ assert }) {
+        const vert = makeAd('a', { link: 'https://www.myshop.example/promo' });
+
+        assert.equal(isEligible(vert, 'myshop.example'), false, 'Vert should never serve on its own link host');
+        assert.equal(isEligible(vert, 'other.example'), true, 'Vert should serve elsewhere');
+      },
+    },
+
+    {
+      name: 'filter-eligible-composes-all-rules',
+      async run({ assert }) {
+        const verts = [
+          makeAd('open'),
+          makeAd('disabled', { enabled: false }),
+          makeAd('blacklisted', { blacklist: ['parent.example'] }),
+          makeAd('self', { link: 'https://parent.example/promo' }),
+          makeAd('whitelisted-elsewhere', { whitelist: ['other.example'] }),
+        ];
+        const eligible = filterEligible(verts, 'parent.example');
+
+        assert.equal(eligible.length, 1, 'Only the open vert should survive');
+        assert.equal(eligible[0].id, 'open', 'The open vert should be the survivor');
+      },
+    },
+
+    {
+      name: 'tag-matching-scores-overlap',
+      async run({ assert }) {
+        const vert = makeAd('a', { targeting: { sites: [], categories: ['Music'], keywords: ['audio-tools', 'dev'] } });
+
+        assert.equal(scoreVert(vert, ['music', 'audio-tools']), 2, 'Score should count overlapping tags (case-insensitive)');
+        assert.equal(scoreVert(vert, ['cooking']), 0, 'No overlap should score 0');
+        assert.equal(scoreVert(vert, []), 0, 'No request tags should be neutral (0)');
+        assert.equal(scoreVert(makeAd('b'), ['music']), 0, 'Untargeted vert should be neutral (0)');
+      },
+    },
+
+    {
+      name: 'select-prefers-top-scorers',
+      async run({ assert }) {
+        const verts = [
+          makeAd('untargeted'),
+          makeAd('targeted', { targeting: { sites: [], categories: ['music'], keywords: ['audio'] } }),
+        ];
+
+        // The targeted vert outscores the untargeted one — always selected
+        for (let i = 0; i < 25; i++) {
+          const selected = selectVert(verts, { parentHost: 'site.example', tags: ['music', 'audio'] });
+          assert.equal(selected.id, 'targeted', 'Top scorer should always win');
+        }
+      },
+    },
+
+    {
+      name: 'no-tags-anywhere-is-pure-weighted-shuffle',
+      async run({ assert }) {
+        const verts = [makeAd('a'), makeAd('b'), makeAd('c')];
+        const seen = new Set();
+
+        for (let i = 0; i < 200; i++) {
+          seen.add(selectVert(verts, { parentHost: 'site.example', tags: [] }).id);
+        }
+
+        assert.equal(seen.size, 3, 'All verts should appear in the neutral shuffle');
+      },
+    },
+
+    {
+      name: 'adid-pin-serves-eligible-pin',
+      async run({ assert }) {
+        const verts = [makeAd('a', { weight: 100 }), makeAd('b', { weight: 1 })];
+        const selected = selectVert(verts, { parentHost: 'site.example', vertId: 'b' });
+
+        assert.equal(selected.id, 'b', 'Pinned eligible vert should be served regardless of weight');
+      },
+    },
+
+    {
+      name: 'adid-pin-ineligible-falls-through',
+      async run({ assert }) {
+        const verts = [
+          makeAd('open'),
+          makeAd('self', { link: 'https://parent.example/promo' }),
+        ];
+        const selected = selectVert(verts, { parentHost: 'parent.example', vertId: 'self' });
+
+        assert.equal(selected.id, 'open', 'Ineligible pin should fall through to normal selection');
+      },
+    },
+
+    {
+      name: 'no-eligible-verts-returns-null',
+      async run({ assert }) {
+        const verts = [makeAd('disabled', { enabled: false })];
+
+        assert.equal(selectVert(verts, { parentHost: 'site.example' }), null, 'No eligible verts should return null');
+        assert.equal(selectVert([], {}), null, 'Empty inventory should return null');
+      },
+    },
+
+    {
+      name: 'weighted-pick-is-deterministic-per-roll',
+      async run({ assert }) {
+        const verts = [makeAd('a', { weight: 1 }), makeAd('b', { weight: 3 })];
+
+        assert.equal(weightedPick(verts, () => 0.1).id, 'a', 'Roll in the first quarter should pick a');
+        assert.equal(weightedPick(verts, () => 0.5).id, 'b', 'Roll past the first quarter should pick b');
+        assert.equal(weightedPick(verts, () => 0.99).id, 'b', 'High roll should pick b');
+      },
+    },
+
+    {
+      name: 'weight-distribution-shape',
+      timeout: 15000,
+      async run({ assert }) {
+        // weight 9 vs 1 → expected 90% share over 1000 draws (±5 sd bounds)
+        const verts = [makeAd('heavy', { weight: 9 }), makeAd('light', { weight: 1 })];
+
+        let heavy = 0;
+
+        for (let i = 0; i < 1000; i++) {
+          if (selectVert(verts, { parentHost: 'site.example' }).id === 'heavy') {
+            heavy++;
+          }
+        }
+
+        assert.inRange(heavy, 850, 950, `Heavy vert should win ~90% of draws (got ${heavy}/1000)`);
+      },
+    },
+
+    {
+      name: 'invalid-weight-defaults-to-1',
+      async run({ assert }) {
+        const verts = [makeAd('a', { weight: 'banana' }), makeAd('b', { weight: -5 })];
+        const seen = new Set();
+
+        for (let i = 0; i < 100; i++) {
+          seen.add(selectVert(verts, {}).id);
+        }
+
+        assert.equal(seen.size, 2, 'Invalid weights should behave as 1 (both verts appear)');
+      },
+    },
+  ],
+});