Opportunities (Deal Registration)

The Opportunities module is the deal-registration system of the Matters.AI Partners Portal. A partner registers a deal (an end customer + an expected ARR + a sales stage); the portal persists it to the partners Neon database, fires a confirmation email, best-effort pushes a Lead into Salesforce, and records an audit event. From then on the deal moves through a portal status lifecycle, accrues a notes thread, and — if it goes quiet for 90 days — is automatically cancelled by a cron sweep.

Every row is scoped to the partner's Clerk organisation (clerkOrgId). Partners see and act only on their own org's deals; internal admins see all of them.

Surfaces#

Source: app/(portal)/opportunities/, app/(admin)/admin/opportunities/page.tsx.

Data model#

Two tables back this module, defined in lib/db/schema.ts. See Data Model for the full schema.

opportunities#

Indexes: portalLeadId, clerkOrgId, portalStatus, lastActivityAt.

opportunity_notes#

Registering a deal#

The form lives at /opportunities/new and submits to the registerOpportunity server action in lib/actions/opportunities.ts via React useActionState.

Form fields and Zod validation#

Every submission is parsed with OpportunitySchema.safeParse. On failure, flattened field errors are returned and rendered inline (no DB write occurs).

The final six are optional enrichment fields: they may be left blank at registration and completed later through the edit flow. The form and the edit form share a single OpportunityFields client component so the two can never drift.

Enumerated values#

companyType: "BFSI" |
  "Healthcare & Life Sciences" |
  "Manufacturing" |
  "Retail & CPG" |
  "Technology" |
  "Government & Public Sector" |
  "Energy & Utilities" |
  "Education" |
  "Other";
companySize: "1-50" | "51-200" | "201-1000" | "1001-5000" | "5000+";
dealStage: "Prospecting" | "Qualification" | "Discovery" | "POC/Pilot" | "Proposal" | "Negotiation";
region: "APAC" |
  "EMEA" |
  "Americas" |
  "Global" |
  "India" |
  "Middle East" |
  "Southeast Asia" |
  "ANZ" |
  "UK & Ireland" |
  "DACH" |
  "Benelux";

primaryUseCases and competingProducts are checkbox groups whose option lists are exported from lib/constants/partner-forms.ts (USE_CASES, COMPETING_PRODUCTS, REGIONS) so the form and validation stay in sync.

What the action does, in order#

1. Auth — requirePartnerSession() resolves the partner session (org, user, email, sfAccountId).
2. Validate — OpportunitySchema.safeParse(raw); abort with field errors on failure.
3. Insert — write the row to opportunities with a fresh portalLeadId = randomUUID(). portalStatus defaults to "registered", sfStatus to "pending", dedupStatus to "approved". lastActivityAt is set to now.
4. Email (fire-and-forget) — sendDealRegisteredEmail({ toEmail: session.email, … }). Errors are swallowed (.catch(() => undefined)) so email never blocks registration.
5. Salesforce push (best-effort) — syncOpportunityToSalesforce upserts a Lead by the external id Portal_Lead_Id__c (so a retry never creates a duplicate). The end-customer name is split into FirstName / LastName (Lead requires LastName). It maps Email, MobilePhone (the org labels this "Primary Mobile Number"; the single portal phone is the contact's primary), Company, LeadSource: "Partner Sourced", Status: "New", mt_Budget__c (ARR), mt_Use_Case_Details__c (use cases joined with ;, 255-capped), mt_Anticipated_Closure__c (close date, YYYY-MM-DD), mt_ByPass_Validation__c: true, and — when the partner has an SF account — PartnerAccountId + mt_Partner_Company_Name__c (which back-fill the read-only Partner Email/Phone/Company formula fields). The enrichment fields map to Title, Website, mt_LinkedIn_URL__c, mt_Why_Now__c, mt_Why_Matters_AI__c, mt_Why_Anything__c, NumberOfEmployees, AnnualRevenue — each omitted when blank so a later edit fills gaps without clobbering existing SF values. On success the returned id is written back as sfLeadId. On failure the catch is silent — the row stays in Neon with sfLeadId = null for ops to retry. See Salesforce sync.
6. Audit — recordActivity({ action: "opportunity.registered", … }) is recorded before the redirect (since redirect() throws to control flow).
7. Revalidate + redirect — revalidatePath("/opportunities") and /dashboard, then redirect("/opportunities").

Salesforce Lead field coverage#

The portal populates every Lead field it can source from a partner deal-registration. The Lead object has 62 fields; the rest are intentionally not written, for concrete reasons:

Phone slot: the org maps standard MobilePhone → "Primary Mobile Number" and standard Phone → "Alternate Mobile Number". The portal captures one phone (the contact's primary), so it writes MobilePhone.

Editing a registered deal#

Once a deal exists, the updateOpportunity server action (same file) lets it be completed or corrected — typically to fill the optional enrichment fields that were skipped at registration. The edit UI (OpportunityEditForm) is a collapsible form on the deal detail page that re-uses the shared OpportunityFields component, pre-filled from the current row.

Who can edit — the permission boundary#

Editing is restricted to exactly two principals:

1. the partner who registered the deal (opportunities.submittedByClerkUserId === session.clerkUserId), and
2. a Matters.AI super admin (getSuperAdminClearance().ok).

No other org member, no partner-org admin, nobody else. The boundary is enforced in two places:

• UI — the detail page computes canEdit = opp.submittedByClerkUserId === session.clerkUserId || clearance.ok server-side and only renders OpportunityEditForm when it's true.
• Action — updateOpportunity re-loads the row by portalLeadId, recomputes the same predicate, and returns a form error ("Only the partner who registered this deal (or a Matters.AI super admin) can edit it.") if it fails. The UI check is a convenience; the action is the security boundary.

What the action does, in order#

1. Auth — requirePartnerSession().
2. Resolve — parse portalLeadId (uuid) from the form; load the row (return "Deal not found." if missing).
3. Authorize — the creator-or-super-admin predicate above; deny otherwise.
4. Validate — OpportunitySchema.safeParse (the same schema as registration, so all rules incl. the enrichment fields apply).
5. Update — write every field back to the row; blank optional fields persist as null. lastActivityAt + updatedAt are bumped (resetting the inactivity clock).
6. Re-sync (best-effort) — syncOpportunityToSalesforce upserts the same SF Lead by Portal_Lead_Id__c, using the row's sfAccountId (so a super-admin edit never rebinds the deal to a different partner account). If the Lead had no sfLeadId yet and the upsert now returns one, it's written back.
7. Audit — opportunity.updated with metadata.bySuperAdmin set when a super admin edited a deal they didn't register.
8. Revalidate — the detail page and list; returns { success: true } (no redirect — the form collapses in place and the refreshed row renders above it).

Clearing vs filling: an emptied optional field is stored as null in Neon (source of truth) but is omitted from the SF upsert rather than nulled — the sync is fill-only, so it never blanks a value a Salesforce user may have set. Neon remains authoritative for the portal-owned fields.

Status model#

Three independent status columns describe a deal.

portalStatus — the partner-facing lifecycle#

Default "registered". The six real values and their UI labels (consistent across the list, admin list, detail, and email templates):

The detail-page progress timeline (OpportunityTimeline.tsx) walks the happy-path sequence registered → under_review → opportunity_active → closed_won, lighting up steps through the current status. closed_lost and cancelled are off-path terminal states (rendered via the badge, not as timeline steps). The list page's "Active Deals" carousel is populated from the three most recent opportunity_active rows.

The registered → under_review → opportunity_active → closed_* transitions are driven by internal pipeline operations (admins / Salesforce sync), not by a partner-facing button. The partner-facing write surface is the deal stage updater (below) and the cancelled transition is automated by the sweep.

dealStage — the sales stage (partner-editable)#

Distinct from portalStatus. One of Prospecting | Qualification | Proposal | Negotiation. Partners change it from the deal detail page; see "Updating the deal stage".

sfStatus — Salesforce sync state#

Default "pending". Reflects the mirror state in Salesforce. The admin list shows a compact SF indicator from sfLeadId / sfOpportunityId ("L ✓" once a Lead exists, " O ✓" once converted to an Opportunity). See Salesforce sync.

dedupStatus — deduplication verdict#

Default "approved". Records whether the registered deal collides with an existing pipeline entry (deal-protection / channel-conflict).

The deal detail page#

/opportunities/[id] validates the UUID format and 404s on a malformed id, then loads the row scoped to the caller's clerkOrgId (404 if it belongs to another org).

Layout. The page is full-width and responsive (.pm-deal-* classes in styles/globals.css), not a narrow single column: a header row, a metric-tile strip, then a two-column split (main detail + sticky aside) that collapses to one column below 960px. It renders:

• Header — company name, end-customer name + email, and an inline OpportunityStatusBadge (with a glowing effect for opportunity_active / closed_won).
• Edit deal — the OpportunityEditForm, rendered only when canEdit (creator or super admin — see Editing a registered deal). Full width: collapses to a right-aligned button, expands in place to the full edit form.
• Metric tiles — Expected ARR, Deal Stage, Region, Expected Close, plus Annual Revenue and Headcount when present (a reflowing auto-fit strip).
• Main column — Deal Information (company type/size, contact phone, and when present contact title, website + LinkedIn links, the Why Now / Why Matters.AI / Why Anything answers, use-case + competing-product chips, and free-text notes) and the Activity Log (a registration event plus the chronological notes thread, followed by the add-note form).
• Aside column (sticky) — Update Stage (the StageUpdateForm, omitted once the deal is in a terminal status), Deal Progress (the status timeline), and Details (registered timestamp, and the sfLeadId / sfOpportunityId references when present).

Updating the deal stage#

The stage updater posts to updateDealStage in lib/actions/update-opportunity.ts:

1. requirePartnerSession(), then validate { opportunityId: uuid, dealStage: enum } with UpdateStageSchema.
2. Load the existing row scoped to id and clerkOrgId; return "Opportunity not found." if missing.
3. Guard: if portalStatus is closed_won, closed_lost, or cancelled, return "Cannot update stage on a closed or cancelled deal." The form also hides itself client-side for those statuses.
4. Update dealStage, and bump lastActivityAt + updatedAt (resetting the inactivity clock).
5. Fire a fire-and-forget in-app notification (sendNotification, type deal_status) linking to the deal.
6. Record an audit event opportunity.status_changed with metadata: { from, to }.
7. Revalidate the detail page, list, and dashboard.

Note: this action changes the sales stage and emits the opportunity.status_changed audit action. The portalStatus lifecycle transitions (and the deal-status email) are driven by internal/admin pipeline operations and the inactivity sweep, not by this partner-facing stage button.

Notes thread#

The add-note form posts to addOpportunityNote in lib/actions/opportunity-notes.ts:

1. requirePartnerSession(), validate { body: string(1..2000), opportunityId: uuid }.
2. Verify the opportunity exists and opp.clerkOrgId === session.clerkOrgId; otherwise _form: ["Opportunity not found or access denied."].
3. Insert into opportunity_notes (authorClerkUserId = session.clerkUserId).
4. Bump the parent opportunity's lastActivityAt + updatedAt (so notes keep a deal "alive" against the sweep).
5. Record audit event opportunity.note_added.
6. Revalidate the detail page.

Admin view#

/admin/opportunities is gated by requireAdminSession() (read tier). It is cross-org: no clerkOrgId filter. It shows:

• A header with aggregate count and pipeline ARR (SUM(expectedArrUsd), rendered in $k).
• Search across companyName, endCustomerName, and clerkOrgId; the same status filter chips; page size 30.
• A per-row partner-org name resolved from partnerProfiles (joined in a second query keyed by clerkOrgId), plus the compact SF link indicator.

See RBAC for the admin session tiers.

Inactivity sweep (lead lifecycle)#

The cron route /api/cron/lead-lifecycle-sweep (GET) enforces a 90-day deal-protection window. It is authorised by a constant-time Bearer comparison against CRON_SECRET (timingSafeEqual); a missing or mismatched token returns 401.

On each run (now):

1. Cancel (90 days): every row whose lastActivityAt < now − 90d and cancelledAt IS NULL is set to portalStatus = "cancelled", cancelledAt = now.
2. Warn (83 days): every row whose lastActivityAt < now − 83d, inactivityWarningAt IS NULL, and cancelledAt IS NULL gets inactivityWarningAt = now (a one-time warning marker, ~7 days before cancellation).

It responds with { cancelled, warned } counts. lastActivityAt is reset to now whenever a partner updates the stage or adds a note, so any genuine activity restarts the 90-day clock. The schema carries an extensionGrantedAt column reserved for a manual deadline extension.

Email notifications#

Rendered with @react-email/components and sent via Resend from lib/email.ts.

DealRegisteredEmail summarises company / stage / expected ARR, a "View in Portal" button to ${APP_URL}/opportunities, and the portalLeadId as a reference id. DealStatusEmail shows the old → new status (mapped through the same label table as the UI). The registration email is dispatched fire-and-forget from registerOpportunity; failures never block the write path.

CSV export#

Both serialise cells through escapeCsvCell (CSV-injection safe), set Content-Type: text/csv, an attachment filename stamped with the date, and Cache-Control: no-store.

Tier gating: the partner export uses the partner session (own-org data). The admin export is gated by requireAdminWriteSession() — the write tier, not the read tier that backs the admin list page. Read-tier admins can browse all deals but cannot bulk-export them. See RBAC.

Audit events#

Each mutation calls recordActivity (org-scoped, with actor + target) — see the Audit Log.

Security and scoping invariants#

• Org isolation: every partner-facing read and write filters on session.clerkOrgId. The detail page and note action both re-check ownership and 404 / deny cross-org access.
• Edit boundary: updateOpportunity may be run only by the deal's creator or a Matters.AI super admin — enforced in the action itself, not just in the UI.
• UUID validation: the detail route rejects malformed ids before touching the DB.
• Terminal-state guard: updateDealStage refuses changes once portalStatus is closed_won / closed_lost / cancelled.
• Non-blocking side effects: the registration email and the Salesforce push are best-effort; failures leave a clean Neon row and never fail the user-facing action.
• Cron auth: the lifecycle sweep requires a constant-time-matched CRON_SECRET Bearer token.

Related#

• Data Model — full opportunities / opportunity_notes schema
• RBAC — partner vs admin (read/write) session tiers
• Audit Log — recordActivity and the event catalog
• Salesforce sync — Lead/Opportunity mapping, sfStatus, retries