Plaid v2 renewals: opportunity-driven init

Port v1's renewal-from-opportunity seeding to Dealops 2 by composing the new CpqImportService with a small SOQL helper, and close the lingering G2 gap so renewedSubscriptionId survives the round trip.

1. Why this exists

Plaid's v1→v2 cutover (EPIC dealops-xq9) needs renewals working end-to-end. ee8 (PR #5648) shipped the generic CPQ importer — give it an sfdcQuoteId and it materializes a v2 PricingQuote. But the actual user flow is opportunity-driven: a rep opens a renewal opportunity in Salesforce, and the system needs to discover which prior quote to import from.

v1 does this in apps/server/src/utils/penguin/renewals.ts via initializePricingFlowFromRenewalOpportunity + getOldestQuoteId. n5u ports just those two pieces, then composes them with ee8.

2. End-to-end flow

Step through the request path. The orchestrator does almost nothing on its own — its job is to compose three existing pieces with one small new SOQL lookup.

3. The four phases, mapped to files

The PR is structured as four sequenced phases per PLAN.md. Each was written test-first, each is independently shippable.

4. P0: the renewedSubscriptionId trail

This is the most subtle phase. v1 carries SBQQ__RenewedSubscription__c on every QLI; v2's ProductInput had no slot for it, so ee8 was dropping it on the floor with a renewed_subscription_id_dropped warning. Three things needed to change in lockstep.

// reconstructProductInputs.ts
for (const { qli } of rows) {
  if (qli.SBQQ__RenewedSubscription__c) {
    warnings.push({
      code: 'renewed_subscription_id_dropped',
      message: `QLI ${qli.Id} carried ...
        which v2 ProductInput cannot store today`,
    });
  }
}

// flat
return {
  ...baseProduct,
  renewedSubscriptionId:
    qli.SBQQ__RenewedSubscription__c ?? undefined,
  quotePriceFlat: numberCurrency(...),
};

// tier — per-tier!
return {
  min: ..., max: ..., value: ...,
  renewedSubscriptionId:
    t.qli.SBQQ__RenewedSubscription__c ?? undefined,
};

The three QLI shapes, three resolution rules

PlaidWriteBack: three former null hardcodes, now fed from input

// Flat QLI site (was: renewedSubscriptionId: null)
renewedSubscriptionId: product.renewedSubscriptionId ?? null,

// Per-tier QLI site — tier wins, falls back to product
renewedSubscriptionId:
  (tieredSource.kind === 'currency'
    ? tieredSource.tiers[tierIndex]?.renewedSubscriptionId
    : undefined) ??
  product.renewedSubscriptionId ??
  null,

// Segmented QLI site — single product-level value, propagates to all segments
renewedSubscriptionId: product.renewedSubscriptionId ?? null,

5. P1: findPriorContractQuote, the SOQL one-liner

A faithful 36-line port of v1's getOldestQuoteId. Same SOQL string verbatim, same LIMIT 1 ORDER BY CreatedDate ASC semantics.

const SFDC_ID_REGEX = /^[a-zA-Z0-9]{15,18}$/;

export async function findPriorContractQuote({
  sfdcOpportunityId,
  salesforceApi,
}): Promise<string | null> {
  if (!SFDC_ID_REGEX.test(sfdcOpportunityId)) {
    throw new Error('findPriorContractQuote: invalid sfdcOpportunityId shape');
  }
  const soql = `SELECT Id FROM SBQQ__Quote__c `
             + `WHERE SBQQ__Opportunity2__c='${sfdcOpportunityId}' `
             + `ORDER BY CreatedDate ASC LIMIT 1`;
  const result = await salesforceApi.query(soql);
  const records = result.valueOrDie().records;
  return (!records || records.length === 0) ? null : records[0].Id;
}

Input validation is upfront: malformed ids throw before any SF call. No prior quote returns null, not an error — the orchestrator decides what that means.

6. P2: RenewalInitService, the orchestrator

Why a Plaid-specific renewal-type set?

v2 already has a generic isOpportunityTypeRenewal in dealgroup/getAmendmentInfo.ts — but it only matches the literal string 'Renewal'. Plaid uses four variants in production CRM data. Rather than expanding the generic predicate (and risking false positives for other orgs), n5u introduces a decoupled constant:

// renewalInit/constants.ts
export const PLAID_RENEWAL_OPPORTUNITY_TYPES: readonly string[] = [
  'Auto Renewal',
  'Manual Renewal',
  'Renewal',
  'Early Renewal',
] as const;

The PLAN notes this is hardcoded for now; a future cleanup could move it into per-org spec data.

7. P3: tRPC + BullMQ wiring

Mirrors dealops2CpqImport 1:1 with one schema simplification — the caller doesn't pass a quote id, only the opportunity id. The mutation does three things before dispatch:

1. Validates SFDC id shape via Zod regex (/^[a-zA-Z0-9]{15,18}$/) with trim.
2. Gates on isPlaidOrgName(ctx.organization.name) → FORBIDDEN.
3. Eagerly fast-fails non-renewal opportunity types so the caller gets a synchronous BAD_REQUEST instead of an async BullMQ failure. (Per a code review comment — duplication with the service is intentional.)

The job handler then re-checks Plaid org membership and re-validates the opportunity exists in the org before constructing a fresh RenewalInitService per request.

8. Files changed

9. What this PR doesn't change

10. Risks & open follow-ups

Trail of references

Bead dealops-n5u · closes dealops-n5u.1 · stacked on #5648 · follow-up dealops-n5u.3 / dealops-n5u.4 · unblocks dealops-hux · EPIC dealops-xq9 (Plaid v1→v2 migration).