@omega.js/backend 0.1.0

package/dist/cli/commands/setup-tests/storage-rules-file.js

@@ -0,0 +1,32 @@
+const BaseTest = require('./base-test');
+const jetpack = require('fs-jetpack');
+const path = require('path');
+const chalk = require('chalk').default;
+
+class StorageRulesFileTest extends BaseTest {
+  getName() {
+    return 'update storage rules file';
+  }
+
+  async run() {
+    const self = this.self;
+    const exists = jetpack.exists(`${self.firebaseProjectPath}/storage.rules`);
+    return exists;
+  }
+
+  async fix() {
+    const self = this.self;
+    const name = 'storage.rules';
+    const filePath = `${self.firebaseProjectPath}/${name}`;
+    const exists = jetpack.exists(filePath);
+    let contents = jetpack.read(filePath) || '';
+
+    if (!exists) {
+      console.log(chalk.yellow(`Writing new ${name} file...`));
+      jetpack.write(filePath, jetpack.read(path.resolve(`${__dirname}/../../../../templates/${name}`)));
+      contents = jetpack.read(filePath) || '';
+    }
+  }
+}
+
+module.exports = StorageRulesFileTest;

package/dist/cli/commands/setup-tests/storage-rules-in-json.js

@@ -0,0 +1,20 @@
+const BaseTest = require('./base-test');
+const jetpack = require('fs-jetpack');
+const _ = require('lodash');
+
+class StorageRulesInJsonTest extends BaseTest {
+  getName() {
+    return 'storage rules in JSON';
+  }
+
+  async run() {
+    return this.self.firebaseJSON?.storage?.rules === 'storage.rules';
+  }
+
+  async fix() {
+    _.set(this.self.firebaseJSON, 'storage.rules', 'storage.rules');
+    jetpack.write(`${this.self.firebaseProjectPath}/firebase.json`, JSON.stringify(this.self.firebaseJSON, null, 2));
+  }
+}
+
+module.exports = StorageRulesInJsonTest;

package/dist/cli/commands/stripe.js

@@ -0,0 +1,14 @@
+const BaseCommand = require('./base-command');
+
+class StripeCommand extends BaseCommand {
+  async execute() {
+    const stripeProcess = this.startStripeWebhookForwarding();
+
+    if (stripeProcess) {
+      // Keep alive until Ctrl+C
+      await new Promise(() => {});
+    }
+  }
+}
+
+module.exports = StripeCommand;

package/dist/cli/commands/test-lanes/stripe-live.js

@@ -0,0 +1,440 @@
+/**
+ * The opt-in real-Stripe test lane
+ *
+ * Every other payment suite proves the pipeline against a fabricated event. This
+ * lane proves it against Stripe's own: real test-mode objects, real webhook
+ * deliveries, real signatures, forwarded into the local emulator by the Stripe
+ * CLI ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * It is OFF by default and stays off. It needs credentials and the network, so it
+ * can never be part of a suite anybody runs without asking for it:
+ * `npx omega test --lane=stripe-live` is the only way in, and a run that cannot
+ * satisfy the gate prints ONE line saying which condition failed and exits clean.
+ * A skipped lane is a normal outcome, not a failure.
+ *
+ * The gate, in order:
+ *   1. A Stripe secret resolves through the ONE env reader
+ *      ([../../../manager/libraries/env.js](../../../manager/libraries/env.js)).
+ *      A test lane composes its `.env` from the base plus `.env.testing`
+ *      ([#586]), so the TEST credential belongs in that overlay.
+ *   2. That secret is test-shaped (`sk_test_`) — the whole gate, and the reason
+ *      a live key can never reach this lane. It also catches everything else a
+ *      key slot might hold: a restricted key, a publishable key, a paste of the
+ *      wrong line.
+ *   3. The Stripe CLI is installed, because the forwarding and the event triggers
+ *      are its job.
+ *
+ * The FIXTURES are Stripe products and prices matching the brand's configured
+ * catalogue, because `resolvePriceId()` matches on interval + amount and nothing
+ * else — a price that is a cent off resolves to nothing. They are created
+ * idempotently and tagged (`metadata.omega_lane`), so a second run reuses the
+ * first run's objects instead of littering the account with duplicates.
+ *
+ * NOTHING here ever prints a secret. The gate's refusals name the KEY and the
+ * fix; the forwarding hands its signing secret to the child process by env.
+ */
+const path = require('path');
+const { commandOnPath } = require('../../../vendor/devkit/command-path.js');
+const { spawnOnPath } = require('../../utils/spawn-shell');
+const chalk = require('chalk').default;
+
+const { assertDeclaredLane } = require('../../../utils/test-lanes.js');
+
+const env = require('../../../manager/libraries/env.js');
+
+// The lane's name, as `--lane=` spells it and as the runner reads it off the
+// env. It is this module's own FILE NAME (the gate is resolved as
+// `test-lanes/<name>.js`), proved against the framework's declared lane list so
+// a rename that missed the manifest fails loudly here instead of leaving the
+// lane unreachable (src/utils/test-lanes.js).
+const LANE = assertDeclaredLane(path.basename(__filename, '.js'));
+
+// The env var the lane sets for the runner child. The runner's discovery skips
+// `test/stripe-live/` unless it names this lane, so the suites are unreachable by
+// any run that did not deliberately ask for them.
+const LANE_ENV = 'OMEGA_TEST_LANE';
+
+// What a Stripe TEST secret key looks like. Restricted keys (`rk_test_`) are
+// deliberately excluded: the lane creates products and prices, and a restricted
+// key would fail deep inside the fixture step instead of at the gate.
+const TEST_KEY_PREFIX = 'sk_test_';
+
+// The tag every object this lane creates carries, and the key a rerun finds it by
+const FIXTURE_TAG_KEY = 'omega_lane';
+
+// Config frequency → Stripe recurring interval, the same map resolvePriceId uses
+const FREQUENCY_TO_INTERVAL = { daily: 'day', weekly: 'week', monthly: 'month', annually: 'year' };
+
+/**
+ * Can this lane run here?
+ *
+ * A pure decision over the two facts that gate it, so the answer is testable
+ * without a Stripe account and without the CLI installed. The `reason` is the one
+ * line a skipped run prints, and it never contains a credential.
+ *
+ * @param {object} options
+ * @param {object} options.env - The env reader (injected so a suite can drive it)
+ * @param {boolean} options.hasStripeCli - Whether `stripe` is on PATH
+ * @returns {{ ok: boolean, reason: string, key?: string }} The decision; `key` only when ok
+ */
+function resolveGate({ env: reader, hasStripeCli }) {
+  let key;
+
+  try {
+    key = reader.get('STRIPE_SECRET_KEY');
+  } catch (error) {
+    // A reader fault (an undeclared key, a missing one) is surfaced as a SKIP,
+    // not a failure: a lane that cannot prove which account it would touch must
+    // not merely fail, it must not run.
+    return { ok: false, reason: error.message };
+  }
+
+  if (!key) {
+    return {
+      ok: false,
+      reason: 'no Stripe secret is configured — put the TEST key (sk_test_…) in STRIPE_SECRET_KEY in the brand\'s .env.testing overlay',
+    };
+  }
+
+  if (!key.startsWith(TEST_KEY_PREFIX)) {
+    return {
+      ok: false,
+      reason: `the resolved Stripe secret is not a test secret key (expected ${TEST_KEY_PREFIX}…) — this lane creates products, prices and subscriptions, so it runs against a TEST account or not at all`,
+    };
+  }
+
+  if (!hasStripeCli) {
+    return {
+      ok: false,
+      reason: 'the Stripe CLI is not installed — this lane forwards real webhooks with `stripe listen` and fires events with `stripe trigger` (https://stripe.com/docs/stripe-cli)',
+    };
+  }
+
+  return { ok: true, reason: 'ready', key: key };
+}
+
+/**
+ * Is the Stripe CLI on PATH?
+ *
+ * The path is REPORTED (the lane hands it down as STRIPE_CLI_PATH so a run says
+ * which CLI it found), never spawned — every spawn below names `stripe` bare and
+ * lets the host resolve it.
+ *
+ * @returns {string|null} Its path, or null when it is not installed
+ */
+function findStripeCli() {
+  return commandOnPath('stripe');
+}
+
+/**
+ * What this lane needs to exist in Stripe for a brand's catalogue
+ *
+ * `resolvePriceId()` finds a price by INTERVAL and AMOUNT among a product's active
+ * prices, so a fixture is only useful if it matches the config to the cent. This
+ * turns the config into that list — pure, so the mapping is testable without an
+ * account, and so a product the lane cannot represent is named rather than
+ * silently skipped.
+ *
+ * @param {object[]} products - `config.payment.products`
+ * @param {string} currency - `config.payment.currency`
+ * @returns {{ fixtures: object[], unsupported: object[] }} What to create, and what could not be mapped
+ */
+function planFixtures(products, currency) {
+  const fixtures = [];
+  const unsupported = [];
+
+  for (const product of products || []) {
+    if (product.id === 'basic' || product.archived) {
+      continue;
+    }
+
+    const type = product.type || 'subscription';
+    const prices = product.prices || {};
+
+    if (type === 'subscription') {
+      for (const [frequency, amount] of Object.entries(prices)) {
+        const interval = FREQUENCY_TO_INTERVAL[frequency];
+
+        if (!interval) {
+          unsupported.push({ productId: product.id, reason: `unknown frequency '${frequency}'` });
+          continue;
+        }
+
+        fixtures.push({
+          productId: product.id,
+          name: product.name || product.id,
+          stripeProductId: product.stripe?.productId || null,
+          interval: interval,
+          frequency: frequency,
+          // Stripe counts in the currency's MINOR unit, and resolvePriceId
+          // compares `unit_amount` against exactly this arithmetic
+          unitAmount: Math.round(Number(amount) * 100),
+          currency: (currency || 'USD').toLowerCase(),
+        });
+      }
+
+      continue;
+    }
+
+    if (!prices.once && prices.once !== 0) {
+      unsupported.push({ productId: product.id, reason: 'a one-time product with no `once` price' });
+      continue;
+    }
+
+    fixtures.push({
+      productId: product.id,
+      name: product.name || product.id,
+      stripeProductId: product.stripe?.productId || null,
+      interval: null,
+      frequency: 'once',
+      unitAmount: Math.round(Number(prices.once) * 100),
+      currency: (currency || 'USD').toLowerCase(),
+    });
+  }
+
+  return { fixtures, unsupported };
+}
+
+/**
+ * Does an existing Stripe price already satisfy a planned fixture?
+ *
+ * The idempotency rule, kept beside the plan that produces it and pure for the
+ * same reason: a rerun must REUSE what the first run made. The comparison is the
+ * one `resolvePriceId()` performs, so "already satisfied" and "will resolve" are
+ * the same question asked once.
+ *
+ * @param {object} fixture - One entry from planFixtures()
+ * @param {object[]} prices - The product's active Stripe prices
+ * @returns {object|null} The price that satisfies it, or null
+ */
+function findSatisfyingPrice(fixture, prices) {
+  return (prices || []).find((price) => {
+    if (price.unit_amount !== fixture.unitAmount) {
+      return false;
+    }
+
+    return fixture.interval
+      ? price.recurring?.interval === fixture.interval
+      : !price.recurring;
+  }) || null;
+}
+
+/**
+ * Create the products and prices this lane needs, reusing anything already there
+ *
+ * @param {object} options
+ * @param {object} options.stripe - An initialized Stripe SDK client
+ * @param {object[]} options.fixtures - From planFixtures()
+ * @param {function} options.log - Where progress goes
+ * @returns {Promise<object[]>} Each fixture with the ids it resolved to
+ */
+async function ensureFixtures({ stripe, fixtures, log }) {
+  const resolved = [];
+  const productCache = new Map();
+
+  for (const fixture of fixtures) {
+    let productId = fixture.stripeProductId || productCache.get(fixture.productId) || null;
+
+    if (!productId) {
+      // The tag is what makes a rerun idempotent: the lane's own products are
+      // the ones carrying it, and nothing else in the account is touched.
+      const search = await stripe.products.search({
+        query: `active:'true' AND metadata['${FIXTURE_TAG_KEY}']:'${fixture.productId}'`,
+        limit: 1,
+      });
+
+      productId = search.data[0]?.id || null;
+    }
+
+    if (!productId) {
+      const created = await stripe.products.create({
+        name: fixture.name,
+        metadata: { [FIXTURE_TAG_KEY]: fixture.productId },
+      });
+
+      productId = created.id;
+      log(`created Stripe product ${productId} for ${fixture.productId}`);
+    }
+
+    productCache.set(fixture.productId, productId);
+
+    const prices = [];
+    for await (const price of stripe.prices.list({ product: productId, active: true, limit: 100 })) {
+      prices.push(price);
+    }
+
+    let price = findSatisfyingPrice(fixture, prices);
+
+    if (!price) {
+      price = await stripe.prices.create({
+        product: productId,
+        currency: fixture.currency,
+        unit_amount: fixture.unitAmount,
+        ...(fixture.interval ? { recurring: { interval: fixture.interval } } : {}),
+        metadata: { [FIXTURE_TAG_KEY]: fixture.productId },
+      });
+
+      log(`created Stripe price ${price.id} for ${fixture.productId}/${fixture.frequency}`);
+    } else {
+      log(`reusing Stripe price ${price.id} for ${fixture.productId}/${fixture.frequency}`);
+    }
+
+    resolved.push({ ...fixture, stripeProductId: productId, priceId: price.id });
+  }
+
+  return resolved;
+}
+
+/**
+ * Start `stripe listen`, forwarding real deliveries into the local webhook route
+ *
+ * Resolves once the CLI reports itself ready, so a trigger can never fire
+ * before the tunnel exists.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey - The test secret key
+ * @param {string} options.forwardUrl - The local webhook endpoint
+ * @param {function} options.log - Where the CLI's own lines go
+ * @param {number} [options.timeoutMs] - How long to wait for readiness
+ * @returns {Promise<{ stop: function }>}
+ */
+function startForwarding({ apiKey, forwardUrl, log, timeoutMs = 30000 }) {
+  return new Promise((resolve, reject) => {
+    const child = spawnOnPath('stripe', ['listen', '--forward-to', forwardUrl, '--api-key', apiKey], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let settled = false;
+    const stop = () => { try { child.kill(); } catch (error) { /* already gone */ } };
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      stop();
+      reject(new Error(`stripe listen did not report itself ready within ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const onLine = (line) => {
+      const ready = isReadyLine(line);
+
+      if (ready && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve({ stop });
+        return;
+      }
+
+      // The ready line is the ONE line held back — it carries the CLI's own
+      // signing secret, which nothing here reads and nothing may print.
+      // Everything else is the CLI narrating deliveries, which is what a human
+      // watching this lane wants.
+      if (!ready) {
+        log(line);
+      }
+    };
+
+    const consume = (stream) => stream.on('data', (data) => {
+      data.toString().split('\n').map((l) => l.trim()).filter(Boolean).forEach(onLine);
+    });
+
+    consume(child.stdout);
+    consume(child.stderr);
+
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Whether a line of `stripe listen` output is the one announcing the tunnel is up
+ *
+ * @param {string} line - One line of CLI output
+ * @returns {boolean}
+ */
+function isReadyLine(line) {
+  return /Ready!/.test(`${line}`);
+}
+
+/**
+ * The local endpoint Stripe forwards to
+ *
+ * @param {object} options
+ * @param {number} options.hostingPort - The resolved hosting port
+ * @param {string} options.webhookKey - OMEGA_WEBHOOK_KEY, the route's shared param
+ * @returns {string}
+ */
+function forwardUrl({ hostingPort, webhookKey }) {
+  return `http://localhost:${hostingPort}/omega/payments/webhook?provider=stripe&key=${webhookKey}`;
+}
+
+/**
+ * Fire one Stripe event through the forwarder
+ *
+ * `stripe trigger` is how the events with no other route in get here — a dispute,
+ * a failed renewal invoice, a trial ending. Stripe's own fixture objects carry no
+ * `metadata.uid`, and the pipeline refuses an event it cannot attribute
+ * ([#399](https://github.com/Omega-JS-Stack/omega/issues/399)), so every trigger
+ * takes the overrides that put one on.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey - The test secret key
+ * @param {string} options.event - The event type to trigger
+ * @param {string[]} [options.overrides] - `--override`/`--add` arguments, e.g. `subscription:metadata.uid=…`
+ * @returns {Promise<void>}
+ */
+function trigger({ apiKey, event, overrides = [] }) {
+  return new Promise((resolve, reject) => {
+    const args = ['trigger', event, '--api-key', apiKey];
+
+    for (const override of overrides) {
+      args.push('--add', override);
+    }
+
+    const child = spawnOnPath('stripe', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stderr = '';
+
+    child.stderr.on('data', (data) => { stderr += data.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`stripe trigger ${event} exited ${code}: ${stderr.trim()}`));
+    });
+  });
+}
+
+/**
+ * The one line a skipped lane prints
+ *
+ * @param {string} reason - From resolveGate()
+ * @returns {string}
+ */
+function skipLine(reason) {
+  return chalk.yellow(`  ⏭  Lane --lane=${LANE} SKIPPED: ${reason}`);
+}
+
+module.exports = {
+  LANE,
+  LANE_ENV,
+  TEST_KEY_PREFIX,
+  FIXTURE_TAG_KEY,
+  FREQUENCY_TO_INTERVAL,
+  resolveGate,
+  findStripeCli,
+  planFixtures,
+  findSatisfyingPrice,
+  ensureFixtures,
+  startForwarding,
+  isReadyLine,
+  forwardUrl,
+  trigger,
+  skipLine,
+  env,
+};