@omega.js/manager 0.1.0

package/dist/services/payment/ensure/stripe-products.js

@@ -0,0 +1,245 @@
+/**
+ * Ensure Stripe products and prices exist for all paid products.
+ *
+ * Product resolution: config productId → state (stripeProducts map) →
+ * metadata match against the account's products (self-heal when state is
+ * lost — every product we create carries { brandId, productId } metadata) →
+ * create. Created/matched IDs are written back into omega.json5
+ * (payment.products[id=…].stripe.productId — comment-preserving) and
+ * mirrored in state. Prices are managed by interval + amount — matching
+ * active prices are kept, stale ones archived (Stripe can't delete prices),
+ * missing ones created. omega-manager's version had no dry-run guard and no
+ * archived-product skip here; both are standard now.
+ */
+const chalk = require('chalk').default;
+const { paidProducts, productDisplayName, productImage } = require('../lib/payment-utils.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+
+// Map config interval names to Stripe price intervals
+const FREQUENCY_TO_INTERVAL = {
+  annually: 'year',
+  monthly: 'month',
+  weekly: 'week',
+  daily: 'day',
+};
+
+/**
+ * Build desired product details from brand/product config.
+ * Images are only managed when brand.images.brandmark is configured.
+ */
+function buildProductDetails(brandConfig, brandId, product) {
+  return {
+    name: productDisplayName(brandConfig, product),
+    description: product.description || brandConfig.brand.description || '',
+    images: productImage(brandConfig) ? [productImage(brandConfig)] : null,
+    url: brandConfig.brand.url,
+    metadata: { brandId, productId: product.id },
+  };
+}
+
+/**
+ * Diff a Stripe product against desired and return the update payload
+ */
+function getProductUpdates(stripeProduct, desired) {
+  const updates = {};
+
+  if (stripeProduct.name !== desired.name) {
+    updates.name = desired.name;
+  }
+  if ((stripeProduct.description || '') !== desired.description) {
+    updates.description = desired.description;
+  }
+  if (stripeProduct.url !== desired.url) {
+    updates.url = desired.url;
+  }
+
+  if (desired.images && JSON.stringify(stripeProduct.images || []) !== JSON.stringify(desired.images)) {
+    updates.images = desired.images;
+  }
+
+  // Metadata — ensure all desired keys exist with correct values
+  const currentMeta = stripeProduct.metadata || {};
+  const metadataUpdates = {};
+  for (const [key, value] of Object.entries(desired.metadata)) {
+    if (currentMeta[key] !== value) {
+      metadataUpdates[key] = value;
+    }
+  }
+  if (Object.keys(metadataUpdates).length > 0) {
+    updates.metadata = { ...currentMeta, ...metadataUpdates };
+  }
+
+  return Object.keys(updates).length > 0 ? updates : null;
+}
+
+/**
+ * Ensure active prices on a Stripe product match config amounts.
+ * Creates missing prices, archives actives at the wrong amount.
+ */
+async function ensurePrices(api, stripeProductId, product, dryRun) {
+  const activePrices = await api.listPricesForProduct(stripeProductId);
+
+  if (product.type === 'subscription') {
+    for (const interval of Object.keys(product.prices)) {
+      const expectedAmount = product.prices[interval];
+
+      if (!expectedAmount) {
+        continue;
+      }
+
+      const expectedCents = Math.round(expectedAmount * 100);
+      const stripeInterval = FREQUENCY_TO_INTERVAL[interval] || 'month';
+
+      const match = activePrices.find((p) =>
+        p.active
+        && p.recurring?.interval === stripeInterval
+        && p.unit_amount === expectedCents
+      );
+
+      if (match) {
+        console.log(`        ${chalk.green('✓')} ${interval}: $${expectedAmount} ${chalk.dim(match.id)}`);
+        continue;
+      }
+
+      // Archive active prices at the wrong amount for this interval
+      const stale = activePrices.filter((p) =>
+        p.active
+        && p.recurring?.interval === stripeInterval
+      );
+
+      for (const old of stale) {
+        if (dryRun) {
+          console.log(`        ${chalk.yellow('↓')} ${interval}: would archive $${old.unit_amount / 100} ${chalk.dim(old.id)} ${chalk.yellow('[DRY RUN]')}`);
+        } else {
+          await api.archivePrice(old.id);
+          console.log(`        ${chalk.yellow('↓')} ${interval}: archived $${old.unit_amount / 100} ${chalk.dim(old.id)}`);
+        }
+      }
+
+      if (dryRun) {
+        console.log(`        ${chalk.cyan('+')} ${interval}: would create $${expectedAmount} ${chalk.yellow('[DRY RUN]')}`);
+      } else {
+        const newPrice = await api.createRecurringPrice(stripeProductId, expectedAmount, interval);
+        console.log(`        ${chalk.green('✓')} ${interval}: created $${expectedAmount} ${chalk.cyan(newPrice.id)}`);
+      }
+    }
+  }
+
+  if (product.type === 'one-time') {
+    const expectedAmount = product.prices.once;
+
+    if (expectedAmount) {
+      const expectedCents = Math.round(expectedAmount * 100);
+      const match = activePrices.find((p) => p.active && !p.recurring && p.unit_amount === expectedCents);
+
+      if (match) {
+        console.log(`        ${chalk.green('✓')} once: $${expectedAmount} ${chalk.dim(match.id)}`);
+      } else {
+        const stale = activePrices.filter((p) => p.active && !p.recurring);
+        for (const old of stale) {
+          if (dryRun) {
+            console.log(`        ${chalk.yellow('↓')} once: would archive $${old.unit_amount / 100} ${chalk.dim(old.id)} ${chalk.yellow('[DRY RUN]')}`);
+          } else {
+            await api.archivePrice(old.id);
+            console.log(`        ${chalk.yellow('↓')} once: archived $${old.unit_amount / 100} ${chalk.dim(old.id)}`);
+          }
+        }
+
+        if (dryRun) {
+          console.log(`        ${chalk.cyan('+')} once: would create $${expectedAmount} ${chalk.yellow('[DRY RUN]')}`);
+        } else {
+          const newPrice = await api.createOneTimePrice(stripeProductId, expectedAmount);
+          console.log(`        ${chalk.green('✓')} once: created $${expectedAmount} ${chalk.cyan(newPrice.id)}`);
+        }
+      }
+    }
+  }
+}
+
+module.exports = async function ensureStripeProducts(context) {
+  const { brandConfig, brandId, stripeApi: api, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  if (!api) {
+    console.log(`      ${chalk.dim('⊘ Stripe not configured')}`);
+    return {};
+  }
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} No changes will be made`);
+  }
+
+  const products = paidProducts(brandConfig);
+  const configEdits = {};
+  let catalog = null; // Lazy-listed only when a product has no configured ID
+
+  for (const product of products) {
+    console.log(`      ${chalk.bold(product.name)} (${product.id}):`);
+
+    const desired = buildProductDetails(brandConfig, brandId, product);
+
+    // --- Resolve the Stripe product: config → metadata match → create ---
+    const stripeId = product.stripe?.productId || null;
+    let stripeProduct = null;
+
+    if (stripeId) {
+      stripeProduct = await api.getProduct(stripeId);
+    } else {
+      // Self-heal: our products carry { brandId, productId } metadata
+      catalog = catalog || await api.listAllProducts();
+      stripeProduct = catalog.find((p) =>
+        p.active !== false
+        && p.metadata?.brandId === brandId
+        && p.metadata?.productId === product.id
+      ) || null;
+
+      if (stripeProduct) {
+        console.log(`        ${chalk.green('✓')} Matched existing product by metadata: ${chalk.dim(stripeProduct.id)}`);
+      }
+    }
+
+    if (stripeProduct) {
+      console.log(`        ${chalk.green('✓')} Product exists: ${chalk.dim(stripeProduct.id)}`);
+
+      const updates = getProductUpdates(stripeProduct, desired);
+      if (updates) {
+        const fields = Object.keys(updates).join(', ');
+        if (dryRun) {
+          console.log(`        ${chalk.cyan('~')} Would update: ${chalk.dim(fields)} ${chalk.yellow('[DRY RUN]')}`);
+        } else {
+          await api.updateProduct(stripeProduct.id, updates);
+          console.log(`        ${chalk.green('✓')} Updated: ${chalk.dim(fields)}`);
+        }
+      }
+    } else {
+      if (dryRun) {
+        console.log(`        ${chalk.cyan('+')} Would create product: ${chalk.dim(desired.name)} ${chalk.yellow('[DRY RUN]')}`);
+        // Can't manage prices without a real product ID
+        continue;
+      }
+
+      stripeProduct = await api.createProduct({
+        name: desired.name,
+        brandId,
+        productId: product.id,
+        description: desired.description,
+        images: desired.images || undefined,
+        url: desired.url,
+      });
+      console.log(`        ${chalk.green('✓')} Created product: ${chalk.cyan(stripeProduct.id)}`);
+    }
+
+    if (stripeProduct.id !== product.stripe?.productId) {
+      configEdits[`payment.products[id=${product.id}].stripe.productId`] = stripeProduct.id;
+    }
+
+    // --- Ensure prices match config amounts ---
+    await ensurePrices(api, stripeProduct.id, product, dryRun);
+  }
+
+  if (Object.keys(configEdits).length > 0) {
+    writeBrandConfig(context, configEdits);
+  }
+
+  return { output: { stripeSync: { productsProcessed: products.length } } };
+};

package/dist/services/payment/ensure/stripe-radar.js

@@ -0,0 +1,74 @@
+/**
+ * Report the desired Stripe Radar rules.
+ *
+ * Stripe has no Radar rules API (Dashboard-only), so this follows the
+ * no-API manual-action pattern (the search service's ga-link): print the desired
+ * rules + the Dashboard deep-link, confirm interactively, and stay warned
+ * until confirmed. A confirmation nothing can re-check is the one kind of
+ * reconcile flag config keeps (#434): it lands at
+ * `payment.providers.stripe.radarConfirmed`. Rules come from
+ * payment.providers.stripe.radar — manager defaults with per-brand
+ * override. Cannot mutate by construction.
+ */
+const chalk = require('chalk').default;
+const { confirm, pressEnterToOpen } = require('../../../vendor/devkit/prompt.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+
+const CONFIG_PATH = 'payment.providers.stripe.radarConfirmed';
+
+module.exports = async function ensureStripeRadar(context) {
+  const { brandConfig, stripeApi: api, serviceData, options = {} } = context;
+
+  if (!api) {
+    console.log(`      ${chalk.dim('⊘ Stripe not configured')}`);
+    return {};
+  }
+
+  const desiredRules = brandConfig.payment?.providers?.stripe?.radar || [];
+  if (desiredRules.length === 0) {
+    console.log(`      ${chalk.dim('⊘ No Radar rules configured')}`);
+    return {};
+  }
+
+  if (brandConfig.payment?.providers?.stripe?.radarConfirmed === true) {
+    console.log(`      ${chalk.green('✓')} Radar rules confirmed (${desiredRules.length} rules)`);
+    return {};
+  }
+
+  const radarUrl = serviceData.stripeAccountId
+    ? `https://dashboard.stripe.com/${serviceData.stripeAccountId}/radar/rules`
+    : 'https://dashboard.stripe.com/radar/rules';
+
+  console.log(`      ${chalk.yellow('⚠')} Stripe has no Radar rules API — add these in the Dashboard:`);
+  console.log('');
+  for (const rule of desiredRules) {
+    const actionColor = rule.action === 'block' ? chalk.red
+      : rule.action === 'review' ? chalk.yellow
+      : chalk.cyan;
+    console.log(`        ${actionColor(rule.action.padEnd(24))} ${chalk.dim(rule.predicate)}`);
+    if (rule.description) {
+      console.log(`        ${' '.repeat(24)} ${chalk.dim(`↳ ${rule.description}`)}`);
+    }
+  }
+  console.log('');
+
+  if (canPrompt(options)) {
+    await pressEnterToOpen(radarUrl, 'the Stripe Radar rules page');
+    const done = await confirm({ message: 'Radar rules added in the Dashboard?', default: false });
+    if (done) {
+      writeBrandConfig(context, { [CONFIG_PATH]: true });
+      console.log(`      ${chalk.green('✓')} Radar rules confirmed (${desiredRules.length} rules)`);
+      return {};
+    }
+  } else {
+    console.log(`      ${chalk.dim('→')} Radar rules: ${chalk.cyan(radarUrl)}`);
+    console.log(`      ${chalk.dim('→')} (rerun in an interactive terminal to confirm)`);
+  }
+
+  return {
+    status: 'warned',
+    reason: 'Radar rules not confirmed — add them in the Stripe Dashboard',
+    output: { stripeRadar: { rules: desiredRules.length, radarUrl } },
+  };
+};

package/dist/services/payment/ensure/stripe-webhook.js

@@ -0,0 +1,130 @@
+/**
+ * Ensure a Stripe webhook endpoint exists for this brand's backend.
+ *
+ * Matches by exact URL, deletes every OTHER endpoint on the brand's API host
+ * (stale twins — one endpoint per host, and endpoints on other hosts are never
+ * touched), re-enables endpoints Stripe auto-disabled after repeated failures,
+ * diffs enabled_events, updates when drifted, creates when missing. Skipped for
+ * shared Firebase projects (no api.{domain} backend to receive events).
+ * Requires OMEGA_WEBHOOK_KEY.
+ */
+const chalk = require('chalk').default;
+const { buildWebhookUrl, diffEventSets, redactWebhookUrl, staleWebhookEndpoints } = require('../lib/payment-utils.js');
+
+// Events the backend handles for subscription/payment processing
+const ENABLED_EVENTS = [
+  // Subscriptions
+  'customer.subscription.created',
+  'customer.subscription.updated',
+  'customer.subscription.deleted',
+  'customer.subscription.paused',
+  'customer.subscription.resumed',
+  'customer.subscription.trial_will_end',
+
+  // Invoices (subscription renewals + failed payments)
+  'invoice.created',
+  'invoice.paid',
+  'invoice.payment_succeeded',
+  'invoice.payment_failed',
+  'invoice.payment_action_required',
+
+  // One-time purchases (Checkout + charges)
+  'checkout.session.completed',
+  'charge.succeeded',
+  'charge.failed',
+  'charge.refunded',
+
+  // Payment intents (covers both subscription and one-time)
+  'payment_intent.succeeded',
+  'payment_intent.payment_failed',
+];
+
+module.exports = async function ensureStripeWebhook(context) {
+  const { brandConfig, stripeApi: api, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  if (!api) {
+    console.log(`      ${chalk.dim('⊘ Stripe not configured')}`);
+    return {};
+  }
+
+  // Shared Firebase project — no backend deploys from this brand, so api.{domain} doesn't exist
+  if (brandConfig.cloud?.shared === true) {
+    console.log(`      ${chalk.dim('⊘ Shared Firebase project — no brand API for webhooks')}`);
+    return {};
+  }
+
+  if (!process.env.OMEGA_WEBHOOK_KEY) {
+    // Unreachable by design (#635): the key is OMEGA's own (`generated:` in
+    // the env schema) and the payment service's setup mints it through the
+    // shared contract before any operation runs. Absent here = broken wiring.
+    throw new Error('OMEGA_WEBHOOK_KEY absent after the payment setup ran — its REQUIRES entry or its requestServiceInput call is missing');
+  }
+
+  const desiredUrl = buildWebhookUrl(brandConfig, 'stripe');
+
+  const { data: webhooks = [] } = await api.listWebhookEndpoints();
+
+  // Exactly ONE endpoint on the brand's API host: the desired URL. Legacy twins
+  // there receive every event and answer 400 forever (#570).
+  for (const stale of staleWebhookEndpoints(webhooks, desiredUrl)) {
+    if (dryRun) {
+      console.log(`      ${chalk.cyan('-')} Would delete stale webhook ${chalk.dim(redactWebhookUrl(stale.url))} ${chalk.yellow('[DRY RUN]')}`);
+      continue;
+    }
+
+    await api.deleteWebhookEndpoint(stale.id);
+    console.log(`      ${chalk.yellow('⚠')} Deleted stale webhook ${chalk.dim(`(${stale.id})`)} ${redactWebhookUrl(stale.url)}`);
+  }
+
+  const existing = webhooks.find((wh) => wh.url === desiredUrl);
+
+  if (existing) {
+    // Re-enable if disabled (Stripe auto-disables after too many failures)
+    if (existing.status === 'disabled') {
+      if (dryRun) {
+        console.log(`      ${chalk.cyan('~')} Would re-enable disabled webhook ${chalk.yellow('[DRY RUN]')}`);
+      } else {
+        console.log(`      ${chalk.yellow('⚠')} Webhook is disabled — re-enabling...`);
+        await api.updateWebhookEndpoint(existing.id, { disabled: false });
+        console.log(`      ${chalk.green('✓')} Webhook re-enabled`);
+      }
+    }
+
+    const diff = diffEventSets(existing.enabled_events || [], ENABLED_EVENTS);
+
+    if (!diff) {
+      console.log(`      ${chalk.green('✓')} Webhook up to date ${chalk.dim(`(${existing.id})`)}`);
+      return { output: { stripeWebhook: { id: existing.id, updated: false } } };
+    }
+
+    if (diff.missing.length > 0) {
+      console.log(`      Adding events: ${chalk.cyan(diff.missing.join(', '))}`);
+    }
+    if (diff.extra.length > 0) {
+      console.log(`      Removing events: ${chalk.dim(diff.extra.join(', '))}`);
+    }
+
+    if (dryRun) {
+      console.log(`      ${chalk.cyan('~')} Would update webhook events ${chalk.yellow('[DRY RUN]')}`);
+      return { output: { stripeWebhook: { id: existing.id, planned: 'update' } } };
+    }
+
+    await api.updateWebhookEndpoint(existing.id, { enabled_events: ENABLED_EVENTS });
+    console.log(`      ${chalk.green('✓')} Webhook events updated ${chalk.dim(`(${existing.id})`)}`);
+
+    return { output: { stripeWebhook: { id: existing.id, updated: true } } };
+  }
+
+  if (dryRun) {
+    console.log(`      ${chalk.cyan('+')} Would create webhook ${chalk.yellow('[DRY RUN]')}`);
+    console.log(`      ${chalk.dim(redactWebhookUrl(desiredUrl))}`);
+    return { output: { stripeWebhook: { planned: 'create' } } };
+  }
+
+  const webhook = await api.createWebhookEndpoint(desiredUrl, ENABLED_EVENTS);
+  console.log(`      ${chalk.green('✓')} Webhook created: ${chalk.dim(webhook.id)}`);
+  console.log(`      ${chalk.dim(redactWebhookUrl(desiredUrl))}`);
+
+  return { output: { stripeWebhook: { id: webhook.id, created: true } } };
+};

package/dist/services/payment/index.js

@@ -0,0 +1,163 @@
+/**
+ * Payment service — reconciles the brand's payment providers to
+ * payment.products: Stripe (account settings, products + prices, webhook,
+ * plus manual-guidance Radar/dispute checks), PayPal (catalog products +
+ * billing plans, webhook), and Chargebee (item family → items → item prices,
+ * webhook). Product IDs are written back to omega.json5
+ * (payment.products[id=…] — comment-preserving) and mirrored in state.
+ *
+ * Coinbase Commerce (crypto, #642) reconciles NOTHING — no catalog, no webhook
+ * API — so it has no operations and no client; its whole surface here is the
+ * credential ask, gated on payment.providers.coinbase.enabled.
+ *
+ * Auth is per provider, from config + the brand .env:
+ *   - Stripe:    STRIPE_SECRET_KEY
+ *   - PayPal:    payment.providers.paypal.clientId + PAYPAL_CLIENT_SECRET
+ *   - Chargebee: payment.providers.chargebee.site + CHARGEBEE_API_KEY
+ *   - Coinbase:  COINBASE_COMMERCE_API_KEY (no public half at all)
+ * When an enabled provider's credentials are missing, interactive runs
+ * offer the setup flow (lib/provider-setup.js — dashboard browser open,
+ * public keys land in omega.json5, secrets in the brand .env); otherwise
+ * the provider is skipped per-operation with a dim note. The service only
+ * skips when NO provider is configured. The webhook operations additionally
+ * need OMEGA_WEBHOOK_KEY, which the setup MINTS through the shared contract
+ * (it is OMEGA's own key, #635) rather than asking anyone for.
+ *
+ * --provider=stripe|paypal|chargebee|coinbase narrows the run to one provider's
+ * operations (omega-manager's flag, unchanged).
+ */
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { StripeAPI } = require('./lib/stripe-api.js');
+const { PayPalAPI } = require('./lib/paypal-api.js');
+const { ChargebeeAPI } = require('./lib/chargebee-api.js');
+const { paidProducts } = require('./lib/payment-utils.js');
+const { providerSetupFlow } = require('./lib/provider-setup.js');
+
+const PROVIDERS = ['paypal', 'stripe', 'chargebee', 'coinbase'];
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const payment = context.brandConfig.payment || {};
+
+    if (payment.enabled === false) {
+      return { skip: true, reason: 'payment.enabled = false' };
+    }
+
+    const url = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+    if (!url) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    if (paidProducts(context.brandConfig).length === 0) {
+      return { skip: true, reason: 'no paid products in payment.products' };
+    }
+
+    const providerFilter = context.options?.provider || null;
+    if (providerFilter && !PROVIDERS.includes(providerFilter)) {
+      return { skip: true, reason: `unknown --provider "${providerFilter}" (paypal | stripe | chargebee | coinbase)` };
+    }
+    const wanted = (name) => !providerFilter || providerFilter === name;
+
+    // Resolve each provider; when an enabled one is missing credentials,
+    // interactive runs offer the setup flow (which lands them in
+    // omega.json5 + the brand .env + process.env) before giving up.
+    // Unconfigured ones stay null and their operations print a dim note.
+    // Tests inject fake clients via context.stripeApi / paypalApi /
+    // chargebeeApi (injected clients never trigger the flow).
+    const providers = () => context.brandConfig.payment.providers || {};
+
+    let stripeApi = null;
+    if (wanted('stripe') && providers().stripe !== false) {
+      if (!context.stripeApi && (!process.env.STRIPE_SECRET_KEY || !providers().stripe?.publishableKey)) {
+        await providerSetupFlow(context, 'stripe');
+      }
+      if (providers().stripe !== false) {
+        stripeApi = context.stripeApi
+          || (process.env.STRIPE_SECRET_KEY ? new StripeAPI(process.env.STRIPE_SECRET_KEY) : null);
+      }
+    }
+
+    let paypalApi = null;
+    if (wanted('paypal') && providers().paypal !== false) {
+      if (!context.paypalApi && (!providers().paypal?.clientId || !process.env.PAYPAL_CLIENT_SECRET)) {
+        await providerSetupFlow(context, 'paypal');
+      }
+      const clientId = providers().paypal !== false ? providers().paypal?.clientId : null;
+      paypalApi = context.paypalApi
+        || (clientId && process.env.PAYPAL_CLIENT_SECRET ? new PayPalAPI(clientId, process.env.PAYPAL_CLIENT_SECRET) : null);
+    }
+
+    let chargebeeApi = null;
+    if (wanted('chargebee') && providers().chargebee !== false) {
+      if (!context.chargebeeApi && (!providers().chargebee?.site || !process.env.CHARGEBEE_API_KEY)) {
+        await providerSetupFlow(context, 'chargebee');
+      }
+      const site = providers().chargebee !== false ? providers().chargebee?.site : null;
+      chargebeeApi = context.chargebeeApi
+        || (site && process.env.CHARGEBEE_API_KEY ? new ChargebeeAPI(site, process.env.CHARGEBEE_API_KEY) : null);
+    }
+
+    // Coinbase Commerce (crypto, [#642](https://github.com/Omega-JS-Stack/omega/issues/642))
+    // has NO operations and therefore no API client: a charge is created ad hoc
+    // at checkout, there is no product catalog to reconcile, and the webhook
+    // endpoint is set by hand in its dashboard (the API manages none). Its whole
+    // manage-time surface is the CREDENTIAL, so the shared setup contract asks
+    // for it right here (#608) and nothing below reads it.
+    //
+    // Gated on the provider being switched ON, because `enabled` IS the whole
+    // switch for this one (there is no public datum to gate on — the API key is
+    // the entire credential): a brand that never turned crypto on is never asked
+    // for a key it has no use for.
+    if (wanted('coinbase') && providers().coinbase?.enabled === true && !process.env.COINBASE_COMMERCE_API_KEY) {
+      await providerSetupFlow(context, 'coinbase');
+    }
+
+    if (!stripeApi && !paypalApi && !chargebeeApi) {
+      return {
+        skip: true,
+        reason: providerFilter === 'coinbase'
+          // Asked for above and that is all there is: crypto reconciles nothing
+          ? 'coinbase has nothing to reconcile — Coinbase Commerce has no product catalog and no webhook API; its key is the whole surface'
+          : providerFilter
+            ? `provider "${providerFilter}" not configured`
+            : 'no payment provider configured (STRIPE_SECRET_KEY, paypal.clientId + PAYPAL_CLIENT_SECRET, or chargebee.site + CHARGEBEE_API_KEY)',
+      };
+    }
+
+    // The webhook key is OMEGA's OWN (#635): the shared helper mints it in
+    // place when this service runs before the workspace one did, so every
+    // webhook operation below can read it unconditionally.
+    const gate = await requestServiceInput(context, serviceInputSpec('payment', { names: ['OMEGA_WEBHOOK_KEY'] }));
+    if (gate) return gate;
+
+    // Stripe account ID → state (dashboard deep-links for the radar/disputes
+    // guidance; omega-manager's bookmark service reads it too). Non-fatal.
+    let serviceData;
+    if (stripeApi) {
+      try {
+        const account = await stripeApi.getAccount();
+        serviceData = { stripeAccountId: account.id };
+      } catch {
+        // Deep-links fall back to the account-less dashboard URLs
+      }
+    }
+
+    // Narrow operations to the filtered provider (operation names are prefixed)
+    let operations;
+    if (providerFilter) {
+      operations = context.operations.filter((op) => op.name.startsWith(providerFilter));
+    }
+
+    return {
+      stripeApi,
+      paypalApi,
+      chargebeeApi,
+      domain: url,
+      serviceData,
+      operations,
+    };
+  },
+});